BB.Message.Sensor.JointState (bb v0.28.0)

Copy Markdown View Source

State of a set of joints.

Fields

  • names - List of joint names as atoms
  • positions - Joint configurations
  • velocities - Joint velocities
  • efforts - Joint efforts

All lists must have the same length. Missing values can be represented as empty lists.

Values are shaped to the joint's type

A joint with more than one degree of freedom has no single number to report, so each list is heterogeneous and its elements line up with names:

Joint typepositionsvelocitiesefforts
single-DoFfloatfloatfloat
:planarBB.Math.Transform2DBB.Message.Geometry.Twist2DBB.Message.Geometry.Wrench2D
:floatingBB.Math.TransformBB.Message.Geometry.TwistBB.Message.Geometry.Wrench

Most consumers only ever see single-DoF joints, so in practice their handling is unchanged — but a consumer that pattern matches on a float, or does arithmetic on an element, should say which joint types it supports.

Splitting multi-DoF state into a separate message type was considered and rejected: a robot's joint state would then arrive on two topics, and every consumer wanting the whole configuration would have to subscribe to both and correlate them by timestamp to reconstruct one instant. That is a permanent tax on every consumer, levied to avoid changing one message.

All three lists changed together for the same reason. velocities and efforts have precisely the same problem as positions, and breaking a widely-consumed message twice is worse than breaking it once.

Examples

alias BB.Message.Sensor.JointState

{:ok, msg} = JointState.new(:arm,
  names: [:joint1, :joint2],
  positions: [0.0, 1.57],
  velocities: [0.1, 0.0],
  efforts: [0.5, 0.2]
)

# A mobile base reports its whole pose in the same message as its mast
{:ok, msg} = JointState.new(:rover,
  names: [:base, :mast],
  positions: [BB.Math.Transform2D.new(12.4, -3.1, 1.57), 0.5]
)

Summary

Types

configuration()

A joint's configuration, shaped to its type.

effort()

A joint's effort, shaped to its type.

t()
velocity()

A joint's velocity, shaped to its type.

Functions

new(frame_id, attrs)

Types

configuration()

@type configuration() :: float() | BB.Math.Transform2D.t() | BB.Math.Transform.t()

A joint's configuration, shaped to its type.

effort()

@type effort() ::
  float() | BB.Message.Geometry.Wrench2D.t() | BB.Message.Geometry.Wrench.t()

A joint's effort, shaped to its type.

t()

@type t() :: %BB.Message.Sensor.JointState{
  efforts: [effort()],
  names: [atom()],
  positions: [configuration()],
  velocities: [velocity()]
}

velocity()

@type velocity() ::
  float() | BB.Message.Geometry.Twist2D.t() | BB.Message.Geometry.Twist.t()

A joint's velocity, shaped to its type.

Functions

new(frame_id, attrs)

@spec new(
  atom(),
  keyword()
) :: {:ok, BB.Message.t()} | {:error, term()}