description {
 * @brief A robot simulator

Player devices may either be real hardware or virtual devices
generated by a simulator such as Stage or Gazebo.  This interface
provides direct access to a simulator.

This interface doesn't do much yet. It is in place to later support things
like pausing and restarting the simulation clock, saving and loading,
etc.

Note: the Stage and Gazebo developers should confer on the best design
for this interface. Suggestions welcome on playerstage-developers.
}


/** Request/reply subtype: set 2D pose */
message { REQ, GET_POSE2D, 1, player_simulation_pose2d_req_t };
/** Request/reply subtype: get 2D pose */
message { REQ, SET_POSE2D, 2, player_simulation_pose2d_req_t };
/** Request/reply subtype: set 2D pose */
message { REQ, GET_POSE3D, 3, player_simulation_pose3d_req_t };
/** Request/reply subtype: get 2D pose */
message { REQ, SET_POSE3D, 4, player_simulation_pose3d_req_t };
/** Request/reply subtype: set property value */
message { REQ, GET_PROPERTY, 5, player_simulation_property_req_t };
/** Request/reply subtype: get property value */
message { REQ, SET_PROPERTY, 6, player_simulation_property_req_t };
/** Cmd subtype: pause (if running) /resume (if paused) command  */
message { CMD, PAUSE, 1, NULL };
/** Cmd subtype: reset simulation command  */
message { CMD, RESET, 2, NULL };
/** Cmd subtype: save simulation command  */
message { CMD, SAVE,  3, NULL };


/** @brief Data

Just a placeholder for now; data will be added in future.
*/
typedef struct player_simulation_data
{
  /** A single byte of as-yet-unspecified data. Useful for experiments. */
  uint8_t data;
} player_simulation_data_t;

/** @brief Command

Just a placeholder for now; data will be added in future.
*/
typedef struct player_simulation_cmd
{
  /** A single byte of as-yet-unspecified command. Useful for experiments. */
  uint8_t cmd;
} player_simulation_cmd_t;

/** @brief Request/reply: get/set 2D pose of a named simulation object

To retrieve the pose of an object in a simulator, send a null
@ref PLAYER_SIMULATION_REQ_GET_POSE2D request.  To set the pose of an object
in a simulator, send a @ref PLAYER_SIMULATION_REQ_SET_POSE2D request (response
will be null). */
typedef struct player_simulation_pose2d_req
{
  /** Length of name */
  uint32_t name_count;
  /** the identifier of the object we want to locate */
  char *name;
  /** the desired pose in (m, m, rad) */
  player_pose2d_t pose;
} player_simulation_pose2d_req_t;

/** @brief Request/reply: get/set 3D pose of a named simulation object

To retrieve the pose of an object in a 3D simulator, send a null
@ref PLAYER_SIMULATION_REQ_GET_POSE3D request.  To set the pose of an object
in a 3D simulator, send a @ref PLAYER_SIMULATION_REQ_SET_POSE3D request (response
will be null). */
typedef struct player_simulation_pose3d_req
{
  /** Length of name */
  uint32_t name_count;
  /** the identifier of the object we want to locate */
  char *name;
  /** the desired pose in (m, m, m, rad, rad, rad) */
  player_pose3d_t pose;
  /** simulation time when PLAYER_SIMULATION_REQ_GET_POSE3D was serviced. */
  double simtime;
} player_simulation_pose3d_req_t;

/** @brief Request/reply: get/set a property of a named simulation object

@par To retrieve an property of an object in a simulator, send a @ref
PLAYER_SIMULATION_REQ_GET_PROPERTY request. The server will reply with
the value array filled in. The type of the data varies by property and
it is up to the caller to cast the data to the correct type: see the
warning below.

@par To set a property, send a completely filled in @ref
PLAYER_SIMULATION_REQ_SET_PROPERTY request. The server will respond
with an ACK if the property was successfully set to your value, else a
NACK.

@par **WARNING** Types are architecture-dependent, so this feature may
not work correctly if the simulator is running on a different
architecture than your client. The value bytes are transmitted as a
raw binary object: no architecture-specific type conversions are
performed. Use with caution.
*/

typedef struct player_simulation_property_req
{
  /** Length of name */
  uint32_t name_count;
  /** The identifier of the object we want to locate */
  char *name;
  /** Length of property identifier */
  uint32_t prop_count;
  /** The identifier of the property we want to get/set */
  char *prop;
  /** Index for properties with multiples values (arrays...) */
  uint32_t index;
  /** The length of the value data in bytes */
  uint32_t value_count;
  /** The value of the property */
  char *value;
} player_simulation_property_req_t;

