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
 
/* Magic constants */
#define CSQ_RSSI_UNKNOWN        (99)
#define CESQ_RSRP_UNKNOWN       (255)
#define CESQ_RSRQ_UNKNOWN       (255)
/* Magic numbers to units conversions */
#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 {
        /* <APN> Access Point Name */
        HL78XX_MODEM_INFO_APN,
        /* <Current RAT> */
        HL78XX_MODEM_INFO_CURRENT_RAT,
        /* <Network Operator> */
        HL78XX_MODEM_INFO_NETWORK_OPERATOR,
        /* <Serial Number> */
        HL78XX_MODEM_INFO_SERIAL_NUMBER,
};

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_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 */
 
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 */
                bool status;
                int value;
        } content;
};

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_apn)(const struct device *dev, const char *apn, uint16_t size);

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; /* forward declaration */
/* Event monitor dispatcher */
typedef void (*hl78xx_evt_monitor_dispatcher_t)(struct hl78xx_evt *notif);
/* Event monitor handler */
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;
        /* link for runtime list */
        struct hl78xx_evt_monitor_entry *next;
        struct {
                uint8_t paused: 1; /* Monitor is paused. */
                uint8_t direct: 1; /* Dispatch in ISR. */
        } 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 __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_DRIVERS_HL78XX_APIS_H_ */