first commit

docs/API.md

@@ -0,0 +1,54 @@
+# Bridge contract
+
+Return: 0 = accepted, 1..10 = am_error values in atom_mb.h.
+256 = invalid/stale handle, 257 = pool full, 258 = insufficient/null buffer,
+259 = unknown command. Always inspect return codes. A rejected call is not a
+completed Modbus request.
+
+Commands: 1 Open, 2 Close, 3 Enable, 4 Disable, 5 Tick, 6 Submit,
+7 CopyRead, 8 Reconnect, 9 Configure, 10 Acknowledge,
+11 Set request timeout (responseTimeoutMs only; permitted while not busy).
+Configure only while disabled; all three timeouts must be nonzero.
+Open receives an IPv4 DWORD in human octet order: 16#C0A80132 = 192.168.1.50.
+Open returns its handle in status[0], NOT in the function return value.
+Close returns status[0]=0; old handles fail even when their slot is reused.
+Capacity values count WORD/UDINT elements, not bytes. Pass separate buffers.
+CopyRead copies `quantity` WORDs; coils/discretes are unpacked WORD 0/1.
+
+| Status index | Meaning |
+|---|---|
+| 0 | Handle |
+| 1 | State: 0 Disabled, 1 Retry, 2 Connecting, 3 Ready, 4 Sending, 5 Receiving |
+| 2 | Busy |
+| 3 | Done |
+| 4 | Error |
+| 5 | Latest transaction result |
+| 6 | Last failure, retained after success |
+| 7 | OS socket error |
+| 8 | Modbus exception |
+| 9 | Write outcome uncertain |
+| 10 | Connection attempts |
+| 11 | Attempts after first attempt |
+| 12 | Completed successful requests |
+| 13 | Failed requests |
+| 14 | Has successful transaction |
+| 15 | Last success timestamp, low 32 bits |
+| 16 | Last success timestamp, high 32 bits |
+| 17 | Quantity of latest request |
+| 18 | Function code |
+| 19 | Unit ID |
+| 20 | Enabled |
+| 21 | Connect timeout milliseconds |
+| 22 | Whole-request timeout milliseconds |
+| 23 | Retry delay milliseconds |
+
+The PLC wrapper consumes Done/Error then Acknowledge before submitting a new
+request. For Done reads, call CopyRead BEFORE Acknowledge. Completed read data
+is retained internally but CopyRead requires Done. For writes, do not replay
+an uncertain result without an application decision.
+
+All calls to the entire bridge pool must originate from ONE IEC task. Contexts
+and the pool are not thread-safe. Handles must not be RETAIN/PERSISTENT. Closing
+on program disposal and invalidating on application reset/download remain PLC
+wrapper responsibilities. Component unload cleanup alone does not cover an IEC
+application stop or download.