# bb v0.17.0 - API Reference

## Modules

- Core
  - [BB](BB.md): Documentation for `BB` (Beam Bots).
  - [BB.PubSub](BB.PubSub.md): Hierarchical pubsub system for robot component messages.
  - [BB.Robot](BB.Robot.md): An optimised robot representation for kinematic computations.
  - [BB.Supervisor](BB.Supervisor.md): Root supervisor for a BB robot.
  - [BB.Telemetry](BB.Telemetry.md): Telemetry events emitted by the BB framework.

- DSL
  - [BB.Dsl](BB.Dsl.md): The DSL extension for describing robot properties and topologies.

  - [BB.Dsl.Actuator](BB.Dsl.Actuator.md): An actuator attached to a joint.
  - [BB.Dsl.Axis](BB.Dsl.Axis.md): Joint axis orientation specified as Euler angles.
  - [BB.Dsl.Box](BB.Dsl.Box.md): A box geometry

  - [BB.Dsl.Bridge](BB.Dsl.Bridge.md): A parameter protocol bridge for remote access.
  - [BB.Dsl.Capsule](BB.Dsl.Capsule.md): A capsule geometry (cylinder with hemispherical caps).
  - [BB.Dsl.Category](BB.Dsl.Category.md): A command category for grouping commands with concurrent execution limits.
  - [BB.Dsl.CategoryTransformer](BB.Dsl.CategoryTransformer.md): Collects category definitions and injects category-related functions.
  - [BB.Dsl.Collision](BB.Dsl.Collision.md): Collision information

  - [BB.Dsl.Color](BB.Dsl.Color.md): A color

  - [BB.Dsl.Command](BB.Dsl.Command.md): A command that can be executed on the robot.
  - [BB.Dsl.Command.Argument](BB.Dsl.Command.Argument.md): An argument for a command.
  - [BB.Dsl.CommandTransformer](BB.Dsl.CommandTransformer.md): Generates convenience functions for commands on the robot module.
  - [BB.Dsl.Controller](BB.Dsl.Controller.md): A controller process at the robot level.
  - [BB.Dsl.Cylinder](BB.Dsl.Cylinder.md): A cylindrical geometry

  - [BB.Dsl.DefaultNameTransformer](BB.Dsl.DefaultNameTransformer.md): Ensures that the default robot name is present
  - [BB.Dsl.Dynamics](BB.Dsl.Dynamics.md): Specifies physical properties of the joint. These values are used to specify modeling properties of the joint, particularly useful for simulation

  - [BB.Dsl.Inertia](BB.Dsl.Inertia.md): Inertial information.

  - [BB.Dsl.Inertial](BB.Dsl.Inertial.md): Inertial information.

  - [BB.Dsl.Joint](BB.Dsl.Joint.md): A joint in the robot topology chain.

  - [BB.Dsl.Limit](BB.Dsl.Limit.md): Joint limits

  - [BB.Dsl.Link](BB.Dsl.Link.md): A kinematic link aka a solid body in a kinematic chain.

  - [BB.Dsl.Material](BB.Dsl.Material.md): A material

  - [BB.Dsl.Mesh](BB.Dsl.Mesh.md): A 3D model (mesh)

  - [BB.Dsl.Origin](BB.Dsl.Origin.md): An origin location.

  - [BB.Dsl.Param](BB.Dsl.Param.md): A runtime-adjustable parameter.
  - [BB.Dsl.ParamGroup](BB.Dsl.ParamGroup.md): A group of runtime-adjustable parameters.
  - [BB.Dsl.ParamRef](BB.Dsl.ParamRef.md): A reference to a parameter for use in DSL fields.
  - [BB.Dsl.ParameterTransformer](BB.Dsl.ParameterTransformer.md): Generates parameter schema and default values from DSL definitions.
  - [BB.Dsl.RobotTransformer](BB.Dsl.RobotTransformer.md): Builds and persists the optimised Robot struct at compile-time.
  - [BB.Dsl.Sensor](BB.Dsl.Sensor.md): A sensor attached to the robot or a specific link.
  - [BB.Dsl.Sphere](BB.Dsl.Sphere.md): A spherical geometry

  - [BB.Dsl.State](BB.Dsl.State.md): A custom operational state for the robot.
  - [BB.Dsl.StateTransformer](BB.Dsl.StateTransformer.md): Collects state definitions and injects state-related functions.
  - [BB.Dsl.SupervisorTransformer](BB.Dsl.SupervisorTransformer.md): Injects `start_link/1` and `child_spec/1` into robot modules.
  - [BB.Dsl.Texture](BB.Dsl.Texture.md): A 2D texture

  - [BB.Dsl.TopologyTransformer](BB.Dsl.TopologyTransformer.md): Validate and transform links as required.

  - [BB.Dsl.UniquenessTransformer](BB.Dsl.UniquenessTransformer.md): Validates that all entity names are globally unique across the robot.
  - [BB.Dsl.ValidateLimitUnitsTransformer](BB.Dsl.ValidateLimitUnitsTransformer.md): Validates that the units provided in a joint's `limit` block are compatible
with the joint's type.
  - [BB.Dsl.Verifiers.ValidateCategoryRefs](BB.Dsl.Verifiers.ValidateCategoryRefs.md): Validates that category references in commands are valid.
  - [BB.Dsl.Verifiers.ValidateChildSpecs](BB.Dsl.Verifiers.ValidateChildSpecs.md): Validates that child_spec options match the module's schema.
  - [BB.Dsl.Verifiers.ValidateParamRefs](BB.Dsl.Verifiers.ValidateParamRefs.md): Validates that parameter references in the DSL refer to valid parameters.
  - [BB.Dsl.Verifiers.ValidateStateRefs](BB.Dsl.Verifiers.ValidateStateRefs.md): Validates that state references in commands are valid.
  - [BB.Dsl.Visual](BB.Dsl.Visual.md): A material

  - [BB.Dsl.WildcardExpansionTransformer](BB.Dsl.WildcardExpansionTransformer.md): Expands `:*` wildcards in command `allowed_states` and `cancel` options.

- Commands
  - [BB.Command](BB.Command.md): Behaviour for implementing robot commands.
  - [BB.Command.Arm](BB.Command.Arm.md): Standard command handler for arming a robot.
  - [BB.Command.Context](BB.Command.Context.md): Context provided to command handlers during execution.
  - [BB.Command.Disarm](BB.Command.Disarm.md): Standard command handler for disarming a robot.
  - [BB.Command.Event](BB.Command.Event.md): Payload type for command execution events.
  - [BB.Command.MoveTo](BB.Command.MoveTo.md): Standard command handler for moving end-effectors to target positions.
  - [BB.Command.ResultCache](BB.Command.ResultCache.md): Caches command results for retrieval after the command process terminates.
  - [BB.Command.Server](BB.Command.Server.md): GenServer wrapper for command callback modules.
  - [BB.Command.SetState](BB.Command.SetState.md): Reusable command handler for transitioning between operational states.

- Controllers
  - [BB.Controller](BB.Controller.md): Behaviour for controllers in the BB framework.
  - [BB.Controller.Action](BB.Controller.Action.md): Action builders and executor for reactive controllers.
  - [BB.Controller.Action.Callback](BB.Controller.Action.Callback.md): Action that calls an arbitrary function.
  - [BB.Controller.Action.Command](BB.Controller.Action.Command.md): Action that invokes a robot command.
  - [BB.Controller.Action.Context](BB.Controller.Action.Context.md): Context provided to action callbacks.
  - [BB.Controller.PatternMatch](BB.Controller.PatternMatch.md): Controller that triggers an action when a message matches a predicate.
  - [BB.Controller.Server](BB.Controller.Server.md): Wrapper GenServer for controller callback modules.
  - [BB.Controller.Threshold](BB.Controller.Threshold.md): Convenience wrapper around PatternMatch for threshold monitoring.

- Sensors
  - [BB.Sensor](BB.Sensor.md): Behaviour and API for sensors in the BB framework.
  - [BB.Sensor.Mimic](BB.Sensor.Mimic.md): A sensor that derives joint state from another joint.
  - [BB.Sensor.OpenLoopPositionEstimator](BB.Sensor.OpenLoopPositionEstimator.md): A "sensor" that estimates joint position for open-loop control systems.
  - [BB.Sensor.Server](BB.Sensor.Server.md): Wrapper GenServer for sensor callback modules.

- Actuators
  - [BB.Actuator](BB.Actuator.md): Behaviour and API for actuators in the BB framework.
  - [BB.Actuator.Server](BB.Actuator.Server.md): Wrapper GenServer for actuator callback modules.

- Messages
  - [BB.Message](BB.Message.md): Message envelope and behaviour for payload types.
  - [BB.Message.Actuator.BeginMotion](BB.Message.Actuator.BeginMotion.md): Message published by actuators when beginning a motion.
  - [BB.Message.Actuator.Command.Effort](BB.Message.Actuator.Command.Effort.md): Command to apply a specific effort (torque/force) to an actuator.
  - [BB.Message.Actuator.Command.Hold](BB.Message.Actuator.Command.Hold.md): Command an actuator to actively maintain its current position.
  - [BB.Message.Actuator.Command.Position](BB.Message.Actuator.Command.Position.md): Command to move an actuator to a target position.
  - [BB.Message.Actuator.Command.Stop](BB.Message.Actuator.Command.Stop.md): Command to stop an actuator's motion.
  - [BB.Message.Actuator.Command.Trajectory](BB.Message.Actuator.Command.Trajectory.md): Command an actuator to follow a trajectory defined by waypoints.
  - [BB.Message.Actuator.Command.Velocity](BB.Message.Actuator.Command.Velocity.md): Command to set an actuator's velocity.
  - [BB.Message.Actuator.EndMotion](BB.Message.Actuator.EndMotion.md): Message published by actuators when motion ends.
  - [BB.Message.Geometry.Accel](BB.Message.Geometry.Accel.md): Linear and angular acceleration in 3D space.
  - [BB.Message.Geometry.Point3D](BB.Message.Geometry.Point3D.md): A 3D point in space.
  - [BB.Message.Geometry.Pose](BB.Message.Geometry.Pose.md): A position and orientation in 3D space.
  - [BB.Message.Geometry.Twist](BB.Message.Geometry.Twist.md): Linear and angular velocity in 3D space.
  - [BB.Message.Geometry.Wrench](BB.Message.Geometry.Wrench.md): Force and torque in 3D space.
  - [BB.Message.Option](BB.Message.Option.md): Custom Spark.Options types for message primitives.
  - [BB.Message.Sensor.BatteryState](BB.Message.Sensor.BatteryState.md): Battery state information.
  - [BB.Message.Sensor.Image](BB.Message.Sensor.Image.md): Raw image data from a camera sensor.
  - [BB.Message.Sensor.Imu](BB.Message.Sensor.Imu.md): Inertial Measurement Unit data.
  - [BB.Message.Sensor.JointState](BB.Message.Sensor.JointState.md): State of a set of joints.
  - [BB.Message.Sensor.LaserScan](BB.Message.Sensor.LaserScan.md): Single scan from a planar laser range-finder.
  - [BB.Message.Sensor.Range](BB.Message.Sensor.Range.md): Single range reading from a distance sensor.

- Safety
  - [BB.Safety](BB.Safety.md): Safety system API.
  - [BB.Safety.Controller](BB.Safety.Controller.md): Global safety controller that owns arm/disarm state for all robots.
  - [BB.Safety.HardwareError](BB.Safety.HardwareError.md): Payload type for hardware error events.

- Parameters
  - [BB.Parameter](BB.Parameter.md): Runtime-adjustable parameters for robot components.
  - [BB.Parameter.Changed](BB.Parameter.Changed.md): Payload type for parameter change events.
  - [BB.Parameter.Schema](BB.Parameter.Schema.md): Builds nested Spark.Options schemas from flat parameter definitions.
  - [BB.Parameter.Store](BB.Parameter.Store.md): Behaviour for parameter persistence backends.
  - [BB.Parameter.Store.Dets](BB.Parameter.Store.Dets.md): DETS-backed parameter persistence.
  - [BB.Parameter.Type](BB.Parameter.Type.md): Validation for parameter type definitions in the DSL.

- Kinematics
  - [BB.IK.Solver](BB.IK.Solver.md): Behaviour for inverse kinematics solvers in the BB ecosystem.
  - [BB.Motion](BB.Motion.md): High-level motion primitives that bridge IK solving and actuator commands.
  - [BB.Motion.Tracker](BB.Motion.Tracker.md): Behaviour for continuous position tracking with IK.
  - [BB.Robot.Kinematics](BB.Robot.Kinematics.md): Kinematic computations for robot manipulators.

- Math
  - [BB.Math.Quaternion](BB.Math.Quaternion.md): Unit quaternion for 3D rotations, backed by an Nx tensor.
  - [BB.Math.Transform](BB.Math.Transform.md): Homogeneous transformation matrices for 3D transformations, backed by an Nx tensor.
  - [BB.Math.Vec3](BB.Math.Vec3.md): 3D vector backed by an Nx tensor.

- Errors
  - [BB.Error](BB.Error.md): Structured error handling for the Beam Bots ecosystem.
  - [BB.Error.Category](BB.Error.Category.md): Error class for command category-related errors.
  - [BB.Error.Category.Full](BB.Error.Category.Full.md): Category is at capacity for concurrent commands.
  - [BB.Error.Hardware](BB.Error.Hardware.md): Hardware communication error classes.
  - [BB.Error.Hardware.BusError](BB.Error.Hardware.BusError.md): Communication bus error (I2C, serial, etc.).
  - [BB.Error.Hardware.DeviceError](BB.Error.Hardware.DeviceError.md): Error reported by the hardware device itself.
  - [BB.Error.Hardware.Disconnected](BB.Error.Hardware.Disconnected.md): Hardware device is disconnected or not responding.
  - [BB.Error.Hardware.Timeout](BB.Error.Hardware.Timeout.md): Communication timeout with a hardware device.
  - [BB.Error.Invalid](BB.Error.Invalid.md): Configuration and validation error classes.
  - [BB.Error.Invalid.Command](BB.Error.Invalid.Command.md): Invalid command or command arguments.
  - [BB.Error.Invalid.JointConfig](BB.Error.Invalid.JointConfig.md): Invalid joint configuration.
  - [BB.Error.Invalid.Parameter](BB.Error.Invalid.Parameter.md): Invalid runtime parameter.
  - [BB.Error.Invalid.Topology](BB.Error.Invalid.Topology.md): Robot topology configuration error.
  - [BB.Error.Kinematics](BB.Error.Kinematics.md): Kinematics and motion planning error classes.
  - [BB.Error.Kinematics.MultiFailed](BB.Error.Kinematics.MultiFailed.md): Multi-target inverse kinematics failed.
  - [BB.Error.Kinematics.NoDofs](BB.Error.Kinematics.NoDofs.md): Kinematic chain has no degrees of freedom.
  - [BB.Error.Kinematics.NoSolution](BB.Error.Kinematics.NoSolution.md): Inverse kinematics solver failed to converge.
  - [BB.Error.Kinematics.SelfCollision](BB.Error.Kinematics.SelfCollision.md): Motion would cause self-collision.
  - [BB.Error.Kinematics.Singularity](BB.Error.Kinematics.Singularity.md): Robot is near or at a kinematic singularity.
  - [BB.Error.Kinematics.UnknownLink](BB.Error.Kinematics.UnknownLink.md): Target link not found in robot topology.
  - [BB.Error.Kinematics.Unreachable](BB.Error.Kinematics.Unreachable.md): Target pose is outside the robot's workspace.
  - [BB.Error.Protocol](BB.Error.Protocol.md): Low-level protocol error classes.
  - [BB.Error.Safety](BB.Error.Safety.md): Safety system error classes.
  - [BB.Error.Safety.CollisionRisk](BB.Error.Safety.CollisionRisk.md): Potential collision detected.
  - [BB.Error.Safety.DisarmFailed](BB.Error.Safety.DisarmFailed.md): Disarm callback failed for a component.
  - [BB.Error.Safety.EmergencyStop](BB.Error.Safety.EmergencyStop.md): Emergency stop triggered.
  - [BB.Error.Safety.LimitExceeded](BB.Error.Safety.LimitExceeded.md): Physical limit exceeded on a joint or actuator.
  - [BB.Error.Severity](BB.Error.Severity.md): Protocol for determining error severity.
  - [BB.Error.State](BB.Error.State.md): State machine error classes.
  - [BB.Error.State.CommandCrashed](BB.Error.State.CommandCrashed.md): A command crashed during execution.
  - [BB.Error.State.Invalid](BB.Error.State.Invalid.md): Invalid state reference.
  - [BB.Error.State.NotAllowed](BB.Error.State.NotAllowed.md): Operation not allowed in current state.
  - [BB.Error.State.Preempted](BB.Error.State.Preempted.md): Operation was preempted by another operation.
  - [BB.Error.State.Timeout](BB.Error.State.Timeout.md): State transition timed out.

- Collision
  - [BB.Collision](BB.Collision.md): Collision detection for BB robots.
  - [BB.Collision.BroadPhase](BB.Collision.BroadPhase.md): Broad phase collision detection using Axis-Aligned Bounding Boxes (AABBs).
  - [BB.Collision.Mesh](BB.Collision.Mesh.md): Mesh loading and bounding geometry computation for collision detection.
  - [BB.Collision.Primitives](BB.Collision.Primitives.md): Collision detection algorithms for primitive geometry pairs.

- URDF
  - [BB.Urdf.Exporter](BB.Urdf.Exporter.md): Export a BB robot definition to URDF XML format.

  - [BB.Urdf.Xml](BB.Urdf.Xml.md): XML building utilities using Erlang's xmerl library.

- Simulation
  - [BB.Sim.Actuator](BB.Sim.Actuator.md): Simulated actuator for kinematic simulation mode.
  - [BB.Sim.Bridge](BB.Sim.Bridge.md): Mock bridge for simulation mode.
  - [BB.Sim.Controller](BB.Sim.Controller.md): Mock controller for simulation mode.

- Bridges
  - [BB.Bridge](BB.Bridge.md): Behaviour for parameter bridge GenServers in the BB framework.
  - [BB.BridgeSupervisor](BB.BridgeSupervisor.md): Supervisor for parameter protocol bridges.

- Examples
  - [BB.ExampleRobots](BB.ExampleRobots.md): Example robot topologies for testing and documentation.

  - [BB.ExampleRobots.CollisionTestArm](BB.ExampleRobots.CollisionTestArm.md): A simple 2-DOF arm with collision geometry for testing self-collision detection.
  - [BB.ExampleRobots.DifferentialDriveRobot](BB.ExampleRobots.DifferentialDriveRobot.md): A simple two-wheeled differential drive robot with a caster.
  - [BB.ExampleRobots.LinearActuator](BB.ExampleRobots.LinearActuator.md): A simple linear actuator (prismatic joint example).
  - [BB.ExampleRobots.PanTiltCamera](BB.ExampleRobots.PanTiltCamera.md): A simple pan-tilt camera mount.
  - [BB.ExampleRobots.SixDofArm](BB.ExampleRobots.SixDofArm.md): A 6 degree-of-freedom industrial robot arm.

- Testing
  - [BB.Test.AsyncCommand](BB.Test.AsyncCommand.md): A test command that waits for an explicit :complete message before finishing.
  - [BB.Test.MockActuator](BB.Test.MockActuator.md): Minimal mock actuator for testing.

  - [BB.Test.MockBridge](BB.Test.MockBridge.md): Minimal mock bridge for testing.

  - [BB.Test.MockController](BB.Test.MockController.md): Minimal mock controller for testing.

  - [BB.Test.MockSolver](BB.Test.MockSolver.md): Mock IK solver for testing BB.Motion without real IK computations.
  - [BB.Test.ParameterBridge](BB.Test.ParameterBridge.md): Reference implementation of `BB.Bridge` for testing.

- Units
  - [BB.Unit](BB.Unit.md): Helpers for working with units in BB DSLs.
  - [BB.Unit.Option](BB.Unit.Option.md): Functions for specifying and validating units in option schemas.

- Internals
  - [BB.ControllerSupervisor](BB.ControllerSupervisor.md): Supervisor for robot-level controllers.
  - [BB.Diagnostic](BB.Diagnostic.md): Diagnostic reporting for monitoring and awareness.
  - [BB.Igniter](BB.Igniter.md): Helpers for writing Igniter installers for BB add-on packages.
  - [BB.JointSupervisor](BB.JointSupervisor.md): Supervisor for a joint and its child link.
  - [BB.LinkSupervisor](BB.LinkSupervisor.md): Supervisor for a link and its joints.
  - [BB.Process](BB.Process.md): Helper functions for building child specs and looking up processes in the robot's registry.

  - [BB.Robot.Builder](BB.Robot.Builder.md): Builds an optimised `BB.Robot` struct from DSL output.
  - [BB.Robot.CommandInfo](BB.Robot.CommandInfo.md): Information about a currently executing command.
  - [BB.Robot.Joint](BB.Robot.Joint.md): An optimised joint representation with all units converted to SI floats.
  - [BB.Robot.Link](BB.Robot.Link.md): An optimised link representation with all units converted to SI floats.
  - [BB.Robot.ParamResolver](BB.Robot.ParamResolver.md): Resolves parameter references in robot structs.
  - [BB.Robot.Runtime](BB.Robot.Runtime.md): Runtime process for a BB robot.
  - [BB.Robot.State](BB.Robot.State.md): ETS-backed mutable state for robot instances.
  - [BB.Robot.Topology](BB.Robot.Topology.md): Pre-computed topology metadata for efficient traversal and kinematic operations.
  - [BB.Robot.Units](BB.Robot.Units.md): Unit conversion functions for transforming `Localize.Unit` values into base
SI floats.
  - [BB.SensorSupervisor](BB.SensorSupervisor.md): Supervisor for robot-level sensors.
  - [BB.Server.ParamResolution](BB.Server.ParamResolution.md): Shared parameter resolution logic for wrapper servers.
  - [BB.StateMachine.Transition](BB.StateMachine.Transition.md): Payload type for state machine transition events.

  - [BB.TopologySupervisor](BB.TopologySupervisor.md): Supervisor for all hardware-facing subsystems of a robot.

## Mix Tasks

- Mix Tasks
  - [mix bb.add_nx_backend](Mix.Tasks.Bb.AddNxBackend.md): Configures an Nx backend for the project
  - [mix bb.add_robot](Mix.Tasks.Bb.AddRobot.md): Adds a new robot module to your project
  - [mix bb.install](Mix.Tasks.Bb.Install.md): Installs BB into a project
  - [mix bb.to_urdf](Mix.Tasks.Bb.ToUrdf.md): Export a BB robot definition to URDF XML format.

