sensor.h

Go to the documentation of this file.

 
/*
 * Copyright (c) 2016 Intel Corporation
 *
 * SPDX-License-Identifier: Apache-2.0
 */
#ifndef ZEPHYR_INCLUDE_DRIVERS_SENSOR_H_
#define ZEPHYR_INCLUDE_DRIVERS_SENSOR_H_
 
#include <errno.h>
#include <stdlib.h>
 
#include <zephyr/device.h>
#include <zephyr/drivers/sensor_data_types.h>
#include <zephyr/dsp/types.h>
#include <zephyr/rtio/rtio.h>
#include <zephyr/sys/iterable_sections.h>
#include <zephyr/types.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct sensor_value {
        int32_t val1;
        int32_t val2;
};
 
enum sensor_channel {
        SENSOR_CHAN_ACCEL_X,
        SENSOR_CHAN_ACCEL_Y,
        SENSOR_CHAN_ACCEL_Z,
        SENSOR_CHAN_ACCEL_XYZ,
        SENSOR_CHAN_GYRO_X,
        SENSOR_CHAN_GYRO_Y,
        SENSOR_CHAN_GYRO_Z,
        SENSOR_CHAN_GYRO_XYZ,
        SENSOR_CHAN_MAGN_X,
        SENSOR_CHAN_MAGN_Y,
        SENSOR_CHAN_MAGN_Z,
        SENSOR_CHAN_MAGN_XYZ,
        SENSOR_CHAN_DIE_TEMP,
        SENSOR_CHAN_AMBIENT_TEMP,
        SENSOR_CHAN_PRESS,
        SENSOR_CHAN_PROX,
        SENSOR_CHAN_HUMIDITY,
        SENSOR_CHAN_LIGHT,
        SENSOR_CHAN_IR,
        SENSOR_CHAN_RED,
        SENSOR_CHAN_GREEN,
        SENSOR_CHAN_BLUE,
        SENSOR_CHAN_ALTITUDE,
 
        SENSOR_CHAN_PM_1_0,
        SENSOR_CHAN_PM_2_5,
        SENSOR_CHAN_PM_10,
        SENSOR_CHAN_DISTANCE,
 
        SENSOR_CHAN_CO2,
        SENSOR_CHAN_VOC,
        SENSOR_CHAN_GAS_RES,
 
        SENSOR_CHAN_VOLTAGE,
 
        SENSOR_CHAN_VSHUNT,
 
        SENSOR_CHAN_CURRENT,
        SENSOR_CHAN_POWER,
 
        SENSOR_CHAN_RESISTANCE,
 
        SENSOR_CHAN_ROTATION,
 
        SENSOR_CHAN_POS_DX,
        SENSOR_CHAN_POS_DY,
        SENSOR_CHAN_POS_DZ,
 
        SENSOR_CHAN_RPM,
 
        SENSOR_CHAN_GAUGE_VOLTAGE,
        SENSOR_CHAN_GAUGE_AVG_CURRENT,
        SENSOR_CHAN_GAUGE_STDBY_CURRENT,
        SENSOR_CHAN_GAUGE_MAX_LOAD_CURRENT,
        SENSOR_CHAN_GAUGE_TEMP,
        SENSOR_CHAN_GAUGE_STATE_OF_CHARGE,
        SENSOR_CHAN_GAUGE_FULL_CHARGE_CAPACITY,
        SENSOR_CHAN_GAUGE_REMAINING_CHARGE_CAPACITY,
        SENSOR_CHAN_GAUGE_NOM_AVAIL_CAPACITY,
        SENSOR_CHAN_GAUGE_FULL_AVAIL_CAPACITY,
        SENSOR_CHAN_GAUGE_AVG_POWER,
        SENSOR_CHAN_GAUGE_STATE_OF_HEALTH,
        SENSOR_CHAN_GAUGE_TIME_TO_EMPTY,
        SENSOR_CHAN_GAUGE_TIME_TO_FULL,
        SENSOR_CHAN_GAUGE_CYCLE_COUNT,
        SENSOR_CHAN_GAUGE_DESIGN_VOLTAGE,
        SENSOR_CHAN_GAUGE_DESIRED_VOLTAGE,
        SENSOR_CHAN_GAUGE_DESIRED_CHARGING_CURRENT,
 
        SENSOR_CHAN_ALL,
 
        SENSOR_CHAN_COMMON_COUNT,
 
        SENSOR_CHAN_PRIV_START = SENSOR_CHAN_COMMON_COUNT,
 
        SENSOR_CHAN_MAX = INT16_MAX,
};
 
enum sensor_trigger_type {
        SENSOR_TRIG_TIMER,
        SENSOR_TRIG_DATA_READY,
        SENSOR_TRIG_DELTA,
        SENSOR_TRIG_NEAR_FAR,
        SENSOR_TRIG_THRESHOLD,
 
        SENSOR_TRIG_TAP,
 
        SENSOR_TRIG_DOUBLE_TAP,
 
        SENSOR_TRIG_FREEFALL,
 
        SENSOR_TRIG_MOTION,
 
        SENSOR_TRIG_STATIONARY,
        SENSOR_TRIG_COMMON_COUNT,
 
        SENSOR_TRIG_PRIV_START = SENSOR_TRIG_COMMON_COUNT,
 
        SENSOR_TRIG_MAX = INT16_MAX,
};
 
struct sensor_trigger {
        enum sensor_trigger_type type;
        enum sensor_channel chan;
};
 
enum sensor_attribute {
        SENSOR_ATTR_SAMPLING_FREQUENCY,
        SENSOR_ATTR_LOWER_THRESH,
        SENSOR_ATTR_UPPER_THRESH,
        SENSOR_ATTR_SLOPE_TH,
        SENSOR_ATTR_SLOPE_DUR,
        /* Hysteresis for trigger thresholds. */
        SENSOR_ATTR_HYSTERESIS,
        SENSOR_ATTR_OVERSAMPLING,
        SENSOR_ATTR_FULL_SCALE,
        SENSOR_ATTR_OFFSET,
        SENSOR_ATTR_CALIB_TARGET,
        SENSOR_ATTR_CONFIGURATION,
        SENSOR_ATTR_CALIBRATION,
        SENSOR_ATTR_FEATURE_MASK,
        SENSOR_ATTR_ALERT,
        SENSOR_ATTR_FF_DUR,
        SENSOR_ATTR_COMMON_COUNT,
 
        SENSOR_ATTR_PRIV_START = SENSOR_ATTR_COMMON_COUNT,
 
        SENSOR_ATTR_MAX = INT16_MAX,
};
 
typedef void (*sensor_trigger_handler_t)(const struct device *dev,
                                         const struct sensor_trigger *trigger);
 
typedef int (*sensor_attr_set_t)(const struct device *dev,
                                 enum sensor_channel chan,
                                 enum sensor_attribute attr,
                                 const struct sensor_value *val);
 
typedef int (*sensor_attr_get_t)(const struct device *dev,
                                 enum sensor_channel chan,
                                 enum sensor_attribute attr,
                                 struct sensor_value *val);
 
typedef int (*sensor_trigger_set_t)(const struct device *dev,
                                    const struct sensor_trigger *trig,
                                    sensor_trigger_handler_t handler);
typedef int (*sensor_sample_fetch_t)(const struct device *dev,
                                     enum sensor_channel chan);
typedef int (*sensor_channel_get_t)(const struct device *dev,
                                    enum sensor_channel chan,
                                    struct sensor_value *val);
 
struct sensor_decoder_api {
        int (*get_frame_count)(const uint8_t *buffer, enum sensor_channel channel,
                               size_t channel_idx, uint16_t *frame_count);
 
        int (*get_size_info)(enum sensor_channel channel, size_t *base_size, size_t *frame_size);
 
        int (*decode)(const uint8_t *buffer, enum sensor_channel channel, size_t channel_idx,
                      uint32_t *fit, uint16_t max_count, void *data_out);
};
 
struct sensor_decode_context {
        const struct sensor_decoder_api *decoder;
        const uint8_t *buffer;
        enum sensor_channel channel;
        size_t channel_idx;
        uint32_t fit;
};
 
#define SENSOR_DECODE_CONTEXT_INIT(decoder_, buffer_, channel_, channel_index_)                    \
        {                                                                                          \
                .decoder = (decoder_),                                                             \
                .buffer = (buffer_),                                                               \
                .channel = (channel_),                                                             \
                .channel_idx = (channel_index_),                                                   \
                .fit = 0,                                                                          \
        }
 
static inline int sensor_decode(struct sensor_decode_context *ctx, void *out, uint16_t max_count)
{
        return ctx->decoder->decode(ctx->buffer, ctx->channel, ctx->channel_idx, &ctx->fit,
                                    max_count, out);
}
 
int sensor_natively_supported_channel_size_info(enum sensor_channel channel, size_t *base_size,
                                                size_t *frame_size);
 
typedef int (*sensor_get_decoder_t)(const struct device *dev,
                                    const struct sensor_decoder_api **api);
 
/*
 * Internal data structure used to store information about the IODevice for async reading and
 * streaming sensor data.
 */
struct sensor_read_config {
        const struct device *sensor;
        enum sensor_channel *const channels;
        size_t count;
        const size_t max;
};
 
#define SENSOR_DT_READ_IODEV(name, dt_node, ...)                                                   \
        static enum sensor_channel __channel_array_##name[] = {__VA_ARGS__};                       \
        static struct sensor_read_config __sensor_read_config_##name = {                           \
                .sensor = DEVICE_DT_GET(dt_node),                                                  \
                .channels = __channel_array_##name,                                                \
                .count = ARRAY_SIZE(__channel_array_##name),                                       \
                .max = ARRAY_SIZE(__channel_array_##name),                                         \
        };                                                                                         \
        RTIO_IODEV_DEFINE(name, &__sensor_iodev_api, &__sensor_read_config_##name)
 
/* Used to submit an RTIO sqe to the sensor's iodev */
typedef int (*sensor_submit_t)(const struct device *sensor, struct rtio_iodev_sqe *sqe);
 
/* The default decoder API */
extern const struct sensor_decoder_api __sensor_default_decoder;
 
/* The default sensor iodev API */
extern const struct rtio_iodev_api __sensor_iodev_api;
 
__subsystem struct sensor_driver_api {
        sensor_attr_set_t attr_set;
        sensor_attr_get_t attr_get;
        sensor_trigger_set_t trigger_set;
        sensor_sample_fetch_t sample_fetch;
        sensor_channel_get_t channel_get;
        sensor_get_decoder_t get_decoder;
        sensor_submit_t submit;
};
 
__syscall int sensor_attr_set(const struct device *dev,
                              enum sensor_channel chan,
                              enum sensor_attribute attr,
                              const struct sensor_value *val);
 
static inline int z_impl_sensor_attr_set(const struct device *dev,
                                         enum sensor_channel chan,
                                         enum sensor_attribute attr,
                                         const struct sensor_value *val)
{
        const struct sensor_driver_api *api =
                (const struct sensor_driver_api *)dev->api;
 
        if (api->attr_set == NULL) {
                return -ENOSYS;
        }
 
        return api->attr_set(dev, chan, attr, val);
}
 
__syscall int sensor_attr_get(const struct device *dev,
                              enum sensor_channel chan,
                              enum sensor_attribute attr,
                              struct sensor_value *val);
 
static inline int z_impl_sensor_attr_get(const struct device *dev,
                                         enum sensor_channel chan,
                                         enum sensor_attribute attr,
                                         struct sensor_value *val)
{
        const struct sensor_driver_api *api =
                (const struct sensor_driver_api *)dev->api;
 
        if (api->attr_get == NULL) {
                return -ENOSYS;
        }
 
        return api->attr_get(dev, chan, attr, val);
}
 
static inline int sensor_trigger_set(const struct device *dev,
                                     const struct sensor_trigger *trig,
                                     sensor_trigger_handler_t handler)
{
        const struct sensor_driver_api *api =
                (const struct sensor_driver_api *)dev->api;
 
        if (api->trigger_set == NULL) {
                return -ENOSYS;
        }
 
        return api->trigger_set(dev, trig, handler);
}
 
__syscall int sensor_sample_fetch(const struct device *dev);
 
static inline int z_impl_sensor_sample_fetch(const struct device *dev)
{
        const struct sensor_driver_api *api =
                (const struct sensor_driver_api *)dev->api;
 
        return api->sample_fetch(dev, SENSOR_CHAN_ALL);
}
 
__syscall int sensor_sample_fetch_chan(const struct device *dev,
                                       enum sensor_channel type);
 
static inline int z_impl_sensor_sample_fetch_chan(const struct device *dev,
                                                  enum sensor_channel type)
{
        const struct sensor_driver_api *api =
                (const struct sensor_driver_api *)dev->api;
 
        return api->sample_fetch(dev, type);
}
 
__syscall int sensor_channel_get(const struct device *dev,
                                 enum sensor_channel chan,
                                 struct sensor_value *val);
 
static inline int z_impl_sensor_channel_get(const struct device *dev,
                                            enum sensor_channel chan,
                                            struct sensor_value *val)
{
        const struct sensor_driver_api *api =
                (const struct sensor_driver_api *)dev->api;
 
        return api->channel_get(dev, chan, val);
}
 
#if defined(CONFIG_SENSOR_ASYNC_API) || defined(__DOXYGEN__)
 
/*
 * Generic data structure used for encoding the sample timestamp and number of channels sampled.
 */
struct __attribute__((__packed__)) sensor_data_generic_header {
        /* The timestamp at which the data was collected from the sensor */
        uint64_t timestamp_ns;
 
        /*
         * The number of channels present in the frame. This will be the true number of elements in
         * channel_info and in the q31 values that follow the header.
         */
        uint32_t num_channels;
 
        /* Shift value for all samples in the frame */
        int8_t shift;
 
        /* This padding is needed to make sure that the 'channels' field is aligned */
        int8_t _padding[sizeof(enum sensor_channel) - 1];
 
        /* Channels present in the frame */
        enum sensor_channel channels[0];
};
 
#define SENSOR_CHANNEL_3_AXIS(chan)                                                                \
        ((chan) == SENSOR_CHAN_ACCEL_XYZ || (chan) == SENSOR_CHAN_GYRO_XYZ ||                      \
         (chan) == SENSOR_CHAN_MAGN_XYZ)
 
__syscall int sensor_get_decoder(const struct device *dev,
                                 const struct sensor_decoder_api **decoder);
 
static inline int z_impl_sensor_get_decoder(const struct device *dev,
                                            const struct sensor_decoder_api **decoder)
{
        const struct sensor_driver_api *api = (const struct sensor_driver_api *)dev->api;
 
        __ASSERT_NO_MSG(api != NULL);
 
        if (api->get_decoder == NULL) {
                *decoder = &__sensor_default_decoder;
                return 0;
        }
 
        return api->get_decoder(dev, decoder);
}
 
__syscall int sensor_reconfigure_read_iodev(struct rtio_iodev *iodev, const struct device *sensor,
                                            const enum sensor_channel *channels,
                                            size_t num_channels);
 
static inline int z_impl_sensor_reconfigure_read_iodev(struct rtio_iodev *iodev,
                                                       const struct device *sensor,
                                                       const enum sensor_channel *channels,
                                                       size_t num_channels)
{
        struct sensor_read_config *cfg = (struct sensor_read_config *)iodev->data;
 
        if (cfg->max < num_channels) {
                return -ENOMEM;
        }
 
        cfg->sensor = sensor;
        memcpy(cfg->channels, channels, num_channels * sizeof(enum sensor_channel));
        cfg->count = num_channels;
        return 0;
        return 0;
}
 
static inline int sensor_read(struct rtio_iodev *iodev, struct rtio *ctx, void *userdata)
{
        if (IS_ENABLED(CONFIG_USERSPACE)) {
                struct rtio_sqe sqe;
 
                rtio_sqe_prep_read_with_pool(&sqe, iodev, RTIO_PRIO_NORM, userdata);
                rtio_sqe_copy_in(ctx, &sqe, 1);
        } else {
                struct rtio_sqe *sqe = rtio_sqe_acquire(ctx);
 
                if (sqe == NULL) {
                        return -ENOMEM;
                }
                rtio_sqe_prep_read_with_pool(sqe, iodev, RTIO_PRIO_NORM, userdata);
        }
        rtio_submit(ctx, 0);
        return 0;
}
 
typedef void (*sensor_processing_callback_t)(int result, uint8_t *buf, uint32_t buf_len,
                                             void *userdata);
 
void sensor_processing_with_callback(struct rtio *ctx, sensor_processing_callback_t cb);
 
#endif /* defined(CONFIG_SENSOR_ASYNC_API) || defined(__DOXYGEN__) */
 
#define SENSOR_G                9806650LL
 
#define SENSOR_PI               3141592LL
 
static inline int32_t sensor_ms2_to_g(const struct sensor_value *ms2)
{
        int64_t micro_ms2 = ms2->val1 * 1000000LL + ms2->val2;
 
        if (micro_ms2 > 0) {
                return (micro_ms2 + SENSOR_G / 2) / SENSOR_G;
        } else {
                return (micro_ms2 - SENSOR_G / 2) / SENSOR_G;
        }
}
 
static inline void sensor_g_to_ms2(int32_t g, struct sensor_value *ms2)
{
        ms2->val1 = ((int64_t)g * SENSOR_G) / 1000000LL;
        ms2->val2 = ((int64_t)g * SENSOR_G) % 1000000LL;
}
 
static inline int32_t sensor_ms2_to_ug(const struct sensor_value *ms2)
{
        int64_t micro_ms2 = (ms2->val1 * INT64_C(1000000)) + ms2->val2;
 
        return (micro_ms2 * 1000000LL) / SENSOR_G;
}
 
static inline void sensor_ug_to_ms2(int32_t ug, struct sensor_value *ms2)
{
        ms2->val1 = ((int64_t)ug * SENSOR_G / 1000000LL) / 1000000LL;
        ms2->val2 = ((int64_t)ug * SENSOR_G / 1000000LL) % 1000000LL;
}
 
static inline int32_t sensor_rad_to_degrees(const struct sensor_value *rad)
{
        int64_t micro_rad_s = rad->val1 * 1000000LL + rad->val2;
 
        if (micro_rad_s > 0) {
                return (micro_rad_s * 180LL + SENSOR_PI / 2) / SENSOR_PI;
        } else {
                return (micro_rad_s * 180LL - SENSOR_PI / 2) / SENSOR_PI;
        }
}
 
static inline void sensor_degrees_to_rad(int32_t d, struct sensor_value *rad)
{
        rad->val1 = ((int64_t)d * SENSOR_PI / 180LL) / 1000000LL;
        rad->val2 = ((int64_t)d * SENSOR_PI / 180LL) % 1000000LL;
}
 
static inline int32_t sensor_rad_to_10udegrees(const struct sensor_value *rad)
{
        int64_t micro_rad_s = rad->val1 * 1000000LL + rad->val2;
 
        return (micro_rad_s * 180LL * 100000LL) / SENSOR_PI;
}
 
static inline void sensor_10udegrees_to_rad(int32_t d, struct sensor_value *rad)
{
        rad->val1 = ((int64_t)d * SENSOR_PI / 180LL / 100000LL) / 1000000LL;
        rad->val2 = ((int64_t)d * SENSOR_PI / 180LL / 100000LL) % 1000000LL;
}
 
static inline double sensor_value_to_double(const struct sensor_value *val)
{
        return (double)val->val1 + (double)val->val2 / 1000000;
}
 
static inline float sensor_value_to_float(const struct sensor_value *val)
{
        return (float)val->val1 + (float)val->val2 / 1000000;
}
 
static inline int sensor_value_from_double(struct sensor_value *val, double inp)
{
        if (inp < INT32_MIN || inp > INT32_MAX) {
                return -ERANGE;
        }
 
        double val2 = (inp - (int32_t)inp) * 1000000.0;
 
        if (val2 < INT32_MIN || val2 > INT32_MAX) {
                return -ERANGE;
        }
 
        val->val1 = (int32_t)inp;
        val->val2 = (int32_t)val2;
 
        return 0;
}
 
static inline int sensor_value_from_float(struct sensor_value *val, float inp)
{
        float val2 = (inp - (int32_t)inp) * 1000000.0f;
 
        if (val2 < INT32_MIN || val2 > (float)(INT32_MAX - 1)) {
                return -ERANGE;
        }
 
        val->val1 = (int32_t)inp;
        val->val2 = (int32_t)val2;
 
        return 0;
}
 
#ifdef CONFIG_SENSOR_INFO
 
struct sensor_info {
        const struct device *dev;
        const char *vendor;
        const char *model;
        const char *friendly_name;
};
 
#define SENSOR_INFO_INITIALIZER(_dev, _vendor, _model, _friendly_name)  \
        {                                                               \
                .dev = _dev,                                            \
                .vendor = _vendor,                                      \
                .model = _model,                                        \
                .friendly_name = _friendly_name,                        \
        }
 
#define SENSOR_INFO_DEFINE(name, ...)                                   \
        static const STRUCT_SECTION_ITERABLE(sensor_info, name) =       \
                SENSOR_INFO_INITIALIZER(__VA_ARGS__)
 
#define SENSOR_INFO_DT_NAME(node_id)                                    \
        _CONCAT(__sensor_info, DEVICE_DT_NAME_GET(node_id))
 
#define SENSOR_INFO_DT_DEFINE(node_id)                                  \
        SENSOR_INFO_DEFINE(SENSOR_INFO_DT_NAME(node_id),                \
                           DEVICE_DT_GET(node_id),                      \
                           DT_NODE_VENDOR_OR(node_id, NULL),            \
                           DT_NODE_MODEL_OR(node_id, NULL),             \
                           DT_PROP_OR(node_id, friendly_name, NULL))    \
 
#else
 
#define SENSOR_INFO_DEFINE(name, ...)
#define SENSOR_INFO_DT_DEFINE(node_id)
 
#endif /* CONFIG_SENSOR_INFO */
 
#define SENSOR_DEVICE_DT_DEFINE(node_id, init_fn, pm_device,            \
                                data_ptr, cfg_ptr, level, prio,         \
                                api_ptr, ...)                           \
        DEVICE_DT_DEFINE(node_id, init_fn, pm_device,                   \
                         data_ptr, cfg_ptr, level, prio,                \
                         api_ptr, __VA_ARGS__);                         \
                                                                        \
        SENSOR_INFO_DT_DEFINE(node_id);
 
#define SENSOR_DEVICE_DT_INST_DEFINE(inst, ...)                         \
        SENSOR_DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
 
static inline int64_t sensor_value_to_milli(const struct sensor_value *val)
{
        return ((int64_t)val->val1 * 1000) + val->val2 / 1000;
}
 
static inline int64_t sensor_value_to_micro(const struct sensor_value *val)
{
        return ((int64_t)val->val1 * 1000000) + val->val2;
}
 
#if defined(CONFIG_HAS_DTS) || defined(__DOXYGEN__)
 
#define SENSOR_DECODER_NAME() UTIL_CAT(DT_DRV_COMPAT, __decoder_api)
 
#define SENSOR_DECODER_DT_GET(node_id)                                                             \
        &UTIL_CAT(DT_STRING_TOKEN_BY_IDX(node_id, compatible, 0), __decoder_api)
 
#define SENSOR_DECODER_API_DT_DEFINE()                                                             \
        COND_CODE_1(DT_HAS_COMPAT_STATUS_OKAY(DT_DRV_COMPAT), (), (static))                        \
        const STRUCT_SECTION_ITERABLE(sensor_decoder_api, SENSOR_DECODER_NAME())
 
#define Z_MAYBE_SENSOR_DECODER_DECLARE_INTERNAL_IDX(node_id, prop, idx)                            \
        extern const struct sensor_decoder_api UTIL_CAT(                                           \
                DT_STRING_TOKEN_BY_IDX(node_id, prop, idx), __decoder_api);
 
#define Z_MAYBE_SENSOR_DECODER_DECLARE_INTERNAL(node_id)                                           \
        COND_CODE_1(DT_NODE_HAS_PROP(node_id, compatible),                                         \
                    (DT_FOREACH_PROP_ELEM(node_id, compatible,                                     \
                                          Z_MAYBE_SENSOR_DECODER_DECLARE_INTERNAL_IDX)),           \
                    ())
 
DT_FOREACH_STATUS_OKAY_NODE(Z_MAYBE_SENSOR_DECODER_DECLARE_INTERNAL)
#endif /* defined(CONFIG_HAS_DTS) || defined(__DOXYGEN__) */
 
#ifdef __cplusplus
}
#endif
 
#include <syscalls/sensor.h>
 
#endif /* ZEPHYR_INCLUDE_DRIVERS_SENSOR_H_ */