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, ESP32
   9 and Raspberry Pi Pico.
  10
  11 In a typical use case the receiver is employed at the REPL to sniff the address
  12 and data values associated with buttons on a remote control. The transmitter is
  13 then used in an application to send those codes, emulating the remote control.
  14
  15 Other use cases involve running the receiver in an application. This enables an
  16 IR remote to control a device such as a robot. This may be problematic on some
  17 platforms. Please see [section 4](./README.md#4-receiver-limitations).
  18
  19 ## Raspberry Pi Pico note
  20
  21 Early firmware has [this issue](https://github.com/micropython/micropython/issues/6866)
  22 affecting USB communication with some PC's. This is now fixed. Please ensure
  23 you are using up to date firmware.
  24
  25 #### [Receiver docs](./RECEIVER.md)
  26
  27 The transmitter driver is compatible with Pyboard (1.x and D series) and ESP32.
  28 ESP8266 is unsupported; it seems incapable of generating the required signals.
  29
  30 #### [Transmitter docs](./TRANSMITTER.md)
  31
  32 # 1. IR communication
  33
  34 IR communication uses a carrier frequency to pulse the IR source. Modulation
  35 takes the form of OOK (on-off keying). There are multiple protocols and at
  36 least three options for carrier frequency: 36, 38 and 40KHz.
  37
  38 In the case of the transmitter the carrier frequency is a runtime parameter:
  39 any value may be specified. The receiver uses a hardware demodulator which
  40 should be purchased for the correct frequency. The receiver device driver sees
  41 the demodulated signal and is hence carrier frequency agnostic.
  42
  43 Remotes transmit an address and a data byte, plus in some cases an extra value.
  44 The address denotes the physical device being controlled. The data defines the
  45 button on the remote. Provision usually exists for differentiating between a
  46 button repeatedly pressed and one which is held down; the mechanism is protocol
  47 dependent.
  48
  49 # 2. Supported protocols
  50
  51 The drivers support NEC and Sony protocols plus two Philips protocols, namely
  52 RC-5 and RC-6 mode 0. There is also support for the OrtekMCE protocol used on
  53 VRC-1100 remotes. These originally supported Microsoft Media Center but can be
  54 used to control Kodi and (with a suitable receiver) to emulate a PC keyboard.
  55 The Samsung protocol (NEC variant) is also supported.
  56
  57 Examining waveforms from various remote controls it is evident that numerous
  58 protocols exist. Some are doubtless proprietary and undocumented. The supported
  59 protocols are those for which I managed to locate documentation. My preference
  60 is for the NEC version. It has conservative timing and good provision for error
  61 detection. RC-5 has limited error detection, and RC-6 mode 0 has rather fast
  62 timing.
  63
  64 A remote using the NEC protocol is [this one](https://www.adafruit.com/products/389).
  65
  66 # 3. Hardware Requirements
  67
  68 These are discussed in detail in the relevant docs; the following provides an
  69 overview.
  70
  71 The receiver is cross-platform. It requires an IR receiver chip to demodulate
  72 the carrier. The chip must be selected for the frequency in use by the remote.
  73 For 38KHz devices a receiver chip such as the Vishay TSOP4838 or the
  74 [adafruit one](https://www.adafruit.com/products/157) is required. This
  75 demodulates the 38KHz IR pulses and passes the demodulated pulse train to the
  76 microcontroller.
  77
  78 In my testing a 38KHz demodulator worked with 36KHz and 40KHz remotes, but this
  79 is obviously neither guaranteed nor optimal.
  80
  81 The transmitter requires a Pyboard 1.x (not Lite), a Pyboard D, an ESP32 or
  82 Raspberry Pico (RP2). Output is via an IR LED which will need a transistor to
  83 provide sufficient current.
  84
  85 ## 3.1 Carrier frequencies
  86
  87 These are as follows. The Panasonic remote appears to use a proprietary
  88 protocol and is not supported by these drivers.
  89
  90 | Protocol  | F KHz | How found     | Support |
  91 |:---------:|:-----:|:-------------:|:-------:|
  92 | NEC       | 38    | Measured      | Y       |
  93 | RC-5 RC-6 | 36    | Spec/measured | Y       |
  94 | Sony      | 40    | Spec/measured | Y       |
  95 | MCE       | 38    | Measured      | Y       |
  96 | Samsung   | 38    | Measured      | Y       |
  97 | Panasonic | 36.3  | Measured      | N       |
  98
  99 # 4. Receiver limitations
 100
 101 The receiver uses a pin interrupt and depends on a quick response to a state
 102 change on the pin. This is guaranteed on platforms which support hard IRQ's
 103 such as the Pyboard and the RP4 Pico. The ESP32 and ESP8266 only support soft
 104 IRQ's. This means that, if code such as WiFi communication is running
 105 concurrently, reliable reception may be problematic.
 106
 107 # 5. References
 108
 109 Sources of information about IR protocols. The `sbprojects.net` site is an
 110 excellent resource.
 111 [General information about IR](https://www.sbprojects.net/knowledge/ir/)
 112
 113 The NEC protocol:
 114 [altium](http://techdocs.altium.com/display/FPGA/NEC+Infrared+Transmission+Protocol)
 115 [circuitvalley](http://www.circuitvalley.com/2013/09/nec-protocol-ir-infrared-remote-control.html)
 116 [sbprojects.net](https://www.sbprojects.net/knowledge/ir/nec.php)
 117
 118 The Samsung protocol:
 119 [Rustic Engineering](https://rusticengineering.wordpress.com/2011/02/09/infrared-room-control-with-samsung-ir-protocol/)
 120 [TechDesign Electronics](https://www.techdesign.be/projects/011/011_waves.htm) Waveforms of various protocols.
 121
 122
 123 Philips protocols:
 124 [RC5 Wikipedia](https://en.wikipedia.org/wiki/RC-5)
 125 [RC5 sbprojects.net](https://www.sbprojects.net/knowledge/ir/rc5.php)
 126 [RC6 sbprojects.net](https://www.sbprojects.net/knowledge/ir/rc6.php)
 127
 128 Sony protocol:
 129 [SIRC sbprojects.net](https://www.sbprojects.net/knowledge/ir/sirc.php)
 130
 131 MCE protocol:
 132 [OrtekMCE](http://www.hifi-remote.com/johnsfine/DecodeIR.html#OrtekMCE)
 133
 134 IR decoders (C sourcecode):
 135 [in the Linux kernel](https://github.com/torvalds/linux/tree/master/drivers/media/rc)