Sensors

The Sensors API provides a unified interface for discovering, configuring, and retrieving data from various hardware sensors in Ocre containers. It supports multiple sensor types and channels, allowing applications to interact with environmental, motion, and position sensing capabilities.

Header File

To use the Sensors API in your application, include the ocre_api.h header from the Atym Toolchain, and link the ocre-sdk library when building your application.

#include "ocre_api.h"

Container Permissions

When using the sensors API in your application, make sure to include the ocre_sensors permission in your build.yaml configuration file. This enables build-time validation to ensure your application only uses the sensor functions you've declared.

config:
  permissions:
    - ocre_sensors

Execution Environment

Container applications shall use ocre_process_events() function to process their sensor events. This is usually done in a loop, similar to following:

    // Main event loop - process events continuously
    while (1) {
        ocre_process_events();
    }

Types

Sensor Handle

A type that represents a sensor device identifier.

typedef int32_t ocre_sensor_handle_t;

Sensor Channels

An enumeration of the different types of sensor channels available.

typedef enum {
    SENSOR_CHANNEL_ACCELERATION,
    SENSOR_CHANNEL_GYRO,
    SENSOR_CHANNEL_MAGNETIC_FIELD,
    SENSOR_CHANNEL_LIGHT,
    SENSOR_CHANNEL_PRESSURE,
    SENSOR_CHANNEL_PROXIMITY,
    SENSOR_CHANNEL_HUMIDITY,
    SENSOR_CHANNEL_TEMPERATURE,
    // Add more channels as needed
} sensor_channel_t;

Sensor Instance

A structure representing a sensor instance with its channels.

typedef struct ocre_sensor_t {
    ocre_sensor_handle_t handle; ///< Sensor handle
    char *sensor_name;           ///< Name of the sensor
    int num_channels;            ///< Number of supported channels
    sensor_channel_t channels[]; ///< Supported channels
} ocre_sensor_t;

Methods

Initialize Sensors

Initializes the sensor subsystem.

int ocre_sensors_init(void);

Returns:

Value	Description
`0`	Initialization successful
negative value	Error code

Discover Sensors

Discovers available sensors on the device.

int ocre_sensors_discover(void);

Returns:

Value	Description
positive value	Number of sensors discovered
negative value	Error code

Open Sensor

Opens a sensor by handle for reading.

int ocre_sensors_open(ocre_sensor_handle_t handle);

Parameters:

Name	Type	Description
`handle`	ocre_sensor_handle_t	Sensor handle

Returns:

Value	Description
`0`	Sensor opened successfully
negative value	Error code

Open Sensor by Name

Opens a sensor by name for reading.

int ocre_sensors_open_by_name(const char *name);

Parameters:

Name	Type	Description
`name`	const char*	Name of the sensor

Returns:

Value	Description
`OCRE_SUCCESS`	Sensor opened successfully
negative value	Error code

Get Sensor Handle

Gets the handle for a sensor by ID.

int ocre_sensors_get_handle(int sensor_id);

Parameters:

Name	Type	Description
`sensor_id`	int	Sensor ID

Returns:

Value	Description
positive value	Sensor handle
negative value	Error code

Get Sensor Handle by Name

Gets the handle for a sensor by name.

int ocre_sensors_get_handle_by_name(const char *name);

Parameters:

Name	Type	Description
`name`	const char*	Name of the sensor

Returns:

Value	Description
positive value	Sensor handle
negative value	Error code

Get Channel Count

Gets the number of channels for a sensor by ID.

int ocre_sensors_get_channel_count(int sensor_id);

Parameters:

Name	Type	Description
`sensor_id`	int	Sensor ID

Returns:

Value	Description
positive value	Number of channels
negative value	Error code

Get Channel Count by Name

Gets the number of channels for a sensor by name.

int ocre_sensors_get_channel_count_by_name(const char *sensor_name);

Parameters:

Name	Type	Description
`sensor_name`	const char*	Name of the sensor

Returns:

Value	Description
positive value	Number of channels
negative value	Error code

Get Channel Type

Gets the channel type for a specific channel index.

int ocre_sensors_get_channel_type(int sensor_id, int channel_index);

Parameters:

Name	Type	Description
`sensor_id`	int	Sensor ID
`channel_index`	int	Channel index

Returns:

Value	Description
positive value	Channel type from sensor_channel_t enum
negative value	Error code

Get Channel Type by Name

Gets the channel type for a specific channel index by sensor name.

int ocre_sensors_get_channel_type_by_name(const char *sensor_name, int channel_index);

Parameters:

Name	Type	Description
`sensor_name`	const char*	Name of the sensor
`channel_index`	int	Channel index

Returns:

Value	Description
positive value	Channel type from sensor_channel_t enum
negative value	Error code

Read Sensor

Reads data from a sensor channel.

double ocre_sensors_read(int sensor_id, int channel_type);

Parameters:

Name	Type	Description
`sensor_id`	int	Sensor ID
`channel_type`	int	Channel type to read (from sensor_channel_t enum)

Returns:

Value	Description
sensor value	Sensor reading as double
negative value	Error code

Read Sensor by Name

Reads data from a sensor channel by sensor name.

double ocre_sensors_read_by_name(const char *sensor_name, int channel_type);

Parameters:

Name	Type	Description
`sensor_name`	const char*	Name of the sensor
`channel_type`	int	Channel type to read (from sensor_channel_t enum)

Returns:

Value	Description
sensor value	Sensor reading as double
negative value	Error code

Reference

Function	Description	Parameters	Return Value	Error Conditions
`ocre_sensors_init`	Initializes the sensor subsystem	None	`0`: Success Negative: Error	System initialization failure
`ocre_sensors_discover`	Discovers available sensors	None	Positive: Number found Negative: Error	No sensors available Discovery failure
`ocre_sensors_open`	Opens a sensor by handle	`handle`: Sensor handle	`0`: Success Negative: Error	Invalid handle Sensor already open
`ocre_sensors_open_by_name`	Opens a sensor by name	`name`: Sensor name	`OCRE_SUCCESS`: Success Negative: Error	Invalid name Sensor not found
`ocre_sensors_get_handle`	Gets handle by sensor ID	`sensor_id`: Sensor ID	Positive: Handle Negative: Error	Invalid sensor ID
`ocre_sensors_get_handle_by_name`	Gets handle by sensor name	`name`: Sensor name	Positive: Handle Negative: Error	Sensor name not found
`ocre_sensors_get_channel_count`	Gets number of channels by ID	`sensor_id`: Sensor ID	Positive: Channel count Negative: Error	Invalid sensor ID
`ocre_sensors_get_channel_count_by_name`	Gets number of channels by name	`sensor_name`: Sensor name	Positive: Channel count Negative: Error	Sensor name not found
`ocre_sensors_get_channel_type`	Gets channel type by ID	`sensor_id`: Sensor ID `channel_index`: Channel index	Positive: Channel type Negative: Error	Invalid sensor ID Invalid channel index
`ocre_sensors_get_channel_type_by_name`	Gets channel type by name	`sensor_name`: Sensor name `channel_index`: Channel index	Positive: Channel type Negative: Error	Sensor name not found Invalid channel index
`ocre_sensors_read`	Reads sensor data by ID	`sensor_id`: Sensor ID `channel_type`: Channel type	Sensor value (double) Negative: Error	Invalid sensor ID Invalid channel type Read failure
`ocre_sensors_read_by_name`	Reads sensor data by name	`sensor_name`: Sensor name `channel_type`: Channel type	Sensor value (double) Negative: Error	Sensor name not found Invalid channel type Read failure

Header File​

Execution Environment​

Types​

Sensor Handle​

Sensor Channels​

Sensor Instance​

Methods​

Initialize Sensors​

Discover Sensors​

Open Sensor​

Open Sensor by Name​

Get Sensor Handle​

Get Sensor Handle by Name​

Get Channel Count​

Get Channel Count by Name​

Get Channel Type​

Get Channel Type by Name​

Read Sensor​

Read Sensor by Name​

Reference​

Header File

Execution Environment

Types

Sensor Handle

Sensor Channels

Sensor Instance

Methods

Initialize Sensors

Discover Sensors

Open Sensor

Open Sensor by Name

Get Sensor Handle

Get Sensor Handle by Name

Get Channel Count

Get Channel Count by Name

Get Channel Type

Get Channel Type by Name

Read Sensor

Read Sensor by Name

Reference