Philips RC5 TX: fix validation for RC5X.

[micorpython_ir.git] / RECEIVER.md

diff --git a/RECEIVER.md b/RECEIVER.md
index db0f164cb6b3cb4aba9f20349e056bc6d0387b2f..13ce77a24339cb1557c1e9aa5c011fe953fe7bd4 100644 (file)
--- 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.
 
 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
 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).
 
 
 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
 
 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.
 
 
 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.
 
 ```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
 # 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
 
 
 #### 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.
  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.
 
 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:
 
 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).
 
  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
 
 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.
 
 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`
 #### Sony classes
 
 `SONY_12`, `SONY_15`, `SONY_20`


@@ -155,7 +190,40 @@ Typical invocation:
 from ir_rx.philips import RC5_IR
 ```
 
 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
 
 
 # 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.
 
 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
 
 
 # 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.
 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.