Messaging.proto

syntax = "proto3";

package click.protobuf;

enum MessageType {
  HandshakeInitMessageType = 0;
  HandshakeMessageType = 1;
  SensorRequestMessageType = 6;
  ControlMessageType = 2;
  SensorMessageType = 3;
  ResetMessageType = 4;
  ErrorMessageType = 5;
}

enum ValueType {
  Angle = 0;                       // radians
  AngularVelocity1D = 1;           // radians/sec
  Torque1D = 2;                    // Nm
  Position = 3;                    // meters vec3
  RPY = 4;                         // radians vec3
  Activated = 5;                   // True/False
  Acceleration3D = 6;              // m/s2   vec3
  Force1D = 12;                    // Newton
  Force3D = 7;                     // Newton vec3
  Torque3D = 8;                    // Nm     vec3
  AngularAcceleration3D = 9;       // rad/s2 vec3
  Velocity3D = 10;                 // m/s    vec3
  AngularVelocity3D = 11;          // rad/s2 vec3
  Multiple = 15;                   // Multiple ValueType:s
}

message Message {
  MessageType messageType = 1;
  int32 id = 2; // Needed?
}

// Version is available in Handshake only to be able to break backward compatibility.
// Then, and only then, update current by 1, and add reserved <old version>
enum Version {
  UNDEFINED = 0;
  CURRENT_VERSION=1;
}

// Each message below has messageType set to the corresponding MessageType enum value
// This makes it possible to implement messages as a flat class hierarchy with Message as parent


message HandshakeInitMessage {
  MessageType messageType = 1;
  Version version = 2;
}

// A SensorRequestMessage will not cause the simulation to step, which a ControlMessage will.
// It can be used to get initial values before first simulation step.
message SensorRequestMessage {
  MessageType messageType = 1;
}

/* HandshakeMessage example
- Version: 1
- Objects:
  - panda_2
    - Joints
      - controlType: angles/velocities/torques          // one only - defined in OpenPLX
      - controlsInOrder: joint1, joint2, ..., joint7    // Defined order of joints in subsequent messages
      - jointSensorsInOrder: joint1, joint2, ..., joint7    // Defined order of joints in subsequent messages
      - jointSensors: Angle, Velocity, Torque
      - controlEvents:
        - gripper -> Activated
      - Sensors:
        - external -->
          - Sensors: Force, AngularAcceleration
  - panda_tool
    ...
  - box
    - objectSensors
      - Sensors: RPY, Position
*/

message HandshakeMessage {
  MessageType messageType = 1;
  Version version = 2;

  message Sensors {
    repeated ValueType types = 1;
  }

  message Object {
    repeated string controlsInOrder = 1;       // The controls (joints) in the order they are expected in every ControlMessage
    repeated ValueType controlTypesInOrder = 8;   // The controlTypes of each control in controlsInorder in the same order
    repeated string jointSensorsInOrder = 7;   // The sensors in the order they are expected in every SensorMessage
    repeated ValueType jointSensors = 2;       // sensor types per control (joints), indicates which vectors in SensorMessage are sent
    map<string, ValueType> controlEvents = 3;  // Which controls are optional, ie not present in every ControlMessage.
    // Optionals will default to default scalar value. IE 0 for doubles, (0,0,0) for Vec3, false for activated, etc.
    // (If the controller sends a value in first ControlMessage it will be used in first simulation step)
    map<string, Sensors> sensors = 4;          // Sensors per joint or other part
    repeated ValueType objectSensors = 6;      // The sensors that will be present for each object in a SensorMessage
  };

  message SimulationSettings {
    double timeStep = 1;                       // Timestep of the simulation
  };

  ValueType controlType = 3;                  // Which controltype is going to be used for joints, ie angles/velocities/torques. Deprecated - use controlTypesInOrder
  map<string, Object> objects = 4;            // Key is name of object/robot
  SimulationSettings simSettings = 5;
}


/*
- ControlMessage example:
  - panda_2
      - angles
    - gripper:
      - true
  - panda_tool
    ...
*/

message ControlMessage {
  MessageType messageType = 1;

  message Object {
    // - not clear by spec that is mutually exclusive
    // - needs controlEvent type anyway probably(?)
    // + can copy vectors more effectively, ie together with extend instead of individually
    // + fewer bytes in message
    // NOTE: Next four repeats are mutually exclusive!
    repeated double angles = 1;            // Present in every ControlMessage. Deprecated - use values.
    repeated double angularVelocities = 2;   // Present in every ControlMessage. Deprecated - use values.
    repeated double torques = 3;           // Present in every ControlMessage. Deprecated - use values.
    repeated double values = 5;            // Present in every ControlMessage. Must be correct type according to handshake.
    map<string, bool> controlEvents = 4;   // Optionals, if missing, keep same value as before
  };

  map<string, Object> objects = 2;
}

/*
SensorMessage example:

- panda_2
  - angleSensors [1,2,3,4] size = #joints
  - angularVelocitySensors ...
  - torqueSensors ...
  ...

  - Map: name_of_sensor --> List[Force, Torque] in order defined by handshake
    - external_1 --> Sensors: List[force-vec3, torque-vec3]
    - external_imu --> Sensors
    - external_imu --> Sensors
    # not in urdf file, not officically supported
    # controller (mc-rtc) typically has additional file
    # --> add in OpenPLX, send it in handshake
  ...
- box
  - objectSensors
    - position
    - rpy
*/


message SensorMessage {
  MessageType messageType = 1;

  message Vec3 {
    repeated double arr = 1;
  }

  // This is 1 byte longer than Vec3
  // message XYZ {
  //   double x = 1;
  //   double y = 2;
  //   double z = 3;
  // }

  message Sensor {
    oneof value {
      double angle = 1;
      double angularVelocity1d = 2;
      double torque1d = 3;
      Vec3 position = 4;
      Vec3 rpy = 5;
      bool activated = 6;
      Vec3 acceleration3d = 7;
      Vec3 force3d = 8;
      Vec3 torque3d = 9;
      Vec3 angularAcceleration3d = 10;
      Vec3 velocity3d = 12;
      Vec3 angularVelocity3d = 13;
      double force1d = 14;
    }
  };

  message Sensors {
    repeated Sensor sensor = 1;
  }

  message Object {
    // Sensors on joints, each present if defined in jointSensors handshake, order and size from jointSensorsInOrder in handshake.
    repeated double angleSensors = 1;
    repeated double angularVelocitySensors = 2;
    repeated double torqueSensors = 3;
    repeated Vec3 forceSensors = 5;
    // Sensors on the object, order of ValueType defined in handshake.
    repeated Sensor objectSensors = 4;
    // Sensors identified by name, ie not per joint or object, names and order of ValueType defined in handshake.
    map<string, Sensors> sensors = 6;
  }

  message SimulationVariables {
    double simulatedTime = 1;            // Will be a factor of timeStep from Handshake
  }

  map<string, Object> objects = 3;
  SimulationVariables simVars = 4;
}

message ResetMessage {
  MessageType messageType = 1;
}


enum ErrorType {
  VersionNotSupported = 0;
}

message ErrorMessage {
  MessageType messageType = 1;
  ErrorType error = 2;
  string errormessage = 3;
}