Add pio/ir_nec

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);
+}
+%}