Beam Bots

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

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:

Your First Robot - defining robots with the DSL
Starting and Stopping - supervision trees
Sensors and PubSub - publishing and subscribing to messages
Forward Kinematics - computing link positions
Commands and State Machine - controlling the robot
Exporting to URDF - interoperability with ROS tools
Parameters - runtime-adjustable configuration
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. Companion packages:

bb_kino - Livebook widgets for robot control and visualisation
bb_liveview - Phoenix LiveView dashboard
bb_ik_fabrik - FABRIK inverse kinematics solver
bb_servo_pca9685 - PCA9685 PWM servo driver (I2C, 16-channel)
bb_servo_pigpio - pigpio servo driver (Raspberry Pi GPIO)
bb_servo_robotis - Robotis/Dynamixel servo driver

See proposals for 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).