API review (2011-10-17)

Proposer: John Hsu

Present at review:

Attendees: Bhaskara, Gil, Ioan, John, Nate, Sachin, Tully

Proposed Robot Dynamics State Description Format

<model_state>
- Purpose: This is the root tag that for this document. All information is included in this tag.
- Elements: <link_state> <joint_state>
- Attributes:
- <link_state>
  - Purpose: use this to specify the state of a link in the robot
  - Elements: <id> <time> <frame_id> <pose> <twist> <wrench>
  - Attributes: name is the name of the link
  - <id> unsigned long int
    - Purpose: an unique identifier for this state
    - Elements:
    - Attributes:
  - <time> double
    - Purpose: time stamp in seconds
  - <reference_frame> string
    - Purpose: A string indicating name of another link as the reference frame of states. Keywords inertial or world can be used to reference absolute inertial frame.
    - Elements:
    - Attributes:
  - <pose> 6-tuple
    - Purpose: A 6-tuplet (x,y,z,roll,pitch,yaw) used to specify the pose of a link, relative to the <reference_frame>
    - Elements:
    - Attributes:
  - <twist> 6-tuple
    - Purpose: A 6-tuplet (x,y,z,roll,pitch,yaw) used to specify the twist of a link, relative to the <reference_frame>
    - Elements:
    - Attributes:
  - <wrench> 6-tuple
    - Purpose: A 6-tuplet (x,y,z,roll,pitch,yaw) used to specify the wrench exerted on a link, relative to the <reference_frame>
    - Elements:
    - Attributes:
- <joint_state>
  - Purpose: use this to specify the state of a joint in the robot
  - Elements: <position> <velocity> <time>
  - Attributes: name is the name of the link
  - <id> unsigned long int
    - Purpose: an unique identifier for this state
    - Elements:
    - Attributes:
  - <time> double
    - Purpose: time stamp in seconds
  - <position> double
    - Purpose: position of the joint
    - Elements:
    - Attributes:
  - <velocity> double
    - Purpose: velocity of the joint
    - Elements:
    - Attributes:

Examples

<model_state name="pr2">
  <link_state name="r_shoulder_pan_link">
    <id>0</id>
    <time>0</time>
    <reference_frame>base_link</reference_frame>
    <pose>0 0 1 0 0 0</pose>
    <twist>0 0 1 0 0 0</twist>
    <wrench>0 0 0 0 0 0</wrench>
  </link_state>
  <link_state name="r_shoulder_lift_link">
    <id>1</id>
    <time>0</id>
    <reference_frame>r_shoulder_pan_link</reference_frame>
    <pose>0 0 0 0 0 0</pose>
    <twist>0 0 0 0 0 0</twist>
    <wrench>0 0 0 0 0 0</wrench>
  </link_state>
</model_state>

<model_state name="pr2">
  <joint_state name="r_shoulder_lift_joint">
    <id>1</id>
    <time>0</id>
    <position>0</position>
    <velocity>0</velocity>
  </joint_state>
</model_state>

<model_state name="my_box">
  <reference_frame>r_shoulder_pan_link</reference_frame>
  <pose>0 0 0 0 0 0</pose>
  <link_state name="my_box0_link">
    <pose>0 0 0 0 0 0</pose>
  </link_state>
  <link_state name="my_box1_link">
    <pose>0 0 0.5 0 0 0</pose>
  </link_state>
</model_state>

Question / concerns / comments

Attendees: Bhaskara, Gil, Ioan, John, Nate, Sachin, Tully
Scope: Is this the corresponding state information description format (for URDF)? or is this more generic.
- YAML? other *ML? (we should not restrict ourselves to either)
  - specification only, this should be format independent
Is top level tag name: <model_state> appropriate? alternatives are <robot> or <state> or ... (model_state)
- <model_state> is fine. add <frame> parallel to <model_state>
Is <id> necessary?
- (no, move to the meta-data of the model_state)
<time>
- (no, move out to meta-data of model_states)
How to represent diff states?
- (should be outside in meta-data).
Determine optional vs. required for each element & attribute. Determine default values for each element & attribute.
- will do online
Is <joint_state> necessary?
- yes
- up to user to keep thing consistent
- position/velocity should be vectors
- add torque (measured torque)
Default reference frame of each link state is its parent. Is <reference_frame> necessary?
- yes, move under <model_state>
gil: is a collection of model_states sufficient to describe a scene?
- yes, it should be.
think about adding twist reference point and wrench reference point?
- leave out until needed.
consider other simulation? vehicles, air traffic
- out of scope for now. current state information focused on mobile manipulator robots that can be represented in URDF.
john: write out conclusions, next round will be emailed.

Comments

Ioan: I think <id> should be at the model level

Proposal: Rev 2

Option 1

<world_state>
- Purpose: This is the root tag that for this document. All information is included in this tag.
- Elements: <frame> <model_state>
- Attributes: name
- name string
  - Purpose: A unique name of the world state
- <model_state>
  - Purpose: This is the root tag that for this document. All information is included in this tag.
  - Elements: <frame> <link_state> <joint_state>
  - Attributes: name
  - name
    - Purpose: Name of the model
  - <frame>
    - Purpose: Contains a reference to the parent frame
    - Elements: <parent> <pose> <twist>
    - Attributes:
    - <parent> string
      - Purpose: A string indicating frame name or name of another model_state to be the reference frame of these states. Keywords world can be used to reference absolute inertial frame. If left empty, default is world
      - Elements:
      - Attributes:
    - <pose> 6-tuple
      - Purpose: A 6-tuplet (x,y,z,roll,pitch,yaw) used to specify the pose of a link, relative to the parent frame of the <model_state>.
      - Elements:
      - Attributes:
    - <twist> 6-tuple
      - Purpose: A 6-tuplet (x,y,z,roll,pitch,yaw) used to specify the twist of a link, relative to the <origin> of
      - Elements:
      - Attributes:
  - <link_state>
    - Purpose: use this to specify the state of a link in the robot
    - Elements: <pose> <twist> <wrench>
    - Attributes: name
    - name
      - Purpose: Name of the link
    - <pose> 6-tuple
      - Purpose: A 6-tuplet (x,y,z,roll,pitch,yaw) used to specify the pose of a link, relative to the frame of the <model_state>.
      - Elements:
      - Attributes:
    - <twist> 6-tuple
      - Purpose: A 6-tuplet (x,y,z,roll,pitch,yaw) used to specify the twist of a link, relative to the <origin> of the link
      - Elements:
      - Attributes:
    - <wrench> 6-tuple
      - Purpose: A 6-tuplet (x,y,z,roll,pitch,yaw) used to specify the wrench exerted on a link, relative to the <origin> of the link
      - Elements:
      - Attributes:
  - <joint_state>
    - Purpose: use this to specify the state of a joint in the robot
    - Elements: <positions> <velocities> <torques>
      - Attributes: name
      - name
        Purpose: Name of the joint
    - <positions> double[]
      - Purpose: array of positions of the DOF's of the joint
      - Elements:
      - Attributes:
    - <velocities> double[]
      - Purpose: array of velocities of the DOF's of the joint
      - Elements:
      - Attributes:
    - <torques> double[]
      - Purpose: array of torques measured for each DOF of the joint
      - Elements:
      - Attributes:
- <frame>
  - Purpose: Frame of reference relative to global frame or anth
  - Elements: <pose> <twist> <parent>
  - Attributes: name
  - name string
    - Purpose: Name of this frame
  - <parent>
    - Purpose: Name of the parent frame or model_state
    - Elements:
    - Attributes:
  - <pose> 6-tuple
    - Purpose: A 6-tuplet (x,y,z,roll,pitch,yaw) used to specify the pose of a link, relative to the frame of the <model_state>.
    - Elements:
    - Attributes:
  - <twist> 6-tuple
    - Purpose: A 6-tuplet (x,y,z,roll,pitch,yaw) used to specify the twist of a link, relative to the <origin> of the link
    - Elements:
    - Attributes:

Option 2

<world_state>
- Purpose: This is the root tag that for this document. All information is included in this tag.
- Elements: <frame> <model_state>
- Attributes:
- <model_state>
  - Purpose: This is the root tag that for this document. All information is included in this tag.
  - Elements: <parent> <pose> <twist> <link_state> <joint_state>
  - Attributes: name
  - name
    - Purpose: Name of the model
  - <parent> name
    - Purpose: A string indicating frame name or name of another model_state to be the reference frame of these states. Keywords world can be used to reference absolute inertial frame. If left empty, default is world.
    - Elements:
    - Attributes:
  - <pose> 6-tuple
    - Purpose: A 6-tuplet (x,y,z,roll,pitch,yaw) used to specify the pose of a link, relative to the <parent> frame.
    - Elements:
    - Attributes:
  - <twist> 6-tuple
    - Purpose: A 6-tuplet (x,y,z,roll,pitch,yaw) used to specify the twist of a link, relative to the <parent> frame.
    - Elements:
    - Attributes:
  - <link_state>
    - Purpose: use this to specify the state of a link in the robot
    - Elements: <pose> <twist> <wrench>
    - Attributes: name
    - name
      - Purpose: Name of the link
    - <pose> 6-tuple
      - Purpose: A 6-tuplet (x,y,z,roll,pitch,yaw) used to specify the pose of a link, relative to the frame of the <model_state>.
      - Elements:
      - Attributes:
    - <twist> 6-tuple
      - Purpose: A 6-tuplet (x,y,z,roll,pitch,yaw) used to specify the twist of a link, relative to the <origin> of the link
      - Elements:
      - Attributes:
    - <wrench> 6-tuple
      - Purpose: A 6-tuplet (x,y,z,roll,pitch,yaw) used to specify the wrench exerted on a link, relative to the <origin> of the link
      - Elements:
      - Attributes:
  - <joint_state>
    - Purpose: use this to specify the state of a joint in the robot
    - Elements: <positions> <velocities> <torques>
      - Attributes: name
      - name
        Purpose: Name of the joint
    - <positions> double[]
      - Purpose: array of positions of the DOF's of the joint
      - Elements:
      - Attributes:
    - <velocities> double[]
      - Purpose: array of velocities of the DOF's of the joint
      - Elements:
      - Attributes:
    - <torques> double[]
      - Purpose: array of torques measured for each DOF of the joint
      - Elements:
      - Attributes:
- <frame>
  - Purpose: Frame of reference relative to global frame or anth
  - Elements: <pose> <twist> <parent>
  - Attributes: name
  - name string
    - Purpose: Name of this frame
  - <parent> name
    - Purpose: A string indicating frame name or name of another model_state to be the reference frame of these states. Keywords world can be used to reference absolute inertial frame. If left empty, default is world.
    - Elements:
    - Attributes:
  - <pose> 6-tuple
    - Purpose: A 6-tuplet (x,y,z,roll,pitch,yaw) used to specify the pose of a link, relative to the parent frame or the parent <model_state>.
    - Elements:
    - Attributes:
  - <twist> 6-tuple
    - Purpose: A 6-tuplet (x,y,z,roll,pitch,yaw) used to specify the twist of a link, relative to the <origin> of the link
    - Elements:
    - Attributes:

Example

Option 1:

<world name="world_1">
  <model_state name="pr2">
    <frame>
      <parent>odom</parent>
      <pose>0 0 0 0 0 0</pose>
      <twist>0 0 0 0 0 0</twist>
    </frame>
    <link_state name="r_shoulder_pan_link>
      <pose>1 0 1 0 0 0</pose>
      <twist>0 0 0 0 0 0</twist>
      <wrench>0 0 0 0 0 0</twist>
    </link_state>
  </model_state>
  <frame name="odom">
    <parent>world</parent>
    <pose>0 0 0 0 0 0</pose>
    <twist>0 0 0 0 0 0</twist>
  </frame>
</world>

Option 2:

<world name="world_1">
  <model_state name="pr2">
    <parent>odom</parent>
    <pose>0 0 0 0 0 0</pose>
    <twist>0 0 0 0 0 0</twist>
    <link_state name="r_shoulder_pan_link>
      <pose>1 0 1 0 0 0</pose>
      <twist>0 0 0 0 0 0</twist>
      <wrench>0 0 0 0 0 0</twist>
    </link_state>
  </model_state>
  <frame name="odom">
    <parent>world</parent>
    <pose>0 0 0 0 0 0</pose>
    <twist>0 0 0 0 0 0</twist>
  </frame>
</world>

Conclusion

Package status change mark change manifest)

$/!\$ Action items that need to be taken.
Major issues that need to be resolved