OpenParable
Skip to content
← Back to skills

Developing With Orbs

Apps & Automation
developing-with-orbs

Developing With Orbs is an Agent Skill for apps & automation published in the worldcoin/orb-software repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when working against a physical Orb from this repo, especially for SSH or scp access, deploying crates with cargo x deploy, using the orb-hil CLI, or running orb-mcu-util workflows

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/worldcoin/orb-software/blob/HEAD/.agents/skills/developing-with-orbs/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/developing-with-orbs, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Developing With Orbs

Overview

Use this skill when the task needs a real Orb instead of local-only work. Favor direct SSH and scp for inspection and staging files, cargo x d for deploying workspace crates, orb-hil for hardware-in-loop workflows, and orb-mcu-util for MCU inspection and firmware operations on the device.

Quick Access

An Orb with ID 1234 is reachable over Avahi as:

ssh [email protected]

scp uses the same host naming:

scp ./local-file [email protected]:/tmp/local-file
scp [email protected]:/tmp/remote-file ./remote-file

If you already know the Orb IP, replace orb-1234.local with that IP.

Deploying Crates From This Repo

Use cargo x d as the short form of cargo x deploy from the workspace xtask crate:

export ORB_IP=orb-1234.local
export WORLDCOIN_PW='...'
cargo x d orb-mcu-util

Example:

cargo x d orb-mcu-util

Operational notes:

  • ORB_IP can be a raw IP address or an Avahi host such as orb-1234.local.
  • WORLDCOIN_PW should be set before deploys. The current xtask implementation will prompt interactively if either variable is unset, but for repeatable runs, set both env vars explicitly.
  • cargo x d <crate-name> builds the crate for aarch64-unknown-linux-gnu, creates a .deb, copies it to the Orb, and reinstalls it there.
  • If the crate declares systemd units in its package metadata, cargo x d automatically restarts the associated service on the Orb after install.

Prefer cargo x d when you are deploying a workspace crate. Prefer raw scp when you are just staging an artifact or test file.

Copying Files With scp

Push a file onto the Orb:

scp ./artifact.bin [email protected]:/tmp/artifact.bin

Copy a file back from the Orb:

scp [email protected]:/tmp/log.txt ./log.txt

Common pattern for MCU work:

scp ./target/aarch64-unknown-linux-gnu/release/main-mcu.bin \
  [email protected]:/tmp/main-mcu.bin
ssh [email protected] \
  'orb-mcu-util image update main --path /tmp/main-mcu.bin'

Using the HIL CLI

The repo ships a hardware-in-loop CLI as orb-hil.

Run it from source:

AWS_PROFILE=hil aws sso login
AWS_PROFILE=hil cargo run -p orb-hil -- --help

Peripheral requirements matter:

  • orb-hil flash needs an x86 Linux machine
  • orb-hil reboot needs a serial adapter
  • orb-hil login needs a serial adapter
  • orb-hil cmd can work with a serial adapter or network access such as SSH/Teleport

Do not recommend orb-hil reboot or orb-hil login as SSH-only replacements.

Important command families from hil/src/main.rs:

  • button-ctrl
  • cmd
  • fetch-persistent
  • flash
  • login
  • mcu
  • nfsboot
  • ota
  • ping
  • reboot
  • set-recovery-pin

Examples:

AWS_PROFILE=hil cargo run -p orb-hil -- flash --help
AWS_PROFILE=hil cargo run -p orb-hil -- reboot --help
AWS_PROFILE=hil cargo run -p orb-hil -- cmd --help
AWS_PROFILE=hil cargo run -p orb-hil -- mcu --help

Use orb-hil when you need hardware-in-loop flows such as flashing, reboot orchestration, login automation, or command execution through supported HIL transport paths.

Using orb-mcu-util

orb-mcu-util is the direct MCU utility in this repo. It supports both normal and CAN-FD operation; add --can-fd when the task specifically needs that bus.

Core inspection and reboot commands:

ssh [email protected] 'orb-mcu-util info'
ssh [email protected] 'orb-mcu-util info --diag'
ssh [email protected] 'orb-mcu-util reboot main'
ssh [email protected] 'orb-mcu-util reboot security'
ssh [email protected] 'orb-mcu-util reboot orb'
ssh [email protected] 'orb-mcu-util reboot --delay 30 orb'
ssh [email protected] 'orb-mcu-util reboot-behavior button'
ssh [email protected] 'orb-mcu-util reboot-behavior always-on'

Firmware image commands:

ssh [email protected] \
  'orb-mcu-util image update main --path /tmp/main-mcu.bin'
ssh [email protected] \
  'orb-mcu-util image update security --path /tmp/security-mcu.bin'
ssh [email protected] \
  'orb-mcu-util image update main --path /tmp/main-mcu.bin --force'
ssh [email protected] 'orb-mcu-util image switch main'
ssh [email protected] 'orb-mcu-util image switch security'
ssh [email protected] 'orb-mcu-util image force-switch main'

Dump and stress commands:

ssh [email protected] 'orb-mcu-util dump main --duration 30'
ssh [email protected] 'orb-mcu-util dump security --duration 30 --logs-only'
ssh [email protected] 'orb-mcu-util stress main --duration 30'
ssh [email protected] 'orb-mcu-util stress security --duration 30'

Hardware, power, and peripheral commands:

ssh [email protected] 'orb-mcu-util hardware-revision'
ssh [email protected] 'orb-mcu-util power-cycle secure-element'
ssh [email protected] 'orb-mcu-util power-cycle heat-camera'
ssh [email protected] 'orb-mcu-util power-cycle wifi'
ssh [email protected] 'orb-mcu-util ui front red'
ssh [email protected] 'orb-mcu-util ui front white'
ssh [email protected] 'orb-mcu-util optics gimbal-home autohome'
ssh [email protected] 'orb-mcu-util optics gimbal-position --phi 45000 --theta 90000'
ssh [email protected] 'orb-mcu-util optics gimbal-move --phi 100 --theta -100'
ssh [email protected] 'orb-mcu-util optics trigger-camera eye 30'
ssh [email protected] 'orb-mcu-util optics trigger-camera face 30'
ssh [email protected] 'orb-mcu-util optics polarizer home'
ssh [email protected] 'orb-mcu-util optics polarizer passthrough'
ssh [email protected] 'orb-mcu-util optics polarizer vertical'
ssh [email protected] 'orb-mcu-util optics polarizer horizontal'
ssh [email protected] 'orb-mcu-util optics polarizer angle 900'
ssh [email protected] \
  'orb-mcu-util optics polarizer stress 0 100 --random'
ssh [email protected] \
  'orb-mcu-util optics polarizer settings --acceleration 100 --max-speed 100'

Use these patterns:

  • info or info --diag to inspect current MCU state
  • reboot and reboot-behavior to control board or Orb restart behavior
  • image update after staging a firmware binary with scp
  • image switch or image force-switch to change active image slots
  • dump to collect MCU messages, optionally logs only
  • stress to exercise MCU communication
  • power-cycle for secure element, heat camera, or Wi-Fi power resets
  • ui and optics when the task involves front LEDs, gimbal, cameras, or the polarizer
  • optics polarizer stress <speed> <repeat> uses positional arguments; in the example above, 0 100 means speed 0 and 100 repetitions

For anything beyond the examples above, run:

ssh [email protected] 'orb-mcu-util --help'
ssh [email protected] 'orb-mcu-util image --help'
ssh [email protected] 'orb-mcu-util optics --help'
ssh [email protected] 'orb-mcu-util ui --help'

Source Of Truth

When the command surface matters, read these files directly:

  • xtask/src/main.rs
  • xtask/src/cmd/deploy.rs
  • docs/src/hil/cli.md
  • hil/src/main.rs
  • mcu-util/src/main.rs