guadaloop_lev_control/PID_TUNING_GUIDE.md

PID Tuning & Reference Control System - Implementation Guide

Overview

This system allows real-time tuning of all 6 PID control modes and reference setpoints through a GUI interface. Changes are transmitted via serial communication and applied immediately to the controller.

Control Modes

The system supports 6 distinct PID control modes:

1. Repelling (Mode 0) - Average height control when pushing away
2. Attracting (Mode 1) - Average height control when pulling in
3. RollLeftDown (Mode 2) - Left-right balance when left side needs to go down
4. RollLeftUp (Mode 3) - Left-right balance when left side needs to go up
5. RollFrontDown (Mode 4) - Front-back balance when front needs to go down
6. RollFrontUp (Mode 5) - Front-back balance when front needs to go up

Reference Values

The system also supports updating three reference setpoints:

1. Average Height Reference (avgRef) - Target height for levitation (mm)
2. Left-Right Difference Reference (LRDiffRef) - Target balance between left and right sensors (mm)
   • Positive value: left side should be higher than right
   • Negative value: right side should be higher than left
3. Front-Back Difference Reference (FBDiffRef) - Target balance between front and back sensors (mm)
   • Positive value: front should be higher than back
   • Negative value: back should be higher than front

Serial Protocol

PID Command Format

PID,<mode>,<kp>,<ki>,<kd>\n

Reference Command Format

REF,<avgRef>,<lrDiffRef>,<fbDiffRef>\n

Parameters

PID Command:

• mode: Integer 0-5 (see control modes above)
• kp: Float - Proportional gain
• ki: Float - Integral gain
• kd: Float - Derivative gain

Reference Command:

• avgRef: Float - Average height target in mm
• lrDiffRef: Float - Left-right balance difference in mm
• fbDiffRef: Float - Front-back balance difference in mm

Examples

PID,0,250,0,1000\n         # Set Repelling: Kp=250, Ki=0, Kd=1000
REF,11.0,-2.0,0.0\n        # Set avgRef=11mm, LRDiff=-2mm, FBDiff=0mm
PID,3,0,0,100\n            # Set RollLeftUp: Kp=0, Ki=0, Kd=100
REF,12.5,0.0,0.5\n         # Set avgRef=12.5mm, LRDiff=0mm, FBDiff=0.5mm

Implementation Details

Arduino Side (AdditiveControlCode.ino)

Default Values

Constants repelling = {250, 0, 1000};
Constants attracting = {250, 0, 1000};
Constants RollLeftUp = {0, 0, 100};
Constants RollLeftDown = {0, 0, 100};
Constants RollFrontUp = {0, 0, 500};
Constants RollFrontDown = {0, 0, 500};

Serial Command Processing

The main loop now parses incoming serial commands:

• Commands starting with "PID," are parsed for PID tuning
• Single character commands ('0' or '1') control the system on/off state
• Upon receiving a PID command, the corresponding Constants struct is updated
• The controller's internal PID values are updated via setter methods

Controller (Controller.hpp/cpp)

New Methods

// PID update methods
void updateAvgPID(Constants repel, Constants attract);
void updateLRPID(Constants down, Constants up);
void updateFBPID(Constants down, Constants up);

// Reference update method
void updateReferences(float avgReference, float lrDiffReference, float fbDiffReference);

These methods update the controller's internal values:

• PID Constants:
  • avgConsts - Controls average height (repelling/attracting)
  • LConsts - Controls left-right balance (RollLeftDown/RollLeftUp)
  • FConsts - Controls front-back balance (RollFrontDown/RollFrontUp)
• Reference Values:
  • AvgRef - Target average height
  • LRDiffRef - Target left-right balance difference
  • FBDiffRef - Target front-back balance difference

Python GUI (serial_plotter.py)

Features

• Individual PID Entry: Each control mode has dedicated Kp, Ki, Kd input fields
• Reference Value Controls: Set avgRef, LRDiffRef, FBDiffRef targets
• Send Button: Each mode has its own "Send" button for individual updates
• Send All: A "Send All PID Values" button transmits all 6 modes at once
• Send References: Update all reference values with one click
• Default Values: GUI is pre-populated with the default values from the Arduino code
• Scrollable Interface: All PID controls are in a scrollable panel for easy access

Control Flow - PID Updates

1. User enters PID values in the GUI
2. Clicks "Send" for individual mode or "Send All" for batch update
3. Python formats the command: PID,<mode>,<kp>,<ki>,<kd>\n
4. Command is sent via serial to Arduino
5. Arduino parses the command and updates the controller
6. Changes take effect immediately in the control loop

Control Flow - Reference Updates

1. User enters reference values in the GUI (Avg Height, LR Diff, FB Diff)
2. Clicks "Send References"
3. Python formats the command: REF,<avgRef>,<lrDiffRef>,<fbDiffRef>\n
4. Command is sent via serial to Arduino
5. Arduino updates the reference variables and controller
6. New setpoints take effect immediately

Usage Instructions

Starting the GUI

python serial_plotter.py --port /dev/cu.usbmodemXXXX

Or for testing without hardware:

python serial_plotter.py --mock

Tuning Workflow

1. Start the application - GUI launches with current PID values
2. Connect to Arduino - Serial connection established automatically
3. Adjust values - Modify Kp, Ki, Kd for desired control mode
4. Send to Arduino - Click "Send" for that mode or "Send All"
5. Observe behavior - Watch real-time plots to see the effect
6. Iterate - Adjust and resend as needed

Tips for Tuning

• Start with one mode at a time
• Use "Send All" to load a complete tuning set
• Watch the real-time plots to observe the effect of changes
• The system updates immediately - no restart required

Data Flow Summary

PID Updates:

GUI Input → Serial Command → Arduino Parse → Constants Update → 
Controller Setter → Internal PID Update → Control Loop → PWM Output

Reference Updates:

GUI Input → Serial Command → Arduino Parse → Reference Variables Update → 
Controller Setter → Internal Reference Update → Control Loop → PWM Output

Compatibility Notes

• The GUI requires tkinter (included with most Python installations)
• Serial communication uses standard pyserial library
• Arduino code uses String parsing (ensure sufficient memory)
• Commands are processed in the main loop between control cycles

Troubleshooting

GUI doesn't send commands

• Check serial connection
• Verify port selection
• Look for error messages in console

Arduino doesn't respond

• Ensure Arduino code is uploaded
• Check Serial Monitor for confirmation messages
• Verify baud rate (115200)

Values don't take effect

• Confirm command format is correct
• Check that mode number (0-5) is valid
• Ensure values are within reasonable ranges

Future Enhancements

Possible additions:

• Save/load PID profiles to/from file
• Preset tuning configurations
• Auto-tuning algorithms
• Real-time response visualization
• Logging of PID changes with timestamps