Updates along with SDK1.3.0 release (#181)

Bug fixes and new examples

Co-authored-by: Paulo Marques <[email protected]>
Co-authored-by: martin <[email protected]>
Co-authored-by: matiasilva <[email protected]>
Co-authored-by: Uri Shaked <[email protected]>
Co-authored-by: Diego Solano <[email protected]>
Co-authored-by: Andrew Scheller <[email protected]>
Co-authored-by: Adrian Hesketh <[email protected]>
Co-authored-by: Emircan Gündoğdu <[email protected]>
Co-authored-by: Josef Wegner <[email protected]>
Co-authored-by: pmarques-dev <[email protected]>
Co-authored-by: Paulo Marques <[email protected]>
Co-authored-by: mjcross <[email protected]>
Co-authored-by: martin <[email protected]>

Author: 12 people

CMakeLists.txt

@@ -7,6 +7,10 @@ project(pico_examples C CXX ASM)
 set(CMAKE_C_STANDARD 11)
 set(CMAKE_CXX_STANDARD 17)
 
+if (PICO_SDK_VERSION_STRING VERSION_LESS "1.3.0")
+    message(FATAL_ERROR "Raspberry Pi Pico SDK version 1.3.0 (or later) required. Your version is ${PICO_SDK_VERSION_STRING}")
+endif()
+
 set(PICO_EXAMPLES_PATH ${PROJECT_SOURCE_DIR})
 
 # Initialize the SDK

CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing to Raspberry Pi Pico C/C++ Examples
+
+## How to Report a Bug
+
+We use GitHub to host code, track [issues](https://github.com/raspberrypi/pico-examples/issues) and feature requests, and to accept [pull requests](https://github.com/raspberrypi/pico-examples/pulls). If you find think you have found a bug, please report it by [opening a new issue](https://github.com/raspberrypi/pico-examples/issues/new). Please include as much detail as possible, and ideally some code to reproduce the problem.
+
+## How to Contribute Code
+
+In order to contribute new or updated code, you must first create a GitHub account and fork the original repository to your own account. You can make changes, save them in your repository, then [make a pull request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) against this repository. The pull request will appear [in the repository](https://github.com/raspberrypi/pico-examples/pulls) where it can be assessed by the maintainers, and if appropriate, merged with the official repository.
+
+**NOTE:** Development takes place on the `develop` branch in this repository. Please open your https://github.com/raspberrypi/pico-examples/pulls[pull request] (PR) against the [`develop`](https://github.com/raspberrypi/pico-examples/tree/develop) branch, pull requests against the `master` branch will automatically CI fail checks and will not be accepted. You will be asked to rebase your PR against `develop` and if you do not do so, your PR will be closed.
+
+### Code Style
+
+If you are contributing new or updated code please match the existing code style, particularly:
+
+* Use 4 spaces for indentation rather than tabs.
+* Braces are required for everything except single line `if` statements.
+* Opening braces should not be placed on a new line.
+
+### Licensing
+
+Code in this repository is lisensed under the [BSD-3 License](LICENSE.TXT). By contributing content to this repository you are agreeing to place your contributions under this licence.

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
 
@@ -109,13 +118,15 @@ App|Description
 [differential_manchester](pio/differential_manchester)| Send and receive differential Manchester-encoded serial (BMC).
 [hub75](pio/hub75)| Display an image on a 128x64 HUB75 RGB LED matrix.
 [i2c](pio/i2c)| Scan an I2C bus.
+[ir_nec](pio/ir_nec)| Sending and receiving IR (infra-red) codes using the PIO.
 [logic_analyser](pio/logic_analyser)| Use PIO and DMA to capture a logic trace of some GPIOs, whilst a PWM unit is driving them.
 [manchester_encoding](pio/manchester_encoding)| Send and receive Manchester-encoded serial.
 [pio_blink](pio/pio_blink)| Set up some PIO state machines to blink LEDs at different frequencies, according to delay counts pushed into their FIFOs.
 [pwm](pio/pwm)| Pulse width modulation on PIO. Use it to gradually fade the brightness of an LED.
 [spi](pio/spi)| Use PIO to erase, program and read an external SPI flash chip. A second example runs a loopback test with all four CPHA/CPOL combinations.
 [squarewave](pio/squarewave)| Drive a fast square wave onto a GPIO. This example accesses low-level PIO registers directly, instead of using the SDK functions.
 [st7789_lcd](pio/st7789_lcd)| Set up PIO for 62.5 Mbps serial output, and use this to display a spinning image on a ST7789 serial LCD.
+[quadrature_encoder](pio/quadrature_encoder)| A quadrature encoder using PIO to maintain counts independent of the CPU. 
 [uart_rx](pio/uart_rx)| Implement the receive component of a UART serial port. Attach it to the spare Arm UART to see it receive characters.
 [uart_tx](pio/uart_tx)| Implement the transmit component of a UART serial port, and print hello world.
 [ws2812](pio/ws2812)| Examples of driving WS2812 addressable RGB LEDs.
@@ -172,13 +183,14 @@ 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
 
 #### TinyUSB Examples 
 
-All but one of the USB device examples come directly from the TinyUSB device examples directory [here](https://github.com/hathach/tinyusb/tree/master/examples/device).
+Most of the USB device examples come directly from the TinyUSB device examples directory [here](https://github.com/hathach/tinyusb/tree/master/examples/device).
 Those that are supported on RP2040 devices are automatically included as part of the pico-examples
 build as targets named `tinyusb_dev_<example_name>`, e.g. https://github.com/hathach/tinyusb/tree/master/examples/device/hid_composite
 is built as `tinyusb_dev_hid_composite`.
@@ -198,11 +210,24 @@ At the time of writing, these examples are available:
 - tinyusb_dev_hid_multiple_interface
 - tinyusb_dev_midi_test
 - tinyusb_dev_msc_dual_lun
+- tinyusb_dev_net_lwip_webserver
 - tinyusb_dev_uac2_headset
 - tinyusb_dev_usbtmc
+- tinyusb_dev_video_capture
 - tinyusb_dev_webusb_serial
 
-#### Low Level examples
+Whilst these examples ably demonstrate how to use TinyUSB in device mode, their `CMakeLists.txt` is set up in a way
+tailored to how TinyUSB builds their examples within their source tree.
+
+For a better example of how to configure `CMakeLists.txt` for using TinyUSB in device mode with the Raspberry Pi SDK
+see below:
+
+#### SDK build example 
+App|Description
+---|---
+[dev_hid_composite](usb/device/dev_hid_composite) | A copy of the TinyUSB device example with the same name, but with a CMakeLists.txt which demonstrates how to add a dependency on the TinyUSB device libraries with the Raspberry Pi Pico SDK
+
+#### Low Level example
 App|Description
 ---|---
 [dev_lowlevel](usb/device/dev_lowlevel) | A USB Bulk loopback implemented with direct access to the USB hardware (no TinyUSB)

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

@@ -2,7 +2,7 @@ add_executable(blink
         blink.c
         )
 
-# Pull in our pico_stdlib which pulls in commonly used features
+# pull in common dependencies
 target_link_libraries(blink pico_stdlib)
 
 # create map/bin/hex file etc.

adc/microphone_adc/microphone_adc_plotter.png

@@ -2,11 +2,11 @@ add_executable(clocks_detached_clk_peri
         detached_clk_peri.c
         )
 
-# Pull in our pico_stdlib which pulls in commonly used features
+# pull in common dependencies
 target_link_libraries(clocks_detached_clk_peri pico_stdlib)
 
 # create map/bin/hex file etc.
 pico_add_extra_outputs(clocks_detached_clk_peri)
 
 # add url via pico_set_program_url
-example_auto_set_url(clocks_detached_clk_peri)
+example_auto_set_url(clocks_detached_clk_peri)

adc/microphone_adc/plotter.py

@@ -2,7 +2,7 @@ add_executable(hello_48MHz
         hello_48MHz.c
         )
 
-# Pull in our pico_stdlib which pulls in commonly used features
+# pull in common dependencies and additional clocks hardware support
 target_link_libraries(hello_48MHz pico_stdlib hardware_clocks)
 
 # create map/bin/hex file etc.

blink/CMakeLists.txt

@@ -2,11 +2,11 @@ add_executable(hello_gpout
         hello_gpout.c
         )
 
-# Pull in our pico_stdlib which pulls in commonly used features
+# pull in common dependencies
 target_link_libraries(hello_gpout pico_stdlib)
 
 # create map/bin/hex file etc.
 pico_add_extra_outputs(hello_gpout)
 
 # add url via pico_set_program_url
-example_auto_set_url(hello_gpout)
+example_auto_set_url(hello_gpout)

clocks/detached_clk_peri/CMakeLists.txt

@@ -2,11 +2,11 @@ add_executable(hello_resus
         hello_resus.c
         )
 
-# Pull in our pico_stdlib which pulls in commonly used features
+# pull in common dependencies
 target_link_libraries(hello_resus pico_stdlib)
 
 # create map/bin/hex file etc.
 pico_add_extra_outputs(hello_resus)
 
 # add url via pico_set_program_url
-example_auto_set_url(hello_resus)
+example_auto_set_url(hello_resus)

clocks/hello_48MHz/CMakeLists.txt

@@ -2,11 +2,11 @@ add_executable(hello_divider
         hello_divider.c
         )
 
-# Pull in our pico_stdlib which pulls in commonly used features
+# pull in common dependencies
 target_link_libraries(hello_divider pico_stdlib)
 
 # create map/bin/hex file etc.
 pico_add_extra_outputs(hello_divider)
 
 # add url via pico_set_program_url
-example_auto_set_url(hello_divider)
+example_auto_set_url(hello_divider)