This document provides a high-level introduction to the Beam Bots (BB) framework, explaining its purpose, core architecture, and major subsystems. It serves as the entry point for understanding how the framework's components work together to enable resilient robotics applications.
For detailed information about specific subsystems, see:
Beam Bots is a framework for building resilient robotics projects in Elixir, leveraging the BEAM VM's fault-tolerance capabilities. The framework is built on three core principles:
The framework provides a complete robotics platform including kinematics, motion control, safety systems, hierarchical messaging, and parameter management.
Sources: README.md9-31 mix.exs8-10 AGENTS.md12-13
The BB framework operates across three architectural layers: compile-time DSL processing, runtime systems, and component processes. The following diagram shows how these layers interact using actual module names from the codebase.
Sources: lib/bb/dsl.ex lib/bb/supervisor.ex lib/bb/robot/runtime.ex lib/bb/safety/controller.ex lib/bb/pub_sub.ex AGENTS.md59-101
The framework performs extensive compile-time processing to eliminate runtime overhead. The following diagram shows how a user's robot definition is transformed into running processes, using actual file paths and function names.
Sources: lib/bb/dsl.ex1-100 lib/bb/dsl/transformer/default_name.ex lib/bb/dsl/transformer/topology.ex lib/bb/dsl/transformer/robot.ex lib/bb/supervisor.ex1-50 AGENTS.md75-82
The following table maps the major subsystems to their primary modules and file locations in the codebase:
| Subsystem | Primary Modules | File Paths | Purpose |
|---|---|---|---|
| DSL Layer | BB.Dsl, BB.Dsl.Transformer.*, BB.Dsl.Verifier.* | lib/bb/dsl.ex lib/bb/dsl/transformer/ lib/bb/dsl/verifier/ | Compile-time robot definition processing |
| Core Runtime | BB.Robot.Runtime, BB.Robot.State, BB.Supervisor | lib/bb/robot/runtime.ex lib/bb/robot/state.ex lib/bb/supervisor.ex | State coordination, supervision tree |
| Safety System | BB.Safety, BB.Safety.Controller | lib/bb/safety.ex lib/bb/safety/controller.ex | Arm/disarm management, hardware safety |
| Communication | BB.PubSub, BB.Message | lib/bb/pub_sub.ex lib/bb/message.ex | Hierarchical messaging, payload schemas |
| Commands | BB.Command, BB.Command.Server, BB.Command.Arm, BB.Command.Disarm | lib/bb/command.ex lib/bb/command/server.ex | Command execution, state machine integration |
| Motion & Kinematics | BB.Motion, BB.Robot.Kinematics, BB.IK.Solver, BB.Collision.Mesh | lib/bb/motion.ex lib/bb/robot/kinematics.ex lib/bb/ik/solver.ex lib/bb/collision/mesh.ex | Forward/inverse kinematics, collision detection |
| Parameters | BB.Parameter, BB.Parameter.Store, BB.Bridge | lib/bb/parameter.ex lib/bb/parameter/store.ex lib/bb/bridge.ex | Runtime configuration, remote parameter access |
| Simulation | BB.Sim.Actuator, BB.Sensor.OpenLoopPositionEstimator | lib/bb/sim/actuator.ex lib/bb/sensor/open_loop_position_estimator.ex | Hardware-less development and testing |
| Components | BB.Sensor, BB.Actuator, BB.Controller, BB.Bridge | lib/bb/sensor.ex lib/bb/actuator.ex lib/bb/controller.ex | Behavior definitions for robot components |
| Units & Math | BB.Unit, BB.Math.Transform, BB.Math.Vec3, BB.Math.Quaternion | lib/bb/unit.ex lib/bb/math/transform.ex | Physical units, transforms, linear algebra |
| Errors | BB.Error, BB.Error.*, BB.Error.Severity | lib/bb/error.ex lib/bb/error/ | Structured error handling with severity protocol |
Sources: mix.exs69-154 lib/bb/
At runtime, a robot consists of multiple supervised processes. The following diagram shows the process hierarchy using actual supervision strategies and process types from the codebase.
Sources: lib/bb/application.ex lib/bb/supervisor.ex lib/bb/link_supervisor.ex lib/bb/joint_supervisor.ex lib/bb/robot/runtime.ex1-100 AGENTS.md90-91
The framework uses hierarchical PubSub for component communication. The following diagram shows how messages flow from components through PubSub to subscribers, using actual message types from the codebase.
Sources: lib/bb/pub_sub.ex1-100 lib/bb/robot/runtime.ex200-300 lib/bb/robot/state.ex lib/bb/message.ex lib/bb/message/sensor/joint_state.ex
The BB framework is built on several key Elixir libraries that enable its functionality:
| Dependency | Version | Purpose | File Reference |
|---|---|---|---|
| Spark | ~> 2.3 | DSL framework for declarative robot definitions | mix.exs205 |
| Splode | ~> 0.2 | Structured error handling with severity protocol | mix.exs206 |
| Nx | ~> 0.10 | Numerical computing for kinematics (tensors, matrices) | mix.exs204 |
| ex_cldr_units | ~> 3.0 | Physical unit handling and SI conversion | mix.exs203 |
| ex_cldr_numbers | ~> 2.36 | Number formatting for units | mix.exs202 |
| Ease | ~> 1.0 | Easing functions for position interpolation | mix.exs201 |
| Phoenix.PubSub | (via Phoenix) | Underlying PubSub implementation | lib/bb/pub_sub.ex1-20 |
Sources: mix.exs199-217 AGENTS.md179-180
The following companion packages extend BB with additional functionality:
Sources: README.md138-145 mix.exs37-44
The current framework version is 0.15.1 (as of 2026-02-08). The framework is licensed under Apache-2.0 and maintained at https://github.com/beam-bots/bb.
Recent major changes include:
BB.Sensor.Mimic for mechanically-linked jointsOpenLoopPositionEstimator in simulation modeSources: mix.exs12 CHANGELOG.md14-75 README.md11-18
Refresh this wiki