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_v1.proto

  syntax = "proto3";
  
  package flr_api.v1;
  
  enum Boolean
  {
      BOOLEAN_UNSPECIFIED = 0;
      BOOLEAN_TRUE = 1;
      BOOLEAN_FALSE = 2;
  }
  
  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;
      Quaternion rotation = 2;
  }
  
  message PoseArray
  {
      repeated Pose poses = 1;
  }
  
  message Twist
  {
      Vector3 linear = 1; // linear velocity
      Vector3 angular = 2; // angular velocity
  }

• api_v1_rtos.proto

  syntax = "proto3";
  import "protos/api_v1.proto";
  
  package flr_api.v1.rtos;
  
  message CartesianJoggingCommand
  {
      option deprecated = true;
      Pose desired_pose = 1;
  }
  
  message CartesianPoseJoggingCommand
  {
      Pose desired_pose = 1;
  }
  
  message CartesianVelocityJoggingCommand
  {
      Twist desired_velocity = 1;
  }
  
  message TimeScaling
  {
      double value = 1;
  }
  
  message JointJoggingCommand
  {
      option deprecated = true;
      repeated double desired_joint_positions = 1;
  }
  
  message JointPositionJoggingCommand
  {
      repeated double desired_joint_positions = 1;
  }
  
  message JointVelocityJoggingCommand
  {
      repeated double desired_joint_velocities = 1;
  }
  
  enum SpeedMode
  {
      SpeedMode_UNKNOWN = 0;
      SpeedMode_T1 = 1;
      SpeedMode_T2 = 2;
  }
  
  message SpeedModeCommand
  {
      SpeedMode speed_mode = 1;
  }
  
  message RobotState
  {
      enum RobotControlMode
      {
          IDLE = 0;
          JOGGING = 1;
          JOINT_POSITION_TRAJECTORY = 2;
      }
      enum ConnectionState
      {
          UNKNOWN = 0;
          DISCONNECTED = 1;
          CONNECTED = 2;
          ERROR = -1;
      }
      repeated string joint_names = 1; // Joints names : [base , link_( 0 -> nDof-1) , flange]
      repeated double joint_positions = 2; // Joints values in rad
      repeated double joint_velocities = 3; // Joints speeds values in deg/s
      bool executing_on_real_robot = 4; // Executing on real or simulated robot
      bool ready_to_execute_commands = 5;
      RobotControlMode robot_control_mode = 6;
      ConnectionState connection_state = 7;
      Pose tool_pose = 8;
      Twist tool_velocity = 9;
      repeated double joint_positions_setpoint = 10; // Joints values in rad
      repeated double joint_velocities_setpoint = 11; // Joints speeds values in deg/s
      Pose tool_pose_setpoint = 12;
      Twist tool_velocity_setpoint = 13;
      double timestamp = 14;
      Boolean safety_system_ready = 15;
      Boolean robot_script_running = 16;
      Boolean power_stage_enabled = 17;
      SpeedMode speed_mode = 18;
      Tool tool = 19;
      repeated string currently_handled_events = 20;
  }
  
  message RunOnRealRobot
  {
      bool run_on_real_robot = 1;
  }
  
  message Tool
  {
      string name = 1;
      Pose flange_to_tcp = 2;
  }
  
  message TrajectoryAction
  {
      enum ActionType
      {
          ON_STOP = 0;
          ON_PAUSE = 1;
          ON_PLAY = 2;
          ON_NEXT = 3;
          ON_PREVIOUS = 4;
          ON_REWIND = 5;
          ON_JOGGING = 6;
      }
      ActionType action = 1;
  }
  
  message TrajectoryState
  {
      bool is_trajectory_valid = 1;
      bool is_real_trajectory = 2;
      bool on_trajectory = 3;
      bool is_trajectory_advancing = 4;
      enum StateType
      {
          STOPPED = 0;
          PAUSED = 1;
          PLAYING = 2;
          MOVE_TO_NEXT = 3;
          MOVE_TO_PREVIOUS = 4;
          REWINDING = 5;
          JOGGING = 6;
          PENDING_STOP = 7;
          FINISHED = 8;
      }
      StateType state = 5;
      double time_scaling_factor = 6;
      double trajectory_start_time = 7;
      double trajectory_current_time = 8;
      double trajectory_end_time = 9;
      double trajectory_total_duration = 10;
      string uuid = 11;
  }
  
  message Waypoint
  {
      enum MotionType
      {
          PTP = 0;
          LIN = 1;
          SPLINE = 2;
          JOINTSPLINE = 3;
      }
      enum BlendingSpeed
      {
          BLENDING_SPEED_AUTO = 0;
          BLENDING_SPEED_VARYING = 1;
          BLENDING_SPEED_CONSTANT = 2;
      }
      MotionType motion_type = 1;
      Pose pose = 2;
      repeated double joint_positions = 3;
      string name = 4;
      bool pause_at_waypoint = 5;
      double velocity_scaling_percent = 6;
      string traj_uuid = 7; // unused
      double blending_percent = 8;
      double pause_duration = 9;
      double time_from_start = 10;
      BlendingSpeed blending_speed = 11;
  }
  
  message TrajectoryGenOptions
  {
      bool force_constant_speed = 1;
      optional string desired_uuid = 2;
  }
  
  message MotionProfileConstraints
  {
      // Motion profiles inputs params
      double initial_position = 1;
      double initial_velocity = 2;
      double initial_acceleration = 3;
      double final_position = 4;
      double final_velocity = 5;
      double final_acceleration = 6;
      double max_speed = 7;
      double max_acceleration = 8;
      double max_deceleration = 9;
      double max_jerk = 10;
      double duration = 11;
  }
  
  message TrajectoryGenInputs
  {
      repeated Waypoint waypoints = 1;
      TrajectoryGenOptions options = 2;
      Pose flange_to_tcp = 3;
      repeated MotionProfileConstraints motion_profiles = 4; // reserved for FuzzyLogic use
  }
  
  message PathPreview
  {
      repeated Pose poses = 1;
  }
  
  message TunableRequest
  {
      enum AccessMode
      {
          UNSPECIFIED = 0;
          READ = 1;
          WRITE = 2;
          ANSWER = 3;
      }
      string tunable_path = 1;
      string value = 2;
      AccessMode access_mode = 3;
  }
  
  message TrajectoryGeneratorState
  {
      enum State {
          STATE_UNSPECIFIED = 0;
          STATE_IDLE = 1;
          STATE_WORKING = 2;
      }
  
      enum Result {
          RESULT_UNSPECIFIED = 0;
          RESULT_SUCCESS = 1;
          RESULT_FAILURE = 2;
      }
  
      message HistoryEntry {
          string uuid = 1;
          Result result = 2;
      }
  
      State state = 1;
      repeated HistoryEntry history = 2;
  }

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).