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 needs a simple circuit 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 the demo uses pins 21 and 23 for IR output and pins 18 and 19 for
  17 pushbuttons. These pins may be changed.
  18
  19 ## 1.1 Pyboard 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 ## 1.2 ESP32 Wiring
  37
  38 The ESP32 RMT device does not currently support the carrier option. A simple
  39 hardware gate is required to turn the IR LED on when both the carrier pin and
  40 the RMT pin are high. A suitable circuit is below.
  41 ![Image](images/gate.png)
  42
  43 The transistor type is not critical.
  44
  45 # 2. Dependencies and installation
  46
  47 ## 2.1 Dependencies
  48
  49 The device driver has no dependencies.
  50
  51 On ESP32 a firmware version >= V1.12 is required. The Loboris port is not
  52 supported owing to the need for the RMT device.
  53
  54 The demo program requires `uasyncio` from the official library and `aswitch.py`
  55 from [this repo](https://github.com/peterhinch/micropython-async).
  56
  57 ## 2.2 Installation
  58
  59 The transmitter is a Python package. This minimises RAM usage: applications
  60 only import the device driver for the protocol in use.
  61
  62 Copy the following to the target filesystem:
  63  1. `ir_tx` Directory and contents.
  64
  65 The demo is of a 2-button remote controller with auto-repeat. It may be run by
  66 issuing:
  67 ```python
  68 from ir_tx.test import test
  69 ```
  70 Instructions will be displayed at the REPL.
  71
  72 # 3. The driver
  73
  74 This is specific to Pyboard D, Pyboard 1.x (not Lite) and ESP32.
  75
  76 It implements a class for each supported protocol, namely `NEC`, `SONY_12`,
  77 `SONY_15`, `SONY_20`, `RC5` and `RC6_M0`.  Each class is subclassed from a
  78 common abstract base class in `__init__.py`. The application instantiates the
  79 appropriate class and calls the `transmit` method to send data.
  80
  81 #### Common to all classes
  82
  83 Constructor args:
  84  1. `pin` A Pin instance instantiated as an output. On a Pyboard this is a
  85  `pyb.Pin` instance supporting Timer 2 channel 1: `X1` is employed by the test
  86  script. On ESP32 any `machine.Pin` may be used. Must be connected to the IR
  87  diode as described below.
  88  2. `freq=default` The carrier frequency in Hz. The default for NEC is 38000,
  89  Sony is 40000 and Philips is 36000.
  90  3. `verbose=False` If `True` emits (a lot of) debug output.
  91
  92 Method:
  93  1. `transmit(addr, data, toggle=0)` Integer args. `addr` and `data` are
  94  normally 8-bit values and `toggle` is normally 0 or 1; details are protocol
  95  dependent and are described below.
  96
  97 The `transmit` method is synchronous with rapid return. Actual transmission
  98 occurs as a background process, on the Pyboard controlled by timers 2 and 5.
  99 Execution times on a Pyboard 1.1 were 3.3ms for NEC, 1.5ms for RC5 and 2ms
 100 for RC6.
 101
 102 #### NEC class
 103
 104 This has an additional method `.repeat` (no args). This causes a repeat code to
 105 be transmitted. Should be called every 108ms if a button is held down.
 106
 107 The NEC protocol accepts 8 or 16 bit addresses. In the former case, a 16 bit
 108 value is transmitted comprising the 8 bit address and its one's complement,
 109 enabling the receiver to perform a simple error check. The `NEC` class supports
 110 these modes by checking the value of `addr` passed to `.transmit` and sending
 111 the complement for values < 256.
 112
 113 A value passed in `toggle` is ignored.
 114
 115 #### Sony classes
 116
 117 The SIRC protocol supports three sizes, supported by the following classes:
 118  1. 12 bit (7 data, 5 address) `SONY_12`
 119  2. 15 bit (7 data, 8 address) `SONY_15`
 120  3. 20 bit (7 data, 5 addresss, 8 extended) `SONY_20`
 121
 122 The `.transmit` method masks `addr` and `data` values to the widths listed
 123 above. `toggle` is ignored except by `SONY_20` which treats it as the extended
 124 value.
 125
 126 #### Philips classes
 127
 128 The RC-5 protocol supports a 5 bit address and 6 or 7 bit (RC5X) data. The
 129 driver uses the appropriate mode depending on the `data` value provided.
 130
 131 The RC-6 protocol accepts 8 bit address and data values.
 132
 133 Both send a `toggle` bit which remains constant if a button is held down, but
 134 changes when the button is released. The application should implement this
 135 behaviour, setting the `toggle` arg of `.transmit` to 0 or 1 as required.
 136
 137 # 4. Principle of operation
 138
 139 ## 4.1 Pyboard
 140
 141 The classes inherit from the abstract base class `IR`. This has an array `.arr`
 142 to contain the duration (in μs) of each carrier on or off period. The
 143 `transmit` method calls a `tx` method of the subclass which populates this
 144 array. This is done by two methods of the base class, `.append` and `.add`. The
 145 former takes a list of times (in ) and appends them to the array. A bound
 146 variable `.carrier` keeps track of the notional on/off state of the carrier:
 147 this is required for bi-phase (manchester) codings.
 148
 149 The `.add` method takes a single μs time value and adds it to the last value
 150 in the array: this pulse lengthening is used in bi-phase encodings.
 151
 152 On completion of the subclass `.tx`, `.transmit` appends a special `STOP` value
 153 and initiates physical transmission which occurs in an interrupt context.
 154
 155 This is performed by two hardware timers initiated in the constructor. Timer 2,
 156 channel 1 is used to configure the output pin as a PWM channel. Its frequency
 157 is set in the constructor. The OOK is performed by dynamically changing the
 158 duty ratio using the timer channel's `pulse_width_percent` method: this varies
 159 the pulse width from 0 to a duty ratio passed to the constructor. The NEC
 160 protocol defaults to 50%, the Sony and Philips ones to 30%.
 161
 162 The duty ratio is changed by the Timer 5 callback `._cb`. This retrieves the
 163 next duration from the array. If it is not `STOP` it toggles the duty cycle
 164 and re-initialises T5 for the new duration.
 165
 166 ## 4.2 ESP32
 167
 168 The carrier is output continuously at the specified duty ratio. A pulse train
 169 generated by the RMT instance drives a hardware gate such that the IR LED is
 170 lit only when both carrier and RMT are high.
 171
 172 The carrier is generated by PWM instance `.pwm` running continuously. The ABC
 173 constructor converts the 0-100 duty ratio specified by the subclass to the
 174 0-1023 range used by ESP32.
 175
 176 # 5. References
 177
 178 [General information about IR](https://www.sbprojects.net/knowledge/ir/)
 179
 180 The NEC protocol:
 181 [altium](http://techdocs.altium.com/display/FPGA/NEC+Infrared+Transmission+Protocol)
 182 [circuitvalley](http://www.circuitvalley.com/2013/09/nec-protocol-ir-infrared-remote-control.html)
 183
 184 Philips protocols:
 185 [RC5](https://en.wikipedia.org/wiki/RC-5)
 186 [RC5](https://www.sbprojects.net/knowledge/ir/rc5.php)
 187 [RC6](https://www.sbprojects.net/knowledge/ir/rc6.php)
 188
 189 Sony protocol:
 190 [SIRC](https://www.sbprojects.net/knowledge/ir/sirc.php)