The ROS (Robot Operating System) interface provides access to the physical (or simulated) robot, its various sensors and actuators, and its supplementary output systems (sound and light emitters). A complete list of topics is given below.
Topic names are based on the Robot Name which can be set using MiRoapp. The default robot name, for example, is
miro. In this case, sensor topics will be under
/miro/sensors and control topics under
/miro/control. Below, we omit the robot name from the topic names in the topic list.
All topics are published at 50Hz except camera and microphone topics, which arrive asynchronously. Downstream control signals can be processed at up to 50Hz, but receivers will behave coherently at signalling rates down to 10Hz. Often, clients will find it sufficient to control at 10Hz even if they receive data at 50Hz.
This interface uses standard message types for most topics, favouring the widest set of clients. All 50Hz sensor data is packaged into one custom message at
sensors/package. Clients that are able to work with custom message types will usually find it convenient to subscribe to this topic to receive all the 50Hz data in one package. In addition, the sensors/battery topic uses the ROS Kinetic version of BatteryState, which is packaged in
miro_msg so that it is available to users of other ROS versions.
~/mdk/bin/shared(most if not all topics are exercised by
~/mdk/bin/shared/client_gui.py, but some more specific clients are present, and are referenced in the tables below). You can use this interface from any development language that supports ROS—if using C/C++, you will find the headers you need at
~/mdk/catkin_ws/install/include, and a client template at
Interoceptive sensors at 50Hz
The commanded wheel speed sent down to the motor controllers after all operations have completed (m/s) in the order
The wheel speeds measured using the opto encoders (m/s) in the order
The wheel speeds measured using motor back EMF (m/s) in the order
The wheel drive effort (motor current) in normalised units in the order
[LEFT, RIGHT]. The actual motor current delivered is constrained to lie in [-1.0, +1.0], but the values published here can exceed this interval if the wheel controller asked for more current (which could not physically be delivered).
Body velocity computed from sensors/wheel_speed_opto (m/s and Rad/s).
The following Python example shows how to recover the speed of the individual wheels from sensors/body_vel, if required.
The same values as sensors/body_vel but packaged differently.
Internal DOF configuration (Rad) in the order
[TILT, LIFT, YAW, PITCH] (see Geometry).
sensor_msgs/BatteryState from ROS Kinetic).
Battery voltage (V).
State of internal DIP switches in a bit array, if fitted (otherwise reads zero).
Acceleration vector measured in body (m/s).
Acceleration vector measured in head (m/s).
Exteroceptive sensors at 50Hz
Level at each of the four light sensors in normalised units in the order
[FRONT LEFT, RIGHT, REAR LEFT, RIGHT]. A value of 0.0 indicates total darkness, and a value of 1.0 indicates the sensor is under strong illumination.
Binary state of body touch sensors in a bit array.
Binary state of head touch sensors in a bit array.
Reading from each of the two cliff sensors in normalised units in the order
[LEFT, RIGHT]. A value of 1.0 strongly indicates that a surface is present, whilst a value of 0.0 indicates no evidence that a surface is present. Actual values returned will depend on physical surface characteristics.
Range to strongest sonar reflector (m). Normal values are in the interval [0.03m, 1.0m). A value of 0.0m indicates that an echo was received at closer than 0.03m, which may not be reliable data. A value of infinity indicates that no echo was received.
Packaged sensors at 50Hz
All the 50Hz sensors (above) packaged into one topic.
Block of interleaved samples from four microphones in the order
[LEFT, RIGHT, CENTRE, TAIL] (arbitrary units packaged in an int16, sample rate is 20kHz, packages arrive at around 40Hz in default configuration).
Frames from the left eye camera (sample rate is variable, see control/command).
Frames from the right eye camera (sample rate matches sensors/caml).
Pose of the robot body (FOOT frame) in the WORLD frame (m and Rad). This is not computed by the physical robot, but is published by the simulator (at 50Hz) to aid in development.
Frames from the overhead camera (sample rate matches sensors/caml). Only available in the simulator, if enabled.
Log information from firmware and from bridge is generated here; used for diagnostics.
Flags word indicating current state of platform (see Constants, flags for this topic are prefixed
State of audio stream buffer in the format
[buffer_space, buffer_total] (bytes).
A client may publish up to
(buffer_total - buffer_space) bytes to control/stream after receiving this signal without overflowing the stream buffer. However, a shorter streaming latency is achieved if the client does not stuff the buffer any more than necessary to maintain continuous playback.
~/mdk/bin/shared/client_stream.py for an example of using this topic.
Commanded body velocity (complements sensors/body_vel).
The following Python example shows how to control the speed of the individual wheels through control/cmd_vel, if required.
sensor_msgs/JointState of length 4.
Commanded internal DOF configuration (complements sensors/kinematic_joints).
std_msgs/FloatMultiArray of length 6.
Commanded configuration of cosmetic joints (normalised). Six joints are commanded in the order
[droop, wag, eyel, eyer, earl, earr].
Supplementary output systems
std_msgs/UInt32MultiArray of length 6.
Commanded pattern for the six illumination LEDs in the order
[Left Front, Middle, Rear, Right Front, Middle, Rear]. Each element is an bRGB word where the "b" is a brightness channel that scales the other three channels (i.e. it is as an independent brightness control).
std_msgs/UInt16MultiArray of length 3.
The three elements are
[frequency, volume, duration] of a tone that will be produced by the on-board speaker. Frequency is in Hertz (values between 50 and 2000 are accepted), volume is in 0 to 255, and duration is in platform ticks (20ms periods).
std_msgs/Int16MultiArray of maximum length 4000 bytes.
~/mdk/bin/shared/client_stream.py for an example of using this topic.
Flags word controlling current state of platform (see Constants, flags for this topic are prefixed
Controllers should usually send this topic just once at the beginning of their execution—see the example client_template for an example of this (search for "--no-cliff").
If you include the flag
PLATFORM_D_FLAG_PERSISTENT, the passed flags will be retained until reboot, or until you send a new value. If not, they will expire whenever no motor control commands (specifically, control/cmd_vel, control/kinematic_joints, or control/cosmetic_joints) have been received for a period of one second, at which point they will reset to the configured bridge flags.
String command to be interpreted by the bridge in changing the operational state of the platform. Multiple commands can be included in a single string, separated by semicolons.
- Change camera frame size and rate (<frame_size> can be any of: 180s, 180w, 240s, 360s, 360w, 720s, 720w; <frame_rate> can be any value but will be constrained between 1 and the maximum frame rate available at the specified resolution). Resolutions are specified as frame height with
sfor standard aspect ratio (4:3) and
wfor wide (16:9).
- Change JPEG encoder quality (values between 10 and 90 are accepted, but very high values used with high frame rates may overload frame delivery bandwidth and lead to dropped frames).