X-Git-Url: https://vault307.fbx.one/gitweb/micorpython_ir.git/blobdiff_plain/f2990bb46017fc3723fdf3d8917f94c458f5ee0a..2ebf5db498266618fc0f037469309a6ea1906304:/README.md?ds=sidebyside diff --git a/README.md b/README.md index 03e013e..96c3fce 100644 --- a/README.md +++ b/README.md @@ -2,158 +2,113 @@ This repo provides a driver to receive from IR (infra red) remote controls and a driver for IR "blaster" apps. The device drivers are nonblocking. They do not -require `uasyncio` but are entirely compatible with it. +require `uasyncio` but are compatible with it, and are designed for standard +firmware builds. -IR communication uses a carrier frequency to pulse the IR source. Modulation -takes the form of OOK (on-off keying). There are a several mutually -incompatible protocols and at least two options for carrier frequency, namely -36KHz and 38KHz. +The receiver is cross platform and has been tested on Pyboard, ESP8266, ESP32 +and Raspberry Pi Pico. -The drivers support the NEC protocol and two Philips protocols, namely RC-5 and -RC-6 mode 0. In the case of the transmitter the carrier frequency is a runtime -parameter so any value may be used. The receiver uses a hardware demodulator -which must be specified for the correct frequency. The device driver is carrier -frequency agnostic. +In a typical use case the receiver is employed at the REPL to sniff the address +and data values associated with buttons on a remote control. The transmitter is +then used in an application to send those codes, emulating the remote control. -# Hardware Requirements +Other use cases involve running the receiver in an application. This enables an +IR remote to control a device such as a robot. -The receiver is cross-platform. It requires an IR receiver chip to demodulate -the carrier. There are two options for carrier frequency: 36KHz and 38KHz. The -chip must be selected for the frequency in use by the remote. +#### [Receiver docs](./RECEIVER.md) -The transmitter requires a Pyboard 1.x (not Lite) or a Pyboard D. Output is via -an IR LED which will normally need a transistor to provide sufficient current. +The transmitter driver is compatible with Pyboard (1.x and D series) and ESP32. +ESP8266 is unsupported; it seems incapable of generating the required signals. -# Decoder for IR Remote Controls using the NEC protocol +#### [Transmitter docs](./TRANSMITTER.md) -This protocol is widely used. An example remote is [this one](https://www.adafruit.com/products/389). -To interface the device a receiver chip such as the Vishay TSOP4838 or the -[adafruit one](https://www.adafruit.com/products/157) is required. This -demodulates the 38KHz IR pulses and passes the demodulated pulse train to the -microcontroller. +# 1. IR communication -The driver and test programs run on the Pyboard and ESP8266. - -# Files - - 1. `aremote.py` The device driver. - 2. `art.py` A test program to characterise a remote. - 3. `art1.py` Control an onboard LED using a remote. The data and addresss - values need changing to match your characterised remote. - -# Dependencies +IR communication uses a carrier frequency to pulse the IR source. Modulation +takes the form of OOK (on-off keying). There are multiple protocols and at +least three options for carrier frequency: 36, 38 and 40KHz. -The driver requires the `uasyncio` library and the file `asyn.py` from this -repository. +In the case of the transmitter the carrier frequency is a runtime parameter: +any value may be specified. The receiver uses a hardware demodulator which +should be purchased for the correct frequency. The receiver device driver sees +the demodulated signal and is hence carrier frequency agnostic. -# Usage +Remotes transmit an address and a data byte, plus in some cases an extra value. +The address denotes the physical device being controlled. The data defines the +button on the remote. Provision usually exists for differentiating between a +button repeatedly pressed and one which is held down; the mechanism is protocol +dependent. -The pin used to connect the decoder chip to the target is arbitrary but the -test programs assume pin X3 on the Pyboard and pin 13 on the ESP8266. +# 2. Supported protocols -The driver is event driven. Pressing a button on the remote causes a user -defined callback to be run. The NEC protocol returns a data value and an -address. These are passed to the callback as the first two arguments (further -user defined arguments may be supplied). The address is normally constant for a -given remote, with the data corresponding to the button. Applications should -check the address to ensure that they only respond to the correct remote. +The drivers support NEC and Sony protocols plus two Philips protocols, namely +RC-5 and RC-6 mode 0. There is also support for the OrtekMCE protocol used on +VRC-1100 remotes. These originally supported Microsoft Media Center but can be +used to control Kodi and (with a suitable receiver) to emulate a PC keyboard. -Data values are 8 bit. Addresses may be 8 or 16 bit depending on whether the -remote uses extended addressing. +Examining waveforms from various remote controls it is evident that numerous +protocols exist. Some are doubtless proprietary and undocumented. The supported +protocols are those for which I managed to locate documentation. My preference +is for the NEC version. It has conservative timing and good provision for error +detection. RC-5 has limited error detection, and RC-6 mode 0 has rather fast +timing. -If a button is held down a repeat code is sent. In this event the driver -returns a data value of `REPEAT` and the address associated with the last -valid data block. +A remote using the NEC protocol is [this one](https://www.adafruit.com/products/389). -To characterise a remote run `art.py` and note the data value for each button -which is to be used. If the address is less than 256, extended addressing is -not in use. +# 3. Hardware Requirements -# Reliability +These are discussed in detail in the relevant docs; the following provides an +overview. -IR reception is inevitably subject to errors, notably if the remote is operated -near the limit of its range, if it is not pointed at the receiver or if its -batteries are low. So applications must check for, and usually ignore, errors. -These are flagged by data values < `REPEAT`. +The receiver is cross-platform. It requires an IR receiver chip to demodulate +the carrier. The chip must be selected for the frequency in use by the remote. +For 38KHz devices a receiver chip such as the Vishay TSOP4838 or the +[adafruit one](https://www.adafruit.com/products/157) is required. This +demodulates the 38KHz IR pulses and passes the demodulated pulse train to the +microcontroller. -On the ESP8266 there is a further source of errors. This results from the large -and variable interrupt latency of the device which can exceed the pulse -duration. This causes pulses to be missed. This tendency is slightly reduced by -running the chip at 160MHz. +In my testing a 38KHz demodulator worked with 36KHz and 40KHz remotes, but this +is obviously neither guaranteed nor optimal. -In general applications should provide user feedback of correct reception. -Users tend to press the key again if no acknowledgement is received. +The transmitter requires a Pyboard 1.x (not Lite), a Pyboard D or an ESP32. +Output is via an IR LED which will need a transistor to provide sufficient +current. The ESP32 requires an extra transistor to work as a transmitter. -# The NEC_IR class +## 3.1 Carrier frequencies -The constructor takes the following positional arguments. +These are as follows. The Samsung and Panasonic remotes appear to use +proprietary protocols and are not supported by these drivers. - 1. `pin` A `Pin` instance for the decoder chip. - 2. `cb` The user callback function. - 3. `extended` Set `False` to enable extra error checking if the remote - returns an 8 bit address. - 4. Further arguments, if provided, are passed to the callback. +| Protocol | F KHz | How found | Support | +|:---------:|:-----:|:-------------:|:-------:| +| NEC | 38 | Measured | Y | +| RC-5 RC-6 | 36 | Spec/measured | Y | +| Sony | 40 | Spec/measured | Y | +| MCE | 38 | Measured | Y | +| Samsung | 38 | Measured | N | +| Panasonic | 36.3 | Measured | N | -The callback receives the following positional arguments: +# 4. References - 1. The data value returned from the remote. - 2. The address value returned from the remote. - 3. Any further arguments provided to the `NEC_IR` constructor. +Sources of information about IR protocols. The `sbprojects.net` site is an +excellent resource. +[General information about IR](https://www.sbprojects.net/knowledge/ir/) -Negative data values are used to signal repeat codes and transmission errors. +The NEC protocol: +[altium](http://techdocs.altium.com/display/FPGA/NEC+Infrared+Transmission+Protocol) +[circuitvalley](http://www.circuitvalley.com/2013/09/nec-protocol-ir-infrared-remote-control.html) +[sbprojects.net](https://www.sbprojects.net/knowledge/ir/nec.php) -The test program `art1.py` provides an example of a minimal application. +Philips protocols: +[RC5 Wikipedia](https://en.wikipedia.org/wiki/RC-5) +[RC5 sbprojects.net](https://www.sbprojects.net/knowledge/ir/rc5.php) +[RC6 sbprojects.net](https://www.sbprojects.net/knowledge/ir/rc6.php) -# How it works +Sony protocol: +[SIRC sbprojects.net](https://www.sbprojects.net/knowledge/ir/sirc.php) -The NEC protocol is described in these references. -[altium](http://techdocs.altium.com/display/FPGA/NEC+Infrared+Transmission+Protocol) -[circuitvalley](http://www.circuitvalley.com/2013/09/nec-protocol-ir-infrared-remote-control.html) +MCE protocol: +[OrtekMCE](http://www.hifi-remote.com/johnsfine/DecodeIR.html#OrtekMCE) -A normal burst comprises exactly 68 edges, the exception being a repeat code -which has 4. An incorrect number of edges is treated as an error. All bursts -begin with a 9ms pulse. In a normal code this is followed by a 4.5ms space; a -repeat code is identified by a 2.25ms space. A data burst lasts for 67.5ms. - -Data bits comprise a 562.5µs mark followed by a space whose length determines -the bit value. 562.5µs denotes 0 and 1.6875ms denotes 1. - -In 8 bit address mode the complement of the address and data values is sent to -provide error checking. This also ensures that the number of 1's and 0's in a -burst is constant, giving a constant burst length of 67.5ms. In extended -address mode this constancy is lost. The burst length can (by my calculations) -run to 76.5ms. - -A pin interrupt records the time of every state change (in µs). The first -interrupt in a burst sets an event, passing the time of the state change. A -coroutine waits on the event, yields for the duration of a data burst, then -decodes the stored data before calling the user-specified callback. - -Passing the time to the `Event` instance enables the coro to compensate for -any asyncio latency when setting its delay period. - -The algorithm promotes interrupt handler speed over RAM use: the 276 bytes used -for the data array could be reduced to 69 bytes by computing and saving deltas -in the interrupt service routine. - -# Error returns - -Data values passed to the callback are normally positive. Negative values -indicate a repeat code or an error. - -`REPEAT` A repeat code was received. - -Any data value < `REPEAT` denotes an error. In general applications do not -need to decode these, but they may be of use in debugging. For completeness -they are listed below. - -`BADSTART` A short (<= 4ms) start pulse was received. May occur due to IR -interference, e.g. from fluorescent lights. The TSOP4838 is prone to producing -200µs pulses on occasion, especially when using the ESP8266. -`BADBLOCK` A normal data block: too few edges received. Occurs on the ESP8266 -owing to high interrupt latency. -`BADREP` A repeat block: an incorrect number of edges were received. -`OVERRUN` A normal data block: too many edges received. -`BADDATA` Data did not match check byte. -`BADADDR` Where `extended` is `False` the 8-bit address is checked -against the check byte. This code is returned on failure. +IR decoders (C sourcecode): +[in the Linux kernel](https://github.com/torvalds/linux/tree/master/drivers/media/rc)