Topics, services and movement

Start with Install and connect. Run commands in a terminal prepared with source scripts/setup_env.sh.

Inspect the ROS graph

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

Services

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.

Movement action

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.

Configuration and additional robots

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.

Task Runner