ESP32 TX: adapt for RMT API change.

[micorpython_ir.git] / README.md

diff --git a/README.md b/README.md
index 03e013e758efcd39a759681282f518601865b72c..48259c5f25034e06ae3c675d27b87bae22be717c 100644 (file)
--- a/README.md
+++ b/README.md
@@ -2,158 +2,128 @@
 
 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
 
 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 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.
+The receiver is cross platform and has been tested on Pyboard, ESP8266, ESP32
+and Raspberry Pi Pico.

 
 

-# 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. 
+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.

 
 

-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.
+Other use cases involve running the receiver in an application. This enables an
+IR remote to control a device such as a robot. This may be problematic on some
+platforms. Please see [section 4](./README.md#4-receiver-limitations).

 
 

-# Decoder for IR Remote Controls using the NEC protocol
+## Raspberry Pi Pico note

 
 

-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.
+Early firmware has [this issue](https://github.com/micropython/micropython/issues/6866)
+affecting USB communication with some PC's. This is now fixed. Please ensure
+you are using up to date firmware.

 
 

-The driver and test programs run on the Pyboard and ESP8266.
+#### [Receiver docs](./RECEIVER.md)

 
 

-# Files
+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.

 
 

- 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.
+#### [Transmitter docs](./TRANSMITTER.md)

 
 

-# Dependencies
+# 1. IR communication

 
 

-The driver requires the `uasyncio` library and the file `asyn.py` from this
-repository.
+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.

 
 

-# Usage
+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.

 
 

-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.
+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 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.
+# 2. Supported protocols

 
 

-Data values are 8 bit. Addresses may be 8 or 16 bit depending on whether the
-remote uses extended addressing.
+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.

 
 

-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.
+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.

 
 

-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.
+A remote using the NEC protocol is [this one](https://www.adafruit.com/products/389).

 
 

-# Reliability
+# 3. Hardware Requirements

 
 

-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`.
+These are discussed in detail in the relevant docs; the following provides an
+overview.

 
 

-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.
+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.

 
 

-In general applications should provide user feedback of correct reception.
-Users tend to press the key again if no acknowledgement is received.
+In my testing a 38KHz demodulator worked with 36KHz and 40KHz remotes, but this
+is obviously neither guaranteed nor optimal.

 
 

-# The NEC_IR class
+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 constructor takes the following positional arguments.
+## 3.1 Carrier frequencies

 
 

- 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.
+These are as follows. The Samsung and Panasonic remotes appear to use
+proprietary protocols and are not supported by these drivers.

 
 

-The callback receives the following positional arguments:
+| 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       |

 
 

- 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.
+# 4. Receiver limitations

 
 

-Negative data values are used to signal repeat codes and transmission errors.
+The receiver uses a pin interrupt and depends on a quick response to a state
+change on the pin. This is guaranteed on platforms which support hard IRQ's
+such as the Pyboard and the RP4 Pico. The ESP32 and ESP8266 only support soft
+IRQ's. This means that, if code such as WiFi communication is running
+concurrently, reliable reception may be problematic.

 
 

-The test program `art1.py` provides an example of a minimal application.
+# 5. References

 
 

-# How it works
+Sources of information about IR protocols. The `sbprojects.net` site is an
+excellent resource.  
+[General information about IR](https://www.sbprojects.net/knowledge/ir/)

 
 

-The NEC protocol is described in these references.  
+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)
 [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)
+
+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)
+
+Sony protocol:  
+[SIRC sbprojects.net](https://www.sbprojects.net/knowledge/ir/sirc.php)
+
+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)