rename to levSim, requirements, readme
This commit is contained in:
112
ReadMe.md
112
ReadMe.md
@@ -1,6 +1,112 @@
|
||||
# Levitation Control Repository
|
||||
This Repo contains the code and data from sensor calibration as well as arduino code for 4-point control on the 2-yoke test rig in the ```PIDTesting-2yoke4coil``` directory.
|
||||
|
||||
This code is property of Texas Guadaloop, a student-led hyperloop team from the University of Texas at Austin.
|
||||
This repository contains embedded firmware, sensor characterization tooling, and a physics-based simulation stack as well as control algorithm trials for the Texas Guadaloop maglev system.
|
||||
|
||||
To be able to run all python files in the repo, run ```pip install -r requirements.txt```
|
||||
This code is property of **Texas Guadaloop**, a student-led hyperloop team from the University of Texas at Austin.
|
||||
|
||||
---
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
.
|
||||
├── AltSensorTesting/ # Arduino firmware for Baumer inductive sensor characterization
|
||||
├── sensor/ # Python scripts to collect and fit sensor calibration data
|
||||
├── loadCellCode/ # Arduino firmware for HX711 load-cell calibration
|
||||
├── TwoCellMagChar/ # Two-cell magnetic characterization rig (validates Ansys data)
|
||||
├── lev_sim/ # PyBullet simulation driven by Ansys sweep data
|
||||
├── MAGLEV_DIGITALTWIN_PYTHON/ # Earlier single-axis analytical digital twin (reference)
|
||||
├── serial_plotter.py # Live serial plotter utility
|
||||
├── equilibrium.py # Equilibrium gap/current solver
|
||||
└── requirements.txt # Python dependencies
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Embedded Stack
|
||||
|
||||
### `AltSensorTesting/`
|
||||
|
||||
Arduino firmware for reading Baumer inductive analog distance sensors. Uses interrupt-driven ADC sampling at ~77 kHz (16 MHz / prescaler 16) for low-latency gap measurement. Tracks the 10 lowest and 10 highest in-range ADC values over a sampling window to help establish calibration bounds. An out-of-range (OOR) digital pin is monitored in the ISR to discard invalid readings.
|
||||
|
||||
Key details:
|
||||
- ADC ISR at ~77 kHz; readings discarded automatically when OOR pin is HIGH
|
||||
- Serial commands: `1` to start sampling, `0` to stop and print boundary statistics
|
||||
- Baud rate: 2,000,000
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Sensor Characterization
|
||||
|
||||
### `sensor/`
|
||||
|
||||
Python pipeline for converting raw ADC readings from the inductive gap sensors into calibrated millimeter distances.
|
||||
|
||||
- **`sensorCollector.py`** — Serial interface that reads live ADC values from Arduino and applies the calibration model in real time.
|
||||
- **`analogFitter-*.py`** — Curve-fitting scripts (polynomial, exponential, 3/4/5-parameter logistic) that fit calibration sweep data (`data*.csv`) to find the best sensor model. The 5-parameter generalized logistic form was found to give the best fit.
|
||||
- **`Sensor*Averages.csv` / `data*.csv`** — Raw and averaged calibration data for sensors 0–3. Sensor 3 required a different voltage divider (20 kΩ / 50 kΩ) because the induction sensor output exceeds 6 V.
|
||||
|
||||
Calibration constants (A, K, B, C, v) for the generalized logistic model are embedded directly in `sensorCollector.py` and `sensor_simplerNew.py` for deployment.
|
||||
|
||||
---
|
||||
|
||||
## Magnetic Characterization (`TwoCellMagChar/`)
|
||||
|
||||
A minimal bench rig used to validate Ansys Maxwell FEA force predictions experimentally.
|
||||
|
||||
- **`TwoCellMagChar.ino`** — Drives two H-bridge coil channels across a sweep of PWM values (−250 to +250 in steps of 50) while reading two HX711 load cells simultaneously. Averages 10 measurements per PWM step and reports gram-force readings over serial.
|
||||
- **`MagCharTrial.xlsx`** — Recorded force-vs-PWM data from physical trials.
|
||||
- **`CalibConsts.hpp`** — Load-cell offset and scale constants shared with `loadCellCode/`.
|
||||
|
||||
The measured force curves confirmed that the Ansys sweep data is in reasonable agreement with physical hardware, providing confidence for using the FEA model inside the simulation.
|
||||
|
||||
---
|
||||
|
||||
## Levitation Simulation (`lev_sim/`)
|
||||
|
||||
A PyBullet-based simulation environment for 4-point active magnetic levitation of the pod. The simulation is driven by an Ansys Maxwell parametric sweep (coil currents × gap height × roll angle → force & torque), fitted to a polynomial regression model for fast inference.
|
||||
|
||||
### Data pipeline
|
||||
|
||||
1. **Ansys sweep** — `Ansys Results 12-9.csv / .xlsx` contains FEA results sweeping left/right coil currents, roll angle, and gap height.
|
||||
2. **Function Fitting** — `Function Fitting.ipynb` fits the Ansys data to a `PolynomialFeatures + LinearRegression` model (inputs: `currL`, `currR`, `roll`, `1/gap`). The trained model is saved to `maglev_model.pkl`.
|
||||
3. **Fast inference** — `maglev_predictor.py` (`MaglevPredictor`) loads the pickle and bypasses sklearn overhead by extracting raw weight matrices, running pure-NumPy polynomial expansion for ~100× faster per-sample prediction.
|
||||
|
||||
### Simulation environment
|
||||
|
||||
`lev_pod_env.py` implements a [Gymnasium](https://gymnasium.farama.org/) `Env` wrapping PyBullet:
|
||||
|
||||
- **State**: 4 gap heights (normalized) + 4 gap-height velocities
|
||||
- **Action**: 4 PWM duty cycles ∈ [−1, 1] (front-left, front-right, back-left, back-right coils)
|
||||
- **Physics**: first-order RL circuit model per coil (`mag_lev_coil.py`); coil parameters: R = 1.1 Ω, L = 2.5 mH, V_supply = 12 V, I_max = 10.2 A
|
||||
- **Forces**: `MaglevPredictor.predict()` maps coil currents + gap + roll → force and torque applied to the pod body in PyBullet
|
||||
- **Noise**: configurable Gaussian sensor noise (default σ = 0.1 mm) and stochastic disturbance forces
|
||||
- Target equilibrium gap: 11.86 mm (9.4 kg pod)
|
||||
- Simulation timestep: 1/240 s
|
||||
|
||||
The environment is controller-agnostic — any control algorithm can be plugged in:
|
||||
|
||||
| File | Controller |
|
||||
|------|-----------|
|
||||
| `pid_simulation.py` | Feedforward LUT + PID |
|
||||
| `lev_PID.ipynb` | Interactive PID tuning notebook |
|
||||
| `optuna_pid_tune.py` | Optuna-based automated PID hyperparameter search |
|
||||
| `lev_PPO.ipynb` | PPO reinforcement learning via Stable-Baselines3 |
|
||||
|
||||
Pre-tuned PID gain sets are saved in `pid_best_params*.json` (variants for 1500, 3000, and 6000 Optuna trials).
|
||||
|
||||
### PWM circuit model
|
||||
|
||||
`PWM_Circuit_Model.py` is a standalone electrical model of the H-bridge PWM drive circuit used for offline verification of the coil current dynamics.
|
||||
|
||||
---
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
Key dependencies: `pybullet`, `gymnasium`, `stable-baselines3`, `scikit-learn`, `optuna`, `pyserial`, `numpy`, `scipy`, `pandas`, `matplotlib`.
|
||||
|
||||
Reference in New Issue
Block a user