# `BB.Supervisor`
[🔗](https://github.com/beam-bots/bb/blob/main/lib/bb/supervisor.ex#L5)

Root supervisor for a BB robot.

Builds a supervision tree that mirrors the robot topology for fault isolation.
A crash in an actuator at the end of a limb only affects that limb's subtree.

## Supervision Tree Structure

```
BB.Supervisor (root, :one_for_one)
├── Registry (named {MyRobot, :registry})
├── PubSub Registry (named {MyRobot, :pubsub})
├── Task.Supervisor (for general async tasks)
├── DynamicSupervisor (for command GenServers, temporary restart)
├── Runtime (robot state, state machine, command execution)
├── BB.BridgeSupervisor (:one_for_one)
│   └── MavlinkBridge, PhoenixBridge...
└── BB.TopologySupervisor (:one_for_one)
    ├── BB.SensorSupervisor (:one_for_one)
    │   └── RobotSensor1, RobotSensor2...
    ├── BB.ControllerSupervisor (:one_for_one)
    │   └── Controller1, Controller2...
    └── BB.LinkSupervisor(:base_link, :one_for_one)
        ├── LinkSensor (link sensors)
        └── BB.JointSupervisor(:shoulder, :one_for_one)
            ├── JointSensor
            ├── JointActuator
            └── BB.LinkSupervisor(:arm, :one_for_one)
                └── ...
```

Each subsystem supervisor (sensors, controllers, bridges) has its own restart
budget, so a flapping process in one won't exhaust the root supervisor's
budget and bring down the entire robot. The topology supervisor groups all
hardware-facing subtrees so they share a restart budget; when that budget is
exhausted the safety controller force-disarms the robot.

# `start_link`

```elixir
@spec start_link(module(), Keyword.t()) :: Supervisor.on_start()
```

Starts the supervisor tree for a robot module.

## Options

  * `:params` - Initial parameter values as a nested keyword list matching
    the parameter group structure. Overrides DSL defaults and persisted values.

        BB.Supervisor.start_link(MyRobot, params: [
          motion: [max_speed: 5.0, acceleration: 2.0],
          debug_mode: true
        ])

  * `:simulation` - Simulation mode (`:kinematic` or `:external`). When set,
    actuators are replaced with simulated versions and controllers may be
    omitted.

All options are also passed through to sensor, actuator, and controller
child processes via the `:bb` key in their start options.

---

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