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>

Go to the source code of this file.

Data Structures
struct	hl78xx_network
	Cellular network structure. More...
struct	hl78xx_evt
struct	hl78xx_evt_monitor_entry

Macros
#define	CSQ_RSSI_UNKNOWN   (99)
#define	CESQ_RSRP_UNKNOWN   (255)
#define	CESQ_RSRQ_UNKNOWN   (255)
#define	CSQ_RSSI_TO_DB(v)
#define	CESQ_RSRP_TO_DB(v)
#define	CESQ_RSRQ_TO_DB(v)
#define	PAUSED   1
	Monitor is paused.
#define	ACTIVE   0
	Monitor is active, default.
#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	HL78XX_EVT_MONITOR(name, _handler, ...)
	Define an Event monitor to receive notifications in the system workqueue thread.

Typedefs
typedef int(*	hl78xx_api_configure_networks) (const struct device *dev, const struct hl78xx_network *networks, uint8_t size)
	API for configuring networks.
typedef int(*	hl78xx_api_get_supported_networks) (const struct device *dev, const struct hl78xx_network **networks, uint8_t *size)
	API 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 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_apn) (const struct device *dev, const char *apn, uint16_t size)
	API for setting apn.
typedef int(*	hl78xx_api_set_phone_functionality) (const struct device *dev, enum hl78xx_phone_functionality functionality, bool reset)
	API for set 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_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)

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 }
	Cellular modem info type. More...
enum	hl78xx_evt_type { HL78XX_LTE_RAT_UPDATE , HL78XX_LTE_REGISTRATION_STAT_UPDATE , HL78XX_LTE_SIM_REGISTRATION , HL78XX_LTE_MODEM_STARTUP }

Functions
int	hl78xx_api_func_set_phone_functionality (const struct device *dev, enum hl78xx_phone_functionality functionality, bool reset)
	hl78xx_api_func_set_phone_functionality
int	hl78xx_api_func_get_phone_functionality (const struct device *dev, enum hl78xx_phone_functionality *functionality)
	hl78xx_api_func_get_phone_functionality
int	hl78xx_api_func_get_signal (const struct device *dev, const enum cellular_signal_type type, int16_t *value)
	hl78xx_api_func_get_signal - Brief description of the function.
int	hl78xx_api_func_get_modem_info_vendor (const struct device *dev, enum hl78xx_modem_info_type type, void *info, size_t size)
	hl78xx_api_func_get_modem_info_vendor - Brief description of the function.
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)
	hl78xx_api_func_modem_dynamic_cmd_send - Brief description of the function.
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.
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 to receive HL78xx modem event notifications.
int	hl78xx_evt_monitor_unregister (struct hl78xx_evt_monitor_entry *mon)
	Unregister an event monitor from receiving HL78xx modem event notifications.
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

ACTIVE

#define ACTIVE   0

Monitor is active, default.

CESQ_RSRP_TO_DB

#define CESQ_RSRP_TO_DB

(

v

)

Value:

(-140 + (v))

CESQ_RSRP_UNKNOWN

#define CESQ_RSRP_UNKNOWN   (255)

CESQ_RSRQ_TO_DB

#define CESQ_RSRQ_TO_DB

(

v

)

Value:

(-20 + ((v) / 2))

CESQ_RSRQ_UNKNOWN

#define CESQ_RSRQ_UNKNOWN   (255)

CSQ_RSSI_TO_DB

#define CSQ_RSSI_TO_DB

(

v

)

Value:

(-113 + (2 * (v)))

CSQ_RSSI_UNKNOWN

#define CSQ_RSSI_UNKNOWN   (99)

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,                                                             \
                COND_CODE_1(__VA_ARGS__, (.flags.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 (PAUSED or ACTIVE). The default initial state of a monitor is active.

MDM_APN_MAX_LENGTH

#define MDM_APN_MAX_LENGTH   64

MDM_ICCID_LENGTH

#define MDM_ICCID_LENGTH   22

MDM_IMEI_LENGTH

#define MDM_IMEI_LENGTH   16

MDM_IMSI_LENGTH

#define MDM_IMSI_LENGTH   23

MDM_MANUFACTURER_LENGTH

#define MDM_MANUFACTURER_LENGTH   20

MDM_MAX_CERT_LENGTH

#define MDM_MAX_CERT_LENGTH   4096

MDM_MAX_HOSTNAME_LEN

#define MDM_MAX_HOSTNAME_LEN   128

MDM_MODEL_LENGTH

#define MDM_MODEL_LENGTH   32

MDM_REVISION_LENGTH

#define MDM_REVISION_LENGTH   64

PAUSED

#define PAUSED   1

Monitor is 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 for configuring networks.

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 for getting modem information.

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 for getting supported networks.

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.

Event monitor entry

hl78xx_api_set_apn

typedef int(* hl78xx_api_set_apn) (const struct device *dev, const char *apn, uint16_t size)

API for setting apn.

hl78xx_api_set_phone_functionality

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

API for set phone functionality.

hl78xx_evt_monitor_dispatcher_t

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

hl78xx_evt_monitor_handler_t

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

Enumeration Type Documentation

hl78xx_cell_rat_mode

enum hl78xx_cell_rat_mode

Cellular radio access technologies.

Enumerator
HL78XX_RAT_CAT_M1
HL78XX_RAT_NB1
HL78XX_RAT_MODE_NONE
HL78XX_RAT_COUNT

hl78xx_evt_type

enum hl78xx_evt_type

Enumerator
HL78XX_LTE_RAT_UPDATE
HL78XX_LTE_REGISTRATION_STAT_UPDATE
HL78XX_LTE_SIM_REGISTRATION
HL78XX_LTE_MODEM_STARTUP

hl78xx_modem_info_type

enum hl78xx_modem_info_type

Cellular modem info type.

Enumerator
HL78XX_MODEM_INFO_APN
HL78XX_MODEM_INFO_CURRENT_RAT
HL78XX_MODEM_INFO_NETWORK_OPERATOR

hl78xx_module_status

enum hl78xx_module_status

Module status codes.

Enumerator
HL78XX_MODULE_READY
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

hl78xx_phone_functionality

enum hl78xx_phone_functionality

Phone functionality modes.

Enumerator
HL78XX_SIM_POWER_OFF
HL78XX_FULLY_FUNCTIONAL
HL78XX_AIRPLANE

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 )

hl78xx_api_func_get_modem_info_vendor - Brief description of the function.

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.

hl78xx_api_func_get_phone_functionality()

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

hl78xx_api_func_get_phone_functionality

Parameters

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

Returns

0 if successful.

hl78xx_api_func_get_signal()

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

hl78xx_api_func_get_signal - Brief description of the function.

Parameters

dev	Cellular network device instance
type	Type of the signal to retrieve
value	Pointer to store the signal value

Returns

0 if successful.

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 )

hl78xx_api_func_modem_dynamic_cmd_send - Brief description of the function.

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	Size of the response patterns

Returns

0 if successful.

hl78xx_api_func_set_phone_functionality()

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

hl78xx_api_func_set_phone_functionality

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.

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 to receive HL78xx modem event notifications.

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 from receiving HL78xx modem event notifications.

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.

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.