Dora-native motion planning and execution orchestration for Forge robots.
Manipulation / application goals
-> MoveJoints / MovePose
-> MotionServer
-> FollowJointTrajectory
-> actuator-facing controllers
The repository is a UV workspace of independently installable motion packages. Version 0.1 starts
with forge-motion-server; shared trajectory processing, collision checking, planning scenes, and
streaming servo packages should only be extracted when real additional consumers require them.
| Item | Current implementation |
|---|---|
| Production Nodes | 2: motion_server and motion_action_policy; source commands forge-motion-server and forge-motion-action-policy |
| Auxiliary programs | Examples such as fake plants are excluded from the production Node count |
| Tool integration | Dora ToolMessage provider; caller-facing access through Gateway |
| Direct HTTP Tool API | 0; the Nodes do not listen on HTTP; Gateway owns the invocation URL |
| Endpoints | 1: motion.server; its provider is motion_action_policy, not motion_server |
| Operations | 2: move_joints and move_pose (both Action, cancellable, status supported; each descriptor has maximum concurrency 1) |
| Gateway Tools | Deployment-defined in tools.specs; robot-control-sim binds 2 Tools to these operations |
| Tool ID (robot-control-sim configuration) | Endpoint / operation | Provider Node |
|---|---|---|
sim.set_joint_positions |
motion.server / move_joints |
motion_action_policy |
sim.move_eef |
motion.server / move_pose |
motion_action_policy |
Gateway -> motion_action_policy -> motion_server -> joint_trajectory_controller -> Adapter / simulator
motion_action_policy handles the Tool lifecycle and Wire argument translation;
motion_server handles fresh state, FK/IK, trajectories and controller orchestration.
Version 0.1.1 uses bounded local IK fallback and separates numerical position
accuracy from physical completion tolerance. A hardware-free JSON-lines
preflight helper is available as python -m forge_motion_server.route_preflight;
it adds no production Node, Endpoint or Tool operation.
They are separate Nodes: the word server in the Endpoint ID does not route the provider to the compute Node.
For arguments, units and validation, see the Action endpoint
and motion_server package guide. Joint values use rad/m according to joint type; pose positions use metres.
Compatibility: current dependency declarations are dora-rs==0.4.1, forge-kinematics==1.0.1, forge-msgs==1.0.1, and scipy>=1.14,<2. See pyproject.toml and uv.lock. The Tool protocol implementation is vendored in this repository. These declarations do not guarantee cross-version interoperability; also check the build revision and Skill lock when using artifacts.
Changes to Node entrypoints, Endpoints or Tool APIs must update this section and the associated configuration/contracts. Follow the Node README contract.
packages/motion_server: fresh-state validation, Forge FK/IK, joint-space time parameterization, parent/child Dora Action orchestration, cancel propagation, and final residual checking.
Motion determines how a configured kinematic group reaches a joint or Cartesian target. It does not
contain object/manipulation semantics, hardware protocols, motor loops, or low-level
JointCommand generation.
The optional preflight helper interprets application waypoint labels outside the
MotionServer action core. It checks sequential IK and sampled TCP height, and
does not provide whole-robot collision checking.
The default planning budget is 1000 ms. Numerical IK position tolerance is
min(completion_position_tolerance * 0.5, 0.002) metres, with orientation cost
weight 0.01 and DLS damping 0.1. Up to eight numerical attempts, each limited to
80 ms, share the planning budget. These settings are defaults when omitted;
explicit configuration overrides them. See the configuration and fallback
guide.
See examples/piper_fake_plant/ for the full Piper fake-plant integration smoke.
Use Python 3.12 and uv:
uv sync --frozen --all-groups
PYTHONPATH=src uv run pytest -qPYTHONPATH=src exposes the vendored forge-tool protocol under
src/forge_tool; see THIRD_PARTY_NOTICES.md for its provenance. Optional
standalone executables can be built with scripts/build_pyinstaller.sh.
The manual Build Ubuntu 20.04 binaries workflow accepts a commit, branch or tag
in ref and checks that both package versions match version. It builds and
checks both CLIs in Ubuntu 20.04, then uploads the combined archive and separate
single-executable archives for motion_server and motion_action_policy.
Release assets also include SHA-256 checksums, the exact source commit and frozen
runtime requirements. Use the separate archives for single-node installation;
the combined archive contains both programs. Build success does not imply that
the independent dependency audit passed. Version 0.1.1 retains an inherited
Pillow 12.3.0 dependency whose audit currently fails; see the
verification update.
Apache License 2.0. Runtime dependencies are not distributed with this source repository and retain their respective licenses; see NOTICE and THIRD_PARTY_NOTICES.md. Review the complete bundled artifact before publishing standalone executables.