QuectelTowerRK Class Reference

Class to grab cellular modem and tower information from Quectel cellular modems on Particle devices. More...

#include <QuectelTowerRK.h>

Data Structures
class	CellularNeighbor
	Information identifying a neighboring tower. More...
class	CellularServing
	Information identifying the serving tower. More...
class	TowerInfo
	Container for serving tower and neighbor tower information. More...

Public Types
enum class	CommandCode { None , Measure , Exit }
	Commands to instruct cellular thread, used internally. More...
enum class	RadioAccessTechnology { NONE = -1 , LTE = 7 , LTE_CAT_M1 = 8 , LTE_NB_IOT = 9 }
	Type of radio used in modem to tower communications. More...

Public Member Functions
int	scanBlocking (TowerInfo &towerInfo, unsigned long timeoutMs=10000)
	Scan for towers, blocking.
int	scanWithCallback (std::function< void(TowerInfo towerInfo)> scanCallback)
	Asynchronous scan for cellular towers with callback function.
int	startScan ()
	Start scan for cellular towers.
void	cancelScan ()
	This method makes sure the callback is not called.
int	getSignal (CellularSignal &signal, unsigned int max_age=DEFAULT_MAX_AGE_SEC)
	Get the cellular signal strength.
unsigned int	getSignalUpdate ()
	Get the signal strength age.
void	getTowerInfo (TowerInfo &towerInfo)
	Get the most recently retrieved tower information.
void	lock ()
	Lock object.
void	unlock ()
	Unlock object.

Static Public Member Functions
static RadioAccessTechnology	parseRadioAccessTechnology (const char *str)
	Parse a AT+QENG RAT string to convert it to a RadioAccessTechnology value (an int).
static QuectelTowerRK &	instance ()
	Singleton class instance access for QuectelTowerRK.

Static Public Attributes
static constexpr system_tick_t	PERIOD_SUCCESS_MS {1000}
	Delay between checking cell strength when no errors detected.
static constexpr system_tick_t	PERIOD_ERROR_MS {10000}
	Delay between checking cell strength when errors detected.
static constexpr unsigned int	DEFAULT_MAX_AGE_SEC {10}
	Cell updates need to be at least this often or flagged as an error.

Detailed Description

Class to grab cellular modem and tower information from Quectel cellular modems on Particle devices.

This includes:

• Tracker (Tracker One, Monitor One, Tracker SoM)
• M-SoM (M-SoM, Muon)
• b5som variants of B-SoM (B504e, B524, B523)

Member Enumeration Documentation

CommandCode

enum class QuectelTowerRK::CommandCode

strong

Commands to instruct cellular thread, used internally.

Enumerator
None	Do nothing
Measure	Perform cellular scan
Exit	Exit from thread

RadioAccessTechnology

enum class QuectelTowerRK::RadioAccessTechnology

strong

Type of radio used in modem to tower communications.

Enumerator
NONE	Not set or not known.
LTE	LTE Cat 1.
LTE_CAT_M1	LTE Cat M1.
LTE_NB_IOT	LET Cat NB1 (NBIoT)

Member Function Documentation

cancelScan()

void QuectelTowerRK::cancelScan

(

)

This method makes sure the callback is not called.

It's used internally by scanBlocking but if you are using scanWithCallback you can also use this to cancel the pending callback.

getSignal()

int QuectelTowerRK::getSignal	(	CellularSignal &	signal,
		unsigned int	max_age = DEFAULT_MAX_AGE_SEC )

Get the cellular signal strength.

Parameters

[out]	signal	Object with signal strength values
[in]	max_age	How old a measurement can be to be valid

Return values

0	Success
-ENODATA	Measurement is old

getSignalUpdate()

unsigned int QuectelTowerRK::getSignalUpdate

(

)

Get the signal strength age.

Returns

unsigned int Age in seconds

getTowerInfo()

void QuectelTowerRK::getTowerInfo

(

TowerInfo &

towerInfo

)

Get the most recently retrieved tower information.

Parameters

towerInfo

This returns the last saved value and does not scan again. See scanBlocking and scanWithCallback.

instance()

static QuectelTowerRK & QuectelTowerRK::instance ( )

inlinestatic

Singleton class instance access for QuectelTowerRK.

Returns

QuectelTowerRK&

parseRadioAccessTechnology()

QuectelTowerRK::RadioAccessTechnology QuectelTowerRK::parseRadioAccessTechnology ( const char * str )

static

Parse a AT+QENG RAT string to convert it to a RadioAccessTechnology value (an int).

Parameters

str

Returns

RadioAccessTechnology

scanBlocking()

int QuectelTowerRK::scanBlocking	(	TowerInfo &	towerInfo,
		unsigned long	timeoutMs = 10000 )

Scan for towers, blocking.

Parameters

towerInfo	Filled in with serving tower and neighboring tower information.
timeoutMs	How long to wait in milliseconds for a response (0 = wait forever). Default is 10 seconds.

Returns

int

This call can take as little as 20 milliseconds, but may take up to a few seconds if connected to cellular. It can block for longer if not connected to cellular as it will wait until connected.

scanWithCallback()

int QuectelTowerRK::scanWithCallback

(

std::function< void(TowerInfo towerInfo)>

scanCallback

)

Asynchronous scan for cellular towers with callback function.

Parameters

scanCallback

Callback function to call when complete

Return values

SYSTEM_ERROR_NONE	Success
SYSTEM_ERROR_BUSY	Cannot start a new scan

The callback function is only called if the return value is SYSTEM_ERROR_NONE. It is called from a separate worker thread.

Callback function prototype for a C++ function or lambda:

void callback(TowerInfo towerInfo)

This call can take as little as 20 milliseconds, but may take up to a few seconds if connected to cellular. It can take for longer if not connected to cellular as it will wait until connected.

startScan()

int QuectelTowerRK::startScan

(

)

Start scan for cellular towers.

Return values

SYSTEM_ERROR_NONE	Success
SYSTEM_ERROR_BUSY	Cannot start a new scan

This is a low-level function; you'd typically use scanBlocking() or scanWithCallback().

Field Documentation

PERIOD_ERROR_MS

constexpr system_tick_t QuectelTowerRK::PERIOD_ERROR_MS {10000}

staticconstexpr

Delay between checking cell strength when errors detected.

Longer than success to minimize thrashing on the cell interface which could delay recovery in Device-OS

---

The documentation for this class was generated from the following files:

• src/QuectelTowerRK.h
• src/QuectelTowerRK.cpp