Chipinterface API#
- file
novelda_chipinterface.h
A common communication interface API for interfacing signal processing libraries provided by Novelda to the X4 and X7 hardware sensors.
The chipinterface API is meant to simplify the integration of Novelda products into custom environments and is limited to general read/write transactions as well as 2 IO pins - one output for enabling the sensor and one input to detect interrupt events. Although it supports both, I2C and SPI, only one variant is usually used per project. Therefore, integrators may focus on one interface for one specific sensor.
The proposed workflow is as follows:
Add the provided high-level sensor library provided by Novelda into your project. You should see linker errors due to missing chipinterface functions.
Find the missing functions below and implement them based upon the available documentation. Demo chipinterface implementations are available for the Zephyr OS and may serve as a blueprint.
Always hook up a logic analyzer to the bus when testing your code.
-
type chipinterface_error_t#
Status code returned by most of the chipinterface functions.
-
static const chipinterface_error_t CHIPINTERFACE_SUCCESS#
The function call succeeded.
-
static const chipinterface_error_t CHIPINTERFACE_FAILURE#
The function call failed due to an error.
-
static const chipinterface_error_t CHIPINTERFACE_TIMEOUT#
The function timed out.
-
static const uint32_t CHIPINTERFACE_WAIT_FOREVER#
Represents an infinite wait time.
-
enum chipinterface_interrupt_state_t#
- Brief
The current level of the interrupt line
The interrupt line can either be asserted or deasserted. Asserted usually means “high” while deasserted means “low”.
- See
chipinterface_get_interrupt_state
-
enumerator chipinterface_interrupt_asserted#
The interrupt line is asserted
-
enumerator chipinterface_interrupt_deasserted#
The interrupt line is deasserted
-
enum chipinterface_polarity_t#
Clock polarity (CPOL) for SPI communication.
-
enumerator chipinterface_polarity_low#
The clock signal idles at the logical low voltage (CPOL = 0).
-
enumerator chipinterface_polarity_high#
The clock signal idles at the logical high voltage (CPOL = 1).
-
enumerator chipinterface_polarity_low#
-
enum chipinterface_phase_t#
Clock phase (CPHA) for SPI communication.
-
enumerator chipinterface_phase_leading#
The first data bit is outputted immediately when CS activates. Subsequent bits are outputted when SCLK transitions to its idle voltage level. Sampling occurs when SCLK transitions from its idle voltage level (CPHA = 0).
-
enumerator chipinterface_phase_trailing#
The first data bit is outputted on SCLK’s first clock edge after CS activates. Subsequent bits are outputted when SCLK transitions from its idle voltage level. Sampling occurs when SCLK transitions to its idle voltage level (CPHA = 1).
-
enumerator chipinterface_phase_leading#
-
enum chipinterface_bitorder_t#
Bit order for SPI communication.
-
enumerator chipinterface_bitorder_msb#
The most significant bit (MSB) is outputted first on the bus.
-
enumerator chipinterface_bitorder_lsb#
The least significant bit (LSB) is first outputted to the bus.
-
enumerator chipinterface_bitorder_msb#
-
struct chipinterface_spi_config_t#
SPI clock configuration to be used for the connection. Novelda X4 and X7 sensors require a different SPI clock configuration. Novelda provides default values for their sensors.
-
chipinterface_polarity_t clock_polarity#
Clock polarity
-
chipinterface_phase_t clock_phase#
Clock phase
-
chipinterface_bitorder_t bit_order#
Bit order
-
chipinterface_polarity_t clock_polarity#
-
static const chipinterface_spi_config_t chipinterface_default_x4_spi_config#
SPI configuration to be used for communication to X4 sensors.
-
static const chipinterface_spi_config_t chipinterface_default_x7_spi_config#
SPI configuration to be used for communication to X7 sensors.
-
chipinterface_error_t chipinterface_set_chip_enabled(int enabled)#
- Brief
Enables and disables the sensor.
The X4 and X7 sensors feature a hardware signal to switch the sensor on and off. The pin is active high.
- Parameters
enabled – true if the sensor should be enabled, otherwise false
- Returns
CHIPINTERFACE_SUCCESS
on success
-
chipinterface_error_t chipinterface_wait_us(uint32_t microseconds)#
- Brief
Waits for a
microseconds
period.
This function is called whenever the X4/7 drivers need to wait for the sensor. The underlying implementation is free to do whatever while waiting. It may yield the current thread or bring the whole system into a sleep mode or just busy-wait.
The actual time may not exactly match the desired period, but it must be at least as long as specified. Longer wait times will prolong the firmware upload, but the sensor will still work. Most of the time, this function is called with rather small values below 1000 microseconds. For wait times below the available tick resolution, consider to implement a busy-wait loop.
- Parameters
microseconds – the timespan to wait in microseconds
- Returns
CHIPINTERFACE_SUCCESS
on success
-
chipinterface_error_t chipinterface_get_time_microseconds(uint32_t *microseconds)#
- Brief
Determines the elapsed time in microseconds
In order to achieve a correct frame rate and when no interrupt is used, the elapsed time must be monitored. This function writes a monotonic increasing counter value into the output parameter
microseconds
. The timestamps may wrap around.It is enough if the underlying implementation to provide a resolution of 1 ms, but it should not be less.
- Parameters
microseconds – the current time stamp in microseconds
- Returns
CHIPINTERFACE_SUCCESS
on success
-
chipinterface_error_t chipinterface_create_i2c(uint32_t frequencyHz, uint8_t slave_address)#
- Brief
Initializes the interface for I2C communication
This function initializes the hardware interface and gets it ready for communication.
- Parameters
frequencyHz – the I2C clock frequency
slave_address – the address of the X4/X7 chip
- Returns
CHIPINTERFACE_SUCCESS
on success
-
chipinterface_error_t chipinterface_delete_i2c()#
- Brief
Deinitializes the chipinterface
This function should free up any resources acquired by
chipinterface_create_i2c()
.- Returns
CHIPINTERFACE_SUCCESS
on success
-
chipinterface_error_t chipinterface_read_i2c(uint8_t *data, int size)#
- Brief
Reads data from the sensor via I2C
This function reads data from the sensor hardware via I2C and stores to the buffer pointed to by
data
. That buffer is guaranteed to besize
bytes large. The IO configuration has been set inchipinterface_create_i2c()
.The implementation may read from the sensor in chunks.
- Parameters
data – pointer to the internal buffer
size – number of bytes to read
- Returns
CHIPINTERFACE_SUCCESS
on success
-
chipinterface_error_t chipinterface_write_i2c(const uint8_t *data, int size)#
- Brief
Writes data to the sensor via I2C
This function writes
size
bytes provided in thedata
buffer to the sensor hardware via I2C. The actual write may happen in chunks. The IO configuration has been set inchipinterface_create_i2c()
.- Parameters
data – pointer to the buffer containing the data to write
size – number of bytes to write
- Returns
CHIPINTERFACE_SUCCESS
on success
-
chipinterface_error_t chipinterface_create_spi(uint32_t frequencyHz, const chipinterface_spi_config_t *configuration)#
- Brief
Initializes the interface for SPI communication
This function initializes the hardware interface and gets it ready for communication.
- Parameters
frequencyHz – the SPI clock frequency
configuration – a pointer to a valid clock configuration object
The configuration object is a temporary argument. When needed by the chip interface implementation beyond this function call, the implementation must store an internal copy of the object.
The chip interface implementation may be tailored towards either X4 or X7 and is thus free to ignore frequencyHz and configuration entirely.
- See
chipinterface_default_x4_spi_config
,chipinterface_default_x7_spi_config
- Returns
CHIPINTERFACE_SUCCESS
on success
-
chipinterface_error_t chipinterface_delete_spi()#
- Brief
Deinitializes the chipinterface
This function should free up any resources acquired by
chipinterface_create_spi()
.- Returns
CHIPINTERFACE_SUCCESS
on success
-
chipinterface_error_t chipinterface_set_clock_frequency(uint32_t frequencyHz)#
- Brief
Sets the SPI/I2C clock frequency
This function sets the SPI/I2C clock frequency at run-time to the specified value.
This function is only needed for X7 sensors.
- Parameters
frequencyHz – the desired SPI/I2C clock frequency
- Returns
CHIPINTERFACE_SUCCESS
on success
-
chipinterface_error_t chipinterface_transfer_spi(const uint8_t *wdata, int wlength, uint8_t *rdata, int rlength)#
- Brief
Transfers data from and to the sensor via SPI.
This function writes and reads data to and from the sensor using the SPI bus. The hardware must first send
wlength
bytes and then read inrlength
bytes. So the resulting transaction on the bus iswlength
+rlength
bytes long.- Parameters
wdata – pointer to the buffer containing data to write
wlength – number of bytes to write
rdata – pointer to the buffer where incoming data should be stored
rlength – number of bytes to read
- Returns
CHIPINTERFACE_SUCCESS
on success
-
chipinterface_error_t chipinterface_get_interrupt_state(chipinterface_interrupt_state_t *state)#
- Brief
Reads the current state of the interrupt line.
- Parameters
state – Pointer to where the current state is written to
- Returns
CHIPINTERFACE_SUCCESS
on success
-
chipinterface_error_t chipinterface_wait_for_interrupt(uint32_t microseconds)#
- Brief
Waits up to
microseconds
for an interrupt
This function blocks and waits for an interrupt for
microseconds
time. If the interrupt line is already asserted, the function returns immediately. Ifmicroseconds
isCHIPINTERFACE_WAIT_FOREVER
, the function waits wait forever. While waiting, the underlying implementation may put the system into a low-power state or use busy-wait.It is enough if the underlying implementation to provide a resolution of 1 ms.
- Parameters
microseconds – The time to wait or
CHIPINTERFACE_WAIT_FOREVER
- Returns
CHIPINTERFACE_SUCCESS
on interrupts, otherwiseCHIPINTERFACE_TIMEOUT
-
chipinterface_error_t chipinterface_set_interrupt_callback(void (*callback)(void*), void *context)#
- Brief
Sets an interrupt callback function
This function sets a callback function that is called when an interrupt occurs.
This function is only needed for X7 sensors.
- Parameters
callback – The callback function
context – Pointer to a user-defined object that is passed back to the callback. Can be NULL if not used.
- Returns
CHIPINTERFACE_SUCCESS
on success, otherwiseCHIPINTERFACE_FAILURE
-
uint32_t reverse_bits(uint32_t n)#
- Brief
Reverse the bits per byte.
- Parameters
n – The 32-bit integer whose bits are to be reversed.
- Returns
The 32-bit integer with reversed bits.
-
void reverse_bits_per_byte_buffer_u32(uint32_t *buf, int numElements)#
- Brief
Reverse the bits for each individual byte in a buffer of specified length.
- Parameters
buf – Pointer to the buffer.
numElements – Number of uint32_t elements in the buffer.
-
void reverse_bits_per_byte_buffer_u8(uint8_t *buf, int numElements)#
- Brief
Reverse the bits for each individual byte in a buffer of specified length.
- Parameters
buf – Pointer to the buffer.
numElements – Number of uint8_t elements in the buffer.
- Note
This is a wrapper around reverse_bits_per_byte(uint32_t n) which operates on a single 32-bit word at a time. Thus the buffer is assumed to have a length and alignment matching that of uint32_t.