Skip to content

GSM modem ​

GSM modem driver.

To use the GSM modem driver, retrieve a handle to the modem device with open(const char*), supplying the device name as declared in the sysconf, and call gsm_modem_init (int, gsm_modem_init_t *). Init powers the module, applies the configuration (bands, RAT, APN) and starts network acquisition; registration and PS attach then proceed autonomously.

cpp
int h_modem = open("gsm0");
// static: the driver keeps a reference to the init structure
static gsm_modem_init_t modem_init = GSM_MODEM_INIT_DEFAULT;
strncpy (modem_init.apn, PDP_CONTEXT_NAME, sizeof (modem_init.apn) - 1);
if (gsm_modem_init (h_modem, &modem_init) != 0) {
    // also returned while a requested modem reset is still running —
    // back off and call gsm_modem_init() again.
}

Connection model ​

The driver distinguishes three conditions: registered (network registration per CEREG, gsm_modem_registered), connected (PPP session up with an active PDP context, gsm_modem_connected), and data actually flowing. The first two are claims made by the modem; only an answered round trip through the network proves the third. A session can be registered, hold an IP address and still move nothing — which is why the driver relies on the evidence reports below.

Data-path evidence ​

The layer that talks to a peer reports what it observes: gsm_modem_note_data_ok after an answered round trip (at a cadence well below the 5-minute evidence window), gsm_modem_note_data_lost once its own cheaper recovery has failed. Without the loss report the driver waits for positive evidence to age out, which takes GSM_MODEM_RUNG_DATA_STALL_MS. A layer without such a cadence (no keepalive) announces its contact interval with gsm_modem_set_contact_interval and reports each send with gsm_modem_note_data_pending; then only an unanswered send ages the evidence.

Recovery guarantee ​

Once a round trip has been reported since the last cold start, the driver guarantees that a device without further answered round trips re-attaches within bounded time — whatever state modem, driver or application are in. The guardian behind this knows one input, the age of the last answered round trip, and its state survives software reboots:

  • GSM_MODEM_RUNG_DATA_STALL_MS: rebuild the PPP session.
  • GSM_MODEM_RUNG_REATTACH_MS: detach and re-attach (AT+CFUN=0/1). The network drops the old PDP context and creates a fresh one — the device-side equivalent of an HLR reset.
  • GSM_MODEM_RUNG_DATA_RESET_MS: reset the modem.
  • then reset the modem again GSM_MODEM_RUNG_REST_RESET_MS after the previous reset. Each such reset ends the cycle; if IP packets arrived during it, the next interval is 50, then 100 and from then on 200 min. Without any packets the interval stays at 30 min.

All deadlines of a cycle carry one random factor of +-25 %, so a fleet does not act in step; the further resets only add to their interval (0 to +25 %), never come earlier. The driver never reboots the device for a network or backend outage (GSMA TS.34); the only reboot left is OS_REBOOT_REASON_MODEM_WEDGE, a requested reset that did not complete within 10 minutes while the modem stopped answering AT.

What a rung actually does is decided by the action gate: while IP packets arrive, the bearer carries and the rest is the application's job, so at most one PPP rebuild per hour happens. While the data session back-off suspects a blocked SIM, while the network's T3396 runs, after a registration reject and once the attach budget is used up, no re-attach and no modem reset happens. gsm_modem_reset and the reset at boot go through the same gate. The last two attaches below the budget are kept for a modem that stops answering AT; while T3396 runs that reset waits as well, since no data session can exist then, and follows with the next dial attempt.

A setup failure without a network cause (no ESM cause from AT+CEER, no authentication failure) is never counted towards the back-off, never stored and does not hold off the guardian; it is not reported as a back-off either. During the first hour of a series of such failures it is retried after 5 s, 15 s, 30 s and then every 60 s, after that every 5 min (0 to +25 %, never earlier); a success or a failure with a network cause ends the series. Failures with an ESM cause, EMM #19 or an authentication failure always count and survive reboots.

From the re-attach deadline on, every reboot resets the modem at boot, also one triggered by the application, if the gate allows it. A reboot that resets the modem ends the cycle as well; if IP packets arrived during the cycle, i.e. the network carried and only the peer was missing, the next one moves up one step (first rungs twice as long, at most 8x). A reported PLMN search pauses the ladder for at most 90 minutes per cycle; while a PPP session is up without CMUX the cached registration predates the session and does not pause it. Without any evidence and without any data session since the last cold start (commissioning) only a modem reset applies, after 4 / 8 / 16 hours.

Data session back-off ​

Every dial is a PDP activation and, with CHAP/PAP, a request to the operator's AAA server. Failed setups with a network cause are retried at once (no sooner than a failure without one), then after 30 s, 2, 5, 15, 30 and 60 min (+-25 %). After 6 such failures spanning at least 60 min the SIM is suspected blocked: at most one attempt per 6 h and 6 per 24 h, also across reboots. ESM cause #26 with T3396 holds off until the timer expires. Any successful setup ends the back-off.

Registration rejects ​

The driver registers for CEREG with the EMM cause (AT+CEREG=3). Permanent causes (#3/#6/#7/#8) get one CFUN cycle after 1 h, 4 h and then every 24 h (0 to +25 %, never earlier); #11/#14 none at all (the modem keeps the forbidden list, which is never cleared); #12/#13/#15, #17/#22 and unknown causes a modem reset after 30, 60, 120 and then every 240 min (+-25 %). Any registration ends the back-off.

Re-attach hold-off ​

After a detach the driver itself caused (AT+CFUN=0, a modem reset, a hang-up that took the PDP context with it) it waits before registering or dialling again: 120 s, doubled for each session in a row that received no packet, at most 300 s. A PDN session set up seconds after the previous one ended has been observed to receive no downlink at all. A modem reset requested for the next boot powers the modem down and waits before powering it up, so boot takes about two minutes longer in that case.

First-packet check ​

If a freshly established session has carried a name or time query (DNS or NTP) and not a single IP packet comes back within 90 s of that query, the session is treated as dead and re-attached after the hold-off, at most twice per 24 h: in a private APN the resolver and NTP server live in the operator's network and can fail on their own. A session that carries none of these queries is never judged. On by default; the BG77 sysprop first_rx_timeout_s overrides the limit, 0 switches the check off.

Not registered, independently of the evidence: modem reset after GSM_MODEM_RUNG_MODEM_RESET_MS in a non-searching state, and at GSM_MODEM_RUNG_CEILING_MS regardless of CEREG — unless a registration reject is being backed off, which then owns the timing.

Layers above that run their own deadman must place it aboveGSM_MODEM_RUNG_DATA_STALL_MS, or the device reboots before the cheaper repair was even tried, and must not reboot for a network or backend outage.

Blocking behaviour ​

Most calls issue AT transactions and serialize on the driver's request mutex. While a PPP session is up, a transaction first has to escape data mode, so a call can block for a long time (the bound is measured in minutes, not milliseconds). Do not call this API from threads that must stay responsive; prefer cached snapshots where a middleware offers them (e.g. coldwave_lte_peek() in libcoldwave).

Sysprops ​

The Modem needs a parent UART device with RTS&CTS

syspropdescription
gpio_riRing-Indicator GPIO
gpio_dcdData Carrier Detect (DCD) GPIO
gpio_dtrData Terminal Ready (DTR) GPIO

Quectel BG77 additionally:

syspropdescription
quectel_bg77_first_rx_timeout_sfirst-packet check in seconds, 0 = off (default 90)
quectel_bg77_enable_cmux1 = run AT and PPP over a 27.010 multiplexer; needs a baudrate of at most 460800
quectel_bg77_start_spread_safter power-on (not after a software reboot) wait U(0, n) s before switching the modem on (default 0)
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
structgsm_modem_init_t
GSM modem initialization parameters.
structgsm_signal_info_t
Signal Strength Information.
structgsm_registration_info_t
Serving-cell registration information.
structgsm_modem_counters_t
Counters of the modem driver over the sliding last 24 h.
structgsm_modem_link_info_t
Snapshot of the link, from the driver's cache.
structgsm_modem_driver
enumgsm_technology_t
Modem Radio Access Technology (RAT).
enumapn_auth_t
APN Authentication Type for PPP.

Functions Overview ​

Name
intgsm_modem_init(int hdev, gsm_modem_init_t * init)
Initialize the modem.
intgsm_modem_reset(int hdev)
Requests a modem reset.
intgsm_modem_rf_on(int hdev)
activates the radio interface of the modem
intgsm_modem_rf_off(int hdev)
turns the radio interface of the modem off
intgsm_modem_sleep(int hdev)
puts the modem in power save mode immediately
intgsm_modem_wakeup(int hdev)
wakes the modem from PSM sleep immediately
intgsm_modem_connect(int hdev, int wait)
Dials the data call and brings up the PPP session for the APN's PDP context.
intgsm_modem_disconnect(int hdev)
Tears the PPP session down and disconnects the modem from the APN.
intgsm_modem_connected(int hdev)
checks the modem's current connection status in the PS domain
intgsm_modem_registered(int hdev)
checks the modem's current registration status
intgsm_modem_imei(int hdev, char * imei)
Reads the modem's device identifier (IMEI).
intgsm_modem_imsi(int hdev, char * imsi)
Reads the SIM's subscriber identity (IMSI).
intgsm_modem_iccid(int hdev, char * iccid)
Reads the SIM's card identity (ICCID).
intgsm_modem_signal_quality(int hdev, gsm_signal_info_t * info)
Reads the current signal quality from the modem.
intgsm_modem_sim_status(int hdev)
Get the status of the SIM card in the GSM modem.
intgsm_modem_registration_info(int hdev, gsm_registration_info_t * info)
Reads the serving cell's identity (MCC/MNC, area code, cell id, RAT).
intgsm_modem_version(int hDev, char * version, size_t version_len)
Retrieves the modem's firmware/version string.
intgsm_modem_power_off(int hDev)
Power down the modem.
intgsm_modem_power_on(int hdev)
Power on the modem.
intgsm_modem_note_data_ok(int hdev)
Report that user data provably crossed the data path.
intgsm_modem_note_data_lost(int hdev)
Report that the data path is not carrying traffic any more.
intgsm_modem_set_contact_interval(int hdev, uint32_t interval_ms)
Tell the driver the contact interval announced to the backend.
intgsm_modem_note_data_pending(int hdev)
Report that a send expecting an answer just went out.
intgsm_modem_net_events(int hdev, char * buf, size_t len, uint32_t * seq)
The last network events as text, newest first.
intgsm_modem_counters(int hdev, gsm_modem_counters_t * out)
Counters over the sliding last 24 h (see gsm_modem_counters_t).
intgsm_modem_link_info(int hdev, gsm_modem_link_info_t * out)
Link snapshot from the driver's cache (see gsm_modem_link_info_t).

Defines ​

Name
GSM_MODEM_RUNG_DATA_STALL_MSGuardian (ms after the last answered round trip): rebuild PPP.
GSM_MODEM_RUNG_REATTACH_MSGuardian (ms after the last answered round trip): detach and re-attach, fresh PDP context.
GSM_MODEM_RUNG_DATA_RESET_MSGuardian (ms after the last answered round trip): reset the modem.
GSM_MODEM_RUNG_REST_RESET_MSGuardian: interval from one modem reset to the next while no IP packets arrive.
GSM_MODEM_RUNG_REBOOT_MSFormer reboot rung, 30 min after the last answered round trip.
GSM_MODEM_RUNG_MODEM_RESET_MSNot registered: reset the modem after this long unregistered and not searching.
GSM_MODEM_RUNG_CEILING_MSNot registered: modem reset regardless of CEREG.
GSM_MODEM_IMEI_MAXLEN
GSM_MODEM_IMSI_MAXLEN
GSM_MODEM_ICCID_MAXLEN
GSM_MODEM_IMEI_SIZERequired buffer size for gsm_modem_imei, including the terminating null byte.
GSM_MODEM_IMSI_SIZERequired buffer size for gsm_modem_imsi, including the terminating null byte.
GSM_MODEM_ICCID_SIZERequired buffer size for gsm_modem_iccid, including the terminating null byte.
GSM_MODEM_NET_EVENTS_SIZEBuffer size that holds the whole text of gsm_modem_net_events.
GSM_MODEM_HAS_NET_EVENTSDefined when gsm_modem_net_events is available.
GSM_MODEM_INIT_DEFAULTDefault init parameters for GSM modem, setting it to LTE Cat-M1 (eMTC) on the driver's default bands.
GSM_SIGNAL_UNKNOWNValue of a field the module did not report.
GSM_SIGNAL_NO_MEASUREMENTThe module answered, but has no usable measurement right now.
GSM_MODEM_HAS_CONTACT_INTERVALDefined when gsm_modem_set_contact_interval and gsm_modem_note_data_pending are available.
GSM_MODEM_HAS_COUNTERSDefined when gsm_modem_counters and gsm_modem_link_info are available.
GSM_MODEM_PDP_NORMALState of the data session back-off (gsm_modem_counters_t::pdp_state).
GSM_MODEM_PDP_BACKOFFfailed setups with a network cause, waiting per the ladder
GSM_MODEM_PDP_SUSPECTSIM suspected blocked, attempts every 6 h.
GSM_MODEM_PDP_T3396network back-off timer (ESM #26) running
GSM_MODEM_RRC_NONESource of gsm_modem_counters_t::rrc.
GSM_MODEM_RRC_ESTIMATEestimated from IP activity (20 s inactivity)
GSM_MODEM_RRC_MODEMreported by the modem (+CSCON / +QCSCON)
GSM_MODEM_RAT_UNKNOWNAccess technology in gsm_modem_link_info_t::rat.
GSM_MODEM_RAT_EMTC
GSM_MODEM_RAT_NBIOT
GSM_MODEM_RAT_LTE
GSM_MODEM_RAT_GSM
GSM_MODEM_BACKOFF_NONEWhy the driver is holding back (gsm_modem_link_info_t::backoff).
GSM_MODEM_BACKOFF_PDP
GSM_MODEM_BACKOFF_PDP_SUSPECT
GSM_MODEM_BACKOFF_T3396
GSM_MODEM_BACKOFF_REJECT
GSM_MODEM_BACKOFF_ATTACH_BUDGET

Types Documentation ​

enum gsm_technology_t ​

EnumeratorDescription
gtNBIOTLTE Cat-NB1 / Cat-NB2 (NB-IoT) only.
gtEMMCLTE Cat-M1 (eMTC) only.
gtEMMC_NBIOTCat-M1 preferred, then NB-IoT.
gtNBIOT_EMMCNB-IoT preferred, then Cat-M1.
gtGSM2G (GPRS/EDGE); module-dependent
gtLTELTE Cat 1+ (E-UTRAN); module-dependent.

Modem Radio Access Technology (RAT).

Which values a given module honours is driver-dependent; the Quectel BG77 supports Cat-M1 and NB-IoT only and ignores the others. (The EMMC spelling in the enumerators is historic; the technology is eMTC / LTE Cat-M1.)

enum apn_auth_t ​

EnumeratorDescription
atNONENo Authentication required.
atPAPPAP Authentication only.
atCHAPCHAP Authentication only.
atPAPCHAPBoth 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. -1 is also returned while a previously requested modem reset is still executing — back off and call again.

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

The structure behind init must stay valid for the lifetime of the device; the driver keeps a reference.

function gsm_modem_reset ​

cpp
int gsm_modem_reset(
    int hdev
)

Requests a modem reset.

Parameters:

Return: 0 if the request was accepted or deliberately suppressed, -1 if the driver could not take it at all

The reset is requested, not executed synchronously, and the request may deliberately be dropped:

  • It is refused while the modem reports CEREG=2 (actively searching for a network). Interrupting a PLMN search restarts it from zero; on a roaming VPLMN a cold search legitimately takes 30-60 minutes, and with COPS=0 the module is free to pick a different operator afterwards.
  • It is rate-limited by the driver's existing reset backoff and circuit breaker, so a caller polling in a loop cannot produce a reset storm.
  • It goes through the driver's action gate: no reset while the data session back-off suspects a blocked SIM, while T3396 runs, while a registration reject is backed off, once the attach budget is used up, and none while IP packets arrive (then at most a PPP rebuild per hour).

When the request is carried out, the driver tears the PPP session down under its own lock and discards the cached modem state first — unlike the bare pin reset this call used to perform.

If the modem was connected to the PS domain, 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:

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:

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:

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:

Return: 0 on success, -1 on failure

function gsm_modem_connect ​

cpp
int gsm_modem_connect(
    int hdev,
    int wait
)

Dials the data call and brings up the PPP session for the APN's PDP context.

Parameters:

  • hdev device handle as returned by open(const char*)
  • wait 1 = block until the connection succeeds or fails, 0 = return immediately

Return: 0 on success (with wait == 0: dial accepted, PPP coming up). -1 if the driver is not ready, not registered (wait == 0), the attach failed (wait == 1) or the data session back-off holds the next attempt (the driver dials on its own when it ends); -3 if the dial itself failed.

wait only controls the waiting, not what is started: the dial and the PPP bring-up are initiated in both modes.

  • wait == 1: requires network registration (blocks for the attach if necessary) and returns once the connection either succeeded or failed.
  • wait == 0: never blocks. Requires the modem to be registered already (-1 otherwise); 0 means "dialled, PPP is coming up" — poll gsm_modem_connected(int) for the outcome.

A successful call also arms the driver's autonomous supervision: from here on it re-establishes the session and escalates along the recovery rungs on its own until gsm_modem_disconnect is called.

function gsm_modem_disconnect ​

cpp
int gsm_modem_disconnect(
    int hdev
)

Tears the PPP session down and disconnects the modem from the APN.

Parameters:

Return: 0 on success (including "nothing to tear down"), -1 if the modem is in PSM sleep.

Also aborts a connection attempt that is still in progress and disarms the driver's autonomous reconnect — this call is the only "user disconnect" the driver knows.

function gsm_modem_connected ​

cpp
int gsm_modem_connected(
    int hdev
)

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

Parameters:

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

Reflects the driver's session state (PPP up, PDP context active) — not proof that data actually flows; see the group notes on data-path evidence.

function gsm_modem_registered ​

cpp
int gsm_modem_registered(
    int hdev
)

checks the modem's current registration status

Parameters:

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
)

Reads the modem's device identifier (IMEI).

Parameters:

  • hdev device handle as returned by open(const char*)
  • imei buffer of at least GSM_MODEM_IMEI_SIZE bytes, allocated by the caller. Filled with the device identifier ("IMEI") and null-terminated on success.

Return: 0 on success, -1 on failure

function gsm_modem_imsi ​

cpp
int gsm_modem_imsi(
    int hdev,
    char * imsi
)

Reads the SIM's subscriber identity (IMSI).

Parameters:

  • hdev device handle as returned by open(const char*)
  • imsi buffer of at least GSM_MODEM_IMSI_SIZE bytes, allocated by the caller. Filled with the subscriber identity ("IMSI") and null-terminated on success.

Return: 0 on success, -1 on failure

function gsm_modem_iccid ​

cpp
int gsm_modem_iccid(
    int hdev,
    char * iccid
)

Reads the SIM's card identity (ICCID).

Parameters:

  • hdev device handle as returned by open(const char*)
  • iccid buffer of at least GSM_MODEM_ICCID_SIZE bytes, allocated by the caller. Filled with the card identity ("ICCID") and null-terminated on 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
)

Reads the current signal quality from the modem.

Parameters:

Return: 0 when the reading is complete and plausible, GSM_SIGNAL_NO_MEASUREMENT when the module answered without a usable measurement, a negative AT_* code when the transaction itself failed. Only a 0 may be aged into a quality estimate; the other two cases say "unknown", not "unchanged".

Issues an AT transaction on the calling thread — see the group notes on blocking behaviour.

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
)

Reads the serving cell's identity (MCC/MNC, area code, cell id, RAT).

Parameters:

Return: 0 on success, -1 on failure

Issues an AT transaction on the calling thread — see the group notes on blocking behaviour.

function gsm_modem_version ​

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

Retrieves the modem's firmware/version string.

Parameters:

  • hDev device handle as returned by open(const char*)
  • version Buffer that receives the version string (null-terminated on success).
  • version_len Capacity of version in bytes.

Return: 0 on success, -1 on failure.

function gsm_modem_power_off ​

cpp
int gsm_modem_power_off(
    int hDev
)

Power down the modem.

Parameters:

Return: 0 on success, -1 on failure.

function gsm_modem_power_on ​

cpp
int gsm_modem_power_on(
    int hdev
)

Power on the modem.

Parameters:

Return: 0 on success, -1 on failure.

function gsm_modem_note_data_ok ​

cpp
int gsm_modem_note_data_ok(
    int hdev
)

Report that user data provably crossed the data path.

Parameters:

Return: 0 on success, -1 if the device does not support the report.

Call this whenever a round trip has been ANSWERED by a peer — not when a datagram was handed to the stack. Only an answer proves that packets reach the network and come back.

The driver cannot obtain this evidence itself: it has no peer, and with ATD*99***1# the PPP link terminates inside the modem, so LCP echo only proves the module is alive. Without this report the driver cannot tell a healthy session from one that is registered, has an active PDP context and an IP address, and still moves nothing.

The caller must guarantee a cadence well below the 5-minute evidence-freshness window that feeds GSM_MODEM_RUNG_DATA_STALL_MS, otherwise a healthy but quiet link is mistaken for a dead one. libcoldwave does this by writing P_UPTIME unconditionally every 2 minutes, or, once the backend has confirmed a contact interval, by announcing it (gsm_modem_set_contact_interval).

Cheap and lock-free; safe to call from any thread.

function gsm_modem_note_data_lost ​

cpp
int gsm_modem_note_data_lost(
    int hdev
)

Report that the data path is not carrying traffic any more.

Parameters:

Return: 0 on success, -1 if the device does not support the report.

The counterpart to gsm_modem_note_data_ok. Call this only after your own cheaper repair has already failed — a rebuilt socket, a fresh handshake. The driver treats it as "the layer that can see the peer says it is broken, and it has already tried what it can", and rebuilds the PPP session and the PDP context.

This is the fast path. Without it the driver can only wait for the positive evidence to rot, which takes GSM_MODEM_RUNG_DATA_STALL_MS — a bound sized for the quietest possible reporter and therefore far too slow for one that talks. With it, detection to action is roughly a minute.

Repeat calls are cheap and idempotent: the driver enforces its own minimum spacing between rebuilds (2 min, doubling up to 1 h while they keep not helping), because from down here a dead backend and a dead bearer look exactly alike. While IP packets keep arriving the bearer carries, and at most one rebuild per hour happens.

function gsm_modem_set_contact_interval ​

cpp
int gsm_modem_set_contact_interval(
    int hdev,
    uint32_t interval_ms
)

Tell the driver the contact interval announced to the backend.

Parameters:

  • interval_ms 0 = back to the evidence window.

Return: 0 on success, -1 if the device does not support it.

Without this call the guardian expects gsm_modem_note_data_ok within the evidence window (5 min, 25 min on NB-IoT), which needs a heartbeat. With an interval the guardian judges the path by unanswered sends instead: evidence only goes stale when a send reported with gsm_modem_note_data_pending stays unanswered for clamp(2 x interval, 5 min, 90 min); a quiet, healthy device is never touched. Call it only once the backend has confirmed the interval (flake CONTACT_INTERVAL echo), and again with 0 when it is gone.

Cheap and lock-free; safe to call from any thread.

function gsm_modem_note_data_pending ​

cpp
int gsm_modem_note_data_pending(
    int hdev
)

Report that a send expecting an answer just went out.

Return: 0 on success, -1 if the device does not support it.

Only the first call after the last gsm_modem_note_data_ok counts; repeat calls are cheap. Has an effect only with a contact interval set (gsm_modem_set_contact_interval).

Cheap and lock-free; safe to call from any thread.

function gsm_modem_net_events ​

cpp
int gsm_modem_net_events(
    int hdev,
    char * buf,
    size_t len,
    uint32_t * seq
)

The last network events as text, newest first.

Parameters:

Return: length of the text, -1 if the device keeps no log.

One line per event: UTC time, event, cause, network, RAT, band, TAC/CI and RSRP/SINR of the cell it happened on, e.g.

09-30 12:01:25 REJ#15 262-02 M B20 AC09/32D1403 -102/10

Events: REG registered, LOST registration lost, REJ rejected (EMM cause), NWDEACT / NWDETACH bearer ended / detached by the network with the registration or the data session lost (ESM / EMM cause when readable), NWDEACT0 / NWDET0 the same without effect on either, judged 10 s later (a network may detach only non-EPS services while roaming), PPP session ended by itself (PPPERR_* code), DEAD fresh session that never answered DNS or NTP, PDP / AUTH data session could not be set up (ESM cause if the modem reports one), PDPBLK SIM suspected blocked, attempts only every 6 h. Repeats of the same event are counted ("x3").

The log keeps the last few events and survives a software reboot, so an outage can still be read after the device is back. Publish it when seq changes.

function gsm_modem_counters ​

cpp
int gsm_modem_counters(
    int hdev,
    gsm_modem_counters_t * out
)

Counters over the sliding last 24 h (see gsm_modem_counters_t).

Return: 0 on success, -1 if the device keeps no counters.

Cheap, no AT command, safe from any thread.

cpp
int gsm_modem_link_info(
    int hdev,
    gsm_modem_link_info_t * out
)

Link snapshot from the driver's cache (see gsm_modem_link_info_t).

Return: 0 on success, -1 if the device does not support it.

Cheap, no AT command, safe from any thread.

Macros Documentation ​

define GSM_MODEM_RUNG_DATA_STALL_MS ​

cpp
#define GSM_MODEM_RUNG_DATA_STALL_MS (480000U)   /* 8 min */

Guardian (ms after the last answered round trip): rebuild PPP.

define GSM_MODEM_RUNG_REATTACH_MS ​

cpp
#define GSM_MODEM_RUNG_REATTACH_MS (900000U)     /* 15 min */

Guardian (ms after the last answered round trip): detach and re-attach, fresh PDP context.

define GSM_MODEM_RUNG_DATA_RESET_MS ​

cpp
#define GSM_MODEM_RUNG_DATA_RESET_MS (1320000U)  /* 22 min */

Guardian (ms after the last answered round trip): reset the modem.

define GSM_MODEM_RUNG_REST_RESET_MS ​

cpp
#define GSM_MODEM_RUNG_REST_RESET_MS (1800000U)  /* 30 min */

Guardian: interval from one modem reset to the next while no IP packets arrive.

With packets the following intervals are 50, 100 and then 200 min.

define GSM_MODEM_RUNG_REBOOT_MS ​

cpp
#define GSM_MODEM_RUNG_REBOOT_MS (1800000U)      /* 30 min */

Former reboot rung, 30 min after the last answered round trip.

The driver no longer reboots. Kept so that layers with their own deadman keep it above the driver's ladder: place it above GSM_MODEM_RUNG_REBOOT_MS << 3.

define GSM_MODEM_RUNG_MODEM_RESET_MS ​

cpp
#define GSM_MODEM_RUNG_MODEM_RESET_MS (1800000U) /* 20 ticks of 90 s */

Not registered: reset the modem after this long unregistered and not searching.

define GSM_MODEM_RUNG_CEILING_MS ​

cpp
#define GSM_MODEM_RUNG_CEILING_MS (7200000U)     /* 80 ticks of 90 s */

Not registered: modem reset regardless of CEREG.

define GSM_MODEM_IMEI_MAXLEN ​

cpp
#define GSM_MODEM_IMEI_MAXLEN 20

define GSM_MODEM_IMSI_MAXLEN ​

cpp
#define GSM_MODEM_IMSI_MAXLEN 20

define GSM_MODEM_ICCID_MAXLEN ​

cpp
#define GSM_MODEM_ICCID_MAXLEN 20

define GSM_MODEM_IMEI_SIZE ​

cpp
#define GSM_MODEM_IMEI_SIZE (GSM_MODEM_IMEI_MAXLEN + 1)

Required buffer size for gsm_modem_imei, including the terminating null byte.

define GSM_MODEM_IMSI_SIZE ​

cpp
#define GSM_MODEM_IMSI_SIZE (GSM_MODEM_IMSI_MAXLEN + 1)

Required buffer size for gsm_modem_imsi, including the terminating null byte.

define GSM_MODEM_ICCID_SIZE ​

cpp
#define GSM_MODEM_ICCID_SIZE (GSM_MODEM_ICCID_MAXLEN + 1)

Required buffer size for gsm_modem_iccid, including the terminating null byte.

define GSM_MODEM_NET_EVENTS_SIZE ​

cpp
#define GSM_MODEM_NET_EVENTS_SIZE (440)

Buffer size that holds the whole text of gsm_modem_net_events.

define GSM_MODEM_HAS_NET_EVENTS ​

cpp
#define GSM_MODEM_HAS_NET_EVENTS (1)

Defined when gsm_modem_net_events is available.

define GSM_MODEM_INIT_DEFAULT ​

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

Default init parameters for GSM modem, setting it to LTE Cat-M1 (eMTC) on the driver's default bands.

define GSM_SIGNAL_UNKNOWN ​

cpp
#define GSM_SIGNAL_UNKNOWN (-2147483647 - 1)

Value of a field the module did not report.

Not every answer carries every field: the Quectel modules reply to AT+QCSQ with the system mode alone when there is no service, with mode plus RSSI on GSM, and with all four values only on the LTE modes. A field that stays at this value was not measured; 0 is not a substitute, because 0 is a plausible-looking reading for RSSI and an excellent one for RSRQ.

define GSM_SIGNAL_NO_MEASUREMENT ​

cpp
#define GSM_SIGNAL_NO_MEASUREMENT (1)

The module answered, but has no usable measurement right now.

Distinct from a failed transaction (negative AT_* codes): the AT channel worked, the radio just has nothing to report. Positive so that callers testing for !=0 keep their previous behaviour.

define GSM_MODEM_HAS_CONTACT_INTERVAL ​

cpp
#define GSM_MODEM_HAS_CONTACT_INTERVAL (1)

Defined when gsm_modem_set_contact_interval and gsm_modem_note_data_pending are available.

define GSM_MODEM_HAS_COUNTERS ​

cpp
#define GSM_MODEM_HAS_COUNTERS (1)

Defined when gsm_modem_counters and gsm_modem_link_info are available.

define GSM_MODEM_PDP_NORMAL ​

cpp
#define GSM_MODEM_PDP_NORMAL (0)

State of the data session back-off (gsm_modem_counters_t::pdp_state).

define GSM_MODEM_PDP_BACKOFF ​

cpp
#define GSM_MODEM_PDP_BACKOFF (1)

failed setups with a network cause, waiting per the ladder

define GSM_MODEM_PDP_SUSPECT ​

cpp
#define GSM_MODEM_PDP_SUSPECT (2)

SIM suspected blocked, attempts every 6 h.

define GSM_MODEM_PDP_T3396 ​

cpp
#define GSM_MODEM_PDP_T3396 (3)

network back-off timer (ESM #26) running

define GSM_MODEM_RRC_NONE ​

cpp
#define GSM_MODEM_RRC_NONE (0)

Source of gsm_modem_counters_t::rrc.

define GSM_MODEM_RRC_ESTIMATE ​

cpp
#define GSM_MODEM_RRC_ESTIMATE (1)

estimated from IP activity (20 s inactivity)

define GSM_MODEM_RRC_MODEM ​

cpp
#define GSM_MODEM_RRC_MODEM (2)

reported by the modem (+CSCON / +QCSCON)

define GSM_MODEM_RAT_UNKNOWN ​

cpp
#define GSM_MODEM_RAT_UNKNOWN (0)

Access technology in gsm_modem_link_info_t::rat.

define GSM_MODEM_RAT_EMTC ​

cpp
#define GSM_MODEM_RAT_EMTC (1)

define GSM_MODEM_RAT_NBIOT ​

cpp
#define GSM_MODEM_RAT_NBIOT (2)

define GSM_MODEM_RAT_LTE ​

cpp
#define GSM_MODEM_RAT_LTE (3)

define GSM_MODEM_RAT_GSM ​

cpp
#define GSM_MODEM_RAT_GSM (4)

define GSM_MODEM_BACKOFF_NONE ​

cpp
#define GSM_MODEM_BACKOFF_NONE (0)

Why the driver is holding back (gsm_modem_link_info_t::backoff).

Only holds the network asked for are reported. The short pause after a setup failure without a network cause (5 s to 5 min) is GSM_MODEM_BACKOFF_NONE.

define GSM_MODEM_BACKOFF_PDP ​

cpp
#define GSM_MODEM_BACKOFF_PDP (1)

define GSM_MODEM_BACKOFF_PDP_SUSPECT ​

cpp
#define GSM_MODEM_BACKOFF_PDP_SUSPECT (2)

define GSM_MODEM_BACKOFF_T3396 ​

cpp
#define GSM_MODEM_BACKOFF_T3396 (3)

define GSM_MODEM_BACKOFF_REJECT ​

cpp
#define GSM_MODEM_BACKOFF_REJECT (4)

define GSM_MODEM_BACKOFF_ATTACH_BUDGET ​

cpp
#define GSM_MODEM_BACKOFF_ATTACH_BUDGET (5)