MQTT API

What is MQTT

From https://mqtt.org/

MQTT is an OASIS standard messaging protocol for the Internet of Things (IoT).

It is designed as an extremely lightweight publish/subscribe messaging transport that is ideal for connecting remote devices with a small code footprint and minimal network bandwidth.

MQTT today is used in a wide variety of industries, such as automotive, manufacturing, telecommunications, oil and gas, etc.

Purpose

We use MQTT for fast data transfert between hosts. It becomes easy to send periodic payloads with little overhead/latency. It is currently the only interface from which it is possible to move the robot, load trajectories, etc…

Message formatting

We use protobuf internally but transmit data in clear text as a JSON string.

• api_v2.proto

  syntax = "proto3";
  
  import "google/protobuf/timestamp.proto";
  
  package flr_api.v2;
  
  message StateHeader
  {
      google.protobuf.Timestamp timestamp = 1;
  }
  
  message CmdHeader
  {
      google.protobuf.Timestamp timestamp = 1;
  }
  
  message Vector3
  {
      double x = 1;
      double y = 2;
      double z = 3;
  }
  
  message Quaternion
  {
      double qx = 1;
      double qy = 2;
      double qz = 3;
      double qw = 4;
  }
  
  message Pose
  {
      Vector3 translation = 1;
      optional Quaternion rotation = 2; // No value set means identity quaternion
  }
  
  message Twist
  {
      Vector3 linear = 1;
      Vector3 angular = 2;
  }
  
  message Joints
  {
      repeated double value = 1;
  }    

• api_v2_rtos.proto

  syntax = "proto3";
  
  import "protos/api_v2.proto";
  
  package flr_api.v2.rtos;
  
  /* -------------------------------------------------------------------------- */
  /*                              Simulation switch                             */
  /* -------------------------------------------------------------------------- */
  
  message RunOnRealRobotCmd {
      CmdHeader header = 1;
      bool run_on_real_robot = 2;
  }
  
  /* -------------------------------------------------------------------------- */
  /*                                Control mode                                */
  /* -------------------------------------------------------------------------- */
  
  enum RTOSControlMode {
      RTOS_CONTROL_MODE_UNSPECIFIED = 0;
      RTOS_CONTROL_MODE_IDLE = 1; // Acts as TRAJECTORY_ACTIONS_STOP
      RTOS_CONTROL_MODE_JOGGING = 2;
      RTOS_CONTROL_MODE_TRAJECTORY = 3;
  }
  
  message RTOSControlModeCmd {
      CmdHeader header = 1;
      RTOSControlMode control_mode_request = 2;
  }
  
  /* -------------------------------------------------------------------------- */
  /*                                    Tool                                    */
  /* -------------------------------------------------------------------------- */
  
  message Tool {
      string name = 1;
      Pose flange_to_tcp = 2;
  }
  
  message SetToolCmd {
      CmdHeader header = 1;
      Tool tool = 2;
  }
  
  /* -------------------------------------------------------------------------- */
  /*                                   Jogging                                  */
  /* -------------------------------------------------------------------------- */
  
  message JoggingOverrideSpeedCmd {
      CmdHeader header = 1;
      double percent = 2;
  }
  
  message CartesianPoseJoggingCmd {
      CmdHeader header = 1;
      Pose desired_pose = 2;
  }
  
  message CartesianVelocityJoggingCmd {
      CmdHeader header = 1;
      Twist desired_velocity = 2;
  }
  
  message JointPositionJoggingCmd {
      CmdHeader header = 1;
      Joints joint_positions = 2;
  }
  
  message JointVelocityJoggingCmd {
      CmdHeader header = 1;
      Joints joint_velocities = 2;
  }
  
  /* -------------------------------------------------------------------------- */
  /*                              Operational mode                              */
  /* -------------------------------------------------------------------------- */
  
  enum OperationalMode {
      OPERATIONAL_MODE_UNSPECIFIED = 0;
      OPERATIONAL_MODE_MANUAL = 1;
      OPERATIONAL_MODE_AUTO = 2;
  }
  
  enum SpeedMode {
      SPEED_MODE_UNSPECIFIED = 0;
      SPEED_MODE_SLOW = 1;
      SPEED_MODE_FAST = 2;
      SPEED_MODE_MAX = 3;
  }
  
  message OperationalSwitchCmd {
      CmdHeader header = 1;
      OperationalMode operational_mode = 2;
      SpeedMode speed_mode = 3;
  }
  
  message DeadmanHeartbeatCmd {
      CmdHeader header = 1;
  }
  
  /* -------------------------------------------------------------------------- */
  /*                                System state                                */
  /* -------------------------------------------------------------------------- */
  
  enum ConnectionState {
      CONNECTION_STATE_UNSPECIFIED = 0;
      CONNECTION_STATE_CONNECTED = 1;
      CONNECTION_STATE_NOT_CONNECTED = 2;
      CONNECTION_STATE_UNREACHABLE = 3;
  }
  
  message RobotControllerState {
      StateHeader header = 1;
      string name = 2;
      bool ready_to_execute_commands = 3;
      optional bool safety_system_ready = 4;
      optional bool robot_script_running = 5;
      optional bool power_stage_enabled = 6;
      optional uint64 number_of_late_packets = 7;
      optional Joints latest_robot_language_setpoint = 8;
  }
  
  message RTOSState {
      StateHeader header = 1;
      string version = 2;
      bool executing_on_real_robot = 3;
      SpeedMode speed_mode = 4;
      OperationalMode operational_mode = 5;
      RTOSControlMode robot_control_mode = 6;
      ConnectionState connection_state = 7;
      repeated string allowed_events = 8;
      Joints latest_position_setpoints = 9;
      Joints joint_position_setpoints = 10;
      Joints joint_velocity_setpoints = 11;
      Pose tool_pose_setpoint = 12;
      Twist tool_velocity_setpoint = 13;
  }
  
  message RobotState {
      StateHeader header = 1;
      repeated string joint_names = 2;
      Joints joint_positions = 3;
      Joints joint_velocities = 4;
      Joints joint_accelerations = 5;
      Joints joint_jerks = 6;
      Tool tool = 7;
      Pose tool_pose = 8;
      Twist tool_velocity = 9;
      Twist tool_acceleration = 10;
  }
  
  message SystemState {
      StateHeader header = 1;
      RobotControllerState robot_controller_state = 2;
      RTOSState rtos_state = 3;
      RobotState robot_state = 4;
  }
  
  /* -------------------------------------------------------------------------- */
  /*                              Trajectory player                             */
  /* -------------------------------------------------------------------------- */
  
  enum TrajectoryPlayerAction {
      TRAJECTORY_PLAYER_ACTION_UNSPECIFIED = 0;
      TRAJECTORY_PLAYER_ACTION_PAUSE = 1;
      TRAJECTORY_PLAYER_ACTION_PLAY = 2;
      TRAJECTORY_PLAYER_ACTION_REWIND = 3;
  }
  
  message TrajectoryPlayerCmd {
      CmdHeader header = 1;
      TrajectoryPlayerAction action = 2;
  }
  
  message TrajectoryOverrideSpeedCmd {
      CmdHeader header = 1;
      double percent = 2;
  }
  
  enum PlayerState {
      PLAYER_STATE_UNSPECIFIED = 0;
      PLAYER_STATE_STOPPED = 1;
      PLAYER_STATE_PAUSED = 2;
      PLAYER_STATE_PLAYING = 3;
      PLAYER_STATE_REWINDING = 4;
      PLAYER_STATE_CONVERGING_TOWARDS_TARGET = 5;
      PLAYER_STATE_FINISHED = 6;
  }
  
  message TrajectoryState {
      StateHeader header = 1;
      string uuid = 2;
      bool is_playable = 3;
      bool is_on_trajectory = 4;
      bool is_advancing = 5;
      PlayerState player_state = 6;
      double override_speed = 7;
      double current_time = 9;
      double duration = 10;
  }
  
  /* -------------------------------------------------------------------------- */
  /*                            Trajectory Generator                            */
  /* -------------------------------------------------------------------------- */
  
  enum MotionType {
      MOTION_TYPE_UNSPECIFIED = 0;
      MOTION_TYPE_PTP = 1;
      MOTION_TYPE_LIN = 2;
      MOTION_TYPE_SPLINE = 3;
      MOTION_TYPE_JOINT_SPLINE = 4;
  }
  
  enum BlendingSpeedType {
      BLENDING_SPEED_TYPE_UNSPECIFIED = 0;
      BLENDING_SPEED_TYPE_AUTO = 1;
      BLENDING_SPEED_TYPE_VARYING = 2;
      BLENDING_SPEED_TYPE_CONSTANT = 3;
  }
  
  message RobotPose {
      Pose pose = 1;
      optional Joints joint_seeds = 2;
  }
  
  message Waypoint {
      MotionType motion_type = 1;
      optional RobotPose robot_pose = 2;
      optional Joints joint_positions = 3;
      string name = 4;
      string uuid = 5;
      optional double velocity_scaling_percent = 6;
      double blending_percent = 7;
      BlendingSpeedType blending_speed_type = 8;
      optional double pause_duration = 9;
  }
  
  message TrajectoryGenOptions {
      bool force_constant_speed = 1;
      optional string desired_uuid = 2;
  }
  
  message Robot{
      string brand = 1;
      string model = 2;
      Pose flange_to_tcp = 3;
  }
  
  message TrajectoryGenInputs {
      repeated Waypoint waypoints = 1;
      Robot robot = 2;
      TrajectoryGenOptions options = 3;
  }
  
  message TrajectoryGenerationCmd {
      CmdHeader header = 1;
      TrajectoryGenInputs inputs = 2;
  }
  
  message PathPreview {
      repeated Pose poses = 1;
  }
  
  enum GeneratorState {
      GENERATOR_STATE_UNSPECIFIED = 0;
      GENERATOR_STATE_IDLE = 1;
      GENERATOR_STATE_BUSY = 2;
  }
  
  message GenerationStatus {
      string uuid = 1;
      bool is_successful = 2;
  }
  
  message TrajectoryGeneratorState {
      StateHeader header = 1;
      GeneratorState state = 2;
      repeated GenerationStatus history = 3;
  }

Topics - outputs

Fuzzy RTOS publishes on the following topics:

• “robot_state”
  • Protobuf type: RobotState
  • Describes the global state of the active driver.
• “trajectory_state”
  • Protobuf type: TrajectoryState
  • Describes the state of the current trajectory.
• “path_preview”
  • Protobuf type: PathPreview
  • Is emitted after a new trajectory becomes active.
• “trajectory_generator_state”
  • Protobuf type: TrajectoryGeneratorState
  • Describes the state of the trajectory generator and gives a history of previous generations.
• “version” is a basic string containing the Fuzzy RTOS version.

Topics - inputs

Fuzzy RTOS listens on the following topics:

• “/fuzzy_studio/run_on_real_robot”
  • Protobuf type: RunOnRealRobot
  • Switch between the simulated driver and the real driver.
• "/fuzzy_studio/tool”
  • Protobuf type: Tool
  • Set the tool used by Fuzzy RTOS.
• "/fuzzy_studio/speed_mode”
  • Protobuf type: SpeedModeCommand
  • Switch between T1 (slow mode, 250mm/s) and T2 (fast mode, full speed)
• "/fuzzy_studio/trajectory_action”
  • Protobuf type: TrajectoryAction
  • Send various actions to Fuzzy RTOS (enable jogging mode, stop, play trajectory…)
• Jogging commands
  • "/fuzzy_studio/joint_position_jogging_command”
    • Protobuf type: JointPositionJoggingCommand
    • Send joint position jogging commands.
  • "/fuzzy_studio/joint_velocity_jogging_command”
    • Protobuf type: JointVelocityJoggingCommand
    • Send joint velocity jogging commands.
  • "/fuzzy_studio/cartesian_pose_jogging_command”
    • Protobuf type: CartesianPoseJoggingCommand
    • Send cartesian pose jogging commands.
  • "/fuzzy_studio/cartesian_velocity_jogging_command”
    • Protobuf type: CartesianVelocityJoggingCommand
    • Send cartesian velocity jogging commands.
• Trajectory commands
  • "/fuzzy_studio/trajectory_inputs"
    • Protobuf type: TrajectoryGenInputs
    • Send a list of waypoints to the trajectory generator.
  • "/fuzzy_studio/time_scaling"
    • Protobuf type: TimeScaling
    • Add a time dilatation to the trajectory (i.e. 0.5 will make the trajectory 2x slower).