Transmitter: ESP32 uses RMT to generate carrier. Test program updated for uasyncio V3

[micorpython_ir.git] / TRANSMITTER.md

diff --git a/TRANSMITTER.md b/TRANSMITTER.md
index 2cf169aabd4c879b601b7f2ce56f88a158298f98..7a70ccae6fc687121b30496f3179ceb27e5defef 100644 (file)
--- a/TRANSMITTER.md
+++ b/TRANSMITTER.md
@@ -13,8 +13,8 @@ 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
 
 
 ## 1.1 Pyboard Wiring
 


@@ -30,20 +30,16 @@ 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)
-
-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)
+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.

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


@@ -51,11 +47,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.14 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
 


@@ -85,6 +87,21 @@ It implements a class for each supported protocol, namely `NEC`, `SONY_12`,
 common abstract base class in `__init__.py`. The application instantiates the
 appropriate class and calls the `transmit` method to send data.
 
 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
+```
+

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


@@ -253,13 +270,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.