blacknode-robot owns transport-neutral robot contracts, connected-device state, profiles, hardware-bound calibration, capability bindings, normalized telemetry, and driver launch descriptors.
Physical bus communication lives in blacknode-drivers; motion control lives in blacknode-motion; ROS transport lives in blacknode-ros2.
| Component | Purpose |
|---|---|
core / contracts |
Robot, joint, device, and fault contracts |
profiles / models |
Reusable profiles, driver descriptors, presets, and launch models |
calibration |
Safe calibration capture tied to stable hardware identity |
capabilities |
Discovery, attachments, provider bindings, and readiness inspection |
devices |
Connected hardware lifecycle, health, and safe provider interfaces |
telemetry |
Normalized joint, voltage, temperature, fault, and status data |
authorization |
Optional consequential-action gating |
Use the Blacknode editor as the primary surface:
- Open Devices to add or inspect a computer.
- Open Packages and enable the required robot and driver components.
- Load
complete-robot-bringup.jsonto discover hardware, select a profile, apply its matching calibration, and start the driver disarmed. Each Robot node keeps its own calibration hardware selection and uses that stable identity to select the connected device, so leader/follower workflows can bind two arms independently. - Use Robot Monitor for read-only state and
RobotServofor preview; arm only after identity, calibration, limits, and fresh feedback are correct. - Use the guided calibration and editable-profile templates when defining a new physical assembly.
Core nodes include Robot, ComputeDevice, PhysicalRobot, RobotDeployment, RobotStream, DeviceInspect, profile load/save/duplicate nodes, calibration control/recording, capability and attachment nodes, RobotMonitor, and RobotServo. Build device workflows as ComputeDevice → PhysicalRobot → RobotDeployment → RobotStream. Each node owns one selection and passes credential-free live inspection state forward. Connect RobotStream.topic and RobotStream.message_type to generic ROS 2 stream inputs, then route the ROS message into a map, camera, LiDAR, IMU, or other compatible viewer or processing node. Local profiles and hardware-bound calibration copies live outside package source under ~/.blacknode/robots/ by default, or under BLACKNODE_ROBOTS_DIR when configured. Releases before 0.5.6 stored them under the process working directory's robots/ folder; that location remains readable for compatibility.
The Robot calibration input also accepts Blacknode's explicit calibration-import envelope. SO-ARM motor range JSON selected through an operator app is validated against the profile, bound to the discovered USB serial, converted to Blacknode's native degree-and-safety format, and copied into the persistent Blacknode directory. Runtime use has no dependency on the tool that originally produced the JSON.
- Motion is disarmed by default.
- Calibration is recorded only while torque is released and the robot is physically supported.
- Calibrations bind to stable hardware identity and are never substituted silently.
- Freshness, calibrated limits, hardware warnings, and shutdown behavior remain enforced at provider and driver boundaries.
- Managed hardware drivers receive an owner watchdog and a graceful-stop signal. On Windows they remain isolated from console-close termination long enough to release torque, and Stop All keeps their transport available until torque-off is confirmed.
- Device pairing tokens never belong in workflows, logs, process arguments, or tracked files.
python -m pytest packages/blacknode-robot/tests
Get-ChildItem packages\blacknode-robot\templates\*.json | ForEach-Object { blacknode validate $_.FullName }Device-service operations are documented in docs/devices.md. See AGENTS.md for calibration and motion safeguards.