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)
[![Hexdocs badge](https://img.shields.io/badge/docs-hexdocs-purple)](https://hexdocs.pm/bb)
[![REUSE status](https://api.reuse.software/badge/github.com/beam-bots/bb)](https://api.reuse.software/info/github.com/beam-bots/bb)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/11772/badge)](https://www.bestpractices.dev/projects/11772)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/beam-bots/bb/badge)](https://scorecard.dev/viewer/?uri=github.com/beam-bots/bb)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/beam-bots/bb)

Beam Bots is a framework for building resilient robotics projects in Elixir.

`bb` is the core of a wider ecosystem of packages — servo drivers, sensors,
inverse kinematics solvers, visualisation tooling and more — that work together
so you can build your robot with exactly the features you want. Browse the full
list at [github.com/beam-bots](https://github.com/orgs/beam-bots/repositories).

## 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.Robot do
  use BB

  topology do
    link :base_link 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.Robot)

# Compute forward kinematics
robot = MyRobot.Robot.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.Robot -o robot.urdf
```

## Documentation

### Tutorials

Guided introduction to Beam Bots:

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

### How-to Guides

Task-oriented guides for common operations:

- [Integrate a Servo Driver](https://hexdocs.pm/bb/integrate-servo-driver.html) - creating hardware driver packages
- [Add a Custom Command](https://hexdocs.pm/bb/add-custom-command.html) - extending the command system
- [Implement Safety Callbacks](https://hexdocs.pm/bb/implement-safety-callbacks.html) - safe hardware shutdown
- [Deploy to Nerves](https://hexdocs.pm/bb/deploy-to-nerves.html) - embedded deployment
- [Write a Custom Sensor](https://hexdocs.pm/bb/write-custom-sensor.html) - creating sensor modules

### Explanation

Understanding the architecture:

- [Understanding Safety](https://hexdocs.pm/bb/understanding-safety.html) - the safety system design
- [Supervision Architecture](https://hexdocs.pm/bb/supervision-architecture.html) - why topology mirrors supervision
- [Command System](https://hexdocs.pm/bb/command-system.html) - command execution patterns
- [PubSub System](https://hexdocs.pm/bb/pubsub-system.html) - hierarchical messaging

### Reference

- [DSL Reference](https://hexdocs.pm/bb/dsl-bb.html) - all DSL options
- [Message Types](https://hexdocs.pm/bb/message-types.html) - PubSub message schemas
- [Error Types](https://hexdocs.pm/bb/error-types.html) - structured error reference
- [Telemetry Events](https://hexdocs.pm/bb/telemetry-events.html) - observability

## Status

Core functionality is implemented. The companion packages that build on `bb`
live alongside it at [github.com/beam-bots](https://github.com/orgs/beam-bots/repositories),
and [proposals](https://github.com/beam-bots/proposals) tracks planned features.

## 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)).

## Sponsors

This project is made possible by the generous support of our sponsors:

- **[Alembic](https://alembic.com.au)** ([@team-alembic](https://github.com/team-alembic)) - Development Support
- **Frank Hunleth** ([@fhunleth](https://github.com/fhunleth)) - Hardware Donation
- **Pascal Charbonneau** ([@pcharbon70](https://github.com/pcharbon70)) - GitHub Sponsor