Sensor Manager API

The sensor manager API manages the sensors that are enabled in an application. The API allows a sensor device to register itself with the sensor manager and an application to look up the sensors that are enabled. The sensor manager maintains a list of sensors, each represented by a struct sensor object defined in the the Sensor API.

Registering Sensors

When the BSP or the sensor creator package creates a sensor device in the kernel, via the os_dev_create() function, the sensor device init function must initialize a struct sensor object and call the sensor_mgr_register() function to register itself with the sensor manager.

Looking Up Sensors

An application uses the sensor manager API to look up the struct sensor object for a sensor. The sensor API and the sensor listener API perform operations on a sensor object. The sensor manager API provides the following sensor lookup functions:

• sensor_mgr_find_next_bytype(): This function returns the next sensor, on the sensors list, whose configured sensor types match one of the specified sensor types to search for. The sensor types to search are specified as a bit mask. You can use the function to search for the first sensor that matches or to iterate through the list and search for all sensors that match. If you are iterating through the list to find the next match, you must call the sensor_mgr_lock() function to lock the sensors list before you start the iteration and call the sensor_mgr_unlock() unlock the list when you are done. You do not need to lock the sensor list if you use the function to find the first match because the sensor_mgr_find_next_bytype() locks the sensors list before the search.

• sensor_mgr_find_next_bydevname(): This function returns the sensor that matches the specified device name.

  Note: There should only be one sensor that matches a specified device name even though the function name suggests that there can be multiple sensors with the same device name.

Checking Configured Sensor Types

An application may configure a sensor device to only support a subset of supported sensor types. The sensor_mgr_match_bytype() function allows an application to check whether a sensor is configured for one of the specified sensor types. The type to check is a bit mask and can include multiple types. The function returns a match when there is a match for one, not all, of the specified types in the bit mask.

Polling Sensors

The sensor manager implements a poller that reads sensor data from sensors at specified poll rates. If an application configures a sensor to be polled, using the sensor_set_poll_rate_ms() function defined in the sensor API, the sensor manager poller will poll and read the configured sensor data from the sensor at the specified interval.

The sensor manager poller uses an OS callout to set up a timer event to poll the sensors, and uses the default OS event queue and the OS main task to process timer events. The SENSOR_MGR_WAKEUP_RATE syscfg setting specifies the default wakeup rate the sensor manager poller wakes up to poll sensors. The sensor manager poller uses the poll rate for a sensor if the sensor is configured for a higher poll rate than the SENSOR_MGR_WAKEUP_RATE setting value.

Note: An application needs to register a sensor listener to receive the sensor data that the sensor manager poller reads from a sensor.

Data Structures

The sensor manager API uses the struct sensor and sensor_type_t types.

API

typedef int (*sensor_mgr_compare_func_t)(struct sensor*, void*)

int sensor_mgr_lock(void)

Lock sensor manager to access the list of sensors.

void sensor_mgr_unlock(void)

Unlock sensor manager once the list of sensors has been accessed.

int sensor_mgr_register(struct sensor *sensor)

Register the sensor with the global sensor list.

This makes the sensor searchable by other packages, who may want to look it up by type.

Parameters:

• sensor – The sensor to register

Returns:

0 on success, non-zero error code on failure.

struct os_eventq *sensor_mgr_evq_get(void)

Get the current eventq, the system is misconfigured if there is still no parent eventq.

Returns:

Ptr OS eventq that the sensor mgr is set to

struct sensor *sensor_mgr_find_next(sensor_mgr_compare_func_t, void*, struct sensor*)

The sensor manager contains a list of sensors, this function returns the next sensor in that list, for which compare_func() returns successful (one).

If prev_cursor is provided, the function starts at that point in the sensor list.

@warn This function MUST be locked by sensor_mgr_lock/unlock() if the goal is to iterate through sensors (as opposed to just finding one.) As the “prev_cursor” may be resorted in the sensor list, in between calls.

Parameters:

• compare_func – The comparison function to use against sensors in the list.

• arg – The argument to provide to that comparison function

• prev_cursor – The previous sensor in the sensor manager list, in case of iteration. If desire is to find first matching sensor, provide a NULL value.

Returns:

A pointer to the first sensor found from prev_cursor, or NULL, if none found.

struct sensor *sensor_mgr_find_next_bytype(sensor_type_t type, struct sensor *sensor)

Find the “next” sensor available for a given sensor type.

If the sensor parameter, is present find the next entry from that parameter. Otherwise, find the first matching sensor.

Parameters:

• type – The type of sensor to search for

• sensor – The cursor to search from, or NULL to start from the beginning.

Returns:

A pointer to the sensor object matching that sensor type, or NULL if none found.

struct sensor *sensor_mgr_find_next_bydevname(const char *devname, struct sensor *prev_cursor)

Search the sensor list and find the next sensor that corresponds to a given device name.

Parameters:

• devname – The device name to search for

• sensor – The previous sensor found with this device name

Returns:

0 on success, non-zero error code on failure

int sensor_mgr_match_bytype(struct sensor *sensor, void*)

Check if sensor type matches.

Parameters:

• sensor – The sensor object

• arg – type to check

Returns:

1 if matches, 0 if it doesn’t match.

int sensor_set_poll_rate_ms(const char *devname, uint32_t poll_rate)

Set the sensor poll rate.

Parameters:

• devname – Name of the sensor

• poll_rate – The poll rate in milli seconds

int sensor_set_n_poll_rate(const char *devname, struct sensor_type_traits *stt)

Set the sensor poll rate multiple based on the device name, sensor type.

Parameters:

• devname – Name of the sensor

• stt – The sensor type trait

int sensor_oic_tx_trigger(struct sensor *sensor, void *arg, sensor_type_t type)

Transmit OIC trigger.

Parameters:

• sensor – Ptr to the sensor

• arg – Ptr to sensor data

• type – The sensor type

Returns:

0 on sucess, non-zero on failure

void sensor_trigger_init(struct sensor *sensor, sensor_type_t type, sensor_trigger_notify_func_t notify)

Sensor trigger initialization.

Parameters:

• sensor – Ptr to the sensor

• type – Sensor type to enable trigger for

• notify – the function to call if the trigger condition is satisfied

struct sensor_type_traits *sensor_get_type_traits_bytype(sensor_type_t type, struct sensor *sensor)

Search the sensor type traits list for specific type of sensor.

Parameters:

• type – The sensor type to search for

• sensor – Ptr to a sensor

Returns:

NULL when no sensor type is found, ptr to sensor_type_traits structure when found

struct sensor *sensor_get_type_traits_byname(const char*, struct sensor_type_traits**, sensor_type_t)

Get the type traits for a sensor.

Parameters:

• devname – Name of the sensor

• stt – Ptr to sensor types trait struct

• type – The sensor type

Returns:

NULL on failure, sensor struct on success

int sensor_set_thresh(const char *devname, struct sensor_type_traits *stt)

Set the thresholds along with the comparison algo for a sensor.

Parameters:

• devname – Name of the sensor

• stt – Ptr to sensor type traits containing thresholds

Returns:

0 on success, non-zero on failure

int sensor_clear_low_thresh(const char *devname, sensor_type_t type)

Clears the low threshold for a sensor.

Parameters:

• devname – Name of the sensor

• type – The sensor type

Returns:

0 on success, non-zero on failure

int sensor_clear_high_thresh(const char *devname, sensor_type_t type)

Clears the high threshold for a sensor.

Parameters:

• devname – Name of the sensor

• type – The sensor type

Returns:

0 on success, non-zero on failure

void sensor_mgr_put_notify_evt(struct sensor_notify_ev_ctx *ctx, sensor_event_type_t evtype)

Puts a notification event on the sensor manager evq.

Parameters:

• ctx – Notification event context

• evtype – The notification event type

void sensor_mgr_put_interrupt_evt(struct sensor *sensor)

Puts a interrupt event on the sensor manager evq.

Parameters:

• sensor – Sensor Ptr as interrupt event context

void sensor_mgr_put_read_evt(void *arg)

Puts read event on the sensor manager evq.

Parameters:

• arg – Argument

int sensor_reset(struct sensor *sensor)

Resets the sensor.

Parameters:

• Ptr – to sensor

char *sensor_ftostr(float, char*, int)

Convinience API to convert floats to strings, might loose some precision due to rounding.

Parameters:

• num – Floating point number to print

• fltstr – Output float string

• len – Length of the string to print

int sensor_shell_register(void)

API to register sensor shell.

void sensor_oic_init(void)

Iterates through the sensor list and initializes OIC resources based on each sensor type.