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

Message published by actuators when beginning a motion.

Used by `BB.Sensor.OpenLoopPositionEstimator` to estimate current position
during open-loop control (actuators without position feedback).

## Fields

- `initial_position` - Position before motion begins (radians or metres)
- `target_position` - Target position (radians or metres)
- `expected_arrival` - When motion should complete (monotonic milliseconds)
- `command_id` - Optional correlation ID from the originating command
- `command_type` - Optional type of command that initiated this motion
- `acceleration` - Optional acceleration magnitude (rad/s² or m/s²) used when
  the motion follows a trapezoidal/triangular velocity profile. `nil`
  indicates a rectangular profile and is the legacy behaviour.
- `peak_velocity` - Optional peak velocity magnitude (rad/s or m/s) achieved
  during the motion. Paired with `acceleration` to fully describe a
  trapezoidal or triangular profile. `nil` falls back to easing-based
  interpolation.

## Example

    alias BB.Message
    alias BB.Message.Actuator.BeginMotion

    expected_arrival = System.monotonic_time(:millisecond) + 500

    {:ok, msg} = Message.new(BeginMotion, :shoulder,
      initial_position: 0.0,
      target_position: 1.57,
      expected_arrival: expected_arrival
    )

# `command_type`

```elixir
@type command_type() :: :position | :velocity | :effort | :trajectory
```

# `t`

```elixir
@type t() :: %BB.Message.Actuator.BeginMotion{
  acceleration: float() | nil,
  command_id: reference() | nil,
  command_type: command_type() | nil,
  expected_arrival: integer(),
  initial_position: float(),
  peak_velocity: float() | nil,
  target_position: float()
}
```

# `new`

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

---

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