Complete Compass Calibration System: Automatic Magnetometer Calibration & Multi-Point Angular Correction

[X9X0]

Overview

This PR implements a comprehensive two-layer calibration system for the K3ng rotator controller, providing both magnetometer hard-iron offset compensation and multi-point angular correction tables with linear interpolation. The system supports automatic 360° rotation calibration, manual calibration workflows, and includes an intelligent wizard to guide users through the calibration process.

Key Features

1. Magnetometer Calibration (Hard-Iron Offset)

• Automatic calibration: Rotates antenna 360° (or max available range) to collect min/max values for X/Y/Z axes
• Manual calibration: User-controlled rotation with real-time sample collection
• Quality assessment: GOOD/POOR/SUSPECT ratings based on range, symmetry, and sensor-specific thresholds
• Sensor support: HMC5883L, QMC5883L (DFRobot/Mechasolution), LSM303 (Pololu/Adafruit)
• Safety: Respects limit switches, validates preconditions, supports partial calibration (≥180°)
• EEPROM persistence: Calibration survives power cycles (CONFIGURATION_STRUCT_VERSION → 124)

2. Multi-Point Calibration (FEATURE_CALIBRATION)

• Completed framework: Implemented missing interpolate_calibration_table() function
• Linear interpolation: Corrects systematic angular errors using calibration point pairs
• Table management: Add/remove/clear calibration points with validation
• Multiple sources: User-entered, sun position, moon position calibration points
• Protection: Default endpoint preservation, large correction warnings (>45°)
• Integration: Applied to all azimuth/elevation sensor reading paths

3. User Experience Improvements

• Calibration wizard (?CAL): Context-aware recommendations guide users step-by-step
• Progress feedback: Real-time percentage, degrees rotated, sample count during calibration
• Validation warnings: Range checks, large correction alerts, duplicate point detection
• Quick status check (?CQ): Fast quality assessment for automation/scripts
• Comprehensive help: Integrated into print_help() with all commands documented

4. Code Quality

• Helper functions: 5 reusable parsing/validation functions reduce duplication by ~60%
• Debug logging: DEBUG_CALIBRATION flag with extensive diagnostic output
• Error handling: 16 calibration-specific return codes for precise error reporting
• Maintainability: Clear function separation, comprehensive inline documentation

5. Protocol Compatibility ✅

• Zero impact on Yaesu GS-232 A/B and Easycomm I/II protocols
• All new features are backslash commands only (no unsolicited messages)
• Maintains existing response-only architecture
• Compile-time feature gating with conditional compilation

New Serial Commands

Magnetometer:

• \XMG - Automatic magnetometer calibration
• \XMGs - Start manual calibration
• \XMGe - End manual calibration

Multi-Point:

• \XAA[from],[to] - Add azimuth calibration point
• \XAE[from],[to] - Add elevation calibration point
• \XRA[index] - Remove azimuth point
• \XRE[index] - Remove elevation point
• \XCA / \XCE - Clear azimuth/elevation tables
• \X0 - Clear all tables
• \XS / \XM - Add point using sun/moon

Status:

• ?CAL - Comprehensive status + wizard
• ?CQ - Quick quality check
• \X - Display calibration tables (enhanced)

Files Modified

• k3ng_rotator_controller.ino (+1470 lines): Core implementation
• rotator.h (±30 lines): Version increment, state/error defines
• rotator_debug_log_activation.h (+1 line): DEBUG_CALIBRATION flag

Testing Recommendations

1. EEPROM Persistence: Verify calibration survives power cycle
2. Limit Switch Safety: Test automatic calibration with limit switches
3. Partial Calibration: Test with <360° rotation capability
4. Quality Assessment: Verify GOOD/POOR/SUSPECT ratings
5. Interpolation: Add multiple points and verify smooth corrections
6. Protocol Isolation: Confirm no interference with Yaesu/Easycomm clients

Benefits

• ✅ Improved heading accuracy (target: ±5° or better)
• ✅ User-friendly guided calibration workflow
• ✅ Production-ready with comprehensive error handling
• ✅ Fully backward compatible with existing configurations
• ✅ Maintains all protocol compatibility requirements

---

Statistics: 3 files changed, 1,470 insertions(+), 31 deletions(-)

[dh1tw]

awesome! very cool PR!

[k3ng]

This is impressive! Apologies for being radio silent. I will try to merge this PR soon. 73 de K3NG

…

On Mon, Jan 19, 2026 at 6:38 PM Tobias Wellnitz ***@***.***> wrote: *dh1tw* left a comment (k3ng/k3ng_rotator_controller#115) <#115 (comment)> awesome! very cool PR! — Reply to this email directly, view it on GitHub <#115 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAZNU4CO6RQJUIHUFOQ2X2L4HVTFXAVCNFSM6AAAAACQEKIP2SVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTONZQGQ2DOOJWGI> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[X9X0]

To be honest the PR was a mistake, I was trying to push it to my own fork but wasn't paying attention, LOL. I wanted to tune this a little more, but it should be pretty usable as is. Thanks for the kudos