mirror of
https://github.com/zephyrproject-rtos/zephyr
synced 2025-09-01 16:32:57 +00:00
eca8842b67
The driver utilizes the CONFIG_NET_OFFLOAD setting to avoid the normal handling of IP packets, and instead uses a socket-like UART interface to handle incoming and outgoing data via AT commands. Signed-off-by: Ryan Erickson <ryan.erickson@lairdconnect.com>
271 lines
6.7 KiB
C
271 lines
6.7 KiB
C
/** @file
|
|
* @brief HL7800 modem public API header file.
|
|
*
|
|
* Allows an application to control the HL7800 modem.
|
|
*
|
|
* Copyright (c) 2020 Laird Connectivity
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
#ifndef ZEPHYR_INCLUDE_DRIVERS_MODEM_HL7800_H_
|
|
#define ZEPHYR_INCLUDE_DRIVERS_MODEM_HL7800_H_
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#ifdef CONFIG_NEWLIB_LIBC
|
|
#include <time.h>
|
|
#endif
|
|
|
|
/* The size includes the NUL character, the strlen doesn't */
|
|
#define MDM_HL7800_REVISION_MAX_SIZE 29
|
|
#define MDM_HL7800_REVISION_MAX_STRLEN (MDM_HL7800_REVISION_MAX_SIZE - 1)
|
|
|
|
#define MDM_HL7800_IMEI_SIZE 16
|
|
#define MDM_HL7800_IMEI_STRLEN (MDM_HL7800_IMEI_SIZE - 1)
|
|
|
|
#define MDM_HL7800_ICCID_SIZE 21
|
|
#define MDM_HL7800_ICCID_STRLEN (MDM_HL7800_ICCID_SIZE - 1)
|
|
|
|
#define MDM_HL7800_SERIAL_NUMBER_SIZE 15
|
|
#define MDM_HL7800_SERIAL_NUMBER_STRLEN (MDM_HL7800_SERIAL_NUMBER_SIZE - 1)
|
|
|
|
#define MDM_HL7800_APN_MAX_SIZE 64
|
|
#define MDM_HL7800_APN_USERNAME_MAX_SIZE 65
|
|
#define MDM_HL7800_APN_PASSWORD_MAX_SIZE 65
|
|
|
|
#define MDM_HL7800_APN_MAX_STRLEN (MDM_HL7800_APN_MAX_SIZE - 1)
|
|
#define MDM_HL7800_APN_USERNAME_MAX_STRLEN \
|
|
(MDM_HL7800_APN_USERNAME_MAX_SIZE - 1)
|
|
#define MDM_HL7800_APN_PASSWORD_MAX_STRLEN \
|
|
(MDM_HL7800_APN_PASSWORD_MAX_SIZE - 1)
|
|
|
|
#define MDM_HL7800_APN_CMD_MAX_SIZE \
|
|
(32 + MDM_HL7800_APN_USERNAME_MAX_STRLEN + \
|
|
MDM_HL7800_APN_PASSWORD_MAX_STRLEN)
|
|
|
|
#define MDM_HL7800_APN_CMD_MAX_STRLEN (MDM_HL7800_APN_CMD_MAX_SIZE - 1)
|
|
|
|
struct mdm_hl7800_apn {
|
|
char value[MDM_HL7800_APN_MAX_SIZE];
|
|
char username[MDM_HL7800_APN_USERNAME_MAX_SIZE];
|
|
char password[MDM_HL7800_APN_PASSWORD_MAX_SIZE];
|
|
};
|
|
|
|
#define MDM_HL7800_LTE_BAND_STR_SIZE 21
|
|
#define MDM_HL7800_LTE_BAND_STRLEN (MDM_HL7800_LTE_BAND_STR_SIZE - 1)
|
|
|
|
enum mdm_hl7800_radio_mode { MDM_RAT_CAT_M1 = 0, MDM_RAT_CAT_NB1 };
|
|
|
|
enum mdm_hl7800_event {
|
|
HL7800_EVENT_RESERVED = 0,
|
|
HL7800_EVENT_NETWORK_STATE_CHANGE,
|
|
HL7800_EVENT_APN_UPDATE,
|
|
HL7800_EVENT_RSSI,
|
|
HL7800_EVENT_SINR,
|
|
HL7800_EVENT_STARTUP_STATE_CHANGE,
|
|
HL7800_EVENT_SLEEP_STATE_CHANGE,
|
|
HL7800_EVENT_RAT,
|
|
HL7800_EVENT_BANDS,
|
|
HL7800_EVENT_ACTIVE_BANDS,
|
|
HL7800_EVENT_FOTA_STATE,
|
|
HL7800_EVENT_FOTA_COUNT,
|
|
HL7800_EVENT_REVISION
|
|
};
|
|
|
|
enum mdm_hl7800_startup_state {
|
|
HL7800_STARTUP_STATE_READY = 0,
|
|
HL7800_STARTUP_STATE_WAITING_FOR_ACCESS_CODE,
|
|
HL7800_STARTUP_STATE_SIM_NOT_PRESENT,
|
|
HL7800_STARTUP_STATE_SIMLOCK,
|
|
HL7800_STARTUP_STATE_UNRECOVERABLE_ERROR,
|
|
HL7800_STARTUP_STATE_UNKNOWN,
|
|
HL7800_STARTUP_STATE_INACTIVE_SIM
|
|
};
|
|
|
|
enum mdm_hl7800_network_state {
|
|
HL7800_NOT_REGISTERED = 0,
|
|
HL7800_HOME_NETWORK,
|
|
HL7800_SEARCHING,
|
|
HL7800_REGISTRATION_DENIED,
|
|
HL7800_OUT_OF_COVERAGE,
|
|
HL7800_ROAMING,
|
|
HL7800_EMERGENCY = 8,
|
|
/* Laird defined states */
|
|
HL7800_UNABLE_TO_CONFIGURE = 0xf0
|
|
};
|
|
|
|
enum mdm_hl7800_sleep_state {
|
|
HL7800_SLEEP_STATE_UNINITIALIZED = 0,
|
|
HL7800_SLEEP_STATE_ASLEEP,
|
|
HL7800_SLEEP_STATE_AWAKE
|
|
};
|
|
|
|
enum mdm_hl7800_fota_state {
|
|
HL7800_FOTA_IDLE,
|
|
HL7800_FOTA_START,
|
|
HL7800_FOTA_WIP,
|
|
HL7800_FOTA_PAD,
|
|
HL7800_FOTA_SEND_EOT,
|
|
HL7800_FOTA_FILE_ERROR,
|
|
HL7800_FOTA_INSTALL,
|
|
HL7800_FOTA_REBOOT_AND_RECONFIGURE,
|
|
HL7800_FOTA_COMPLETE,
|
|
};
|
|
|
|
/* The modem reports state values as an enumeration and a string */
|
|
struct mdm_hl7800_compound_event {
|
|
uint8_t code;
|
|
char *string;
|
|
};
|
|
|
|
/**
|
|
* event - The type of event
|
|
* event_data - Pointer to event specific data structure
|
|
* HL7800_EVENT_NETWORK_STATE_CHANGE - compound event
|
|
* HL7800_EVENT_APN_UPDATE - struct mdm_hl7800_apn
|
|
* HL7800_EVENT_RSSI - int
|
|
* HL7800_EVENT_SINR - int
|
|
* HL7800_EVENT_STARTUP_STATE_CHANGE - compound event
|
|
* HL7800_EVENT_SLEEP_STATE_CHANGE - compound event
|
|
* HL7800_EVENT_RAT - int
|
|
* HL7800_EVENT_BANDS - string
|
|
* HL7800_EVENT_ACTIVE_BANDS - string
|
|
* HL7800_EVENT_FOTA_STATE - compound event
|
|
* HL7800_EVENT_FOTA_COUNT - uint32_t
|
|
* HL7800_EVENT_REVISION - string
|
|
*/
|
|
typedef void (*mdm_hl7800_event_callback_t)(enum mdm_hl7800_event event,
|
|
void *event_data);
|
|
|
|
/**
|
|
* @brief Power off the HL7800
|
|
*
|
|
* @return int32_t 0 for success
|
|
*/
|
|
int32_t mdm_hl7800_power_off(void);
|
|
|
|
/**
|
|
* @brief Reset the HL7800
|
|
*
|
|
* @return int32_t 0 for success
|
|
*/
|
|
int32_t mdm_hl7800_reset(void);
|
|
|
|
/**
|
|
* @brief Control the wake signals to the HL7800.
|
|
* @note this API should only be used for debug purposes.
|
|
*
|
|
* @param awake True to keep the HL7800 awake, False to allow sleep
|
|
*/
|
|
void mdm_hl7800_wakeup(bool awake);
|
|
|
|
/**
|
|
* @brief Send an AT command to the HL7800.
|
|
* @note this API should only be used for debug purposes.
|
|
*
|
|
* @param data AT command string
|
|
* @return int32_t 0 for success
|
|
*/
|
|
int32_t mdm_hl7800_send_at_cmd(const uint8_t *data);
|
|
|
|
/**
|
|
* @brief Get the signal quality of the HL7800
|
|
*
|
|
* @param rsrp Reference Signals Received Power (dBm)
|
|
* Range = -140 dBm to -44 dBm
|
|
* @param sinr Signal to Interference plus Noise Ratio (dBm)
|
|
* Range = -128 dBm to 40dBm
|
|
*/
|
|
void mdm_hl7800_get_signal_quality(int *rsrp, int *sinr);
|
|
|
|
/**
|
|
* @brief Get the SIM card ICCID
|
|
*
|
|
*/
|
|
char *mdm_hl7800_get_iccid(void);
|
|
|
|
/**
|
|
* @brief Get the HL7800 serial number
|
|
*
|
|
*/
|
|
char *mdm_hl7800_get_sn(void);
|
|
|
|
/**
|
|
* @brief Get the HL7800 IMEI
|
|
*
|
|
*/
|
|
char *mdm_hl7800_get_imei(void);
|
|
|
|
/**
|
|
* @brief Get the HL7800 firmware version
|
|
*
|
|
*/
|
|
char *mdm_hl7800_get_fw_version(void);
|
|
|
|
/**
|
|
* @brief Update the Access Point Name in the modem.
|
|
*
|
|
* @retval 0 on success, negative on failure.
|
|
*/
|
|
int32_t mdm_hl7800_update_apn(char *access_point_name);
|
|
|
|
/**
|
|
* @brief Update the Radio Access Technology (mode).
|
|
*
|
|
* @retval 0 on success, negative on failure.
|
|
*/
|
|
int32_t mdm_hl7800_update_rat(enum mdm_hl7800_radio_mode value);
|
|
|
|
/**
|
|
* @retval true if RAT value is valid
|
|
*/
|
|
bool mdm_hl7800_valid_rat(uint8_t value);
|
|
|
|
/**
|
|
* @brief Register a function that is called when a modem event occurs.
|
|
*
|
|
* @param cb event callback
|
|
*/
|
|
void mdm_hl7800_register_event_callback(mdm_hl7800_event_callback_t cb);
|
|
|
|
/**
|
|
* @brief Force modem module to generate status events.
|
|
*
|
|
* @note This can be used to get the current state when a module initializes
|
|
* later than the modem.
|
|
*/
|
|
void mdm_hl7800_generate_status_events(void);
|
|
|
|
#ifdef CONFIG_NEWLIB_LIBC
|
|
/**
|
|
* @brief Get the local time from the modem's real time clock.
|
|
*
|
|
* @param tm time structure
|
|
* @param offset The amount the local time is offset from GMT/UTC in seconds.
|
|
*
|
|
* @param 0 if successful
|
|
*/
|
|
int32_t mdm_hl7800_get_local_time(struct tm *tm, int32_t *offset);
|
|
#endif
|
|
|
|
#ifdef CONFIG_MODEM_HL7800_FW_UPDATE
|
|
/**
|
|
* @brief Update the HL7800 via XMODEM protocol. During the firmware update
|
|
* no other modem fuctions will be available.
|
|
*
|
|
* @param file_path Absolute path of the update file
|
|
*
|
|
* @param 0 if successful
|
|
*/
|
|
int32_t mdm_hl7800_update_fw(char *file_path);
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* ZEPHYR_INCLUDE_DRIVERS_MODEM_HL7800_H_ */
|