89 lines
5.0 KiB
Markdown
89 lines
5.0 KiB
Markdown
# 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
|