README.md

   1 # Device drivers for IR (infra red) remote controls
   2
   3 This repo provides a driver to receive from IR (infra red) remote controls and
   4 a driver for IR "blaster" apps. The device drivers are nonblocking. They do not
   5 require `uasyncio` but are entirely compatible with it.
   6
   7 IR communication uses a carrier frequency to pulse the IR source. Modulation
   8 takes the form of OOK (on-off keying). There are a several mutually
   9 incompatible protocols and at least two options for carrier frequency, namely
  10 36KHz and 38KHz.
  11
  12 The drivers support the NEC protocol and two Philips protocols, namely RC-5 and
  13 RC-6 mode 0. In the case of the transmitter the carrier frequency is a runtime
  14 parameter so any value may be used. The receiver uses a hardware demodulator
  15 which must be specified for the correct frequency. The device driver is carrier
  16 frequency agnostic.
  17
  18 # Hardware Requirements
  19
  20 The receiver is cross-platform. It requires an IR receiver chip to demodulate
  21 the carrier. There are two options for carrier frequency: 36KHz and 38KHz. The
  22 chip must be selected for the frequency in use by the remote.
  23
  24 The transmitter requires a Pyboard 1.x (not Lite) or a Pyboard D. Output is via
  25 an IR LED which will normally need a transistor to provide sufficient current.
  26
  27 # Decoder for IR Remote Controls using the NEC protocol
  28
  29 This protocol is widely used. An example remote is [this one](https://www.adafruit.com/products/389).
  30 To interface the device a receiver chip such as the Vishay TSOP4838 or the
  31 [adafruit one](https://www.adafruit.com/products/157) is required. This
  32 demodulates the 38KHz IR pulses and passes the demodulated pulse train to the
  33 microcontroller.
  34
  35 The driver and test programs run on the Pyboard and ESP8266.
  36
  37 # Files
  38
  39  1. `aremote.py` The device driver.
  40  2. `art.py` A test program to characterise a remote.
  41  3. `art1.py` Control an onboard LED using a remote. The data and addresss
  42  values need changing to match your characterised remote.
  43
  44 # Dependencies
  45
  46 The driver requires the `uasyncio` library and the file `asyn.py` from this
  47 repository.
  48
  49 # Usage
  50
  51 The pin used to connect the decoder chip to the target is arbitrary but the
  52 test programs assume pin X3 on the Pyboard and pin 13 on the ESP8266.
  53
  54 The driver is event driven. Pressing a button on the remote causes a user
  55 defined callback to be run. The NEC protocol returns a data value and an
  56 address. These are passed to the callback as the first two arguments (further
  57 user defined arguments may be supplied). The address is normally constant for a
  58 given remote, with the data corresponding to the button. Applications should
  59 check the address to ensure that they only respond to the correct remote.
  60
  61 Data values are 8 bit. Addresses may be 8 or 16 bit depending on whether the
  62 remote uses extended addressing.
  63
  64 If a button is held down a repeat code is sent. In this event the driver
  65 returns a data value of `REPEAT` and the address associated with the last
  66 valid data block.
  67
  68 To characterise a remote run `art.py` and note the data value for each button
  69 which is to be used. If the address is less than 256, extended addressing is
  70 not in use.
  71
  72 # Reliability
  73
  74 IR reception is inevitably subject to errors, notably if the remote is operated
  75 near the limit of its range, if it is not pointed at the receiver or if its
  76 batteries are low. So applications must check for, and usually ignore, errors.
  77 These are flagged by data values < `REPEAT`.
  78
  79 On the ESP8266 there is a further source of errors. This results from the large
  80 and variable interrupt latency of the device which can exceed the pulse
  81 duration. This causes pulses to be missed. This tendency is slightly reduced by
  82 running the chip at 160MHz.
  83
  84 In general applications should provide user feedback of correct reception.
  85 Users tend to press the key again if no acknowledgement is received.
  86
  87 # The NEC_IR class
  88
  89 The constructor takes the following positional arguments.
  90
  91  1. `pin` A `Pin` instance for the decoder chip.
  92  2. `cb` The user callback function.
  93  3. `extended` Set `False` to enable extra error checking if the remote
  94  returns an 8 bit address.
  95  4. Further arguments, if provided, are passed to the callback.
  96
  97 The callback receives the following positional arguments:
  98
  99  1. The data value returned from the remote.
 100  2. The address value returned from the remote.
 101  3. Any further arguments provided to the `NEC_IR` constructor.
 102
 103 Negative data values are used to signal repeat codes and transmission errors.
 104
 105 The test program `art1.py` provides an example of a minimal application.
 106
 107 # How it works
 108
 109 The NEC protocol is described in these references.
 110 [altium](http://techdocs.altium.com/display/FPGA/NEC+Infrared+Transmission+Protocol)
 111 [circuitvalley](http://www.circuitvalley.com/2013/09/nec-protocol-ir-infrared-remote-control.html)
 112
 113 A normal burst comprises exactly 68 edges, the exception being a repeat code
 114 which has 4. An incorrect number of edges is treated as an error. All bursts
 115 begin with a 9ms pulse. In a normal code this is followed by a 4.5ms space; a
 116 repeat code is identified by a 2.25ms space. A data burst lasts for 67.5ms.
 117
 118 Data bits comprise a 562.5µs mark followed by a space whose length determines
 119 the bit value. 562.5µs denotes 0 and 1.6875ms denotes 1.
 120
 121 In 8 bit address mode the complement of the address and data values is sent to
 122 provide error checking. This also ensures that the number of 1's and 0's in a
 123 burst is constant, giving a constant burst length of 67.5ms. In extended
 124 address mode this constancy is lost. The burst length can (by my calculations)
 125 run to 76.5ms.
 126
 127 A pin interrupt records the time of every state change (in µs). The first
 128 interrupt in a burst sets an event, passing the time of the state change. A
 129 coroutine waits on the event, yields for the duration of a data burst, then
 130 decodes the stored data before calling the user-specified callback.
 131
 132 Passing the time to the `Event` instance enables the coro to compensate for
 133 any asyncio latency when setting its delay period.
 134
 135 The algorithm promotes interrupt handler speed over RAM use: the 276 bytes used
 136 for the data array could be reduced to 69 bytes by computing and saving deltas
 137 in the interrupt service routine.
 138
 139 # Error returns
 140
 141 Data values passed to the callback are normally positive. Negative values
 142 indicate a repeat code or an error.
 143
 144 `REPEAT` A repeat code was received.
 145
 146 Any data value < `REPEAT` denotes an error. In general applications do not
 147 need to decode these, but they may be of use in debugging. For completeness
 148 they are listed below.
 149
 150 `BADSTART` A short (<= 4ms) start pulse was received. May occur due to IR
 151 interference, e.g. from fluorescent lights. The TSOP4838 is prone to producing
 152 200µs pulses on occasion, especially when using the ESP8266.
 153 `BADBLOCK` A normal data block: too few edges received. Occurs on the ESP8266
 154 owing to high interrupt latency.
 155 `BADREP` A repeat block: an incorrect number of edges were received.
 156 `OVERRUN` A normal data block: too many edges received.
 157 `BADDATA` Data did not match check byte.
 158 `BADADDR` Where `extended` is `False` the 8-bit address is checked
 159 against the check byte. This code is returned on failure.