feat: add servo motor driver (Modbus RTU + CiA402) by Alpaca233 · Pull Request #4 · Cephla-Lab/Squid-Fluidics

Alpaca233 · 2026-03-09T21:24:32Z

Summary

Add modbus_rtu.py — consolidated Modbus RTU client with CRC-16, frame building, retry logic for transport errors (exception responses are not retried)
Add servo_motor.py — CiA402 servo motor driver with state machine, profile position/homing/jog control, abort support (quick_stop on all axes), and ServoMotorSimulation class
58 unit tests covering CRC, frame building, state machine decoding/transitions, and simulation class

Test plan

python -m pytest tests/unit/control/test_modbus_rtu.py -v — 22 tests pass
python -m pytest tests/unit/control/test_servo_motor.py -v — 36 tests pass
Hardware integration test with NiMotion Z4 axis (requires connected hardware)

🤖 Generated with Claude Code

…shaker) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Don't retry Modbus exception responses (application-level errors) - Fix jog() far-position sign inversion - Replace magic hex constants with ControlWordBits expressions - Add abort checks to all polling loops (_wait_for_state/motion/homing) - Add bounds checking to move_relative() in real ServoMotor class - abort() now calls quick_stop() on all axes Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Adds a new NiMotion Z4-oriented servo motor driver to the fluidics control layer, including a consolidated Modbus RTU client and a CiA402-based motion/state-machine implementation, plus unit tests and an implementation plan document.

Changes:

Added fluidics/control/modbus_rtu.py with CRC16, frame builders, and a thread-safe Modbus RTU client with retry logic.
Added fluidics/control/servo_motor.py implementing CiA402 state decoding/transitions, axis configuration, motion primitives, abort support, and a simulation class.
Added unit tests for Modbus RTU primitives/client defaults and servo motor state machine + simulation behaviors; added a hardware drivers plan doc.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
software/fluidics/control/modbus_rtu.py	New Modbus RTU utilities + client used by the servo driver
software/fluidics/control/servo_motor.py	New CiA402 servo driver + simulation and axis configuration
software/tests/unit/control/test_modbus_rtu.py	Unit tests for CRC, frame building, and basic client behavior
software/tests/unit/control/test_servo_motor.py	Unit tests for axis config conversions, state machine, and simulation
software/docs/plans/2026-03-09-hardware-drivers.md	Implementation plan/reference for the driver work

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-09T21:32:54Z

+    def test_known_crc_value(self):
+        # Modbus CRC of [0x01, 0x03, 0x00, 0x00, 0x00, 0x01] = 0x840A
+        data = bytes([0x01, 0x03, 0x00, 0x00, 0x00, 0x01])
+        assert calculate_crc(data) == 0x840A
+


The CRC value in this plan snippet (0x840A) conflicts with the implemented/tested representation in tests/unit/control/test_modbus_rtu.py (which expects calculate_crc(...) == 0x0A84 and appends low-byte-first for wire order). Consider updating the plan text to match the code’s CRC integer convention, or explicitly clarify which endianness each value refers to, to avoid future confusion.

Copilot · 2026-03-09T21:32:55Z

+from enum import Enum, IntEnum
+from typing import Optional


Optional is imported but not used in this module. Please remove the unused import to keep linting/static analysis clean.

Copilot · 2026-03-09T21:32:55Z

+                    response = self._serial.read(expected_response_len)
+                    if len(response) < expected_response_len:
+                        raise ModbusError(
+                            f"Incomplete response: expected {expected_response_len} "
+                            f"bytes, got {len(response)}",
+                            slave_id=frame[0],
+                        )
+


_send_receive() treats any response shorter than expected_response_len as a retryable "Incomplete response". Modbus exception responses are typically 5 bytes long (slave, fc|0x80, code, crc16), so they will be misclassified and retried, and the non-retry exception handling block will never run. Consider special-casing len(response) == 5 and (response[1] & 0x80) (with CRC verification) before raising the incomplete-response error, or reading/parsing enough bytes to detect exception frames first.

Copilot · 2026-03-09T21:32:55Z

+                try:
+                    self._serial.reset_input_buffer()
+                    self._serial.write(frame)
+                    time.sleep(FRAME_INTERVAL)
+
+                    response = self._serial.read(expected_response_len)
+                    if len(response) < expected_response_len:
+                        raise ModbusError(
+                            f"Incomplete response: expected {expected_response_len} "
+                            f"bytes, got {len(response)}",
+                            slave_id=frame[0],
+                        )
+
+                    if not _verify_crc(response):
+                        raise ModbusError("CRC verification failed", slave_id=frame[0])
+
+                except ModbusError as e:
+                    last_error = e
+                    logger.warning(
+                        f"Modbus request failed (attempt {attempt + 1}/"
+                        f"{self._retries + 1}): {e}"
+                    )
+                    if attempt < self._retries:
+                        time.sleep(FRAME_INTERVAL * 2)
+                    continue


The retry loop in _send_receive() only catches ModbusError. Transport-layer failures from pyserial (e.g., serial.SerialException / OSError during reset_input_buffer(), write(), or read()) will bypass the retry logic entirely, even though the PR description says transport errors are retried. Consider catching those exceptions, wrapping them in ModbusError, and applying the same retry/backoff behavior.

Copilot · 2026-03-09T21:32:55Z

+    def connect(self, port: Optional[str] = None, baudrate: Optional[int] = None):
+        if port is not None:
+            self._port = port
+        if baudrate is not None:
+            self._baudrate = baudrate
+        self._serial = serial.Serial(
+            self._port, baudrate=self._baudrate, timeout=self._timeout
+        )


connect() will pass self._port directly into serial.Serial(...) even when it is still None, which results in a pyserial error message that’s harder to interpret at the call site. Consider validating that a port was provided (either via __init__ or the connect() argument) and raising a clear ModbusError/ValueError if it’s missing.

- Detect Modbus exception responses (5 bytes) before incomplete check - Catch pyserial SerialException/OSError in retry loop - Validate port is set before connecting - Remove unused Optional import from servo_motor.py Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Log errors in abort() instead of silently swallowing exceptions - Close existing connection before re-opening in ModbusRTUClient.connect() - Add abort/fault checks and TimeoutError to stop() polling loop - Log warning when jog() clamps velocity to max - Wrap pyserial exceptions in ModbusError in connect() - Use try/finally in disconnect() to ensure _serial = None - Reject zero velocity in jog() Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

OEM-AMCB209 peristaltic pump driver reusing ModbusRTUClient. Supports multiple pumps on a shared RS485 bus with direction-based sign convention for aspirate/dispense. Includes start/stop, run_for_duration, abort, and simulation class. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add ServoMotorConfig and PeristalticPumpsConfig pydantic models to config.py. Both are optional sections keyed by serial number. Rename default axis from Z4 to Z. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Alpaca233 and others added 4 commits March 9, 2026 14:25

docs: add hardware drivers implementation plan (servo motor + heater …

1229fc3

…shaker) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat: add Modbus RTU communication module for servo motor

ebfac1a

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat: add servo motor driver with CiA402 state machine and simulation

3fe61f3

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Alpaca233 requested a review from Copilot March 9, 2026 21:26

Alpaca233 force-pushed the add-hardware-drivers branch from 18e93b1 to d81b91e Compare March 9, 2026 21:26

Copilot started reviewing on behalf of Alpaca233 March 9, 2026 21:26 View session

Copilot AI reviewed Mar 9, 2026

View reviewed changes

Alpaca233 and others added 6 commits March 9, 2026 14:48

docs: add peristaltic pump driver design spec

d8f951a

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat: add servo motor and peristaltic pump config models

040f892

Add ServoMotorConfig and PeristalticPumpsConfig pydantic models to config.py. Both are optional sections keyed by serial number. Rename default axis from Z4 to Z. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

test: add hardware test script for pumps and servo motor

b5cc7d3

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add servo motor driver (Modbus RTU + CiA402)#4

feat: add servo motor driver (Modbus RTU + CiA402)#4
Alpaca233 wants to merge 10 commits intomainfrom
add-hardware-drivers

Alpaca233 commented Mar 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Alpaca233 commented Mar 9, 2026

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants