TLx493D 3D Hall Sensor Generic Library  1.3
Generic library for the TLx493D 3D Hall sensor family
3D Hall Sensor Generic Library

General Description

The TLx493D Generic Library is a microcontroller-agnostic implementation of a software stack abstraction for sensors of the TLx493D 3D Hall family.

The supported hardware versions are:
*TLV493D-A1B6
*TLE493D-A2B6
*TLE493D-W2B6
*TLI493D-W2BW

The library presents the following three levels of abstraction:
*TLx493D abstraction level
*TLV493D/TLE493D + TLI493D-W2BW abstraction levels
*Drivers abstraction levels

Quick start guide

Before calling any library function it is important to note that the functions require the ability to communicate with the 3D Hall sensor on the I2C bus. This implementation of such functionality depends on the microcontroller that the library will be compiled for. As such, the user is required to provide certain functions that when called by the library, will establish communication with the sensor. For details about the aforementioned functions regarding implementation and interfacing with the library, please see the file:
interface.h

The Core distribution of this library does not provide implementations for such functions.
The XMC distribution of the library provides XMC drivers already interfaced with the library.

Follow the TODO comments in the code for additional interfacing instructions.

When importing the library as a project in Dave IDE, only use the Debug Build Configuration, otherwise the project might not build !

TLx493D abstraction level

The library is able to automatically detect the sensor type and version, making it very easy to get started with such a sensor. The downside of using this level is that regardless of the sensor used, only basic functionality is available to the user, and only one sensor can be used at a time (bus mode not supported).

Example code for reading a data frame in Master Control Mode:

// please note that the value of status should be checked and properly handler
int32_t status;
int16_t Bx_LSB, By_LSB, Bz_LSB, sensor_temperature_LSB;
// Initialize the sensor
status = TLx493D_init();
// set operation mode to Master Control Mode
status = TLx493D_set_operation_mode(TLx493D_OP_MODE_MCM);
// read a data frame
status = TLx493D_read_frame(&frame);
// Copy Magnetic Field Intensity and temperature values in LSB format
Bx_LSB = frame.x;
By_LSB = frame.y;
Bz_LSB = frame.z;
sensor_temperature_LSB = frame.temp;

For this abstraction level please see the following files:
TLx493D.h
TLx493D.c

TLV493D/TLE493D/TLI493D-W2BW abstraction levels

By using the functions defined at this abstraction level, the user may change most of the sensor parameters while also not having to manually change register values or ensure that parity values are correct. This level presents a balance between ease of use and access to sensor settings and is the recommended mode for testing sensor features. The sensor type and version must be known by the user (it is written on the PCB of newer kit versions).

Example code for reading a data frame in Master Control Mode on TLE493D-A1B6:

// please note that the value of status should be checked and properly handler
int32_t status;
int16_t Bx_LSB, By_LSB, Bz_LSB, sensor_temperature_LSB;
TLV493D_data_t sensor_state;
// power-cycle the sensor
// On the 2Go Kit, the sensor may not be powered by default
// (some 2Go kits do not support sensor power control)
// Initialize the sensor
// sensor_state - data structure used to store the sensor configuration.
// "NULL" can be passed to use the internal data structure of the
// library to store the sensor state but when working with several sensors,
// "NULL" can be passed for only one of them.
// false - ADDR (i.e. SDA) line will be HIGH at sensor power up. Use false otherwise.
// TLV493D_A1B6_ADDR_1E_9C - the address to be configured to the sensor. Since true was passed
// for the previous parameter, the greater address (9C) will be used for
// further I2C communications.
status = TLV493D_A1B6_init(&sensor_state, true, TLV493D_A1B6_ADDR_1E_9C);
// set operation mode to Master Control Mode
status = TLV493D_A1B6_set_operation_mode(&sensor_state, TLx493D_OP_MODE_MCM);
// read a data frame
status = TLV493D_A1B6_read_frame(&sensor_state, &frame);
// Copy Magnetic Field Intensity and temperature values in LSB format
Bx_LSB = frame.x;
By_LSB = frame.y;
Bz_LSB = frame.z;
sensor_temperature_LSB = frame.temp;

Example code for reading a data frame in Master Control Mode on TLE493D-A2B6/W2B6/TLI493D-W2BW:

// please note that the value of status should be checked and properly handler
int32_t status;
int16_t Bx_LSB, By_LSB, Bz_LSB, sensor_temperature_LSB;
TLE493D_data_t sensor_state;
// power-cycle the sensor
// On the 2Go Kit, the sensor may not be powered by default
// Initialize the sensor
// sensor_state - data structure used to store the sensor configuration.
// "NULL" can be passed to use the internal data structure of the
// library to store the sensor state but when working with several sensors,
// "NULL" can be passed for only one of them.
// Please note that the structure type is different then in the TLV example!
// TLE493D_AW2B6_I2C_A0_ADDR - the fused address of the sensor. It can be A0, A1, A2 or A3.
status = TLE493D_AW2B6_init(&sensor_state, TLE493D_AW2B6_I2C_A0_ADDR);
// set operation mode to Master Control Mode
status = TLE493D_AW2B6_set_operation_mode(&sensor_state, TLx493D_OP_MODE_MCM);
// read a data frame
status = TLE493D_AW2B6_read_frame(&sensor_state, &frame);
// Copy Magnetic Field Intensity and temperature values in LSB format
Bx_LSB = frame.x;
By_LSB = frame.y;
Bz_LSB = frame.z;
sensor_temperature_LSB = frame.temp;

For TLV493D-A1B6 please see the following files:
TLV_A1B6.h
TLV_A1B6.c

For TLE493D-A2B6/-W2B6 please see the following files:
TLE_AW2B6.h
TLE_AW2B6.c

Drivers abstraction levels

The lowest abstraction level presented by the library is the driver level allowing basic read and write operations with reserved data correction for the TLV493D-A1B6. The implementation is stateless and allows reading and writing sensor registers.

Example code for reading a data frame in Master Control Mode on TLE493D-A1B6:

// please note that the value of status should be checked and properly handler
int32_t status;
TLV493D_data_t sensor_state;
// power-cycle the sensor
// On the 2Go Kit, the sensor may not be powered by default
// { Initialize the sensor }
// consider the line ADDR(i.e. SDA) as HIGH at sensor startup
// and user default I2C address for that particular case
sensor_state.IIC_addr = TLV493D_A1B6_I2C_DEFAULT_ADDR_HIGH;
// copy the state of ALL the read registers, used for auto-correction
// on write operations
status = TLV493D_A1B6_read_regs(sensor_state.IIC_addr,
&(sensor_state.regmap_read),
TLV493D_A1B6_READ_REGS_COUNT - 1
);
// { Configure Master Control Mode }
// clear IICAddr, INT, FAST, LOW flags
sensor_state.regmap_write.MOD1 &= ~(TLV493D_A1B6_MOD1_IICAddr_MSK
| TLV493D_A1B6_MOD1_INT_MSK
| TLV493D_A1B6_MOD1_FAST_MSK
| TLV493D_A1B6_MOD1_LOW_MSK);
// set Master Control Mode configuration and 9C as I2C address
// (it ADDR were LOW at sensor power-up, the address would have been 1E)
sensor_state.regmap_write.MOD1 |= TLV493D_A1B6_MOD1_IICAddr_1E_9C
| TLV493D_A1B6_MOD1_INT_DISABLE
| TLV493D_A1B6_MOD1_FAST_ENABLE
| TLV493D_A1B6_MOD1_LOW_ENABLE;
// write the register to the sensor; use read registers for correction of
// reserved bits (so they do not need to be copied manually)
status = TLV493D_A1B6_write_regs(sensor_state.IIC_addr,
&(sensor_state.regmap_write),
&(sensor_state.regmap_read));
// { after changing the address, manually update it in the data structure }
sensor_state.IIC_addr = 0x9Cu;
// { read a data frame }
// note that here the information is located in sensor_state.regmap_read
// and it is NOT parsed. In order to extract the Bx, By, Bz and temperature
// values, please see the TLV493D_A1B6_read_frame function (found in TLV_A1B6.c).
status = TLV493D_A1B6_read_regs(sensor_state.IIC_addr,
&(sensor_state.regmap_read),
TLV493D_A1B6_Temp2_REG);

Example code for reading a data frame in Master Control Mode on TLE493D-A1B6:

// please note that the value of status should be checked and properly handler
int32_t status;
TLV493D_data_t sensor_state;
// power-cycle the sensor
// On the 2Go Kit, the sensor may not be powered by default
// { Initialize the sensor }
// set I2C address
sensor_state.IIC_addr = TLE493D_AW2B6_I2C_A0_ADDR;
// I2C address A0 (not hexadecimal value A0, but rated the address with the label A0)
// 1-byte read protocol, Collision Avoidance Enabled, Interrupt Disabled
// Mode Master Control Mode
sensor_state.regmap.MOD1 = TLE493D_AW2B6_MOD1_IICadr_A0
| TLE493D_AW2B6_MOD1_PR_1BYTE
| TLE493D_AW2B6_MOD1_CA_ENABLE
| TLE493D_AW2B6_MOD1_INT_DISABLE
| TLE493D_AW2B6_MOD1_MODE_MCM;
// compute the parity bit
sensor_state.regmap.MOD1 |= (_get_FP_bit(&sensor_state) << TLE493D_AW2B6_MOD1_FP_POS);
// write registers
status = TLE493D_AW2B6_write_reg(sensor_state.IIC_addr,
TLE493D_AW2B6_MOD1_REG,
sensor_state.regmap.MOD1
);
// write config reg, set trigger
sensor_state.regmap.Config = TLE493D_AW2B6_Config_TRIG_R6;
status = TLE493D_AW2B6_write_reg(sensor_state.IIC_addr,
TLE493D_AW2B6_Config_REG,
sensor_state.regmap.Config
);
// { read entire register map }
// note that here the information is located in sensor_state.regmap
// and it is NOT parsed. In order to extract the Bx, By, Bz and temperature
// values, please see the TLE493D_AW2B6_read_frame function (found in TLE_AW2B6.c).
status = TLE493D_AW2B6_read_regs(sensor_state.IIC_addr,
&(sensor_state.regmap),
(TLE493D_AW2B6_REGS_COUNT - 1)
);

For this level please see the following files:

For TLV493D-A1B6:
TLV_A1B6_driver.h
TLV_A1B6_defines.h
TLV_A1B6_driver.c

For TLE493D-A2B6/-W2B6 TLI493D-W2BW:
TLE_AW2B6_driver.h
TLE_AW2B6_driver.c
TLE_AW2B6_defines.h