Support transmit and receive on Samsung remotes.

[micorpython_ir.git] / TRANSMITTER.md

diff --git a/TRANSMITTER.md b/TRANSMITTER.md
index 2cf169aabd4c879b601b7f2ce56f88a158298f98..c76995bb5390014de2e4b4dcbd55519aa818ab0c 100644 (file)
--- a/TRANSMITTER.md
+++ b/TRANSMITTER.md
@@ -13,10 +13,19 @@ On the Pyboard the transmitter test script assumes pin X1 for IR output. It can
 be changed, but it must support Timer 2 channel 1. Pins for pushbutton inputs
 are arbitrary: X3 and X4 are used. The driver uses timers 2 and 5.
 
 be changed, but it must support Timer 2 channel 1. Pins for pushbutton inputs
 are arbitrary: X3 and X4 are used. The driver uses timers 2 and 5.
 

-On ESP32 the demo uses pins 21 and 23 for IR output and pins 18 and 19 for
-pushbuttons. These pins may be changed.
+On ESP32 the demo uses pin 23 for IR output and pins 18 and 19 for pushbuttons.
+These pins may be changed. The only device resource used is `RMT(0)`.

 
 

-## 1.1 Pyboard Wiring
+On Raspberry Pi Pico the demo uses pin 17 for IR output and pins 18 and 19 for
+pushbuttons. These pins may be changed. The driver uses the PIO to emulate a
+device similar to the ESP32 RMT. The device driver is
+[documented here](./RP2_RMT.md); this is for experimenters and those wanting to
+use the library in conjunction with their own PIO assembler code.
+
+## 1.1 Wiring
+
+All microcontrollers require an external circuit to drive the LED. The notes
+below on specific microcontrollers assume that such a circuit is used.

 
 I use the following circuit which delivers just under 40mA to the diode. R2 may
 be reduced for higher current.  
 
 I use the following circuit which delivers just under 40mA to the diode. R2 may
 be reduced for higher current.  


@@ -30,20 +39,22 @@ increase power.
 The transistor type is not critical.
 
 The driver assumes circuits as shown. Here the carrier "off" state is 0V,
 The transistor type is not critical.
 
 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 class variable `active_high` should be set `False`.
+which is the driver default. If using an alternative circuit where "off" is
+required to be 3.3V, the class variable `active_high` should be set `False`.

 
 ## 1.2 ESP32 Wiring
 
 
 ## 1.2 ESP32 Wiring
 

-The ESP32 RMT device does not currently support the carrier option. A simple
-hardware gate is required to turn the IR LED on when both the carrier pin and
-the RMT pin are high. A suitable circuit is below; the transistor type is not
-critical.  
-![Image](images/gate.png)
+The ESP32 RMT device now supports the carrier option, and this driver has been
+updated to use it. The same circuits as above may be used to connect to pin 23
+(or other pin, if the code has been adapted). The `active_high` option is not
+available on the ESP32 `RMT` object, so any alternative circuit must illuminate
+the LED if the pin state is high.
+
+## 1.3 RP2 Wiring

 
 

-This simpler alternative uses MOSFETS, but the device type needs attention. The
-chosen type has a low gate-source threshold voltage and low Rdson.  
-![Image](images/gate_mosfet.png)
+There is no `active_high` option so the circuit  must illuminate the LED if the
+pin state is high, as per the above drivers. Test programs use pin 17, but this
+can be reassigned.

 
 # 2. Dependencies and installation
 
 
 # 2. Dependencies and installation
 


@@ -51,11 +62,17 @@ chosen type has a low gate-source threshold voltage and low Rdson.
 
 The device driver has no dependencies.
 
 
 The device driver has no dependencies.
 

-On ESP32 a firmware version >= V1.12 is required. The Loboris port is not
-supported owing to the need for the RMT device.
+On ESP32 a firmware version >= V1.17 is required. The Loboris port is not
+supported owing to the need for the RMT device and other issues.

 
 

-The demo program requires `uasyncio` from the official library and `aswitch.py`
-from [this repo](https://github.com/peterhinch/micropython-async).
+The demo program uses `uasyncio` primitives from
+[this repo](https://github.com/peterhinch/micropython-async). Clone the repo to
+a directory on your PC:
+```bash
+$ git clone https://github.com/peterhinch/micropython-async
+```
+move to its `v3` directory, and copy the `primitives` directory with its
+contents to the filesystem.

 
 ## 2.2 Installation
 
 
 ## 2.2 Installation
 


@@ -78,13 +95,36 @@ Instructions will be displayed at the REPL.
 
 # 3. The driver
 
 
 # 3. The driver
 

-This is specific to Pyboard D, Pyboard 1.x (not Lite) and ESP32.
+This is specific to Pyboard D, Pyboard 1.x (not Lite), ESP32 and Raspberry Pi
+Pico (RP2 architecture chip).

 
 It implements a class for each supported protocol, namely `NEC`, `SONY_12`,
 `SONY_15`, `SONY_20`, `RC5` and `RC6_M0`.  Each class is subclassed from a
 common abstract base class in `__init__.py`. The application instantiates the
 appropriate class and calls the `transmit` method to send data.
 
 
 It implements a class for each supported protocol, namely `NEC`, `SONY_12`,
 `SONY_15`, `SONY_20`, `RC5` and `RC6_M0`.  Each class is subclassed from a
 common abstract base class in `__init__.py`. The application instantiates the
 appropriate class and calls the `transmit` method to send data.
 

+Basic usage on a Pyboard:
+```python
+from machine import Pin
+from ir_tx.nec import NEC
+nec = NEC(Pin('X1'))
+nec.transmit(1, 2)  # address == 1, data == 2
+```
+Basic usage on ESP32:
+```python
+from machine import Pin
+from ir_tx.nec import NEC
+nec = NEC(Pin(23, Pin.OUT, value = 0))
+nec.transmit(1, 2)  # address == 1, data == 2
+```
+Basic usage on Pico:
+```python
+from machine import Pin
+from ir_tx.nec import NEC
+nec = NEC(Pin(17, Pin.OUT, value = 0))
+nec.transmit(1, 2)  # address == 1, data == 2
+```
+

 #### Common to all classes
 
 Constructor args:  
 #### Common to all classes
 
 Constructor args:  


@@ -132,7 +172,7 @@ skipping validation.
 | RC6_M0   | 6.0ms | 2.0ms   |
 | MCE      | 6.7ms | 2.0ms   |
 
 | RC6_M0   | 6.0ms | 2.0ms   |
 | MCE      | 6.7ms | 2.0ms   |
 

-#### NEC class
+#### NEC class (also Samsung)

 
 Class `NEC`. Example invocation:
 ```python
 
 Class `NEC`. Example invocation:
 ```python


@@ -150,6 +190,16 @@ the complement for values < 256.
 
 A value passed in `toggle` is ignored.
 
 
 A value passed in `toggle` is ignored.
 

+For Samsung protocol set the `samsung` class variable `True`:
+```python
+from ir_tx.nec import NEC
+NEC.samsung=True
+```
+Samsung remotes do not seem to use repeat codes: the sample I have simply
+repeats the original code.
+
+Thanks are due to J.E.Tannenbaum for information about the Samsung protocol.
+

 #### Sony classes
 
 Classes `SONY_12`, `SONY_15` and `SONY_20`. Example invocation:
 #### Sony classes
 
 Classes `SONY_12`, `SONY_15` and `SONY_20`. Example invocation:


@@ -253,13 +303,9 @@ transmission by calling the Timer5 callback.
 
 ## 4.2 ESP32
 
 
 ## 4.2 ESP32
 

-The carrier is output continuously at the specified duty ratio. A pulse train
-generated by the RMT instance drives a hardware gate such that the IR LED is
-lit only when both carrier and RMT are high.
-
-The carrier is generated by PWM instance `.pwm` running continuously. The ABC
-constructor converts the 0-100 duty ratio specified by the subclass to the
-0-1023 range used by ESP32.
+The RMT class now supports `carrier_freq` and `carrier_duty_percent`
+constructor args, so the base class `IR` (in `__init__.py`) uses these to
+enable the OOK (on-off keying) waveform.

 
 The `.trigger` method calls `RMT.write_pulses` and returns with `RMT` operating
 in the background.
 
 The `.trigger` method calls `RMT.write_pulses` and returns with `RMT` operating
 in the background.