Merge pull request #5126 from tonhuisman/feature/P054-fix-some-gpio-i…

…ssues-for-esp32

[P054] Allow GPIO configuration for ESP32 units

docs/source/Plugin/P054.rst

@@ -1,4 +1,4 @@
-.. include:: ../Plugin/_plugin_substitutions_p05x.repl
+.. include:: ../Plugin/_plugin_substitutions_p05x.repl
 .. _P054_page:
 
 |P054_typename|
@@ -21,15 +21,59 @@ Maintainer: |P054_maintainer|
 
 Used libraries: |P054_usedlibraries|
 
-Supported hardware
-------------------
-
 |P054_usedby|
 
-.. Commands available
-.. ^^^^^^^^^^^^^^^^^^
+Description
+-----------
+
+For controlling DMX512 equipment, this plugin can be used for sending commands to a DMX bus. As an ESP only has a 5V compatible serial interface, usually a RS485 or DMX converter is needed to connect to the DMX bus.
+
+This plugin can only send out commands to the DMX bus, no receiving or recording features are available.
+
+Configuration
+-------------
+
+.. image:: P054_DeviceConfiguration.png
+
+* **Name** In the Name field a unique name should be entered.
+
+* **Enabled** When unchecked the plugin is not enabled.
+
+Actuator
+^^^^^^^^
+
+See: :ref:`SerialHelper_page`
+
+.. warning:: The selected serial port **must** use on-ESP GPIO pins, as the DMX protocol has some specific coding that is not supported by regular serial chips, and is implemented by directly interacting with the ESP TX pin.
+
+Example selection list (taken from an ESP32-C6 configuration):
+
+.. image:: P054_SerialPortOptions.png
 
-.. .. include:: P054_commands.repl
+* *HW Serial0*: First serial port, usually also in use for the serial log, so should best be avoided.
+
+* *HW Serial1*: Secondary serial port. Selected as the default, and required to be used on ESP8266.
+
+* *HW Serial2*: (Not available on an ESP32-C6, but is available on some other ESP32 models) Can be used.
+
+* *SW Serial*: Can be tried, and used if working as intended, but should better be avoided because of the high serial speed (250000 baud).
+
+* *USB HWCDC*: Can not be used.
+
+* *USB CDC*: Can not be used.
+
+* *I2C Serial*: Can not be used.
+
+Device Settings
+^^^^^^^^^^^^^^^
+
+* **Channels**: The number of DMX channels to be used. Determines the size of a memory buffer. Keep as small as possible, especially on ESP8266, where available memory can be limited.
+
+
+Commands available
+^^^^^^^^^^^^^^^^^^
+
+.. include:: P054_commands.repl
 
 .. Events
 .. ~~~~~~
@@ -42,6 +86,8 @@ Change log
 .. versionchanged:: 2.0
   ...
 
+  |added| 2024-09-29: Add selection for Serial port and GPIO on ESP32.
+
   |added|
   Major overhaul for 2.0 release.
 

docs/source/Plugin/P054_commands.repl

@@ -0,0 +1,39 @@
+.. csv-table::
+    :header: "Command Syntax", "Extra information"
+    :widths: 20, 30
+
+    "
+    | ``dmx,log``
+    ","
+    | List the current content of the send-buffer to the log.
+    "
+    "
+    | ``dmx,test``
+    ","
+    | Fills the send-buffer with random data and sends that to the connected devices.
+    "
+    "
+    | ``dmx,on``
+    ","
+    | Fills the send-buffer all \'255\' values and sends that to the connected devices to turn everthing on.
+    "
+    "
+    | ``dmx,off``
+    ","
+    | Fills the send-buffer all \'0\' values and sends that to the connected devices to turn everthing off.
+    "
+    "
+    | ``dmx,<channel>=<value>[,<value>[,<channel>=<value>]]``
+
+    | ``channel``: Channel number from 1 .. **Channels** set in the configuration.
+
+    | ``value``: Numeric value between 0 and 255 (inclusive) to set for the channel.
+    ","
+    | Fills the send-buffer given value(s) for the channel and sends that to the connected devices.
+
+    | If no channel is used with a value, it is set for the next channel. The channel is initially set to 1.
+
+    | Multiple values, optionally with a channel prefixed, can be provided and will be processed until no more data is found.
+
+    | Also, other subcommands (not including ``dmx``) can be used, f.e. setting up some channel data and adding a ``,log`` at the end to list the current buffer content to the log output.
+    "

docs/source/Plugin/_plugin_substitutions_p05x.repl

@@ -53,7 +53,7 @@
 .. |P054_name| replace:: :cyan:`DMX512 TX`
 .. |P054_type| replace:: :cyan:`Communication`
 .. |P054_typename| replace:: :cyan:`Communication - DMX512 TX`
-.. |P054_porttype| replace:: `.`
+.. |P054_porttype| replace:: `Serial`
 .. |P054_status| replace:: :yellow:`COLLECTION`
 .. |P054_github| replace:: P054_DMX512.ino
 .. _P054_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_P054_DMX512.ino