Firmware

Prerequisites

PlatformIO (CLI or VS Code extension)
USB cable for ESP32

Build and Flash

Clone the repository

git clone https://git.supported.systems/rf/mcpositioner.git
cd mcpositioner/firmware

Build the firmware
Terminal window
```
pio run
```
Flash to ESP32
Terminal window
```
pio run -t upload
```
Monitor serial output (optional)
Terminal window
```
pio device monitor
```

Configuration

Edit include/config.h before building:

WiFi Settings

#define WIFI_SSID "your-network"
#define WIFI_PASSWORD "your-password"

Motor Parameters

// Steps per revolution (including microstepping)
#define THETA_STEPS_PER_REV 3200  // 200 * 16 microstepping
#define PHI_STEPS_PER_REV 3200

// Gear ratios (if using reduction gearing)
#define THETA_GEAR_RATIO 1.0
#define PHI_GEAR_RATIO 1.0

// Motor current (mA)
#define MOTOR_CURRENT_MA 800

TMC2209 Settings

// UART addresses
#define THETA_TMC_ADDR 0x00
#define PHI_TMC_ADDR 0x01

// StallGuard threshold (lower = more sensitive)
#define STALL_VALUE 50

// Homing speed (steps/sec)
#define HOMING_SPEED 500

Pin Assignments

// Theta axis
#define THETA_STEP_PIN 16
#define THETA_DIR_PIN 17
#define THETA_EN_PIN 4

// Phi axis
#define PHI_STEP_PIN 21
#define PHI_DIR_PIN 22
#define PHI_EN_PIN 23

// Shared UART
#define TMC_UART_TX 18
#define TMC_UART_RX 19

HTTP API

The firmware exposes these endpoints at http://positioner.local:

Endpoint	Method	Description
`/status`	GET	Current position and state
`/move`	POST	Absolute move: `{"theta_deg": 90, "phi_deg": 45}`
`/move/relative`	POST	Relative move: `{"d_theta": 5, "d_phi": 10}`
`/home`	POST	Homing: `{"axis": "both"}`
`/stop`	POST	Emergency stop
`/config`	GET/POST	Motion parameters

Dependencies

The firmware uses these PlatformIO libraries (auto-installed):

Library	Purpose
AccelStepper	Smooth acceleration profiles
TMCStepper	TMC2209 UART configuration
ESPAsyncWebServer	HTTP API
ArduinoJson	JSON parsing
ESPmDNS	Network discovery

Troubleshooting

Can’t connect to WiFi

Check SSID and password in config.h
Verify ESP32 is within range
Check serial monitor for connection status

mDNS not working

Some networks block mDNS
Use IP address directly (shown in serial monitor on boot)
Set MCPOSITIONER_HOST environment variable

Motors don’t respond

Check UART wiring (TX/RX may be swapped)
Verify TMC2209 addresses match config
Check motor power supply

StallGuard unreliable

Adjust STALL_VALUE (lower = more sensitive)
Increase motor current
Decrease homing speed
Ensure mechanical stops are solid

OTA Updates

The firmware supports over-the-air updates:

pio run -t upload --upload-port positioner.local