Merge pull request #8 from jetannenbaum/master

[micorpython_ir.git] / TRANSMITTER.md

diff --git a/TRANSMITTER.md b/TRANSMITTER.md
index 3e3290e28d56f2c66ca8e73d9e33891ae17ed21f..a328d68f4fcaf7c5354415aee405a84b38f1600c 100644 (file)
--- a/TRANSMITTER.md
+++ b/TRANSMITTER.md
@@ -13,8 +13,14 @@ 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)`.
+
+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 Pyboard Wiring
 
 
 ## 1.1 Pyboard Wiring
 


@@ -30,20 +36,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 +59,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,7 +92,8 @@ 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
 
 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


@@ -96,8 +111,14 @@ Basic usage on ESP32:
 ```python
 from machine import Pin
 from ir_tx.nec import NEC
 ```python
 from machine import Pin
 from ir_tx.nec import NEC

-pins = (Pin(23, Pin.OUT, value = 0), Pin(21, Pin.OUT, value = 0))
-nec = NEC(pins)
+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
 ```
 
 nec.transmit(1, 2)  # address == 1, data == 2
 ```
 


@@ -269,13 +290,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.