Industrial integration lab: read a register without losing its meaning¶
Purpose: decode a fictional sensor through a real localhost TCP connection, then distinguish a valid packet from a valid measurement. Prerequisites: Python bytes, hexadecimal, and the industrial overview. Layers and roles: embedded interfaces, networking, and robot integration; preparation for embedded robotics and automation engineering. Allow 15 minutes for setup, 30 for execution and packet decoding, and 45 for fault analysis.
The worked example uses generated data and a read-only subset of Modbus TCP.
The server binds only to 127.0.0.1, chooses an unused port, and exits after its
scripted exchanges. No PLC, physical sensor, robot, or external endpoint is used.
You need Python 3.10+ and permission to open a local TCP socket. The optional
library exercise additionally downloads one small pinned Python package.
1. Three agreements are needed¶
A network connection tells you that bytes can move. A protocol tells you which bytes belong together and what operation they encode. An application contract tells you what a value means. Keep all three visible:
| Layer | This fixture | A defect the lower layer cannot detect |
|---|---|---|
| Transport | TCP stream between two local sockets | A peer sends a valid but wrong transaction |
| Protocol | Unit 1, function 03, two holding registers | Register 0 represents the wrong engineering quantity |
| Application | Register 0 = temperature in hundredths °C; register 1 = supply in mV | The sensor stopped updating while reads still succeed |
Our fictional map contains [2500, 5000], meaning 25 °C and 5 V. These scales
are supplied by this exercise, not by Modbus. A device manual must define its
own map, signedness, scale, invalid values, and any multi-register word order.
A display label such as 40001 is not the same thing as the zero-based address
encoded in the request. Confirm the device's convention rather than subtracting
a prefix from every unfamiliar label. The protocol organization maintains the
Modbus specifications.
2. Decode a complete exchange by hand¶
We request two holding registers starting at address zero. Each multibyte field in this example uses big-endian byte order:
request: 12 34 00 00 00 06 01 03 00 00 00 02
tx proto length unit fn address count
response: 12 34 00 00 00 07 01 03 04 09 c4 13 88
tx proto length unit fn bytes value0 value1
0x1234 identifies this transaction. Protocol identifier zero selects Modbus.
The length counts the unit identifier plus PDU, so it is 6 in the request
and 7 in the response. It does not count the first six header bytes. Function
03 reads holding registers. The response byte count is four because two
16-bit registers occupy four bytes. 0x09c4 = 2500, and 0x1388 = 5000.
The response must match the outstanding transaction, unit, function, and expected
data length. Reading unknown address 100 produces function 83, exception
code 02 (illegal data address). That is an application-visible failure, not a
successful empty reading. A request for an unsupported function receives exception
code 01; this teaching server has no write implementation. Compare the framing
logic with libmodbus's TCP implementation.
3. TCP does not preserve your send boundaries¶
One send can arrive in several reads; several sends can arrive together. Calling
recv(12) does not guarantee twelve returned bytes. The implementation first
collects the seven-byte header, checks its bounded length, then collects exactly
the remaining PDU. A peer closing early raises an error. It leaves the following
frame in the stream for the next call.
Separate sends in a real socket experiment do not force separate receives. The tests therefore use both actual TCP exchanges and a deterministic stream fixture that returns short reads at every chunk size. This proves a property that a successful run on an unloaded loopback interface could miss.
From the repository root, run these tested here commands:
cd "Phase 5 - Advanced Topics and Specialization/Track D - Robotics/Industrial and Embedded Robotics/labs"
python3 -m unittest -v
python3 modbus_read.py > my-modbus-result.json
Expected: 11 tests pass. The result contains three exchanges: registers
[2500, 5000], illegal-address exception 2, and unsupported-function exception
1. The independent golden packet, truncations, incorrect length, mismatched
transaction/unit, excessive quantity, and the end of the 16-bit address space
are checked. Compare with the recorded output.
The socket timeout bounds each blocking operation in this small experiment. It is not an end-to-end control deadline, a network benchmark, or proof of a hard real-time system. The fixture does not implement a full Modbus server.
4. Repeat with an actual maintained client¶
The optional exercise was executed with PyModbus 3.16.1. Install it in a
separate environment from the same labs directory:
python3 -m venv .venv-modbus
.venv-modbus/bin/python -m pip install 'pymodbus==3.16.1'
.venv-modbus/bin/python -m pip check
.venv-modbus/bin/python pymodbus_client.py --output my-library-result.json
The script starts its own local teaching server, connects a real client, reads
the two registers, then checks the illegal-address response. Expected:
checks_passed: 2, registers: [2500, 5000], and exception code 2. The
recorded library result includes source hashes
and the request bytes produced by the library.
For this pinned version the call is
client.read_holding_registers(0, count=2, device_id=1); older examples may use
different parameter names. Check .isError() before consuming .registers.
Serialize calls on one client: the synchronous client is not thread-safe.
See the versioned client API
and 3.16.1 release.
5. A good packet can still be an old measurement¶
Suppose reads complete every 20 ms while the physical sensor refreshes every 100 ms. Five successful reads can contain the same sample. A transaction ID correlates a response with a request; it does not identify a new sensor sample. TCP delivery likewise does not prove that the device's acquisition task is live.
For a real integration, define a measurement counter or capture timestamp if the device supplies one, the counter wrap/reset rules, and the allowed acquisition-to-use age. If only host receive time exists, label it honestly: it cannot reveal an unknown device-side delay. A multi-register read also needs the device's guarantee about whether those values form one coherent acquisition. A network timeout requires a documented controller response; ordinary protocol success does not establish a protective function.
For example, a conveyor at 0.5 m/s moves 0.05 m during 100 ms. Converting a temperature register correctly says nothing about whether a position estimate is recent enough for a grasp. Connect this timing argument to the capture-time perception lab.
6. Variations and answer guidance¶
- Change register 0 to 3125. Predict the application value before executing.
- Change one response transaction byte while leaving its measurement unchanged. Explain why an apparently plausible value must be rejected.
- Sketch a device record containing value, acquisition counter, and a validity flag. Define how a consumer treats repeated counters, reconnects, and an invalid sensor reading. Do not add a physical endpoint to this lab.
Answers and completion criterion
- The map specifies hundredths °C, so the result is 31.25 °C. A different device's map could specify another scale or signed representation.
- A valid value from another outstanding or delayed request cannot satisfy this request. Payload plausibility does not replace transaction correlation.
- A repeat can be a valid repeat of an old acquisition; it is not new evidence. Reconnect/reset creates an epoch ambiguity that the contract must resolve. Invalid sensor data must remain invalid rather than becoming a default zero. The device's update and coherence guarantees determine what is defensible.
Finish with your packet annotation, both raw outputs if the optional dependency is available, one failing mutation and its explanation, and a hypothetical measurement-freshness contract. State separately that no physical I/O, TLS/authentication, serial bus, timing guarantee, or protocol certification was tested. Continue to the ROS integration lab to see how reliable delivery and application backlog differ.