cellular.h

Go to the documentation of this file.

/*
 * Copyright (c) 2023 Bjarki Arge Andreasen
 * Copyright (c) 2023 Lucas Denefle
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_DRIVERS_CELLULAR_H_
#define ZEPHYR_INCLUDE_DRIVERS_CELLULAR_H_

 
#include <zephyr/types.h>
#include <zephyr/device.h>
#include <errno.h>
 
#ifdef __cplusplus
extern "C" {
#endif

enum cellular_access_technology {
        CELLULAR_ACCESS_TECHNOLOGY_GSM = 0,
        CELLULAR_ACCESS_TECHNOLOGY_GSM_COMPACT = 1,
        CELLULAR_ACCESS_TECHNOLOGY_UTRAN = 2,
        CELLULAR_ACCESS_TECHNOLOGY_GSM_EGPRS = 3,
        CELLULAR_ACCESS_TECHNOLOGY_UTRAN_HSDPA = 4,
        CELLULAR_ACCESS_TECHNOLOGY_UTRAN_HSUPA = 5,
        CELLULAR_ACCESS_TECHNOLOGY_UTRAN_HSDPA_HSUPA = 6,
        CELLULAR_ACCESS_TECHNOLOGY_E_UTRAN = 7,
        CELLULAR_ACCESS_TECHNOLOGY_EC_GSM_IOT = 8,
        CELLULAR_ACCESS_TECHNOLOGY_E_UTRAN_NB_S1 = 9,
        CELLULAR_ACCESS_TECHNOLOGY_E_UTRA_5G_CN = 10,
        CELLULAR_ACCESS_TECHNOLOGY_NR_5G_CN = 11,
        CELLULAR_ACCESS_TECHNOLOGY_NG_RAN = 12,
        CELLULAR_ACCESS_TECHNOLOGY_E_UTRA_NR_DUAL = 13,
        CELLULAR_ACCESS_TECHNOLOGY_E_UTRAN_NB_S1_SAT = 14,
        CELLULAR_ACCESS_TECHNOLOGY_E_UTRAN_WB_S1_SAT = 15,
        CELLULAR_ACCESS_TECHNOLOGY_NG_RAN_SAT = 16,
        CELLULAR_ACCESS_TECHNOLOGY_UNKNOWN = 255,
};

struct cellular_network {
        enum cellular_access_technology technology;
        uint16_t *bands;
        uint16_t size;
};

enum cellular_signal_type {
        CELLULAR_SIGNAL_RSSI,
        CELLULAR_SIGNAL_RSRP,
        CELLULAR_SIGNAL_RSRQ,
};

enum cellular_modem_info_type {
        CELLULAR_MODEM_INFO_IMEI,
        CELLULAR_MODEM_INFO_MODEL_ID,
        CELLULAR_MODEM_INFO_MANUFACTURER,
        CELLULAR_MODEM_INFO_FW_VERSION,
        CELLULAR_MODEM_INFO_SIM_IMSI,
        CELLULAR_MODEM_INFO_SIM_ICCID,
};

enum cellular_registration_status {
        CELLULAR_REGISTRATION_NOT_REGISTERED = 0,
        CELLULAR_REGISTRATION_REGISTERED_HOME = 1,
        CELLULAR_REGISTRATION_SEARCHING = 2,
        CELLULAR_REGISTRATION_DENIED = 3,
        CELLULAR_REGISTRATION_UNKNOWN = 4,
        CELLULAR_REGISTRATION_REGISTERED_ROAMING = 5,
        CELLULAR_REGISTRATION_SMS_ONLY_HOME = 6,
        CELLULAR_REGISTRATION_SMS_ONLY_ROAMING = 7,
        CELLULAR_REGISTRATION_EMERGENCY_ONLY = 8,
        CELLULAR_REGISTRATION_CSFB_NOT_PREFERRED_HOME = 9,
        CELLULAR_REGISTRATION_CSFB_NOT_PREFERRED_ROAMING = 10,
        CELLULAR_REGISTRATION_RLOS = 11,
};

enum cellular_event {
        CELLULAR_EVENT_MODEM_INFO_CHANGED = BIT(0),
        CELLULAR_EVENT_REGISTRATION_STATUS_CHANGED = BIT(1),
        CELLULAR_EVENT_MODEM_COMMS_CHECK_RESULT = BIT(2),
        CELLULAR_EVENT_NETWORK_STATUS_CHANGED = BIT(3),
        CELLULAR_EVENT_MODEM_SUSPENDED = BIT(4),
};
 
/* Opaque bit-mask large enough for all current & future events */
typedef uint32_t cellular_event_mask_t;

struct cellular_evt_modem_info {
        enum cellular_modem_info_type field; 
};

struct cellular_evt_registration_status {
        enum cellular_registration_status status; 
};

struct cellular_evt_modem_comms_check_result {
        bool success; 
};

#define CELLULAR_EUTRAN_CELL_ID_MAX     0xFFFFFFFU
#define CELLULAR_EUTRAN_CELL_ID_INVALID UINT32_MAX

struct cellular_evt_network_status {
        enum cellular_registration_status status; 
        enum cellular_access_technology access_tech; 
        union {
                struct {
                        uint16_t mcc; 
                        uint16_t mnc; 
                        uint32_t tac; 
                        uint32_t earfcn; 
                        uint32_t gci; 
                        uint16_t phys_cell_id; 
                        uint16_t band; 
                        int16_t rsrp; 
                        int8_t rsrq; 
                } lte; 
        } cell; 
};

struct cellular_stats {
        uint32_t outage_ms;
        uint32_t deregistrations;
        uint32_t link_drops;
        uint32_t command_failures;
        uint32_t command_errors_cme;
        uint32_t recoveries;
        uint32_t cmux_disconnects;
};

typedef void (*cellular_event_cb_t)(const struct device *dev, enum cellular_event event,
                                    const void *payload, void *user_data);


typedef int (*cellular_api_configure_networks)(const struct device *dev,
                                               const struct cellular_network *networks,
                                               uint8_t size);

typedef int (*cellular_api_get_supported_networks)(const struct device *dev,
                                                   const struct cellular_network **networks,
                                                   uint8_t *size);

typedef int (*cellular_api_get_signal)(const struct device *dev,
                                       const enum cellular_signal_type type, int16_t *value);

typedef int (*cellular_api_get_modem_info)(const struct device *dev,
                                           const enum cellular_modem_info_type type, char *info,
                                           size_t size);

typedef int (*cellular_api_get_registration_status)(const struct device *dev,
                                                    enum cellular_access_technology tech,
                                                    enum cellular_registration_status *status);

typedef int (*cellular_api_get_network_status)(const struct device *dev,
                                               struct cellular_evt_network_status *status);

typedef int (*cellular_api_set_apn)(const struct device *dev, const char *apn);

typedef int (*cellular_api_set_callback)(const struct device *dev, cellular_event_mask_t mask,
                                         cellular_event_cb_t cb, void *user_data);

typedef const struct cellular_stats *(*cellular_api_get_stats)(const struct device *dev);

__subsystem struct cellular_driver_api {
        cellular_api_configure_networks configure_networks;
        cellular_api_get_supported_networks get_supported_networks;
        cellular_api_get_signal get_signal;
        cellular_api_get_modem_info get_modem_info;
        cellular_api_get_registration_status get_registration_status;
        cellular_api_get_network_status get_network_status;
        cellular_api_set_apn set_apn;
        cellular_api_set_callback set_callback;
        cellular_api_get_stats get_stats;
};


static inline int cellular_configure_networks(const struct device *dev,
                                              const struct cellular_network *networks, uint8_t size)
{
        const struct cellular_driver_api *api = DEVICE_API_GET(cellular, dev);
 
        if (api->configure_networks == NULL) {
                return -ENOSYS;
        }
 
        return api->configure_networks(dev, networks, size);
}

static inline int cellular_get_supported_networks(const struct device *dev,
                                                  const struct cellular_network **networks,
                                                  uint8_t *size)
{
        const struct cellular_driver_api *api = DEVICE_API_GET(cellular, dev);
 
        if (api->get_supported_networks == NULL) {
                return -ENOSYS;
        }
 
        return api->get_supported_networks(dev, networks, size);
}

static inline int cellular_get_signal(const struct device *dev,
                                      const enum cellular_signal_type type, int16_t *value)
{
        const struct cellular_driver_api *api = DEVICE_API_GET(cellular, dev);
 
        if (api->get_signal == NULL) {
                return -ENOSYS;
        }
 
        return api->get_signal(dev, type, value);
}

static inline int cellular_get_modem_info(const struct device *dev,
                                          const enum cellular_modem_info_type type, char *info,
                                          size_t size)
{
        const struct cellular_driver_api *api = DEVICE_API_GET(cellular, dev);
 
        if (api->get_modem_info == NULL) {
                return -ENOSYS;
        }
 
        return api->get_modem_info(dev, type, info, size);
}

static inline int cellular_get_registration_status(const struct device *dev,
                                                   enum cellular_access_technology tech,
                                                   enum cellular_registration_status *status)
{
        const struct cellular_driver_api *api = DEVICE_API_GET(cellular, dev);
 
        if (api->get_registration_status == NULL) {
                return -ENOSYS;
        }
 
        return api->get_registration_status(dev, tech, status);
}

static inline int cellular_get_network_status(const struct device *dev,
                                              struct cellular_evt_network_status *status)
{
        const struct cellular_driver_api *api = DEVICE_API_GET(cellular, dev);
 
        if (api->get_network_status == NULL) {
                return -ENOSYS;
        }
 
        return api->get_network_status(dev, status);
}

static inline int cellular_set_apn(const struct device *dev, const char *apn)
{
        const struct cellular_driver_api *api = DEVICE_API_GET(cellular, dev);
 
        if (api->set_apn == NULL) {
                return -ENOSYS;
        }
 
        return api->set_apn(dev, apn);
}

static inline int cellular_set_callback(const struct device *dev, cellular_event_mask_t mask,
                                        cellular_event_cb_t cb, void *user_data)
{
        const struct cellular_driver_api *api = DEVICE_API_GET(cellular, dev);
 
        if (api->set_callback == NULL) {
                return -ENOSYS;
        }
 
        return api->set_callback(dev, mask, cb, user_data);
}

static inline const struct cellular_stats *cellular_get_stats(const struct device *dev)
{
        const struct cellular_driver_api *api = DEVICE_API_GET(cellular, dev);
 
        if (api->get_stats == NULL) {
                return NULL;
        }
 
        return api->get_stats(dev);
}
 
#ifdef __cplusplus
}
#endif

 
#endif /* ZEPHYR_INCLUDE_DRIVERS_CELLULAR_H_ */