Article first published by Michael E Stanley in The Embedded Beat (Freescale blog) on 29 Apr. 2013
A few weeks ago, my coworkers and I had the pleasure of participating in an awards ceremony in which Electronic Products Magazine presented Freescale with a Product of the Year award for our Xtrinsic eCompass software. This software processes the outputs of two sensors (an accelerometer and a magnetometer) to implement a tilt-compensated electronic compass. The software is available in source code format supported by an easy-to-use click through license.
We were at revision 2.0 of that library when Electronic Products announced the award. Since then, revision 3.0 has been uploaded to our web site. To download, click on the ECOMPASS_SW link on the Xtrinsic eCompass software page, read and approve the license agreement that pops up (you can freely use this software in products which include Freescale magnetometers and accelerometers), and save the offered .zip file onto your hard drive.
When you expand the zip file, you will have a folder called "eCompass", with sub-folders: "Documents" and "Software". This is a major new release. I'm going to claim it to be the best-documented e-compass solution anywhere, thanks to the Herculean efforts of my good friend Mark Pedley, who also supplied much of the content for this post. Here's what you're going to find in the "Documents" folder:
- Software for Tilt-Compensated eCompass with Magnetic Calibration (v3 Release) User Guide
- AN4676 - Euler Angle, Rotation Matrix and Quaternion Representations of Orientation in Aerospace, Android
and Windows 8 Coordinates - AN4684 - Magnetic Calibration of Hard and Soft Iron Interference
- AN4685 - Tilt-Compensated eCompass in Aerospace, Android and Windows 8 Coordinate Systems
- AN4696 - Accelerometer and Magnetometer Sensor Simulatoin for Tilt-Compensated eCompass
- AN4697 - Low Pass Filtering of Orientation Estimates
- AN4698 - CPU, Flash and RAM Benchmarks : Xtrinsic eCompass and Magnetic Calibration Algorithms
- AN4699 - Data Structures for Matrix and Vector Algebra
- AN4700 - Control Loop, Data Structures and Compile Time Constants
- AN4706 - Accelerometer and Magnetometer Selection and Configuration
The software itself has been expanded and improved.
The "Software" directory contains half a dozen C source and header files that contain everything you need to implement your own e-compass. It also includes a pre-compiled command line tool that lets you simulate performance of the e-compass. The ANSI C source code is processor agnostic allowing Freescale customers to retain their existing MCU architecture. The software is highly optimized to minimize use of program memory, RAM and floating point calculations. Software features include:
- The code compiles into 10KB of ARM Thumb2 object code and uses less than 4KB of RAM.
- A dedicated floating point unit (FPU) is not required and the software can run on typical 32 bit integer processors with software floating point emulation.
- Orientation is provided in Euler angle (roll, pitch, yaw and compass heading), rotation matrix and quaternion formats.
- Supports Aerospace, Android and Windows 8 coordinate systems
- Tilt-compensated
- Programmable low pass filter
- Quality of fit metric indicates expected compass heading error
- Resilient to magnetic jamming corrupting calibration
- Three levels of hard and soft iron magnetic calibration are provided at increasing levels of performance and computational complexity.
- The simplest 4 element calibration solver computes the hard iron correction vector and geomagnetic field strength and removes the largest component of the magnetic interference caused by ferromagnetic components on the circuit board. It consumes 3300 floating point operations per call.
- The seven element calibration solver corrects for differing magnetic permeability along the three Cartesian axes and is suitable for the more complex calibration environments found in the dense circuit board layouts of smartphones and tablets. It consumes 20,000 floating point operations per call.
- The 10 element calibration solver computes a best-fit solution to the 10 dimensional magnetic optimization problem including off-diagonal elements of the soft iron matrix. It consumes 62,000 floating point operations per call.
The web-release includes source for options 1 and 2 above. Option 3, the highest performing 10 element calibration solver, is not available in source form, but is available under license in object code format for ARM Thumb2 processors. If you have used previous generations of our e-compass software, you will see major improvements in the feature set above. I like the fact that it now supports any of three different orientation representations right out of the box. The math behind an electronic compass isn't easy, but Mark has done an excellent job of breaking it down into manageable chunks that are easily digested. So please, download the new release, give it a go and let us have your feedback.
References:
