v0.2.2: API cleanup, pinokin IK, tool support, hot path optimization#14
Merged
Conversation
Breaking change: removed SETPROFILE/GETPROFILE commands. New commands: - SETJOINTPROFILE/GETJOINTPROFILE for joint moves (supports all 6 profiles) - SETCARTPROFILE/GETCARTPROFILE for Cartesian moves (TOPPRA, LINEAR only) Other changes: - Made RESET a SystemCommand so client waits for acknowledgment - Fixed client _request_ok to properly propagate ERROR responses - Updated README with expanded architecture diagram
LINEAR profile now uses iterative duration extension when joint velocity/acceleration limits would be violated, matching the behavior of QUINTIC, TRAPEZOID, and SCURVE profiles. Add parametrized tests to verify all profiles respect joint limits and extend duration when needed.
…expand test matrix to 3.10-3.14
- Update MockState to use joint_motion_profile/cartesian_motion_profile instead of deprecated motion_profile attribute - Fix test_reset_command tests to call tick() instead of setup() since ResetCommand executes in tick, not setup - Add is_finished = True to ResetCommand.execute_step() Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Standardize duration|velocity_percent|accel_percent format for joint, cartesian, and smooth motion commands - Add parse_motion_params helper to base.py for consistent parsing - Update client methods to use positional format instead of DURATION|value - Refactor trajectory.py with proper duration estimators for each profile - Add Cartesian velocity constraint support via JointVelocityConstraintVarying - Expand profile command integration tests with duration/velocity coverage - Fix smooth command tests to use correct parameter format
…mplete wait_motion_complete relies on speed detection which races with the planner subprocess on slow CI machines. Switch all move/home/gripper methods to use wait_command_complete (command-index tracking) which is deterministic. Replace **wait_kwargs with explicit timeout parameter.
On some Windows CI runners, multicast socket binding fails with PermissionError. The server already handles this gracefully; now the client does too.
… docs - Fix outdated API names (manage_server→Robot, wait_for_server_ready→wait_ready, move_joints→moveJ, disable/stop→halt, MockSerialProcessAdapter→MockSerialTransport) - Add mermaid architecture diagram with planned vs streaming command paths - Add control loop internals: 7-phase loop, hybrid timing, command paths - Add hot path rules: zero-allocation zones, GC discipline, Numba JIT - Add command system: categories table, lifecycle, adding new commands - Add motion profiles table with speed/accel API - Consolidate kinematics + tools into single section - Add TOC, env vars, dev setup, FAQ, safety notes
- query_commands: use .name instead of .value for ActionState (IntEnum) - test_query_commands_actions: use ActionState enum instead of plain strings - test_moveP_basic: reduce waypoint offsets to stay within IK-reachable workspace
- test_moveP_basic: use dz=-5 offset to avoid near-singular home orientation that caused IK failures on certain platform/Python combinations - trajectory.py: widen constraints list type to constraint.Constraint to accept JointVelocityConstraintVarying from cart vel limit
- Make set_pdeathsig() cross-platform: prctl on Linux, parent-liveness polling thread on macOS/Windows - Add set_pdeathsig() to IK worker (was missing, motion planner already had it) - Add Windows guard to unregister_shm() to avoid _posixsubprocess crash - Widen moveL position tolerance from 1.01mm to 1.5mm for cross-platform CI - Add CI failure guidance to CLAUDE.md - Add test verifying children exit when parent is SIGKILL'd
On Windows, os.kill(pid, SIGTERM) calls TerminateProcess which caused cascading KeyboardInterrupt in the pytest process. Windows handles shared memory cleanup via named file mappings automatically.
…lean up executor threading
…nt gap accumulation
…scillation at boundary
…et logging jogL: use CSE smoothed_pose for IK (not FK+velocity recomputation), add _q_commanded/_q_ik_seed tracking for branch continuity and smooth joint trajectories, scale jog velocity by previous tick's clamping ratio to keep CSE in sync with joint-velocity-limited motion. servoL: replace per-tick correct_position calls with set_limits(speed/ratio) to slow CSE when joints are velocity-clamped (restores pre-80a7d80 approach). Remove _clamped/_fk_buf infrastructure. controller: overbudget warnings start at DEBUG when process priority is not elevated (occasional overbudget is normal with OS scheduling), escalate to WARNING if >3 in 60s. Always WARNING when priority is elevated. Tune J1/J2/J6 hardware speed limits.
macOS CI achieves ~45Hz (vs 100Hz target), so a 0.5s jog only gets ~23 ticks — not enough to complete the wrist flip warm-up from home before the timer expires. Increase to 2s.
ty 0.0.25 requires ty:-prefixed error codes in type: ignore comments. Add ty: codes alongside existing mypy codes on all suppressed lines. servoL: remove _ik_failed_target check that permanently blocked IK recovery for the same target. If IK succeeds, resume regardless. Loosen straight-line path deviation tolerance from 0.1mm to 0.15mm for marginal CI failures on slow runners.
- fix outdated API references (wait_motion_complete, stream_on/off) - fix incorrect env var defaults (BUSY_THRESHOLD, STATUS_STALE, BLEND_LOOKAHEAD) - remove nonexistent PAROL6_TX_KEEPALIVE_S env var - add platform requirements, waldoctl ABC section, examples index - expand set_tool example with variant_key usage - fix example docstring paths (external/... -> examples/...) - add pick_and_place, draw_circle, zigzag_scan, speed_comparison examples
Wire protocol: - CmdType enum: GET_X → X, SET_X → SELECT_X/WRITE_X/CONNECT_HARDWARE - Struct renames: GetAnglesCmd → AnglesCmd, SetIOCmd → WriteIOCmd, etc. - New: SimulatorStateCmd query + SimulatorStateResultStruct - New: simulator_active field in status broadcast Client API: - Motion: moveJ/moveL/etc → move_j/move_l/etc - Queries: get_angles/get_pose/etc → angles/pose/etc - Mutations: set_tool → select_tool, set_io → write_io, etc. - Mode: simulator_on/off → simulator(bool) setter + is_simulator() query - Streams: status_stream → stream_status - Waits: wait_motion_complete → wait_motion - pose() now returns [x,y,z,rx,ry,rz] (merges get_pose_rpy) - activity() returns ActivityResult - get_tool_status → private _tool_status (users use rbt.tool.status()) Backend discovery: - pyproject.toml entry point: [project.entry-points."waldoctl.robots"] Server, commands, tests, and examples all updated.
- new SET_TCP_OFFSET / TCP_OFFSET wire commands; SetTcpOffsetCommand is a SystemCommand and now lives in SYSTEM_CMD_TYPES so the client waits for ack instead of leaving stale OK in the rx queue - TCP_OFFSET added to QUERY_CMD_TYPES for consistency - controller now syncs tool state to the planner subprocess on RESET (fixes test_cartesian_move_validation when run after tool tests) - joint_path_to_tcp_poses uses pinokin so3_rpy (intrinsic XYZ) to match the convention used elsewhere in robot.py - async_client move_s/move_p Category: Smooth Motion -> Motion to match the ABC; drop incompatible move_j @Overloads - examples reorganised to mirror programs/ (deleted pick_and_place, reachable poses in demo_showcase, use robot.create_sync_client) - example tests gated behind --examples flag (port 5001 collides with the integration server fixture); 240s subprocess + 300s pytest timeout per example
Demote per-step startup INFO lines to DEBUG and emit a single "Controller ready on host:port" line as the boot summary. Also quiet toppra/numba third-party loggers at INFO and above. Suppress expected EOFError/BrokenPipeError/KeyboardInterrupt in the IK worker and motion planner subprocess loops so parent shutdown no longer logs spurious tracebacks. UDP transport now treats socket errors as DEBUG once self._running is False.
Compound `cd foo && ...` calls cross directories and require explicit user approval each time. Instruct Claude to issue cd as a standalone command and rely on the Bash tool's persistent working directory for follow-up actions.
bump version to 0.2.2
User scripts that import the client directly via
`from parol6 import RobotClient` (or AsyncRobotClient) hit a KeyError
on the first `client.tool` access, even after `select_tool("SSG-48")`.
The constructor was leaving `_bound_tools` empty and only
`Robot.create_*_client()` populated it from the registry. So any
standalone script — and waldo-commander's stepping bootstrap, which
patches `parol6.RobotClient` and constructs it directly — failed
with `KeyError: 'SSG-48'` (or whichever tool was selected).
Fix: have both client constructors call a new `_bind_default_tools()`
helper that reads `parol6.robot._build_tools()` and binds each tool's
`_execute` / `_get_status` callbacks to the client's own
`tool_action` / `_tool_status` methods. The Robot factory still
rebinds afterwards from its own `tools.available`, which is the same
underlying registry, so no behavior change for that path. Lazy import
of `parol6.robot` inside the helper avoids the import cycle (parol6
.robot imports the clients at module level).
Verified: full test suite (228 passed, 8 skipped) on aarch64.
The gripper requires a one-time calibration before its first open/close/set_position call. Document this in the example scripts so users copy-pasting from them won't hit silent calibration failures on real hardware.
`tbump <new_version>` now handles the within-repo bump dance: edit pyproject.toml, commit, annotated tag, and atomic push of branch + tag. Install with `pip install tbump`. Removes the easy-to-forget 'push the tag separately' step.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR merges ~87 commits from the fork that backs
Waldo Commander. Tagged
in the fork as
v0.2.2. Major themes below.Client API cleanup
snake_case methods, queries are nouns (
angles(),pose()),mutations are verbs (
move_j(),home()). Unified motion commandparameter format across all command types. Method renames:
start/stop→resume/halt,wait_for_server_ready→wait_ready. Breaking for existing user code.RobotClientandAsyncRobotClientnow auto-bind tools atconstruction time so
from parol6 import RobotClientworks directlywithout going through a
Robot.create_*_client()factory.IK backend: roboticstoolbox → pinokin
Pinocchio bindings via nanobind. Faster, smaller install, no
compile-from-source on Apple Silicon. Drops the
roboticstoolbox-pythondependency. IK worker refactored to use numba SE3 operations.
Tool support
First-class end-effector model with
select_tool(), per-toolmeshes / TCP offsets / variants, and a
rbt.tool.calibrate()/open()/close()/set_position()API. Tool variants andconcurrent tool commands.
Backend abstraction
Implements the waldoctl
RobotABC so frontends can stay backend-agnostic. DefinesRobot,ToolSpec,JointsSpec, and related types in a shared package;parol6 inherits from it.
Wire protocol: ASCII → binary msgpack
Smaller packets, faster encode/decode, structured types via msgspec.
Multicast status broadcasting with unicast fallback when multicast
socket creation fails.
Zero-allocation hot paths
execute_step()/tick()run at 100 Hz;do_setup()for streamablecommands at 50 Hz. Both are now zero-allocation: pre-allocated buffers,
in-place numpy ops, no list/dict construction in the inner loops.
Rules documented in
CLAUDE.md.Motion planning
Added TOPPRA, Ruckig, S-curve, Quintic, and Trapezoid profiles.
Separate joint vs cartesian motion profiles. Limit enforcement on
the LINEAR profile.
tcp_offsetcommands. Blending via ther=parameter. Fixes to
jogL/servoLfor jitter and IK oscillationat workspace boundaries.
Architecture refactor
Controller split into modular components. Structured error catalog.
Motion pipeline.
CI / tooling
Cross-platform CI (Linux / Windows / macOS, Python 3.12–3.14,
dropped 3.10/3.11). Switched lint/type runners to pre-commit
(ruff + ty). Added
tbumpconfig for one-command releases. JITpre-warming for test reliability.
Docs
Rewrote README with API reference, architecture overview, and
internals docs. Added
CLAUDE.mdfor AI-assisted contributors.Test status
Passes on Linux x86_64 / aarch64, Windows AMD64, macOS ARM64 across
Python 3.12 / 3.13 / 3.14.