Ryan Malloy
ce93070a04
README covers installation, hardware setup, tools, prompts, and cross-server integration with mcnanovna for 3D pattern measurement. CLAUDE.md provides project guidance for Claude Code.
95 lines
2.8 KiB
Markdown
95 lines
2.8 KiB
Markdown
# mcpositioner
|
|
|
|
MCP server for controlling an ESP32 dual-axis antenna positioner over WiFi.
|
|
|
|
Drives two NEMA 17 stepper motors via TMC2209 drivers for theta (polar, 0-180°) and phi (azimuth, 0-360°) rotation. Designed for automated antenna radiation pattern measurement in coordination with a VNA.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# From PyPI (when published)
|
|
uvx mcpositioner
|
|
|
|
# From source
|
|
uv run mcpositioner
|
|
```
|
|
|
|
## Hardware
|
|
|
|
- **ESP32** (any DevKit variant) running the firmware in `firmware/`
|
|
- **2x TMC2209** stepper drivers in UART mode
|
|
- **2x NEMA 17** stepper motors (0.9° or 1.8° step angle)
|
|
- **24V power supply** for motors (5V for ESP32)
|
|
|
|
See `hardware/` for KiCad schematics showing the wiring.
|
|
|
|
### Firmware
|
|
|
|
Build and flash with PlatformIO:
|
|
|
|
```bash
|
|
cd firmware
|
|
pio run -t upload
|
|
```
|
|
|
|
The ESP32 advertises itself as `positioner.local` via mDNS. Override with the `MCPOSITIONER_HOST` environment variable if needed.
|
|
|
|
## MCP Tools
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `positioner_status` | Get theta/phi position, moving state, homed state |
|
|
| `positioner_move` | Move to absolute theta/phi with optional wait |
|
|
| `positioner_home` | StallGuard sensorless homing on one or both axes |
|
|
| `positioner_stop` | Emergency stop all motors |
|
|
| `positioner_config` | Get/set speed, acceleration, microstepping |
|
|
|
|
## Prompts
|
|
|
|
| Prompt | Description |
|
|
|--------|-------------|
|
|
| `home_positioner` | Guided homing with safety checks |
|
|
| `configure_positioner` | Motion parameter tuning guide |
|
|
| `measure_pattern_grid` | Cross-server 3D pattern measurement workflow |
|
|
|
|
## Cross-Server Pattern Measurement
|
|
|
|
This server controls positioning only. For 3D antenna pattern measurement, use together with [mcnanovna](../mcnanovna/) (VNA MCP server):
|
|
|
|
1. `positioner_move` (mcpositioner) — position antenna at theta/phi
|
|
2. `scan` (mcnanovna) — measure S21 transmission
|
|
3. Repeat across theta/phi grid
|
|
4. Assemble pattern from collected measurements
|
|
|
|
The `measure_pattern_grid` prompt provides step-by-step guidance for this workflow.
|
|
|
|
### Adding Both Servers to Claude Code
|
|
|
|
```bash
|
|
claude mcp add mcpositioner -- uvx mcpositioner
|
|
claude mcp add mcnanovna -- uvx mcnanovna
|
|
```
|
|
|
|
## Configuration
|
|
|
|
| Environment Variable | Default | Description |
|
|
|---------------------|---------|-------------|
|
|
| `MCPOSITIONER_HOST` | `positioner.local` | ESP32 hostname or IP |
|
|
|
|
## HTTP API (ESP32 Firmware)
|
|
|
|
The ESP32 exposes these endpoints:
|
|
|
|
| Endpoint | Method | Description |
|
|
|----------|--------|-------------|
|
|
| `/status` | GET | Current position, moving, homed |
|
|
| `/move` | POST | `{"theta_deg": 90, "phi_deg": 45}` |
|
|
| `/move/relative` | POST | `{"d_theta": 5, "d_phi": 10}` |
|
|
| `/home` | POST | `{"axis": "both"}` (or "theta"/"phi") |
|
|
| `/stop` | POST | Emergency stop |
|
|
| `/config` | GET/POST | Motion parameters |
|
|
|
|
## License
|
|
|
|
MIT
|