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