User Manual CompassPoint Prime 3-Axis Electronic Compass Module
Table of Contents 1 2 3 COPYRIGHT & WARRANTY INFORMATION ....................................................................... 1 INTRODUCTION................................................................................................................ 2 SPECIFICATIONS ............................................................................................................... 3 3.1 3.2 3.3 4 Performance Specifications .................................................................................
6 FIELD CALIBRATION........................................................................................................ 23 6.1 Magnetic Calibration Overview ................................................................................................. 24 6.1.1 Hard-Iron and Soft-Iron Effects ......................................................................................... 24 6.1.2 Magnetic Calibration Limitations ...............................................................................
8 CODE EXAMPLES ............................................................................................................ 49 8.1 8.2 8.3 8.4 8.5 Header File & CRC-16 Function ................................................................................................. 49 CommProtocol.h File ................................................................................................................. 52 CommProtocol.cp File .........................................................................
1 Copyright & Warranty Information © Copyright PNI Sensor Corporation 2009 All Rights Reserved. Reproduction, adaptation, or translation without prior written permission is prohibited, except as allowed under copyright laws. Revised July 2011. For most recent version visit our website at www.pnicorp.com PNI Sensor Corporation 133 Aviation Blvd, Suite 101 Santa Rosa, CA 95403, USA Tel: (707) 566-2260 Fax: (707) 566-2261 Warranty and Limitation of Liability.
2 Introduction Thank you for purchasing PNI’s CompassPoint™ Prime 3-axis electronic compassing module. Incorporating 3-axis magnetic field sensing and 3-axis tilt sensing, the Prime provides accurate and precise tilt-compensated heading measurements at up to 45° of tilt. The Prime utilizes PNI’s advanced magnetic distortion correction algorithms to provide accurate heading information when incorporated into a user’s system, even when the compass is being tilted.
3 Specifications 3.1 Performance Specifications Table 3-1: Specifications 1 Parameter Heading Value Range Accuracy, tilt ≤45° Resolution Repeatability Range Pitch Roll Tilt (Pitch & Roll) Accuracy Resolution Repeatability Maximum Functional Dip Angle2 Usable Field Range Magnetometer Resolution Repeatability 360° 1° rms 0.1° 0.05° rms ±90° ±180° 1° rms 0.1° 0.05° rms 85° ±100 µT 0.05 µT 0.1 µT Footnotes: 1. Specifications are subject to change.
Table 3-3: Power Requirements Parameter Value DC Supply Voltage Average Current Draw @ 10 Hz sample rate1 During external power up Peak Current Draw1 During logical power up/down Sleep Mode Current Draw 3.6 - 5 V (unregulated) 18 mA 120 mA pk, 75 mA over 2 ms 110 mA pk, 85 mA over 1 ms, 60 mA over 2 ms 0.25 mA Footnote: 1. Tested at 3.6 V. Table 3-4: Environmental Requirements Parameter Value Operating Temperature1 Storage Temperature -40C to +85C -40C to +85C Footnote: 1.
3.3 Mechanical Drawing Note: The default orientation for the Prime is for the silk-screened arrow to point in the “forward” direction.
4 Set-Up This section describes how to configure the Prime in your host system. To install the Prime into your system, follow these steps: Make electrical connections to the Prime. Evaluate the Prime using the included StudioPrime program or terminal emulation software, such as Tera Term or RealTerm, to ensure the compass generally works correctly. Choose a mounting location in the host system. Mechanically mount the Prime in the host system. Perform a field calibration. 4.
The Prime Interface Kit includes the PNI 45 cm (18”) custom pigtailed cable (see Figure 3-2). One end of the cable mates with the Prime’s 9 pin Molex connector while the other end is not connectorized and has 9 wires accessible. These wires are intended to mate with the user’s system. The cable’s wires are color coded as indicated in Table 4-1. The Prime Evaluation Kit includes the same PNI pigtailed cable as provided in the Interface Kit, plus a 1.8 m (6’) custom dual-connectorized cable.
4.2.3 Mount in a physically stable location Choose a location that is isolated from excessive shock, oscillation, and vibration. The Prime works best when stationary. Any non-gravitational acceleration results in a distorted reading of Earth’s gravitational vector, which affects the heading measurement. 4.2.
Figure 4-1: Positive & Negative Roll and Pitch Definition Prime User Manual r08 Page 9
5 Operation with StudioPrime The StudioPrime evaluation software communicates with the Prime through the RS232 serial port of your computer. It puts an easy-to-use, graphical-user interface (GUI) onto the binary command language used by the Prime. Instead of manually issuing command codes, the user can use buttons, check boxes, and dialog boxes to control the Prime and obtain data. It reads the binary responses of the Prime output and formats this into labeled and easy-to-read data fields.
5.2.1 Initial connection When initially launching StudioPrime: If using the PNI dual-connecterized cable, ensure the batteries are well-charged and the cable is securely attached to the Prime and the PC’s serial port. Select the serial port the module is plugged into, which is generally COM 1. Select 38400 as the baud rate. Click the button if the connection is not automatically made.
5.3 Configuration Tab Note: No settings will be changed in the unit until the button has been selected. 5.3.1 Mounting Options StudioPrime supports 6 mounting orientations, as detailed below in Figure 5-1. Note that PNI’s binary protocol supports 18 more orientations (24 total), as shown in Figure 7-2.
5.3.2 North Reference Magnetic When the button is selected, heading will be relative to magnetic north. True When the button is selected, heading will be relative to geographic (true) north. In this case, the declination needs to be set in the “Declination” box. Refer to Section 6.3 for more information. 5.3.3 Endianess Select either the or Endian button. The default is . See Section 7.2 for more information on appropriate data formats. 5.3.
new data as soon as the previous request has been fulfilled. Note that the inverse of the Poll Delay is somewhat greater than the sample rate, since the Poll Delay does not include actual acquisition time. Interval Delay The Interval Delay is relevant when Push Mode is selected, and is the time delay, in seconds, between completion of the Prime module sending one set of sampled data and the start of sending the next sample set.
takes more time. If this checkbox is deselected, then the module will NOT wait for a stable reading and will immediately take a reading once the minimum changebetween-points threshold has been met. Automatic Sampling When this checkbox is selected, the module automatically takes a calibration point once the minimum change-between-points requirement and the stability check requirement (if selected) have been satisfied.
5.4 5.4.1 Calibration Tab Samples Before proceeding, refer to Section 6.2 for the recommended calibration procedure corresponding to the calibration method selected on the Configuration tab. Clicking the button begins the calibration process. If “Automatic Sampling” is not checked on the Configuration tab, it is necessary to click the button to take a calibration sample point.
5.4.2 Calibration Results Once calibration is complete the “Calibration Results” window will indicate the quality of the calibration. This applies to both magnetic sensor and accelerometer calibration. The X, Y, and Z “Dist Coverage” values show a percentage of each vector that has been covered during the calibration. The only way to get a Z value greater than 50% would be to take some points with the module upside-down.
5.4.4 Options Audible Feedback: If selected, StudioPrime gives an audible signal when a calibration point is taken. Note that an audible signal also will occur when the button is clicked, but no data will be taken. 5.4.5 Clear Clear Mag Cal to Factory: This button clears the user’s calibration of the magnetic sensors. Once selected, the module reverts to its factory default values. To save this action in non-volatile memory, click the button.
5.5 Test Tab 5.5.1 Current Reading Once the button is selected the unit will begin outputting heading, pitch and roll information. The button then turns to a button. Selecting the button or changing tabs will halt the output. Contrast Selecting this box sets the “Current Readings” window to have yellow lettering on a black background, rather than black lettering on a white background. 5.5.
5.6 Data Logger Tab StudioPrime can capture measurement data and then export it to a text file. To acquire data and export it, follow the procedure below: Select the data to log in the “Data” window. Use Shift-Ctrl-Click and Ctrl-Click to select multiple items. Click on the button to start logging. The button changes to a button after data logging begins. Click the button to stop logging. Click the button to save the data to a text file.
5.7 System Log Tab The System Log tab shows all communication between StudioPrime and the Prime module since StudioPrime was opened. Closing StudioPrime will erase the system log. Select the button, at the bottom right of the screen, to save the system log to a text file.
5.8 Graph Tab The graph provides a 2-axis (X,Y) plot of the measured field strength. The graph can be used to visually see hard and soft iron effects within the environment measured by the Prime module as well as corrected output after a field calibration has been performed. (The screen shot shown shows the MX and MY readings as the module was held horizontally and rotated through 360º in the horizontal plane, then held in vertical orientation and rotated 360º in the vertical plane.
6 Field Calibration Sources of magnetic distortion that are positioned near the Prime in the user’s system will distort Earth’s local magnetic field and need to be compensated for before implementing the Prime in the host system. Examples of such sources include ferrous metals and alloys (ex. iron, nickel, magnetized or non-stainless steel, etc.), batteries, permanent magnets, wires, and electric motors.
6.1 Magnetic Calibration Overview The main objective of a magnetic field calibration is to compensate for distortions to the magnetic field caused by the host system. To that end, the Prime needs to be mounted within the host system and the entire system must be moved as a single unit during calibration. 6.1.1 Hard-Iron and Soft-Iron Effects Hard-iron distortions are caused by permanent magnets and magnetized steel or iron objects within close proximity to the sensors.
The calibration procedures can be executed using StudioPrime or the Prime’s binary protocol. Sections 5.3 and 5.4 outline how to configure and perform a calibration in StudioPrime. The steps below provide an example sequence of commands to perform a calibration using the PNI binary protocol. (Refer to Section 7 for information on how to implement the binary protocol commands.) Using the kSetParam command, set the number of filter taps. (8 is typical.) Using the kSetConfig command, set kUserCalAutoSampling.
Figure 6-1: Magnetic Calibration Pattern PNI Sensor Corporation Prime User Manual – July 2011 DOC# 1014177 r08 Page 26
Table 6-1: Magnetic Calibration Pattern Sample # Yaw Pitch Roll 0° 90° 180° 270° ±5° ±5° ±5° ±5° 30° to 40° -30° to -40° 30° to 40° -30° to -40° 30° 120° 210° 300° > +45° > +45° > +45° > +45° 30° to 40° -30° to -40° 30° to 40° -30° to -40° 60° 150° 240° 330° < -45° < -45° < -45° < -45° 30° to 40° -30° to -40° 30° to 40° -30° to -40° First Circle 1 2 3 4 Second Circle 5 6 7 8 Third Circle 9 10 11 12 6.2.
Figure 6-2: Accelerometer Calibration Starting Positions Table 6-2: Accelerometer Calibration Pattern Sample # Yaw Pitch Roll 0° 0° 180° 0° 0° 0° 0° 90° 0° -90° 0° 0° 90° 90° -90° 90° 0° 180° 0° 90° 180° ±5° ±5° ±5° 10° to 20° -10° to -20° 10° to 20° 270° 30° 120° ±5° > +45° > +45° -10° to -20° 10° to 20° -10° to -20° 210° 300° 60° > +45° > +45° < -45° 10° to 20° -10° to -20° 10° to 20° 150° 240° 330° < -45° < -45° < -45° -10° to -20° 10° to 20° -10° to -20° Sides 1 2 3 4 5 6 First Corne
6.2.3 Simultaneous Mag and Accel Calibration The Prime allows for a simultaneous magnetic sensor and accelerometer field calibration. This requires a good 18 point calibration pattern, stable measurements, and installation in the user’s system. The Accelerometer Calibration Pattern discussed in Section 6.2.2 works well for a simultaneous calibration.
7 Operation with PNI Binary Protocol The Prime utilizes a binary protocol that is transmitted over an RS232 interface. configuration parameters should be set as follows: The Table 7-1: Configuration Parameter Value Number of Data Bits Start Bits Stop Bits Parity 7.
7.2 Parameter Formats Note: Floating-point based parameters conform to ANSI/IEEE Std 754-1985. Please refer to the Standard for more information. PNI also recommends the user refer to the compiler’s instructions to understand how the compiler implements floating-point format. 64-Bit floating point (Float64) Below is the 64-bit float format (double precision) in Big Endian. In Little Endian the bytes are in reverse order in 4 byte groups. (e.g. Big Endian: ABCD EFGH; Little Endian: DCBA HGFE).
Signed 16-bit Integer (SInt16) SInt16 based parameters are signed 16 bit numbers (2’s compliment). represents the sign of the value (0=positive, 1=negative) 15 8 7 msb 0 7 0 15 8 lsb lsb Bit 15 msb Little Endian Big Endian Signed 8-bit Integer (SInt8) UInt8 based parameters are unsigned 8-bit numbers. Bit 7 represents the sign of the value (0=positive, 1=negative) 7 0 byte Unsigned 32-bit Integer (UInt32) UInt32 based parameters are unsigned 32 bit numbers.
Unsigned 8-bit Integer (UInt8) UInt8 based parameters are unsigned 8-bit numbers. 7 0 byte Boolean Boolean is a 1-byte parameter that MUST have the value 0 (false) or 1 (true). 7 0 byte 7.3 Commands & Communication Frames The Prime’s command set is given below and descriptions of each command follow.
22 23 24 25 26 27 28 29 30 31 36 37 kStopIntervalMode kPowerUp kSetAcqParams kGetAcqParams kAcqParamsDone kAcqParamsResp kPowerDownDone kFactoryUserCal kFactorUserCalDone kTakeUserCalSample kFactoryInclCal kFactoryInclCalDone 7.3.
7.3.3 kSetDataComponents (frame ID 3d) This frame sets the data components in the module's data output. This is not a query for the module's data (see kGetData). The first byte of the payload indicates the number of data components followed by the data component IDs.
kDistortion (Component ID 8d) Read only flag that indicates that at least one magnetic sensor axis reading is beyond ±100 µT. kCalStatus (Component ID 9d) Read only flag that indicates field calibration status. False (Default) = Not calibrated. kPAligned, kRAligned & kIZAligned (Component IDs 21d, 22d, 23d) User calibrated Earth’s gravity vector (G) component output. kPAngle, kRAngle (Component IDs 24d, 25d) The outputs provide pitch and roll angles. The pitch range is -90.0˚ to 90.
7.3.6 kSetConfig (frame ID 6d) This frame configures the Prime. Configuration values must be set one at time. Payload Config ID Value UInt8 ID Specific Example: To configure the declination, the payload would look like: 1 10.
kUserCalStableCheck kUserCalNumPoints kUserCalAutoSampling 11 12 13 Boolean UInt32 Boolean kBaudRate 14 UInt8 True or False 12 – 32 True or False 0 – 300 1 – 600 2 – 1200 3 – 1800 4 – 2400 5 – 3600 6 – 4800 7 – 7200 8 – 9600 9 – 14400 10 – 19200 11 – 28800 12 – 38400 13 – 57600 14 - 115200 True 12 True 12 Configuration parameters and settings for kSetConfig: kDeclination (Config. ID 1d) This sets the declination angle to determine True North heading.
Figure 7-2: PNI Protocol Mounting Orientations Prime User Manual r08 Page 39
kUserCalStableCheck (Config. ID 11d) This flag is used during field calibration. If set to FALSE, a calibration point can be taken if the magnetic field is stable to <23 µT for each axis. If set to TRUE a calibration point can be taken if the magnetic field is stable to <5 µT for each axis. kUserCalNumPoints (Config. ID 12d) The user must select the number of points to take during a field calibration. The number of points must be within “Allowable Range”.
7.3.8 kConfigResp (frame ID 8d) This frame is the response to kGetConfig frame. The payload contains the configuration ID and value. Payload Config ID Value UInt8 ID Specific Example: If a request to get the set declination angle, the payload would look like: 1 10.0 Declination ID Declination Angle (Float32) 7.3.9 kSave (frame ID 9d) This frame commands the module to save internal configurations and field calibration to non-volatile memory.
Below is a complete sample frame for an Accelerometer Only Calibration: 00 09 0A 00 00 00 64 5C F9 7.3.11 kStopCal (frame ID 11d) This command aborts the calibration process. The prior calibration results are retained. 7.3.12 kSetParam (frame ID 12d) The Prime incorporates a finite impulse response (FIR) filter to provide a more stable heading reading. The number of taps (or samples) represents the amount of filtering to be performed.
Table 7-6: Recommended FIR Filter Tap Values Count 4 Tap Filter 8 Tap Filter 16 Tap Filter 32 Tap Filter 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 01.9875512449729e-2 06.4500864832660e-2 01.6637325898141e-1 02.4925036373620e-1 02.4925036373620e-1 01.6637325898141e-1 06.4500864832660e-2 01.9875512449729e-2 07.9724971069144e-3 01.2710056429342e-2 02.5971390034516e-2 04.6451949792704e-2 07.1024151197772e-2 09.5354386848804e-2 01.1484431942626e-1 01.
7.3.14 kParamResp (frame ID 14d) This frame is the response to kGetParam and contains the current FIR filter settings. The format and values will be the same as defined by kSetParam. Payload Parameter ID Axis ID Count Value1 Value2 Value3 ValueCount UInt8 UInt8 UInt8 Filter Top Value ID Specific ID Specific ID Specific 7.3.15 kPowerDown (frame ID 15d) This frame is used to completely power-down the module, which is referred to as putting the module in Sleep Mode. The frame has no payload.
7.3.18 kUserCalScore (frame ID 18d) This frame contains the calibration score, which is presented after completing or aborting a calibration. It is a series of Float32 values as shown in the payload diagram below.
7.3.20 kSetParamDone (frame ID 20d) This frame is the response to kSetParam frame. The frame has no payload. 7.3.21 kStartIntervalMode (frame ID 21d) This frame commands the module to output data at a fixed time interval, otherwise known as Push Mode. See kSetAcqParams. The frame has no payload. 7.3.22 kStopIntervalMode (frame ID 22d) This frame commands the module to stop data output when in Push Mode. The frame has no payload. 7.3.
Note: If “Flush Filters” is selected the rate at which the output is updated will be inversely proportional to the number of taps. For example, if 8 taps and flush filters are selected, the output will be updated at ~3.5 Hz, while it will be updated at ~1 Hz if 32 taps is selected. SensorAcqTime: The SensorAcqTime sets the time between samples taken by the module, in seconds. The default is 0.0 seconds, which means that the module will reacquire data immediately after the last acquisition.
7.3.28 kPowerDownDone (frame ID 28d) This frame is the response to kPowerDown frame. This indicates that the Prime successfully received the kPowerDone frame and is in the process of powering down. The frame has no payload. 7.3.29 kFactoryUserCal (frame ID 29d) This frame clears the magnetic sensor field calibration coefficients and returns to the factory-loaded coefficients. The frame has no payload. This frame must be followed by the kSave frame to change in non-volatile memory. 7.3.
8 Code Examples The following example files (CommProtocol.h, CommProtocol.cp, Prime.h and Prime.cp) would be used together for proper communication with a Prime module. NOTE: The user also needs to create the following: SystemSerPort.h; Processes.h, TickGenerator.h. 8.
kStopIntervalMode, kPowerUp, kSetAcqParams, kGetAcqParams, kAcqParamsDone, kAcqParamsResp, kPowerDoneDown, kFactoryUserCal, kFactoryUserCalDone, kTakeUserCalSample, kFactoryInclCal, kFactoryInclCalDone, // Param IDs kFIRConfig = 1, // // // // // // // // // // // // 22 23 24 25 26 27 28 29 30 31 36 37 // 3-AxisID(UInt8)+Count(UInt8)+Value(Float64)+...
// Update the CRC for transmitted and received data using // the CCITT 16bit algorithm (X^16 + X^12 + X^5 + 1).
8.2 CommProtocol.h File Note: This file contains objects used to handle the serial communication with the unit. Unfortunately, these files are not available as the program was written on a non-PC computer. The comments in the code should explain what is expected to be sent or received from these functions so that you can write this section for your specific platform. For example, with the TickGenerator.h, you would need to write a routing that generates 10msec ticks. #pragma once #include "SystemSerPort.
kRAngle, // 25 - type Float32 }; enum { //maximum size of our input buffer kBufferSize = 512, //minimum size of a serial packet kPacketMinSize = 5 }; //SerPort is a serial communication object abstracting //the hardware implementation CommProtocol(CommHandler * handler = NULL, SerPort * serPort = NULL); void Init(UInt32 baud = 38400); void SendData(UInt8 frame, void * dataPtr = NULL, UInt32 len = 0); void SetBaud(UInt32 baud); protected: CommHandler * mHandler; SerPort * mSerialPort; UInt8 mOutData[kBuffe
8.3 CommProtocol.cp File #include "CommProtocol.h" // import an object that will provide a 10mSec tick count through // a function called Ticks() #include "TickGenerator.h" // // SerPort is an object that controls the physical serial // interface. It handles sending out the characters, and buffers // the characters read in until we are ready for them.
if(len > kBufferSize - kPacketMinSize) return; // Store the total len of the packet including the len // bytes(2), the frame ID(1), the data (len), and the crc (2).
} return crc; } // // This is called each time this process gets a turn to execute. // void CommProtocol::Control() { // InLen returns the number of bytes in the input buffer of // the serial object that are available for us to read. UInt32 inLen = mSerialPort->InLen(); switch(mStep) { case 1: { // wait for length bytes to be received by the // serial object if(inLen >= 2) { // Read block will return the number of // requested (or available) bytes that are in // the serial objects input buffer.
mSerialPort->ReadBlock(&mInData[2], mExpectedLen - 2); // in CRC verification, don't include the CRC // in the recalculation (-2) crc = CRC(mInData, mExpectedLen - 2); // CRC is also ALWAYS transmitted in big // Endian crcReceived = (mInData[mExpectedLen - 2] << 8) | mInData[mExpectedLen - 1] ; if(crc == crcReceived) { // the crc is correct, so pass the frame // up for processing.
8.4 Prime.h File #pragma once #include "Processes.h" #include "CommProtocol.h" // // This file contains the object providing communication to the // Prime. It will set up the unit and parse packets received // Process is a base class that provides Prime with cooperative // parallel processing. The Control method will be // called by a process manager on a continuous basis.
8.5 Prime.cp File #include "Prime.h" #include "TickGenerator.h" const UInt8 kDataCount = 4;// We will be requesting 4 components //(Heading, pitch, roll, temperature) // // This object polls the Prime unit once a second for heading, // pitch, roll and temperature.
// Message is a function that displays a C // formatted string (similar to printf) Message("Received %u data elements instead of the %u requested\r\n", (UInt16)count, (UInt16)kDataCount); return; } // loop through and collect the elements while(count) { // The elements are received as {type (ie.
{ // Move(source, destination, size // (bytes)). Move copies the // specified number of bytes from // the source pointer to the // destination pointer. // Store the roll. Move(&(data[pntr]), &roll, sizeof(roll)); // increase the pointer to point // to the next data element type pntr += sizeof(roll); break; } case CommProtocol::kTemperature: { // Move(source, destination, size // (bytes)). Move copies the // specified number of bytes from // the source pointer to the // destination pointer.
break; } default: { // Message is a function that displays a formatted // string (similar to printf) Message("Unknown frame %02X received\r\n", (UInt16)frameType); break; } } } // // Have the CommProtocol build and send the frame to the unit. // void Prime::SendComm(UInt8 frameType, void * dataPtr, UInt16 dataLen) { if(mComm) mComm->SendData(frameType, dataPtr, dataLen); // Ticks is a timer function. 1 tick = 10msec.
// Ticks is a timer function. 1 tick = 10msec. if(Ticks() > mTime) { // tell the unit to take a sample SendComm(CommProtocol::kGetData); mTime = Ticks() + 100; // take a sample every // second mStep++; } break; } case 3: { // Ticks is a timer function. 1 tick = 10msec. if(Ticks() > mResponseTime) { Message("No response from the unit.