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.

See: chipinterface_wait_us(), chipinterface_wait_for_interrupt()

static const uint32_t CHIPINTERFACE_WAIT_FOREVER#

Represents an infinite wait time.

See: chipinterface_wait_us(), chipinterface_wait_for_interrupt()

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

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

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.

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.

See: chipinterface_default_x4_spi_config, chipinterface_default_x7_spi_config

chipinterface_polarity_t clock_polarity#: Clock polarity

chipinterface_phase_t clock_phase#: Clock phase

chipinterface_bitorder_t bit_order#: Bit order

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 be size bytes large. The IO configuration has been set in chipinterface_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 the data buffer to the sensor hardware via I2C. The actual write may happen in chunks. The IO configuration has been set in chipinterface_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 in rlength bytes. So the resulting transaction on the bus is wlength + 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. If microseconds is CHIPINTERFACE_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, otherwise CHIPINTERFACE_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, otherwise CHIPINTERFACE_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.