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) const
	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`
	)		const

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

str	The String object to append to
buf	The buffer to copy from. Does not need to be null terminated.
len	The 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

resp	Filled 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

mode	is 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

resp	Filled 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

timeoutMs timeout 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

type	one of 13 different enumerated AT command response types.
buf	a pointer to the character array containing the AT command response.
len	length of the AT command response buf.
param	a 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

mccMnc The 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:

src/CellularHelper.h
src/CellularHelper.cpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ appendBufferToString()

◆ getCREG()

◆ getEnvironment()

◆ getExtendedQual()

◆ getICCID()

◆ getIMEI()

◆ getLocation()

◆ getOperatorName()

◆ getRSSIQual()

◆ isLTE()

◆ responseCallback()

◆ rssiToBars()

◆ selectOperator()

Field Documentation

◆ DEFAULT_TIMEOUT

◆ ENVIRONMENT_SERVING_CELL

◆ ENVIRONMENT_SERVING_CELL_AND_NEIGHBORS

◆ OPERATOR_NAME_NUMERIC