|
CellularHelper
|
A library to access useful things from the Electron, E Series, Boron, and B Series cellular modem
The full API documentation can be found here.
The Github repository for this library is now: https://github.com/particle-iot/CellularHelper.
The simple information calls query information from the modem and return a String.
These are all just various bits of data from the modem or the SIM card.
You might find the ICCID (SIM Number) to be useful as well.
Cellular.on() needs to have been called, which happens automatically in automatic mode (the default).
Note that if you are using SYSTEM_THREAD(ENABLED) or SYSTEM_MODE(SEMI_AUTOMATIC) or SYSTEM_MODE(MANUAL) you must also wait after turning the modem on. 4 seconds should be sufficient, because Cellular.on() is asynchronous and there's no call to determine if has completed yet. Instead of a delay, you could also use cellular_on(NULL) which blocks until the modem is turned on.
For full information about these commands, consult the API documentation which describes these functions in much more detail.
These functions can only be used after connecting to the cellular network.
Returns a string containing the operator name, for example AT&T or T-Mobile in the United States.
Example output:
The operator name is not available on LTE Cat M1 devices (SARA-R410M-02-B).
Returns the RSSI (signal strength) value and a quality value.
The RSSI is in dBm, the standard measure of signal strength. It's a negative value, and values closer to 0 are higher signal strength. There is more information in the API documentation.
The quality value is 0 (highest quality) to 7 (lowest quality) or 99 if the value unknown. It's typically 99 for 2G connections. The qual value is described in the u-blox documentation, and it's returned by the call, but you probably won't need to use it.
The rssiToBars() method converts the RSSI to a 0 to 5 bars, where 5 is the strongest signal.
The CellularHelper.getExtendedQualResponse() is available on LTE Cat M1 devices and returns LTE specific parameters like the RSRP. You can find more information here.
The method getEnvironment returns cell tower information. The is the u-blox AT+CGED command.
The first line declares a variable to hold up to 8 neighbor towers.
The first getEnvironment call tries to get the serving cell (the one you're connected to) and the neighbor cells. This only works for me on the 2G (G350) Electron.
If that fails, it will try again only using the serving cell information.
This sample just prints the information to serial debug:
Note that the rssi will always be 0 for 3G towers. This information is only returned by the AT+CGED command for 2G towers. You can use getRSSIQual() to get the RSSI for the connected tower; that works for 3G.
This function returns the location of the Electron, using cell tower location. This call may take 10 seconds to complete!
The locResp contains the member variables:
This only works on 2G/3G devices, and a better alternative in most cases is to use the google-maps-device-locator to do the location query on the cloud-side instead of on-device.
The simple demo tests all of the basic functions in the library, displaying the results to USB serial.
The code examples in this document were taken from this example.
This is a demo program that uses the cellular modem to scan for available operators, frequency band used, and signal strength. It prints a result like this to USB serial:
It should work even when you can't connect to a tower and also display carriers that are not supported by your SIM. (It only displays carriers compatible with the GSM modem, however, so it won't, for example, display Verizon in the United States since that requires a PCS modem.)
This is a very time consuming operation (it can take 2 minutes or longer to run) and it's pretty rarely needed, so it builds on the CellularHelper library but the commands it uses (AT+COPS and AT+COPN) are not part of the library itself because they're so rarely needed.
To build a binary for this, you can download the repository and use the Particle CLI compiler from the top level of it:
Then you can flash it to your Electron in DFU mode (blinking yellow):
The 3-select-carrier example shows how to prefer a certain carrier when multiple carriers are supported by the SIM card.
cellular_on(NULL) or Cellular.on() (see comments in the code).The 2-show-carriers example prints out the MCC/MNC for carriers at your location.
On a cold boot, you might see something like this in the USB serial debug log:
Then, later:
If you do a warm boot after setting:
This demo uses the u-blox Cell Locate feature to find the latitude, longitude, and elevation of the device.
This only works on 2G and 3G devices, not LTE Cat M1. Another alternative is to use google-maps-device-locator which works on all devices, and is also generally much faster.
Previously getting the cell tower information required a variety of techniques that depended on the cellular modem and generation of device. In Device OS 1.2.1 and later, it's now easy to query this information from Device OS. This example shows how.
1.8.17