Updates along with SDK1.3.0 release (#181)

Bug fixes and new examples

Co-authored-by: Paulo Marques <pm@quant-insight.com>
Co-authored-by: martin <admin@crossleys.biz>
Co-authored-by: matiasilva <matias.silva@raspberrypi.com>
Co-authored-by: Uri Shaked <uri@urishaked.com>
Co-authored-by: Diego Solano <diegosolano@gmail.com>
Co-authored-by: Andrew Scheller <andrew.scheller@raspberrypi.com>
Co-authored-by: Adrian Hesketh <a-h@users.noreply.github.com>
Co-authored-by: Emircan Gündoğdu <58917386+emircangun@users.noreply.github.com>
Co-authored-by: Josef Wegner <80200012+josefwegner@users.noreply.github.com>
Co-authored-by: pmarques-dev <72901351+pmarques-dev@users.noreply.github.com>
Co-authored-by: Paulo Marques <pm@quant-insight.com>
Co-authored-by: mjcross <mjcross@users.noreply.github.com>
Co-authored-by: martin <admin@crossleys.biz>

pio/CMakeLists.txt

@@ -6,10 +6,12 @@ if (NOT PICO_NO_HARDWARE)
     add_subdirectory(hello_pio)
     add_subdirectory(hub75)
     add_subdirectory(i2c)
+    add_subdirectory(ir_nec)
     add_subdirectory(logic_analyser)
     add_subdirectory(manchester_encoding)
     add_subdirectory(pio_blink)
     add_subdirectory(pwm)
+    add_subdirectory(quadrature_encoder)
     add_subdirectory(spi)
     add_subdirectory(squarewave)
     add_subdirectory(st7789_lcd)

pio/addition/addition.pio

@@ -1,3 +1,9 @@
+;
+; Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
+;
+; SPDX-License-Identifier: BSD-3-Clause
+;
+
 .program addition
 
 ; Pop two 32 bit integers from the TX FIFO, add them together, and push the

pio/hub75/hub75.pio

@@ -1,3 +1,9 @@
+;
+; Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
+;
+; SPDX-License-Identifier: BSD-3-Clause
+;
+
 .program hub75_row
 
 ; side-set pin 0 is LATCH

pio/ir_nec/CMakeLists.txt

@@ -0,0 +1,8 @@
+# build the transmit and receive libraries
+#
+add_subdirectory(nec_transmit_library)
+add_subdirectory(nec_receive_library)
+
+# build the example program
+#
+add_subdirectory(ir_loopback)

pio/ir_nec/README.adoc

@@ -0,0 +1,57 @@
+= Sending and receiving IR (infra-red) codes using the PIO
+
+This example shows how to use the Raspberry Pi Pico (RP2040) to send and receive infra-red frames in the 'NEC' format that is used by many consumer remote control applications.
+
+It performs a loopback test by transmitting IR codes via an IR LED and receiving them on an IR detector. The results are sent to the default serial terminal connnected via UART or USB as configured in the SDK.
+
+The tasks of encoding and decoding the data are offloaded to the RP2040 PIO state machines. This releases the main processor cores to concentrate on other tasks.
+
+== Wiring information
+
+Connect GPIO 14 to the positive side ('anode') of an IR LED via a suitable series resistor e.g. 1.5k Ohms, and the negative side ('cathode') to ground. The wavelength of the LED is unlikely to be critical so long as it is compatible with your detector.
+
+Connect GPIO 15 to the output of a 3.3v IR detector such as the VS1838b, and wire the power connections of the detector to 3v3 and ground. The program expects the decoder output to be low (logic '0') when a carrier is detected.
+
+[[pio_ir_loopback_wiring]]
+[pdfwidth=75%]
+.Wiring Diagram for IR loopback.
+image::pio_ir_loopback.png[]
+
+== Build information
+
+The code is organised into three sub-directories. These contain the loopback example and two libraries for the IR transmit and receive functions.
+
+After a successful build the executable program can be found in the **build/ir_loopback** directory.
+
+== List of Files
+
+CMakeLists.txt:: CMake file to incorporate the example in to the examples build tree.
+ir_loopback:: A directory containing the code for the loopback example.
+CMakeLists.txt::: CMake file to incorporate the example in to the examples build tree.
+ir_loopback.c::: The code for the loopback example.
+nec_receive_library:: A directory containing the code for the IR receive functions.
+CMakeLists.txt::: CMake file to incorporate the IR receive library in to the examples build tree.
+nec_receive.c::: The source code for the IR receive functions.
+nec_receive.h::: The headers for the IR receive functions.
+nec_receive.pio::: The PIO assembler code to receive a frame.
+nec_transmit_library:: A directory containing the code for the IR transmit functions.
+CMakeLists.txt::: CMake file to incorporate the IR transmit library in to the examples build tree.
+nec_transmit.c::: The source code for the IR transmit functions.
+nec_transmit.h::: The headers for the IR transmit functions.
+nec_carrier_burst.pio::: The PIO assembler code to generate a carrier burst.
+nec_carrier_control.pio::: The PIO assembler code to transmit a complete frame.
+
+== Bill of Materials
+
+.A list of materials required for the example
+[[pio_ir_loopback-bom-table]]
+[cols=3]
+|===
+| *Item* | *Quantity* | Details
+| Breadboard | 1 | generic part
+| Raspberry Pi Pico | 1 | https://www.raspberrypi.com/products/raspberry-pi-pico/
+| Infra-Red LED | 1 | generic part
+| 1500 ohm resistor | 1 | generic part
+| Infra-Red Detector | 1 | generic part e.g. VS1838b
+| M/M Jumper wires | 5 | generic part
+|===

pio/ir_nec/ir_loopback/CMakeLists.txt

@@ -0,0 +1,15 @@
+add_executable (pio_ir_loopback ir_loopback.c)
+
+# link the executable using the IR transmit and receive libraries
+#
+target_link_libraries(pio_ir_loopback LINK_PUBLIC
+  pico_stdlib
+  hardware_pio
+  nec_transmit_library
+  nec_receive_library
+  )
+
+pico_add_extra_outputs(pio_ir_loopback)
+
+# add url via pico_set_program_url
+example_auto_set_url(pio_ir_loopback)

pio/ir_nec/ir_loopback/ir_loopback.c

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) 2021 mjcross
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include <stdio.h>
+#include "pico/stdlib.h"
+
+#include "nec_transmit.h"                           // include the library headers
+#include "nec_receive.h"
+
+// Infrared loopback example ('NEC' format)
+//
+// Need to connect an IR LED to GPIO 14 via a suitable series resistor (e.g. 1.5k)
+// and an active-low IR detector to GPIO 15 (e.g. VS1838b)
+//
+// Output is sent to stdout
+
+int main() {
+    stdio_init_all();
+
+    PIO pio = pio0;                                 // choose which PIO block to use (RP2040 has two: pio0 and pio1)
+    uint tx_gpio = 14;                              // choose which GPIO pin is connected to the IR LED
+    uint rx_gpio = 15;                              // choose which GPIO pin is connected to the IR detector
+
+    // configure and enable the state machines
+    int tx_sm = nec_tx_init(pio, tx_gpio);         // uses two state machines, 16 instructions and one IRQ
+    int rx_sm = nec_rx_init(pio, rx_gpio);         // uses one state machine and 9 instructions
+
+    if (tx_sm == -1 || rx_sm == -1) {
+        printf("could not configure PIO\n");
+        return -1;
+    }
+
+    // transmit and receive frames
+    uint8_t tx_address = 0x00, tx_data = 0x00, rx_address, rx_data;
+    while (true) {
+        // create a 32-bit frame and add it to the transmit FIFO
+        uint32_t tx_frame = nec_encode_frame(tx_address, tx_data);
+        pio_sm_put(pio, tx_sm, tx_frame);
+        printf("\nsent: %02x, %02x", tx_address, tx_data);
+
+        // allow time for the frame to be transmitted (optional)
+        sleep_ms(100);
+
+        // display any frames in the receive FIFO
+        while (!pio_sm_is_rx_fifo_empty(pio, rx_sm)) {
+            uint32_t rx_frame = pio_sm_get(pio, rx_sm);
+
+            if (nec_decode_frame(rx_frame, &rx_address, &rx_data)) {
+                printf("\treceived: %02x, %02x", rx_address, rx_data);
+            } else {
+                printf("\treceived: %08x", rx_frame);
+            }
+        }
+
+        sleep_ms(900);
+        tx_data += 1;
+    }
+}

pio/ir_nec/nec_receive_library/CMakeLists.txt

@@ -0,0 +1,19 @@
+# build a normal library
+#
+add_library(nec_receive_library nec_receive.c)
+
+# invoke pio_asm to assemble the state machine program
+#
+pico_generate_pio_header(nec_receive_library ${CMAKE_CURRENT_LIST_DIR}/nec_receive.pio)
+
+target_link_libraries(nec_receive_library PRIVATE
+        pico_stdlib
+        hardware_pio
+        )
+
+# add the `binary` directory so that the generated headers are included in the project
+#
+target_include_directories (nec_receive_library PUBLIC
+	${CMAKE_CURRENT_SOURCE_DIR}
+	${CMAKE_CURRENT_BINARY_DIR}
+	)

pio/ir_nec/nec_receive_library/nec_receive.c

@@ -0,0 +1,79 @@
+/**
+ * Copyright (c) 2021 mjcross
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+// SDK types and declarations
+#include "pico/stdlib.h"
+#include "hardware/pio.h"
+#include "hardware/clocks.h"    // for clock_get_hz()
+
+#include "nec_receive.h"
+
+// import the assembled PIO state machine program
+#include "nec_receive.pio.h"
+
+// Claim an unused state machine on the specified PIO and configure it
+// to receive NEC IR frames on the given GPIO pin.
+//
+// Returns: the state machine number on success, otherwise -1
+int nec_rx_init(PIO pio, uint pin_num) {
+
+    // disable pull-up and pull-down on gpio pin
+    gpio_disable_pulls(pin_num);
+
+    // install the program in the PIO shared instruction space
+    uint offset;
+    if (pio_can_add_program(pio, &nec_receive_program)) {
+        offset = pio_add_program(pio, &nec_receive_program);
+    } else {
+        return -1;      // the program could not be added
+    }
+
+    // claim an unused state machine on this PIO
+    int sm = pio_claim_unused_sm(pio, true);
+    if (sm == -1) {
+        return -1;      // we were unable to claim a state machine
+    }
+
+    // configure and enable the state machine
+    nec_receive_program_init(pio, sm, offset, pin_num);
+
+    return sm;
+}
+
+
+// Validate a 32-bit frame and store the address and data at the locations
+// provided.
+//
+// Returns: `true` if the frame was valid, otherwise `false`
+bool nec_decode_frame(uint32_t frame, uint8_t *p_address, uint8_t *p_data) {
+
+    // access the frame data as four 8-bit fields
+    //
+    union {
+        uint32_t raw;
+        struct {
+            uint8_t address;
+            uint8_t inverted_address;
+            uint8_t data;
+            uint8_t inverted_data;
+        };
+    } f;
+
+    f.raw = frame;
+
+    // a valid (non-extended) 'NEC' frame should contain 8 bit
+    // address, inverted address, data and inverted data
+    if (f.address != (f.inverted_address ^ 0xff) ||
+        f.data != (f.inverted_data ^ 0xff)) {
+        return false;
+    }
+
+    // store the validated address and data
+    *p_address = f.address;
+    *p_data = f.data;
+
+    return true;
+}

pio/ir_nec/nec_receive_library/nec_receive.h

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2021 mjcross
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "pico/stdlib.h"
+#include "hardware/pio.h"
+
+// public API
+
+int nec_rx_init(PIO pio, uint pin);
+bool nec_decode_frame(uint32_t sm, uint8_t *p_address, uint8_t *p_data);

pio/ir_nec/nec_receive_library/nec_receive.pio

@@ -0,0 +1,96 @@
+;
+; Copyright (c) 2021 mjcross
+;
+; SPDX-License-Identifier: BSD-3-Clause
+;
+
+
+.program nec_receive
+
+; Decode IR frames in NEC format and push 32-bit words to the input FIFO.
+;
+; The input pin should be connected to an IR detector with an 'active low' output.
+;
+; This program expects there to be 10 state machine clock ticks per 'normal' 562.5us burst period
+; in order to permit timely detection of start of a burst. The initailisation function below sets
+; the correct divisor to achive this relative to the system clock.
+;
+; Within the 'NEC' protocol frames consists of 32 bits sent least-siginificant bit first; so the
+; Input Shift Register should be configured to shift right and autopush after 32 bits, as in the
+; initialisation function below.
+;
+.define BURST_LOOP_COUNTER 30                   ; the detection threshold for a 'frame sync' burst
+.define BIT_SAMPLE_DELAY 15                     ; how long to wait after the end of the burst before sampling
+
+.wrap_target
+
+next_burst:
+    set X, BURST_LOOP_COUNTER
+    wait 0 pin 0                                ; wait for the next burst to start
+
+burst_loop:
+    jmp pin data_bit                            ; the burst ended before the counter expired
+    jmp X-- burst_loop                          ; wait for the burst to end
+
+                                                ; the counter expired - this is a sync burst
+    mov ISR, NULL                               ; reset the Input Shift Register
+    wait 1 pin 0                                ; wait for the sync burst to finish
+    jmp next_burst                              ; wait for the first data bit
+
+data_bit:
+    nop [ BIT_SAMPLE_DELAY - 1 ]                ; wait for 1.5 burst periods before sampling the bit value
+    in PINS, 1                                  ; if the next burst has started then detect a '0' (short gap)
+                                                ; otherwise detect a '1' (long gap)
+                                                ; after 32 bits the ISR will autopush to the receive FIFO
+.wrap
+
+
+% c-sdk {
+static inline void nec_receive_program_init (PIO pio, uint sm, uint offset, uint pin) {
+
+    // Set the GPIO function of the pin (connect the PIO to the pad)
+    //
+    pio_gpio_init(pio, pin);
+
+    // Set the pin direction to `input` at the PIO
+    //
+    pio_sm_set_consecutive_pindirs(pio, sm, pin, 1, false);
+
+    // Create a new state machine configuration
+    //
+    pio_sm_config c = nec_receive_program_get_default_config (offset);
+
+    // configure the Input Shift Register
+    //
+    sm_config_set_in_shift (&c,
+                            true,       // shift right
+                            true,       // enable autopush
+                            32);        // autopush after 32 bits
+
+    // join the FIFOs to make a single large receive FIFO
+    //
+    sm_config_set_fifo_join (&c, PIO_FIFO_JOIN_RX);
+
+    // Map the IN pin group to one pin, namely the `pin`
+    // parameter to this function.
+    //
+    sm_config_set_in_pins (&c, pin);
+
+    // Map the JMP pin to the `pin` parameter of this function.
+    //
+    sm_config_set_jmp_pin (&c, pin);
+
+    // Set the clock divider to 10 ticks per 562.5us burst period
+    //
+    float div = clock_get_hz (clk_sys) / (10.0 / 526.6e-6);
+    sm_config_set_clkdiv (&c, div);
+
+    // Apply the configuration to the state machine
+    //
+    pio_sm_init (pio, sm, offset, &c);
+
+    // Set the state machine running
+    //
+    pio_sm_set_enabled (pio, sm, true);
+}
+%}

pio/ir_nec/nec_transmit_library/CMakeLists.txt

@@ -0,0 +1,20 @@
+# build a normal library
+#
+add_library(nec_transmit_library nec_transmit.c)
+
+# invoke pio_asm to assemble the PIO state machine programs
+#
+pico_generate_pio_header(nec_transmit_library ${CMAKE_CURRENT_LIST_DIR}/nec_carrier_burst.pio)
+pico_generate_pio_header(nec_transmit_library ${CMAKE_CURRENT_LIST_DIR}/nec_carrier_control.pio)
+
+target_link_libraries(nec_transmit_library PRIVATE
+        pico_stdlib
+        hardware_pio
+        )
+
+# add the `binary` directory so that the generated headers are included in the project
+#
+target_include_directories (nec_transmit_library PUBLIC
+	${CMAKE_CURRENT_SOURCE_DIR}
+	${CMAKE_CURRENT_BINARY_DIR}
+	)

pio/ir_nec/nec_transmit_library/nec_carrier_burst.pio

@@ -0,0 +1,61 @@
+;
+; Copyright (c) 2021 mjcross
+;
+; SPDX-License-Identifier: BSD-3-Clause
+;
+
+
+.program nec_carrier_burst
+
+; Generate bursts of carrier.
+;
+; Repeatedly wait for an IRQ to be set then clear it and generate 21 cycles of
+; carrier with 25% duty cycle
+;
+.define NUM_CYCLES 21               ; how many carrier cycles to generate
+.define BURST_IRQ 7                 ; which IRQ should trigger a carrier burst
+.define public TICKS_PER_LOOP 4     ; the number of instructions in the loop (for timing)
+
+.wrap_target
+    set X, (NUM_CYCLES - 1)         ; initialise the loop counter
+    wait 1 irq BURST_IRQ            ; wait for the IRQ then clear it
+cycle_loop:
+    set pins, 1                     ; set the pin high (1 cycle)
+    set pins, 0 [1]                 ; set the pin low (2 cycles)
+    jmp X--, cycle_loop             ; (1 more cycle)
+.wrap
+
+
+% c-sdk {
+static inline void nec_carrier_burst_program_init(PIO pio, uint sm, uint offset, uint pin, float freq) {
+    // Create a new state machine configuration
+    //
+    pio_sm_config c = nec_carrier_burst_program_get_default_config (offset);
+
+    // Map the SET pin group to one pin, namely the `pin`
+    // parameter to this function.
+    //
+    sm_config_set_set_pins (&c, pin, 1);
+
+    // Set the GPIO function of the pin (connect the PIO to the pad)
+    //
+    pio_gpio_init (pio, pin);
+
+    // Set the pin direction to output at the PIO
+    //
+    pio_sm_set_consecutive_pindirs (pio, sm, pin, 1, true);
+
+    // Set the clock divider to generate the required frequency
+    //
+    float div = clock_get_hz (clk_sys) / (freq * nec_carrier_burst_TICKS_PER_LOOP);
+    sm_config_set_clkdiv (&c, div);
+
+    // Apply the configuration to the state machine
+    //
+    pio_sm_init (pio, sm, offset, &c);
+
+    // Set the state machine running
+    //
+    pio_sm_set_enabled (pio, sm, true);
+}
+%}

pio/ir_nec/nec_transmit_library/nec_carrier_control.pio

@@ -0,0 +1,79 @@
+;
+; Copyright (c) 2021 mjcross
+;
+; SPDX-License-Identifier: BSD-3-Clause
+;
+
+
+.program nec_carrier_control
+
+; Transmit an encoded 32-bit frame in NEC IR format.
+;
+; Accepts 32-bit words from the transmit FIFO and sends them least-significant bit first
+; using pulse position modulation.
+;
+; Carrier bursts are generated using the nec_carrier_burst program, which is expected to be
+; running on a separate state machine.
+;
+; This program expects there to be 2 state machine ticks per 'normal' 562.5us
+; burst period.
+;
+.define BURST_IRQ 7                     ; the IRQ used to trigger a carrier burst
+.define NUM_INITIAL_BURSTS 16           ; how many bursts to transmit for a 'sync burst'
+
+.wrap_target
+    pull                                ; fetch a data word from the transmit FIFO into the
+                                        ; output shift register, blocking if the FIFO is empty
+
+    set X, (NUM_INITIAL_BURSTS - 1)     ; send a sync burst (9ms)
+long_burst:
+    irq BURST_IRQ
+    jmp X-- long_burst
+
+    nop [15]                            ; send a 4.5ms space
+    irq BURST_IRQ [1]                   ; send a 562.5us burst to begin the first data bit
+
+data_bit:
+    out X, 1                            ; shift the least-significant bit from the OSR
+    jmp !X burst                        ; send a short delay for a '0' bit
+    nop [3]                             ; send an additional delay for a '1' bit
+burst:
+    irq BURST_IRQ                       ; send a 562.5us burst to end the data bit
+
+jmp !OSRE data_bit                      ; continue sending bits until the OSR is empty
+
+.wrap                                   ; fetch another data word from the FIFO
+
+
+% c-sdk {
+static inline void nec_carrier_control_program_init (PIO pio, uint sm, uint offset, float tick_rate, int bits_per_frame) {
+
+    // create a new state machine configuration
+    //
+    pio_sm_config c = nec_carrier_control_program_get_default_config(offset);
+
+    // configure the output shift register
+    //
+    sm_config_set_out_shift (&c,
+                             true,       // shift right
+                             false,      // disable autopull
+                             bits_per_frame);
+
+    // join the FIFOs to make a single large transmit FIFO
+    //
+    sm_config_set_fifo_join (&c, PIO_FIFO_JOIN_TX);
+
+    // configure the clock divider
+    //
+    float div = clock_get_hz (clk_sys) / tick_rate;
+    sm_config_set_clkdiv (&c, div);
+
+    // apply the configuration to the state machine
+    //
+    pio_sm_init(pio, sm, offset, &c);
+
+    // set the state machine running
+    //
+    pio_sm_set_enabled(pio, sm, true);
+}
+%}

pio/ir_nec/nec_transmit_library/nec_transmit.c

@@ -0,0 +1,78 @@
+/**
+ * Copyright (c) 2021 mjcross
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+
+// SDK types and declarations
+//
+#include "pico/stdlib.h"
+#include "hardware/pio.h"
+#include "hardware/clocks.h"    // for clock_get_hz()
+#include "nec_transmit.h"
+
+// import the assembled PIO state machine programs
+#include "nec_carrier_burst.pio.h"
+#include "nec_carrier_control.pio.h"
+
+// Claim an unused state machine on the specified PIO and configure it
+// to transmit NEC IR frames on the specificied GPIO pin.
+//
+// Returns: on success, the number of the carrier_control state machine
+// otherwise -1
+int nec_tx_init(PIO pio, uint pin_num) {
+
+    // install the carrier_burst program in the PIO shared instruction space
+    uint carrier_burst_offset;
+    if (pio_can_add_program(pio, &nec_carrier_burst_program)) {
+        carrier_burst_offset = pio_add_program(pio, &nec_carrier_burst_program);
+    } else {
+        return -1;
+    }
+
+    // claim an unused state machine on this PIO
+    int carrier_burst_sm = pio_claim_unused_sm(pio, true);
+    if (carrier_burst_sm == -1) {
+        return -1;
+    }
+
+    // configure and enable the state machine
+    nec_carrier_burst_program_init(pio,
+                                   carrier_burst_sm,
+                                   carrier_burst_offset,
+                                   pin_num,
+                                   38.222e3);                   // 38.222 kHz carrier
+
+    // install the carrier_control program in the PIO shared instruction space
+    uint carrier_control_offset;
+    if (pio_can_add_program(pio, &nec_carrier_control_program)) {
+        carrier_control_offset = pio_add_program(pio, &nec_carrier_control_program);
+    } else {
+        return -1;
+    }
+
+    // claim an unused state machine on this PIO
+    int carrier_control_sm = pio_claim_unused_sm(pio, true);
+    if (carrier_control_sm == -1) {
+        return -1;
+    }
+
+    // configure and enable the state machine
+    nec_carrier_control_program_init(pio,
+                                     carrier_control_sm,
+                                     carrier_control_offset,
+                                     2 * (1 / 562.5e-6f),        // 2 ticks per 562.5us carrier burst
+                                     32);                       // 32 bits per frame
+
+    return carrier_control_sm;
+}
+
+
+// Create a frame in `NEC` format from the provided 8-bit address and data
+//
+// Returns: a 32-bit encoded frame
+uint32_t nec_encode_frame(uint8_t address, uint8_t data) {
+    // a normal 32-bit frame is encoded as address, inverted address, data, inverse data,
+    return address | (address ^ 0xff) << 8 | data << 16 | (data ^ 0xff) << 24;
+}

pio/ir_nec/nec_transmit_library/nec_transmit.h

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2021 mjcross
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include "pico/stdlib.h"
+#include "hardware/pio.h"
+
+// public API
+
+int nec_tx_init(PIO pio, uint pin);
+uint32_t nec_encode_frame(uint8_t address, uint8_t data);

pio/pio_blink/blink.c

@@ -31,5 +31,5 @@ void blink_pin_forever(PIO pio, uint sm, uint offset, uint pin, uint freq) {
     pio_sm_set_enabled(pio, sm, true);
 
     printf("Blinking pin %d at %d Hz\n", pin, freq);
-    pio->txf[sm] = clock_get_hz(clk_sys) / 2 * freq;
+    pio->txf[sm] = clock_get_hz(clk_sys) / (2 * freq);
 }

pio/quadrature_encoder/CMakeLists.txt

@@ -0,0 +1,18 @@
+add_executable(pio_quadrature_encoder)
+
+pico_generate_pio_header(pio_quadrature_encoder ${CMAKE_CURRENT_LIST_DIR}/quadrature_encoder.pio)
+
+target_sources(pio_quadrature_encoder PRIVATE quadrature_encoder.c)
+
+target_link_libraries(pio_quadrature_encoder PRIVATE
+        pico_stdlib
+        pico_multicore
+        hardware_pio
+        )
+
+pico_enable_stdio_usb(pio_quadrature_encoder 1)
+
+pico_add_extra_outputs(pio_quadrature_encoder)
+
+# add url via pico_set_program_url
+example_auto_set_url(pio_quadrature_encoder)

pio/quadrature_encoder/quadrature_encoder.c

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) 2021 pmarques-dev @ github
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#include <stdio.h>
+#include "pico/stdlib.h"
+#include "hardware/pio.h"
+#include "hardware/timer.h"
+
+#include "quadrature_encoder.pio.h"
+
+//
+// ---- quadrature encoder interface example
+//
+// the PIO program reads phase A/B of a quadrature encoder and increments or
+// decrements an internal counter to keep the current absolute step count
+// updated. At any point, the main code can query the current count by using
+// the quadrature_encoder_*_count functions. The counter is kept in a full
+// 32 bit register that just wraps around. Two's complement arithmetic means
+// that it can be interpreted as a 32-bit signed or unsigned value, and it will
+// work anyway.
+//
+// As an example, a two wheel robot being controlled at 100Hz, can use two
+// state machines to read the two encoders and in the main control loop it can
+// simply ask for the current encoder counts to get the absolute step count. It
+// can also subtract the values from the last sample to check how many steps
+// each wheel as done since the last sample period.
+//
+// One advantage of this approach is that it requires zero CPU time to keep the
+// encoder count updated and because of that it supports very high step rates.
+//
+
+int main() {
+    int new_value, delta, old_value = 0;
+
+    // Base pin to connect the A phase of the encoder.
+    // The B phase must be connected to the next pin
+    const uint PIN_AB = 10;
+
+    stdio_init_all();
+
+    PIO pio = pio0;
+    const uint sm = 0;
+
+    uint offset = pio_add_program(pio, &quadrature_encoder_program);
+    quadrature_encoder_program_init(pio, sm, offset, PIN_AB, 0);
+
+    while (1) {
+        // note: thanks to two's complement arithmetic delta will always
+        // be correct even when new_value wraps around MAXINT / MININT
+        new_value = quadrature_encoder_get_count(pio, sm);
+        delta = new_value - old_value;
+        old_value = new_value;
+
+        printf("position %8d, delta %6d\n", new_value, delta);
+        sleep_ms(100);
+    }
+}
+

pio/quadrature_encoder/quadrature_encoder.pio

@@ -0,0 +1,165 @@
+;
+; Copyright (c) 2021 pmarques-dev @ github
+;
+; SPDX-License-Identifier: BSD-3-Clause
+;
+
+.program quadrature_encoder
+
+; this code must be loaded into address 0, but at 29 instructions, it probably
+; wouldn't be able to share space with other programs anyway
+.origin 0
+
+
+; the code works by running a loop that continuously shifts the 2 phase pins into
+; ISR and looks at the lower 4 bits to do a computed jump to an instruction that
+; does the proper "do nothing" | "increment" | "decrement" action for that pin
+; state change (or no change)
+
+; ISR holds the last state of the 2 pins during most of the code. The Y register
+; keeps the current encoder count and is incremented / decremented according to
+; the steps sampled
+
+; writing any non zero value to the TX FIFO makes the state machine push the
+; current count to RX FIFO between 6 to 18 clocks afterwards. The worst case
+; sampling loop takes 14 cycles, so this program is able to read step rates up
+; to sysclk / 14  (e.g., sysclk 125MHz, max step rate = 8.9 Msteps/sec)
+
+
+; 00 state
+	JMP update	; read 00
+	JMP decrement	; read 01
+	JMP increment	; read 10
+	JMP update	; read 11
+
+; 01 state
+	JMP increment	; read 00
+	JMP update	; read 01
+	JMP update	; read 10
+	JMP decrement	; read 11
+
+; 10 state
+	JMP decrement	; read 00
+	JMP update	; read 01
+	JMP update	; read 10
+	JMP increment	; read 11
+
+; to reduce code size, the last 2 states are implemented in place and become the
+; target for the other jumps
+
+; 11 state
+	JMP update	; read 00
+	JMP increment	; read 01
+decrement:
+	; note: the target of this instruction must be the next address, so that
+	; the effect of the instruction does not depend on the value of Y. The
+	; same is true for the "JMP X--" below. Basically "JMP Y--, <next addr>"
+	; is just a pure "decrement Y" instruction, with no other side effects
+	JMP Y--, update	; read 10
+
+	; this is where the main loop starts
+.wrap_target
+update:
+	; we start by checking the TX FIFO to see if the main code is asking for
+	; the current count after the PULL noblock, OSR will have either 0 if
+	; there was nothing or the value that was there
+	SET X, 0
+	PULL noblock
+
+	; since there are not many free registers, and PULL is done into OSR, we
+	; have to do some juggling to avoid losing the state information and
+	; still place the values where we need them
+	MOV X, OSR
+	MOV OSR, ISR
+
+	; the main code did not ask for the count, so just go to "sample_pins"
+	JMP !X, sample_pins
+
+	; if it did ask for the count, then we push it
+	MOV ISR, Y	; we trash ISR, but we already have a copy in OSR
+	PUSH
+
+sample_pins:
+	; we shift into ISR the last state of the 2 input pins (now in OSR) and
+	; the new state of the 2 pins, thus producing the 4 bit target for the
+	; computed jump into the correct action for this state
+	MOV ISR, NULL
+	IN OSR, 2
+	IN PINS, 2
+	MOV PC, ISR
+
+	; the PIO does not have a increment instruction, so to do that we do a
+	; negate, decrement, negate sequence
+increment:
+	MOV X, !Y
+	JMP X--, increment_cont
+increment_cont:
+	MOV Y, !X
+.wrap	; the .wrap here avoids one jump instruction and saves a cycle too
+
+
+
+% c-sdk {
+
+#include "hardware/clocks.h"
+#include "hardware/gpio.h"
+
+// max_step_rate is used to lower the clock of the state machine to save power
+// if the application doesn't require a very high sampling rate. Passing zero
+// will set the clock to the maximum, which gives a max step rate of around
+// 8.9 Msteps/sec at 125MHz
+
+static inline void quadrature_encoder_program_init(PIO pio, uint sm, uint offset, uint pin, int max_step_rate)
+{
+	pio_sm_set_consecutive_pindirs(pio, sm, pin, 2, false);
+	pio_gpio_init(pio, pin);
+	gpio_pull_up(pin);
+
+	pio_sm_config c = quadrature_encoder_program_get_default_config(offset);
+	sm_config_set_in_pins(&c, pin); // for WAIT, IN
+	sm_config_set_jmp_pin(&c, pin); // for JMP
+	// shift to left, autopull disabled
+	sm_config_set_in_shift(&c, false, false, 32);
+	// don't join FIFO's
+	sm_config_set_fifo_join(&c, PIO_FIFO_JOIN_NONE);
+
+	// passing "0" as the sample frequency,
+	if (max_step_rate == 0) {
+		sm_config_set_clkdiv(&c, 1.0);
+	} else {
+		// one state machine loop takes at most 14 cycles
+		float div = (float)clock_get_hz(clk_sys) / (14 * max_step_rate);
+		sm_config_set_clkdiv(&c, div);
+	}
+
+	pio_sm_init(pio, sm, offset, &c);
+	pio_sm_set_enabled(pio, sm, true);
+}
+
+
+// When requesting the current count we may have to wait a few cycles (average
+// ~11 sysclk cycles) for the state machine to reply. If we are reading multiple
+// encoders, we may request them all in one go and then fetch them all, thus
+// avoiding doing the wait multiple times. If we are reading just one encoder,
+// we can use the "get_count" function to request and wait
+
+static inline void quadrature_encoder_request_count(PIO pio, uint sm)
+{
+	pio->txf[sm] = 1;
+}
+
+static inline int32_t quadrature_encoder_fetch_count(PIO pio, uint sm)
+{
+	while (pio_sm_is_rx_fifo_empty(pio, sm))
+		tight_loop_contents();
+	return pio->rxf[sm];
+}
+
+static inline int32_t quadrature_encoder_get_count(PIO pio, uint sm)
+{
+	quadrature_encoder_request_count(pio, sm);
+	return quadrature_encoder_fetch_count(pio, sm);
+}
+
+%}
+

pio/squarewave/generated/squarewave.pio.h

@@ -2,6 +2,8 @@
 // This file is autogenerated by pioasm; do not edit! //
 // -------------------------------------------------- //
 
+#pragma once
+
 #if !PICO_NO_HARDWARE
 #include "hardware/pio.h"
 #endif

pio/squarewave/generated/squarewave_wrap.pio.h

@@ -2,6 +2,8 @@
 // This file is autogenerated by pioasm; do not edit! //
 // -------------------------------------------------- //
 
+#pragma once
+
 #if !PICO_NO_HARDWARE
 #include "hardware/pio.h"
 #endif

pio/uart_rx/uart_rx.pio

@@ -71,7 +71,7 @@ static inline void uart_rx_program_init(PIO pio, uint sm, uint offset, uint pin,
     pio_sm_config c = uart_rx_program_get_default_config(offset);
     sm_config_set_in_pins(&c, pin); // for WAIT, IN
     sm_config_set_jmp_pin(&c, pin); // for JMP
-    // Shift to right, autopull disabled
+    // Shift to right, autopush disabled
     sm_config_set_in_shift(&c, true, false, 32);
     // Deeper FIFO as we're not doing any TX
     sm_config_set_fifo_join(&c, PIO_FIFO_JOIN_RX);

pio/ws2812/generated/ws2812.pio.h

@@ -2,6 +2,8 @@
 // This file is autogenerated by pioasm; do not edit! //
 // -------------------------------------------------- //
 
+#pragma once
+
 #if !PICO_NO_HARDWARE
 #include "hardware/pio.h"
 #endif

pio/ws2812/ws2812.c

@@ -12,6 +12,16 @@
 #include "hardware/clocks.h"
 #include "ws2812.pio.h"
 
+#define IS_RGBW true
+#define NUM_PIXELS 150
+
+#ifdef PICO_DEFAULT_WS2812_PIN
+#define WS2812_PIN PICO_DEFAULT_WS2812_PIN
+#else
+// default to pin 2 if the board doesn't have a default WS2812 pin defined
+#define WS2812_PIN 2
+#endif
+
 static inline void put_pixel(uint32_t pixel_grb) {
     pio_sm_put_blocking(pio0, 0, pixel_grb << 8u);
 }
@@ -71,19 +81,17 @@ const struct {
         {pattern_greys,   "Greys"},
 };
 
-const int PIN_TX = 0;
-
 int main() {
     //set_sys_clock_48();
     stdio_init_all();
-    puts("WS2812 Smoke Test");
+    printf("WS2812 Smoke Test, using pin %d", WS2812_PIN);
 
     // todo get free sm
     PIO pio = pio0;
     int sm = 0;
     uint offset = pio_add_program(pio, &ws2812_program);
 
-    ws2812_program_init(pio, sm, offset, PIN_TX, 800000, true);
+    ws2812_program_init(pio, sm, offset, WS2812_PIN, 800000, IS_RGBW);
 
     int t = 0;
     while (1) {
@@ -92,9 +100,9 @@ int main() {
         puts(pattern_table[pat].name);
         puts(dir == 1 ? "(forward)" : "(backward)");
         for (int i = 0; i < 1000; ++i) {
-            pattern_table[pat].pat(150, t);
+            pattern_table[pat].pat(NUM_PIXELS, t);
             sleep_ms(10);
             t += dir;
         }
     }
-}
+}

pio/ws2812/ws2812_parallel.c

@@ -16,7 +16,8 @@
 #include "ws2812.pio.h"
 
 #define FRAC_BITS 4
-#define PIN_TX 0
+#define NUM_PIXELS 64
+#define WS2812_PIN_BASE 2
 
 // horrible temporary hack to avoid changing pattern code
 static uint8_t *current_string_out;
@@ -174,17 +175,15 @@ void dither_values(const value_bits_t *colors, value_bits_t *state, const value_
     }
 }
 
-#define MAX_LENGTH 100
-
-// requested colors * 4 to allow for WRGB
-static value_bits_t colors[MAX_LENGTH * 4];
+// requested colors * 4 to allow for RGBW
+static value_bits_t colors[NUM_PIXELS * 4];
 // double buffer the state of the string, since we update next version in parallel with DMAing out old version
-static value_bits_t states[2][MAX_LENGTH * 4];
+static value_bits_t states[2][NUM_PIXELS * 4];
 
 // example - string 0 is RGB only
-static uint8_t string0_data[MAX_LENGTH * 3];
-// example - string 1 is WRGB
-static uint8_t string1_data[MAX_LENGTH * 4];
+static uint8_t string0_data[NUM_PIXELS * 3];
+// example - string 1 is RGBW
+static uint8_t string1_data[NUM_PIXELS * 4];
 
 string_t string0 = {
         .data = string0_data,
@@ -213,7 +212,7 @@ string_t *strings[] = {
 #define DMA_CHANNELS_MASK (DMA_CHANNEL_MASK | DMA_CB_CHANNEL_MASK)
 
 // start of each value fragment (+1 for NULL terminator)
-static uintptr_t fragment_start[MAX_LENGTH * 4 + 1];
+static uintptr_t fragment_start[NUM_PIXELS * 4 + 1];
 
 // posted when it is safe to output a new set of values
 static struct semaphore reset_delay_complete_sem;
@@ -286,7 +285,7 @@ int main() {
     int sm = 0;
     uint offset = pio_add_program(pio, &ws2812_parallel_program);
 
-    ws2812_parallel_program_init(pio, sm, offset, PIN_TX, count_of(strings), 800000);
+    ws2812_parallel_program_init(pio, sm, offset, WS2812_PIN_BASE, count_of(strings), 800000);
 
     sem_init(&reset_delay_complete_sem, 1, 1); // initially posted so we don't block first time
     dma_init(pio, sm);
@@ -300,19 +299,17 @@ int main() {
         int brightness = 0;
         uint current = 0;
         for (int i = 0; i < 1000; ++i) {
-            int n = 64;
-
             current_string_out = string0.data;
             current_string_4color = false;
-            pattern_table[pat].pat(n, t);
+            pattern_table[pat].pat(NUM_PIXELS, t);
             current_string_out = string1.data;
             current_string_4color = true;
-            pattern_table[pat].pat(n, t);
+            pattern_table[pat].pat(NUM_PIXELS, t);
 
-            transform_strings(strings, count_of(strings), colors, n * 4, brightness);
-            dither_values(colors, states[current], states[current ^ 1], n * 4);
+            transform_strings(strings, count_of(strings), colors, NUM_PIXELS * 4, brightness);
+            dither_values(colors, states[current], states[current ^ 1], NUM_PIXELS * 4);
             sem_acquire_blocking(&reset_delay_complete_sem);
-            output_strings_dma(states[current], n * 4);
+            output_strings_dma(states[current], NUM_PIXELS * 4);
 
             current ^= 1;
             t += dir;