X-Git-Url: https://vault307.fbx.one/gitweb/micorpython_ir.git/blobdiff_plain/36140aa568d4a538adafb03e575b26de8a0784ef..0dd5fa3ec131e728516643db26efc88bf843fc11:/RECEIVER.md?ds=inline diff --git a/RECEIVER.md b/RECEIVER.md index db0f164..cd84c4f 100644 --- a/RECEIVER.md +++ b/RECEIVER.md @@ -15,32 +15,53 @@ 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. 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 +92,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 +113,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: @@ -155,7 +176,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 +285,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) - -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) +# 7. Unsupported protocols -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 +306,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.