Tool Reference

Available Tools

Tool	Description
positioner_status	Get current position and state
positioner_move	Move to absolute theta/phi position
positioner_home	Run sensorless homing
positioner_stop	Emergency stop all motors
positioner_config	Get/set motion parameters

positioner_status

Returns the current state of the positioner.

Response fields:

• theta_deg: Current polar angle (0-180°)
• phi_deg: Current azimuth angle (0-360°)
• moving: True if motors are currently moving
• homed: True if homing has been completed

Example:

{
  "theta_deg": 45.0,
  "phi_deg": 90.0,
  "moving": false,
  "homed": true
}

positioner_move

Move to an absolute theta/phi position.

Parameters:

Parameter	Type	Default	Description
theta_deg	float	required	Target polar angle (0-180°)
phi_deg	float	required	Target azimuth angle (0-360°)
wait	bool	true	Wait for move to complete
poll_interval_ms	int	100	Status polling interval

Example:

positioner_move(theta_deg=90, phi_deg=45, wait=true)

Caution

Always home the positioner before making moves. Without homing, the position reference is unknown.

positioner_home

Run sensorless StallGuard homing on one or both axes.

Parameters:

Parameter	Type	Default	Description
axis	string	"both"	Which axis: "theta", "phi", or "both"

How it works:

1. Motors move slowly in the negative direction
2. TMC2209 detects stall when motor hits mechanical stop
3. Position counter is zeroed
4. Motor backs off slightly from the stop

Example:

positioner_home(axis="both")

positioner_stop

Emergency stop all motors immediately.

Parameters: None

Example:

positioner_stop()

Tip

Use this if the antenna is about to collide with something or cables are getting tangled.

positioner_config

Get or set motion parameters.

Parameters (all optional):

Parameter	Type	Range	Description
speed	float	100-5000	Max speed (steps/sec)
accel	float	100-3000	Acceleration (steps/sec²)
microstepping	int	1-256	Microstep divisor

Get current config:

positioner_config()

Set parameters:

positioner_config(speed=2000, accel=1000, microstepping=16)

Tuning guide:

Use Case	Speed	Accel	Notes
Fast survey	3000	2000	More vibration, use longer settle time
Precision	1000	500	Smoother, less overshoot
Heavy antenna	500	300	Prevents missed steps

Example Workflow

Basic Movement

# Home first
positioner_home(axis="both")

# Move to measurement position
positioner_move(theta_deg=90, phi_deg=0, wait=true)

# Check position
positioner_status()

Grid Measurement

# Home and configure
positioner_home(axis="both")
positioner_config(speed=1500, accel=800)

# Measure at multiple points
for theta in [0, 30, 60, 90, 120, 150, 180]:
    for phi in [0, 45, 90, 135, 180, 225, 270, 315]:
        positioner_move(theta_deg=theta, phi_deg=phi, wait=true)
        # ... run VNA measurement here ...