GSM modem

GSM modem driver.

To use the GSM modem driver you need to retrieve a handle to the GSM modem device by a call to open(const char*) supplying the device name as specified in the sysconf. Afterwards call gsm_modem_init (int, gsm_modem_init_t *) to have the modem start searching for a mobile network operator and attach to the PS domain.

cpp

int h_modem = open("gsm0");
gsm_modem_init_t modem_init = GSM_MODEM_INIT_DEFAULT;
memmove (modem_init.apn, PDP_CONTEXT_NAME, strlen (PDP_CONTEXT_NAME));
gsm_modem_init(h_modem, &modem_init);

Sysprops

The Modem needs a parent UART device with RTS&CTS

sysprop	description
gpio_ri	Ring-Indicator GPIO
gpio_dcd	Data Carrier Detect (DCD) GPIO
gpio_dtr	Data Terminal Ready (DTR) GPIO

cpp

sysconf_create_device("silabs-gecko-euart", eusart1, 0x500A0000UL ,
                      sysconf_set_int_param (gpio_rx, 206),
                      sysconf_set_int_param (gpio_tx, 205),
                      sysconf_set_int_param (gpio_rts, 204),
                      sysconf_set_int_param (gpio_cts, 203))

sysconf_create_device("quectel-bg77", modem0, 0x0,
                      sysconf_set_parent_dev (eusart1),
                      sysconf_set_int_param (gpio_dcd, 201),
                      sysconf_set_int_param (gpio_dtr, 207),
                      sysconf_set_int_param (gpio_ri, 200),
                      sysconf_set_int_param (quectel_bg77_pwrkey_gpio, 208),
                      sysconf_set_int_param (gpio_status, 202))

Types

	Name
struct	gsm_modem_init_t GSM modem initialization parameters.
struct	gsm_signal_info_t Signal Strength Information.
struct	gsm_registration_info_t
struct	gsm_modem_driver
enum	gsm_technology_t Modem Radio Access Technology (RAT)
enum	apn_auth_t APN Authentication Type for PPP.

Functions Overview

	Name
int	gsm_modem_init(int hdev, gsm_modem_init_t * init) Initialize the modem.
int	gsm_modem_reset(int hdev) resets the modem.
int	gsm_modem_rf_on(int hdev) activates the radio interface of the modem
int	gsm_modem_rf_off(int hdev) turns the radio interface of the modem off
int	gsm_modem_sleep(int hdev) puts the modem in power save mode immediately
int	gsm_modem_wakeup(int hdev) wakes the modem from PSM sleep immediately
int	gsm_modem_connect(int hdev, int wait) The function creates a PDP context and connects the modem to the APN.
int	gsm_modem_disconnect(int hdev) The function closes the PDP context and disconnects the modem from the APN.
int	gsm_modem_connected(int hdev) checks the modem's current connection status in the PS domain
int	gsm_modem_registered(int hdev) checks the modem's current rgistration status
int	gsm_modem_imei(int hdev, char * imei)
int	gsm_modem_imsi(int hdev, char * imsi)
int	gsm_modem_iccid(int hdev, char * imsi)
int	gsm_modem_signal_quality(int hdev, gsm_signal_info_t * info)
int	gsm_modem_sim_status(int hdev) Get the status of the SIM card in the GSM modem.
int	gsm_modem_registration_info(int hdev, gsm_registration_info_t * info)
int	gsm_modem_version(int hDev, char * version, size_t version_len)

Defines

Name
GSM_MODEM_INIT_DEFAULT	Default init parameters for GSM modem, setting it to LTE CAT-M1 on Band 8.

Types Documentation

enum gsm_technology_t

Enumerator	Description
gtNBIOT	LTE CAT-NB1 / CAT-NB2.
gtEMMC	LTE CAT-M1.
gtEMMC_NBIOT	CAT-M1 and LTE CAT-NB1 / CAT-NB2 and.
gtNBIOT_EMMC	LTE CAT-NB1 / CAT-NB2 and CAT-M1.
gtGSM	GPRS / UMTS.

Modem Radio Access Technology (RAT)

enum apn_auth_t

Enumerator	Description
atNONE	No Authentication required.
atPAP	PAP Authentication only.
atCHAP	CHAP Authentication only.
atPAPCHAP	Both PAP and CHAP are supported.

APN Authentication Type for PPP.

Function Details

function gsm_modem_init

cpp

int gsm_modem_init(
    int hdev,
    gsm_modem_init_t * init
)

Initialize the modem.

Parameters:

hdev device handle as returned by open(const char*)
init structure holding the device configuration parameters

Return: 0 on success, -1 on failure

This function has to be called before any other gsm_modem_xx functions. If not, behaviour will be unpredictable.

function gsm_modem_reset

cpp

int gsm_modem_reset(
    int hdev
)

resets the modem.

Parameters:

hdev device handle as returned by open(const char*)

Return: 0 on success, -1 on failure

if the modem was connected to the PS domain before calling reset, it will be disconnected and gsm_modem_connect(int hdev, int wait) has to be called again.

function gsm_modem_rf_on

cpp

int gsm_modem_rf_on(
    int hdev
)

activates the radio interface of the modem

Parameters:

hdev device handle as returned by open(const char*)

Return: 0 on success, -1 on failure

function gsm_modem_rf_off

cpp

int gsm_modem_rf_off(
    int hdev
)

turns the radio interface of the modem off

Parameters:

hdev device handle as returned by open(const char*)

Return: 0 on success, -1 on failure

function gsm_modem_sleep

cpp

int gsm_modem_sleep(
    int hdev
)

puts the modem in power save mode immediately

Parameters:

hdev device handle as returned by open(const char*)

Return: 0 on success, -1 on failure

the modem will not automatically wake up when a previously set PSM timer runs out. It has to be explicitly woken up by gsm_modem_wakeup (int hdev). Any open connection to the PS-Domain will be closed and has to be re-established after waking the modem up again. An attachment to the network will be kept for the time, the MNO confirmed after requesting a PSM setting.

function gsm_modem_wakeup

cpp

int gsm_modem_wakeup(
    int hdev
)

wakes the modem from PSM sleep immediately

Parameters:

hdev device handle as returned by open(const char*)

Return: 0 on success, -1 on failure

function gsm_modem_connect

cpp

int gsm_modem_connect(
    int hdev,
    int wait
)

The function creates a PDP context and connects the modem to the APN.

Parameters:

hdev device handle as returned by open(const char*)
wait if 0 is passed, the function returns immediately, trying to connect in the background.

Return: if the modem has succesfully connected, the function returns 0, otherwise -1. In case wait is set to zero, the function will only check for successful attachment to the PS-domain but not wait for the PDP-context establishment or the PPP connection setup and return with 0 (=OK) immediately.

the connection status can be queried by a call to gsm_modem_connected(int) . if 1 is passed, the function blocks until the connection either succeeds or fails.

function gsm_modem_disconnect

cpp

int gsm_modem_disconnect(
    int hdev
)

The function closes the PDP context and disconnects the modem from the APN.

Parameters:

hdev device handle as returned by open(const char*)

Return: if the modem is disconnected succesfully the function returns 1, otherwise 0.

function gsm_modem_connected

cpp

int gsm_modem_connected(
    int hdev
)

checks the modem's current connection status in the PS domain

Parameters:

hdev device handle as returned by open(const char*)

Return: if the modem is connected to the PS domain the function returns 1, otherwise 0.

function gsm_modem_registered

cpp

int gsm_modem_registered(
    int hdev
)

checks the modem's current rgistration status

Parameters:

hdev device handle as returned by open(const char*)

Return: if the modem is registered to the network the function returns 1, otherwise 0.

function gsm_modem_imei

cpp

int gsm_modem_imei(
    int hdev,
    char * imei
)

Parameters:

hdev device handle as returned by open(const char*)
imei reference to a character buffer of 15bytes, allocated by the called. The buffer will be filled with the device identifier ("IMEI") upon success.

Return: execution status 0 = Succeeded, any other value = Error

function gsm_modem_imsi

cpp

int gsm_modem_imsi(
    int hdev,
    char * imsi
)

Parameters:

hdev device handle as returned by open(const char*) device handle as returned by open(char*)
imsi reference to a character buffer of 15bytes, allocated by the caller. The buffer will be filled with the subscriber identity ("IMSI") upon success.

Return: 0 on success, -1 on failure

function gsm_modem_iccid

cpp

int gsm_modem_iccid(
    int hdev,
    char * imsi
)

Parameters:

hdev device handle as returned by open(const char*) device handle as returned by open(char*)
imsi reference to a character buffer of 22bytes, allocated by the caller. The buffer will be filled with the card identity ("ICCID") upon success.

Return: 0 on success, -1 on failure

function gsm_modem_signal_quality

cpp

int gsm_modem_signal_quality(
    int hdev,
    gsm_signal_info_t * info
)

Parameters:

hdev device handle as returned by open(const char*)
info

Return: 0 on success, -1 on failure

function gsm_modem_sim_status

cpp

int gsm_modem_sim_status(
    int hdev
)

Get the status of the SIM card in the GSM modem.

Parameters:

hdev The handle to the GSM modem device

Return: The SIM card status code:

0: SIM card is active
-1: SIM card is defective or not inserted

This function retrieves the status of the SIM card inserted in the GSM modem.

function gsm_modem_registration_info

cpp

int gsm_modem_registration_info(
    int hdev,
    gsm_registration_info_t * info
)

Parameters:

hdev device handle as returned by open(const char*)
info

Return: 0 on success, -1 on failure

function gsm_modem_version

cpp

int gsm_modem_version(
    int hDev,
    char * version,
    size_t version_len
)

Macros Documentation

define GSM_MODEM_INIT_DEFAULT

cpp

#define GSM_MODEM_INIT_DEFAULT   = {  \
  .bands = LTE_B8,                    \
  .power_on_reset = 1,                \
  .use_peer_dns = 1,                  \
  .edrx = 0,                          \
  .psm = 0,                           \
  .oper = {0},                        \
  .apn_auth_type = atCHAP,            \
  .tech = gtEMMC,                     \
  .baudrate = 921600,                 \
  .apn = {0},                         \
  .scanseq[0] = 0,                    \
  .apn_user = {0),                    \
  .apn_pwd = {0}                      \
  }

Default init parameters for GSM modem, setting it to LTE CAT-M1 on Band 8.

GSM modem ​

Sysprops ​

Types ​

Functions Overview ​

Defines ​

Types Documentation ​

enum gsm_technology_t ​

enum apn_auth_t ​

Function Details ​

function gsm_modem_init ​

function gsm_modem_reset ​

function gsm_modem_rf_on ​

function gsm_modem_rf_off ​

function gsm_modem_sleep ​

function gsm_modem_wakeup ​

function gsm_modem_connect ​

function gsm_modem_disconnect ​

function gsm_modem_connected ​

function gsm_modem_registered ​

function gsm_modem_imei ​

function gsm_modem_imsi ​

function gsm_modem_iccid ​

function gsm_modem_signal_quality ​

function gsm_modem_sim_status ​

function gsm_modem_registration_info ​

function gsm_modem_version ​

Macros Documentation ​

define GSM_MODEM_INIT_DEFAULT ​

GSM modem

Sysprops

Types

Functions Overview

Defines

Types Documentation

enum gsm_technology_t

enum apn_auth_t

Function Details

function gsm_modem_init

function gsm_modem_reset

function gsm_modem_rf_on

function gsm_modem_rf_off

function gsm_modem_sleep

function gsm_modem_wakeup

function gsm_modem_connect

function gsm_modem_disconnect

function gsm_modem_connected

function gsm_modem_registered

function gsm_modem_imei

function gsm_modem_imsi

function gsm_modem_iccid

function gsm_modem_signal_quality

function gsm_modem_sim_status

function gsm_modem_registration_info

function gsm_modem_version

Macros Documentation

define GSM_MODEM_INIT_DEFAULT