# `BB.Message.Actuator.Command.Trajectory`
[🔗](https://github.com/beam-bots/bb/blob/main/lib/bb/message/actuator/command/trajectory.ex#L5)

Command an actuator to follow a trajectory defined by waypoints.

A trajectory specifies exact position, velocity, and acceleration at
each point in time, enabling smooth coordinated motion.

## Fields

- `waypoints` - List of waypoint maps defining the trajectory
- `repeat` - Number of times to repeat: positive integer or `:forever` (default 1)
- `command_id` - Optional reference for correlating with feedback messages

## Waypoint Structure

Each waypoint is a map with:

- `position` - Position at this waypoint (radians or metres)
- `velocity` - Velocity at this waypoint (rad/s or m/s)
- `acceleration` - Acceleration at this waypoint (rad/s² or m/s²)
- `time_from_start` - Time from trajectory start (milliseconds)

## Examples

    alias BB.Message
    alias BB.Message.Actuator.Command.Trajectory

    waypoints = [
      %{position: 0.0, velocity: 0.0, acceleration: 0.5, time_from_start: 0},
      %{position: 0.1, velocity: 0.3, acceleration: 0.2, time_from_start: 100},
      %{position: 0.3, velocity: 0.4, acceleration: 0.0, time_from_start: 200},
      %{position: 0.5, velocity: 0.3, acceleration: -0.2, time_from_start: 300},
      %{position: 0.6, velocity: 0.0, acceleration: -0.5, time_from_start: 400}
    ]

    {:ok, msg} = Message.new(Trajectory, :shoulder,
      waypoints: waypoints
    )

    # Repeat 5 times
    {:ok, msg} = Message.new(Trajectory, :shoulder,
      waypoints: waypoints,
      repeat: 5
    )

    # Repeat forever (until stopped)
    {:ok, msg} = Message.new(Trajectory, :shoulder,
      waypoints: waypoints,
      repeat: :forever
    )

# `t`

```elixir
@type t() :: %BB.Message.Actuator.Command.Trajectory{
  command_id: reference() | nil,
  repeat: pos_integer() | :forever,
  waypoints: [waypoint()]
}
```

# `waypoint`

```elixir
@type waypoint() :: %{
  position: float(),
  velocity: float(),
  acceleration: float(),
  time_from_start: non_neg_integer()
}
```

# `new`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*