git.giacomolli.uk - onehouse/blob - doc/m31.rst

   1 ###############
   2  Ebyte M31 I/O
   3 ###############
   4
   5 The ``driver/m31`` package defines one host and up to fifteen expansion
   6 modules. A module's slice index is its slot. The host has eight digital
   7 inputs and eight digital outputs. Mixed expansions add eight of each,
   8 input expansions add sixteen inputs, output expansions add sixteen
   9 outputs, and analog expansions add eight voltage outputs.
  10
  11 Each point uses ``m{slot}.di{channel}``, ``m{slot}.do{channel}``, or
  12 ``m{slot}.ao{channel}``. Inputs, coils, and analog registers have
  13 independent zero-based address ranges that continue across modules.
  14 Configure every physical analog output channel for zero through ten
  15 volts before operation. The driver does not configure the module's
  16 output range. Analog registers represent zero through ten volts as zero
  17 through 10000. Hardware pulse widths are whole milliseconds from 50
  18 through 65535. Their width registers start at ``0x30d4`` and their
  19 output-mode registers start at ``0x32c8``, both indexed by coil address.
  20 Mode zero is level control and mode one is pulse control.
  21
  22 Descriptors use manufacturer ``ebyte`` and firmware ``unknown``. The
  23 package does not read the host identity registers. Pulse capabilities
  24 accept commands but do not report transient coil state. Input
  25 capabilities are read-only.
  26
  27 Tests verify topology and descriptor values without a physical module.
  28 They do not confirm physical expansion limits or relay timing under
  29 load. The conservative sixteen-module limit includes the host.
  30
  31 ***************
  32  Modbus client
  33 ***************
  34
  35 ``NewTCPClient`` supplies a caller-owned, serialized connection through
  36 ``Client``. Connect selects the configured unit and has a two-second
  37 timeout. A request has a one-second write deadline and a two-second
  38 response deadline, both measured from its start. Caller deadlines and
  39 cancellation can stop it earlier. Each response must match the
  40 transaction, unit, function, length, and write acknowledgement.
  41 Supported functions are 01, 02, 03, 05, 15, and 16. No external Modbus
  42 package is required.
  43
  44 In-memory stream tests check request bytes, response validation,
  45 exceptions, truncation, cancellation, and timeouts. They do not verify a
  46 physical host or TCP network behavior.
  47
  48 *******************
  49  Polling lifecycle
  50 *******************
  51
  52 ``New`` validates ``Settings`` and takes a shared publisher and a
  53 client. The caller runs both the publisher and the integration through
  54 ``driver.Run``. The command keeps its explicit driver list empty and
  55 does not open hardware connections.
  56
  57 Every connection writes and reads back all digital output modes. Pulse
  58 outputs also write and verify their widths before online. The first
  59 complete read establishes a baseline without events. A later input
  60 change sends retained state followed by a pressed or released event. All
  61 events from one input read share its completion time, before coil and
  62 analog reads. A steady output or analog change sends reported state.
  63 Pulse coils do not send transient feedback.
  64
  65 A device error publishes offline and retries after one second, doubling
  66 to thirty seconds until a complete baseline succeeds. Device failures do
  67 not log inside the integration. Publication and cleanup failures return
  68 to the runner. Cancellation closes the client without a false offline
  69 publication. Refresh requests cached snapshots through the shared
  70 publisher without repeating events or physical work.
  71
  72 Polling can miss an edge that starts and ends between reads. It does not
  73 expose input counters. A configured poll interval is a target, not a
  74 guaranteed edge latency. Tests use fake clients and simulated time for
  75 baseline, transitions, pulse verification, reconnect, refresh, shutdown,
  76 and error propagation. Physical timing remains unverified.