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 one-second
  37 timeout. Each write has a one-second deadline. Each response has a
  38 two-second deadline measured after the request write. Caller deadlines
  39 and 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.
  77
  78 *****************
  79  Output commands
  80 *****************
  81
  82 The shared router supplies one device FIFO for singles and batches. The
  83 driver checks ownership, output access, value type, and expiry before
  84 physical work. Steady outputs accept Boolean values. Pulse outputs
  85 accept only true and complete after the function 05 acknowledgement,
  86 without coil readback or transient reports. Analog outputs accept JSON
  87 numbers from zero through ten volts and round them to millivolts. Exact
  88 range checks precede floating-point conversion.
  89
  90 A batch accepts steady digital outputs only. It sorts eligible targets
  91 by coil address, writes each contiguous range with function 15, and uses
  92 function 05 for an isolated target. Gaps remain unchanged. It reads the
  93 complete coil range once after all writes. A transport failure fails all
  94 pending members, including those in an earlier successful range. A
  95 mismatch fails only that member. Commands that expire before their write
  96 are rejected. Physical writes also have the earliest member deadline. If
  97 an expiry rejection cannot be sent after an earlier range is written,
  98 the driver reads back that range and records its outcomes before it
  99 returns the publication failure. A readback failure records failed
 100 outcomes, so replay cannot repeat the earlier physical writes.
 101
 102 Changed feedback is sent before results. Each changed commanded point
 103 has its command ID as causation. Unrelated output changes have no
 104 command cause. Equal feedback needs no second report. The framework
 105 ledger records all outcomes before feedback or result publication, so a
 106 failed send cannot cause another physical action on replay. A repeated
 107 command reuses its first result ID, time, status, and reason. The ledger
 108 is memory-only and bounded to 256 records for the assembly. An eviction
 109 or process restart removes that duplicate protection.
 110
 111 Commands received during device backoff are rejected if invalid or
 112 expired, and fail as unavailable otherwise. No command executes before
 113 the connection setup and baseline complete. Shutdown does not retry a
 114 physical action. Results use fixed failure reasons without transport
 115 addresses or untrusted response data. Drivers return errors and do not
 116 log them. Publication and independent cleanup failures stop the driver
 117 through the runner.
 118
 119 Fake tests cover single writes, cross-bank batches, gaps, partial
 120 transport failure, mismatches, pulses, analog boundaries, expired work,
 121 cancellation, duplicate replay, and failed feedback or result sends.
 122 They do not verify electrical simultaneity, contact timing, hardware
 123 interlocks, or physical pulse width. Local motor protection remains
 124 necessary when network commands control moving equipment.
 125
 126 A caller cancellation interrupts blocked transport work through its
 127 deadline. A timeout caused only by that interruption is a context stop
 128 for the runner. A joined independent transport or cleanup failure stays
 129 a failure. Operation timeouts while the worker context is active remain
 130 device failures and enter reconnect recovery.