Merge pull request #5446 from tonhuisman/feature/P180-enable-extra-device-flags

[P180] Enable CustomVTypeVar and MQTTStateClass device flags

Author: TD-er

docs/source/Plugin/P180.rst

@@ -30,6 +30,17 @@ This enables the implementation of yet unsupported I2C devices or use I2C device
 
 .. warning:: This plugin is in the 'pro' category of plugins (i.o.w. not really *Easy* to use), and requires in-depth studying of the datasheet for the device, extracting the required commands and calculation(s) for implementing correct usage. (Some examples available below)
 
+Example device configurations
+-----------------------------
+
+* :ref:`aht2x-temperature-humidity-sensor`
+* :ref:`m5stack-ain4-20ma-unit-module`
+* :ref:`bosch-bmp58x-temp-baro`
+* :ref:`tiny-code-reader-qr-code-reader`
+* :ref:`sensirion-sdp-810-differential-pressure-sensor`
+* :ref:`tf-luna-lidar-distance-sensor`
+* :ref:`qmc6310-3-axis-magnetic-sensor`
+
 Configuration
 -------------
 
@@ -189,6 +200,8 @@ A few warnings though:
 Example I2C command sequences
 -----------------------------
 
+.. _aht2x-temperature-humidity-sensor:
+
 AHT2x Temperature / Humidity sensor
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -231,6 +244,8 @@ Command sequence explanation:
 
 |
 
+.. _m5stack-ain4-20ma-unit-module:
+
 M5Stack AIN4-20mA Unit / Module
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -277,6 +292,8 @@ This device supports adjusting the calibration to the current current that is fl
 
 |
 
+.. _bosch-bmp58x-temp-baro:
+
 Bosch BMP58x Temp/Baro
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -341,6 +358,8 @@ Command sequence explanation:
 
 |
 
+.. _tiny-code-reader-qr-code-reader:
+
 Tiny Code Reader (QR-code reader)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -409,6 +428,8 @@ This device needs a Rule to handle the result, as we can't store string values i
 
 |
 
+.. _sensirion-sdp-810-differential-pressure-sensor:
+
 Sensirion SDP-810 Differential pressure sensor
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -472,12 +493,127 @@ This command sequence is nearly the same as with the Continuous measurement, exc
 
 |
 
+.. _tf-luna-lidar-distance-sensor:
+
+TF-Luna Lidar distance sensor
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The somewhat popular laser-distance sensor, with a range of 0.2 to 8 meter, TF-Luna, can be configured to use I2C as the communication protocol, instead of the default RS232 serial protocol, by connecting pin 5 of the sensor to GND on startup.
+
+The command sequence is based on documentation from this `WaveShare page <https://www.waveshare.com/wiki/TF-Luna_LiDAR_Range_Sensor>`_
+
+.. note:: The checksum available from the sensor measurements is ignored!
+
+When only retrieving the ``distance`` from the sensor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The plugin should be configured with these settings:
+
+* **I2C Address (Hex)**: ``0x10``
+
+* **Output Data Type**: ``Single``
+
+* **Interval**: can be set to 1 second to retrieve a measurement every second.
+
+* **Values**: the name can be changed to Distance, and the number of decimals 0. Stats can be enabled, as desired. The Unit of Measure should he set to ``cm``, and the Value Type to ``Distance``
+
+* **Cache-Name 1 (optional)**: Fill with a useable name, f.e. ``distance``, so the I2C Command sequence is cached for much improved execution-performance.
+
+* **I2C Commands 1**:
+
+``put.u8.0;delay.5;get.b.7;eval;calc.0x{substring:4:6:%h%}*256+0x{substring:2:4:%h%}``
+
+Command sequence explanation:
+
+* ``put.u8.0`` : Announce data fetch
+* ``delay.5`` : Give the sensor a few msec to prepare
+* ``get.b.7`` : Read 7 bytes (entire available buffer)
+* ``eval`` : Make data available for processing
+* ``calc.0x{substring:4:6:%h%}*256+0x{substring:2:4:%h%}`` : Fetch byte 1 (* 256) + byte 0 to calculate distance in cm, value is set to Values 1 field
+
+When retrieving both ``distance`` and ``signal strength`` from the sensor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The plugin should be configured with these settings:
+
+* **I2C Address (Hex)**: ``0x10``
+
+* **Output Data Type**: ``Dual``
+
+* **Interval**: can be set to 1 second to retrieve a measurement every second.
+
+* **Values**: the first name can be changed to ``Distance``, and the number of decimals 0. Stats can be enabled, as desired. The Unit of Measure should he set to ``cm``, and the Value Type to ``Distance``, the second name can be changed to f.e. ``SignalStrength``, and number of decimals to 0. Stats can be enabled, as desired. No further settings for this value, as it has an undefined unit and value type.
+
+* **Cache-Name 1 (optional)**: Fill with a useable name, f.e. ``distance``, so the I2C Command sequence is cached for much improved execution-performance.
+
+* **I2C Commands 1**:
+
+``put.u8.0;delay.5;get.b.7;eval;calc.0x{substring:4:6:%h%}*256+0x{substring:2:4:%h%};value.1;calc.0x{substring:8:10:%h%}*256+0x{substring:6:8:%h%};value.2``
+
+NB: The fields for **Cache-Name 2** and **I2C Commands 2** are left empty, the entire command sequence is combined into the first command sequence, as the complete data set is read and the separate values calculated and assigned in a single command sequence. This makes processing more efficient.
+
+Command sequence explanation:
+
+* ``put.u8.0`` : Announce data fetch
+* ``delay.5`` : Give the sensor a few msec to prepare
+* ``get.b.7`` : Read 7 bytes (entire available buffer)
+* ``eval`` : Make data available for processing
+* ``calc.0x{substring:4:6:%h%}*256+0x{substring:2:4:%h%}`` : Fetch byte 1 (* 256) + byte 0 to calculate distance in cm
+* ``value.1`` : current value, Distance, set to Values 1 field
+* ``calc.0x{substring:8:10:%h%}*256+0x{substring:6:8:%h%}`` : Fetch byte 3 (* 256) + byte 2 to calculate signal strength (unknown unit)
+* ``value.2`` : current value, Signal strength, set to Values 2 field
+
+|
+
+.. _qmc6310-3-axis-magnetic-sensor:
+
+QMC6310 3-axis magnetic sensor
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This sensor provides a 3-axis directional signal, as documented in the QST Corp `QMC6310 Datasheet <https://www.qstcorp.com/upload/pdf/202202/%EF%BC%88%E5%B7%B2%E4%BC%A0%EF%BC%8913-52-17%20QMC6310%20Datasheet%20Rev.C(1).pdf>`_ (url includes some Chinese characters).
+
+The plugin should be configured with these settings:
+
+* **I2C Address (Hex)**: ``0x1C``
+
+* **Output Data Type**: ``Triple`` To activate this setting, the page must be submitted to show the extra input fields.
+
+* **Interval**: Can be set in the seconds range to retrieve a measurement often.
+
+* **Values**: The names can be changed to ``x``, ``y`` and ``z``, and the number of decimals to 0. Stats can be enabled, as desired. The Unit of Measure is undocumented.
+
+* **I2C Init Commands** sequence for initializing the sensor:
+
+``write.u8.0x29.0x06;write.u8.0x0B.0x00;write.u8.0x0A.0xCD``: Initialize the sensor according to the datasheet, Normal mode, field range 8 Gauss, output data rate 200 Hz, over-sample ratio 8, down-sample ratio 8.
+
+* **I2C Exit Commands** sequence for shutting down the sensor:
+
+``write.u8.0x0A.0x00``: Set sensor in Suspend mode.
+
+* **Cache-Name 1 (optional)**: Fill with a useable name, f.e. ``x``, so the I2C Command sequence is cached for much improved execution-performance.
+
+* **I2C Commands 1**: ``read.16le.0x01`` Read 2 bytes starting at register 1, the ``x`` value, and store in first Value field.
+
+* **Cache-Name 2 (optional)**: Fill with a useable name, f.e. ``y``.
+
+* **I2C Commands 2**: ``read.16le.0x03`` Read 2 bytes starting at register 3, the ``y`` value, and store in second Value field.
+
+* **Cache-Name 3 (optional)**: Fill with a useable name, f.e. ``z``.
+
+* **I2C Commands 3**: ``read.16le.0x05`` Read 2 bytes starting at register 5, the ``z`` value, and store in third Value field.
+
+To reduce the logging content, **Single event with all values** can be enabled, to generate a single event ``<task-name>#All`` with all values as argument, and thus reduce the logging from 3 lines per Interval to a single line per Interval.
+
+|
+
 Change log
 ----------
 
 .. versionchanged:: 2.0
   ...
 
+  |added| 2025-12-08 Add index to example configurations.
+
   |added|
   2025-04-19 Initial release version.
 

src/_P180_I2C_generic.ino

@@ -6,6 +6,7 @@
 // #######################################################################################################
 
 /** Changelog:
+ * 2025-12-06 tonhuisman: Enable CustomVTypeVar and MQTTStateClass device options, as any type of sensor can be connected
  * 2025-06-04 tonhuisman: Add [<taskname>#log] to Get Config to fetch the current Parsing and execution log setting
  * 2025-06-03 tonhuisman: Restore PLUGIN_GET_CONFIG_VALUE support, to allow I2C operations to be executed and return a value without
  *                        defining extra I2C Command definitions. Not available for LIMIT_BUILD_SIZE builds
@@ -135,6 +136,8 @@ boolean Plugin_180(uint8_t function, struct EventStruct *event, String& string)
       dev.TimerOptional  = true;
       dev.FormulaOption  = true;
       dev.PluginStats    = true;
+      dev.CustomVTypeVar = true;
+      dev.MqttStateClass = true;
       break;
     }
 

src/src/PluginStructs/P180_data_struct.cpp

@@ -152,7 +152,7 @@ bool P180_data_struct::plugin_write(struct EventStruct *event,
     } else if (equals(sub, F("exec")) && hasPar3 && hasBusCmd) {     // genI2c,exec,<cache_name>[,<TaskValueIndex>]
       cmds = busCmd_Helper->parseBusCmdCommands(par3, EMPTY_STRING); // Fetch commands from cache by name
     } else if (equals(sub, F("log")) && hasPar3) {                   // genI2c,log,<1|0>
-      _showLog       = event->Par3 != 0;
+      _showLog       = event->Par2 != 0;
       P180_LOG_DEBUG = _showLog ? 1 : 0;
 
       if (hasBusCmd) {