# Documentation

> Documentation for UPAN Gen 4 — hardware, configuration, motion programs, the USB and network interfaces, and AI agent integration.

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

```text
 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](/docs/quickstart) — first connection and first move.

## Hardware

- [Wiring](/docs/wiring) — motor, limit switches, inputs, outputs, stop input.
- [Power](/docs/power) — supply voltage and compatible power supplies.
- [Safety](/docs/safety) — the stop input, the machine emergency stop and safe operation.
- [Drawings](/docs/drawings) — dimensions and mounting.

## Motion

- [Configuration and limits](/docs/configuration) — HardConfig and SoftConfig, units, homing, limit switches.
- [Programs](/docs/programs) — JSON motion programs and how the device checks them.

## Interfaces

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

## Help

- [Troubleshooting](/docs/troubleshooting) — common problems and error codes.