# `BB.Command.Disarm`
[🔗](https://github.com/beam-bots/bb/blob/main/lib/bb/command/disarm.ex#L5)

Standard command handler for disarming a robot.

When executed from the `:idle` state, this command disarms the robot
via `BB.Safety.Controller`, which calls all registered `BB.Safety.disarm/1`
callbacks to ensure hardware is made safe.

## Usage

Add to your robot's command definitions:

    commands do
      command :disarm do
        handler BB.Command.Disarm
        allowed_states [:idle]
      end
    end

Then execute:

    {:ok, cmd} = MyRobot.disarm()
    {:ok, :disarmed} = BB.Command.await(cmd)

## Implicit `disarm: true`

When this module is the handler, the DSL implicitly sets `disarm: true`
on the command, which means `BB.Safety.disarm/2` will route through
this command rather than flipping safety state directly. To insert
pre-disarm work (e.g. moving to a home position) without losing the
safety-API routing, write a custom handler that calls
`BB.Safety.Controller.disarm/2` directly and flag it with
`disarm true`. If the custom handler returns an error before reaching
the controller, the safety system parks the robot in `:error` —
`force_disarm/1` is required to recover.

---

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