pmw frame and data capture mode and visualization scripts.

firmware/include/config.h

 
 #define INVERT_MOUSE_X_AXIS false
 #define INVERT_MOUSE_Y_AXIS true
-#define DEFAULT_MOUSE_SENSITIVITY PMW_CPI_TO_SENSE(800)
+#define DEFAULT_MOUSE_SENSITIVITY PMW_CPI_TO_SENSE(500)
 
 #endif // __CONFIG_H__

firmware/include/log.h

         ##__VA_ARGS__)
 
 // for interactive output. is not stored or re-played.
-#define print(fmt, ...) debug_log(false, fmt "\r\n", ##__VA_ARGS__)
+#define print(fmt, ...) debug_log(false, fmt, ##__VA_ARGS__)
+#define println(fmt, ...) debug_log(false, fmt "\r\n", ##__VA_ARGS__)
 
 void debug_log(bool log, const char *format, ...) __attribute__((format(printf, 2, 3)));
 void log_dump_to_usb(void);

firmware/include/pmw3360.h

 #ifndef __PMW3360_H__
 #define __PMW3360_H__
 
+#include <sys/types.h>
+
 struct pmw_motion {
     bool motion;
     int32_t delta_x;
 };
 
 int pmw_init(void);
+void pmw_run(void);
 bool pmw_is_alive(void);
 
 struct pmw_motion pmw_get(void);
 #define PMW_CPI_TO_SENSE(cpi) ((cpi / 100) - 1)
 
 void pmw_print_status(void);
+void pmw_dump_data(void);
+
+ssize_t pmw_frame_capture(uint8_t *buff, size_t buffsize);
+#define PMW_FRAME_CAPTURE_LEN 1296
 
 #endif // __PMW3360_H__

firmware/include/util.h

 void reset_to_bootloader(void);
 void reset_to_main(void);
 
+void hexdump(uint8_t *buff, size_t len);
+
 #endif // __UTIL_H__

firmware/src/console.c

     if (strlen(line) == 0) {
         if ((strlen(cnsl_last_command) > 0) && (strcmp(cnsl_last_command, "repeat") != 0)) {
             // repeat last command once
-            print("repeating command \"%s\"", cnsl_last_command);
+            println("repeating command \"%s\"", cnsl_last_command);
             cnsl_interpret(cnsl_last_command);
-            print();
+            println();
         }
         return;
     } else if (strcmp(line, "repeat") == 0) {
     } else if ((strcmp(line, "help") == 0)
             || (strcmp(line, "h") == 0)
             || (strcmp(line, "?") == 0)) {
-        print("Trackball Firmware Usage:");
-        print("    cpi - print current sensitivity");
-        print("  cpi N - set sensitivity");
-        print("   pmws - print PMW3360 status");
-        print("   pmwr - reset PMW3360");
-        print("  reset - reset back into this firmware");
-        print("   \\x18 - reset to bootloader");
-        print(" repeat - repeat last command every %d milliseconds", CNSL_REPEAT_MS);
-        print("   help - print this message");
-        print("Press Enter with no input to repeat last command.");
-        print("Use repeat to continuously execute last command.");
-        print("Stop this by calling repeat again.");
+        println("Trackball Firmware Usage:");
+        println("    cpi - print current sensitivity");
+        println("  cpi N - set sensitivity");
+        println("   pmws - print PMW3360 status");
+        println("   pmwf - print PMW3360 frame capture");
+        println("   pmwd - print PMW3360 data dump");
+        println("   pmwr - reset PMW3360");
+        println("  reset - reset back into this firmware");
+        println("   \\x18 - reset to bootloader");
+        println(" repeat - repeat last command every %d milliseconds", CNSL_REPEAT_MS);
+        println("   help - print this message");
+        println("Press Enter with no input to repeat last command.");
+        println("Use repeat to continuously execute last command.");
+        println("Stop this by calling repeat again.");
     } else if (strcmp(line, "pmws") == 0) {
         pmw_print_status();
+    } else if (strcmp(line, "pmwd") == 0) {
+        pmw_dump_data();
+    } else if (strcmp(line, "pmwf") == 0) {
+        uint8_t frame[PMW_FRAME_CAPTURE_LEN];
+        ssize_t r = pmw_frame_capture(frame, PMW_FRAME_CAPTURE_LEN);
+        if (r == PMW_FRAME_CAPTURE_LEN) {
+            println("PMW3360 frame capture:");
+            hexdump(frame, PMW_FRAME_CAPTURE_LEN);
+
+            println("Re-Initializing PMW3360");
+            pmw_init();
+        } else {
+            println("error capturing frame (%d)", r);
+        }
     } else if (strcmp(line, "pmwr") == 0) {
-        print("user requests re-initializing of PMW3360");
+        println("user requests re-initializing of PMW3360");
         int r = pmw_init();
         if (r < 0) {
-            print("error initializing PMW3360");
+            println("error initializing PMW3360");
         } else {
-            print("PMW3360 re-initialized successfully");
+            println("PMW3360 re-initialized successfully");
         }
     } else if (strcmp(line, "cpi") == 0) {
         uint8_t sense = pmw_get_sensitivity();
         uint16_t cpi = PMW_SENSE_TO_CPI(sense);
-        print("current cpi: %u (0x%02X)", cpi, sense);
+        println("current cpi: %u (0x%02X)", cpi, sense);
     } else if (str_startswith(line, "cpi ")) {
         const char *num_str = line + 4;
         uintmax_t num = strtoumax(num_str, NULL, 10);
         if ((num < 100) || (num > 12000)) {
-            print("invalid cpi %llu, needs to be %u <= cpi <= %u", num, 100, 12000);
+            println("invalid cpi %llu, needs to be %u <= cpi <= %u", num, 100, 12000);
         } else {
             num = PMW_CPI_TO_SENSE(num);
-            print("setting cpi to 0x%02llX", num);
+            println("setting cpi to 0x%02llX", num);
             pmw_set_sensitivity(num);
         }
     } else if (strcmp(line, "reset") == 0) {
         reset_to_main();
     } else {
-        print("unknown command \"%s\"", line);
+        println("unknown command \"%s\"", line);
         return;
     }
 
-    print();
+    println();
 }
 
 void cnsl_init(void) {
             && (strcmp(cnsl_repeated_command, "repeat") != 0)) {
         uint32_t now = to_ms_since_boot(get_absolute_time());
         if (now >= (last_repeat_time + CNSL_REPEAT_MS)) {
-            print("repeating command \"%s\"", cnsl_repeated_command);
+            println("repeating command \"%s\"", cnsl_repeated_command);
             cnsl_interpret(cnsl_repeated_command);
-            print();
+            println();
 
             last_repeat_time = now;
         }
     } else {
         if (repeat_command) {
-            print("nothing to repeat");
+            println("nothing to repeat");
         }
         repeat_command = false;
     }

firmware/src/main.c

 #include "usb.h"
 #include "pmw3360.h"
 
-#define HEALTH_CHECK_INTERVAL_MS 500
-static uint32_t last_health_check = 0;
-
 int main(void) {
     heartbeat_init();
 
         heartbeat_run();
         usb_run();
         cnsl_run();
-
-        uint32_t now = to_ms_since_boot(get_absolute_time());
-        if (now >= (last_health_check + HEALTH_CHECK_INTERVAL_MS)) {
-            last_health_check = now;
-            if (!pmw_is_alive()) {
-                debug("PMW3360 is dead. resetting!");
-                while (1) { }
-            }
-        }
+        pmw_run();
     }
 
     return 0;

firmware/src/pmw3360.c

 #include "pico/stdlib.h"
 #include "pico/binary_info.h"
 #include "hardware/spi.h"
+#include "hardware/watchdog.h"
 
 #include "config.h"
 #include "log.h"
 #include "pmw3360_srom.h"
 #include "pmw3360.h"
 
+#define HEALTH_CHECK_INTERVAL_MS 1000
+
 #if !defined(spi_default) || !defined(PICO_DEFAULT_SPI_SCK_PIN) || !defined(PICO_DEFAULT_SPI_TX_PIN) || !defined(PICO_DEFAULT_SPI_RX_PIN) || !defined(PICO_DEFAULT_SPI_CSN_PIN)
 #error PMW3360 API requires a board with SPI pins
 #endif
 
 static volatile int32_t delta_x = 0, delta_y = 0;
 static volatile bool mouse_motion = false;
+static uint32_t last_health_check = 0;
 
 #ifdef PMW_IRQ_COUNTERS
 static uint64_t pmw_irq_count_all = 0;
 #endif // PMW_IRQ_COUNTERS
 
 void pmw_print_status(void) {
+    bool com = pmw_is_alive();
+    if (com) {
+        println("Communication to PMW3360 is working");
+    } else {
+        println("ERROR: can not communicate to PMW3360");
+    }
+
 #ifdef PMW_IRQ_COUNTERS
-    print("    pmw_irq_cnt_all = %llu", pmw_irq_count_all);
-    print(" pmw_irq_cnt_motion = %llu", pmw_irq_count_motion);
-    print("pmw_irq_cnt_no_move = %llu", pmw_irq_count_no_motion);
-    print("pmw_irq_cnt_surface = %llu", pmw_irq_count_on_surface);
-    print(" pmw_irq_cnt_lifted = %llu", pmw_irq_count_lifted);
-    print("    pmw_irq_cnt_run = %llu", pmw_irq_count_run);
-    print("  pmw_irq_cnt_rest1 = %llu", pmw_irq_count_rest1);
-    print("  pmw_irq_cnt_rest2 = %llu", pmw_irq_count_rest2);
-    print("  pmw_irq_cnt_rest3 = %llu", pmw_irq_count_rest3);
+    println("Interrupt statistics:");
+    println("    pmw_irq_cnt_all = %llu", pmw_irq_count_all);
+    println(" pmw_irq_cnt_motion = %llu", pmw_irq_count_motion);
+    println("pmw_irq_cnt_no_move = %llu", pmw_irq_count_no_motion);
+    println("pmw_irq_cnt_surface = %llu", pmw_irq_count_on_surface);
+    println(" pmw_irq_cnt_lifted = %llu", pmw_irq_count_lifted);
+    println("    pmw_irq_cnt_run = %llu", pmw_irq_count_run);
+    println("  pmw_irq_cnt_rest1 = %llu", pmw_irq_count_rest1);
+    println("  pmw_irq_cnt_rest2 = %llu", pmw_irq_count_rest2);
+    println("  pmw_irq_cnt_rest3 = %llu", pmw_irq_count_rest3);
 #endif // PMW_IRQ_COUNTERS
 }
 
     return sense_y;
 }
 
+static void pmw_irq_start(void) {
+    gpio_set_irq_enabled(PMW_MOTION_PIN, GPIO_IRQ_LEVEL_LOW, true);
+}
+
+static void pmw_irq_stop(void) {
+    gpio_set_irq_enabled(PMW_MOTION_PIN, GPIO_IRQ_LEVEL_LOW, false);
+}
+
 static void pmw_irq_init(void) {
     // setup MOTION pin interrupt to handle reading data
     gpio_add_raw_irq_handler(PMW_MOTION_PIN, pmw_motion_irq);
-    gpio_set_irq_enabled(PMW_MOTION_PIN, GPIO_IRQ_LEVEL_LOW, true);
+    pmw_irq_start();
     irq_set_enabled(IO_IRQ_BANK0, true);
 
     // make MOTION pin available to picotool
     bi_decl(bi_1pin_with_name(PMW_MOTION_PIN, "PMW3360 MOTION"));
 }
 
-static void pmw_irq_stop(void) {
-    gpio_set_irq_enabled(PMW_MOTION_PIN, GPIO_IRQ_LEVEL_LOW, false);
-    irq_set_enabled(IO_IRQ_BANK0, false);
-}
-
 bool pmw_is_alive(void) {
     bool r = true;
     gpio_set_irq_enabled(PMW_MOTION_PIN, GPIO_IRQ_LEVEL_LOW, false);
     return r;
 }
 
+ssize_t pmw_frame_capture(uint8_t *buff, size_t buffsize) {
+    if ((buffsize < PMW_FRAME_CAPTURE_LEN) || (buff == NULL)) {
+        debug("invalid or too small buffer (%u < %u)", buffsize, PMW_FRAME_CAPTURE_LEN);
+        return -1;
+    }
+
+    pmw_irq_stop();
+
+    // write 0 to Rest_En bit of Config2 register to disable Rest mode
+    pmw_write_register(REG_CONFIG2, 0x00);
+
+    // write 0x83 to Frame_Capture register
+    pmw_write_register(REG_FRAME_CAPTURE, 0x83);
+
+    // write 0xC5 to Frame_Capture register
+    pmw_write_register(REG_FRAME_CAPTURE, 0xC5);
+
+    // wait for 20ms
+    busy_wait_ms(20);
+
+    // continue burst read from Raw_data_Burst register until all 1296 raw data are transferred
+    pmw_read_register_burst(REG_RAW_DATA_BURST, buff, PMW_FRAME_CAPTURE_LEN);
+
+    return PMW_FRAME_CAPTURE_LEN;
+}
+
+#define PMW_DATA_DUMP_SAMPLES 5000
+
+void pmw_dump_data(void) {
+    struct pmw_motion_report buff[PMW_DATA_DUMP_SAMPLES];
+
+    println("Will now capture %u data samples from PMW3360", PMW_DATA_DUMP_SAMPLES);
+    println("Move trackball to generate some data!");
+
+    pmw_irq_stop();
+
+    for (size_t i = 0; i < PMW_DATA_DUMP_SAMPLES; i++) {
+        // wait until MOTION pin is set
+        while (gpio_get(PMW_MOTION_PIN)) {
+            watchdog_update();
+        }
+
+        buff[i] = pmw_motion_read();
+    }
+
+    println();
+    println("time,motion,observation,delta_x,delta_y,squal,raw_sum,raw_max,raw_min,shutter");
+    for (size_t i = 0; i < PMW_DATA_DUMP_SAMPLES; i++) {
+        watchdog_update();
+
+        uint16_t delta_x_raw = buff[i].delta_x_l | (buff[i].delta_x_h << 8);
+        uint16_t delta_y_raw = buff[i].delta_y_l | (buff[i].delta_y_h << 8);
+        uint16_t shutter_raw = buff[i].shutter_lower | (buff[i].shutter_upper << 8);
+
+        print("%llu,", to_us_since_boot(get_absolute_time()));
+        print("%u,", buff[i].motion);
+        print("%u,", buff[i].observation);
+        print("%ld,", convert_two_complement(delta_x_raw));
+        print("%ld,", convert_two_complement(delta_y_raw));
+        print("%u,", buff[i].squal);
+        print("%u,", buff[i].raw_data_sum);
+        print("%u,", buff[i].maximum_raw_data);
+        print("%u,", buff[i].minimum_raw_data);
+        println("%u", shutter_raw);
+    }
+    println();
+
+    pmw_irq_start();
+}
+
 int pmw_init(void) {
+    // initializing takes a while (~160ms)
+    watchdog_update();
+
     pmw_irq_stop();
     pmw_spi_init();
 
     uint8_t srom_id = pmw_power_up();
-
     uint8_t prod_id = pmw_read_register(REG_PRODUCT_ID);
     uint8_t inv_prod_id = pmw_read_register(REG_INVERSE_PRODUCT_ID);
     uint16_t srom_checksum = pmw_srom_checksum();
         return -1;
     }
 
-    if (srom_id != pmw_fw_id) {
-        debug("PMW3360 error: invalid SROM ID (0x%02X != 0x%02X)", srom_id, pmw_fw_id);
-        return -1;
-    }
+    if ((srom_id != pmw_fw_id) || (srom_checksum != pmw_fw_crc)) {
+        if (srom_id != pmw_fw_id) {
+            debug("PMW3360 error: invalid SROM ID (0x%02X != 0x%02X)", srom_id, pmw_fw_id);
+        }
+
+        if (srom_checksum != pmw_fw_crc) {
+            debug("PMW3360 error: invalid SROM CRC (0x%04X != 0x%04X)", srom_checksum, pmw_fw_crc);
+        }
 
-    if (srom_checksum != pmw_fw_crc) {
-        debug("PMW3360 error: invalid SROM CRC (0x%04X != 0x%04X)", srom_checksum, pmw_fw_crc);
+        debug("this may require a power-cycle to fix!");
         return -1;
     }
 
 
     return 0;
 }
+
+void pmw_run(void) {
+    uint32_t now = to_ms_since_boot(get_absolute_time());
+    if (now >= (last_health_check + HEALTH_CHECK_INTERVAL_MS)) {
+        last_health_check = now;
+        if (!pmw_is_alive()) {
+            debug("PMW3360 is dead. resetting!");
+            reset_to_main();
+        }
+    }
+}

firmware/src/util.c

 #include "hardware/watchdog.h"
 
 #include "config.h"
+#include "log.h"
 #include "util.h"
 
 #define HEARTBEAT_INTERVAL_MS 500
         asm volatile("nop");
     }
 }
+
+void hexdump(uint8_t *buff, size_t len) {
+    for (size_t i = 0; i < len; i += 16) {
+        for (size_t j = 0; (j < 16) && ((i + j) < len); j++) {
+            print("0x%02X", buff[i + j]);
+            if ((j < 15) && ((i + j) < (len - 1))) {
+                print(" ");
+            }
+        }
+        println();
+    }
+}

firmware/util/README.md

+# RP2040 Trackball Firmware Utilities
+
+Some utilities to help with this project.
+
+## Frame Capture and Visualization
+
+The PMW3360 mouse sensor can do full captures of the raw 2D image seen by the chip.
+These can be grabbed from the firmware by opening the debug USB serial port and running the `pmwf` command.
+The output should be pasted into a textfile and can then be visualized using the included `visualize_frame.py` script.
+
+## Data Capture and Visualization
+
+The firmware can also grab a number of data samples from the sensor, by running the `pmwd` command.
+The output can then be visualized with `visualize_data.py`.

firmware/util/visualize_data.py

+#!/usr/bin/env python
+
+import matplotlib.pyplot as plt
+import numpy as np
+import sys
+import math
+
+if len(sys.argv) < 2:
+    print("Usage:")
+    print("    " + sys.argv[0] + " filename")
+    sys.exit(0)
+
+fig, axes = plt.subplots(6, 1, figsize=(5, 15))
+
+data = []
+lines_heading = []
+with open(sys.argv[1]) as f:
+    lines = f.readlines()
+    lines_heading = lines[0].split(',')
+    lines_data = lines[1:]
+    for line in lines_data:
+        nums = line.split(',')
+        line_data = []
+        for r in nums:
+            line_data.append(int(r))
+        data.append(line_data)
+
+start_time = data[0][0]
+for i in range(0, len(data)):
+    data[i][0] = (data[i][0] - start_time) / 1000.0 / 1000.0
+
+print("samples: " + str(len(data)))
+
+x = [ r[0] for r in data ]
+
+for n in range(3, 9):
+    y = [ r[n] for r in data ]
+    im = axes[n - 3].plot(x, y)
+    axes[n - 3].set_title(lines_heading[n])
+
+plt.suptitle(sys.argv[1], fontsize=18)
+plt.tight_layout()
+plt.show()

firmware/util/visualize_frame.py

+#!/usr/bin/env python
+
+import matplotlib.pyplot as plt
+import numpy as np
+import sys
+import math
+
+if len(sys.argv) < 2:
+    print("Usage:")
+    print("    " + sys.argv[0] + " filename [...]")
+    sys.exit(0)
+
+fig, axes = plt.subplots(1, len(sys.argv) - 1, figsize=(15, 5))
+
+# support one or multiple files
+if not isinstance(axes, np.ndarray):
+    axes = [axes]
+
+for n in range(0, len(sys.argv) - 1):
+    print("reading " + sys.argv[n + 1])
+
+    frame = []
+    with open(sys.argv[n + 1]) as f:
+        lines = f.readlines()
+        for line in lines:
+            nums = line.split()
+            for r in nums:
+                frame.append(int(r, 16))
+
+    print("frame length: " + str(len(frame)))
+    row_len = math.sqrt(len(frame))
+    print("row length: " + str(row_len))
+    row_len = int(row_len)
+
+    frame2d = []
+    for i in range(0, row_len):
+        row = []
+        for j in range(0, row_len):
+            row.append(frame[i * row_len + j])
+        frame2d.append(row)
+
+    im = axes[n].imshow(frame2d, vmin=0, vmax=0xFF, cmap='plasma')
+    axes[n].set_title(sys.argv[n + 1], fontsize=18)
+
+fig.colorbar(im, ax=axes, label='Value Range')
+plt.suptitle('Pan and Zoom on colorbar to adjust', fontsize=10)
+plt.show()