# MAGCAL - Magnetometer calibration python tool for robotics, drones, satellites, and embedded systems
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/py/magcal)
```
███╗ ███╗ █████╗ ██████╗ ██████╗ █████╗ ██╗
████╗ ████║ ██╔══██╗ ██╔════╝ ██╔════╝ ██╔══██╗ ██║
██╔████╔██║ ███████║ ██║ ███╗ ██║ ███████║ ██║
██║╚██╔╝██║ ██╔══██║ ██║ ██║ ██║ ██╔══██║ ██║
██║ ╚═╝ ██║ ██║ ██║ ╚██████╔╝ ╚██████╗ ██║ ██║ ███████╗
╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝ ╚══════╝
```
**Magnetometer calibration CLI tool using ellipsoid correction for robotics, drones, satellites, and other critical embedded systems. Originally developed in python for Stanford SSI's satellite SAMWISE for attitude determination.**
## Why MAGCAL?
If you're working with magnetometers, you know the pain. Your compass readings are off by 30 degrees. Your drone's heading is all over the place. Your satellite's attitude determination is unreliable. Sound familiar?
The problem? **Magnetic interference**. Your magnetometer isn't just measuring Earth's magnetic field - it's also picking up interference from batteries, motors, metal frames, and anything else magnetic nearby.
MAGCAL fixes this. We use ellipsoid fitting (the gold standard for magnetometer calibration) to remove both hard iron and soft iron distortions. The result? Accurate, reliable magnetic field measurements you can actually trust.
## What can you use it for?
- **Satellites & Cubesats** - Get accurate attitude determination (like we did for Stanford SSI's SAMWISE)
- **Drones & UAVs** - Fix that wonky compass behavior once and for all
- **Marine navigation** - Reliable compass readings for boats and ships
- **Robotics** - Dead reckoning and navigation that actually works
- **Research** - Precise magnetometer data for scientific applications
- **IoT devices** - Any embedded system that needs to know which way is north
Works with pretty much any 3-axis magnetometer: RM3100, HMC5883L, MPU9250, LSM9DS1, QMC5883, MMC5983MA, BMM150, AK8963, you name it. If your microcontroller can output over serial, this tool is for you.
## How it works
1. **Connect your magnetometer** - Plug in via serial/USB (Arduino, Raspberry Pi, Pico, Feather, etc.)
2. **Run the calibration** - Just type `magcal` and follow the prompts
3. **Wave it around** - Rotate your device through all orientations while it collects data
4. **Get results** - MAGCAL spits out calibration parameters as a C header file
5. **Integrate** - Drop the calibration into your firmware and you're done
## Features
- **Real-time visualization** - Watch your data points form a sphere as you collect them
- **Professional algorithms** - Ellipsoid fitting that actually works (not some hack from Stack Overflow)
- **Easy integration** - Generates clean C header files for embedded projects
- **Quality metrics** - Know if your calibration is good or if you need more data
- **Works everywhere** - Any magnetometer with serial output, any platform
- **Beautiful CLI** - No config files to mess with, just an interactive menu that makes sense
## 🚀 Quick Start
### Installation
Install directly from PyPI:
```bash
pip install magcal
```
Or install from source:
```bash
git clone https://github.com/lundeen06/magnetometer-calibration-tool
cd magnetometer-calibration-tool
pip install -e .
```
### Basic Usage
Just type `magcal` to launch the interactive menu:
```bash
magcal
```
This will show you a beautiful menu with all available options - perfect for getting started quickly!
### Direct Commands
You can also use specific commands directly:
```bash
magcal calibrate # Run calibration with default settings
magcal interactive # Guided configuration mode
magcal monitor # Real-time data monitoring
```
## 📋 Commands
| Command | Description |
|---------|-------------|
| `magcal` | Show help and available commands |
| `magcal calibrate` | Run complete calibration workflow |
| `magcal interactive` | Interactive configuration mode |
| `magcal from-file <file>` | Calibrate from existing data file |
| `magcal monitor` | Real-time data monitoring |
## ⚙️ Command Options
### `magcal calibrate`
```bash
magcal calibrate [OPTIONS]
Options:
-p, --port TEXT Serial port path [default: /dev/tty.usbmodem101]
-b, --baudrate INTEGER Serial baudrate [default: 115200]
-n, --samples INTEGER Number of samples to collect [default: 1000]
-m, --method [sphere|ellipsoid] Calibration method [default: ellipsoid]
--pattern TEXT Custom regex pattern for data parsing
--no-plot Disable real-time plotting
```
## 🔧 Prerequisites
Before running calibration:
1. **Hardware Setup**
- Connect your magnetometer to the computer via serial
- Ensure the device is powered and sending data
2. **Firmware Preparation**
- Modify your embedded firmware to send **raw** magnetometer values
- Comment out any normalization in your magnetometer driver
- Flash the updated firmware
3. **Data Format**
- Default expected format: `Magnetometer reading: [x, y, z]`
- Values should be in µT (microTesla) units
- Use `--pattern` option for custom formats
## 🤔 Why Calibrate Your Magnetometer?
**Uncalibrated magnetometers suffer from:**
- **Hard iron distortion** - Permanent magnetic fields from nearby ferrous materials, motors, batteries
- **Soft iron distortion** - Induced magnetic fields in ferrous materials that vary with orientation
- **Scale factor errors** - Different sensitivities on X, Y, Z axes
- **Misalignment errors** - Sensor mounting angles affecting measurements
- **Temperature drift** - Magnetic properties changing with temperature
**Results without calibration:**
- ❌ Inaccurate compass heading (can be off by 30-180°)
- ❌ Poor attitude determination in satellites
- ❌ Unreliable navigation in drones/vehicles
- ❌ Failed magnetometer-based applications
**Results after calibration:**
- ✅ Sub-degree heading accuracy
- ✅ Reliable magnetic field measurements
- ✅ Professional-grade sensor performance
- ✅ Successful deployment in real applications
## 📊 Calibration Methods
### Ellipsoid Fitting (Recommended)
- Corrects both hard iron and soft iron effects
- Accounts for sensor mounting misalignment and scale factors
- Industry standard for aerospace and precision applications
- Generates 3x3 transformation matrix + offset vector
### Sphere Fitting
- Simple hard iron correction (offset only)
- Faster computation for basic applications
- Good when soft iron effects are minimal
## 📁 Output Files
Calibration generates files in the `output/` directory:
- **`mag_calibration_YYYYMMDD_HHMMSS.json`** - Raw collected data
- **`mag_calibration_YYYYMMDD_HHMMSS.h`** - C header file with calibration parameters
### Using Generated Files
Include the header file in your embedded project:
Example:
```c
#include "mag_calibration_20240101_120000.h"
// Apply calibration
float3 raw_reading = get_magnetometer_reading();
float3 corrected = raw_reading - MAG_HARD_IRON_OFFSET;
float3 calibrated = MAG_SOFT_IRON_MATRIX * corrected;
```
## 🎯 Quality Assessment
The tool provides quality metrics:
- **Sphericity**: Higher is better (max 1.0 for perfect sphere)
- **Quality Score**: Lower is better (< 0.05 is excellent)
| Score | Assessment |
|-------|------------|
| < 0.05 | 🟢 Excellent |
| < 0.10 | 🟡 Good |
| < 0.20 | 🟠 Fair |
| ≥ 0.20 | 🔴 Poor - collect more data |
## 🔧 Troubleshooting & FAQ
### Common Calibration Issues
**Q: My compass/magnetometer readings are still inaccurate after calibration**
- Ensure you collected data while rotating the sensor through ALL orientations (full 3D sphere)
- Check for strong magnetic interference sources nearby during calibration
- Verify your device outputs RAW magnetometer values (not normalized/filtered)
**Q: How to calibrate HMC5883L / MPU9250 / LSM9DS1 magnetometer?**
- Use MagCal with the appropriate data pattern for your sensor's output format
- Most sensors work with default settings, just specify your serial port
**Q: Calibration quality is poor (high error scores)**
- Collect more data points (try 2000+ samples instead of 1000)
- Ensure smooth, complete rotation through all orientations
- Remove or move away from magnetic interference sources
**Q: How to integrate calibration into Arduino/embedded firmware?**
- Use the generated `.h` header file - it contains the calibration matrix and offset
- Apply: `calibrated = (raw - offset) * transformation_matrix`
**Q: What's the difference between hard iron and soft iron calibration?**
- **Hard iron**: Fixed magnetic offsets (like from a nearby magnet)
- **Soft iron**: Variable magnetic distortion that changes with orientation
- Most applications need BOTH corrections (use ellipsoid method)
## 📝 License
MIT License - see [LICENSE](LICENSE) file for details.
---
**🧭 Happy calibrating! 🛰️**
Raw data
{
"_id": null,
"home_page": null,
"name": "magcal",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "magnetometer, calibration, compass, hard-iron, soft-iron, satellite, drone, embedded, magnetic-field, sensor-fusion, aerospace, cubesat, navigation, ellipsoid-fitting, bias-correction",
"author": null,
"author_email": "Lundeen Cahilly <lundeen.cahilly@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/aa/46/99a98ba1b132ea1cfeae3ef837ad9cb5015e9e333714f73ec4cabe935086/magcal-1.0.1.tar.gz",
"platform": null,
"description": "# MAGCAL - Magnetometer calibration python tool for robotics, drones, satellites, and embedded systems\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://badge.fury.io/py/magcal)\n\n```\n\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557 \n\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2551 \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557 \u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d \u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557 \u2588\u2588\u2551 \n\u2588\u2588\u2554\u2588\u2588\u2588\u2588\u2554\u2588\u2588\u2551 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551 \u2588\u2588\u2551 \u2588\u2588\u2588\u2557 \u2588\u2588\u2551 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551 \u2588\u2588\u2551 \n\u2588\u2588\u2551\u255a\u2588\u2588\u2554\u255d\u2588\u2588\u2551 \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2551 \u2588\u2588\u2551 \u2588\u2588\u2551 \u2588\u2588\u2551 \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2551 \u2588\u2588\u2551 \n\u2588\u2588\u2551 \u255a\u2550\u255d \u2588\u2588\u2551 \u2588\u2588\u2551 \u2588\u2588\u2551 \u255a\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255d \u255a\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2551 \u2588\u2588\u2551 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\n\u255a\u2550\u255d \u255a\u2550\u255d \u255a\u2550\u255d \u255a\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2550\u255d \u255a\u2550\u255d \u255a\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\n```\n\n**Magnetometer calibration CLI tool using ellipsoid correction for robotics, drones, satellites, and other critical embedded systems. Originally developed in python for Stanford SSI's satellite SAMWISE for attitude determination.**\n\n## Why MAGCAL?\n\nIf you're working with magnetometers, you know the pain. Your compass readings are off by 30 degrees. Your drone's heading is all over the place. Your satellite's attitude determination is unreliable. Sound familiar?\n\nThe problem? **Magnetic interference**. Your magnetometer isn't just measuring Earth's magnetic field - it's also picking up interference from batteries, motors, metal frames, and anything else magnetic nearby.\n\nMAGCAL fixes this. We use ellipsoid fitting (the gold standard for magnetometer calibration) to remove both hard iron and soft iron distortions. The result? Accurate, reliable magnetic field measurements you can actually trust.\n\n## What can you use it for?\n\n- **Satellites & Cubesats** - Get accurate attitude determination (like we did for Stanford SSI's SAMWISE)\n- **Drones & UAVs** - Fix that wonky compass behavior once and for all\n- **Marine navigation** - Reliable compass readings for boats and ships\n- **Robotics** - Dead reckoning and navigation that actually works\n- **Research** - Precise magnetometer data for scientific applications\n- **IoT devices** - Any embedded system that needs to know which way is north\n\nWorks with pretty much any 3-axis magnetometer: RM3100, HMC5883L, MPU9250, LSM9DS1, QMC5883, MMC5983MA, BMM150, AK8963, you name it. If your microcontroller can output over serial, this tool is for you. \n\n## How it works\n\n1. **Connect your magnetometer** - Plug in via serial/USB (Arduino, Raspberry Pi, Pico, Feather, etc.)\n2. **Run the calibration** - Just type `magcal` and follow the prompts\n3. **Wave it around** - Rotate your device through all orientations while it collects data\n4. **Get results** - MAGCAL spits out calibration parameters as a C header file\n5. **Integrate** - Drop the calibration into your firmware and you're done\n\n## Features\n\n- **Real-time visualization** - Watch your data points form a sphere as you collect them\n- **Professional algorithms** - Ellipsoid fitting that actually works (not some hack from Stack Overflow)\n- **Easy integration** - Generates clean C header files for embedded projects \n- **Quality metrics** - Know if your calibration is good or if you need more data\n- **Works everywhere** - Any magnetometer with serial output, any platform\n- **Beautiful CLI** - No config files to mess with, just an interactive menu that makes sense\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\nInstall directly from PyPI:\n\n```bash\npip install magcal\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/lundeen06/magnetometer-calibration-tool\ncd magnetometer-calibration-tool\npip install -e .\n```\n\n### Basic Usage\n\nJust type `magcal` to launch the interactive menu:\n\n```bash\nmagcal\n```\n\nThis will show you a beautiful menu with all available options - perfect for getting started quickly!\n\n### Direct Commands\n\nYou can also use specific commands directly:\n\n```bash\nmagcal calibrate # Run calibration with default settings\nmagcal interactive # Guided configuration mode\nmagcal monitor # Real-time data monitoring\n```\n\n## \ud83d\udccb Commands\n\n| Command | Description |\n|---------|-------------|\n| `magcal` | Show help and available commands |\n| `magcal calibrate` | Run complete calibration workflow |\n| `magcal interactive` | Interactive configuration mode |\n| `magcal from-file <file>` | Calibrate from existing data file |\n| `magcal monitor` | Real-time data monitoring |\n\n## \u2699\ufe0f Command Options\n\n### `magcal calibrate`\n\n```bash\nmagcal calibrate [OPTIONS]\n\nOptions:\n -p, --port TEXT Serial port path [default: /dev/tty.usbmodem101]\n -b, --baudrate INTEGER Serial baudrate [default: 115200]\n -n, --samples INTEGER Number of samples to collect [default: 1000]\n -m, --method [sphere|ellipsoid] Calibration method [default: ellipsoid]\n --pattern TEXT Custom regex pattern for data parsing\n --no-plot Disable real-time plotting\n```\n\n## \ud83d\udd27 Prerequisites\n\nBefore running calibration:\n\n1. **Hardware Setup**\n - Connect your magnetometer to the computer via serial\n - Ensure the device is powered and sending data\n\n2. **Firmware Preparation**\n - Modify your embedded firmware to send **raw** magnetometer values\n - Comment out any normalization in your magnetometer driver\n - Flash the updated firmware\n\n3. **Data Format**\n - Default expected format: `Magnetometer reading: [x, y, z]`\n - Values should be in \u00b5T (microTesla) units\n - Use `--pattern` option for custom formats\n\n## \ud83e\udd14 Why Calibrate Your Magnetometer?\n\n**Uncalibrated magnetometers suffer from:**\n- **Hard iron distortion** - Permanent magnetic fields from nearby ferrous materials, motors, batteries\n- **Soft iron distortion** - Induced magnetic fields in ferrous materials that vary with orientation \n- **Scale factor errors** - Different sensitivities on X, Y, Z axes\n- **Misalignment errors** - Sensor mounting angles affecting measurements\n- **Temperature drift** - Magnetic properties changing with temperature\n\n**Results without calibration:**\n- \u274c Inaccurate compass heading (can be off by 30-180\u00b0)\n- \u274c Poor attitude determination in satellites\n- \u274c Unreliable navigation in drones/vehicles \n- \u274c Failed magnetometer-based applications\n\n**Results after calibration:**\n- \u2705 Sub-degree heading accuracy\n- \u2705 Reliable magnetic field measurements\n- \u2705 Professional-grade sensor performance\n- \u2705 Successful deployment in real applications\n\n## \ud83d\udcca Calibration Methods\n\n### Ellipsoid Fitting (Recommended)\n- Corrects both hard iron and soft iron effects\n- Accounts for sensor mounting misalignment and scale factors\n- Industry standard for aerospace and precision applications\n- Generates 3x3 transformation matrix + offset vector\n\n### Sphere Fitting \n- Simple hard iron correction (offset only)\n- Faster computation for basic applications\n- Good when soft iron effects are minimal\n\n## \ud83d\udcc1 Output Files\n\nCalibration generates files in the `output/` directory:\n\n- **`mag_calibration_YYYYMMDD_HHMMSS.json`** - Raw collected data\n- **`mag_calibration_YYYYMMDD_HHMMSS.h`** - C header file with calibration parameters\n\n### Using Generated Files\n\nInclude the header file in your embedded project:\n\nExample: \n```c\n#include \"mag_calibration_20240101_120000.h\"\n\n// Apply calibration\nfloat3 raw_reading = get_magnetometer_reading();\nfloat3 corrected = raw_reading - MAG_HARD_IRON_OFFSET;\nfloat3 calibrated = MAG_SOFT_IRON_MATRIX * corrected;\n```\n\n## \ud83c\udfaf Quality Assessment\n\nThe tool provides quality metrics:\n\n- **Sphericity**: Higher is better (max 1.0 for perfect sphere)\n- **Quality Score**: Lower is better (< 0.05 is excellent)\n\n| Score | Assessment |\n|-------|------------|\n| < 0.05 | \ud83d\udfe2 Excellent |\n| < 0.10 | \ud83d\udfe1 Good |\n| < 0.20 | \ud83d\udfe0 Fair |\n| \u2265 0.20 | \ud83d\udd34 Poor - collect more data |\n\n## \ud83d\udd27 Troubleshooting & FAQ\n\n### Common Calibration Issues\n\n**Q: My compass/magnetometer readings are still inaccurate after calibration**\n- Ensure you collected data while rotating the sensor through ALL orientations (full 3D sphere)\n- Check for strong magnetic interference sources nearby during calibration\n- Verify your device outputs RAW magnetometer values (not normalized/filtered)\n\n**Q: How to calibrate HMC5883L / MPU9250 / LSM9DS1 magnetometer?** \n- Use MagCal with the appropriate data pattern for your sensor's output format\n- Most sensors work with default settings, just specify your serial port\n\n**Q: Calibration quality is poor (high error scores)**\n- Collect more data points (try 2000+ samples instead of 1000)\n- Ensure smooth, complete rotation through all orientations\n- Remove or move away from magnetic interference sources\n\n**Q: How to integrate calibration into Arduino/embedded firmware?**\n- Use the generated `.h` header file - it contains the calibration matrix and offset\n- Apply: `calibrated = (raw - offset) * transformation_matrix`\n\n**Q: What's the difference between hard iron and soft iron calibration?**\n- **Hard iron**: Fixed magnetic offsets (like from a nearby magnet)\n- **Soft iron**: Variable magnetic distortion that changes with orientation\n- Most applications need BOTH corrections (use ellipsoid method)\n\n## \ud83d\udcdd License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n**\ud83e\udded Happy calibrating! \ud83d\udef0\ufe0f**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Magnetometer calibration python CLI tool for robotics, drones, satellites, and embedded systems",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/lundeen06/magcal",
"Issues": "https://github.com/lundeen06/magcal/issues"
},
"split_keywords": [
"magnetometer",
" calibration",
" compass",
" hard-iron",
" soft-iron",
" satellite",
" drone",
" embedded",
" magnetic-field",
" sensor-fusion",
" aerospace",
" cubesat",
" navigation",
" ellipsoid-fitting",
" bias-correction"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5b5e692ac816f7d5addfd925d25b1c90986f142bc5d643947946cacc599420e1",
"md5": "2c842e5522954847d011d929b0a995a7",
"sha256": "ec803f16913e54da984c4f3f9359bebba41e8211c30a1ff105c3625ada3ec896"
},
"downloads": -1,
"filename": "magcal-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2c842e5522954847d011d929b0a995a7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22331,
"upload_time": "2025-08-23T04:56:06",
"upload_time_iso_8601": "2025-08-23T04:56:06.674502Z",
"url": "https://files.pythonhosted.org/packages/5b/5e/692ac816f7d5addfd925d25b1c90986f142bc5d643947946cacc599420e1/magcal-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "aa4699a98ba1b132ea1cfeae3ef837ad9cb5015e9e333714f73ec4cabe935086",
"md5": "4ab9b31a407d2eeaa994fc2ada03ae48",
"sha256": "9db40545e3464c43ad8fb85364f1fac827879d9a886d0602ee5cc1e9609edaf8"
},
"downloads": -1,
"filename": "magcal-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "4ab9b31a407d2eeaa994fc2ada03ae48",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24965,
"upload_time": "2025-08-23T04:56:08",
"upload_time_iso_8601": "2025-08-23T04:56:08.055688Z",
"url": "https://files.pythonhosted.org/packages/aa/46/99a98ba1b132ea1cfeae3ef837ad9cb5015e9e333714f73ec4cabe935086/magcal-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-23 04:56:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lundeen06",
"github_project": "magcal",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "magcal"
}
JSON
