hl78xx_apis.h

Go to the documentation of this file.

/*
 * Copyright (c) 2025 Netfeasa Ltd.
 *
 * SPDX-License-Identifier: Apache-2.0
 */
#ifndef ZEPHYR_INCLUDE_DRIVERS_HL78XX_APIS_H_
#define ZEPHYR_INCLUDE_DRIVERS_HL78XX_APIS_H_
 
#include <zephyr/types.h>
#include <zephyr/device.h>
#include <errno.h>
#include <stddef.h>
#include <zephyr/modem/chat.h>
#include <zephyr/drivers/cellular.h>
 
#ifdef __cplusplus
extern "C" {
#endif


#define CSQ_RSSI_UNKNOWN         (99)
#define CESQ_RSRP_UNKNOWN        (255)
#define CESQ_RSRQ_UNKNOWN        (255)

#define CSQ_RSSI_TO_DB(v)        (-113 + (2 * (v)))
#define CESQ_RSRP_TO_DB(v)       (-140 + (v))
#define CESQ_RSRQ_TO_DB(v)       (-20 + ((v) / 2))

#define PAUSED                   1
#define ACTIVE                   0

#define MDM_MANUFACTURER_LENGTH  20
#define MDM_MODEL_LENGTH         32
#define MDM_REVISION_LENGTH      64
#define MDM_IMEI_LENGTH          16
#define MDM_IMSI_LENGTH          23
#define MDM_ICCID_LENGTH         22
#define MDM_APN_MAX_LENGTH       64
#define MDM_MAX_CERT_LENGTH      4096
#define MDM_MAX_HOSTNAME_LEN     128
#define MDM_SERIAL_NUMBER_LENGTH 32


#define HL78XX_EVT_MONITOR(name, _handler, ...)                                                    \
        static STRUCT_SECTION_ITERABLE(hl78xx_evt_monitor_entry, name) = {                         \
                .handler = _handler,                                                               \
                .next = NULL,                                                                      \
                .flags.direct = false,                                                             \
                COND_CODE_1(__VA_ARGS__, (.flags.paused = __VA_ARGS__,), ()) }

enum hl78xx_cell_rat_mode {
        HL78XX_RAT_CAT_M1 = 0,
        HL78XX_RAT_NB1,
#ifdef CONFIG_MODEM_HL78XX_12
        HL78XX_RAT_GSM,
#ifdef CONFIG_MODEM_HL78XX_12_FW_R6
        HL78XX_RAT_NBNTN,
#endif
#endif
#ifdef CONFIG_MODEM_HL78XX_AUTORAT
        HL78XX_RAT_MODE_AUTO,
#endif
        HL78XX_RAT_MODE_NONE,
        HL78XX_RAT_COUNT = HL78XX_RAT_MODE_NONE
};

enum hl78xx_phone_functionality {
        HL78XX_SIM_POWER_OFF,
        HL78XX_FULLY_FUNCTIONAL,
        HL78XX_AIRPLANE = 4,
};

enum hl78xx_module_status {
        HL78XX_MODULE_READY = 0,
        HL78XX_MODULE_WAITING_FOR_ACCESS_CODE,
        HL78XX_MODULE_SIM_NOT_PRESENT,
        HL78XX_MODULE_SIMLOCK,
        HL78XX_MODULE_UNRECOVERABLE_ERROR,
        HL78XX_MODULE_UNKNOWN_STATE,
        HL78XX_MODULE_INACTIVE_SIM
};

enum hl78xx_modem_info_type {
        HL78XX_MODEM_INFO_APN,
        HL78XX_MODEM_INFO_CURRENT_RAT,
        HL78XX_MODEM_INFO_NETWORK_OPERATOR,
        HL78XX_MODEM_INFO_SERIAL_NUMBER,
        HL78XX_MODEM_INFO_CURRENT_BAUD_RATE,
};

enum nmea_output_port {
        NMEA_OUTPUT_NONE = 0x00,
        NMEA_OUTPUT_USB_NMEA_PORT = 0x01,
        NMEA_OUTPUT_UART1 = 0x03,
        NMEA_OUTPUT_SAME_PORT = 0x04,
        NMEA_OUTPUT_CMUX_DLC1 = 0x05,
        NMEA_OUTPUT_CMUX_DLC2 = 0x06,
        NMEA_OUTPUT_CMUX_DLC3 = 0x07,
        NMEA_OUTPUT_CMUX_DLC4 = 0x08
};
 
#if defined(CONFIG_HL78XX_GNSS_SUPPORT_ASSISTED_MODE) || defined(__DOXYGEN__)
enum hl78xx_agnss_mode {
        HL78XX_AGNSS_MODE_INVALID = 0,
        HL78XX_AGNSS_MODE_VALID = 1,
};

enum hl78xx_agnss_days {
        HL78XX_AGNSS_DAYS_1 = 1,
        HL78XX_AGNSS_DAYS_2 = 2,
        HL78XX_AGNSS_DAYS_3 = 3,
        HL78XX_AGNSS_DAYS_7 = 7,
        HL78XX_AGNSS_DAYS_14 = 14,
        HL78XX_AGNSS_DAYS_28 = 28,
};

struct hl78xx_agnss_status {
        enum hl78xx_agnss_mode mode;
        uint8_t days;
        uint8_t hours;
        uint8_t minutes;
};
#endif /* CONFIG_HL78XX_GNSS_SUPPORT_ASSISTED_MODE */
 
#ifdef CONFIG_MODEM_HL78XX_LOW_POWER_MODE
#ifdef CONFIG_MODEM_HL78XX_POWER_DOWN
enum power_down_event {
        POWER_DOWN_EVENT_ENTER = 0,
        POWER_DOWN_EVENT_EXIT,
        POWER_DOWN_EVENT_NONE,
};
#endif /* CONFIG_MODEM_HL78XX_POWER_DOWN */
 
#ifdef CONFIG_MODEM_HL78XX_EDRX
enum hl78xx_edrx_event {
        HL78XX_EDRX_EVENT_IDLE_EXIT = 0,
        HL78XX_EDRX_EVENT_IDLE_ENTER,
        HL78XX_EDRX_EVENT_IDLE_NONE,
};
#endif /* CONFIG_MODEM_HL78XX_EDRX */
#ifdef CONFIG_MODEM_HL78XX_PSM
enum hl78xx_psmev_event {
        HL78XX_PSM_EVENT_EXIT = 0,
        HL78XX_PSM_EVENT_ENTER,
        HL78XX_PSM_EVENT_NONE,
};
#endif /* CONFIG_MODEM_HL78XX_PSM */
#endif /* CONFIG_MODEM_HL78XX_LOW_POWER_MODE */

struct k_cellmeas_signal_info {
        int16_t rsrp;
};

struct hl78xx_network {
        enum hl78xx_cell_rat_mode technology;
        uint16_t *bands;
        uint16_t size;
};

enum hl78xx_evt_type {
        HL78XX_LTE_RAT_UPDATE,
        HL78XX_LTE_REGISTRATION_STAT_UPDATE,
        HL78XX_LTE_SIM_REGISTRATION,
        HL78XX_LTE_MODEM_STARTUP,
        HL78XX_LTE_FOTA_UPDATE_STATUS,
#ifdef CONFIG_HL78XX_GNSS
        HL78XX_GNSS_ENGINE_READY,
        HL78XX_GNSS_EVENT_INIT,
        HL78XX_GNSS_EVENT_START,
        HL78XX_GNSS_EVENT_STOP,
        HL78XX_GNSS_EVENT_POSITION,
        HL78XX_GNSS_EVENT_START_BLOCKED,
        HL78XX_GNSS_EVENT_SEARCH_TIMEOUT,
        HL78XX_GNSS_EVENT_MODE_EXITED,
#endif /* CONFIG_HL78XX_GNSS */
#ifdef CONFIG_MODEM_HL78XX_LOW_POWER_MODE
#ifdef CONFIG_MODEM_HL78XX_EDRX
        HL78XX_EDRX_IDLE_UPDATE,
#endif /* CONFIG_MODEM_HL78XX_EDRX */
#ifdef CONFIG_MODEM_HL78XX_PSM
        HL78XX_LTE_PSMEV_UPDATE,
#endif /* CONFIG_MODEM_HL78XX_PSM */
#endif /* CONFIG_MODEM_HL78XX_LOW_POWER_MODE */
        HL78XX_CELLMEAS_UPDATE,
        HL78XX_EVT_TYPE_COUNT
};
#ifdef CONFIG_MODEM_HL78XX_AIRVANTAGE
enum wdsi_indication {
        WDSI_BOOTSTRAP_CREDENTIALS_PRESENT = 0,
        WDSI_USER_AGREEMENT_REQUEST = 1,
        WDSI_FIRMWARE_DOWNLOAD_REQUEST = 2,
        WDSI_FIRMWARE_INSTALL_REQUEST = 3,
        WDSI_AUTHENTICATION_START = 4,
        WDSI_AUTHENTICATION_FAILED = 5,
        WDSI_AUTHENTICATION_SUCCESS = 6,
        WDSI_CONNECTION_DENIED = 7,
        WDSI_DM_SESSION_CLOSED = 8,
        WDSI_FIRMWARE_AVAILABLE = 9,
        WDSI_FIRMWARE_DOWNLOADED = 10,
        WDSI_FIRMWARE_DOWNLOAD_ISSUE = 11,
        WDSI_PACKAGE_VERIFIED_CERTIFIED = 12,
        WDSI_PACKAGE_VERIFIED_NOT_CERTIFIED = 13,
        WDSI_FIRMWARE_UPDATE_START = 14,
        WDSI_FIRMWARE_UPDATE_FAILED = 15,
        WDSI_FIRMWARE_UPDATE_SUCCESS = 16,
        WDSI_DOWNLOAD_IN_PROGRESS = 18,
        WDSI_SESSION_STARTED = 23
};
#endif /* CONFIG_MODEM_HL78XX_AIRVANTAGE */
 
#ifdef CONFIG_HL78XX_GNSS
enum hl78xx_gnss_event_type {
        HL78XX_GNSSEV_INITIALISATION = 0,
        HL78XX_GNSSEV_START = 1,
        HL78XX_GNSSEV_STOP = 2,
        HL78XX_GNSSEV_POSITION = 3
};
enum hl78xx_event_status {
        HL78XX_STATUS_FAILED = 0,
        HL78XX_STATUS_SUCCESS = 1
};
enum gnss_position_events {
        GNSS_FIX_LOST_OR_UNAVAILABLE = 0,
        GNSS_ESTIMATED_POSITION_AVAILABLE = 1,
        GNSS_2D_POSITION_AVAILABLE = 2,
        GNSS_3D_POSITION_AVAILABLE = 3,
        GNSS_FIX_CHANGED_TO_INVALID = 4
};
#endif /* CONFIG_HL78XX_GNSS */

struct hl78xx_evt {
        enum hl78xx_evt_type type;

        union {
                enum cellular_registration_status reg_status;
                enum hl78xx_cell_rat_mode rat_mode;
#ifdef CONFIG_MODEM_HL78XX_AIRVANTAGE
                enum wdsi_indication wdsi_indication;
#endif /* CONFIG_MODEM_HL78XX_AIRVANTAGE */
#ifdef CONFIG_HL78XX_GNSS
                enum hl78xx_event_status event_status;
                enum gnss_position_events position_event;
#endif /* CONFIG_HL78XX_GNSS */
#ifdef CONFIG_MODEM_HL78XX_LOW_POWER_MODE
#ifdef CONFIG_MODEM_HL78XX_PSM
                /* PSM event */
                enum hl78xx_psmev_event psm_event;
#endif /* CONFIG_MODEM_HL78XX_PSM */
#ifdef CONFIG_MODEM_HL78XX_EDRX
                /* eDRX event */
                enum hl78xx_edrx_event edrx_event;
#endif /* CONFIG_MODEM_HL78XX_EDRX */
#endif /* CONFIG_MODEM_HL78XX_LOW_POWER_MODE */
                struct k_cellmeas_signal_info cellmeas;
                bool status;
                int value;
        } content;
};
 
#if defined(CONFIG_HL78XX_GNSS_AUX_DATA_PARSER) || defined(__DOXYGEN__)
struct nmea_match_gsa_data {
        int32_t fix_type;
        int64_t pdop;
        int64_t hdop;
        int64_t vdop;
};

struct nmea_match_gst_data {
        int32_t i32;
        uint32_t gst_utc;
        int64_t rms;
        int64_t sd_major;
        int64_t sd_minor;
        int64_t orient;
        int64_t lat_err;
        int64_t lon_err;
        int64_t alt_err;
};

struct nmea_match_epu_data {
        int64_t pos_3d;
        int64_t pos_2d;
        int64_t pos_lat;
        int64_t pos_lon;
        int64_t pos_alt;
        int64_t vel_3d;
        int64_t vel_2d;
        int64_t vel_hdg;
        int64_t vel_east;
        int64_t vel_north;
        int64_t vel_up;
};

struct hl78xx_gnss_nmea_aux_data {
        struct nmea_match_gsa_data gsa;
        struct nmea_match_gst_data gst;
        struct nmea_match_epu_data epu;
};

typedef void (*hl78xx_gnss_aux_data_callback_t)(const struct device *dev,
                                                const struct hl78xx_gnss_nmea_aux_data *aux_data,
                                                uint16_t size);

struct hl78xx_gnss_aux_data_callback {
        const struct device *dev;
        hl78xx_gnss_aux_data_callback_t callback;
};

#define GNSS_AUX_DATA_CALLBACK_DEFINE(_dev, _callback)                                             \
        static const STRUCT_SECTION_ITERABLE(hl78xx_gnss_aux_data_callback,                        \
                                             _hl78xx_gnss_aux_data_callback__##_callback) = {      \
                .dev = _dev,                                                                       \
                .callback = _callback,                                                             \
        }

#define GNSS_DT_AUX_DATA_CALLBACK_DEFINE(_node_id, _callback)                                      \
        static const STRUCT_SECTION_ITERABLE(hl78xx_gnss_aux_data_callback,                        \
                                             _CONCAT_4(_hl78xx_gnss_aux_data_callback_,            \
                                                       DT_DEP_ORD(_node_id), _, _callback)) = {    \
                .dev = DEVICE_DT_GET(_node_id),                                                    \
                .callback = _callback,                                                             \
        }
#else
#define GNSS_AUX_DATA_CALLBACK_DEFINE(_dev, _callback)
#define GNSS_DT_AUX_DATA_CALLBACK_DEFINE(_node_id, _callback)
#endif
typedef int (*hl78xx_api_configure_networks)(const struct device *dev,
                                             const struct hl78xx_network *networks, uint8_t size);

typedef int (*hl78xx_api_get_supported_networks)(const struct device *dev,
                                                 const struct hl78xx_network **networks,
                                                 uint8_t *size);

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

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

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

typedef int (*hl78xx_api_set_phone_functionality)(const struct device *dev,
                                                  enum hl78xx_phone_functionality functionality,
                                                  bool reset);

typedef int (*hl78xx_api_get_phone_functionality)(const struct device *dev,
                                                  enum hl78xx_phone_functionality *functionality);

typedef int (*hl78xx_api_send_at_cmd)(const struct device *dev, const char *cmd, uint16_t cmd_size,
                                      const struct modem_chat_match *response_matches,
                                      uint16_t matches_size);

struct hl78xx_evt_monitor_entry;

typedef void (*hl78xx_evt_monitor_dispatcher_t)(struct hl78xx_evt *notif);

typedef void (*hl78xx_evt_monitor_handler_t)(struct hl78xx_evt *notif,
                                             struct hl78xx_evt_monitor_entry *mon);

struct hl78xx_evt_monitor_entry {
        const hl78xx_evt_monitor_handler_t handler;
        struct hl78xx_evt_monitor_entry *next;
        struct {
                uint8_t paused: 1;
                uint8_t direct: 1;
        } flags;
};

int hl78xx_api_func_set_phone_functionality(const struct device *dev,
                                            enum hl78xx_phone_functionality functionality,
                                            bool reset);

int hl78xx_api_func_get_phone_functionality(const struct device *dev,
                                            enum hl78xx_phone_functionality *functionality);

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

int hl78xx_api_func_get_modem_info_vendor(const struct device *dev,
                                          enum hl78xx_modem_info_type type, void *info,
                                          size_t size);

int hl78xx_api_func_modem_dynamic_cmd_send(const struct device *dev, const char *cmd,
                                           uint16_t cmd_size,
                                           const struct modem_chat_match *response_matches,
                                           uint16_t matches_size);
static inline int hl78xx_get_modem_info(const struct device *dev,
                                        const enum hl78xx_modem_info_type type, void *info,
                                        size_t size)
{
        return hl78xx_api_func_get_modem_info_vendor(dev, type, info, size);
}

static inline int hl78xx_set_phone_functionality(const struct device *dev,
                                                 enum hl78xx_phone_functionality functionality,
                                                 bool reset)
{
        return hl78xx_api_func_set_phone_functionality(dev, functionality, reset);
}

static inline int hl78xx_get_phone_functionality(const struct device *dev,
                                                 enum hl78xx_phone_functionality *functionality)
{
        return hl78xx_api_func_get_phone_functionality(dev, functionality);
}

static inline int hl78xx_modem_cmd_send(const struct device *dev, const char *cmd,
                                        uint16_t cmd_size,
                                        const struct modem_chat_match *response_matches,
                                        uint16_t matches_size)
{
 
        return hl78xx_api_func_modem_dynamic_cmd_send(dev, cmd, cmd_size, response_matches,
                                                      matches_size);
}

static inline int hl78xx_parse_rssi(uint8_t rssi, int16_t *value)
{
        /* AT+CSQ returns a response +CSQ: <rssi>,<ber> where:
         * - rssi is a integer from 0 to 31 whose values describes a signal strength
         *   between -113 dBm for 0 and -51dbM for 31 or unknown for 99
         * - ber is an integer from 0 to 7 that describes the error rate, it can also
         *   be 99 for an unknown error rate
         */
        if (rssi == CSQ_RSSI_UNKNOWN) {
                return -EINVAL;
        }
 
        *value = (int16_t)CSQ_RSSI_TO_DB(rssi);
        return 0;
}

static inline int hl78xx_parse_rsrp(uint8_t rsrp, int16_t *value)
{
        /* AT+CESQ returns a response
         * +CESQ: <rxlev>,<ber>,<rscp>,<ecn0>,<rsrq>,<rsrp> where:
         * rsrq is a integer from 0 to 34 whose values describes the Reference
         * Signal Receive Quality between -20 dB for 0 and -3 dB for 34
         * (0.5 dB steps), or unknown for 255
         * rsrp is an integer from 0 to 97 that describes the Reference Signal
         * Receive Power between -140 dBm for 0 and -44 dBm for 97 (1 dBm steps),
         * or unknown for 255
         */
        if (rsrp == CESQ_RSRP_UNKNOWN) {
                return -EINVAL;
        }
 
        *value = (int16_t)CESQ_RSRP_TO_DB(rsrp);
        return 0;
}

static inline int hl78xx_parse_rsrq(uint8_t rsrq, int16_t *value)
{
        if (rsrq == CESQ_RSRQ_UNKNOWN) {
                return -EINVAL;
        }
 
        *value = (int16_t)CESQ_RSRQ_TO_DB(rsrq);
        return 0;
}

static inline void hl78xx_evt_monitor_pause(struct hl78xx_evt_monitor_entry *mon)
{
        mon->flags.paused = true;
}

static inline void hl78xx_evt_monitor_resume(struct hl78xx_evt_monitor_entry *mon)
{
        mon->flags.paused = false;
}

int hl78xx_evt_notif_handler_set(hl78xx_evt_monitor_dispatcher_t handler);

int hl78xx_evt_monitor_register(struct hl78xx_evt_monitor_entry *mon);

int hl78xx_evt_monitor_unregister(struct hl78xx_evt_monitor_entry *mon);

enum cellular_access_technology hl78xx_rat_to_access_tech(enum hl78xx_cell_rat_mode rat_mode);
#ifdef CONFIG_MODEM_HL78XX_AIRVANTAGE
int hl78xx_start_airvantage_dm_session(const struct device *dev);

int hl78xx_stop_airvantage_dm_session(const struct device *dev);
#endif /* CONFIG_MODEM_HL78XX_AIRVANTAGE */
 
#ifdef CONFIG_MODEM_HL78XX_LOW_POWER_MODE
int hl78xx_wakeup_modem(const struct device *dev);
 
#ifdef CONFIG_MODEM_HL78XX_EDRX
int hl78xx_edrx_get_time_to_sleep(const struct device *dev);
#endif /* CONFIG_MODEM_HL78XX_EDRX */
#endif /* CONFIG_MODEM_HL78XX_LOW_POWER_MODE */
 
#ifdef CONFIG_HL78XX_GNSS
int hl78xx_enter_gnss_mode(const struct device *dev);

int hl78xx_exit_gnss_mode(const struct device *dev);

int hl78xx_queue_gnss_search(const struct device *dev);

int hl78xx_gnss_set_nmea_output(const struct device *dev, enum nmea_output_port port);

int hl78xx_gnss_set_search_timeout(const struct device *dev, uint32_t timeout_ms);

int hl78xx_gnss_get_latest_known_fix(const struct device *dev);
 
#ifdef CONFIG_HL78XX_GNSS_SUPPORT_ASSISTED_MODE
int hl78xx_gnss_assist_data_get_status(const struct device *dev,
                                       struct hl78xx_agnss_status *status);

int hl78xx_gnss_assist_data_download(const struct device *dev, enum hl78xx_agnss_days days);

int hl78xx_gnss_assist_data_delete(const struct device *dev);
#endif /* CONFIG_HL78XX_GNSS_SUPPORT_ASSISTED_MODE */
 
#endif /* CONFIG_HL78XX_GNSS */
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_DRIVERS_HL78XX_APIS_H_ */