TRANSMITTER.md

   1 # IR Transmitter
   2
   3 ##### [Main README](./README.md#1-ir-communication)
   4
   5 # 1. Hardware Requirements
   6
   7 The transmitter requires a Pyboard 1.x (not Lite), a Pyboard D or an ESP32.
   8 Output is via an IR LED which will need a transistor to provide sufficient
   9 current. Typically these need 50-100mA of drive to achieve reasonable range and
  10 data integrity. A suitable 940nm LED is [this one](https://www.adafruit.com/product/387).
  11
  12 On the Pyboard the transmitter test script assumes pin X1 for IR output. It can
  13 be changed, but it must support Timer 2 channel 1. Pins for pushbutton inputs
  14 are arbitrary: X3 and X4 are used. The driver uses timers 2 and 5.
  15
  16 On ESP32 pin 23 is used for IR output and pins 18 and 19 for pushbuttons. The
  17 ESP32 solution has limitations discussed in [section 5.2](./TRANSMITTER.md#52-esp32).
  18
  19 ## 1.1 Wiring
  20
  21 I use the following circuit which delivers just under 40mA to the diode. R2 may
  22 be reduced for higher current.
  23 ![Image](images/circuit.png)
  24
  25 This alternative delivers a constant current of about 53mA if a higher voltage
  26 than 5V is available. R4 determines the current value and may be reduced to
  27 increase power.
  28 ![Image](images/circuit2.png)
  29
  30 The transistor type is not critical.
  31
  32 The driver assumes circuits as shown. Here the carrier "off" state is 0V,
  33 which is the driver default. If using a circuit where "off" is required to be
  34 3.3V, the constant `_SPACE` in `ir_tx.__init__.py` should be changed to 100.
  35
  36 # 2. Installation
  37
  38 The transmitter is a Python package. This minimises RAM usage: applications
  39 only import the device driver for the protocol in use.
  40
  41 Copy the following to the target filesystem:
  42  1. `ir_tx` Directory and contents.
  43
  44 The device driver has no dependencies.
  45
  46 The demo program requires `uasyncio` from the official library and `aswitch.py`
  47 from [this repo](https://github.com/peterhinch/micropython-async). The demo is
  48 of a 2-button remote controller with auto-repeat. It may be run by issuing:
  49
  50 ```python
  51 from ir_tx.test import test
  52 ```
  53 Instructions will be displayed at the REPL.
  54
  55 # 3. The driver
  56
  57 This is specific to Pyboard D, Pyboard 1.x (not Lite) and ESP32.
  58
  59 It implements a class for each supported protocol, namely `NEC`, `SONY_12`,
  60 `SONY_15`, `SONY_20`, `RC5` and `RC6_M0`.  Each class is subclassed from a
  61 common abstract base class in `__init__.py`. The application instantiates the
  62 appropriate class and calls the `transmit` method to send data.
  63
  64 The ESP32 platform is marginal in this application because of imprecision in
  65 its timing. The Philips protocols are unsupported as they require unachievable
  66 levels of precision. Test results are discussed [here](./TRANSMITTER.md#52-esp32).
  67
  68 #### Common to all classes
  69
  70 Constructor args:
  71  1. `pin` A Pin instance instantiated as an output. On a Pyboard this is a
  72  `pyb.Pin` instance supporting Timer 2 channel 1: `X1` is employed by the test
  73  script. On ESP32 any `machine.Pin` may be used. Must be connected to the IR
  74  diode as described below.
  75  2. `freq=default` The carrier frequency in Hz. The default for NEC is 38000,
  76  Sony is 40000 and Philips is 36000.
  77  3. `verbose=False` If `True` emits (a lot of) debug output.
  78
  79 Method:
  80  1. `transmit(addr, data, toggle=0)` Integer args. `addr` and `data` are
  81  normally 8-bit values and `toggle` is normally 0 or 1; details are protocol
  82  dependent and are described below.
  83
  84 The `transmit` method is synchronous with rapid return. Actual transmission
  85 occurs as a background process, on the Pyboard controlled by timers 2 and 5.
  86 Execution times on a Pyboard 1.1 were 3.3ms for NEC, 1.5ms for RC5 and 2ms
  87 for RC6.
  88
  89 #### NEC class
  90
  91 This has an additional method `.repeat` (no args). This causes a repeat code to
  92 be transmitted. Should be called every 108ms if a button is held down.
  93
  94 The NEC protocol accepts 8 or 16 bit addresses. In the former case, a 16 bit
  95 value is transmitted comprising the 8 bit address and its one's complement,
  96 enabling the receiver to perform a simple error check. The `NEC` class supports
  97 these modes by checking the value of `addr` passed to `.transmit` and sending
  98 the complement for values < 256.
  99
 100 A value passed in `toggle` is ignored.
 101
 102 #### Sony classes
 103
 104 The SIRC protocol supports three sizes, supported by the following classes:
 105  1. 12 bit (7 data, 5 address) `SONY_12`
 106  2. 15 bit (7 data, 8 address) `SONY_15`
 107  3. 20 bit (7 data, 5 addresss, 8 extended) `SONY_20`
 108
 109 The `.transmit` method masks `addr` and `data` values to the widths listed
 110 above. `toggle` is ignored except by `SONY_20` which treats it as the extended
 111 value.
 112
 113 #### Philips classes
 114
 115 These are only supported on Pyboard hosts. An `RuntimeError` will be thrown on
 116 an attempt to instantiate a Philips class on an ESP32.
 117
 118 The RC-5 protocol supports a 5 bit address and 6 or 7 bit (RC5X) data. The
 119 driver uses the appropriate mode depending on the `data` value provided.
 120
 121 The RC-6 protocol accepts 8 bit address and data values.
 122
 123 Both send a `toggle` bit which remains constant if a button is held down, but
 124 changes when the button is released. The application should implement this
 125 behaviour, setting the `toggle` arg of `.transmit` to 0 or 1 as required.
 126
 127 # 4. Test results
 128
 129 # 5. Principle of operation
 130
 131 ## 5.1 Pyboard
 132
 133 The classes inherit from the abstract base class `IR`. This has an array `.arr`
 134 to contain the duration (in μs) of each carrier on or off period. The
 135 `transmit` method calls a `tx` method of the subclass which populates this
 136 array. This is done by two methods of the base class, `.append` and `.add`. The
 137 former takes a list of times (in μs) and appends them to the array. A bound
 138 variable `.carrier` keeps track of the notional on/off state of the carrier:
 139 this is required for bi-phase (manchester) codings.
 140
 141 The `.add` method takes a single μs time value and adds it to the last value
 142 in the array: this pulse lengthening is used in bi-phase encodings.
 143
 144 On completion of the subclass `.tx`, `.transmit` appends a special `STOP` value
 145 and initiates physical transmission which occurs in an interrupt context.
 146
 147 This is performed by two hardware timers initiated in the constructor. Timer 2,
 148 channel 1 is used to configure the output pin as a PWM channel. Its frequency
 149 is set in the constructor. The OOK is performed by dynamically changing the
 150 duty ratio using the timer channel's `pulse_width_percent` method: this varies
 151 the pulse width from 0 to a duty ratio passed to the constructor. The NEC
 152 protocol defaults to 50%, the Sony and Philips ones to 30%.
 153
 154 The duty ratio is changed by the Timer 5 callback `._cb`. This retrieves the
 155 next duration from the array. If it is not `STOP` it toggles the duty cycle
 156 and re-initialises T5 for the new duration.
 157
 158 ## 5.2 ESP32
 159
 160 This is something of a hack because my drivers work with standard firmware.
 161
 162 A much better solution will be possible when the `esp32.RMT` class supports the
 163 `carrier` option. A fork supporting this is
 164 [here](https://github.com/mattytrentini/micropython). You may want to adapt the
 165 base class to use this fork: it should be easy and would produce a solution
 166 capable of handling all protocols.
 167
 168 A consequence of this hack is that timing is imprecise. In testing NEC
 169 protocols were reliable. Sony delivered some erroneous bitsreams but may be
 170 usable. Philips protocols require timing precision which is unachievable; these
 171 are unsupported.
 172
 173 The ABC stores durations in Hz rather than in μs. This is because the `period`
 174 arg of `Timer.init` expects an integer number of ms. Passing a `freq` value
 175 enables slightly higher resolution timing. In practice timing lacks precision
 176 with the code having a hack which subtracts a nominal amount from each value to
 177 compensate for the typical level of overrun.
 178
 179 The carrier is generated by PWM instance `.pwm` with its duty cycle controlled
 180 by software timer `._tim` in a similar way to the Pyboard Timer 5 described
 181 above. The ESP32 duty value is in range 0-1023 as against 0-100 on the Pyboard.
 182
 183 # 6. References
 184
 185 [General information about IR](https://www.sbprojects.net/knowledge/ir/)
 186
 187 The NEC protocol:
 188 [altium](http://techdocs.altium.com/display/FPGA/NEC+Infrared+Transmission+Protocol)
 189 [circuitvalley](http://www.circuitvalley.com/2013/09/nec-protocol-ir-infrared-remote-control.html)
 190
 191 Philips protocols:
 192 [RC5](https://en.wikipedia.org/wiki/RC-5)
 193 [RC5](https://www.sbprojects.net/knowledge/ir/rc5.php)
 194 [RC6](https://www.sbprojects.net/knowledge/ir/rc6.php)
 195
 196 Sony protocol:
 197 [SIRC](https://www.sbprojects.net/knowledge/ir/sirc.php)