Start with Install and connect. Run commands in a terminal prepared with source scripts/setup_env.sh.
ros2 node list
ros2 node info /marty/marty_driver
ros2 topic list -t
ros2 service list -t
ros2 action list -t
The driver node publishes topics, serves connection/control requests and provides a movement action. Names below use the default /marty namespace.
| Topic | Message type | Contents |
|---|---|---|
| /marty/imu/data_raw | sensor_msgs/msg/Imu | Acceleration in m/s²; no gyro or orientation. |
| /marty/joint_states | sensor_msgs/msg/JointState | Valid measured positions in radians; velocity and effort are empty. |
| /marty/servo_states | marty_interfaces/msg/ServoStates | Servo angles, current in amperes, flags and communication validity. |
| /marty/battery | sensor_msgs/msg/BatteryState | Valid battery information; percentage is 0–1 and capacities are Ah. |
| /marty/telemetry | marty_interfaces/msg/Telemetry | Decoded SDK data with original names, units and validity flags. |
| /marty/status | marty_interfaces/msg/DriverStatus | Connection state, freshness, movement state, queue and errors. |
| /marty/diagnostics | diagnostic_msgs/msg/DiagnosticArray | Connection and telemetry health. |
Measurement topics use best-effort QoS. Status is reliable and transient-local. Measurements are published only when fresh SDK data arrives, with host receipt timestamps.
ros2 topic echo /marty/joint_states --qos-reliability best_effort
ros2 topic echo /marty/battery --qos-reliability best_effort
ros2 interface show marty_interfaces/msg/DriverStatus
All three services use std_srvs/srv/Trigger with an empty request:
ros2 service call /marty/connect std_srvs/srv/Trigger '{}'
ros2 service call /marty/stop std_srvs/srv/Trigger '{}'
ros2 service call /marty/disconnect std_srvs/srv/Trigger '{}'
Connect opens the configured endpoint and starts telemetry. Stop requests the firmware's clear-and-stop command; success confirms acknowledgement. Disconnect closes the connection and disables automatic reconnect. Stop interrupts an active motion goal, which reports ABORTED.
Actions provide feedback and a final result for operations that take time. Inspect the goal, result and feedback fields:
ros2 interface show marty_interfaces/action/Motion
With Marty connected and idle, try a small eyebrow movement (servo 8):
ros2 action send_goal /marty/motion marty_interfaces/action/Motion \
'{command: 4, joint_id: 8, position_degrees: 5, move_time_ms: 800}' --feedback
Place Marty on a clear, flat surface before walking or turning. One small forward step:
ros2 action send_goal /marty/motion marty_interfaces/action/Motion \
'{command: 0, num_steps: 1, side: auto, step_length_mm: 20, turn_degrees: 0, move_time_ms: 1500}' --feedback
A turning step uses step_length_mm: 0 and a nonzero turn_degrees.
| command | Operation | Main arguments |
|---|---|---|
| 0 | Walk / turn | num_steps, side, step_length_mm, turn_degrees, move_time_ms |
| 1 | Dance | side: left or right, move_time_ms |
| 2 | Kick | side: left or right, move_time_ms |
| 3 | Stand | move_time_ms |
| 4 | Move joint | joint_id, position_degrees, move_time_ms |
Goals use SDK angles in degrees; joint topics use radians. Walking accepts 1–10 steps, −50–50 mm step length and −100–100° turn. Joint IDs are 0–8 and positions are −90–90°. Duration is 100–10000 ms; for walking it is per step.
Only one goal is admitted at a time. Fresh, idle and unpaused robot status with an empty firmware queue is required. Completion waits for fresh idle status; acknowledgement alone does not finish the action. A connection loss aborts the goal, and commands are never replayed after reconnect.
A robot file can contain multiple entries with unique namespaces and connections:
martys:
marty:
method: usb
locator: /dev/serial/by-id/REPLACE_WITH_MARTY_DEVICE
auto_connect: false
auto_reconnect: false
marty2:
method: wifi
locator: 192.168.1.9
auto_connect: false
auto_reconnect: false
Launch each driver in its own terminal:
ros2 launch marty_bringup bringup.launch.py namespace:=marty
ros2 launch marty_bringup bringup.launch.py namespace:=marty2
The second robot's services and topics use /marty2/…. A launch starts one driver, not every entry in the file. Configuration is read at startup; restart the driver after editing it.
Explicit overrides take precedence:
ros2 launch marty_bringup bringup.launch.py namespace:=marty subscribe_rate_hz:=20.0
ros2 launch marty_bringup bringup.launch.py --show-args
MARTY_MACHINE_CONFIG selects another machine env file. robots_file:=/path/to/robots.yaml selects another robot file; params_file:=/path/to/parameters.yaml selects another ROS parameter YAML.
See ROS interface reference for action semantics and joint mapping. The existing Marty model still needs a verified name/sign/zero-angle mapping before displaying measured joints in RViz.
RViz simulation provides a separate setup for controlling simulated joints without a physical connection.