Tuning Guide

RIG-Hover is a self-balancing robot. Tune carefully and change only one thing at a time.

Bring-Up Order

Mechanical inspection

Battery voltage check

Motor direction check

Encoder feedback direction check

IMU orientation check

Head center check

Fall protection check

Hand-held balance

Free-standing balance

Move, rotate, and head commands

Do not skip straight to free-standing balance. First prove that sensors, motor directions, and protection logic are correct.

Safety Logic

The firmware contains protection logic in update_state():

abs(pitch) >= 60 deg or abs(roll) >= 40 deg for 500 ms -> robot_state = 0

abs(pitch) < 7 deg and abs(roll) < 7 deg for 1500 ms -> robot_state = 1

abs(wheel velocity) > 350 for repeated cycles -> robot_state = 0

When robot_state == 0, wheel torque output must be zero.

Default Parameters

Current defaults from InitializeController():

pid_pos.fpKp = 60.0;

pid_vel.fpKp = 0.15;

pid_vel.fpKi = 0.01;

pid_pit.fpKp = 21.0;



kd_pit = 2.3;

imu_zero = -5.0;



lqr_k[0] = 1400.0f;

lqr_k[1] = 6.8f;

lqr_k[2] = 32.0f;

lqr_k[3] = 1.6f;

The current main path uses LQR-style full-state feedback. Legacy PID variables are still present and some are exposed in the Web page, but active balance behavior is mainly determined by imu_zeroand lqr_k.

LQR State

pitch_ref = imu_zero * cosf(q_head * PI / 180.0f);

lqr_x  = wheel_x - stable_pos;

lqr_vx = wheek_vx - vx;

lqr_q  = pitch - pitch_ref;

lqr_dq = dq;



temp_u = -(lqr_k[0] * lqr_x

        + lqr_k[1] * lqr_vx

        + lqr_k[2] * lqr_q

        + lqr_k[3] * lqr_dq);

Yaw is added as differential torque:

yaw_u = k_yaw * (yaw - q_head - stable_yaw);

tor1 = -temp_u + yaw_u;

tor2 =  temp_u + yaw_u;

Recommended Tuning Order

Order	Parameter	Meaning	Suggested step
1	`imu_zero`	Balance reference angle	0.5 deg
2	`LQR_k2`	Pitch error recovery	1 to 3
3	`LQR_k3`	Pitch angular velocity damping	0.1 to 0.3
4	`LQR_k1`	Velocity feedback	0.5 to 1
5	`LQR_k0`	Position feedback	50 to 100
6	`k_yaw`	Heading hold	Small changes

Do not increase LQR_k0early. Strong position feedback can create forward/backward surging.

Web Debug Page

After Wi-Fi connection, open:

http://<RIG-Hover-IP>/

Endpoints:

GET /api/data

GET /api/set?i=<index>&v=<value>

Current mapping:

index	Label	Actual variable
0	`head`	`target_head_pos = value`
1	`delta_pos`	`stable_pos += value`
2	`POS_kp`	`pid_pos.fpKp = value`
3	`POS_kd`	`pid_pos.fpKd = value`
4	`VEL_kp`	`pid_vel.fpKp = value`
5	`VEL_ki`	`pid_vel.fpKi = value`
6	`PIT_kp`	`pid_pit.fpKp = value`
7	`PIT_kd`	`kd_pit = value`
8	`YAW_kp`	actually `imu_zero = value`
9	`delta_yaw`	`stable_yaw += value`
10	`LQR_k0`	`lqr_k[0] = value`
11	`LQR_k1`	`lqr_k[1] = value`
12	`LQR_k2`	`lqr_k[2] = value`
13	`LQR_k3`	`lqr_k[3] = value`

Known cleanup item: the Web label YAW_kpat index 8 actually sets imu_zero. Future firmware should rename the label or expose a real k_yawparameter.

Symptoms

Symptom	Possible cause	Check
Falls immediately after release	Wrong zero, low battery, motor direction error	`imu_zero`, battery, motor wiring
High-frequency shaking	Pitch gain too high or damping too low	Lower `LQR_k2`or raise `LQR_k3`
Slowly drives forward/backward	Zero offset or wheel feedback bias	Tune `imu_zero`, check encoder direction
Spins in place	Wheel mismatch, yaw bias, cable mapping issue	Motor mapping, wheel friction, `stable_yaw`
Screen works but no balance	IMU task or motor task abnormal	Serial logs and `/api/data`

Acceptance Tests

Hand-held startup enters balance without violent oscillation.

Free-standing balance is stable.

A light tap is followed by quick recovery.

Move forward/backward commands do not create severe impact.

Rotate left/right directions are correct.

Head left/right/center directions are correct.

Wi-Fi setup and reboot do not create uncontrolled behavior when the robot is held.

08-Tuning-Guide