Reachy Elixir

Elixir/OTP implementation of the Reachy Mini robot control system, designed for fault-tolerance, real-time control, and expressive behaviors.

Features

• Fault-Tolerant Architecture: Supervision trees mirror physical robot structure
• Real-Time Control: 50Hz motor control loops with trajectory interpolation
• Native Performance: Zig NIFs for Dynamixel protocol, Rust NIFs for kinematics
• Expressive Behaviors: Idle animations, face tracking, and more
• Web Interface: REST API and WebSocket for remote control
• Nerves Ready: Production deployment to Raspberry Pi

Architecture

ReachyMini.Supervisor
├── Registry
├── PubSub
├── DynamixelBus (Zig NIF)
├── Safety.Controller
├── Actuators.MotorSupervisor
│   ├── Motor (body_yaw)
│   ├── Motor (stewart_1..6)
│   └── Motor (antenna_left, antenna_right)
├── Actuators.StewartPlatform (Rust NIF)
├── Motion
├── Behaviors.Supervisor
│   ├── IdleAnimations
│   ├── FaceTracking
│   └── Animations
├── Recording
└── Bridge.Endpoint (Phoenix)

Quick Start

Development (Simulation)

# Install dependencies
mix deps.get

# Run in simulation mode
MIX_TARGET=host mix run --no-halt

# In another terminal, interact via IEx
iex -S mix

Hardware (Raspberry Pi)

# Set target
export MIX_TARGET=rpi4

# Get dependencies and build firmware
mix deps.get
mix firmware

# Deploy to robot
mix upload reachy.local

Usage

# Arm the robot
ReachyMini.arm()

# Move head
ReachyMini.set_head_pose(%{pitch: 0.2, yaw: 0.3})

# Look at a point
ReachyMini.look_at({0.5, 0.1, 0.3})

# Play animation
ReachyMini.play_animation(:happy)

# Wiggle antennas
ReachyMini.wiggle_antennas()

# Disarm
ReachyMini.disarm()

API

REST Endpoints

Endpoint	Method	Description
/api/state	GET	Get full robot state
/api/arm	POST	Arm the robot
/api/disarm	POST	Disarm the robot
/api/move/head	POST	Move head to pose
/api/move/look_at	POST	Look at point
/api/animation/:name	POST	Play animation

WebSocket

Connect to /api/ws for real-time updates:

const socket = new Phoenix.Socket("/api/ws")
socket.connect()

const channel = socket.channel("state:full")
channel.on("state", state => console.log(state))
channel.join()

Configuration

# config/config.exs

config :beachy,
  robot_name: "beachy",
  control_rate_hz: 50,
  dynamixel: [
    port: "/dev/ttyUSB0",
    baudrate: 1_000_000
  ],
  motors: %{
    body_yaw: %{id: 10, model: :xc330_m288},
    stewart_1: %{id: 11, model: :xl330_m288},
    # ...
  }

Project Structure

lib/
├── beachy.ex              # Main API
├── beachy/
│   ├── application.ex          # OTP Application
│   ├── safety.ex               # Safety controller
│   ├── motion.ex               # Motion coordination
│   ├── recording.ex            # Motion recording/playback
│   ├── diagnostics.ex          # System diagnostics
│   ├── telemetry.ex            # Metrics collection
│   ├── actuators/
│   │   ├── motor.ex            # Individual motor control
│   │   ├── motor_supervisor.ex # Motor supervision
│   │   └── stewart_platform.ex # Stewart platform control
│   ├── kinematics/
│   │   └── stewart.ex          # Stewart platform kinematics
│   ├── protocol/
│   │   ├── dynamixel.ex        # Dynamixel protocol (Zig NIF)
│   │   └── dynamixel_bus.ex    # Serial bus management
│   ├── behaviors/
│   │   ├── supervisor.ex       # Behavior supervision
│   │   ├── idle_animations.ex  # Idle animations
│   │   ├── face_tracking.ex    # Face tracking
│   │   └── animations.ex       # Predefined animations
│   └── bridge/
│       ├── endpoint.ex         # Phoenix endpoint
│       ├── router.ex           # API routes
│       ├── socket.ex           # WebSocket
│       └── controllers/        # API controllers

native/
├── dynamixel_nif/              # Zig implementation
│   └── dynamixel.zig
└── kinematics_nif/             # Rust implementation
    ├── Cargo.toml
    └── src/lib.rs

Native Code

Dynamixel Protocol (Zig)

High-performance packet building and parsing with compile-time CRC tables:

// Build a sync write packet for all Stewart motors
pub fn buildSyncWritePacket(ids: []const u8, address: u16, ...) Packet

Stewart Platform Kinematics (Rust)

Fast inverse/forward kinematics using nalgebra:

// Compute leg lengths for desired head pose
pub fn inverse_kinematics(pose: &Pose) -> Result<[f64; 6], ()>

Testing

# Run all tests
mix test

# Run with coverage
mix test --cover

# Run specific test
mix test test/beachy/kinematics/stewart_test.exs

Deployment

OTA Updates

# Build new firmware
mix firmware

# Push to running robot
mix upload reachy.local

SSH Access

ssh reachy.local

# In IEx
iex> ReachyMini.status()
iex> ReachyMini.run_diagnostics()

License

Apache 2.0