RP2_RMT.md

   1 # 1. Pulse train ouput on RP2
   2
   3 The `RP2_RMT` class provides functionality similar to that of the ESP32 `RMT`
   4 class. It enables pulse trains to be output using a non-blocking driver. By
   5 default the train occurs once. Alternatively it can repeat a defned number of
   6 times, or can be repeated continuously.
   7
   8 The class was designed for my [IR blaster](https://github.com/peterhinch/micropython_ir)
   9 and [433MHz remote](https://github.com/peterhinch/micropython_remote)
  10 libraries. It supports an optional carrier frequency, where each high pulse can
  11 appear as a burst of a defined carrier frequency. The class can support both
  12 forms concurrently on a pair of pins: one pin produces pulses while a second
  13 produces carrier bursts.
  14
  15 Pulse trains are specified as arrays with each element being a duration in μs.
  16 Arrays may be of integers or half-words depending on the range of times to be
  17 covered. The duration of a "tick" is 1μs by default, but this can be changed.
  18
  19 # 2. The RP2_RMT class
  20
  21 ## 2.1 Constructor
  22
  23 This takes the following args:
  24  1. `pin_pulse=None` If an ouput `Pin` instance is provided, pulses will be
  25  output on it.
  26  2. `carrier=None` To output a carrier, a 3-tuple should be provided comprising
  27  `(pin, freq, duty)` where `pin` is an output pin instance, `freq` is the
  28  carrier frequency in Hz and `duty` is the duty ratio in %.
  29  3. `sm_no=0` State machine no.
  30  4. `sm_freq=1_000_000` Clock frequency for SM. Defines the unit for pulse
  31  durations.
  32
  33 ## 2.2 Methods
  34
  35 ### 2.2.1 send
  36
  37 This returns "immediately" with a pulse train being emitted as a background
  38 process. Args:
  39  1. `ar` A zero terminated array of pulse durations in μs. See notes below.
  40  2. `reps=1` No. of repetions. 0 indicates continuous output.
  41  3. `check=True` By default ensures that the pulse train ends in the inactive
  42  state.
  43
  44 In normal operation, between pulse trains, the pulse pin is low and the carrier
  45 is off. A pulse train ends when a 0 pulse width is encountered: this allows
  46 pulse trains to be shorter than the array length, for example where a
  47 pre-allocated array stores pulse trains of varying lengths. In RF transmitter
  48 applications ensuring the carrier is off between pulse trains may be a legal
  49 requirement, so by default the `send` method enforces this.
  50
  51 The first element of the array defines the duration of the first high going
  52 pulse, with the second being the duration of the first `off` period. If there
  53 are an even number of elements prior to the terminating 0, the signal will end
  54 in the `off` state. If the `check` arg is `True`, `.send()` will check for an
  55 odd number of elements; in this case it will overwrite the last element with 0
  56 to enforce a final `off` state.
  57
  58 This check may be skipped by setting `check=False`. This provides a means of
  59 inverting the normal sense of the driver: if the first pulse train has an odd
  60 number of elements and `check=False` the pin will be left high (and the carrier
  61 on). Subsequent normal pulsetrains will start and end in the high state.
  62
  63 ### 2.2.2 busy
  64
  65 No args. Returns `True` if a pulse train is being emitted.
  66
  67 ### 2.2.3 cancel
  68
  69 No args. If a pulse train is being emitted it will continue to the end but no
  70 further repetitions will take place.
  71
  72 # 3. Design
  73
  74 The class constructor installs one of two PIO scripts depending on whether a
  75 `pin_pulse` is specified. If it is, the `pulsetrain` script is loaded which
  76 drives the pin directly from the PIO. If no `pin_pulse` is required, the
  77 `irqtrain` script is loaded. Both scripts cause an IRQ to be raised at times
  78 when a pulse would start or end.
  79
  80 The `send` method loads the transmit FIFO with initial pulse durations and
  81 starts the state machine. The `._cb` ISR keeps the FIFO loaded with data until
  82 a 0 entry is encountered. It also turns the carrier on and off (using a PWM
  83 instance). This means that there is some latency between the pulse and the
  84 carrier. However latencies at start and end are effectively identical, so the
  85 duration of a carrier burst is correct.
  86
  87 # 4. Limitations
  88
  89 While the tick interval can be reduced to provide timing precision better than
  90 1μs, the design of this class will not support very high pulse repetition
  91 frequencies. This is because each pulse causes an interrupt: MicroPython is
  92 unable to support high IRQ rates.
  93 [This library](https://github.com/robert-hh/RP2040-Examples/tree/master/pulses)
  94 is more capable in this regard.