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
2021-10-25 12:30:57 -05:00
parent fabb762f75
commit 6e647c6f26
59 changed files with 2440 additions and 0 deletions
--- a/i2c/oled_i2c/CMakeLists.txt
+++ b/i2c/oled_i2c/CMakeLists.txt
@@ -0,0 +1,12 @@
+add_executable(oled_i2c
+        oled_i2c.c
+        )
+
+# pull in common dependencies and additional i2c hardware support
+target_link_libraries(oled_i2c pico_stdlib hardware_i2c)
+
+# create map/bin/hex file etc.
+pico_add_extra_outputs(oled_i2c)
+
+# add url via pico_set_program_url
+example_auto_set_url(oled_i2c)
--- a/i2c/oled_i2c/README.adoc
+++ b/i2c/oled_i2c/README.adoc
@@ -0,0 +1,76 @@
+= Attaching an OLED display via I2C
+
+This example code shows how to interface the Raspberry Pi Pico with an 128x32 OLED display board based on the SSD1306 display driver, datasheet https://cdn-shop.adafruit.com/datasheets/SSD1306.pdf[here].
+
+The code displays a series of tiny raspberries that scroll horizontally, in the process showing you how to initialize the display, write to the entire display, write to only a portion of the display, and configure scrolling.
+
+The SSD1306 is operated via a list of versatile commands (see datasheet) that allows the user to access all the capabilities of the driver. After sending a slave address, the data that follows can be either a command, flags to follow up a command or data to be written directly into the display's RAM. A control byte is required for each write after the slave address so that the driver knows what type of data is being sent.
+
+This display is 32 pixels high by 128 pixels wide. These 32 vertical pixels are partitioned into 4 pages, each 8 pixels in height. In RAM, this looks roughly like:
+
+[NOTE]
+======
+The SSD1306 can drive displays that are up to 64 pixels high and 128 pixels wide.
+======
+
+----
+           | COL0 | COL1 | COL2 | COL3 |  ...  | COL126 | COL127 |
+    PAGE 0 |      |      |      |      |       |        |        |
+    PAGE 1 |      |      |      |      |       |        |        |
+    PAGE 2 |      |      |      |      |       |        |        |
+    PAGE 3 |      |      |      |      |       |        |        |
+    --------------------------------------------------------------
+----
+
+Within each page, we have:
+
+----
+          | COL0 | COL1 | COL2 | COL3 |  ...  | COL126 | COL127 |
+    COM 0 |      |      |      |      |       |        |        |   
+    COM 1 |      |      |      |      |       |        |        |   
+       :  |      |      |      |      |       |        |        |  
+    COM 7 |      |      |      |      |       |        |        |
+    -------------------------------------------------------------
+----
+
+[NOTE]
+======
+There is a difference between columns in RAM and the actual segment pads that connect the driver to the display. The RAM addresses COL0 - COL127 are mapped to these segment pins SEG0 - SEG127 by default. The distinction between these two is important as we can for example,  easily mirror contents of RAM without rewriting a buffer.
+======
+
+The driver has 3 modes of transferring the pixels in RAM to the display (provided that the driver is set to use its RAM content to drive the display, ie. command 0xA4 is sent). We choose horizontal addressing mode which, after setting the column address and page address registers to our desired start positions, will increment the column address register until the OLED display width is reached (127 in our case) after which the column address register will reset to its starting value and the page address is incremented. Once the page register reaches the end, it will wrap around as well. Effectively, this scans across the display from top to bottom, left to right in blocks that are 8 pixels high. When a byte is sent to be written into RAM, it sets all the rows for the current position of the column address register. So, if we send 10101010, and we are on PAGE 0 and COL1, COM0 is set to 1, COM1 is set to 0, COM2 is set to 1, and so on. Effectively, the byte is "transposed" to fill a single page's column. The datasheet has further information on this and the two other modes.
+
+Horizontal addressing mode has the key advantage that we can keep one single 512 byte buffer (128 columns x 4 pages and each byte fills a page's rows) and write this in one go to the RAM (column address auto increments on writes as well as reads) instead of working with 2D matrices of pixels and adding more overhead. 
+
+[NOTE]
+======
+* The SSD1306 is able to drive 128x64 displays but as our display is 128x32, only half of the COM (common) pins are connected to the display.
+* The specific display model being used is UG-2832HSWEG02
+======
+
+== Wiring information
+
+Wiring up the device requires 4 jumpers, to connect VCC (3.3v), GND, SDA and SCL and optionally a 5th jumper for the driver RESET pin. 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.
+
+[[oled_i2c_wiring]]
+[pdfwidth=75%]
+.Wiring Diagram for oled display via I2C.
+image::oled_i2c_bb.png[]
+
+== List of Files
+
+CMakeLists.txt:: CMake file to incorporate the example into the examples build tree.
+oled_i2c.c:: The example code.
+
+== Bill of Materials
+
+.A list of materials required for the example
+[[oled_i2c-bom-table]]
+[cols=3]
+|===
+| *Item* | *Quantity* | Details
+| Breadboard | 1 | generic part
+| Raspberry Pi Pico | 1 | https://www.raspberrypi.com/products/raspberry-pi-pico/
+| SSD1306-based OLED display | 1 | https://www.adafruit.com/product/4440[Adafruit part]
+| M/M Jumper wires | 4 | generic part
+|===
--- a/i2c/oled_i2c/img_to_array.py
+++ b/i2c/oled_i2c/img_to_array.py
@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+
+# Converts a grayscale image into a format able to be
+# displayed by the SSD1306 driver in horizontal addressing mode
+
+# usage: python3 img_to_array.py <logo.bmp>
+
+# depends on the Pillow library
+# `python3 -m pip install --upgrade Pillow`
+
+from PIL import Image
+import sys
+from pathlib import Path
+
+OLED_HEIGHT = 32
+OLED_WIDTH = 128
+OLED_PAGE_HEIGHT = 8
+
+if len(sys.argv) < 2:
+    print("No image path provided.")
+    sys.exit()
+
+img_path = sys.argv[1]
+
+try:
+    im = Image.open(img_path)
+except OSError:
+    raise Exception("Oops! The image could not be opened.")
+
+img_width = im.size[0]
+img_height = im.size[1]
+
+if img_width > OLED_WIDTH or img_height > OLED_HEIGHT:
+    print(f'Your image is f{img_width} pixels wide and {img_height} pixels high, but...')
+    raise Exception(f"OLED display only {OLED_WIDTH} pixels wide and {OLED_HEIGHT} pixels high!")
+
+if not (im.mode == "1" or im.mode == "L"):
+    raise Exception("Image must be grayscale only")
+
+# black or white
+out = im.convert("1")
+
+img_name = Path(im.filename).stem
+
+# `pixels` is a flattened array with the top left pixel at index 0
+# and bottom right pixel at the width*height-1
+pixels = list(out.getdata())
+
+# swap white for black and swap (255, 0) for (1, 0)
+pixels = [0 if x == 255 else 1 for x in pixels]
+
+# our goal is to divide the image into 8-pixel high pages
+# and turn a pixel column into one byte, eg for one page:
+# 0 1 0 ....
+# 1 0 0
+# 1 1 1
+# 0 0 1
+# 1 1 0
+# 0 1 0
+# 1 1 1
+# 0 0 1 ....
+
+# we get 0x6A, 0xAE, 0x33 ... and so on
+# as `pixels` is flattened, each bit in a column is IMG_WIDTH apart from the next
+
+buffer = []
+for i in range(img_height // OLED_PAGE_HEIGHT):
+    start_index = i*img_width*OLED_PAGE_HEIGHT
+    for j in range(img_width):
+        out_byte = 0
+        for k in range(OLED_PAGE_HEIGHT):
+            out_byte |= pixels[k*img_width + start_index + j] << k
+        buffer.append(f'{out_byte:#04x}')
+
+buffer = ", ".join(buffer)
+buffer_hex = f'static uint8_t {img_name}[] = {{{buffer}}}\n'
+
+with open(f'{img_name}.h', 'wt') as file:
+    file.write(f'#define IMG_WIDTH {img_width}\n')
+    file.write(f'#define IMG_HEIGHT {img_height}\n\n')
+    file.write(buffer_hex)
--- a/i2c/oled_i2c/oled_i2c.c
+++ b/i2c/oled_i2c/oled_i2c.c
@@ -0,0 +1,298 @@
+/**
+ * Copyright (c) 2021 Raspberry Pi (Trading) Ltd.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include <stdio.h>
+#include <string.h>
+#include <stdlib.h>
+#include "pico/stdlib.h"
+#include "pico/binary_info.h"
+#include "hardware/i2c.h"
+#include "raspberry26x32.h"
+
+/* Example code to talk to an SSD1306-based OLED display
+
+   NOTE: Ensure the device is capable of being driven at 3.3v NOT 5v. The Pico
+   GPIO (and therefore I2C) cannot be used at 5v.
+
+   You will need to use a level shifter on the I2C lines if you want to run the
+   board at 5v.
+
+   Connections on Raspberry Pi Pico board, other boards may vary.
+
+   GPIO PICO_DEFAULT_I2C_SDA_PIN (on Pico this is GP4 (pin 6)) -> SDA on display
+   board
+   GPIO PICO_DEFAULT_I2C_SCK_PIN (on Pico this is GP5 (pin 7)) -> SCL on
+   display board
+   3.3v (pin 36) -> VCC on display board
+   GND (pin 38)  -> GND on display board
+*/
+
+// commands (see datasheet)
+#define OLED_SET_CONTRAST _u(0x81)
+#define OLED_SET_ENTIRE_ON _u(0xA4)
+#define OLED_SET_NORM_INV _u(0xA6)
+#define OLED_SET_DISP _u(0xAE)
+#define OLED_SET_MEM_ADDR _u(0x20)
+#define OLED_SET_COL_ADDR _u(0x21)
+#define OLED_SET_PAGE_ADDR _u(0x22)
+#define OLED_SET_DISP_START_LINE _u(0x40)
+#define OLED_SET_SEG_REMAP _u(0xA0)
+#define OLED_SET_MUX_RATIO _u(0xA8)
+#define OLED_SET_COM_OUT_DIR _u(0xC0)
+#define OLED_SET_DISP_OFFSET _u(0xD3)
+#define OLED_SET_COM_PIN_CFG _u(0xDA)
+#define OLED_SET_DISP_CLK_DIV _u(0xD5)
+#define OLED_SET_PRECHARGE _u(0xD9)
+#define OLED_SET_VCOM_DESEL _u(0xDB)
+#define OLED_SET_CHARGE_PUMP _u(0x8D)
+#define OLED_SET_HORIZ_SCROLL _u(0x26)
+#define OLED_SET_SCROLL _u(0x2E)
+
+#define OLED_ADDR _u(0x3C)
+#define OLED_HEIGHT _u(32)
+#define OLED_WIDTH _u(128)
+#define OLED_PAGE_HEIGHT _u(8)
+#define OLED_NUM_PAGES OLED_HEIGHT / OLED_PAGE_HEIGHT
+#define OLED_BUF_LEN (OLED_NUM_PAGES * OLED_WIDTH)
+
+#define OLED_WRITE_MODE _u(0xFE)
+#define OLED_READ_MODE _u(0xFF)
+
+struct render_area {
+    uint8_t start_col;
+    uint8_t end_col;
+    uint8_t start_page;
+    uint8_t end_page;
+
+    int buflen;
+};
+
+void fill(uint8_t buf[], uint8_t fill) {
+    // fill entire buffer with the same byte
+    for (int i = 0; i < OLED_BUF_LEN; i++) {
+        buf[i] = fill;
+    }
+};
+
+void fill_page(uint8_t *buf, uint8_t fill, uint8_t page) {
+    // fill entire page with the same byte
+    memset(buf + (page * OLED_WIDTH), fill, OLED_WIDTH);
+};
+
+// convenience methods for printing out a buffer to be rendered
+// mostly useful for debugging images, patterns, etc
+
+void print_buf_page(uint8_t buf[], uint8_t page) {
+    // prints one page of a full length (128x4) buffer
+    for (int j = 0; j < OLED_PAGE_HEIGHT; j++) {
+        for (int k = 0; k < OLED_WIDTH; k++) {
+            printf("%u", (buf[page * OLED_WIDTH + k] >> j) & 0x01);
+        }
+        printf("\n");
+    }
+}
+
+void print_buf_pages(uint8_t buf[]) {
+    // prints all pages of a full length buffer
+    for (int i = 0; i < OLED_NUM_PAGES; i++) {
+        printf("--page %d--\n", i);
+        print_buf_page(buf, i);
+    }
+}
+
+void print_buf_area(uint8_t *buf, struct render_area *area) {
+    // print a render area of generic size
+    int area_width = area->end_col - area->start_col + 1;
+    int area_height = area->end_page - area->start_page + 1; // in pages, not pixels
+    for (int i = 0; i < area_height; i++) {
+        for (int j = 0; j < OLED_PAGE_HEIGHT; j++) {
+            for (int k = 0; k < area_width; k++) {
+                printf("%u", (buf[i * area_width + k] >> j) & 0x01);
+            }
+            printf("\n");
+        }
+    }
+}
+
+void calc_render_area_buflen(struct render_area *area) {
+    // calculate how long the flattened buffer will be for a render area
+    area->buflen = (area->end_col - area->start_col + 1) * (area->end_page - area->start_page + 1);
+}
+
+#ifdef i2c_default
+
+void oled_send_cmd(uint8_t cmd) {
+    // I2C write process expects a control byte followed by data
+    // this "data" can be a command or data to follow up a command
+
+    // Co = 1, D/C = 0 => the driver expects a command
+    uint8_t buf[2] = {0x80, cmd};
+    i2c_write_blocking(i2c_default, (OLED_ADDR & OLED_WRITE_MODE), buf, 2, false);
+}
+
+void oled_send_buf(uint8_t buf[], int buflen) {
+    // in horizontal addressing mode, the column address pointer auto-increments
+    // and then wraps around to the next page, so we can send the entire frame
+    // buffer in one gooooooo!
+
+    // copy our frame buffer into a new buffer because we need to add the control byte
+    // to the beginning
+
+    // TODO find a more memory-efficient way to do this..
+    // maybe break the data transfer into pages?
+    uint8_t *temp_buf = malloc(buflen + 1);
+
+    for (int i = 1; i < buflen + 1; i++) {
+        temp_buf[i] = buf[i - 1];
+    }
+    // Co = 0, D/C = 1 => the driver expects data to be written to RAM
+    temp_buf[0] = 0x40;
+    i2c_write_blocking(i2c_default, (OLED_ADDR & OLED_WRITE_MODE), temp_buf, buflen + 1, false);
+
+    free(temp_buf);
+}
+
+void oled_init() {
+    // some of these commands are not strictly necessary as the reset
+    // process defaults to some of these but they are shown here
+    // to demonstrate what the initialization sequence looks like
+
+    // some configuration values are recommended by the board manufacturer
+
+    oled_send_cmd(OLED_SET_DISP | 0x00); // set display off
+
+    /* memory mapping */
+    oled_send_cmd(OLED_SET_MEM_ADDR); // set memory address mode
+    oled_send_cmd(0x00); // horizontal addressing mode
+
+    /* resolution and layout */
+    oled_send_cmd(OLED_SET_DISP_START_LINE); // set display start line to 0
+
+    oled_send_cmd(OLED_SET_SEG_REMAP | 0x01); // set segment re-map
+    // column address 127 is mapped to SEG0
+
+    oled_send_cmd(OLED_SET_MUX_RATIO); // set multiplex ratio
+    oled_send_cmd(OLED_HEIGHT - 1); // our display is only 32 pixels high
+
+    oled_send_cmd(OLED_SET_COM_OUT_DIR | 0x08); // set COM (common) output scan direction
+    // scan from bottom up, COM[N-1] to COM0
+
+    oled_send_cmd(OLED_SET_DISP_OFFSET); // set display offset
+    oled_send_cmd(0x00); // no offset
+
+    oled_send_cmd(OLED_SET_COM_PIN_CFG); // set COM (common) pins hardware configuration
+    oled_send_cmd(0x02); // manufacturer magic number
+
+    /* timing and driving scheme */
+    oled_send_cmd(OLED_SET_DISP_CLK_DIV); // set display clock divide ratio
+    oled_send_cmd(0x80); // div ratio of 1, standard freq
+
+    oled_send_cmd(OLED_SET_PRECHARGE); // set pre-charge period
+    oled_send_cmd(0xF1); // Vcc internally generated on our board
+
+    oled_send_cmd(OLED_SET_VCOM_DESEL); // set VCOMH deselect level
+    oled_send_cmd(0x30); // 0.83xVcc
+
+    /* display */
+    oled_send_cmd(OLED_SET_CONTRAST); // set contrast control
+    oled_send_cmd(0xFF);
+
+    oled_send_cmd(OLED_SET_ENTIRE_ON); // set entire display on to follow RAM content
+
+    oled_send_cmd(OLED_SET_NORM_INV); // set normal (not inverted) display
+
+    oled_send_cmd(OLED_SET_CHARGE_PUMP); // set charge pump
+    oled_send_cmd(0x14); // Vcc internally generated on our board
+
+    oled_send_cmd(OLED_SET_SCROLL | 0x00); // deactivate horizontal scrolling if set
+    // this is necessary as memory writes will corrupt if scrolling was enabled
+
+    oled_send_cmd(OLED_SET_DISP | 0x01); // turn display on
+}
+
+void render(uint8_t *buf, struct render_area *area) {
+    // update a portion of the display with a render area
+    oled_send_cmd(OLED_SET_COL_ADDR);
+    oled_send_cmd(area->start_col);
+    oled_send_cmd(area->end_col);
+
+    oled_send_cmd(OLED_SET_PAGE_ADDR);
+    oled_send_cmd(area->start_page);
+    oled_send_cmd(area->end_page);
+
+    oled_send_buf(buf, area->buflen);
+}
+
+#endif
+
+int main() {
+    stdio_init_all();
+
+    // useful information for picotool
+    bi_decl(bi_2pins_with_func(PICO_DEFAULT_I2C_SDA_PIN, PICO_DEFAULT_I2C_SCL_PIN, GPIO_FUNC_I2C));
+    bi_decl(bi_program_description("OLED I2C example for the Raspberry Pi Pico"));
+
+#if !defined(i2c_default) || !defined(PICO_DEFAULT_I2C_SDA_PIN) || !defined(PICO_DEFAULT_I2C_SCL_PIN)
+#warning i2c / oled_i2d example requires a board with I2C pins
+    puts("Default I2C pins were not defined");
+#else
+    printf("Hello, OLED display! Look at my raspberries..\n");
+
+    // I2C is "open drain", pull ups to keep signal high when no data is being
+    // sent
+    i2c_init(i2c_default, 400 * 1000);
+    gpio_set_function(PICO_DEFAULT_I2C_SDA_PIN, GPIO_FUNC_I2C);
+    gpio_set_function(PICO_DEFAULT_I2C_SCL_PIN, GPIO_FUNC_I2C);
+    gpio_pull_up(PICO_DEFAULT_I2C_SDA_PIN);
+    gpio_pull_up(PICO_DEFAULT_I2C_SCL_PIN);
+
+    // run through the complete initialization process
+    oled_init();
+
+    // initialize render area for entire frame (128 pixels by 4 pages)
+    struct render_area frame_area = {start_col: 0, end_col : OLED_WIDTH - 1, start_page : 0, end_page : OLED_NUM_PAGES -
+                                                                                                        1};
+    calc_render_area_buflen(&frame_area);
+
+    // zero the entire display
+    uint8_t buf[OLED_BUF_LEN];
+    fill(buf, 0x00);
+    render(buf, &frame_area);
+
+    // intro sequence: flash the screen 3 times
+    for (int i = 0; i < 3; i++) {
+        oled_send_cmd(0xA5); // ignore RAM, all pixels on
+        sleep_ms(500);
+        oled_send_cmd(0xA4); // go back to following RAM
+        sleep_ms(500);
+    }
+
+    // render 3 cute little raspberries
+    struct render_area area = {start_col: 0, end_col : IMG_WIDTH - 1, start_page : 0, end_page : OLED_NUM_PAGES - 1};
+    calc_render_area_buflen(&area);
+    render(raspberry26x32, &area);
+    for (int i = 1; i < 3; i++) {
+        uint8_t offset = 5 + IMG_WIDTH; // 5px padding
+        area.start_col += offset;
+        area.end_col += offset;
+        render(raspberry26x32, &area);
+    }
+
+    // configure horizontal scrolling
+    oled_send_cmd(OLED_SET_HORIZ_SCROLL | 0x00);
+    oled_send_cmd(0x00); // dummy byte
+    oled_send_cmd(0x00); // start page 0
+    oled_send_cmd(0x00); // time interval
+    oled_send_cmd(0x03); // end page 3
+    oled_send_cmd(0x00); // dummy byte
+    oled_send_cmd(0xFF); // dummy byte
+
+    // let's goooo!
+    oled_send_cmd(OLED_SET_SCROLL | 0x01);
+
+#endif
+    return 0;
+}
--- a/i2c/oled_i2c/oled_i2c.fzz
+++ b/i2c/oled_i2c/oled_i2c.fzz
--- a/i2c/oled_i2c/oled_i2c_bb.png
+++ b/i2c/oled_i2c/oled_i2c_bb.png
--- a/i2c/oled_i2c/raspberry26x32.bmp
+++ b/i2c/oled_i2c/raspberry26x32.bmp
--- a/i2c/oled_i2c/raspberry26x32.h
+++ b/i2c/oled_i2c/raspberry26x32.h
@@ -0,0 +1,4 @@
+#define IMG_WIDTH 26
+#define IMG_HEIGHT 32
+
+static uint8_t raspberry26x32[] = { 0x0, 0x0, 0xe, 0x7e, 0xfe, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfe, 0xfe, 0xfc, 0xf8, 0xfc, 0xfe, 0xfe, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfe, 0x7e, 0x1e, 0x0, 0x0, 0x0, 0x80, 0xe0, 0xf8, 0xfd, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfd, 0xf8, 0xe0, 0x80, 0x0, 0x0, 0x1e, 0x7f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x7f, 0x1e, 0x0, 0x0, 0x0, 0x3, 0x7, 0xf, 0x1f, 0x1f, 0x3f, 0x3f, 0x7f, 0xff, 0xff, 0xff, 0xff, 0x7f, 0x7f, 0x3f, 0x3f, 0x1f, 0x1f, 0xf, 0x7, 0x3, 0x0, 0x0};