Add pio/ir_nec (#129)

Co-authored-by: martin <admin@crossleys.biz>

pio/CMakeLists.txt

@@ -6,6 +6,7 @@ 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)

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 | http://raspberrypi.org/
+| 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,67 @@
+/**
+ * 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,98 @@
+/**
+ * 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()
+
+
+// declare the public API functions
+//
+#include "nec_receive.h"
+
+
+// import the assembled PIO state machine program
+//
+#include "nec_receive.pio.h"
+
+
+// define the public API functions
+//
+
+// 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,7 @@
+#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,97 @@
+/**
+ * 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()
+
+
+// declare the public API functions
+//
+#include "nec_transmit.h"
+
+
+// import the assembled PIO state machine programs
+//
+#include "nec_carrier_burst.pio.h"
+#include "nec_carrier_control.pio.h"
+
+
+// define the public API functions
+//
+
+// 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-6),        // 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,7 @@
+#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);