Latest Version: 0.0.5
This library provides provides you with extra configuration options for the imp006’s BG96 modem.
The code for this library is private and is not disclosed. It is included here to provide customers using the library with documentation.
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 the object BG96_Modem directly.
Configure the BG96 to support GSM/EDGE, LTE Cat-M and NB networks with a preferred order. “RAT” is short for “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.
| Parameter | Type | Required? | Description |
|---|---|---|---|
| rats | String | Yes | RATs to be enabled on modem at next boot, in order of preference. See options, below |
| callback | Function | No | Callback to be called on success or failure |
| rats Value | 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. Separate RATs with 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. 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 If you configure NB networks, you should also configure the bands supported otherwise a network search can take multiple hours.
Nothing — return values are via the callback. The 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.
Configure the radio bands the BG96 will scan for each RAT.
| 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 three comma-separated parts. 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 with the formula (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". As Cat-M is not being used, the default band set is specified here.
Note 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.
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 five minutes to around five seconds.
Generally, a device that makes short connections should periodically — say, 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.
This call will block for around 2.4 seconds. The modem must be powered up.
None
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 (for example, the modem is not powered up), it will return false.
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.
| 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