finalise example

Martin Crossley · Martin Crossley · commit 4ab66a210bfc · 2026-01-04T20:35:38.000Z
diff --git a/README.md b/README.md
@@ -368,6 +368,7 @@ App|Description
 [spi_dma](spi/spi_dma) | Use DMA to transfer data both to and from the SPI simultaneously. The SPI is configured for loopback.
 [spi_flash](spi/spi_flash) | Erase, program and read a serial flash device attached to one of the SPI controllers.
 [spi_master_slave](spi/spi_master_slave) | Demonstrate SPI communication as master and slave.
+[ssd1309_stdout_spi](spi/ssd1309_stdout_spi/) | Display text from stdout and simple graphics on an SSD1309-based OLED panel via SPI.
 [max7219_8x7seg_spi](spi/max7219_8x7seg_spi) | Attaching a Max7219 driving an 8 digit 7 segment display via SPI.
 [max7219_32x8_spi](spi/max7219_32x8_spi) | Attaching a Max7219 driving an 32x8 LED display via SPI.
 
diff --git a/spi/CMakeLists.txt b/spi/CMakeLists.txt
@@ -4,7 +4,7 @@ if (TARGET hardware_spi)
     add_subdirectory_exclude_platforms(spi_dma)
     add_subdirectory_exclude_platforms(spi_master_slave)
     add_subdirectory_exclude_platforms(spi_flash)
-    add_subdirectory_exclude_platforms(ssd1309_spi_dma)
+    add_subdirectory_exclude_platforms(ssd1309_stdout_spi)
     add_subdirectory_exclude_platforms(max7219_32x8_spi)
     add_subdirectory_exclude_platforms(max7219_8x7seg_spi)
 else()
diff --git a/spi/ssd1309_stdout_spi/CMakeLists.txt b/spi/ssd1309_stdout_spi/CMakeLists.txt
@@ -1,16 +1,16 @@
-add_executable(ssd1309_spi_dma
-    ssd1309_spi_dma.c
+add_executable(ssd1309_stdout_spi
+    ssd1309_stdout_spi.c
     )
 
 # pull in common dependencies and additional hardware support
-target_link_libraries(ssd1309_spi_dma
+target_link_libraries(ssd1309_stdout_spi
     pico_stdlib
     hardware_spi
     hardware_dma
     )
 
 # create map/bin/hex file etc.
-pico_add_extra_outputs(ssd1309_spi_dma)
+pico_add_extra_outputs(ssd1309_stdout_spi)
 
 # add url via pico_set_program_url
-example_auto_set_url(ssd1309_spi_dma)
+example_auto_set_url(ssd1309_stdout_spi)
diff --git a/spi/ssd1309_stdout_spi/README.adoc b/spi/ssd1309_stdout_spi/README.adoc
@@ -0,0 +1,59 @@
+= Simple graphics and stdout text on an OLED display via SPI
+
+Ths example displays text and graphics on one of the widely-available small OLED panels based on the *SSD1309* controller. It should also work with compatible devices such as the *SSD1306* (not tested).
+
+These modules typically support either I2C or SPI. For this example you will need one configured for SPI.
+
+The code renders content onto a frame buffer that is transferred to the SPI port in the background, by a DMA channel under the control of a frame timer. A simple driver is used to copy _stdout_ to the frame buffer and some basic graphics functions are provided.
+
+The interface uses one of the Pico's onboard SPI peripherals and two extra GPIO pins as shown below. Note that in SPI mode the SSD1309 is a receive-only device.
+
+For details of the commands supported by the SSD1309 controller and its addressing modes see the manufacturer's datasheet: https://www.hpinfotech.ro/SSD1309.pdf.
+
+
+== Wiring information
+
+Wiring up the device requires seven jumpers as follows:
+
+    * Display CS (chip select) -> Pico GP17 (SPI0 CSn), pin 22
+    * Display DC (data/command) -> Pico GP20, pin 26
+    * Display RES (reset) -> Pico GP21, pin 27
+    * Display SDA (MOSI) -> Pico GP19 (SPI0 TX), pin 25
+    * Display SCLK (SPI clock) -> Pico GP18 (SPI0 SCK), pin 24
+    * Display VDD (3.3v) -> Pico 3V3_OUT, pin 36
+    * Display VSS (0v, gnd) -> Pico GND, pin 23
+
+The example uses SPI device 0 and powers the display from the Pico 3.3v output. If you power the display from an external supply then ensure that the Pico's logic pins are not exposed to any voltage higher than 3.3v.
+
+[NOTE]
+======
+The pins on your board may be labelled slightly differently to the list above. Check the documentation for your display.
+
+You can change the code to use different pins if you like, but the ones for CSn, TX and SCK must match your SPI device: see the GPIO Function Select Table in the datasheet. 
+======
+
+
+[[wiring_diagram.png]]
+[pdfwidth=75%]
+.Wiring Diagram for SSD1309 with SPI interface
+image::wiring_diagram.png[]
+
+== List of Files
+
+CMakeLists.txt:: A file to configure the CMake build system for the example.
+ssd1309_stdout_spi.c:: The example code.
+font.h:: A basic 8x8 bit font table used by the example.
+
+
+== Bill of Materials
+
+.A list of materials required for the example
+[[SSD1309-bom-table]]
+[cols=3]
+|===
+| *Item* | *Quantity* | Details
+| Breadboard | 1 | generic part
+| Raspberry Pi Pico or Pico 2 | 1 | https://www.raspberrypi.com/products/raspberry-pi-pico/
+| SSD1309-based OLED display panel with SPI interface| 1 | generic part
+| M/F Jumper wires (assorted colours) | 7 | generic part
+|===
diff --git a/spi/ssd1309_stdout_spi/font.h b/spi/ssd1309_stdout_spi/font.h
@@ -2,13 +2,13 @@
  * Copyright (c) 2026 mjcross
  *
  * SPDX-License-Identifier: BSD-3-Clause
- */
+**/
 
 // Vertical bitmaps for commonly-used characters.
 
-// Each bitmap is 8 pixels wide and 8 pixels high, with the least
-// significant bit at the top. The patterns are based on bitmaps
-// originally credited to IBM.
+// Each bitmap is 8 pixels wide and 8 pixels high, with the least significant bit
+// at the top. The bitmaps were translated from one of the original IBM BIOS fonts
+// released over 45yrs ago (see https://int10h.org/oldschool-pc-fonts/)
 
 #include <stdint.h>
 
diff --git a/spi/ssd1309_stdout_spi/ssd1309_stdout_spi.c b/spi/ssd1309_stdout_spi/ssd1309_stdout_spi.c
@@ -1,37 +1,38 @@
 /**
- * Copyright (c) 2025 mjcross
+ * Copyright (c) 2026 mjcross
  *
  * SPDX-License-Identifier: BSD-3-Clause
 **/
 
-// An example showing how to drive a ssd1309-based OLED panel from a frame buffer using
-// DMA transfers over SPI. It should also work on a ssd1306 device (not tested).
+// Copy stdout and/or simple graphics to an OLED display panel based on the ssd1309 
+// (or compatible) controller, using a frame buffer transferred by DMA over an SPI interface.
 //
-// To understand the commands and addressing modes for the display refer to
-// the manufacturer's datasheet at https://www.hpinfotech.ro/SSD1309.pdf
+// For details of the display controller and its commands and addressing modes refer to the 
+// manufacturer's datasheet at https://www.hpinfotech.ro/SSD1309.pdf
 
 #include <stdio.h>
+#include <string.h>
+#include <stdlib.h>
 #include "pico/stdio/driver.h"
 #include "pico/stdlib.h"
 #include "hardware/dma.h"
 #include "hardware/spi.h"
-#include "string.h"
-
 #include "font.h"
 
-// dimensions of our OLED display panel
+// dimensions of the display panel
 #define NUM_X_PIXELS        128
 #define NUM_Y_PIXELS        64
 #define PIXELS_PER_BYTE     8
 #define TABSTOPS            4
 
 // how often we want to refresh the display from the frame buffer
-#define FRAME_PERIOD_MS     20
+#define FRAME_PERIOD_MS     20      // 50 Hz
 
-// ssd1309 accepts a maximum SPI clock rate of 10 Mbit/sec
+// clock rate for the SPI interface
+// the ssd1309 is specified up to 10 Mbit/sec
 #define DISPLAY_SPI_BITRATE 10 * 1000 * 1000
 
-// define the pins for the SPI interface
+// pins to use for the SPI interface
 // we will use the spi0 peripheral and the following GPIO pins (see the
 // GPIO function select table in the Pico datasheet).
 #define SPI_DEVICE          spi0
@@ -41,26 +42,26 @@
 #define PIN_DC              20      // data/command mode (low for command)
 #define PIN_R               21      // reset (active low)
 
-// modes for the ssd1309 data/command pin (see ssd1309 datasheet)
+// modes for the ssd1309 data/command pin (see the datasheet)
 #define DC_COMMAND_MODE     0
 #define DC_DATA_MODE        1
 
 // global variables
-uint8_t frame_buffer[NUM_X_PIXELS * NUM_Y_PIXELS / PIXELS_PER_BYTE];
+uint8_t frame_buffer[ NUM_X_PIXELS * NUM_Y_PIXELS / PIXELS_PER_BYTE ];
 int dma_ch_transfer_fb;
 volatile bool display_needs_refresh = false;
-volatile uint fb_out_index = 0;
+volatile uint fb_cursor_index = 0;
 
 
-// configure a DMA channel to transmit the frame buffer over SPI
+// configure a dma channel to send the frame buffer over SPI
 void dma_init() {
     dma_ch_transfer_fb = dma_claim_unused_channel(true);
     dma_channel_config_t c = dma_channel_get_default_config(dma_ch_transfer_fb);
     channel_config_set_transfer_data_size(&c, DMA_SIZE_8);
     channel_config_set_dreq(&c, spi_get_dreq(SPI_DEVICE, true));
     dma_channel_configure(
         dma_ch_transfer_fb,
-        &c,
+        &c,                             // the channel_config above
         &spi_get_hw(SPI_DEVICE)->dr,    // write address (doesn't increment)
         frame_buffer,                   // initial read address
         dma_encode_transfer_count(count_of(frame_buffer)),
@@ -70,7 +71,7 @@ void dma_init() {
 
 // initialise the SPI interface
 void interface_init() {
-    // configure the SPI controller for 8-bit transfers using Motorola SPI mode 0
+    // configure the SPI controller for 8-bit transfers and Motorola SPI mode 0
     spi_init(SPI_DEVICE, DISPLAY_SPI_BITRATE);
     spi_set_format(SPI_DEVICE, 8, SPI_CPOL_0, SPI_CPHA_0, SPI_MSB_FIRST);
 
@@ -98,108 +99,121 @@ void display_reset() {
     spi_write_blocking(SPI_DEVICE, cmd_list, sizeof(cmd_list));
     gpio_put(PIN_DC, DC_DATA_MODE);
 
-    // clear the frame buffer and set it to refresh
+    // clear the frame buffer and flag it to be transferred
     memset(frame_buffer, 0x00, sizeof(frame_buffer));
-    fb_out_index = 0;
+    fb_cursor_index = 0;
     display_needs_refresh = true;
 }
 
-// this will be called every frame period
-bool frame_refresh_callback(__unused struct repeating_timer *t) {
-    if (display_needs_refresh) {
-        // reset read address and start transfer
-        dma_channel_set_read_addr(dma_ch_transfer_fb, frame_buffer, true);
-        display_needs_refresh = false;
-    }
-    return true;    // repeat timer
-}
 
-// simple stdout driver for the display
+// a simple stdout driver for the display
 void fb_out_chars(const char *buf, int len) {
+    uint font_index;
     while (len) {
         char code = *buf;
-        uint font_index;
         buf += 1;
         len -= 1;
-        // scroll display if needed (using DMA would almost certainly be OTT)
-        while (fb_out_index >= sizeof(frame_buffer)) {
+        while (fb_cursor_index >= sizeof(frame_buffer)) {
+            // scroll frame buffer (on RP2350 you could use a decementing dma transfer but it's probably overkill)
             memmove(frame_buffer, frame_buffer + NUM_X_PIXELS, sizeof(frame_buffer) - NUM_X_PIXELS);
-            fb_out_index -= NUM_X_PIXELS;
+            fb_cursor_index -= NUM_X_PIXELS;
             memset(&frame_buffer[sizeof(frame_buffer) - NUM_X_PIXELS - 1], 0x00, NUM_X_PIXELS);
         }
         // handle control codes
         if (code == '\n') {
-            fb_out_index = (fb_out_index / NUM_X_PIXELS + 1) * NUM_X_PIXELS;
+            fb_cursor_index = (fb_cursor_index / NUM_X_PIXELS + 1) * NUM_X_PIXELS;
         } else if (code == '\t') {
-            fb_out_index = (fb_out_index / (TABSTOPS * FONT_BYTES_PER_CODE) + 1) * TABSTOPS * FONT_BYTES_PER_CODE;
+            fb_cursor_index = (fb_cursor_index / (TABSTOPS * FONT_BYTES_PER_CODE) + 1) * TABSTOPS * FONT_BYTES_PER_CODE;
         } else {
             // handle alphanumeric codes
             if (code < FONT_CODE_FIRST || code > FONT_CODE_LAST ) {
                 font_index = FONT_INDEX_UNDEF;
             } else {
                 font_index = FONT_BYTES_PER_CODE * (FONT_INDEX_START + code - FONT_CODE_FIRST);
             }
-            // copy bitmap from font table
-            memcpy(&frame_buffer[fb_out_index], &font[font_index], FONT_BYTES_PER_CODE);
-            fb_out_index += FONT_BYTES_PER_CODE;
+            // copy bitmap to frame buffer and advance cursor
+            memcpy(&frame_buffer[fb_cursor_index], &font[font_index], FONT_BYTES_PER_CODE);
+            fb_cursor_index += FONT_BYTES_PER_CODE;
         }
     }
     display_needs_refresh = true;
 }
 
 
-// convenience functions to set/clear pixels in the frame buffer
-void set_pixel_xy(uint x, uint y) {
+// some simple graphics funtions (for the display memory layout see the datasheet)
+void set_pixel(uint x, uint y) {
     if (x < NUM_X_PIXELS && y < NUM_Y_PIXELS) {
         frame_buffer[x + (y / 8) * NUM_X_PIXELS] |= (1 << (y % 8));
         display_needs_refresh = true;
     }
 }
 
-void clear_pixel_xy(uint x, uint y) {
+void clear_pixel(uint x, uint y) {
     if (x < NUM_X_PIXELS && y < NUM_Y_PIXELS) {
         frame_buffer[x + (y / 8) * NUM_X_PIXELS] &= ~(1 << (y % 8));
         display_needs_refresh = true;
     }
 }
 
-// set text output position in rows and columns
-// rows go from 0 (top) to NUM_Y_PIXELS / 8 - 1
-// columns go from 0 (left) to NUM_X_PIXELS / 8 - 1
+void draw_line(int x0, int y0, int x1, int y1) {
+  int dx =  abs (x1 - x0), sx = x0 < x1 ? 1 : -1;
+  int dy = -abs (y1 - y0), sy = y0 < y1 ? 1 : -1; 
+  int err = dx + dy, e2;
+  while(true) {
+    set_pixel (x0, y0);
+    if (x0 == x1 && y0 == y1) break;
+    e2 = 2 * err;
+    if (e2 >= dy) { err += dy; x0 += sx; }
+    if (e2 <= dx) { err += dx; y0 += sy; }
+  }
+  display_needs_refresh = true;
+}
+
+
+// set the text output position
+// rows go from 0 at the top to NUM_Y_PIXELS/8 - 1 and columns go from 0 on the left to NUM_X_PIXELS/8 - 1
 void set_cursor_pos(uint text_row, uint text_col) {
     if (text_row < NUM_Y_PIXELS / PIXELS_PER_BYTE && text_col < NUM_X_PIXELS / FONT_BYTES_PER_CODE) {
-        fb_out_index = text_row * NUM_X_PIXELS + text_col * FONT_BYTES_PER_CODE;
+        fb_cursor_index = text_row * NUM_X_PIXELS + text_col * FONT_BYTES_PER_CODE;
+    }
+}
+
+// the callback function for our frame-rate timer
+bool frame_refresh_callback(__unused struct repeating_timer *t) {
+    if (display_needs_refresh) {
+        dma_channel_set_read_addr(dma_ch_transfer_fb, frame_buffer, true);  // reset and trigger the dma channel
+        display_needs_refresh = false;
     }
+    return true;    // reschedule the timer
 }
 
 
 int main(){
     stdio_init_all();
 
-    // initialise the interface and display
+    // initialise everything
     dma_init();
     interface_init();
     display_reset();
 
-    // refresh the display from the frame buffer (if needed) once per frame using DMA
+    // start refreshing the display
     struct repeating_timer timer;
     add_repeating_timer_ms(FRAME_PERIOD_MS, frame_refresh_callback, NULL, &timer);
 
-    // use a simple driver to copy stdout to the frame buffer
+    // install our simple driver to copy stdout to the frame buffer
     stdio_driver_t fb_stdio_driver = { fb_out_chars };
     stdio_set_driver_enabled(&fb_stdio_driver, true);
 
-    // show some text on the screen
+    // display some text
     set_cursor_pos(0, 2);
     printf("Hello, World\n");
 
     // show a moving 'snake'
     int head_x = NUM_Y_PIXELS - 1, head_y = NUM_Y_PIXELS - 1, head_dx = 1, head_dy = 1;
     int tail_x = FONT_BYTES_PER_CODE + 1, tail_y = FONT_BYTES_PER_CODE + 1, tail_dx = 1, tail_dy = 1;
     while(true) {
-        set_pixel_xy(head_x, head_y);
-        clear_pixel_xy(tail_x, tail_y);
-        // update head position
+        set_pixel(head_x, head_y);
+        clear_pixel(tail_x, tail_y);
         if (head_x + head_dx < 0 || head_x + head_dx >= NUM_X_PIXELS) {
             head_dx = -head_dx;
         }
@@ -208,7 +222,6 @@ int main(){
             head_dy = -head_dy;
         }
         head_y += head_dy;
-        // update tail position
         if (tail_x + tail_dx < 0 || tail_x + tail_dx >= NUM_X_PIXELS) {
             tail_dx = -tail_dx;
         }
diff --git a/spi/ssd1309_stdout_spi/wiring_diagram.fzz b/spi/ssd1309_stdout_spi/wiring_diagram.fzz
diff --git a/spi/ssd1309_stdout_spi/wiring_diagram.png b/spi/ssd1309_stdout_spi/wiring_diagram.png
