# `BB.Controller.Action`
[🔗](https://github.com/beam-bots/bb/blob/main/lib/bb/controller/action.ex#L5)

Action builders and executor for reactive controllers.

Provides two action types:
- `Command` - invokes a robot command
- `Callback` - calls an arbitrary function with the message and context

## DSL Builders

These functions are imported into the controller entity scope:

    controller :over_current, {BB.Controller.Threshold,
      topic: [:sensor, :servo_status],
      field: :current,
      max: 1.21,
      action: command(:disarm)
    }

    controller :collision, {BB.Controller.PatternMatch,
      topic: [:sensor, :proximity],
      match: fn msg -> msg.payload.distance < 0.05 end,
      action: handle_event(fn msg, ctx ->
        Logger.warning("Collision detected")
        :ok
      end)
    }

# `t`

```elixir
@type t() :: BB.Controller.Action.Command.t() | BB.Controller.Action.Callback.t()
```

# `command`

```elixir
@spec command(atom()) :: BB.Controller.Action.Command.t()
```

Build a command action that invokes the named robot command.

## Examples

    command(:disarm)
    command(:move_to, target: pose)

# `command`

```elixir
@spec command(
  atom(),
  keyword()
) :: BB.Controller.Action.Command.t()
```

# `execute`

```elixir
@spec execute(t(), BB.Message.t(), BB.Controller.Action.Context.t()) :: any()
```

Execute an action with the given message and context.

# `handle_event`

```elixir
@spec handle_event((BB.Message.t(), BB.Controller.Action.Context.t() -&gt; any())) ::
  BB.Controller.Action.Callback.t()
```

Build a callback action that calls the given function.

The function receives the triggering message and a context struct.

## Examples

    handle_event(fn msg, ctx ->
      Logger.info("Received: #{inspect(msg)}")
      :ok
    end)

---

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