hl78xx_apis.h File Reference

#include <zephyr/types.h>
#include <zephyr/device.h>
#include <errno.h>
#include <stddef.h>
#include <zephyr/modem/chat.h>
#include <zephyr/drivers/cellular.h>
#include <zephyr/sys/util_macro.h>

Go to the source code of this file.

Data Structures
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_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	CESQ_RSRP_UNKNOWN   (255)
	Unknown RSRP value returned by AT+CESQ command.
#define	CESQ_RSRQ_UNKNOWN   (255)
	Unknown RSRQ value returned by AT+CESQ command.
#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_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 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_phone_functionality { HL78XX_SIM_POWER_OFF , HL78XX_FULLY_FUNCTIONAL , HL78XX_AIRPLANE = 4 }
	Phone functionality 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_APN , HL78XX_MODEM_INFO_CURRENT_RAT , HL78XX_MODEM_INFO_NETWORK_OPERATOR , HL78XX_MODEM_INFO_SERIAL_NUMBER ,   HL78XX_MODEM_INFO_CURRENT_BAUD_RATE }
	Cellular modem info type. 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_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_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_vendor (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_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).
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_set_phone_functionality (const struct device *dev, enum hl78xx_phone_functionality functionality, bool reset)
	Set the modem phone functionality mode.
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_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.

Macro Definition Documentation

GNSS_AUX_DATA_CALLBACK_DEFINE

#define GNSS_AUX_DATA_CALLBACK_DEFINE	(		_dev,
			_callback )

Value:

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

Register a callback structure for GNSS auxiliary data published.

Parameters

_dev	Device pointer
_callback	The callback function

GNSS_DT_AUX_DATA_CALLBACK_DEFINE

#define GNSS_DT_AUX_DATA_CALLBACK_DEFINE	(		_node_id,
			_callback )

Value:

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,                                                             \
}

Register a callback structure for GNSS auxiliary data published.

Parameters

_node_id	Device tree node identifier
_callback	The callback function

HL78XX_AT_MONITOR

#define HL78XX_AT_MONITOR	(		name,
			_filter,
			_handler,
			... )

Value:

static STRUCT_SECTION_ITERABLE(hl78xx_at_monitor_entry, name) = {                          \
        .filter = _filter,                                                                 \
        .handler = _handler,                                                               \
        .next = NULL,                                                                      \
        .flags = {                                                                         \
                .direct = false,                                                           \
                .paused = HL78XX_MONITOR_INITIAL_PAUSED(__VA_ARGS__),                      \
        }}

Define an AT monitor to receive parsed unsolicited AT notifications in the system workqueue thread.

Parameters

name	The monitor name.
_filter	Exact unsolicited AT match pattern to receive, or HL78XX_AT_MONITOR_ANY to receive all parsed notifications.
_handler	The monitor callback.
...	Optional monitor initial state (HL78XX_MONITOR_ACTIVE or HL78XX_MONITOR_PAUSED). The default initial state of a monitor is active.

HL78XX_AT_MONITOR_ANY

#define HL78XX_AT_MONITOR_ANY   NULL

Monitor any parsed unsolicited AT notification.

HL78XX_AT_MONITOR_DIRECT

#define HL78XX_AT_MONITOR_DIRECT	(		name,
			_filter,
			_handler,
			... )

Value:

static STRUCT_SECTION_ITERABLE(hl78xx_at_monitor_entry, name) = {                          \
        .filter = _filter,                                                                 \
        .handler = _handler,                                                               \
        .next = NULL,                                                                      \
        .flags = {                                                                         \
                .direct = true,                                                            \
                .paused = HL78XX_MONITOR_INITIAL_PAUSED(__VA_ARGS__),                      \
        }}

Define an AT monitor to receive parsed unsolicited AT notifications directly in the HL78xx modem RX workqueue context.

Direct monitor callbacks run in the HL78xx modem RX workqueue context. Handlers should keep processing short and must avoid operations that could block modem receive processing for a long time.

Parameters

name	The monitor name.
_filter	Exact unsolicited AT match pattern to receive, or HL78XX_AT_MONITOR_ANY to receive all parsed notifications.
_handler	The monitor callback.
...	Optional monitor initial state (HL78XX_MONITOR_ACTIVE or HL78XX_MONITOR_PAUSED). The default initial state of a monitor is active.

HL78XX_EVT_MONITOR

#define HL78XX_EVT_MONITOR	(		name,
			_handler,
			... )

Value:

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

Define an Event monitor to receive notifications in the system workqueue thread.

Parameters

name	The monitor name.
_handler	The monitor callback.
...	Optional monitor initial state (HL78XX_MONITOR_ACTIVE or HL78XX_MONITOR_PAUSED). The default initial state of a monitor is active.

HL78XX_MONITOR_ACTIVE

#define HL78XX_MONITOR_ACTIVE   false

Initial active state for HL78xx monitors.

Use this as the optional state argument when defining a monitor that should start in the active state.

HL78XX_MONITOR_INITIAL_PAUSED

#define HL78XX_MONITOR_INITIAL_PAUSED

(

...

)

Value:

COND_CODE_1(IS_EMPTY(__VA_ARGS__), (false), (__VA_ARGS__))

Resolve the optional monitor initial state argument.

If no optional state argument is provided, the monitor starts active. Otherwise, the provided state value is used.

Parameters

...	Optional monitor initial state, either HL78XX_MONITOR_ACTIVE or HL78XX_MONITOR_PAUSED.

HL78XX_MONITOR_PAUSED

#define HL78XX_MONITOR_PAUSED   true

Initial paused state for HL78xx monitors.

Use this as the optional state argument when defining a monitor that should start paused.

Typedef Documentation

hl78xx_api_configure_networks

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

API function pointer for configuring networks.

Parameters

dev	Cellular network device instance
networks	Array of network configurations
size	Number of networks in array

Returns

0 on success, negative errno on failure

hl78xx_api_get_modem_info

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.

Parameters

dev	Cellular network device instance
type	Type of modem information
info	Buffer to store information string
size	Size of info buffer

Returns

0 on success, negative errno on failure

hl78xx_api_get_phone_functionality

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

API for get phone functionality.

hl78xx_api_get_registration_status

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.

hl78xx_api_get_signal

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.

hl78xx_api_get_supported_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.

Parameters

dev	Cellular network device instance
networks	Pointer to receive network array
size	Pointer to receive array size

Returns

0 on success, negative errno on failure

hl78xx_api_send_at_cmd

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.

hl78xx_api_set_phone_functionality

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.

Parameters

dev	Cellular network device instance
functionality	Phone functionality mode
reset	Whether to reset modem

Returns

0 on success, negative errno on failure

hl78xx_at_monitor_handler_t

typedef void(* hl78xx_at_monitor_handler_t) (const struct hl78xx_at_notification *notif, struct hl78xx_at_monitor_entry *mon)

AT monitor handler function type.

User callback for receiving parsed unsolicited AT notifications.

Parameters

notif	Pointer to the parsed AT notification.
mon	Pointer to the monitor entry that received the notification.

hl78xx_at_monitor_release_t

typedef void(* hl78xx_at_monitor_release_t) (struct hl78xx_at_monitor_entry *mon)

AT monitor release function type.

Called when an AT monitor entry is released and no longer referenced.

Parameters

mon	Pointer to the monitor entry being released.

hl78xx_evt_monitor_dispatcher_t

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

Event monitor dispatcher function type.

Called to dispatch events to registered monitors

Parameters

notif

Pointer to the event notification

hl78xx_evt_monitor_handler_t

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

Event monitor handler function type.

User callback for receiving event notifications

Parameters

notif	Pointer to the event notification
mon	Pointer to the monitor entry that received the event

hl78xx_evt_monitor_release_t

typedef void(* hl78xx_evt_monitor_release_t) (struct hl78xx_evt_monitor_entry *mon)

Event monitor release function type.

Called when an event monitor entry is released and no longer referenced.

Parameters

mon	Pointer to the monitor entry being released

hl78xx_gnss_aux_data_callback_t

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.

Parameters

dev	Pointer to the GNSS device
aux_data	Pointer to auxiliary NMEA data structure
size	Size of the auxiliary data

Enumeration Type Documentation

hl78xx_agnss_days

enum hl78xx_agnss_days

Number of days of predicted assistance data to download (write command) or number of days before it expires (read command).

Only these values are accepted by the AT+GNSSAD=1,<days> command

Enumerator
HL78XX_AGNSS_DAYS_1	Request 1 day of A-GNSS assistance data.
HL78XX_AGNSS_DAYS_2	Request 2 days of A-GNSS assistance data.
HL78XX_AGNSS_DAYS_3	Request 3 days of A-GNSS assistance data.
HL78XX_AGNSS_DAYS_7	Request 7 days of A-GNSS assistance data.
HL78XX_AGNSS_DAYS_14	Request 14 days of A-GNSS assistance data.
HL78XX_AGNSS_DAYS_28	Request 28 days of A-GNSS assistance data.

hl78xx_agnss_mode

enum hl78xx_agnss_mode

A-GNSS assistance data validity mode.

Mode value returned by AT+GNSSAD? read command or used by write command

Enumerator
HL78XX_AGNSS_MODE_INVALID	Data is not valid (read) / Delete data (write).
HL78XX_AGNSS_MODE_VALID	Data is valid (read) / Download data (write).

hl78xx_cell_rat_mode

enum hl78xx_cell_rat_mode

Cellular radio access technologies.

Supported radio access technology modes for HL78xx modem

Enumerator
HL78XX_RAT_CAT_M1	LTE Cat-M1 radio access technology.
HL78XX_RAT_NB1	NB-IoT radio access technology.
HL78XX_RAT_MODE_NONE	No RAT mode.
HL78XX_RAT_COUNT	Number of valid RAT modes.

hl78xx_evt_type

enum hl78xx_evt_type

HL78xx event types.

Asynchronous event notifications from the HL78xx modem

Enumerator
HL78XX_LTE_RAT_UPDATE	LTE Radio Access Technology changed.
HL78XX_LTE_REGISTRATION_STAT_UPDATE	LTE network registration status changed.
HL78XX_LTE_SIM_REGISTRATION	SIM registration status changed.
HL78XX_LTE_MODEM_STARTUP	Modem startup completed.
HL78XX_LTE_FOTA_UPDATE_STATUS	FOTA update status changed.
HL78XX_CELLMEAS_UPDATE	Cellular measurement update.
HL78XX_EVT_TYPE_COUNT	Event type count.

hl78xx_modem_info_type

enum hl78xx_modem_info_type

Cellular modem info type.

Types of modem information that can be queried

Enumerator
HL78XX_MODEM_INFO_APN	Access Point Name.
HL78XX_MODEM_INFO_CURRENT_RAT	Current Radio Access Technology.
HL78XX_MODEM_INFO_NETWORK_OPERATOR	Network Operator name.
HL78XX_MODEM_INFO_SERIAL_NUMBER	Modem Serial Number.
HL78XX_MODEM_INFO_CURRENT_BAUD_RATE	Current Baud Rate.

hl78xx_module_status

enum hl78xx_module_status

Module status codes.

Status codes returned by AT+CPIN? indicating SIM and module state

Enumerator
HL78XX_MODULE_READY	Module is ready to receive commands for the TE. No access code is required.
HL78XX_MODULE_WAITING_FOR_ACCESS_CODE	Module is waiting for an access code. Use AT+CPIN? to determine it.
HL78XX_MODULE_SIM_NOT_PRESENT	SIM card is not present.
HL78XX_MODULE_SIMLOCK	Module is in "SIMlock" state.
HL78XX_MODULE_UNRECOVERABLE_ERROR	Unrecoverable error.
HL78XX_MODULE_UNKNOWN_STATE	Unknown state.
HL78XX_MODULE_INACTIVE_SIM	Inactive SIM.

hl78xx_phone_functionality

enum hl78xx_phone_functionality

Phone functionality modes.

AT+CFUN command modes for controlling modem operational state

Enumerator
HL78XX_SIM_POWER_OFF	SIM and modem powered off (minimum functionality).
HL78XX_FULLY_FUNCTIONAL	Full functionality, modem operational.
HL78XX_AIRPLANE	Airplane mode, RF transmitters disabled.

nmea_output_port

enum nmea_output_port

NMEA output port options.

Port selection for GNSS NMEA sentence output from the modem

Enumerator
NMEA_OUTPUT_NONE	0x00 — NMEA frames are not output
NMEA_OUTPUT_USB_NMEA_PORT	0x01 — NMEA frames are output on dedicated NMEA port over USB
NMEA_OUTPUT_UART1	0x03 — NMEA frames are output on UART1
NMEA_OUTPUT_SAME_PORT	0x04 — NMEA frames are output on the same port the +GNSSNMEA was received on
NMEA_OUTPUT_CMUX_DLC1	0x05 — NMEA frames are output on CMUX DLC1
NMEA_OUTPUT_CMUX_DLC2	0x06 — NMEA frames are output on CMUX DLC2
NMEA_OUTPUT_CMUX_DLC3	0x07 — NMEA frames are output on CMUX DLC3
NMEA_OUTPUT_CMUX_DLC4	0x08 — NMEA frames are output on CMUX DLC4

Function Documentation

hl78xx_api_func_get_modem_info_vendor()

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

Get vendor-specific modem information (internal implementation).

Internal function to retrieve HL78xx-specific modem information. Users should call hl78xx_get_modem_info() instead.

Parameters

dev	Cellular network device instance
type	Type of the modem info to retrieve
info	Pointer to store the modem info
size	Size of the info buffer

Returns

0 if successful, negative errno on failure

hl78xx_api_func_get_phone_functionality()

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

Get phone functionality mode (internal implementation).

Internal function to query the modem's phone functionality mode. Users should call hl78xx_get_phone_functionality() instead.

Parameters

dev	Cellular network device instance
functionality	Pointer to store the current phone functionality mode

Returns

0 if successful, negative errno on failure

hl78xx_api_func_get_signal()

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).

Internal function to retrieve cellular signal strength metrics. Users should use the standard cellular API instead.

Parameters

dev	Cellular network device instance
type	Type of the signal to retrieve (RSSI, RSRP, RSRQ, etc.)
value	Pointer to store the signal value

Returns

0 if successful, negative errno on failure

hl78xx_api_func_modem_dynamic_cmd_send()

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).

Internal function to send arbitrary AT commands to the modem. Users should call hl78xx_modem_cmd_send() instead.

Parameters

dev	Cellular network device instance
cmd	AT command to send
cmd_size	Size of the AT command
response_matches	Expected response patterns
matches_size	Number of response patterns

Returns

0 if successful, negative errno on failure

hl78xx_api_func_set_phone_functionality()

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

Set phone functionality mode (internal implementation).

Internal function to set the modem's phone functionality mode. Users should call hl78xx_set_phone_functionality() instead.

Parameters

dev	Cellular network device instance
functionality	Phone functionality mode to set
reset	If true, the modem will be reset as part of applying the functionality change.

Returns

0 if successful, negative errno on failure

hl78xx_at_monitor_pause()

void hl78xx_at_monitor_pause ( struct hl78xx_at_monitor_entry * mon )

inlinestatic

Pause AT monitor.

Pause monitor mon from receiving parsed unsolicited AT notifications.

Parameters

mon	The monitor to pause.

hl78xx_at_monitor_register()

int hl78xx_at_monitor_register

(

struct hl78xx_at_monitor_entry *

mon

)

Register an AT monitor.

Adds a runtime monitor to the list of registered AT monitors. The monitor entry must not already be registered and must not have outstanding runtime references from a previous registration.

Monitor entries should be zero-initialized before first registration.

Parameters

mon	Pointer to the monitor entry to register.

Returns

0 on success.

-EINVAL if mon is NULL.

-EALREADY if mon is already registered.

-EBUSY if mon still has outstanding runtime references.

-ENOMEM if the maximum number of runtime monitors is reached.

hl78xx_at_monitor_resume()

void hl78xx_at_monitor_resume ( struct hl78xx_at_monitor_entry * mon )

inlinestatic

Resume AT monitor.

Resume forwarding parsed unsolicited AT notifications to monitor mon.

Parameters

mon	The monitor to resume.

hl78xx_at_monitor_unregister()

int hl78xx_at_monitor_unregister

(

struct hl78xx_at_monitor_entry *

mon

)

Unregister an AT monitor.

Removes a runtime monitor from future dispatch snapshots. This function does not wait for callbacks that are already in progress or for snapshots that already captured the monitor entry.

If the monitor entry is dynamically allocated, the caller must not free or reuse it immediately after this function returns. Instead, provide a release callback in the monitor entry and free the entry from that callback. The release callback is invoked after the final runtime reference is dropped.

This function may be called from a monitor callback.

Parameters

mon	Pointer to the monitor entry to unregister.

Returns

0 on success.

-EINVAL if mon is NULL.

-ENOENT if mon is not registered.

hl78xx_evt_monitor_pause()

void hl78xx_evt_monitor_pause ( struct hl78xx_evt_monitor_entry * mon )

inlinestatic

Pause monitor.

Pause monitor mon from receiving notifications.

Parameters

mon	The monitor to pause.

hl78xx_evt_monitor_register()

int hl78xx_evt_monitor_register

(

struct hl78xx_evt_monitor_entry *

mon

)

Register an event monitor.

Adds a runtime monitor to the list of registered event monitors. The monitor entry must not already be registered and must not have outstanding runtime references from a previous registration.

Monitor entries should be zero-initialized before first registration.

Parameters

mon	Pointer to the monitor entry to register.

Returns

0 on success.

-EINVAL if mon is NULL.

-EALREADY if mon is already registered.

-EBUSY if mon still has outstanding runtime references.

-ENOMEM if the maximum number of runtime monitors is reached.

hl78xx_evt_monitor_resume()

void hl78xx_evt_monitor_resume ( struct hl78xx_evt_monitor_entry * mon )

inlinestatic

Resume monitor.

Resume forwarding notifications to monitor mon.

Parameters

mon	The monitor to resume.

hl78xx_evt_monitor_unregister()

int hl78xx_evt_monitor_unregister

(

struct hl78xx_evt_monitor_entry *

mon

)

Unregister an event monitor.

Removes a runtime monitor from future dispatch snapshots. This function does not wait for callbacks that are already in progress or for snapshots that already captured the monitor entry.

If the monitor entry is dynamically allocated, the caller must not free or reuse it immediately after this function returns. Instead, provide a release callback in the monitor entry and free the entry from that callback. The release callback is invoked after the final runtime reference is dropped.

This function may be called from a monitor callback.

Parameters

mon	Pointer to the monitor entry to unregister.

Returns

0 on success.

-EINVAL if mon is NULL.

-ENOENT if mon is not registered.

hl78xx_evt_notif_handler_set()

int hl78xx_evt_notif_handler_set

(

hl78xx_evt_monitor_dispatcher_t

handler

)

Set the event notification handler for HL78xx modem events.

Registers a callback handler to receive asynchronous event notifications from the HL78xx modem, such as network registration changes, GNSS updates, or other modem-generated events.

Parameters

handler

Function pointer to the event monitor callback. Pass NULL to clear the existing handler.

Return values

0	on success.
-EINVAL	if the handler parameter is invalid.

hl78xx_get_modem_info()

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

inlinestatic

Get modem info for the device.

Parameters

dev	Cellular network device instance
type	Type of the modem info requested
info	Info string destination
size	Info string size

Return values

0	if successful.
-ENOTSUP	if API is not supported by cellular network device.
-ENODATA	if modem does not provide info requested
Negative	errno-code from chat module otherwise.

hl78xx_get_phone_functionality()

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

inlinestatic

Get the current phone functionality mode of the modem.

Queries the modem to retrieve its current operational mode, such as full functionality, airplane mode, or minimum functionality.

Parameters

dev	Pointer to the modem device instance.
functionality	Pointer to store the retrieved functionality mode. (see enum hl78xx_phone_functionality)

Return values

0	on success.
-EINVAL	if the input parameters are invalid.
-EIO	if the modem fails to respond or returns an error.

hl78xx_modem_cmd_send()

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 )

inlinestatic

Send an AT command to the modem and wait for a matched response.

Transmits the specified AT command to the modem and waits for a response that matches one of the expected patterns defined in the response match table.

Parameters

dev	Pointer to the modem device instance.
cmd	Pointer to the AT command string to be sent.
cmd_size	Length of the AT command string in bytes.
response_matches	Pointer to an array of expected response patterns. (see struct modem_chat_match)
matches_size	Number of response patterns in the array.

Return values

0	on successful command transmission and response match.
-EINVAL	if any parameter is invalid.
-ETIMEDOUT	if the modem did not respond in the expected time.
-EIO	on communication failure or if response did not match.

hl78xx_parse_rsrp()

int hl78xx_parse_rsrp ( uint8_t rsrp, int16_t * value )

inlinestatic

Convert raw RSRP value from the modem to dBm.

Parses the Reference Signal Received Power (RSRP) value reported by the modem and converts it into a corresponding signal strength in dBm, typically based on 3GPP TS 36.133 specifications.

Parameters

rsrp	Raw RSRP value (commonly in the range 0–97, or 255 if unknown).
value	Pointer to store the converted RSRP in dBm.

Return values

0	on successful conversion.
-EINVAL	if the RSRP value is out of range or represents an unknown value.

hl78xx_parse_rsrq()

int hl78xx_parse_rsrq ( uint8_t rsrq, int16_t * value )

inlinestatic

Convert raw RSRQ value from the modem to dB.

Parses the Reference Signal Received Quality (RSRQ) value provided by the modem and converts it into a signal quality measurement in decibels (dB), as specified by 3GPP TS 36.133.

Parameters

rsrq	Raw RSRQ value (typically 0–34, or 255 if unknown).
value	Pointer to store the converted RSRQ in dB.

Return values

0	on successful conversion.
-EINVAL	if the RSRQ value is out of valid range or indicates unknown.

hl78xx_parse_rssi()

int hl78xx_parse_rssi ( uint8_t rssi, int16_t * value )

inlinestatic

Convert raw RSSI value from the modem to dBm.

Parses the RSSI value reported by the modem (typically from an AT command response) and converts it to a corresponding signal strength in dBm, as defined by 3GPP TS 27.007.

Parameters

rssi	Raw RSSI value (0–31 or 99 for not known or not detectable).
value	Pointer to store the converted RSSI in dBm.

Return values

0	on successful conversion.
-EINVAL	if the RSSI value is out of valid range or unsupported.

hl78xx_rat_to_access_tech()

enum cellular_access_technology hl78xx_rat_to_access_tech

(

enum hl78xx_cell_rat_mode

rat_mode

)

Convert HL78xx RAT mode to standard cellular API.

Maps HL78xx-specific radio access technology enum to the standard Zephyr cellular API access technology enum.

Parameters

rat_mode

HL78xx RAT mode

Returns

Corresponding cellular_access_technology value

hl78xx_set_phone_functionality()

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

inlinestatic

Set the modem phone functionality mode.

Configures the operational state of the modem (e.g., full, airplane, or minimum functionality). Optionally, the modem can be reset during this transition.

Parameters

dev	Pointer to the modem device instance.
functionality	Desired phone functionality mode to be set. (e.g., full, airplane, minimum – see enum hl78xx_phone_functionality)
reset	If true, the modem will be reset as part of applying the functionality change.

Return values

0	on success.
-EINVAL	if an invalid parameter is passed.
-EIO	on communication or command failure with the modem.