first commit

2026-09-30 21:17:41 -06:00
commit 07244fc761
57 changed files with 30094 additions and 0 deletions
@@ -0,0 +1,72 @@
+# 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.