BG96_Modem

Library to configure the BG96 modem on imp006.

BG96_Modem Usage

BG96_Modem is a singleton and has no constructor. There is no need to create an instance or initialize. All of the methods listed below should be called on BG96_Modem directly.

BG96_Modem Methods

enableRAT([rats],[callback])

Configure the BG96 to support GSM/EDGE, LTE Cat-M, and NB networks with a preferred order. "RAT" refers to "Radio Access Technology" - a type of cellular network.

If the modem is not powered, this call will power up the modem in order to send the configuration commands and power it off afterwards. If the modem is already powered (for example, because the device has connected over cellular already) then the modem will remain powered after the callback is fired.

Parameters

Parameter	Type	Required	Description
rats	String	Yes	RATs to be enabled on modem at next boot, in order of preference
callback	Function	No	Callback to be called on success or failure

RAT string	Effect
gsm	Modem will attempt to connect via GSM/EDGE networks
catm	Modem will attempt to connect to LTE Cat-M networks
nb	Modem will attempt to connect to LTE NB-IOT networks

The RAT string can specify a single RAT, or multiple RATs in order of preference, with RATs separated by the "+" character; for example the string "catm+gsm" will configure the modem to first attempt Cat-M connections, then fall back to GSM if no Cat-M is found.

Modem configuration is persistent; note that if you (for example) force Cat-M only support and there are no Cat-M networks available, the modem will never fall back to GSM/EDGE and hence in some areas may never come online again (at least until a compatible Cat-M network comes into existence within range).

Note that if you configure NB networks, you should also configure the bands supported otherwise a network search can take multiple hours.

Return Value

Nothing; return values are via the callback. If no callback is specified

Callback is fired with "true" if the RAT was successfully set, and "false" if an error was encountered. The modem configuration will take effect at the next modem power up and is stored in non-volatile memory inside the modem.

setBands([bands],[callback])

Configure the radio bands the BG96 will scan for each RAT.

Parameters

Parameter	Type	Required	Description
bands	String	Yes	Band configuration string
callback	Function	No	Callback to be called on success or failure

The band configuration string is in 3 parts, separated by commas. The first part is the GSM band list, the second is the Cat-M band list and the third is the NB band list.

GSM bands are represented by 0x1 (GSM900), 0x2 (GSM1800), 0x4 (GSM850), 0x8 (GSM1900). Combinations are logical ORs of each desired band, so an example band configuration for the EU might be 0x3, enabling both GSM900 and GSM1800.

Cat-M and NB bands are represented by bits, one per band, calculated like this: (1<< (band number - 1)) - so, band 4 is 0x8, band 20 is 0x80000, and bands 4 and 20 both being enabled is 0x80008.

The default band set is the string "0xf,0x400a0e189f,0xa0e189f".

An example configuration to support GSM900, GSM1800 and NB band 20 would be "0x3,0x400a0e189f,0x80000". Note that as Cat-M is not being used, the default band set is specified here.

Note that if NB is to be used, you should restrict the band set to only the bands required because NB can take hours to perform a band search looking for networks.

forceSuperSimOTA()

Forces the Super SIM to check in with the SIM OTA server for pending updates; when called after a device is successfully connected on cellular, this reduces the time the device needs to spend online in order to start the OTA update from around 5 minutes to around 5 seconds.

Generally, a device that makes short connections should periodically - eg once a week - call this method and then stay online for 60 seconds after it returns success to give the OTA applet time to run.

Note that this call will block for around 2.4 seconds. The modem must be powered up.

Parameters

None

Return Value

Returns true if the trigger was successfully sent. There is currently no way to check the OTA has started (or finished). If errors are encountered during the trigger process (eg modem is not powered up), it will return false.

readBatteryVoltage([callback])

Ask the modem to read the battery voltage; this returns the voltage seen by the modem on its VBAT pin by issuing the AT+CBC command

Parameters

Parameter	Type	Required	Description
callback	Function	No	Callback to be called on success or failure

The callback will be called with the string result of the AT+CBC command, typically looking like this:

+CBC: 0,100,4200

scanNetwork([callback])

Scans for available networks using the AT+COPS=? command. This function queries the modem to return a list of networks that are currently available.

Parameters

Parameter	Type	Required	Description
callback	Function	No	Callback to be called with the result of the network scan.

Callback

The callback function is invoked with the following parameters:

response: The raw string result of the AT+COPS=? command if the operation succeeds.

error: A string describing the error if the operation fails.

If the device is connected to the imp server , the callback will receive the string "Device is connected to the imp server. Disconnect first.".

Example

// Callback to handle the network scan response
function onScan(response, error) {
    if (error != null) {
        server.log("Network Scan Failed: " + error);
    } else {
        server.log("Network Scan Response: " + response);
    }
}    

// Perform a network scan
BG96_Modem.scanNetwork(onScan);

Notes

The response format of AT+COPS=? includes a list of networks with their status
Parsing the response may be necessary to extract specific details about the networks.

readUPLMN([length], [callback])

Reads the UPLMN (User Preferred PLMN) list from the SIM card by issuing the AT+CRSM command. The function dynamically determines the EF size from the SIM card and reads the entire file.

Parameters

Parameter	Type	Required	Description
callback	Function	No	Callback to be called with the result of the read operation.

Description

The function reads the UPLMN EF from the SIM card and decodes it into an array of PLMN records. Each record contains the following fields:

mcc: String, 3-digit Mobile Country Code.
mnc: String, 2- or 3-digit Mobile Network Code.
rat: Integer, A bitmask representing the Radio Access Technologies (RAT).

RAT Constants

The rat field is a bitmask where each bit corresponds to a specific Radio Access Technology (RAT). The following table lists the bit values and their corresponding RAT constants:

Bit Value	Constant	Description
`0x01`	`RAT_UTRAN`	Universal Terrestrial Radio Access Network.
`0x02`	`RAT_E_UTRAN_WB_S1_NB_S1`	LTE in Wideband S1 and Narrowband S1 modes.
`0x04`	`RAT_E_UTRAN_NB_S1`	LTE in Narrowband S1 mode only.
`0x08`	`RAT_E_UTRAN_WB_S1`	LTE in Wideband S1 mode only.
`0x10`	`RAT_NG_RAN`	Next-Generation Radio Access Network (5G).
`0x20`	`RAT_GSM`	Standard GSM.
`0x40`	`RAT_EC_GSM_IOT`	Extended Coverage GSM for IoT.
`0x80`	`RAT_GSM_EC_GSM_IOT`	GSM and Extended Coverage GSM for IoT.
`0x100`	`RAT_GSM_COMPACT`	GSM Compact mode.
`0x200`	`RAT_CDMA2000_HRPD`	CDMA2000 High Rate Packet Data.
`0x400`	`RAT_CDMA2000_1XRTT`	CDMA2000 1x Radio Transmission Technology.

The EF size is dynamically determined using the AT+CRSM=242 command, and the entire file is read using the AT+CRSM=176 command. Empty records (filled with FF) are skipped during decoding.

If the modem is not ready, the callback will receive the string "Modem not ready". If there is an error parsing the UPLMN records, the callback will receive an error message.

The callback function is invoked with the following parameters:

response: An array of decoded PLMN records if the operation succeeds. error: A string describing the error if the operation fails.

Example

// Callback to handle the read response
function onRead(response, error) {
    if (error != null) {
        server.log("Error: " + response);
    } else {
        foreach (record in response) {
            server.log(format("MCC: %s, MNC: %s, RAT: %x", record.mcc, record.mnc, record.rat));
            local ratString = BG96_Modem.RATHexToString(record.rat);
            server.log("Human-Readable RAT: " + ratString);
        }
    }
}

// Read UPLMN records
BG96_Modem.readUPLMN(onRead);

writeUPLMN(records, [callback])

Writes the UPLMN (User Preferred PLMN) list to the SIM card by issuing the AT+CRSM command. The function encodes the provided MCC, MNC, and RAT values into the appropriate format and writes them to the SIM . The maximum writable size is determined from the SIM, and any remaining space is padded with FF.

Parameters

Parameter	Type	Required	Description
records	Array	Yes	An array of objects, where each object represents a PLMN entry with the following fields: - mcc: String, 3-digit Mobile Country Code. - mnc: String, 2- or 3-digit Mobile Network Code. - rat: Integer, A bitfield representing the Radio Access Technologies (RAT). Use predefined constants.
callback	Function	No	Callback to be called with the result of the write operation.

The callback will be called with the string result of the AT+CRSM command. If the modem is not ready, the callback will receive the string "Modem not ready".

RAT Constants

The rat field must be a combination of the following constants (OR-ed together):

LTE (Long-Term Evolution) Modes:

Constant	Description
`RAT_UTRAN`	Universal Terrestrial Radio Access Network.
`RAT_E_UTRAN_WB_S1_NB_S1`	LTE in Wideband S1 and Narrowband S1 modes.
`RAT_E_UTRAN_NB_S1`	LTE in Narrowband S1 mode only.
`RAT_E_UTRAN_WB_S1`	LTE in Wideband S1 mode only.
`RAT_NG_RAN`	Next-Generation Radio Access Network (5G).

GSM (Global System for Mobile Communications) and CDMA Modes:

Constant	Description
`RAT_GSM`	Standard GSM.
`RAT_EC_GSM_IOT`	Extended Coverage GSM for IoT.
`RAT_GSM_EC_GSM_IOT`	GSM and Extended Coverage GSM for IoT.
`RAT_GSM_COMPACT`	GSM Compact mode.
`RAT_CDMA2000_HRPD`	CDMA2000 High Rate Packet Data.
`RAT_CDMA2000_1XRTT`	CDMA2000 1x Radio Transmission Technology.

Notes

The rat field must use predefined constants (e.g., RAT_UTRAN | RAT_GSM) instead of strings.
An error will be returned if the SIM does not support UPLMN.

Example

// Callback to handle the write response
function onWrite(response, error) {
    if (error != null) {
        server.log("Write UPLMN failed: " + error);
    } else {
        server.log("Write UPLMN succeeded. Response: " + response);
    }
}

// Define UPLMN records to write
local uplmnRecords = [
    { "mcc": "310", "mnc": "260", "rat": RAT_UTRAN | RAT_GSM }, // Example record 1
    { "mcc": "311", "mnc": "480", "rat": RAT_E_UTRAN_WB_S1 | RAT_GSM_COMPACT } // Example record 2
];

// Write the UPLMN records
BG96_Modem.writeUPLMN(uplmnRecords, onWrite);

RATHexToString(ratBitmask)

This function can be used to convert the bitmask RAT output from the readUPLMN function into a human-readable, comma-separated string representing the RAT types.

Parameters

Parameter	Type	Required	Description
ratBitmask	Integer	Yes	A bitmask or hex value representing the Radio Access Technologies (RAT).

Description

The function takes a bitmask or hex value representing the RAT and converts it into a human-readable string. Each bit in the bitmask corresponds to a specific RAT type, and the function appends the corresponding RAT name to the output string.

Example

local ratBitmask = RAT_UTRAN | RAT_GSM | RAT_E_UTRAN_WB_S1;
local ratString = BG96_Modem.RATHexToString(ratBitmask);
server.log("Human-Readable RAT: " + ratString);

autoNetworkSelection([callback])

Triggers automatic network re-evaluation by forcing the modem to re-scan and select the best available network based on signal strength. Issues AT+COPS=0 command to put the modem in automatic selection mode.

Parameters

Parameter	Type	Required	Description
callback	Function	No	Callback to be called on success or failure.

Return Value

Callback is fired with "true" if automatic selection was triggered, and "false" if an error was encountered.

manualNetworkSelect(operatorCode,[callback])

Forces the modem to manually select a specific cellular operator using the AT+COPS=1,2,operatorCode command. The modem will NOT fall back to automatic selection if the specified operator becomes unavailable.

Parameters

Parameter	Type	Required	Description
operatorCode	String	Yes	5-6 digit operator code in PLMN format (MCC + MNC). Example: "310410" (AT&T)
callback	Function	No	Callback to be called on success or failure.

Return Value

Callback is fired with "true" if operator selection was set, and "false" if an error was encountered. On failure, the error parameter contains the raw modem response (e.g., +CME ERROR, +COPS, +CEREG) for Quectel support debugging.

Notes

If the specified operator is unavailable, the modem will NOT fall back to other networks
Use manualNetworkSelectWithFallback() if fallback behavior is desired
Operator code must be 5-6 digits (numeric only)

manualNetworkSelectWithFallback(operatorCode,[callback])

Forces the modem to prefer a specific cellular operator, but automatically falls back to the best available network if the preferred operator is unavailable. Issues AT+COPS=4,2,operatorCode command.

Parameters

Parameter	Type	Required	Description
operatorCode	String	Yes	5-6 digit operator code in PLMN format (MCC + MNC). Example: "40402" (Vodafone India)
callback	Function	No	Callback to be called on success or failure.

Return Value

Callback is fired with "true" if mode was set, and "false" if an error was encountered. On failure, the error parameter contains the raw modem response (e.g., +CME ERROR, +COPS, +CEREG) for Quectel support debugging.

Notes

More flexible than manualNetworkSelect() for reliability
Recommended for real-world deployments where operator availability varies

deregisterFromNetwork([callback])

Deregisters the modem from the currently connected network by issuing the AT+COPS=2 command. This is useful for forcing network re-evaluation or switching to a different carrier.

Parameters

Parameter	Type	Required	Description
callback	Function	No	Callback to be called on success or failure.

Return Value

Callback is fired with "true" if deregistration was issued, and "false" if an error was encountered. On failure, the error parameter contains the raw modem response (e.g., +CME ERROR) for Quectel support debugging.

Notes

After deregistration, the modem will gradually attempt to re-register based on its network selection mode
Combine with imp.wakeup() to allow modem time to settle before calling manualNetworkSelect() or autoNetworkSelection()
Does not affect the UPLMN list; use clearRegisteredPLMN() if you need to reset last-known PLMN records

clearRegisteredPLMN([callback])

Clears the SIM's last-registered PLMN records from the EF_LOCI and EF_PSLOCI files. This forces the modem to use the UPLMN (User Preferred PLMN) list on the next boot instead of trying to reconnect to the last-known network.

On power-up, the BG96 modem reads: - EF_LOCI (last CS registered PLMN, file ID 28542, 11 bytes) - EF_PSLOCI (last PS registered PLMN, file ID 28531, 14 bytes)

These are attempted reconnection targets BEFORE the UPLMN list is consulted. Clearing them forces UPLMN-guided automatic selection on next boot — essential for carrier preference workflows using writeUPLMN().

Prerequisites

SIM must permit write access to EF_LOCI/EF_PSLOCI via AT+CRSM=214 command
Most Super SIMs support this; contact your SIM provider if unclear

Parameters

Parameter	Type	Required	Description
callback	Function	No	Callback to be called on success or failure.

Return Value

Callback is fired with "true" if both EF_LOCI and EF_PSLOCI were cleared, and "false" if an error was encountered.

Notes

Only clears EF_LOCI and EF_PSLOCI; does not affect the UPLMN list
Must call this BEFORE writeUPLMN() in carrier switching workflows
Changes take effect on next device power cycle or reboot

Latest Version: 0.1.5

BG96_Modem Usage

BG96_Modem Methods

enableRAT([rats],[callback])

Parameters

Return Value

setBands([bands],[callback])

Parameters

forceSuperSimOTA()

Parameters

Return Value

readBatteryVoltage([callback])

Parameters

scanNetwork([callback])

Parameters

Callback

Example

Notes

readUPLMN([length], [callback])

Parameters

Description

RAT Constants

Example

writeUPLMN(records, [callback])

Parameters

RAT Constants

LTE (Long-Term Evolution) Modes:

GSM (Global System for Mobile Communications) and CDMA Modes:

Notes

Example

RATHexToString(ratBitmask)

Parameters

Description

Example

autoNetworkSelection([callback])

Parameters

Return Value

manualNetworkSelect(operatorCode,[callback])

Parameters

Return Value

Notes

manualNetworkSelectWithFallback(operatorCode,[callback])

Parameters

Return Value

Notes

deregisterFromNetwork([callback])

Parameters

Return Value

Notes

clearRegisteredPLMN([callback])

Prerequisites

Parameters

Return Value

Notes