# Integration into atomLibrary

This package contains a working C TCP core and native C bridge, not a compiled
CODESYS library. Target supplied: Raspberry Pi ARM64, runtime 4.16.0.0,
development environment SP22. ExtensionSDK inspected. See PI_SETUP.md for
the original generated-interface step. Real generated C/M4 files are now
supplied and the stub is implemented; use BUILD_ON_PI.md for the prepared build.
Do not map `am_client` directly to an IEC STRUCT: C int, size_t, alignment and
pointer sizes vary by target. Use SDK-generated external function signatures.

## Implemented bridge API

The separate operations below are implemented as commands through ONE external
function, `atMbCall_cext`. See STATUS.md for command IDs and the status array.
The table describes operations rather than separate exported function names.

The bridge uses a fixed pool of contexts and returns generation-checked UDINT handles.
Zero is invalid. Use functions named with `_cext` for the Control SL Extension SDK:

| Function | Purpose |
|---|---|
| atMbOpen_cext | Allocate a fixed context slot; configure numeric IPv4 and port |
| atMbConfigure_cext | Set connect, response and reconnect times in milliseconds |
| atMbEnable_cext | Enable/disable recovery |
| atMbTick_cext | Advance one nonblocking step using monotonic time |
| atMbSubmit_cext | Validate and copy request/write data into the context |
| atMbGetStatus_cext | Copy explicitly sized status fields to IEC outputs |
| atMbCopyRead_cext | Copy validated read result with destination capacity check |
| atMbReconnect_cext | Cancel active transaction and create a fresh connection |
| atMbClose_cext | Close socket and release pool slot |

Only pass pointers during a synchronous call. Never store pointers into IEC
application memory in C across scans or online changes. All operations for one
handle must run from one task. Add target-specific lifecycle handling for stop,
reset, download and online change; close or invalidate old handles before reuse.

## Map existing function blocks

Keep the existing names and data interfaces, with these internal changes:

- `atMbClientTCP`: own the C handle and call Tick once per scan. Keep
  `in_ipAddress`, `in_port`, request registration and priority scheduling.
  Changing the endpoint cancels the transaction and opens the new endpoint.
- `atMbClient`: schedule only while Ready and no request is pending. Complete
  the prior request and copy its read data BEFORE submitting the next request.
  Preserve priority ageing/minimum delay, adding explicit enabled eligibility
  and starvation checks. Enforce the existing 100-request registration limit.
- `atMbReqBase`: snapshot parameters when submitted; validate offset plus
  quantity against destination capacity. Reject overflow rather than silently
  truncate. Quantity zero means disabled at the wrapper level.
- `atMbReadCoil` / `atMbReadDiscrete`: FC01 / FC02; convert unpacked C uint16_t
  values to the actual IEC BOOL array type when copying.
- `atMbReadHolding` / `atMbReadInput`: FC03 / FC04, WORD values.
- `atMbWriteCoil` / `atMbWriteHolding`: FC15 / FC16; preserve `writeNow` semantics.
  Snapshot write values on submit. A failed write is not automatically replayed;
  the application must explicitly decide whether to reissue it.
- `atMbRequestStats`: replace `ModbusFB.Error` with your own transport-error enum;
  keep Modbus exception separately. Keep counts, intervals and HMI indicators.
- `atMbClientRTU`: retain as a separate future transport; this C core does not
  implement serial RTU framing, CRC, timing or serial-port control.

## Status additions

Client: state, connection attempt count, reconnect count, last transport error,
OS socket error, active request index and last successful response time.
Request: Busy/Done/Error, result, exception, consecutive successes/failures,
last successful read time, hasValidData, dataAgeMs, stale and writeUncertain.

Use connection state for transport readiness. Use per-request successful read
timestamps for freshness; another successful request must not refresh stale
data. A valid exception proves the peer responded but does not validate data.
Keep startup/never-read distinct from stale. The C core exposes a CLIENT-wide
last_success timestamp; per-request timestamps belong in the scheduler wrapper.

## Deployment gate

1. Confirm PLC model, CODESYS runtime version, operating system and architecture.
2. Confirm vendor support for custom C components; Control SL SDK support must
   not be assumed on a vendor-supplied PLC runtime.
3. Generate the external declarations/stubs in the matching SDK, implement the
   bridge, compile for the actual target and package its component.
4. Compile the IEC wrapper in CODESYS and exercise stop/start and online change.
5. Bench-test unplug/replug, device restart, long outage, endpoint change, full
   request list, priority fairness and uncertain writes before site deployment.

References:
- https://content.helpme-codesys.com/en/CODESYS%20Control/_rtsl_extension_extension_sdk.html
- https://www.modbus.org/modbus-specifications