bb

<!--
SPDX-FileCopyrightText: 2025 James Harton
SPDX-License-Identifier: Apache-2.0
-->
<img src="https://github.com/beam-bots/bb/blob/main/logos/beam_bots_logo.png?raw=true" alt="Beam Bots Logo" width="250" />
# Beam Bots
[![CI](https://github.com/beam-bots/bb/actions/workflows/ci.yml/badge.svg)](https://github.com/beam-bots/bb/actions/workflows/ci.yml)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache--2.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
[![Hex version badge](https://img.shields.io/hexpm/v/bb.svg)](https://hex.pm/packages/bb)
[![REUSE status](https://api.reuse.software/badge/github.com/beam-bots/bb)](https://api.reuse.software/info/github.com/beam-bots/bb)
Beam Bots is a framework for building resilient robotics projects in Elixir.
## Features
- **Spark DSL** for defining robot topologies (links, joints, sensors, actuators)
- **Physical units** via `~u` sigil with automatic SI conversion (e.g., `~u(90 degree)`, `~u(0.1 meter)`)
- **Topology-based supervision** - supervision tree mirrors robot structure for fault isolation
- **Hierarchical PubSub** - subscribe to messages by path or subtree
- **Forward kinematics** - compute link positions using Nx tensors
- **Message system** - typed payloads with schema validation
- **Command system** - state machine with arm/disarm and custom commands
- **URDF export** - export robot definitions for use with ROS tools
## Example
```elixir
defmodule MyRobot do
  use BB
  topology do
    link :base do
      joint :shoulder do
        type(:revolute)
        origin do
          z(~u(0.1 meter))
        end
        axis do
        end
        limit do
          effort(~u(10 newton_meter))
          velocity(~u(1 radian_per_second))
        end
        link :upper_arm do
          joint :elbow do
            type(:revolute)
            origin do
              z(~u(0.3 meter))
            end
            axis do
              roll(~u(-90 degree))
            end
            limit do
              effort(~u(10 newton_meter))
              velocity(~u(1 radian_per_second))
            end
            link :forearm do
            end
          end
        end
      end
    end
  end
end
# Start the supervision tree
{:ok, _pid} = BB.Supervisor.start_link(MyRobot)
# Compute forward kinematics
robot = MyRobot.robot()
positions = %{shoulder: :math.pi() / 4, elbow: 0.0}
{x, y, z} = BB.Robot.Kinematics.link_position(robot, positions, :forearm)
# Export to URDF
mix bb.to_urdf MyRobot -o robot.urdf
```
## Documentation
See the tutorials for a guided introduction:
1. [Your First Robot](https://hexdocs.pm/bb/01-first-robot.html) - defining robots with the DSL
2. [Starting and Stopping](https://hexdocs.pm/bb/02-starting-and-stopping.html) - supervision trees
3. [Sensors and PubSub](https://hexdocs.pm/bb/03-sensors-and-pubsub.html) - publishing and subscribing to messages
4. [Forward Kinematics](https://hexdocs.pm/bb/04-kinematics.html) - computing link positions
5. [Commands and State Machine](https://hexdocs.pm/bb/05-commands.html) - controlling the robot
6. [Exporting to URDF](https://hexdocs.pm/bb/06-urdf-export.html) - interoperability with ROS tools
7. [Parameters](https://hexdocs.pm/bb/07-parameters.html) - runtime-adjustable configuration
8. [Parameter Bridges](https://hexdocs.pm/bb/08-parameter-bridges.html) - bidirectional remote access
The [DSL Reference](https://hexdocs.pm/bb/dsl-bb.html) documents all available options.
## Status
Core functionality is implemented. Planned additions:
- `bb_sitl` - simulation integration (Gazebo, etc.)
- `bb_rc_servo` - PWM-based RC servo driver
- `bb_mavlink` - MAVLink protocol bridge
- `bb_crossfire` - Crossfire RC bridge
## Installation
### With Igniter (Recommended)
If your project uses [Igniter](https://hex.pm/packages/igniter):
```bash
mix igniter.install bb
```
This will:
- Add Beam Bots to your dependencies
- Create a `{YourApp}.Robot` module with arm/disarm commands and a base link
- Add the robot to your application supervision tree
- Configure the formatter for the Beam Bots DSL
To add additional robots later:
```bash
mix bb.add_robot --robot MyApp.Robots.SecondRobot
```
### Manual Installation
Add Beam Bots to your dependencies:
```elixir
def deps do
  [
    {:bb, "~> 0.1"}
  ]
end
```
Then create a robot module manually (see [Your First Robot](https://hexdocs.pm/bb/01-first-robot.html)).