X-Git-Url: https://vault307.fbx.one/gitweb/micorpython_ir.git/blobdiff_plain/07fa0939855ebcefb238aed67bfe9dff22942ebf..e53fbf4b049125934af6b4572a078301401dbed5:/README.md diff --git a/README.md b/README.md index d84bba7..2e31090 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,11 @@ 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 compatible with it. +NOTE: The receiver is intended to be cross-platform. In testing it has proved +problematic on ESP8266 and ESP32 with a tendency to crash and reboot, +especially when repeated pulse trains re received. The cause is under +investigation. + # 1. IR communication IR communication uses a carrier frequency to pulse the IR source. Modulation @@ -27,10 +32,11 @@ Pyboard. A remote using the NEC protocol is [this one](https://www.adafruit.com/products/389). -Remotes normally transmit an address and a data byte. The address denotes the -physical device being controlled. The data is associated with the button on the -remote. Provision exists for differentiating between a button repeatedly -pressed and one which is held down; the mechanism is protocol dependent. +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. # 2. Hardware Requirements @@ -40,14 +46,14 @@ 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. The tested chip returns a 0 level on carrier detect, but the -driver design should ensure operation regardless of sense. +driver design ensures operation regardless of sense. In my testing a 38KHz demodulator worked with 36KHz and 40KHz remotes, but this is obviously not guaranteed or optimal. -The pin used to connect the decoder chip to the target is arbitrary but the -test programs assume pin X3 on the Pyboard, pin 13 on the ESP8266 and pin 23 on -ESP32. +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. 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. @@ -110,10 +116,12 @@ Protocol specific args: address will be correctly received. Set `False` to enable extra error checking for remotes that return an 8 bit address. 2. `bits=20` Sony specific. The SIRC protocol comes in 3 variants: 12, 15 and - 20 bits. The default will handle bitstreams from all three types of remote. - Choosing a value matching your remote improves the timing and reduces the - likelihood of errors when handling repeats: the SIRC timing when a button is - held down is tight in 20 bit mode. + 20 bits. The default will handle bitstreams from all three types of remote. A + value matching your remote improves the timing and reduces the likelihood of + errors when handling repeats: in 20-bit mode SIRC timing when a button is held + down is tight. A worst-case 20-bit block takes 39ms nominal, yet the repeat + time is 45ms nominal. + The Sony remote tested issues both 12 bit and 15 bit streams. The callback takes the following args: 1. `data` Integer value fom the remote. A negative value indicates an error @@ -121,7 +129,9 @@ The callback takes the following args: 2. `addr` Address from the remote 3. `ctrl` 0 in the case of NEC. Philips protocols toggle this bit on repeat button presses. If the button is held down the bit is not toggled. The - transmitter demo implements this behaviour. + transmitter demo implements this behaviour. + In the case of Sony the value will be 0 unless receiving a 20-bit stream, in + which case it will hold the extended value. 4. Any args passed to the constructor. Class variable: @@ -142,7 +152,7 @@ running the chip at 160MHz. In general applications should provide user feedback of correct reception. Users tend to press the key again if the expected action is absent. -Data values passed to the callback are normally positive. Negative values +Data values passed to the callback are zero or positive. Negative values indicate a repeat code or an error. `REPEAT` A repeat code was received. @@ -202,13 +212,8 @@ All constructors take the following args: 3. `verbose=False` If `True` emits debug output. The `SONY` constructor is of form `pin, bits=12, freq=40000, verbose=False`. -The `bits` value may be 12, 15 or 20 to set the highest SIRC variant in use. -Other args are as above. If `bits` is set to 20 then all variants will be -received. Setting the value to the maximum expected improves error checking and -timing tolerances. In particular a worst-case 20-bit block takes 39ms nominal, -yet the repeat time is 45ms nominal. - -The Sony remote tested issues both 12 bit and 15 bit streams. +The `bits` value may be 12, 15 or 20 to set SIRC variant in use. Other args are +as above. Method: 1. `transmit(addr, data, toggle=0)` Integer args. `addr` and `data` are @@ -239,7 +244,7 @@ increase power. The transistor type is not critical. -These circuits assume circuits as shown. Here the carrier "off" state is 0V, +The driver assumes circuits as shown. Here the carrier "off" state is 0V, which is the driver default. If using a circuit where "off" is required to be 3.3V, the constant `_SPACE` in `ir_tx.py` should be changed to 100. @@ -256,7 +261,7 @@ channel 1 is used to configure the output pin as a PWM channel. Its frequency is set in the constructor. The OOK is performed by dynamically changing the duty ratio using the timer channel's `pulse_width_percent` method: this varies the pulse width from 0 to a duty ratio passed to the constructor. The NEC -protocol defaults to 50%, the Philips ones to 30%. +protocol defaults to 50%, the Sony and Philips ones to 30%. The duty ratio is changed by the Timer 5 callback `._cb`. This retrieves the next duration from the array. If it is not `STOP` it toggles the duty cycle