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 compatible with it, and are designed for standard
   6 firmware builds.
   7
   8 The receiver is cross platform and has been tested on Pyboard, ESP8266 and
   9 ESP32.
  10
  11 #### [Receiver docs](./RECEIVER.md)
  12
  13 The transmitter driver is compatible with Pyboard (1.x and D series) and ESP32.
  14 ESP8266 is unsupported; it seems incapable of generating the required signals.
  15
  16 #### [Transmitter docs](./TRANSMITTER.md)
  17
  18 # 1. IR communication
  19
  20 IR communication uses a carrier frequency to pulse the IR source. Modulation
  21 takes the form of OOK (on-off keying). There are multiple protocols and at
  22 least three options for carrier frequency: 36, 38 and 40KHz.
  23
  24 The drivers support NEC and Sony protocols plus two Philips protocols, namely
  25 RC-5 and RC-6 mode 0. In the case of the transmitter the carrier frequency is a
  26 runtime parameter: any value may be specified. The receiver uses a hardware
  27 demodulator which should be purchased for the correct frequency. The receiver
  28 device driver sees the demodulated signal and is hence carrier frequency
  29 agnostic.
  30
  31 Examining waveforms from various remote controls it is evident that numerous
  32 protocols exist. Some are doubtless proprietary and undocumented. The supported
  33 protocols are those for which I managed to locate documentation. My preference
  34 is for the NEC version. It has conservative timing and good provision for error
  35 detection. RC-5 has limited error detection, and RC-6 mode 0 has rather fast
  36 timing.
  37
  38 A remote using the NEC protocol is [this one](https://www.adafruit.com/products/389).
  39
  40 Remotes transmit an address and a data byte, plus in some cases an extra value.
  41 The address denotes the physical device being controlled. The data defines the
  42 button on the remote. Provision usually exists for differentiating between a
  43 button repeatedly pressed and one which is held down; the mechanism is protocol
  44 dependent.
  45
  46 # 2. Hardware Requirements
  47
  48 These are discussed in detail in the relevant docs; the following provides an
  49 overview.
  50
  51 The receiver is cross-platform. It requires an IR receiver chip to demodulate
  52 the carrier. The chip must be selected for the frequency in use by the remote.
  53 For 38KHz devices a receiver chip such as the Vishay TSOP4838 or the
  54 [adafruit one](https://www.adafruit.com/products/157) is required. This
  55 demodulates the 38KHz IR pulses and passes the demodulated pulse train to the
  56 microcontroller.
  57
  58 In my testing a 38KHz demodulator worked with 36KHz and 40KHz remotes, but this
  59 is obviously neither guaranteed nor optimal.
  60
  61 The transmitter requires a Pyboard 1.x (not Lite), a Pyboard D or an ESP32.
  62 Output is via an IR LED which will need a transistor to provide sufficient
  63 current. The ESP32 has significant limitations as a transmitter discussed
  64 [here](./TRANSMITTER.md#52-esp32).