This Isentek eCompass API Quick Start Tutorial •eCompassAPI library •PCB Sensor direction and coordinate system •Sample code •API Manual (chm) •FAQ

1. eCompass API quick start
Alex.Hsieh
2016.11.10
V2.0.1

2. Outline
• eCompass API library
• PCB Sensor direction and coordinate system
• Sample code
• API Manual (chm)
• FAQ

3. eCompass API library & manual
• Check 5 files for eCompass API library
1) Sample code folder
2) Config.h
3) IST_LIB.h
4) IST_LIB.c
5) eCompass API.chm

4. eCompass API library
• Include 2 header file (.h) and 1 source file (.c) in
your project - Config.h / IST_LIB.h / IST_LIB.c
• Copy essential part from sample code - Main.c

5. PCB Sensor direction and coordinate system
• Change mag and acc sensor axis direction (x, y,
z) to fit coordinate system (N, E, U)
PCB Sensor direction

6. PCB Sensor direction and coordinate system
• Change sensor axis direction (x, y, z) to fit
coordinate system (N, E, U)
X
Y Z
X’
Y’Z’
X’ = -Y
Y’ = -X
Z’ = Z
X’
Y’Z’
X
Y Z
E
N
U
E
N
U
E
N
U
E
N
U

7. PCB Sensor direction and coordinate system
• Change mag sensor data (x, y, z) from LSB to
uT and axis direction • X’ = -Y * Mag_LSBtoUT
• Y’ = -X * Mag_LSBtoUT
• Z’ = Z * Mag_LSBtoUT
• Mag_LSBtoUT = 0.3

8. Sample code
• Steps
1) Copy sample code and enable the essential function
in your project
• Set_HeadingAngleEnable
• Set_MagAccuracyEnable
• Set_SingleCalibration / Set_DynamicCalibration
2) Input data need mag and acc data, if you don’t have
acc data, please input [0,0,9.8]
3) Check the input data axis direction to fit NEU
system

9. Sample code
• Include header file

10. Sample code
• Variable and compass API initialization (A and B
part.)

11. Sample code
• Variable and compass API initialization (A and B
part.)

12. Sample code
• Part B : isentek compass initialization stage
• ist8310_Init(); // init driver
• Set_HeadingAngleEnable(IST_TRUE);// if return Heading angle, it need acc
and mag sensor
• Set_MagAccuracyEnable(IST_TRUE);// if enable eCompass accuracy report -
return 0:unreliable 3:High 2:medum 1: low
• Set_SingleCalibration(IST_TRUE);// if enable single calibration right now
• Set_DynamicCalibration(IST_TRUE) ;// if enable continuous calibration
• Set_MagBias(Mag_IST8310_Bias);
// if you have last calibrated value and don't calibrate again, you can set by this
"Set_MagBias" function
// note : this setting dependent on your application, please check if you
applciation is suitable

13. Sample code
• Run process in while loop (C1-C6 part.)

14. Sample code
• Run process in while loop (C1-C6 part.)

15. Sample code
• Run process in while loop (C1 & C2 part.)
// C1. Get mag and acc data from driver and change the sensor value from LSB
to uT
ist8310_GetXYZ(MagXYZ);
for (int i = 0; i < 3; ++i) {
Mag_RawData[i] = (float)MagXYZ[i] * Mag_LSBtoUT;
}
// C2. Dependent on PCB layout, change the mag and acc direction to NEU (x =
east, y = west, z = up)
Mag_RawData[0] = Mag_RawData[0];
Mag_RawData[1] = -Mag_RawData[1];
Mag_RawData[2] = Mag_RawData[2];
AccData[0] = AccData[1];
AccData[1] = AccData[0];
AccData[2] = AccData[2]; PCB Sensor direction

16. Sample code
• Run process in while loop (C3-C4 part.)
// C3. Run Compass Process to get Calibrated Data
// Here, we use constant acc data input [0,0,9.8], also, acc data [0,0,1] is ok.
Process_RunCompass(Mag_RawData, AccData, Mag_CalibratedData);
// C4. Check Calibration Status
// Mag_CalibrationStatus : In calibration = 1, no = 0
// Get_MagBias : BiasX, BiasY, BiasZ, Radius
// Mag_GetIST8310_Bias element will have valid value after calibration,
// you can check the bias value to know process finish calibration.
Mag_CalibrationStatus = Get_CalibrationStatus();
Get_MagBias(Mag_GetIST8310_Bias);

17. Sample code
• Run process in while loop (C5-C6 part.)
// C5. Get Heading Angle
// Get_HeadingAngle return int type angle. 0 - 360 degree
// Get_HeadingAngle100 return int type angle . 0 - 36000 degree
// Therefore, we need to change angle type
Mag_HeadingAngle = (float)Get_HeadingAngle();
Mag_HeadingAngle_Int100 = 0.01f * ((float)Get_HeadingAngle100());
// C6. Get Mag Accuracy Status
// 0:unreliable 3:High 2:medum 1: low
Mag_Accurancy = Get_MagAccuracyStatus();

18. API Manual (chm)
• File list – inc – IST_LIB.h

19. API Manual (chm)
• Function list

20. API Manual (chm)
• Function detail

21. FAQ
• IST_A001 – What’s the LSB to uT?
• IST_A002 – Why do we change the axis of acc and mag sensor to
NEU system?
• IST_A003 – What’s the difference and priority between
Set_SingleCalibration and Set_DynamicCalibration API?
• IST_A004 – How to calibrate eCompass correctly?
• IST_A005 – What’s the definition for 0, 1, 2, 3 in accuracy report ?
• IST_A006 – What time do I use “Set_MagBias” function?