Merge pull request #3493 from BsAtHome/backport_2.9_fix-hm2_modbus

Backport hm2_modbus fixes and additions from master

Author: BsAtHome

docs/src/man/man1/mesambccc.1.adoc

@@ -97,6 +97,7 @@ needs to be covered. Differences are primarily byte-ordering.
 
 The byte-ordering is specified with one of the following suffixes:
 
+* `_A`, `_B`
 * `_AB`, `_BA`
 * `_ABCD`, `_BADC`, `_CDAB`, `_DCBA`
 * `_ABCDEFGH`, `_BADCFEHG`, `_CDABGHEF`, `_DCBAHGFE`,
@@ -107,6 +108,18 @@ Modbus standard byte-ordering is big-endian, which is the first in each list
 may use any of the byte-orderings necessary and required because some device
 vendors have not paid attention to the proper on-wire ordering.
 
+The orderings `_A` and `_B` are single byte values from a modbus register. A
+single byte will be taken from the register value. You cannot access successive
+bytes from the same register using these types. (You require a second component
+that de-multiplexes the HAL value(s) into individual bytes from the data stream
+using the hm2_modbus presented pin values.) +
+The ordering `_A` will use the the least significant byte (LSB), with respect
+to the default big endian order for Modbus. Ordering `_B` will use the most
+significant byte (MSB). Note that there is no floating point type when only
+using sizes of one single byte. +
+Single byte values have the additional restriction that they cannot be used as
+data values in '<initlist>/<command>/<data>'.
+
 The byte-ordering suffix is prefixed with S (signed), U (unsigned) or F (float)
 to complete the 'modbustype' attribute value. For example, a 32-bit float in
 big-endian is named `F_ABCD`. A 64-bit signed integer value in little-endian is
@@ -115,6 +128,9 @@ S_HGFEDCBA.
 The types have following ranges and will be clamped to the min/max values if
 the 'clamp' attribute is set in the '<command>':
 
+* 8-bit:
+ ** signed integer [-128..+127] (`S_A`, `S_B`)
+ ** unsigned integer [0..255] (`U_A`, `U_B`)
 * 16-bit:
  ** float16 [-65504.0..+65504.0] (`F_AB`, `F_BA`)
  ** signed integer [-32768..+32767] (`S_AB`, `S_BA`)
@@ -177,9 +193,11 @@ other setup values as attributes:
   and reply sizes. The 'timeout' value can be overridden in the '<command>'
   definitions. Default auto.
 *writeflush* [Boolean]::
-  Set to true when the _very first_ round of write commands must be flushed to
-  synchronize the internal state to the pin state. This flush happens either
-  once when the module starts or each time the module comes out of 'suspend'. +
+  Set to true when the first round of write commands must synchronize the
+  internal state to the pin state. The writes are calculated but not sent to
+  the Modbus device (i.e. flushed). This flush happens either once when the
+  module starts, each time when the module comes out of 'suspend', or
+  specifically for a command when it gets re-enabled. +
   The write flush is necessary when you need to ensure proper and correct pin
   data is present _before_ the Modbus commands start sending potentially
   harmful or invalid data because the pins have not yet been initialized to
@@ -503,6 +521,15 @@ Recognized '<commands>/<command>' attributes:
   The Modbus device to communicate with. The 'device' attribute
   references '<device>[name]'. +
   The device name '`broadcast`' will send the command to all devices on the bus.
+*disabled* [Boolean]::
+  Start the command in disabled state when set, preventing it from being
+  executed. Using the 'disabled' flag is a fine grain per command control.
+  In contrast, 'suspend' works on the entire state machine and controls
+  operation of all commands in an all-or-nothing way. A command in the disabled
+  state can be enabled by toggling the reset pin of the command. Using 'disable'
+  can be particularly useful when you need to delay one particular command
+  while others may already be run. The 'writeflush' setting is honored when
+  coming out of the disabled state. Default false.
 *function* [see link:#_modbus_functions[*MODBUS FUNCTIONS*]]::
   The attribute value is one of the supported Modbus functions.
 *haltype* [see link:#_hal_types[*HAL TYPES*]]::
@@ -571,6 +598,14 @@ Recognized '<commands>/<command>' attributes:
   should be emitted when it does. This differs from 'noanswer' in that a reply
   may be expected within the timeout period but not after the timeout expires.
   This may be required for flaky devices. Default false.
+*unaligned* [Boolean]::
+  Set to true to suppress the alignment warning in multi-register reads or
+  writes where 32-bit or 64-bit values are not aligned to their natural Modbus
+  address boundaries. This is useful for devices that do not care about
+  alignment or do not use Modbus addresses in conventional ways. +
+  Setting 'unaligned' is purely a cosmetic attribute to suppress console
+  clutter when compiling the mbccs file. It has no functional effect on the
+  communication with the device. Default false.
 *writeflush* [Boolean]::
   The override the 'writeflush' value. See '<mesamodbus>[writeflush]' for
   details. Default '<mesamodbus>[writeflush]'.

docs/src/man/man9/hm2_modbus.9.adoc

@@ -142,13 +142,17 @@ Each command in the MBCCB file (not init commands) will generate a set of pins
 to reflect the current state, where `MM` is the command number counting from zero
 (00):
 
+hm2_modbus.N.command.MM.disable (bit, input)::
+  Disable this command on the rising edge of this pin. You need to use the
+  command's corresponding reset pin to re-enable it.
 hm2_modbus.N.command.MM.disabled (bit, output)::
   Set if the command is no longer sent in the commands loop.
 hm2_modbus.N.command.MM.error-code (u32, output)::
   The errno code of the last error. The following error codes can be set:
 
   ** 5,  0x05 (EIO): The receiver detected an overrun, a false start-bit or wrong parity.
   ** 9,  0x09 (EBADF): The reply returned an unsupported function.
+  ** 11, 0x0b (EAGAIN): The command was manually disabled in the mbccb or via the disable pin.
   ** 22, 0x16 (EINVAL): An invalid value was detected (internal error).
   ** 27, 0x1b (EFBIG): The received data packet size exceeds the internally allocated buffer.
   ** 34, 0x22 (ERANGE): The received data packet was too small or the message's length indicator was wrong.
@@ -166,7 +170,9 @@ hm2_modbus.N.command.MM.errors (u32, output)::
   when the command succeeds.
 hm2_modbus.N.command.MM.reset (bit, input)::
   Reset this command's error counter and re-enable the command on the rising
-  edge of the input pin.
+  edge of the input pin. +
+  Note: Re-enabling the command will honor the 'writeflush' setting of the
+  command.
 
 Each mbccb file will generate a set of pins as defined in the mbccb file. See
 *mesambccc*(1) for details.