Beam Bots

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.

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

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 - defining robots with the DSL
2. Starting and Stopping - supervision trees
3. Sensors and PubSub - publishing and subscribing to messages
4. Forward Kinematics - computing link positions
5. Commands and State Machine - controlling the robot
6. Exporting to URDF - interoperability with ROS tools
7. Parameters - runtime-adjustable configuration
8. Parameter Bridges - bidirectional remote access

How-to Guides

Task-oriented guides for common operations:

• Integrate a Servo Driver - creating hardware driver packages
• Add a Custom Command - extending the command system
• Implement Safety Callbacks - safe hardware shutdown
• Deploy to Nerves - embedded deployment
• Write a Custom Sensor - creating sensor modules

Explanation

Understanding the architecture:

• Understanding Safety - the safety system design
• Supervision Architecture - why topology mirrors supervision
• Command System - command execution patterns
• PubSub System - hierarchical messaging

Reference

• DSL Reference - all DSL options
• Message Types - PubSub message schemas
• Error Types - structured error reference
• Telemetry Events - observability

Status

Core functionality is implemented. The companion packages that build on bb live alongside it at github.com/beam-bots, and proposals tracks planned features.

Installation

With Igniter (Recommended)

If your project uses Igniter:

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:

mix bb.add_robot --robot MyApp.Robots.SecondRobot

Manual Installation

Add Beam Bots to your dependencies:

def deps do
  [
    {:bb, "~> 0.1"}
  ]
end

Then create a robot module manually (see Your First Robot).

Sponsors

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

• Alembic (@team-alembic) - Development Support
• Frank Hunleth (@fhunleth) - Hardware Donation
• Pascal Charbonneau (@pcharbon70) - GitHub Sponsor