Additional examples for specific h/w by our interns (#171)

adc/microphone_adc - Read analog values from a microphone and plot the measured sound amplitude.
i2c/bmp280_i2c - Read and convert temperature and pressure data from a BMP280 sensor, attached to an I2C bus.
i2c/lis3dh_i2c - Read acceleration and temperature value from a LIS3DH sensor via I2C
i2c/mcp9808_i2c - Read temperature, set limits and raise alerts when limits are surpassed.
i2c/mma8451_i2c - Read acceleration from a MMA8451 accelerometer and set range and precision for the data.
i2c/mpl3115a2_i2c - Interface with an MPL3115A2 altimeter, exploring interrupts and advanced board features, via I2C.
i2c/oled_i2c - Convert and display a bitmap on a 128x32 SSD1306-driven OLED display
i2c/pa1010d_i2c - Read GPS location data, parse and display data via I2C.
i2c/pcf8523_i2c - Read time and date values from a real time clock. Set current time and alarms on it.
uart/lcd_uart - Display text and symbols on a 16x02 RGB LCD display via UART

Author: kilograham

README.md

@@ -20,6 +20,7 @@ App|Description
 [hello_adc](adc/hello_adc)|Display the voltage from an ADC input.
 [joystick_display](adc/joystick_display)|Display a Joystick X/Y input based on two ADC inputs.
 [adc_console](adc/adc_console)|An interactive shell for playing with the ADC. Includes example of free-running capture mode.
+[microphone_adc](adc/microphone_adc)|Read analog values from a microphone and plot the measured sound amplitude.
 
 ### Clocks
 
@@ -76,8 +77,16 @@ App|Description
 App|Description
 ---|---
 [bus_scan](i2c/bus_scan) | Scan the I2C bus for devices and display results.
+[bmp280_i2c](i2c/bmp280_i2c) | Read and convert temperature and pressure data from a BMP280 sensor, attached to an I2C bus.
 [lcd_1602_i2c](i2c/lcd_1602_i2c) | Display some text on a generic 16x2 character LCD display, via I2C.
+[lis3dh_i2c](i2c/lis3dh_i2c) | Read acceleration and temperature value from a LIS3DH sensor via I2C
+[mcp9808_i2c](i2c/mcp9808_i2c) | Read temperature, set limits and raise alerts when limits are surpassed.
+[mma8451_i2c](i2c/mma8451_i2c) | Read acceleration from a MMA8451 accelerometer and set range and precision for the data.
+[mpl3115a2_i2c](i2c/mpl3115a2_i2c) | Interface with an MPL3115A2 altimeter, exploring interrupts and advanced board features, via I2C.
 [mpu6050_i2c](i2c/mpu6050_i2c) | Read acceleration and angular rate values from a MPU6050 accelerometer/gyro, attached to an I2C bus.
+[oled_i2c](i2c/oled_i2c) | Convert and display a bitmap on a 128x32 SSD1306-driven OLED display
+[pa1010d_i2c](i2c/pa1010d_i2c) | Read GPS location data, parse and display data via I2C.
+[pcf8523_i2c](i2c/pcf8523_i2c) | Read time and date values from a real time clock. Set current time and alarms on it.
 
 ### Interpolator
 
@@ -172,6 +181,7 @@ App|Description
 App|Description
 ---|---
 [hello_uart](uart/hello_uart) | Print some text from one of the UART serial ports, without going through `stdio`.
+[lcd_uart](uart/lcd_uart) | Display text and symbols on a 16x02 RGB LCD display via UART
 [uart_advanced](uart/uart_advanced) | Use some other UART features like RX interrupts, hardware control flow, and data formats other than 8n1.
 
 ### USB Device

adc/CMakeLists.txt

@@ -3,4 +3,5 @@ if (NOT PICO_NO_HARDWARE)
     add_subdirectory(dma_capture)
     add_subdirectory(hello_adc)
     add_subdirectory(joystick_display)
+    add_subdirectory(microphone_adc)
 endif ()

adc/microphone_adc/CMakeLists.txt

@@ -0,0 +1,12 @@
+add_executable(microphone_adc
+        microphone_adc.c
+        )
+
+# pull in common dependencies and adc hardware support
+target_link_libraries(microphone_adc pico_stdlib hardware_adc)
+
+# create map/bin/hex file etc.
+pico_add_extra_outputs(microphone_adc)
+
+# add url via pico_set_program_url
+example_auto_set_url(microphone_adc)

adc/microphone_adc/README.adoc

@@ -0,0 +1,48 @@
+= Attaching a microphone using the ADC
+
+This example code shows how to interface the Raspberry Pi Pico with a standard analog microphone via the onboard analog to digital converter (ADC). In this example, we use an ICS-40180 breakout board by SparkFun but any analog microphone should be compatible with this tutorial. SparkFun have https://learn.sparkfun.com/tutorials/mems-microphone-hookup-guide[written a guide] for this board that goes into more detail about the board and how it works.
+
+[TIP]
+======
+An analog to digital converter (ADC) is responsible for reading continually varying input signals that may range from 0 to a specified reference voltage (in the Pico's case this reference voltage is set by the supply voltage and can be measured on pin 35, ADC_VREF) and converting them into binary, i.e. a number that can be digitally stored.
+======
+
+The Pico has a 12-bit ADC (ENOB of 8.7-bit, see https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf[RP2040 datasheet section 4.9.3 for more details]), meaning that a read operation will return a number ranging from 0 to 4095 (2^12 - 1) for a total of 4096 possible values. Therefore, the resolution of the ADC is 3.3/4096, so roughly steps of 0.8 millivolts. The SparkFun breakout uses an OPA344 operational amplifier to boost the signal coming from the microphone to voltage levels that can be easily read by the ADC. An important side effect is that a bias of 0.5*Vcc is added to the signal, even when the microphone is not picking up any sound.
+
+The ADC provides us with a raw voltage value but when dealing with sound, we're more interested in the amplitude of the audio signal. This is defined as one half the peak-to-peak amplitude. Included with this example is a very simple Python script that will plot the voltage values it receives via the serial port. By tweaking the sampling rates, and various other parameters, the data from the microphone can be analysed in various ways, such as in a Fast Fourier Transform to see what frequencies make up the signal.
+
+[[microphone_adc_plotter_image]]
+[pdfwidth=75%]
+.Example output from included Python script
+image::microphone_adc_plotter.png[]
+
+== Wiring information
+
+Wiring up the device requires 3 jumpers, to connect VCC (3.3v), GND, and AOUT. The example here uses ADC0, which is GP26. Power is supplied from the 3.3V pin.
+
+WARNING: Most boards will take a range of VCC voltages from the Pico's default 3.3V to the 5 volts commonly seen on other microcontrollers. Ensure your board doesn't output an analogue signal greater than 3.3V as this may result in permanent damage to the Pico's ADC.
+
+[[ics-40180-adc_wiring]]
+[pdfwidth=75%]
+.Wiring Diagram for ICS-40180 microphone breakout board.
+image::microphone_adc_bb.png[]
+
+== List of Files
+
+CMakeLists.txt:: CMake file to incorporate the example in to the examples build tree.
+microphone_adc.c:: The example code.
+
+== Bill of Materials
+
+.A list of materials required for the example
+[[ics-40180-adc-bom-table]]
+[cols=3]
+|===
+| *Item* | *Quantity* | Details
+| Breadboard | 1 | generic part
+| Raspberry Pi Pico | 1 | https://www.raspberrypi.com/products/raspberry-pi-pico/
+| ICS-40180 microphone breakout board or similar | 1 | https://www.sparkfun.com/products/18011[From SparkFun]
+| M/M Jumper wires | 3 | generic part
+|===
+
+

adc/microphone_adc/microphone_adc.c

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2021 Raspberry Pi (Trading) Ltd.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include <stdio.h>
+#include "pico/stdlib.h"
+#include "hardware/gpio.h"
+#include "hardware/adc.h"
+#include "hardware/uart.h"
+#include "pico/binary_info.h"
+
+/* Example code to extract analog values from a microphone using the ADC
+   with accompanying Python file to plot these values
+
+   Connections on Raspberry Pi Pico board, other boards may vary.
+
+   GPIO 26/ADC0 (pin 31)-> AOUT or AUD on microphone board
+   3.3v (pin 36) -> VCC on microphone board
+   GND (pin 38)  -> GND on microphone board
+*/
+
+#define ADC_NUM 0
+#define ADC_PIN (26 + ADC_NUM)
+#define ADC_VREF 3.3
+#define ADC_RANGE (1 << 12)
+#define ADC_CONVERT (ADC_VREF / (ADC_RANGE - 1))
+
+int main() {
+    stdio_init_all();
+    printf("Beep boop, listening...\n");
+
+    bi_decl(bi_program_description("Analog microphone example for Raspberry Pi Pico")); // for picotool
+    bi_decl(bi_1pin_with_name(ADC_PIN, "ADC input pin"));
+
+    adc_init();
+    adc_gpio_init( ADC_PIN);
+    adc_select_input( ADC_NUM);
+
+    uint adc_raw;
+    while (1) {
+        adc_raw = adc_read(); // raw voltage from ADC
+        printf("%.2f\n", adc_raw * ADC_CONVERT);
+        sleep_ms(10);
+    }
+
+    return 0;
+}

adc/microphone_adc/microphone_adc.fzz

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+
+# Grabs raw data from the Pico's UART and plots it as received
+
+# Install dependencies:
+# python3 -m pip install pyserial matplotlib
+
+# Usage: python3 plotter <port>
+# eg. python3 plotter /dev/ttyACM0
+
+# see matplotlib animation API for more: https://matplotlib.org/stable/api/animation_api.html
+
+import serial
+import sys
+import matplotlib.pyplot as plt
+import matplotlib.animation as animation
+from matplotlib.lines import Line2D
+
+# disable toolbar
+plt.rcParams['toolbar'] = 'None'
+
+class Plotter:
+    def __init__(self, ax):
+        self.ax = ax
+        self.maxt = 250
+        self.tdata = [0]
+        self.ydata = [3.3/2]
+        self.line = Line2D(self.tdata, self.ydata)
+
+        self.ax.add_line(self.line)
+        self.ax.set_ylim(0, 3.3)
+        self.ax.set_xlim(0, self.maxt)
+
+    def update(self, y):
+        lastt = self.tdata[-1]
+        if lastt - self.tdata[0] >= self.maxt:  # drop old frames
+            self.tdata = self.tdata[1:]
+            self.ydata = self.ydata[1:]
+            self.ax.set_xlim(self.tdata[0], self.tdata[0] + self.maxt)
+
+        t = lastt + 1
+        self.tdata.append(t)
+        self.ydata.append(y)
+        self.line.set_data(self.tdata, self.ydata)
+        return self.line,
+
+
+def serial_getter():
+    # grab fresh ADC values
+    # note sometimes UART drops chars so we try a max of 5 times
+    # to get proper data
+    while True:
+        for i in range(5):
+            line = ser.readline()
+            try:
+                line = float(line)
+            except ValueError:
+                continue
+            break
+        yield line
+
+if len(sys.argv) < 2:
+    raise Exception("Ruh roh..no port specified!")
+
+ser = serial.Serial(sys.argv[1], 115200, timeout=1)
+
+fig, ax = plt.subplots()
+plotter = Plotter(ax)
+
+ani = animation.FuncAnimation(fig, plotter.update, serial_getter, interval=1,
+                              blit=True, cache_frame_data=False)
+
+ax.set_xlabel("Samples")
+ax.set_ylabel("Voltage (V)")
+fig.canvas.manager.set_window_title('Microphone ADC example')
+fig.tight_layout()
+plt.show()

adc/microphone_adc/microphone_adc_bb.png

@@ -1,5 +1,13 @@
 if (NOT PICO_NO_HARDWARE)
+    add_subdirectory(bmp280_i2c)
     add_subdirectory(bus_scan)
     add_subdirectory(lcd_1602_i2c)
+    add_subdirectory(lis3dh_i2c)
+    add_subdirectory(mcp9808_i2c)
+    add_subdirectory(mma8451_i2c)
+    add_subdirectory(mpl3115a2_i2c)
     add_subdirectory(mpu6050_i2c)
+    add_subdirectory(oled_i2c)
+    add_subdirectory(pa1010d_i2c)
+    add_subdirectory(pcf8523_i2c)
 endif ()

adc/microphone_adc/microphone_adc_plotter.png

@@ -0,0 +1,12 @@
+add_executable(bmp280_i2c
+        bmp280_i2c.c
+        )
+
+# pull in common dependencies and additional i2c hardware support
+target_link_libraries(bmp280_i2c pico_stdlib hardware_i2c)
+
+# create map/bin/hex file etc.
+pico_add_extra_outputs(bmp280_i2c)
+
+# add url via pico_set_program_url
+example_auto_set_url(bmp280_i2c)

adc/microphone_adc/plotter.py

@@ -0,0 +1,41 @@
+= Attaching a BMP280 temp/pressure sensor via I2C
+
+This example code shows how to interface the Raspberry Pi Pico with the popular BMP280 temperature and air pressure sensor manufactured by Bosch. A similar variant, the BME280, exists that can also measure humidity. There is another example that uses the BME280 device but talks to it via SPI as opposed to I2C.
+
+The code reads data from the sensor's registers every 500 milliseconds and prints it via the onboard UART. This example operates the BMP280 in _normal_ mode, meaning that the device continuously cycles between a measurement period and a standby period at a regular interval we can set. This has the advantage that subsequent reads do not require configuration register writes and is the recommended mode of operation to filter out short-term disturbances.
+
+[TIP]
+======
+The BMP280 is highly configurable with 3 modes of operation, various oversampling levels, and 5 filter settings. Find the datasheet online (https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bmp280-ds001.pdf) to explore all of its capabilities beyond the simple example given here.
+======
+
+== Wiring information
+
+Wiring up the device requires 4 jumpers, to connect VCC (3.3v), GND, SDA and SCL. The example here uses the default I2C port 0, which is assigned to GPIO 4 (SDA) and 5 (SCL) in software. Power is supplied from the 3.3V pin from the Pico.
+
+WARNING: The BMP280 has a maximum supply voltage rating of 3.6V. Most breakout boards have voltage regulators that will allow a range of input voltages of 2-6V, but make sure to check beforehand.
+
+[[bmp280_i2c_wiring]]
+[pdfwidth=75%]
+.Wiring Diagram for BMP280 sensor via I2C.
+image::bmp280_i2c_bb.png[]
+
+== List of Files
+
+CMakeLists.txt:: CMake file to incorporate the example into the examples build tree.
+bmp280_i2c.c:: The example code.
+
+== Bill of Materials
+
+.A list of materials required for the example
+[[bmp280_i2c-bom-table]]
+[cols=3]
+|===
+| *Item* | *Quantity* | Details
+| Breadboard | 1 | generic part
+| Raspberry Pi Pico | 1 | https://www.raspberrypi.com/products/raspberry-pi-pico/
+| BMP280-based breakout board | 1 | https://shop.pimoroni.com/products/bmp280-breakout-temperature-pressure-altitude-sensor[from Pimoroni]
+| M/M Jumper wires | 4 | generic part
+|===
+
+