Documentation

These pages describe UPAN Gen 4: how to connect and power the hardware, how to set limits and write motion programs, and how to control the device from a PC, a browser, your own code or an AI agent. UPAN Core drives two stepper axes; an UPAN Axis module beside it on the DIN rail adds two more.

Note: The documentation follows board revision A and firmware that is still in development. Pages marked draft may change. Where something is not decided yet, the page says so.

How the pieces fit

 AI agent ──MCP──▶ upan-mcp ─┐
                             ├── USB-C ───────────────────────────┐
 PC: upan-cli, Python ───────┘                                    ▼
                                                        ┌──────────────────┐
 Phone / browser ──Wi-Fi──▶ network module ── UART ───▶ │   motion MCU     │──▶ driver ──▶ motor
   (apps on the device,     (local REST/WebSocket,      │ checks limits,   │
    upan.js)                 login, apps)               │ executes motion  │◀── limit switches,
                                                        └──────────────────┘    stop, I/O
                                                                 │
                                                           module bus ──▶ UPAN Axis modules

• The motion MCU is the only part that moves the motor. It checks every command and every program against the limits stored on the device, then executes it deterministically.
• The network module serves the local API and apps over Wi-Fi. It translates requests and checks login, but it does not decide about motion.
• Hosts — upan-cli and the Python library over USB, apps in the browser through upan.js, AI agents through upan-mcp — are all untrusted. The worst a wrong request can cause is a refusal with the reason and the allowed value.
• Machine limits can be changed only over USB with a button press on the device. The stop input is a hardware circuit, not a safety-rated emergency stop.
• Everything runs locally. No cloud account is needed.

Get started

• Quickstart — first connection and first move.

Hardware

• Wiring — motor, limit switches, inputs, outputs, stop input.
• Power — supply voltage and compatible power supplies.
• Safety — the stop input, the machine emergency stop and safe operation.
• Drawings — dimensions and mounting.

Motion

• Configuration and limits — HardConfig and SoftConfig, units, homing, limit switches.
• Programs — JSON motion programs and how the device checks them.

Interfaces

• upan-mcp — connect an AI agent through MCP.
• upan.js — browser library for apps on the device.
• Network API — local REST and WebSocket API (draft).
• Web apps on the device — single-file control panels served by UPAN.
• USB protocol — framing, messages, events and the simulator.
• API reference — every message, field and error code, generated from the protocol schema.

Help

• Troubleshooting — common problems and error codes.