Beam Bots Pigpio servo control

BB.Servo.Pigpio

BB integration for driving RC servos via pigpio on Raspberry Pi.

This library provides an actuator module for controlling RC servos directly connected to Raspberry Pi GPIO pins using the pigpio daemon.

Installation

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

def deps do
  [
    {:bb_servo_pigpio, "~> 0.4.0"}
  ]
end

Requirements

• Raspberry Pi with pigpio daemon running (sudo pigpiod)
• BB framework (~> 0.2)

Usage

Define a joint with a servo actuator in your robot DSL:

defmodule MyRobot do
  use BB

  topology do
    link :base do
      joint :shoulder, type: :revolute do
        limit lower: ~u(-45 degree), upper: ~u(45 degree), velocity: ~u(60 degree_per_second)

        actuator :servo, {BB.Servo.Pigpio.Actuator, pin: 17}
        sensor :feedback, {BB.Sensor.OpenLoopPositionEstimator, actuator: :servo}

        link :arm do
          # ...
        end
      end
    end
  end
end

The actuator automatically derives its configuration from the joint limits - no need to specify servo rotation range or speed separately.

Sending Commands

Use the BB.Actuator module to send commands to servos. Three delivery methods are available:

Pubsub Delivery (for orchestration)

Commands are published via pubsub, enabling logging, replay, and multi-subscriber patterns:

# Send position command via pubsub
BB.Actuator.set_position(MyRobot, [:base, :shoulder, :servo], 0.5)

# With options
BB.Actuator.set_position(MyRobot, [:base, :shoulder, :servo], 0.5,
  command_id: make_ref()
)

Direct Delivery (for time-critical control)

Commands bypass pubsub for lower latency. Use when responsiveness matters more than observability:

# Fire-and-forget
BB.Actuator.set_position!(MyRobot, :servo, 0.5)

Synchronous Delivery (with acknowledgement)

Wait for the actuator to acknowledge the command:

case BB.Actuator.set_position_sync(MyRobot, :servo, 0.5) do
  {:ok, :accepted} -> :ok
  {:error, reason} -> handle_error(reason)
end

Components

Actuator

BB.Servo.Pigpio.Actuator controls servo position via PWM.

Options:

Option	Type	Default	Description
pin	integer	required	GPIO pin number
min_pulse	integer	500	Minimum PWM pulse width (microseconds)
max_pulse	integer	2500	Maximum PWM pulse width (microseconds)
reverse?	boolean	false	Reverse rotation direction
update_speed	unit	50 Hz	PWM update frequency

Behaviour:

• Maps joint position limits directly to PWM range
• Clamps commanded positions to joint limits
• Publishes BB.Message.Actuator.BeginMotion after each command
• Calculates expected arrival time based on joint velocity limit

Sensor

Use BB.Sensor.OpenLoopPositionEstimator from the BB core library for position feedback. It subscribes to actuator BeginMotion messages and interpolates position during movement.

sensor :feedback, {BB.Sensor.OpenLoopPositionEstimator, actuator: :servo}

How It Works

Position Mapping

The actuator maps the joint's position limits to the servo's PWM range:

Joint lower limit  ->  min_pulse (500 microseconds)
Joint upper limit  ->  max_pulse (2500 microseconds)
Joint centre       ->  mid_pulse (1500 microseconds)

For a joint with limits -45 degrees to +45 degrees:

• -45 degrees maps to 500 microseconds
• 0 degrees maps to 1500 microseconds
• +45 degrees maps to 2500 microseconds

Position Feedback

Since RC servos don't provide position feedback, the open-loop position estimator estimates position based on commanded targets and expected arrival times:

1. Actuator sends command and publishes BeginMotion with expected arrival time
2. Sensor receives BeginMotion and interpolates position during movement
3. After arrival time, sensor reports the target position

This provides realistic position feedback for trajectory planning and monitoring.

Motion Lifecycle

When a position command is processed:

1. Actuator clamps position to joint limits
2. Converts angle to PWM pulse width
3. Sends PWM command to pigpiod
4. Publishes BB.Message.Actuator.BeginMotion with:
   • initial_position - where the servo was
   • target_position - where it's going
   • expected_arrival - when it should arrive (monotonic milliseconds)
   • command_id - correlation ID (if provided)
   • command_type - :position

Documentation

Full documentation is available at HexDocs.