Codesys-Library-Atom-Modbus/codesys/PI_SETUP.md

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:

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

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

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.