2.3 KiB
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.