From f2990bb46017fc3723fdf3d8917f94c458f5ee0a Mon Sep 17 00:00:00 2001 From: Peter Hinch Date: Mon, 24 Feb 2020 05:34:31 +0000 Subject: [PATCH] Initial commit. RC6 rx not working. --- README.md | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 159 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index df2feac..03e013e 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,159 @@ -# micropython_ir -Nonblocking device drivers to receive from IR remotes and for IR "blaster" apps. +# Device drivers for IR (infra red) remote controls + +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. + +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 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. + +# Hardware Requirements + +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. + +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. + +# Decoder for IR Remote Controls using the NEC protocol + +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. + +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 + +The driver requires the `uasyncio` library and the file `asyn.py` from this +repository. + +# Usage + +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. + +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. + +Data values are 8 bit. Addresses may be 8 or 16 bit depending on whether the +remote uses extended addressing. + +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. + +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. + +# Reliability + +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`. + +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 general applications should provide user feedback of correct reception. +Users tend to press the key again if no acknowledgement is received. + +# The NEC_IR class + +The constructor takes the following positional arguments. + + 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. + +The callback receives the following positional arguments: + + 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. + +Negative data values are used to signal repeat codes and transmission errors. + +The test program `art1.py` provides an example of a minimal application. + +# How it works + +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) + +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. -- 2.47.3