X4 Sensor Lib API#

file: novelda_x4sensor.h

The X4Sensor C API interfaces a stand-alone detection algorithm running on the X4 hardware sensor to a bare metal host application. It takes care of the low-level communication with the sensor.

The application life-cycle is as follows:

Initialize the library and the sensor with x4sensor_initialize_i2c() or x4sensor_initialize_spi().
Optionally configure the library with x4sensor_set_range_cm() and x4sensor_set_sensitivity_level().
Start the sensor operation

The sensor can operate in the following modes:

Normal operation mode:
- started by x4sensor_start_normal_mode()
- reports detections via a GPIO pin
- optimized for power consumption
Event mode:
- an event-based operation mode where the host is notified in case of a subscribed event.
- started by x4sensor_start_event_mode()
- reports events by asserting a GPIO pin
- frame data must be read out via x4sensor_get_sensor_data()
Recording mode:
- reads out internal data from the hardware sensor and is used for tests and validation.
- started by x4sensor_start_recording_mode()
- reports a new frame by asserting a GPIO pin
- frame data must be read out via x4sensor_get_sensor_data()
The sensor may be stopped by calling x4sensor_stop().

type x4sensor_error_t#

Brief: Error codes used in the X4Sensor API

static const x4sensor_error_t X4SENSOR_SUCCESS#: The function call was successful

static const x4sensor_error_t X4SENSOR_FAILURE#: An unspecified error happened

static const x4sensor_error_t X4SENSOR_CONFIGURATION_INVALID_SIZE#: The blob size is wrong

static const x4sensor_error_t X4SENSOR_CONFIGURATION_INVALID_DATA#: Blob data corrupted

static const x4sensor_error_t X4SENSOR_CONFIGURATION_INVALID_TYPE#: Blob seems valid but has wrong type

static const x4sensor_error_t X4SENSOR_CONFIGURATION_INVALID_LAYOUT#: Blob data format is not compatible to this x4sensor build

static const x4sensor_error_t X4SENSOR_FIRMWARE_INCOMPATIBLE_INTERFACE_VERSION#: The X4 firmware interface is not compatible to this version of x4sensor lib.

static const x4sensor_error_t X4SENSOR_FIRMWARE_VERIFICATION_FAILED#: An error happened while verifying the firmware. Check the hardware connection.

static const x4sensor_error_t X4SENSOR_CHIPINTERFACE_ERROR#: An error happened in a call to a chipinterface function

static const x4sensor_error_t X4SENSOR_SENSOR_DISCOVERY_FAILED#: Initial contact to the sensor failed, most likely a connection problem

static const x4sensor_error_t X4SENSOR_INVALID_PARAMETER#: A function was called with one or more invalid parameter values

static const x4sensor_error_t X4SENSOR_NOT_ALLOWED#: A function was called while it was not allowed

static const x4sensor_error_t X4SENSOR_OSCILLATOR_FREQUENCY_NOT_PLAUSIBLE#: The measured X4 oscillator frequency is outside the plausible range

static const x4sensor_error_t X4SENSOR_FEATURE_NOT_SUPPORTED#: The feature is not configured/supported

static const x4sensor_error_t X4SENSOR_FRAME_COUNTER_NOT_INCREASED#: The frame counter not increased

static const x4sensor_error_t X4SENSOR_DATA_NOT_READY#: The sensor data is not ready to be read

enum x4sensor_event_flag_t#

Brief: A single event flag

The event mode is started by x4sensor_start_event_mode().

enumerator X4SENSOR_EVENT_PERIODIC_REPORT = 1#: Enables periodic reports from the sensor. Can be used for keep-alive checks of the sensor hardware or just for periodic updates of the host. The report interval is configured with x4sensor_set_periodic_report_interval().

enumerator X4SENSOR_EVENT_STATE_CHANGE = 2#: Enables notifications when the detetion state changes. Depending on the algorithm configuration this may be the proximity or occupancy state.

type x4sensor_event_flags_t#

Brief: A combination of x4sensor_event_flag_t event flags

enum x4_test_mode_t#

Brief: Various test modes used in x4sensor_start_test_mode().

struct x4sensor_info_t#

Brief: Meta information about the sensor and the firmware

uint32_t sample_id#: The hardware sensor’s serial number

uint8_t chip_revision#: The hardware sensor’s revision id

uint16_t algorithm_version[3]#: Major, minor and patch number of the algorithm version

uint32_t firmware_version#: A firmware version identifier, little endian

uint32_t algorithm_commit_hash#: Identifies the algorithm version, little endian

uint32_t algorithm_variant_hash#: Identifies the algorithm variant, little endian

struct x4sensor_distance_cluster_t#

Brief: A window of detection power values

A distance cluster contains the signal power values per range bin around the first detector hit. A detector hit occurs when the processed radar signal exceeds the configured sensitivity threshold at a certain range bin.

The distance cluster starts one range bin before the first hit and ends multiple bins later. The actual length of the distance cluster is preconfigured by the algorithm and can be obtained from x4sensor_get_distance_cluster_length().

The x4sensor_distance_cluster_t.first_detection_bin_distance_mm member is the distance from the sensor to the range bin with the detection hit. That is the second entry in the cluster.

See: x4sensor_set_sensitivity_level(), x4sensor_get_distance_cluster_length()

bool detector_hit#: True if the cluster has power values above the threshold

uint16_t first_detection_bin_distance_mm#: Distance in mm to first bin above the threshold

uint32_t bin_power[X4SENSOR_DISTANCE_CLUSTER_MAX_LENGTH]#: Signal power per range bin

x4sensor_error_t x4sensor_set_retry_count(uint8_t retry_count)#

Brief: Set number of retransmition attemts

This function sets up the number of times the communication will be retried before the read/write function returns error. Default value of 5 is used if user doesn’t set otherwise.

Parameters

retry_count – a value of retry number

Returns

X4SENSOR_SUCCESS on success, otherwise an error code

uint8_t x4sensor_get_retry_count(void)#

Brief: Get number of retransmition attemts

This function returns the number of times the communication will be retried before the read/write function returns error.

Returns: number of retry attempts

uint32_t x4sensor_get_retries_total_count(void)#

Brief: Get a total number of retransmition attemts made

This function returns the total number of retries that has been made since X4 sensor initialization.

Returns: number of retries made

x4sensor_error_t x4sensor_initialize_i2c(const uint8_t *configuration, size_t configuration_size)#

Brief: Initializes and sets up the X4Sensor library for I2C communication

This function sets up the low-level chip interface and prepares the hardware sensor for operation. It is the first function to be called.

Parameters

configuration – a pointer to the configuration binary blob
configuration_size – the configuration size

Returns

X4SENSOR_SUCCESS on success, otherwise an error code

x4sensor_error_t x4sensor_initialize_spi(const uint8_t *configuration, size_t configuration_size)#

Brief: Initializes and sets up the X4Sensor library for SPI communication

This function sets up the low-level chip interface and prepares the hardware sensor for operation. It is the first function to be called.

Parameters

configuration – a pointer to the configuration binary blob
configuration_size – the configuration size

Returns

X4SENSOR_SUCCESS on success, otherwise an error code

x4sensor_error_t x4sensor_deinitialize()#

Brief: Frees up all resources used by X4Sensor

This function may be called when the X4Sensor is no longer needed. After that, one might start over again with x4sensor_initialize_i2c() or x4sensor_initialize_spi(). This function may be called at any time, even without stopping the sensor.

Returns: X4SENSOR_SUCCESS on success, otherwise an error code

const x4sensor_info_t *x4sensor_get_info()#

Brief: Shows meta information about the sensor and the firmware

This function returns a pointer to a struct with meta information about the sensor and its firmware. It may be called at any time after initializing the X4Sensor library.

Returns: X4SENSOR_SUCCESS on success, otherwise an error code

uint16_t x4sensor_get_range_cm()#

Brief: Returns the configured detection range

The value returned may differ from desired range inputted to x4sensor_set_range_cm() function. If no range has been configured, a default value is returned.

See: x4sensor_set_range_cm()
Returns: detection range in centimeters

uint8_t x4sensor_get_sensitivity_level()#

Brief: Returns the configured sensitivity level

If no sensitivity has been configured, a default value is returned.

Returns: sensitivity level
See: x4sensor_set_sensitivity_level()

uint8_t x4sensor_get_frame_rate()#

Brief: Returns the sensor frame rate
Returns: frame rate in frames per second

x4sensor_error_t x4sensor_set_range_cm(uint16_t centimeters)#

Brief: Sets the maximum detection range

This function allows the user to set the maximum detection range of the sensor. Since the radar sensor divides the detection zone in range bins, the observed range might not match the configured value exactly.

This function may be called after initialization and while the sensor is stopped.

Parameters

centimeters – the desired maximum detection range in centimeters

Returns

X4SENSOR_SUCCESS on success, otherwise an error code

x4sensor_error_t x4sensor_set_sensitivity_level(uint8_t level)#

Brief: Sets the sensitivity level

The sensitivity level configures the sensitivity of the sensor. Each firmware comes with a set of sensitivity thresholds. The meaning of the different levels depends on the actual firmware. A higher value means usually “more sensitive.” The maximum value depends on the actual firmware and algorithm and can be obtained from the release documentation.

This function may be called after initialization and while the sensor is stopped.

Parameters

level – a value greater than 0

Returns

X4SENSOR_SUCCESS on success, otherwise an error code

x4sensor_error_t x4sensor_set_periodic_report_interval(uint16_t frames)#

Brief: Sets the interval length of periodic sensor reports

This function sets the interval length of periodic sensor reports. The interval length is specified in number of frames. This option is only effective when the sensor is started in event mode with x4sensor_event_flag_t.X4SENSOR_EVENT_PERIODIC_REPORT subscribed.

This function may be called after initialization and while the sensor is stopped.

Parameters

frames – the interval length in frames

Returns

X4SENSOR_SUCCESS on success, otherwise an error code

See

x4sensor_get_frame_rate(), x4sensor_start_event_mode()

uint16_t x4sensor_get_periodic_report_interval()#

Brief: Gets the interval length of periodic sensor reports

This function gets the interval length of periodic sensor reports.

This function may be called while the sensor is running.

Returns: interval length in frames
See: x4sensor_set_periodic_report_interval(), x4sensor_start_event_mode()

x4sensor_error_t x4sensor_start_normal_mode()#

Brief: Starts the hardware sensor in normal operation mode

This function starts the sensor in normal operation mode and returns. The hardware sensor runs autonomously and reports detections by asserting an IO pin. Operation can be stopped using x4sensor_stop().

Returns: X4SENSOR_SUCCESS on success, otherwise an error code

x4sensor_error_t x4sensor_start_event_mode(x4sensor_event_flags_t events)#

Brief: Starts the hardware sensor in event mode

This function starts the sensor in event mode and returns. Several events may be subscribed by specifying a combination of event flags.

When a subscribed event occurs, the hardware sensor reports it by asserting the interrupt line. The frame data must then be read out using x4sensor_get_sensor_data() before the sensor is ready to acquire the next frame. The time between interrupt and reading out the frame data must be kept as short as possible.

The implementation of interrupt handling is left to the integrator. It is for instance possible to use the chipinterface_wait_for_interrupt() function in chipinterface.

Parameters

events – a combination of event flags

Returns

X4SENSOR_SUCCESS on success, otherwise an error code

x4sensor_error_t x4sensor_start_recording_mode()#

Brief: Starts the hardware sensor in recording mode

This function starts the sensor in recording mode and returns. The hardware sensor reports each frame by asserting the interrupt line. The frame data must then be read out using x4sensor_get_sensor_data() before the sensor acquires the next frame. The time between interrupt and reading out the frame data must be kept as short as possible.

The implementation of interrupt handling is left to the integrator. It is for instance possible to use the chipinterface_wait_for_interrupt() function in chipinterface.

Returns: X4SENSOR_SUCCESS on success, otherwise an error code

x4sensor_error_t x4sensor_stop()#

Brief: Stops the current sensor operation

This function stops the sensor and brings it into a power-down state. After calling this function, the sensor may be reconfigured and can be started again.

Returns: X4SENSOR_SUCCESS on success, otherwise an error code

size_t x4sensor_get_max_sensor_data_size_recording_mode()#

Brief: Returns the maximum buffer size needed for the frame in recording mode

This function returns the estimated maximum buffer size needed for the call of x4sensor_get_sensor_data() so that the application can preallocate sufficient space. The utilized size may be less than that.

Returns: the maximum sensor data buffer size.

size_t x4sensor_get_max_sensor_data_size_event_mode()#

Brief: Returns the maximum buffer size needed for the frame in event mode

Returns: the maximum sensor data buffer size.

size_t x4sensor_get_sensor_data(uint8_t *buffer, size_t max_size)#

Brief: Reads out frame data and prepares the next sensor interval

This function reads out frame data and prepares the next sensor interval. The frame data contains presence information and can be queried with x4sensor_get_detection().

Call this function after obtaining an interrupt in event mode or in recording mode. Do not call it in normal operation mode.

Make sure to preallocate enough space in buffer. In event mode, the maximum buffer size can be predicted with x4sensor_get_max_sensor_data_size_event_mode() or in recording mode with x4sensor_get_max_sensor_data_size_recording(), respectively.

Parameters

buffer – a pointer to the destination memory
max_size – the maximum size of buffer

Returns

the number of bytes written to buffer

x4sensor_error_t x4sensor_get_last_error()#

Brief: Returns the error code of the last function call

Most X4Sensor functions return an error code of type x4sensor_error_t. Some functions return other values for convenience but may still produce an error. This function allows the user to retrieve the error that happened in the last function call regardless of which function was called.

Returns: the error code of the last function call

const char *x4sensor_convert_error_to_string(x4sensor_error_t error)#

Brief: Converts an a error code into a human-readable string

This function converts a x4sensor_error_t error code into a human-readable C string. It is a convenience function that should be used with care. Calling it will have a significant impact on the code size and is only recommended if code size is not top priority.

Param: error the error code
Returns: a C string with more information about the error

x4sensor_error_t x4sensor_start_test_mode(x4_test_mode_t test_mode)#

Brief: Starts the hardware sensor in regulatory test mode

This function starts the sensor in test mode and returns. In case of x4_test_mode_t.X4_TEST_MODE_M1 and x4_test_mode_t.X4_TEST_MODE_M2 mode the hardware sensor emits continuously and no further action is needed. In other test modes sensor behaves like in recording mode (see x4sensor_start_recording_mode()). x4sensor_stop() has to be called before starting another test mode.

Parameters

test_mode – a test mode index

Returns

X4SENSOR_SUCCESS on success, otherwise an error code

x4sensor_event_flags_t x4sensor_get_events(const uint8_t *buffer)#

Brief: Extracts event flags from the frame data buffer

This function returns the event flags that caused the sensor to report data. Events are subscribed to by x4sensor_start_event_mode().

Parameters

buffer – data fetched by x4sensor_get_sensor_data()

Returns

the flags that caused the sensor to report data

uint32_t x4sensor_get_frame_counter(const uint8_t *buffer)#

Brief: Extracts frame counter from the frame data buffer

This function returns the frame counter from the data buffer. The frame counter is incremented for each processed frame.

Parameters

buffer – data fetched by x4sensor_get_sensor_data()

Returns

value of the frame counter

bool x4sensor_get_detection_state(const uint8_t *buffer)#

Brief

Extracts the detection state from a sensor data buffer

Parameters

buffer – data fetched by x4sensor_get_sensor_data()

Returns

true in case of proximity or occupancy depending on the algorithm, otherwise false

x4sensor_error_t x4sensor_get_distance_cluster(const uint8_t *buffer, x4sensor_distance_cluster_t *distance_cluster)#

Brief

Extracts distance cluster data from sensor data buffer

Parameters

buffer – data fetched by x4sensor_get_sensor_data()
distance_cluster – pointer to where the cluster data is written to

Returns

X4SENSOR_SUCCESS on success, otherwise an error code

uint8_t x4sensor_get_distance_cluster_length()#

Brief: Returns the number of range bins in a distance cluster

The number of range bins is fixed and cannot be changed.

Returns: number of range bins in a distance cluster

uint8_t x4sensor_get_distance_cluster_first_bin_number(const uint8_t *buffer)#

Brief

Returns the number of the first bin in a distance cluster

Parameters

buffer – data fetched by x4sensor_get_sensor_data()

Returns

bin index to the first bin in a distance cluster

uint16_t x4sensor_get_distance_between_bins_mm()#

Brief: Returns the distance between adjacent range bins in mm

The X4Sensor radar divides the detection zone into range bins with a certain length. This length is fixed and cannot be changed.

Returns: The distance between adjacent range bins in mm