Header file for extended cellular API of HL78xx modems. More...

#include <zephyr/types.h>
#include <zephyr/device.h>
#include <zephyr/kernel.h>
#include <errno.h>
#include <stddef.h>
#include <stdint.h>
#include <time.h>
#include <zephyr/drivers/cellular.h>
#include <zephyr/sys/util_macro.h>

Data Structures
struct	kselacq_syntax
	KSELACQ RAT configuration syntax. More...
struct	hl78xx_cxreg_status
	Cached +CEREG/+CREG registration details. More...
struct	hl78xx_network_operator
	Cached network operator information. More...
struct	hl78xx_network_info
	Cached network information. More...
struct	hl78xx_agnss_status
	A-GNSS assistance data status structure. More...
struct	k_cellmeas_signal_info
	Cellular measurement signal information. More...
struct	hl78xx_network
	Cellular network structure. More...
struct	hl78xx_ctzeu_update
	Parsed +CTZEU update payload. More...
struct	hl78xx_evt
	HL78xx event structure. More...
struct	nmea_match_gsa_data
	Parsed GSA sentence data (GNSS DOP and Active Satellites). More...
struct	nmea_match_gst_data
	Parsed GST sentence data (GNSS Pseudorange Error Statistics). More...
struct	nmea_match_epu_data
	Parsed EPU sentence data (HL78xx proprietary position error). More...
struct	hl78xx_gnss_nmea_aux_data
	Container for all GNSS auxiliary NMEA data. More...
struct	hl78xx_gnss_aux_data_callback
	GNSS auxiliary data callback structure. More...
struct	hl78xx_at_notification
	Parsed unsolicited AT notification payload. More...
struct	hl78xx_at_monitor_entry
	AT monitor entry structure. More...
struct	hl78xx_evt_monitor_entry
	Event monitor entry structure. More...

Macros
#define	CSQ_RSSI_UNKNOWN (99)
	Unknown RSSI value returned by AT+CSQ command.
#define	CSQ_RSSI_MAX (31)
	Maximum valid RSSI code returned by AT+CSQ command.
#define	CESQ_RSRP_UNKNOWN (255)
	Unknown RSRP value returned by AT+CESQ command.
#define	CESQ_RSRP_MAX (97)
	Maximum valid RSRP code returned by AT+CESQ command.
#define	CESQ_RSRQ_UNKNOWN (255)
	Unknown RSRQ value returned by AT+CESQ command.
#define	CESQ_RSRQ_MAX (34)
	Maximum valid RSRQ code returned by AT+CESQ command.
#define	HL78XX_MODEM_AT_ERROR 1
	Modem response type for generic ERROR responses returned by public AT helpers.
#define	HL78XX_MODEM_AT_CME_ERROR 2
	Modem response type for +CME ERROR responses returned by public AT helpers.
#define	HL78XX_MODEM_AT_CMS_ERROR 3
	Modem response type for +CMS ERROR responses returned by public AT helpers.
#define	CSQ_RSSI_TO_DB(v)
	Convert CSQ RSSI value to dBm.
#define	CESQ_RSRP_TO_DB(v)
	Convert CESQ RSRP value to dBm.
#define	CESQ_RSRQ_TO_DB(v)
	Convert CESQ RSRQ value to dB.
#define	PAUSED 1
	Monitor is paused.
#define	ACTIVE 0
	Monitor is active, default.
#define	MDM_MANUFACTURER_LENGTH 20
	Maximum length of modem manufacturer string.
#define	MDM_MODEL_LENGTH 32
	Maximum length of modem model string.
#define	MDM_REVISION_LENGTH 64
	Maximum length of modem revision string.
#define	MDM_IMEI_LENGTH 16
	Maximum length of modem IMEI string.
#define	MDM_IMSI_LENGTH 23
	Maximum length of modem IMSI string.
#define	MDM_ICCID_LENGTH 22
	Maximum length of modem ICCID string.
#define	MDM_APN_MAX_LENGTH 64
	Maximum length of APN string.
#define	MDM_MAX_CERT_LENGTH 4096
	Maximum length of certificate.
#define	MDM_MAX_HOSTNAME_LEN 128
	Maximum length of hostname.
#define	MDM_SERIAL_NUMBER_LENGTH 32
	Maximum length of serial number string.
#define	HL78XX_CTZEU_UTIME_MAX_LEN 32
	Recommended buffer size for extracted +CTZEU universal time strings.
#define	HL78XX_CEREG_TIMER_STR_LEN 9
	Maximum length of CEREG timer string.
#define	HL78XX_NETWORK_ADDRESS_MAX_LEN 46
	Maximum length of network address string.
#define	MDM_HL78XX_EOF_PATTERN "--EOF--Pattern--"
	Pattern used to indicate end-of-file or completion of data transmission.
#define	MDM_HL78XX_TERMINATION_PATTERN "+++"
	Escape/termination sequence used to exit data mode and return to command mode.
#define	MDM_HL78XX_CONNECT_STRING "CONNECT"
	Response string indicating a successful data connection has been established.
#define	MDM_HL78XX_NO_CARRIER_STRING "NO CARRIER"
	Response string indicating the connection has been lost or terminated.
#define	MDM_HL78XX_CME_ERROR_STRING "+CME ERROR: "
	Prefix for CME (Mobile Equipment) error responses, typically followed by an error code.
#define	MDM_HL78XX_CMS_ERROR_STRING "+CMS ERROR: "
	Prefix for CMS (Message Service) error responses, typically related to SMS operations.
#define	MDM_HL78XX_ERROR_STRING "ERROR"
	Generic error response string indicating command failure.
#define	MDM_HL78XX_OK_STRING "OK"
	Standard response string indicating successful execution of an AT command.
#define	HL78XX_MONITOR_ACTIVE false
	Initial active state for HL78xx monitors.
#define	HL78XX_MONITOR_PAUSED true
	Initial paused state for HL78xx monitors.
#define	HL78XX_MONITOR_INITIAL_PAUSED(...)
	Resolve the optional monitor initial state argument.
#define	HL78XX_EVT_MONITOR(name, _handler, ...)
	Define an Event monitor to receive notifications in the system workqueue thread.
#define	HL78XX_AT_MONITOR_ANY NULL
	Monitor any parsed unsolicited AT notification.
#define	HL78XX_AT_MONITOR(name, _filter, _handler, ...)
	Define an AT monitor to receive parsed unsolicited AT notifications in the system workqueue thread.
#define	HL78XX_AT_MONITOR_DIRECT(name, _filter, _handler, ...)
	Define an AT monitor to receive parsed unsolicited AT notifications directly in the HL78xx modem RX workqueue context.
#define	GNSS_AUX_DATA_CALLBACK_DEFINE(_dev, _callback)
	Register a callback structure for GNSS auxiliary data published.
#define	GNSS_DT_AUX_DATA_CALLBACK_DEFINE(_node_id, _callback)
	Register a callback structure for GNSS auxiliary data published.

Typedefs
typedef bool(*	hl78xx_runtime_band_provider_t) (const struct device dev, enum hl78xx_cell_rat_mode rat, uint16_t band, void *user_data)
	Callback used to supply an optional runtime band override for a RAT.
typedef void(*	hl78xx_gnss_aux_data_callback_t) (const struct device dev, const struct hl78xx_gnss_nmea_aux_data aux_data, uint16_t size)
	GNSS auxiliary data callback function type.
typedef int(*	hl78xx_api_configure_networks) (const struct device dev, const struct hl78xx_network networks, uint8_t size)
	API function pointer for configuring networks.
typedef int(*	hl78xx_api_get_supported_networks) (const struct device dev, const struct hl78xx_network networks, uint8_t size)
	API function pointer for getting supported networks.
typedef int(*	hl78xx_api_get_signal) (const struct device dev, const enum cellular_signal_type type, int16_t value)
	API for getting network signal strength.
typedef int(*	hl78xx_api_get_modem_info) (const struct device dev, const enum cellular_modem_info_type type, char info, size_t size)
	API function pointer for getting modem information.
typedef int(*	hl78xx_api_get_registration_status) (const struct device dev, enum cellular_access_technology tech, enum cellular_registration_status status)
	API for getting registration status.
typedef int(*	hl78xx_api_set_phone_functionality) (const struct device *dev, enum hl78xx_phone_functionality functionality, bool reset)
	API function pointer for setting phone functionality.
typedef int(*	hl78xx_api_get_phone_functionality) (const struct device dev, enum hl78xx_phone_functionality functionality)
	API for get phone 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)
	API for get phone functionality.
typedef void(*	hl78xx_at_monitor_handler_t) (const struct hl78xx_at_notification notif, struct hl78xx_at_monitor_entry mon)
	AT monitor handler function type.
typedef void(*	hl78xx_at_monitor_release_t) (struct hl78xx_at_monitor_entry *mon)
	AT monitor release function type.
typedef void(*	hl78xx_evt_monitor_dispatcher_t) (struct hl78xx_evt *notif)
	Event monitor dispatcher function type.
typedef void(*	hl78xx_evt_monitor_handler_t) (struct hl78xx_evt notif, struct hl78xx_evt_monitor_entry mon)
	Event monitor handler function type.
typedef void(*	hl78xx_evt_monitor_release_t) (struct hl78xx_evt_monitor_entry *mon)
	Event monitor release function type.

Enumerations
enum	hl78xx_cell_rat_mode { HL78XX_RAT_CAT_M1 = 0 , HL78XX_RAT_NB1 , HL78XX_RAT_MODE_NONE , HL78XX_RAT_COUNT = HL78XX_RAT_MODE_NONE }
	Cellular radio access technologies. More...
enum	hl78xx_kselacq_rat { HL78XX_KSELACQ_RAT_CLEAR = 0 , HL78XX_KSELACQ_RAT_CAT_M1 = 1 , HL78XX_KSELACQ_RAT_NB1 = 2 , HL78XX_KSELACQ_RAT_GSM = 3 }
	Raw AT+KSELACQ PRL RAT entries. More...
enum	hl78xx_phone_functionality { HL78XX_SIM_POWER_OFF , HL78XX_FULLY_FUNCTIONAL , HL78XX_AIRPLANE = 4 }
	Phone functionality modes. More...
enum	hl78xx_sim_slot { HL78XX_SIM_SLOT_1 = 0 , HL78XX_SIM_SLOT_2 = 1 }
	External SIM slot selection driven by the optional SIM-switch GPIO. More...
enum	hl78xx_modem_restart_mode { HL78XX_MODEM_RESTART_HARD = 0 , HL78XX_MODEM_RESTART_SOFT }
	Driver-managed modem restart modes. More...
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 }
	Module status codes. More...
enum	hl78xx_modem_info_type { HL78XX_MODEM_INFO_SERIAL_NUMBER , HL78XX_MODEM_INFO_CURRENT_BAUD_RATE }
	Cellular modem info type. More...
enum	hl78xx_operator_format { HL78XX_OPERATOR_FORMAT_LONG_ALPHANUMERIC = 0 , HL78XX_OPERATOR_FORMAT_SHORT_ALPHANUMERIC , HL78XX_OPERATOR_FORMAT_NUMERIC }
	Network operator format options. More...
enum	hl78xx_network_info_type { HL78XX_NETWORK_INFO_APN , HL78XX_NETWORK_INFO_CURRENT_RAT , HL78XX_NETWORK_INFO_NETWORK_OPERATOR_LONG_ALPHA , HL78XX_NETWORK_INFO_NETWORK_OPERATOR_SHORT_ALPHA , HL78XX_NETWORK_INFO_NETWORK_OPERATOR_NUMERIC , HL78XX_NETWORK_INFO_OPERATOR_FORMAT , HL78XX_NETWORK_INFO_TAC , HL78XX_NETWORK_INFO_MCC , HL78XX_NETWORK_INFO_MNC , HL78XX_NETWORK_INFO_CELL_ID , HL78XX_NETWORK_INFO_IP_ADDRESS , HL78XX_NETWORK_INFO_DNS_PRIMARY , HL78XX_NETWORK_INFO_ACTIVE_BAND , HL78XX_NETWORK_INFO_SINR }
	Cached network information types. More...
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 }
	NMEA output port options. More...
enum	hl78xx_agnss_mode { HL78XX_AGNSS_MODE_INVALID = 0 , HL78XX_AGNSS_MODE_VALID = 1 }
	A-GNSS assistance data validity mode. More...
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 }
	Number of days of predicted assistance data to download (write command) or number of days before it expires (read command). More...
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 , HL78XX_LTE_DNS_READY , HL78XX_LTE_AT_CMD_READY , HL78XX_LTE_PHONE_FUNCTIONALITY_UPDATE , HL78XX_LTE_CTZEU_UPDATE , HL78XX_CELLMEAS_UPDATE , HL78XX_EVT_TYPE_COUNT }
	HL78xx event types. More...

Functions
int	hl78xx_api_func_set_phone_functionality (const struct device *dev, enum hl78xx_phone_functionality functionality, bool reset)
	Set phone functionality mode (internal implementation).
int	hl78xx_api_func_restart (const struct device *dev, enum hl78xx_modem_restart_mode mode)
	Request a driver-managed modem restart.
int	hl78xx_api_func_get_phone_functionality (const struct device dev, enum hl78xx_phone_functionality functionality)
	Get phone functionality mode (internal implementation).
int	hl78xx_api_func_get_signal (const struct device dev, const enum cellular_signal_type type, int16_t value)
	Get network signal strength (internal implementation).
int	hl78xx_api_func_get_modem_info (const struct device dev, enum hl78xx_modem_info_type type, void info, size_t size)
	Get vendor-specific modem information (internal implementation).
int	hl78xx_api_func_get_modem_info_standard (const struct device dev, enum cellular_modem_info_type type, char info, size_t size)
	Get standard (Zephyr cellular API) modem information from cache.
int	hl78xx_api_func_get_network_info (const struct device dev, enum hl78xx_network_info_type type, void info, size_t size)
	Get cached vendor-specific network information.
int	hl78xx_api_func_get_rsrp_validity (const struct device dev, bool is_valid)
	Check whether the current RSRP meets the configured minimum threshold.
int	hl78xx_api_func_get_rsrq_validity (const struct device dev, bool is_valid)
	Check whether the current RSRQ meets the configured minimum threshold.
int	hl78xx_api_func_get_sinr_validity (const struct device dev, bool is_valid)
	Check whether the current SINR meets the configured minimum threshold.
int	hl78xx_api_func_set_network_operator_format (const struct device *dev, enum hl78xx_operator_format format)
	Set the +COPS network operator format.
int	hl78xx_set_runtime_band_provider (const struct device dev, hl78xx_runtime_band_provider_t provider, void user_data)
	Register or clear a runtime band provider for the driver.
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)
	Send dynamic AT command (internal implementation).
int	hl78xx_modem_at_send (const struct device dev, const char cmd)
	Send a pre-formatted AT command to the modem.
int	hl78xx_modem_at_cmd (const struct device dev, char response, size_t response_size, const char *cmd)
	Send a pre-formatted AT command and copy the whole modem response into a caller-supplied buffer.
static int	hl78xx_get_modem_info (const struct device dev, const enum hl78xx_modem_info_type type, void info, size_t size)
	Get modem info for the device.
static int	hl78xx_get_network_info (const struct device dev, enum hl78xx_network_info_type type, void info, size_t size)
	Get cached network info for the device.
static int	hl78xx_get_rsrp_validity (const struct device dev, bool is_valid)
	Check whether the current RSRP meets the configured threshold.
static int	hl78xx_get_rsrq_validity (const struct device dev, bool is_valid)
	Check whether the current RSRQ meets the configured threshold.
static int	hl78xx_get_sinr_validity (const struct device dev, bool is_valid)
	Check whether the current SINR meets the configured threshold.
static int	hl78xx_set_phone_functionality (const struct device *dev, enum hl78xx_phone_functionality functionality, bool reset)
	Set the modem phone functionality mode.
static int	hl78xx_restart_modem (const struct device *dev, enum hl78xx_modem_restart_mode mode)
	Request a driver-managed modem restart.
static int	hl78xx_get_phone_functionality (const struct device dev, enum hl78xx_phone_functionality functionality)
	Get the current phone functionality mode of the modem.
static 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)
	Send an AT command to the modem and wait for a matched response.
static int	hl78xx_modem_at_err_type (int error)
	Return the modem error type encoded in hl78xx_modem_at_send/cmd return values.
static int	hl78xx_modem_at_err (int error)
	Return the modem CME/CMS error code encoded in hl78xx_modem_at_send/cmd.
static int	hl78xx_parse_rssi (uint8_t rssi, int16_t *value)
	Convert raw RSSI value from the modem to dBm.
static int	hl78xx_parse_rsrp (uint8_t rsrp, int16_t *value)
	Convert raw RSRP value from the modem to dBm.
static int	hl78xx_parse_rsrq (uint8_t rsrq, int16_t *value)
	Convert raw RSRQ value from the modem to dB.
static void	hl78xx_evt_monitor_pause (struct hl78xx_evt_monitor_entry *mon)
	Pause monitor.
static void	hl78xx_evt_monitor_resume (struct hl78xx_evt_monitor_entry *mon)
	Resume monitor.
static void	hl78xx_at_monitor_pause (struct hl78xx_at_monitor_entry *mon)
	Pause AT monitor.
static void	hl78xx_at_monitor_resume (struct hl78xx_at_monitor_entry *mon)
	Resume AT monitor.
int	hl78xx_at_monitor_register (struct hl78xx_at_monitor_entry *mon)
	Register an AT monitor.
int	hl78xx_at_monitor_unregister (struct hl78xx_at_monitor_entry *mon)
	Unregister an AT monitor.
int	hl78xx_evt_notif_handler_set (hl78xx_evt_monitor_dispatcher_t handler)
	Set the event notification handler for HL78xx modem events.
int	hl78xx_evt_monitor_register (struct hl78xx_evt_monitor_entry *mon)
	Register an event monitor.
int	hl78xx_evt_monitor_unregister (struct hl78xx_evt_monitor_entry *mon)
	Unregister an event monitor.
enum cellular_access_technology	hl78xx_rat_to_access_tech (enum hl78xx_cell_rat_mode rat_mode)
	Convert HL78xx RAT mode to standard cellular API.
enum hl78xx_cell_rat_mode	hl78xx_access_tech_to_rat (enum cellular_access_technology access_tech)
	Convert standard cellular access technology to HL78xx RAT mode.
int	hl78xx_set_wake_pin_low (const struct device *dev)
	Drive the modem WAKE pin low.
int	hl78xx_set_wake_pin_high (const struct device *dev)
	Drive the modem WAKE pin high.
int	hl78xx_set_active_sim (const struct device *dev, enum hl78xx_sim_slot sim_slot)
	Select the active external SIM slot.

Detailed Description

Header file for extended cellular API of HL78xx modems.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description