Box2Robot — Robotic Arm Control Skill

Control ESP32-based robotic arms through a cloud server API. Move servos, record trajectories, calibrate, capture images, voice interaction, and orchestrate AI training/inference — all from a single CLI.

Official skill published by the Box2Robot team (https://robot.box2ai.com).

Safety & Supervision

This skill controls physical robotic hardware and camera/microphone peripherals.

• Human supervision required: Do NOT run autonomously without operator oversight. Servo torque and motion commands cause physical movement that could injure people or damage objects.
• Destructive operations (device.factory_reset, device.wifi_clear, calibrate.center_offset) require explicit user confirmation before execution.
• Privacy-sensitive operations (camera.snapshot, camera.voice_start, camera.record_audio_start) access camera and microphone — only invoke with user consent.
• No OS shell access: The exec command routes named Actions through the HTTP API (e.g., exec servo.move). The shell command is an interactive REPL that dispatches CLI subcommands — neither executes arbitrary OS commands. All operations are HTTP requests to B2R_SERVER.
• Token sensitivity: ~/.b2r_token stores a JWT that grants device control. Treat it like an SSH key. Delete it when no longer needed.

Credential Flow

login → POST /api/auth/login → JWT token
  → saved to ~/.b2r_token (mode 0600, owner-only)
  → all subsequent commands use this token automatically
  → override with B2R_TOKEN env var
  → delete ~/.b2r_token to revoke

All network calls go exclusively to B2R_SERVER (default: https://robot.box2ai.com). No other endpoints are contacted.

Setup

# Install dependency
pip install aiohttp

# Login (one-time, token cached to ~/.b2r_token)
python b2r.py login \x3Cusername> \x3Cpassword>

# Or set environment variables
export B2R_SERVER="https://robot.box2ai.com"
export B2R_TOKEN="\x3Cjwt_token>"
export B2R_DEVICE="B2R-XXXXXXXXXXXX"

CLI Quick Reference

Device & Status

b2r.py devices                     # List devices (* = online)
b2r.py status                      # Servo positions, load, temperature

Servo Control

b2r.py torque on                   # Lock servos
b2r.py torque off                  # Release (allows manual dragging)
b2r.py home                        # Safe return to home position
b2r.py move \x3Cservo_id> \x3Cpos> [spd] # Move a single servo
# Position: 0-4095 (center 2048), Speed: 0-4000 (default 1000)

Recording & Playback

b2r.py record start                # Start recording
b2r.py record stop [name]          # Stop and save
b2r.py play                        # List all trajectories
b2r.py play \x3Ctraj_id>              # Play a trajectory

Camera & Data

b2r.py snapshot                    # Camera snapshot
b2r.py frame [cam_id] [output.jpg] # Download latest camera frame (JPEG)
b2r.py calibrate [servo_id]        # Auto-calibrate (0 = all)
b2r.py download \x3Ctraj_id> [dir]    # Download trajectory images (HTTP GET only)

Action System (79 Actions)

Invoke via b2r.py exec \x3Caction_name>. Parameters in JSON or key=value format.

device (Device Management)

servo (Servo Control)

recording (Recording & Playback)

pairing (Leader-Follower)

calibration

camera (Camera & Voice)

Privacy note: Snapshot and voice commands access camera/microphone hardware. Only invoke with user consent.

training (Training & Inference)

store (Skill Store)

config (Configuration)

Natural Language

Via b2r.py say "text":

Preflight Checks

Agents must verify before executing:

Orchestration Examples

"Teach you to pour water, record 5 demos"

1. torque off
2. camera.stream_mode(cam_id, "preview")
3. Loop 5x:
   record.start(mode="single", camera_id)
   [user demonstrates]
   record.stop(name="pour_water_{n}")
4. training.submit(name="pour_water", dataset_ids)

Visual Inference Loop

1. training.deploy(job_id, arm_id, gpu_id, cam_id)
2. GPU auto-loop: image → inference → command → arm
3. training.stop_inference(job_id)

HTTP API Direct Access

# Login
curl -X POST https://robot.box2ai.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"xxx","password":"xxx"}'

# Move servo
curl -X POST https://robot.box2ai.com/api/device/B2R-xxx/command \
  -H "Authorization: Bearer \x3Ctoken>" \
  -H "Content-Type: application/json" \
  -d '{"id":1,"position":2048,"speed":1000}'

Environment Variables