# Raspberry Pi integration — known target

UPDATE: Real generated C/M4 files have been supplied and component/ is prepared.
Start with BUILD_ON_PI.md; the interface-generation steps below are historical
reference and do not need to be repeated.

User-reported: aarch64, 64-bit userland, codesyscontrol 4.16.0.0;
development environment CODESYS 3.5 SP22. Supplied ExtensionSDK inspected.
The runtime package reports `all`, so verify the actual component/runtime
binary architecture on the Pi after building. No ARM binary is included here.

## Generate the official CODESYS interface

1. Create an **Empty library** named `CmpAtomModbus.library`. In Project
   Information set Title = `CmpAtomModbus`, Version = `0.2.0.0`.
2. Add one Function named `atMbCall_cext`, return type UDINT. Paste the matching
   declaration from atMbCall_cext.st (the FUNCTION line may already exist in
   the declaration editor; do not duplicate it).
3. Right-click the function > Properties > Build > **External implementation**.
4. Build > **Generate Runtime System Files**. Select **M4 interface file** and
   **C stub file**. Component name must be `CmpAtomModbus`.
5. Send the generated `CmpAtomModbus.c` and `CmpAtomModbusItf.m4` back for actual
   interface validation. The generated signature/checksum must be preserved;
   a plain `.so` exported symbol alone is insufficient for the IEC call.

## Prepare and build on Pi after generating those files

Keep your ExtensionSDK directory outside this source folder. Install host build
tools on the Pi if missing:

```sh
sudo apt-get install build-essential m4 sed dos2unix make
```

From the atom-modbus source folder, with the generated files in `generated/`:

```sh
python3 tools/prepare_component.py generated/CmpAtomModbus.c generated/CmpAtomModbusItf.m4 --sdk ../ExtensionSDK
make -C component SDKDIR="$(realpath sdk/ExtensionSDK)" all
file component/out/libCmpAtomModbus.so
```

The last output must identify an AArch64 ELF shared object. Native compilation
on the Pi avoids guessing a cross-toolchain or glibc version. The preparation
script validates field names from the real generated M4 struct and preserves
the generated interface. Its parser has only been exercised with a synthetic
fixture until the real generated files are supplied.

The generated component adds cleanup at `CH_EXIT`, after runtime tasks have
stopped. This does not yet handle application-only lifecycle changes.

## Install only after final review/bench test

The SDK's documented method is to place the component in `/usr/lib`, stop the
runtime and add `Component.N=CmpAtomModbus` under `[ComponentManager]` in
`/etc/CODESYSControl_User.cfg`, choosing an UNUSED component index. Restart the
runtime and inspect `/var/log/codesyscontrol.log`. Use a maintenance
window: a runtime restart stops the PLC application.

Alternatively, package it using the C-Implemented Library object for the exact
Raspberry Pi device target. That packaging still requires CODESYS IDE work.

## First bench exercise

Use a separate test application/task. Open -> configure -> enable -> tick every
scan until Ready. Submit an FC03 read. Tick until Done/Error. On Done, CopyRead,
then Acknowledge. On Error, record diagnostics, Acknowledge and allow recovery.
Do not submit writes during initial connection testing. Use a monotonic
millisecond clock (e.g. SysTimeGetUs value divided by 1000).

Preserve your existing production atomLibrary until the IEC wrapper and
stop/start/download/online-change handling have passed target tests.