CellularHelper
Public Member Functions | Static Public Member Functions | Static Public Attributes
CellularHelperClass Class Reference

Class for calling the u-blox SARA modem directly. More...

#include <CellularHelper.h>

Public Member Functions

String getManufacturer () const
 Returns a string, typically "u-blox".
 
String getModel () const
 Returns a string like "SARA-G350", "SARA-U260" or "SARA-U270".
 
String getOrderingCode () const
 Returns a string like "SARA-U260-00S-00".
 
String getFirmwareVersion () const
 Returns a string like "23.20".
 
String getIMEI () const
 Returns the IMEI for the modem. More...
 
String getIMSI () const
 Returns the IMSI for the modem.
 
String getICCID () const
 Returns the ICCID for the SIM card. More...
 
bool isLTE () const
 Returns true if the device is LTE Cat-M1 (deprecated method) More...
 
bool isSARA_R4 () const
 Returns true if the device is a u-blox SARA-R4 model (LTE-Cat M1)
 
String getOperatorName (int operatorNameType=OPERATOR_NAME_LONG_EONS) const
 Returns the operator name string, something like "AT&T" or "T-Mobile" in the United States (2G/3G only) More...
 
CellularHelperRSSIQualResponse getRSSIQual () const
 Get the RSSI and qual values for the receiving cell site. More...
 
CellularHelperExtendedQualResponse getExtendedQual () const
 Gets extended quality information on LTE Cat M1 devices (SARA-R410M-02B) (AT+CESQ) More...
 
bool selectOperator (const char *mccMnc=NULL) const
 Select the mobile operator (in areas where more than 1 carrier is supported by the SIM) (AT+COPS) More...
 
void getEnvironment (int mode, CellularHelperEnvironmentResponse &resp) const
 Gets cell tower information (AT+CGED). Only on 2G/3G, does not work on LTE Cat M1. More...
 
CellularHelperLocationResponse getLocation (unsigned long timeoutMs=DEFAULT_TIMEOUT) const
 Gets the location coordinates using the CellLocate feature of the u-blox modem (AT+ULOC) More...
 
void getCREG (CellularHelperCREGResponse &resp) const
 Gets the AT+CREG (registration info including CI and LAC) as an alternative to AT+CGED. More...
 

Static Public Member Functions

static void appendBufferToString (String &str, const char *buf, int len, bool noEOL=true)
 Append a buffer (pointer and length) to a String object. More...
 
static int responseCallback (int type, const char *buf, int len, void *param)
 Used internally as the Cellular.command callback. More...
 
static int rssiToBars (int rssi)
 Function to convert an RSSI value into "bars" of signal strength (0-5) More...
 

Static Public Attributes

static const system_tick_t DEFAULT_TIMEOUT = 10000
 Default timeout in milliseconds. Passed to Cellular.command(). More...
 
static const int ENVIRONMENT_SERVING_CELL = 3
 Constant for getEnvironment() to get information about the connected cell. More...
 
static const int ENVIRONMENT_SERVING_CELL_AND_NEIGHBORS = 5
 Constant for getEnvironment() to get information about the connected cell and neighbors. More...
 
static const int OPERATOR_NAME_NUMERIC = 0
 Constants for getOperatorName(). Default and recommended value is OPERATOR_NAME_LONG_EONS. More...
 
static const int OPERATOR_NAME_SHORT_ROM = 1
 Short name in ROM.
 
static const int OPERATOR_NAME_LONG_ROM = 2
 Long name in ROM.
 
static const int OPERATOR_NAME_SHORT_CPHS = 3
 Short network operator name (CPHS)
 
static const int OPERATOR_NAME_LONG_CPHS = 4
 Long network operator name (CPHS)
 
static const int OPERATOR_NAME_SHORT_NITZ = 5
 Short NITZ name.
 
static const int OPERATOR_NAME_LONG_NITZ = 6
 Full NITZ name.
 
static const int OPERATOR_NAME_SERVICE_PROVIDER = 7
 Service provider name.
 
static const int OPERATOR_NAME_SHORT_EONS = 8
 EONS short operator name.
 
static const int OPERATOR_NAME_LONG_EONS = 9
 EONS long operator name.
 
static const int OPERATOR_NAME_SHORT_NETWORK_OPERATOR = 11
 Short network operator name.
 
static const int OPERATOR_NAME_LONG_NETWORK_OPERATOR = 12
 Long network operator name.
 

Detailed Description

Class for calling the u-blox SARA modem directly.

Most of the methods you will need are in this class, and can be referenced using the global CellularHelper object. For example:

String mfg = CellularHelper.getManufacturer();

Member Function Documentation

◆ appendBufferToString()

void CellularHelperClass::appendBufferToString ( String &  str,
const char *  buf,
int  len,
bool  noEOL = true 
)
static

Append a buffer (pointer and length) to a String object.

Used internally to add data to a String object with buffer and length, which is not one of the built-in overloads for String. This format is what comes from the Cellular.command callbacks.

Parameters
strThe String object to append to
bufThe buffer to copy from. Does not need to be null terminated.
lenThe number of bytes to copy.
noEOL(default: true) If true, don't copy CR and LF characters to the output.

◆ getCREG()

void CellularHelperClass::getCREG ( CellularHelperCREGResponse resp) const

Gets the AT+CREG (registration info including CI and LAC) as an alternative to AT+CGED.

Parameters
respFilled in with the response data

Note: This has limited support and using the CellularGlobalIdentity in Device OS 1.2.1 and later is the preferred method to get the CI and LAC. This function will be deprecated in the future.

Modem Device Device OS Compatible
SARA-G350 Gen 2 < 1.2.1 Yes
SARA-U260 Gen 2 < 1.2.1 Yes
SARA-U270 Gen 2 < 1.2.1 Yes
SARA-U201 Gen 2 < 1.2.1 Yes
SARA-R410M-02B Gen 2 < 1.2.1 Yes
Any Gen 3 Any No
Any Any >= 1.2.1 No

◆ getEnvironment()

void CellularHelperClass::getEnvironment ( int  mode,
CellularHelperEnvironmentResponse resp 
) const

Gets cell tower information (AT+CGED). Only on 2G/3G, does not work on LTE Cat M1.

Parameters
modeis whether to get the serving cell, or serving cell and neighboring cells:
  • ENVIRONMENT_SERVING_CELL - only the cell you're connected to
  • ENVIRONMENT_SERVING_CELL_AND_NEIGHBORS - note: only works on Electron 2G G350, not 3G models
Parameters
respFilled in with the response data.

Note: With Device OS 1.2.1 and later you should use the CellularGlobalIdentity built into Device OS instead of using this method (AT+CGED). CellularGlobalIdentity is much more efficient and works on LTE Cat M1 devices. The 5-cellular-global-identity example shows how to get the CI (cell identifier), LAC (location area code), MCC (mobile country code), and MNC (mobile network code) efficiently using CellularGlobalIdentity.

Modem Device Available Neighbors Available
SARA-G350 Gen 2 Yes Yes
SARA-U260 Gen 2 Yes No
SARA-U270 Gen 2 Yes No
SARA-U201 All Yes No
SARA-R410M-02B All No No

◆ getExtendedQual()

CellularHelperExtendedQualResponse CellularHelperClass::getExtendedQual ( ) const

Gets extended quality information on LTE Cat M1 devices (SARA-R410M-02B) (AT+CESQ)

The response structure contains the following public members:

  • resp - is RESP_OK if the call succeeded or RESP_ERROR on failure
  • rxlev - Received Signal Strength Indication (RSSI)
    • 0: less than -110 dBm
    • 1..62: from -110 to -49 dBm with 1 dBm steps
    • 63: -48 dBm or greater
    • 99: not known or not detectable
  • ber - Bit Error Rate (BER)
    • 0..7: as the RXQUAL values described in GSM TS 05.08 [28]
    • 99: not known or not detectable
  • rscp - Received Signal Code Power (RSCP)
    • 0: -121 dBm or less
    • 1..95: from -120 dBm to -24 dBm with 1 dBm steps
    • 96: -25 dBm or greater
    • 255: not known or not detectable
  • ecn0 - Ratio of received energy per PN chip to the total received power spectral density
    • 0: -24.5 dB or less
    • 1..48: from -24 dB to -0.5 dBm with 0.5 dB steps
    • 49: 0 dB or greater
    • 255: not known or not detectable
  • rsrq - Reference Signal Received Quality (RSRQ)
    • 0: -19 dB or less
    • 1..33: from -19.5 dB to -3.5 dB with 0.5 dB steps
    • 34: -3 dB or greater
    • 255: not known or not detectable Number
  • rsrp - Reference Signal Received Power (RSRP)
    • 0: -141 dBm or less
    • 1..96: from -140 dBm to -45 dBm with 1 dBm steps
    • 97: -44 dBm or greater
    • 255: not known or not detectable

Compatibility:

Modem Device Available
SARA-G350 Gen 2 No
SARA-U260 Gen 2 No
SARA-U270 Gen 2 No
SARA-U201 All No
SARA-R410M-02B All Yes

◆ getICCID()

String CellularHelperClass::getICCID ( ) const

Returns the ICCID for the SIM card.

Both IMEI and ICCID are commonly used identifiers. The IMEI is assigned to the modem itself. The ICCID is assigned to the SIM card.

◆ getIMEI()

String CellularHelperClass::getIMEI ( ) const

Returns the IMEI for the modem.

Both IMEI and ICCID are commonly used identifiers. The IMEI is assigned to the modem itself. The ICCID is assigned to the SIM card.

For countries that require the cellular devices to be registered, the IMEI is typically the number that is required.

◆ getLocation()

CellularHelperLocationResponse CellularHelperClass::getLocation ( unsigned long  timeoutMs = DEFAULT_TIMEOUT) const

Gets the location coordinates using the CellLocate feature of the u-blox modem (AT+ULOC)

Parameters
timeoutMstimeout in milliseconds. Should be at least 10 seconds.

This may take several seconds to execute and only works on Gen 2 2G/3G devices. It does not work on Gen 3 and does not work on LTE M1 (SARA-R410M-02B). In general, we recommend using a cloud-based approach (google-maps-device-locator) instead of using CellLocate.

Compatibility:

Modem Device Compatible
SARA-G350 Gen 2 Yes
SARA-U260 Gen 2 Yes
SARA-U270 Gen 2 Yes
SARA-U201 Gen 2 Yes
SARA-U201 Gen 3 No
SARA-R410M-02B All No

◆ getOperatorName()

String CellularHelperClass::getOperatorName ( int  operatorNameType = OPERATOR_NAME_LONG_EONS) const

Returns the operator name string, something like "AT&T" or "T-Mobile" in the United States (2G/3G only)

Modem Device Compatible
SARA-G350 Gen 2 Yes
SARA-U260 Gen 2 Yes
SARA-U270 Gen 2 Yes
SARA-U201 All Yes
SARA-R410M-02B All No

◆ getRSSIQual()

CellularHelperRSSIQualResponse CellularHelperClass::getRSSIQual ( ) const

Get the RSSI and qual values for the receiving cell site.

The response structure contains the following public members:

  • resp - is RESP_OK if the call succeeded or RESP_ERROR on failure
  • rssi - RSSI Received Signal Strength Indication value
    • 0: -113 dBm or less
    • 1: -111 dBm
    • 2..30: from -109 to -53 dBm with 2 dBm steps
    • 31: -51 dBm or greater
    • 99: not known or not detectable or currently not available
  • qual - Signal quality
    • 0..7: Signal quality, 0 = good, 7 = bad
    • 99: not known or not detectable or currently not available

The qual value is not always available.

Modem Device Qual Available
SARA-G350 Gen 2 No
SARA-U260 Gen 2 Usually
SARA-U270 Gen 2 Usually
SARA-U201 All Usually
SARA-R410M-02B All No

Get the RSSI and qual values for the receiving cell site.

The qual value is always 99 for me on the G350 (2G) and LTE-M1

◆ isLTE()

bool CellularHelperClass::isLTE ( ) const
inline

Returns true if the device is LTE Cat-M1 (deprecated method)

This method is deprecated. You should use isSARA_R4() instead. Included for backward compatibility for now.

◆ responseCallback()

int CellularHelperClass::responseCallback ( int  type,
const char *  buf,
int  len,
void *  param 
)
static

Used internally as the Cellular.command callback.

Parameters
typeone of 13 different enumerated AT command response types.
bufa pointer to the character array containing the AT command response.
lenlength of the AT command response buf.
parama pointer to the variable or structure being updated by the callback function.
Returns
user specified callback return value

◆ rssiToBars()

int CellularHelperClass::rssiToBars ( int  rssi)
static

Function to convert an RSSI value into "bars" of signal strength (0-5)

RSSI Bars
>= -57 5
> -68 4
> -80 3
> -92 2
> -104 1
<= -104 0

5 is strong and 0 is weak.

◆ selectOperator()

bool CellularHelperClass::selectOperator ( const char *  mccMnc = NULL) const

Select the mobile operator (in areas where more than 1 carrier is supported by the SIM) (AT+COPS)

Parameters
mccMncThe MCC/MNC numeric string to identify the carrier. For examples, see the table below.
Returns
true on success or false on error
MCC-MNC Carrier
310410 AT&T
310260 T-Mobile

You must turn cellular on before making this call, but it's most efficient if you don't Cellular.connect() or Particle.connect(). You should use SYSTEM_MODE(SEMI_AUTOMATIC) or SYSTEM_MODE(MANUAL).

If the selected carrier matches, this function return true quickly.

If the carrier needs to be changed it may take 15 seconds or longer for the operation to complete.

Omitting the mccMnc parameter or passing NULL will reset the default automatic mode.

This setting is stored in the modem but reset on power down, so you should set it from setup().

Field Documentation

◆ DEFAULT_TIMEOUT

const system_tick_t CellularHelperClass::DEFAULT_TIMEOUT = 10000
static

Default timeout in milliseconds. Passed to Cellular.command().

Several commands take an optional timeout value and the default value is this.

◆ ENVIRONMENT_SERVING_CELL

const int CellularHelperClass::ENVIRONMENT_SERVING_CELL = 3
static

Constant for getEnvironment() to get information about the connected cell.

This only works on the 2G and 3G Electron, E Series, and Boron. It does not work on LTE Cat M1 (SARA-R410M-02B) models. See getEnvironment() for alternatives.

◆ ENVIRONMENT_SERVING_CELL_AND_NEIGHBORS

const int CellularHelperClass::ENVIRONMENT_SERVING_CELL_AND_NEIGHBORS = 5
static

Constant for getEnvironment() to get information about the connected cell and neighbors.

This only works on the 2G Electron (G350)!

◆ OPERATOR_NAME_NUMERIC

const int CellularHelperClass::OPERATOR_NAME_NUMERIC = 0
static

Constants for getOperatorName(). Default and recommended value is OPERATOR_NAME_LONG_EONS.

In most cases, OPERATOR_NAME_NUMERIC is 6 BCD digits in cccnnn format where (ccc = MCC and nnn = MNC). However, in some countries MNC is only two BCD digits, so in that case it will be cccnn (5 BCD digits). Numeric format of MCC/MNC network (three BCD digit country code and two/three BCD digit network code)


The documentation for this class was generated from the following files:
CellularHelperClass::getManufacturer
String getManufacturer() const
Returns a string, typically "u-blox".
Definition: CellularHelper.cpp:815