Roarm

An Elixir library for controlling Waveshare RoArm robot arms using Circuits.UART for serial communication. This library replicates the functionality of the official Waveshare RoArm SDK in idiomatic Elixir.

Supported Hardware

This library is designed for the Waveshare RoArm-M2-S and compatible robot arms:

Key Features:

Features

Installation

Add roarm to your list of dependencies in mix.exs:

def deps do
  [
    {:roarm, "~> 0.1.0"}
  ]
end

Hardware Requirements

Quick Start

# Start a registry with the name of the module
{:ok, _} = Registry.start_link(keys: :unique, name: Roarm.Registry)
# Start the robot with your configuration
{:ok, _pid} = Roarm.start_robot(robot_type: :roarm_m2, port: "/dev/cu.usbserial-110", baudrate: 115200)

# Move to a specific position
Roarm.Robot.move_to_position(%{x: 100.0, y: 0.0, z: 150.0, t: 0.0})

# Control individual joints with convenience functions
Roarm.Robot.move_base(45.0)      # Move base joint to 45 degrees
Roarm.Robot.move_shoulder(-30.0) # Move shoulder joint to -30 degrees
Roarm.Robot.move_elbow(90.0)     # Move elbow joint to 90 degrees
Roarm.Robot.move_wrist(0.0)      # Move wrist joint to 0 degrees

# Control RGB LED color (0-255)
Roarm.Robot.set_led(%{r: 255, g: 0, b: 0})

# Control gripper-mounted LED brightness
Roarm.Robot.led_on(200)  # Set brightness to 200/255

# Return to home position
Roarm.Robot.home()

# Enable/disable torque lock
Roarm.Robot.set_torque_lock(true)

Complete API Reference

The RoArm protocol uses JSON commands where "T" represents the Type of command. All commands can be sent using Roarm.Robot.send_custom_command/1 for maximum flexibility.

Movement Commands

System Control Commands

LED and Hardware Control Commands

PID Control Commands

Mission and Task Commands

File System Commands

WiFi Configuration Commands

Robot Model Differences

Joint Layout Reference

RoArm-M2 (4-DOF)

     [4] Hand/Wrist + Gripper
            |
        [3] Elbow
            |
       [2] Shoulder
            |
        [1] Base (rotates entire arm)

RoArm-M3 (6-DOF)

      [6] Gripper
          |
       [5] Wrist
          |
       [4] Hand
          |
      [3] Elbow
          |
     [2] Shoulder
          |
      [1] Base (rotates entire arm)

Convenience Functions

The library provides semantic convenience functions that map to the underlying joint numbers:

# Instead of remembering joint numbers:
Roarm.Robot.move_joint(1, 45.0)    # Base
Roarm.Robot.move_joint(2, -30.0)   # Shoulder
Roarm.Robot.move_joint(3, 90.0)    # Elbow
Roarm.Robot.move_joint(4, 0.0)     # Wrist

# Use semantic names:
Roarm.Robot.move_base(45.0)        # Joint 1
Roarm.Robot.move_shoulder(-30.0)   # Joint 2
Roarm.Robot.move_elbow(90.0)       # Joint 3
Roarm.Robot.move_wrist(0.0)        # Joint 4

# Extended models (M3):
Roarm.Robot.move_wrist_x(15.0)     # Joint 5
Roarm.Robot.move_wrist_y(-20.0)    # Joint 6

Common Usage Examples

Basic Movement Sequence

# Start from home
Roarm.Robot.home()

# Move to pickup position
Roarm.Robot.move_to_position(%{x: 150, y: 100, z: 100, t: 0})

# Close gripper (works for all models)
Roarm.Robot.gripper_close()

# Lift object
Roarm.Robot.move_to_position(%{x: 150, y: 100, z: 200, t: 0})

# Move to drop location
Roarm.Robot.move_to_position(%{x: 200, y: 200, z: 100, t: 0})

# Release object
Roarm.Robot.gripper_open()

# Return home
Roarm.Robot.home()

Custom Command Examples

# Slow precise movement
Roarm.Robot.send_custom_command(~s({"T": 122, "b": 45, "s": 30, "e": -15, "h": 0, "spd": 500}))

# Maximum speed movement
Roarm.Robot.send_custom_command(~s({"T": 121, "joint": 1, "angle": 90, "spd": 4096}))

# Enable force adaptation
Roarm.Robot.send_custom_command(~s({"T": 112, "mode": 1, "b": 60, "s": 110, "e": 50, "h": 50}))

# Create and play a mission
Roarm.Robot.send_custom_command(~s({"T": 220, "name": "test", "intro": "Test sequence"}))
Roarm.Robot.send_custom_command(~s({"T": 223, "mission": "test", "spd": 0.5}))
Roarm.Robot.send_custom_command(~s({"T": 242, "name": "test", "times": 3}))

Interactive Demo

Run the interactive demo to test your robot setup:

# Start the interactive demo
Roarm.Demo.interactive_demo()

# Or run specific tests
Roarm.Demo.test_connection("/dev/ttyUSB0")
Roarm.Demo.full_test_suite("/dev/ttyUSB0")

Documentation

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/roarm.