Search documentation of bb

# README

Copy Markdown View Source

# 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:

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

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

Next Page → Change Log