X-Git-Url: https://vault307.fbx.one/gitweb/micorpython_ir.git/blobdiff_plain/a1bee40ddc3835dce155541c295e3fcfb49ddcc9..d7ff5be7654ececde87be89f32a08986b5c3b5c7:/RECEIVER.md?ds=inline diff --git a/RECEIVER.md b/RECEIVER.md index db0f164..13ce77a 100644 --- a/RECEIVER.md +++ b/RECEIVER.md @@ -15,32 +15,60 @@ driver design ensures operation regardless of sense. In my testing a 38KHz demodulator worked with 36KHz and 40KHz remotes, but this is obviously neither guaranteed nor optimal. +The TSOP4838 can run from 3.3V or 5V supplies. The former should be used on +non-5V compliant hosts such as ESP32 and Raspberry Pi Pico and is fine on 5V +compliant hosts too. + The pin used to connect the decoder chip to the target is arbitrary. The test -program assumes pin X3 on the Pyboard, pin 23 on ESP32 and pin 13 on ESP8266. -On the WeMos D1 Mini the equivalent pin is D7. +program `acquire.py` uses the following pins by default: + +| Host | Pin | Notes | +|:-------:|:---:|:-----:| +| Pyboard | X3 | | +| ESP32 | 23 | | +| ESP8266 | 13 | | +| D1 Mini | D7 | WeMos name for pin 13. | +| Pico | 16 | | A remote using the NEC protocol is [this one](https://www.adafruit.com/products/389). -# 2. Installation and demo script +# 2. Installation and demo scripts The receiver is a Python package. This minimises RAM usage: applications only -import the device driver for the protocol in use. - +import the device driver for the protocol in use. Clone the repository to the +current directory of your PC with: +```bash +$ git clone https://github.com/peterhinch/micropython_ir +``` Copy the following to the target filesystem: 1. `ir_rx` Directory and contents. There are no dependencies. -The demo can be used to characterise IR remotes. It displays the codes returned -by each button. This can aid in the design of receiver applications. The demo -prints "running" every 5 seconds and reports any data received from the remote. +## 2.1 Test scripts +The demo can be used to characterise IR remotes where the protocol is known. It +displays the codes returned by each button. This can aid in the design of +receiver applications. The demo prints "running" every 5 seconds and reports +any data received from the remote. ```python from ir_rx.test import test ``` Instructions will be displayed at the REPL. +If the protocol in use is unknown, there are two options: trial and error with +the above script or run the following: +```python +from ir_rx.acquire import test +test() +``` +This script waits for a single burst from the remote and prints the timing of +the pulses followed by its best guess at the protocol. It correctly identifies +supported protocols, but can wrongly identify unsupported protocols. The +report produced by the script exposed to an unknown protocol is unpredictable. +The `test()` function returns a list of the mark and space periods (in μs). + # 3. The driver This implements a class for each supported protocol. Each class is subclassed @@ -71,8 +99,7 @@ while True: #### Common to all classes -Constructor: -Args: +Constructor args: 1. `pin` is a `machine.Pin` instance configured as an input, connected to the IR decoder chip. 2. `callback` is the user supplied callback. @@ -93,13 +120,14 @@ The user callback takes the following args: Bound variable: 1. `verbose=False` If `True` emits debug output. -Method: - 1. `error_function` Arg: a function taking a single `int` arg. If this is - specified it will be called if an error occurs. The value corresponds to the - error code (see below). Typical usage might be to provide some user feedback - of incorrect reception although beware of occasional triggers by external - events. In my testing the TSOP4838 produces 200µs pulses on occasion for no - obvious reason. See [section 4](./RECEIVER.md#4-errors). +Methods: + 1. `error_function` Arg: a function taking a single `int` arg. If specified + the function will be called if an error occurs. The arg value corresponds to + the error code. Typical usage might be to provide some user feedback of + incorrect reception although beware of occasional triggers by external events. + In my testing the TSOP4838 produces 200µs pulses on occasion for no obvious + reason. See [section 4](./RECEIVER.md#4-errors). + 2. `close` No args. Shuts down the pin and timer interrupts. A function is provided to print errors in human readable form. This may be invoked as follows: @@ -113,9 +141,9 @@ Class variables: 1. These are constants defining the NEC repeat code and the error codes sent to the error function. They are discussed in [section 4](./RECEIVER.md#4-errors). -#### NEC classes +#### NEC classes (includes Samsung) -`NEC_8`, `NEC_16` +`NEC_8`, `NEC_16`, `SAMSUNG` Typical invocation: ```python @@ -129,6 +157,13 @@ The `NEC_8` class enables error checking for remotes that return an 8 bit address: the complement is checked and the address returned as an 8-bit value. A 16-bit address will result in an error. +The `SAMSUNG` class returns 16 bit address and data values. The remote sample +tested did not issue repeat codes - if a button is held down it simply repeated +the original value. In common with other NEC classes the callback receives a +value of 0 in the `ctrl` arg. + +Thanks are due to J.E.Tannenbaum for information about the Samsung protocol. + #### Sony classes `SONY_12`, `SONY_15`, `SONY_20` @@ -155,7 +190,40 @@ Typical invocation: from ir_rx.philips import RC5_IR ``` -These support the RC-5 and RC-6 mode 0 protocols respectively. +These support the RC-5 (including RC-5X) and RC-6 mode 0 protocols +respectively. + +#### Microsoft MCE class + +`MCE` + +Typical invocation: +```python +from ir_rx.mce import MCE +``` + +I have been unable to locate a definitive specification: the protocol was +analysed by a mixture of googling and experiment. Behaviour may change if I +acquire new information. The protocol is known as OrtekMCE and the remote +control is sold on eBay as VRC-1100. + +The remote was designed for Microsoft Media Center and is used to control Kodi +on boxes such as the Raspberry Pi. With a suitable PC driver it can emulate a +PC keyboard and mouse. The mouse emulation uses a different protocol: the class +does not currently support it. Pressing mouse buttons and pad will cause the +error function (if provided) to be called. + +Args passed to the callback comprise 4 bit `addr`, 6 bit `data` and 2 bit `ctrl` +with the latter having the value 0 for the first message and 2 for the message +sent on key release. Intermediate messages (where the key is held down) have +value 1. + +There is a 4-bit checksum which is used by default. The algorithm requires an +initial 'seed' value which my testing proved to be 4. However the only +[documentation](http://www.hifi-remote.com/johnsfine/DecodeIR.html#OrtekMCE) I +could find stated that the value should be 3. I implemented this as a class +variable `MCE.init_cs=4`. This enables it to be changed if some remotes use 3. +If the value is set to -1 the check will be skipped. # 4. Errors @@ -231,21 +299,11 @@ CPU times used by `.decode` (not including the user callback) were measured on a Pyboard D SF2W at stock frequency. They were: NEC 1ms for normal data, 100μs for a repeat code. Philips codes: RC-5 900μs, RC-6 mode 0 5.5ms. -# 7. References - -[General information about IR](https://www.sbprojects.net/knowledge/ir/) - -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) +# 7. Unsupported protocols -Philips protocols: -[RC5](https://en.wikipedia.org/wiki/RC-5) -[RC5](https://www.sbprojects.net/knowledge/ir/rc5.php) -[RC6](https://www.sbprojects.net/knowledge/ir/rc6.php) - -Sony protocol: -[SIRC](https://www.sbprojects.net/knowledge/ir/sirc.php) +It is possible to capture an IR burst from a remote and to re-create it using +the transmitter. This has limitations and is discussed in detail in +[the transmitter doc](./TRANSMITTER.md#5-unsupported-protocols). # Appendix 1 NEC Protocol description @@ -262,3 +320,18 @@ 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. + +# Appendix 2 MCE Protocol + +The bitstream comprises a header (2ms mark, 1ms space) followed by 16 bits of +Manchester encoded data with a bit time of 500μs. Data are encoded +``` +ccccddddddppaaaa +``` +Where `aaaa` is the address, `pp` is the position (toggle) field, `dddddd` is +data and `cccc` is a checksum. This is calculated by counting the ones in +`ddddddppaaaa` and adding 4. Data are transmitted LSB first. + +The only [doc](http://www.hifi-remote.com/johnsfine/DecodeIR.html#OrtekMCE) I +could find states that the checksum seed value is 3, but this did not match the +remote I have.