[daniel-p-carvalho]

Summary

Add the server side of FC20 (Read File Record) and FC21 (Write File Record) to nxmodbus, sections 6.14 and 6.15 of the Modbus Application Protocol Specification V1.1b3. They move whole files, such as a configuration or a firmware image, to a device that only has a Modbus link.

• New options NXMODBUS_FUNC_READ_FILE and NXMODBUS_FUNC_WRITE_FILE, both default n so existing configurations do not grow.
• The data stays with the application: a new file_cb in struct nxmb_callbacks_s gets one group of records (file, record, nregs) and reads or writes the buffer in wire order. -ENOENT becomes exception 2.
• Every sub-request is validated before the first callback. A write is not atomic, as the specification does not make it so.
• examples/nxmbserver gets two RAM files to exercise both functions.

Impact

Only users who enable the new options are affected. On an Arm Cortex-M4 the handlers take 612 and 362 bytes of code. The new file_cb member sits before priv in struct nxmb_callbacks_s, so a structure initialized by position would break; nothing in the tree does that. The user documentation (function code list and options) will follow in a PR to nuttx.

Testing

Host: Linux x86_64, arm-none-eabi-gcc 15.2.1. Target: NUCLEO-L432KC, nxmbserver as the init task on USART2 (ST-LINK VCP), RTU 115200 8E1, nuttx master (846e525657) plus this PR.

Client: pymodbus 3.16.1, 11 cases: both examples of the specification, 100-record reads and writes, two groups in one request, and the exceptions (file or record out of range, response over 0xf5 bytes). The handlers were also run on the host against stub headers under AddressSanitizer and UBSan.

Client output

ok:   read: two groups (file 1 records 0-9, file 2 records 5-6)  [[0, 1, 2, 3, 4, 5, 6, 7, 8, 9], [4101, 4102]]
ok:   read: all 100 records of file 2
ok:   write: 5 records to file 1 at record 20
ok:   read back (neighbours untouched)
ok:   write: two groups in one request
ok:   write and read back 100 records (200 bytes)
ok:   read: file 3 does not exist -> exception 2  got 2
ok:   read: record 99 + 2 registers (past the end) -> exception 2  got 2
ok:   read: record 10000 -> exception 2  got 2
ok:   write: file 9 does not exist -> exception 2  got 2
ok:   read: 123 registers (response over 0xf5 bytes) -> exception 3  got 3

0 failures

[cederom]

Great stuff thank you @daniel-p-carvalho :-)

Please also provide documentation with examples in https://nuttx.apache.org/docs/latest/applications/industry/nxmodbus/index.html :-)

[daniel-p-carvalho]

Thanks @cederom! The documentation is in apache/nuttx#20966 and has already been approved by @xiaoxiang781216. It covers the options, the file_cb contract and error mapping, and the file records served by nxmbserver. The example server can be used to try both functions. I'd rather keep that PR as it is now; worked examples can follow in a separate documentation PR if you think they're needed.