update Changelog and Readme. I2S related to #338

gin66 · gin66 · commit 06a12fe14ea2 · 2026-03-07T22:41:46.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,7 +6,6 @@ pre-1.0.0:
 - esp32: new platformio project in extras/Esp32StepperDemo for esp32 stepper configuration
 - esp32-idf5: implement I2S-module in DIRECT mode to drive one stepper up to 200 kHz (1-3 modules depending on esp32 variant)
 - esp32-idf5: use I2S-module in MUX mode (16bit/stereo) to drive up to 32 steppers (or less if direction/enable on mux) (#338)
-    ATTENTION: WORK IN PROGRESS - DIR/ENABLE not yet functional. using Esp32StepperDemo manual dir/enable setting is possible
 
 0.34.0:
 - Major internal refactoring: reorganize code into subdirectories
diff --git a/README.md b/README.md
@@ -34,19 +34,23 @@ The stepper motors should be connected via a driver IC (like A4988) with a 1, 2
   - avr atmega32u4: only Pin 9, 10 and 11.
   - avr atmega2560: only Pin 6, 7 and 8.
       On platformio, this can be changed to other triples: 11/12/13 Timer 1, 5/2/3 Timer 3 or 46/45/44 Timer 5 with `FAS_TIMER_MODULE` setting.
-  - esp32: This can be any output capable port pin.
+  - esp32: This can be any output capable port pin, or use I2S for additional steppers:
+    * I2S Mux mode: up to 32 additional steppers via external demultiplexer (IDF ≥5.3)
+    * I2S Direct mode: 1-3 additional steppers using I2S controllers directly (IDF ≥5.3)
   - pico: Any GPIO up to 31
   - atmel sam due: This can be one of each group of pins: 34/67/74/35, 17/36/72/37/42, 40/64/69/41, 9, 8/44, 7/45, 6
   - Step should be done on transition Low to High. High time will be only a few us.
   On esp32 the high time is for slow speed fixed to ~2ms and high speed to 50% duty cycle.
   For pico direction delay is recommended
 * Direction Signal (optional)
   - This can be any output capable port pin.
+  - esp32: Can also use I2S Mux slots for direction control (IDF ≥5.3)
   - pico: Any GPIO up to 31
   - Position counting up on direction pin high or low, as per optional parameter to setDirectionPin(). Default is high.
   - With external callback on esp32 derivates, even shift register outputs can be used
 * Enable Signal (optional)
   - This can be any output capable port pin.
+  - esp32: Can also use I2S Mux slots for enable control (IDF ≥5.3)
   - Stepper will be enabled on pin high or low, as per optional parameter to setEnablePin(). Default is low.
   - With external callback, even shift register outputs can be used
 
@@ -142,49 +146,104 @@ Comments to pin sharing:
 * Steppers' command queue depth: 16
 * This device has four 16 bit timers, so extension up to 12 steppers should be possible (not implemented)
 
-### ESP32
+### ESP32 Variants Overview
+
+| Variant     | IDF 4.x Driver     | IDF 4.x Max | IDF 5.3+ Driver  | IDF 5.3+ Max (RMT+I2S) | I2S Ctrl | I2S Mux | I2S Direct |
+|-------------|--------------------|-------------|------------------|------------------------|----------|---------|------------|
+| ESP32       | MCPWM/PCNT + RMT   | 14 (6+8)    | RMT + I2S        | 8 + 32                 | 2        | 32 pins | 2 ch       |
+| ESP32-S2    | RMT                | 4           | RMT + I2S        | 4 + 32                 | 2        | 32 pins | 2 ch       |
+| ESP32-S3    | MCPWM/PCNT + RMT   | 8           | RMT + I2S        | 4 + 32                 | 2        | 32 pins | 2 ch       |
+| ESP32-C3    | RMT                | 2           | RMT + I2S        | 2 + 32                 | 1        | 32 pins | 1 ch       |
+| ESP32-C6    | -                  | -           | RMT + I2S        | 4 + 32                 | 1        | 32 pins | 1 ch       |
+| ESP32-P4    | -                  | -           | RMT + I2S        | 4 + 32                 | 3        | 32 pins | 3 ch       |
+
+**Notes:**
+- IDF 5.3+ Max = RMT channels + I2S Mux slots (can be combined)
+- I2S Mux requires ESP-IDF ≥5.3 and uses one I2S controller
+- I2S Mux slots are shared: if step/dir/enable all use I2S Mux, each stepper consumes 1-3 slots
+  - Step only: up to 32 steppers
+  - Step + Dir: up to 16 steppers
+  - Step + Dir + Enable: up to 10 steppers
+- I2S Direct channels = number of I2S controllers (experimental)
+- C6 and P4 require IDF ≥5.3 (no IDF 4.x support)
 
 #### ESP-IDF version 4.x.y:
 * allows up to 200000 generated steps per second
 * supports up to 14 stepper motors using Step/Direction/Enable Control (Direction and Enable is optional)
 * Steppers' command queue depth: 32
 
 #### ESP-IDF version >=5.3.0:
-* allows up to 200000 generated steps per second
-* supports up to 8 stepper motors using Step/Direction/Enable Control (Direction and Enable is optional)
+* allows up to 200000 generated steps per second for RMT. 40kHz for I2S-MUX.
+* supports up to 8+32 stepper motors using Step/Direction/Enable Control (Direction and Enable is optional)
 * Steppers' command queue depth: 32
 
-### ESP32S2
+#### ESP32 I2S Mux Driver (ESP-IDF >=5.3.0 only)
 
-* reported to work
-* allows up to 200000 generated steps per second ?
-* supports up to four stepper motors using Step/Direction/Enable Control (Direction and Enable is optional)
-* Steppers' command queue depth: 32
+The I2S Mux driver provides an alternative approach for driving multiple stepper motors using the ESP32's I2S peripheral. This is especially useful when you need more steppers than RMT channels provide.
 
-### ESP32S3
+**Overview:**
+The I2S transmitter outputs a 32-bit data word at 250kHz. Each bit corresponds to one output slot (0-31). These signals can be used in two ways:
 
-#### ESP-IDF version 4.x.y:
-* allows up to 200000 generated steps per second ?
-* supports up to eight stepper motors using Step/Direction/Enable Control (Direction and Enable is optional)
-* Steppers' command queue depth: 32
+1. **With external demultiplexer**: Connect a decoder IC (e.g., 74HC154, 74HC138 cascade, or shift registers like 74HC595) to the I2S data pin to decode the 32-bit stream into individual output pins for step, direction, and enable signals.
 
-#### ESP-IDF version >=5.3.0:
-* allows up to 200000 generated steps per second ?
-* supports up to four stepper motors using Step/Direction/Enable Control (Direction and Enable is optional)
-* Steppers' command queue depth: 32
+2. **Direct connection**: Use individual I2S output slots directly as stepper driver inputs. Each slot provides one output signal that toggles at the I2S frame rate.
 
-### ESP32C3
+**Key Features:**
+* Up to 32 output pins from a single I2S transmitter
+* I2S runs at 250kHz sample rate (4µs frame time)
+* Step, direction, and enable pins can all use I2S outputs
+* Suitable for applications requiring many coordinated steppers
 
-* allows up to 200000 generated steps per second ?
-* supports up to two stepper motors using Step/Direction/Enable Control (Direction and Enable is optional)
-* Steppers' command queue depth: 32
+**Limitations:**
+* Requires ESP-IDF 5.3 or later (I2S driver API changed significantly)
+* Minimum speed for I2S Mux is 25µs period (40kHz max step rate)
+* Minimum speed for I2S Direct is 5µs period (200kHz max step rate)
+* Step pulse width is 2.5us for I2S Direct and 4us for I2S MUX
+* I2S Direct: stepper speed adjustable in 1/8us deltas.
+* I2S MUX: stepper speed adjustable in 4us deltas e.g. speed 50us will be 52/48/52/48...
 
-### ESP32C6
+**I2S Direct vs I2S Mux:**
+* **I2S Mux**: Single I2S transmitter drives up to 32 pins. All pins share the same timing.
+* **I2S Direct**: Each stepper gets its own I2S channel. Higher precision timing.
+
+**Initialization:**
+```cpp
+// Initialize I2S Mux with data, bclk, and word select pins
+// Not needed, if I2S direct mode is used
+engine.initI2sMux(data_pin, bclk_pin, ws_pin);
+
+// Connect stepper to I2S mux slot (0-31)
+// PIN_I2S_FLAG automatically selects I2S Mux mode
+stepper = engine.stepperConnectToPin(slot | PIN_I2S_FLAG);
+
+// Direction and enable can also use I2S mux slots
+stepper->setDirectionPin(dir_slot | PIN_I2S_FLAG, dirHighCountsUp);
+stepper->setEnablePin(enable_slot | PIN_I2S_FLAG, activeLow);
+```
+
+**Pin Allocation:**
+The I2S mux uses slot numbers 0-31, which are output on the I2S data line. These can be used in two ways:
+* **With external demultiplexer**: Connect a decoder (e.g., 74HC154, 74HC138 cascade) to the I2S data pin to decode the 32-bit frame into 32 individual output pins for step/direction/enable signals
+* **Direct connection**: Use the I2S data pin directly as a step signal
+
+**Testing and Demo Application:**
+A comprehensive platformio test application with web interface is available in `extras/Esp32StepperDemo/`. 
+This demonstrates:
+* Configuration of multiple steppers via Web UI
+* Real-time position and status monitoring via WebSocket
+* Each I2S slot can be toggled individually
+* I2S mux pin management
+* serial console 115200 asks at startup for Wifi credentials.
+* Sequence automation (not tested)
+
+To build and test:
+```bash
+cd extras/Esp32StepperDemo
+pio run -t upload && pio device monitor
+```
+
+This test application was AI crafted....
 
-* only from esp-idf >=v5.3.0
-* allows up to 200000 generated steps per second ?
-* supports up to four stepper motors using Step/Direction/Enable Control (Direction and Enable is optional)
-* Steppers' command queue depth: 32
 
 ### Raspberry pi pico/pico 2
 
@@ -316,19 +375,37 @@ For the other stepper motors, the rmt module comes into use.
 
 #### ESP-IDF version >=5.3.0:
 
-Only rmt module is supported.
+RMT and I2S Mux/Direct drivers are supported. MCPWM/PCNT is not available in ESP-IDF 5.3+.
+
+#### I2S Mux Driver Implementation
+
+The I2S Mux driver uses the ESP32's I2S transmitter in 16-bit stereo mode at 250kHz sample rate. Each I2S frame (32 bits = 16-bit left + 16-bit right channel) represents one time slot, with each bit corresponding to one output pin.
+
+**Technical Details:**
+* Sample rate: 250kHz, giving 4µs per frame (64 ticks at 16MHz reference)
+* 32 output slots per frame, each slot is one bit
+* Bits are transmitted MSB-first within each byte
+* DMA buffers are filled in the I2S TX-done callback
+* Direction and enable pins are stored in a 32-bit state word, written to each frame's data
+
+**Timing Considerations:**
+* Minimum step period: 25µs for I2S Mux, 5µs for I2S Direct
+* Direction/enable changes have up to 4µs latency
+* All steppers sharing I2S mux are inherently synchronized (same DMA buffer)
 
 #### Both ESP-IDF versions
 A note to `MIN_CMD_TICKS` using mcpwm/pcnt: The current implementation uses one interrupt per command in the command queue. This is much less interrupt rate than for avr. Nevertheless at 200kSteps/s the switch from one command to the next one should be ideally serviced before the next step. This means within 5us. As this cannot be guaranteed, the driver remedies an overrun (at least by design) to deduct the overrun pulses from the next command. The overrun pulses will then be run at the former command's tick rate. For real life stepper application, this should be ok. To be considered for raw access: Do not run many steps at high rate e.g. 200kSteps/s followed by a pause. 
 
-What are the differences between mcpwm/pcnt and rmt ?
+What are the differences between mcpwm/pcnt, rmt, and i2s mux?
 
-|                            | mcpwm/pcnt                              | rmt                                                                           |
-|:---------------------------|:----------------------------------------|:------------------------------------------------------------------------------|
-|Interrupt rate/stepper      | one interrupt per command               | min: one interrupt per command, max: one interrupt per 31 steps at high speed |
-|Required interrupt response | at high speed: time between two steps   | at high speed: time between 31 steps                                          |
-|Module usage                | 1 or 2 mcpcms, up to 6 channels of pcnt | rmt                                                                           |
-|esp32 notes                 | availabe pcnt modules can be connected  | no pcnt module used, so can be attached to rmt output as realtime position    |
+|                            | mcpwm/pcnt                              | rmt                                                                           | i2s mux                         |
+|:---------------------------|:----------------------------------------|:------------------------------------------------------------------------------|:--------------------------------|
+|Interrupt rate/stepper      | one interrupt per command               | min: one interrupt per command, max: one interrupt per 31 steps at high speed | one interrupt per 500µs (all)   |
+|Required interrupt response | at high speed: time between two steps   | at high speed: time between 31 steps                                          | 500µs for all steppers combined |
+|Module usage                | 1 or 2 mcpcms, up to 6 channels of pcnt | rmt                                                                           | 1 i2s                           |
+|Max steppers                | 6 + 8 rmt                               | 8 (ESP32), 4 (ESP32S3)                                                        | 32 (I2S slots) + rmt            |
+|esp32 notes                 | available pcnt modules can be connected | no pcnt module used, so can be attached to rmt output as realtime position    | synchronized outputs            |
+|Min step period             | ~5µs                                    | ~5µs                                                                          | ~25µs                           |
 
 If the interrupt load is not an issue, then rmt is the better choice. With rmt the below (multi-axis application) mentioned loss of synchonicity at high speeds can be avoided. The rmt driver is - besides some rmt modules perks - less complex and way more straightforward.
 
@@ -338,7 +415,7 @@ One specific note for the rmt: If a direction pin toggle is needed directly afte
 
 ### ESP32S2
 
-This stepper driver uses rmt module.
+This stepper driver uses rmt module only.
 
 ### ESP32S3
 
@@ -347,7 +424,8 @@ The ESP32S3's rmt module is similar to esp32c3 with 4 instead of 2 channels and
 #### ESP-IDF version 4.x.y:
 This stepper driver uses mcpwm/pcnt + rmt modules. Can drive up to 8 motors. Tested with 6 motors (not by me). 
 #### ESP-IDF version >=5.3.0:
-This stepper driver uses rmt modules. Can drive up to 4 motors. 
+This stepper driver uses rmt modules. Can drive up to 4 motors.
+I2S Mux driver is also available with same capabilities as ESP32 (see ESP32 I2S Mux section above). 
 
 ### ESP32C3
 
