eCompass API quick start

Alex.Hsieh

2016.11.10

V2.0.1

Outline

• eCompass API library

• PCB Sensor direction and coordinate system

• Sample code

• API Manual (chm)

• FAQ

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

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

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

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

UE

N

U

E

N

U

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

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

Sample code

• Include header file

Sample code

• Variable and compass API initialization (A and B

part.)

Sample code

• Variable and compass API initialization (A and B

part.)

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

Sample code

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

Sample code

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

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

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);

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();

API Manual (chm)

• File list – inc – IST_LIB.h

API Manual (chm)

• Function list

API Manual (chm)

• Function detail

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?