This is a class for communicating with a Cellular radio device. More...

#include <Cellular.h>

Inherited by EasyIP, and UIP.

Data Structures
struct	gpsData
	This structure contains the data for GPS position. More...
struct	Sms
	This structure contains the data for an SMS message. More...
Public Types
enum	Radio
	Enumeration for different cellular radio types. More...
enum	Registration
	An enumeration of radio registration states with a cell tower. More...
Public Member Functions
virtual bool	init (MTSBufferedIO *io)
	This method initializes the object with the underlying radio interface to use.
bool	configureSignals (unsigned int DCD=NC, unsigned int DTR=NC, unsigned int RESET=NC)
	Sets up the physical connection pins (DTR,DCD, and RESET)
virtual Code	test ()
	A method for testing command access to the radio.
virtual int	getSignalStrength ()
	A method for getting the signal strength of the radio.
virtual Registration	getRegistration ()
	This method is used to check the registration state of the radio with the cell tower.
virtual Code	setApn (const std::string &apn)=0
	This method is used to set the radios APN if using a SIM card.
virtual Code	setDns (const std::string &primary, const std::string &secondary="0.0.0.0")
	This method is used to set the DNS which enables the use of URLs instead of IP addresses when making a socket connection.
virtual Code	sendSMS (const std::string &phoneNumber, const std::string &message)
	This method is used to send an SMS message.
virtual Code	sendSMS (const Sms &sms)
	This method is used to send an SMS message.
virtual std::vector < Cellular::Sms >	getReceivedSms ()
	This method retrieves all of the SMS messages currently available for this phone number.
virtual Code	deleteAllReceivedSms ()
	This method can be used to remove/delete all received SMS messages even if they have never been retrieved or read.
virtual Code	deleteOnlyReceivedReadSms ()
	This method can be used to remove/delete all received SMS messages that have been retrieved by the user through the getReceivedSms method.
virtual std::string	sendCommand (const std::string &command, unsigned int timeoutMillis, char esc=CR)
	A method for sending a generic AT command to the radio.
virtual Code	sendBasicCommand (const std::string &command, unsigned int timeoutMillis, char esc=CR)
	A method for sending a basic AT command to the radio.
virtual Code	echo (bool state)
	A method for changing the echo commands from radio.
virtual Code	setSocketCloseable (bool enabled)
	This method can be used to trade socket functionality for performance.
virtual bool	bind (unsigned int port)
	Binds the socket to a specific port if able.
virtual bool	isOpen ()
	Checks if a socket is open.
virtual unsigned int	readable ()
	Checks if there is data available from the socket.
virtual unsigned int	writeable ()
	Checks data to output on the socket.
virtual std::string	getDeviceIP ()
	Gets the device IP.
virtual bool	setDeviceIP (std::string address="DHCP")
	Sets the device IP (Not implemented, IP address values are assigned by DHCP)
std::string	getEquipmentIdentifier ()
	Get the device IMEI or MEID (whichever is available)
int	getRadioType ()
	Get radio type.
std::string	getRadioTypeString ()
	Get string representation of radio type.
virtual bool	GPSenable ()
	Enables GPS.
virtual bool	GPSdisable ()
	Disables GPS.
virtual bool	GPSenabled ()
	Checks if GPS is enabled.
virtual gpsData	GPSgetPosition ()
	Get GPS position.
virtual bool	GPSgotFix ()
	Check for GPS fix.
Static Public Member Functions
static std::string	getRegistrationNames (Registration registration)
	A static method for getting a string representation for the Registration enumeration.
static std::string	getRadioNames (Radio radio)
	A static method for getting a string representation for the Radio enumeration.

Detailed Description

This is a class for communicating with a Cellular radio device.

This class supports three main types of cellular radio interactions including: configuration and status processing, SMS processing, and TCP/UDP Socket data connections. This class also inherits from IPStack providing a common set of commands for communication devices that support IP protocols. It is also integrated with the standard mbed Sockets package and can therefore be used seamlessly with clients and services built on top of this interface already within the mbed library.

For all examples below please change Pin Names to match your hardware configuration. It also assumes the use of RTS/CTS hardware handshaking using GPIOs. To disable this you will need to change settings on the radio module and and use the MTSSerial class instead of MTSSerialFlowControl.

The following set of example code demonstrates how to send and receive configuration and status AT commands with the radio, create a data connection and test it:

 #include "mbed.h"
 #include "mtsas.h"

 int main(){
    //Modify to match your apn if you are using an HSPA radio with a SIM card
    const char APN[] = "";
    
    //Sets the log level to INFO, higher log levels produce more log output.
    //Possible levels: NONE, FATAL, ERROR, WARNING, INFO, DEBUG, TRACE
    MTSLog::setLogLevel(MTSLog::INFO_LEVEL);
    
    // STMicro Nucelo F401RE
    // The supported jumper configurations of the MTSAS do not line up with
    // the pin mapping of the Nucleo F401RE. Therefore, the MTSAS serial TX
    // pin (JP8 Pin 2) must be manually jumped to Serial1 RX (Shield pin D2)
    // and the MTSAS serial RX pin (JP9 Pin 2) pin must be manually jumped to
    // Serial1 TX (Shield pin D8).
    // Uncomment the following line to use the STMicro Nuceleo F401RE
    //
    MTSSerialFlowControl* io = new MTSSerialFlowControl(D8, D2, D3, D6);
    
    // Freescale KL46Z
    // To configure the pins for the Freescale KL46Z board, use configuration B
    // Uncomment the following line to use the Freescale KL46Z board
    //
    //MTSSerialFlowControl* io = new MTSSerialFlowControl(D2, D9, D3, D6);
    
    // Freescale K64F
    // To configure the pins for the Freescale KL46Z board, use configuration A
    // Uncomment the following line to use the Freescale KL46F board
    //
    //MTSSerialFlowControl* io = new MTSSerialFlowControl(D1, D0, D3, D6);
    
    //Sets the baud rate for communicating with the radio
    io->baud(115200);
    
    //Create radio object
    Cellular* radio = CellularFactory::create(io);
    radio->configureSignals(D4,D7,RESET);
    Transport::setTransport(radio);
    
    if (! radio) {
        logFatal("Failed to initialize radio");
        return 1;
    }
    
    //Set radio APN
    for (int i = 0; i < 10; i++) {
        if (i >= 10) {
            logError("Failed to set APN to %s", APN);
        }
        if (radio->setApn(APN) == MTS_SUCCESS) {
            logInfo("Successfully set APN to %s", APN);
            break;
        } else {
            wait(1);
        }
    }
    
    //Establish PPP link
    for (int i = 0; i < 10; i++) {
        if (i >= 10) {
            logError("Failed to establish PPP link");
        }
        if (radio->connect() == true) {
            logInfo("Successfully established PPP link");
            break;
        } else {
            wait(1);
        }
    }
    
    //Ping google.com
    for (int i = 0; i < 10; i++) {
        if (i >= 10) {
            logError("Failed to ping www.google.com");
        }
        if (radio->ping("www.google.com") == true) {
            logInfo("Successfully pinged www.google.com");
            break;
        } else {
            wait(1);
        }
    }
    
    //Disconnect ppp link
    radio->disconnect();
    
    logInfo("End of example code");
    return 0;
 }

The following set of example code demonstrates how to process SMS messages:

 #include "mbed.h"
 #include "mtsas.h"

 int main(){
    
    //Sets the log level to INFO, higher log levels produce more log output.
    //Possible levels: NONE, FATAL, ERROR, WARNING, INFO, DEBUG, TRACE
    MTSLog::setLogLevel(MTSLog::INFO_LEVEL);
    
    //Modify to match your apn if you are using an HSPA radio with a SIM card
    const char APN[] = "";
    
    //Phone number to send to and receive from. Must be in the form "1xxxxxxxxxx"
    string PHONE_NUMBER = "";
    
    Cellular::Sms txtmsg;
    txtmsg.phoneNumber = PHONE_NUMBER;
    txtmsg.message = "Hello World! MTSAS is up and running!";
    
    // STMicro Nucelo F401RE
    // The supported jumper configurations of the MTSAS do not line up with
    // the pin mapping of the Nucleo F401RE. Therefore, the MTSAS serial TX
    // pin (JP8 Pin 2) must be manually jumped to Serial1 RX (Shield pin D2)
    // and the MTSAS serial RX pin (JP9 Pin 2) pin must be manually jumped to
    // Serial1 TX (Shield pin D8).
    // Uncomment the following line to use the STMicro Nuceleo F401RE
    //
    MTSSerialFlowControl* io = new MTSSerialFlowControl(D8, D2, D3, D6);
    
    // Freescale KL46Z
    // To configure the pins for the Freescale KL46Z board, use configuration B
    // Uncomment the following line to use the Freescale KL46Z board
    //
    //MTSSerialFlowControl* io = new MTSSerialFlowControl(D2, D9, D3, D6);
    
    // Freescale K64F
    // To configure the pins for the Freescale KL46Z board, use configuration A
    // Uncomment the following line to use the Freescale KL46F board
    //
    //MTSSerialFlowControl* io = new MTSSerialFlowControl(D1, D0, D3, D6);
    
    //Sets the baudrate for communicating with the radio
    io->baud(115200); 
    
    //Creates a radio object
    Cellular* radio = CellularFactory::create(io);
    radio->configureSignals(D4,D7,RESET);
    Transport::setTransport(radio);
    
    if (! radio) {
        logFatal("Failed to initialize radio");
        return 1;
    }
    
    //Set radio APN
    for (int i = 0; i < 10; i++) {
        if (i >= 10) {
            logError("Failed to set APN\n");
        }
        if (radio->setApn(APN) == MTS_SUCCESS) {
            logInfo("Successfully set APN\n");
            break;
        } else {
            wait(1);
        }
    }
    
    //Delete any previously received SMS messages
    for (int i = 0; i < 10; i++) {
        if (i >= 10) {
            logError("Failed to delete SMS messages\n");
        }
        if (radio->deleteAllReceivedSms() == MTS_SUCCESS) {
            logInfo("Deleted all SMS messages\n");
            break;
        } else {
            wait(1);
        }
    }
    
    // Send SMS message to phone
    for (int i = 1; i < 10; i++) {
        if(radio->sendSMS(txtmsg) == MTS_SUCCESS) {
            logInfo("Sent SMS successfully:<%s>\n", txtmsg.message.c_str());
            break;
        } else {
            logError("Failed to send SMS<%s>\n", txtmsg.message.c_str());
        }
    }
    
    //Checking for received SMS messages
    while (true) {
        logInfo("Checking for received messages");
        vector<Cellular::Sms> recv = radio->getReceivedSms();
        if(recv.size() > 0) {
            int size = recv.size();
            for (int i = 0; i < size; i++) {
                logInfo("Message %d: [%s] [%s] [%s]", i, recv[i].phoneNumber.c_str(), recv[i].timestamp.c_str(), recv[i].message.c_str());
            }
        }
        
        if(radio->deleteOnlyReceivedReadSms() != MTS_SUCCESS) {
            logError("Failed to delete received and read SMS messages");
        }
        wait(10);
    }
    
    logDebug("End of example code\n");
    return 0;
 }

Definition at line 239 of file Cellular.h.

Member Enumeration Documentation

enum Radio

Enumeration for different cellular radio types.

Definition at line 247 of file Cellular.h.

enum Registration

An enumeration of radio registration states with a cell tower.

Definition at line 253 of file Cellular.h.

Member Function Documentation

bool bind ( unsigned int port ) [virtual]

Binds the socket to a specific port if able.

Parameters:

port	integer to bind the socket to.

Returns:: true if successfully bound port, false if bind failed.

Definition at line 523 of file Cellular.cpp.

bool configureSignals	(	unsigned int	DCD = `NC`,
		unsigned int	DTR = `NC`,
		unsigned int	RESET = `NC`
	)

Sets up the physical connection pins (DTR,DCD, and RESET)

Definition at line 18 of file Cellular.cpp.

Code deleteAllReceivedSms ( ) [virtual]

This method can be used to remove/delete all received SMS messages even if they have never been retrieved or read.

Returns:: the standard AT Code enumeration.

Definition at line 409 of file Cellular.cpp.

Code deleteOnlyReceivedReadSms ( ) [virtual]

This method can be used to remove/delete all received SMS messages that have been retrieved by the user through the getReceivedSms method.

Messages that have not been retrieved yet will be unaffected.

Returns:: the standard AT Code enumeration.

Definition at line 404 of file Cellular.cpp.

Code echo ( bool state ) [virtual]

A method for changing the echo commands from radio.

Parameters:

state Echo mode is off (an argument of 1 turns echos off, anything else turns echo on)

Returns:: standard Code enumeration

Definition at line 482 of file Cellular.cpp.

std::string getDeviceIP ( ) [virtual]

Gets the device IP.

Returns:: string containing the IP address

Definition at line 476 of file Cellular.cpp.

std::string getEquipmentIdentifier ( )

Get the device IMEI or MEID (whichever is available)

Returns:: string containing the IMEI for GSM, the MEID for CDMA, or an empty string if it failed to parse the number.

Definition at line 427 of file Cellular.cpp.

std::string getRadioNames ( Radio radio ) [static]

A static method for getting a string representation for the Radio enumeration.

Parameters:

type	a Radio enumeration.

Returns:: the enumeration name as a string.

Definition at line 58 of file Cellular.cpp.

int getRadioType ( )

Get radio type.

Returns:: the radio type (MTSMC-H5, etc)

Definition at line 442 of file Cellular.cpp.

std::string getRadioTypeString ( )

Get string representation of radio type.

Returns:: string containing the radio type (MTSMC-H5, etc)

Definition at line 447 of file Cellular.cpp.

std::vector< Cellular::Sms > getReceivedSms ( ) [virtual]

This method retrieves all of the SMS messages currently available for this phone number.

Returns:: a vector of existing SMS messages each as an Sms struct.

Definition at line 319 of file Cellular.cpp.

Cellular::Registration getRegistration ( ) [virtual]

This method is used to check the registration state of the radio with the cell tower.

If not appropriatley registered with the tower you cannot make a cellular connection.

Returns:: the registration state as an enumeration type.

Definition at line 121 of file Cellular.cpp.

std::string getRegistrationNames ( Registration registration ) [static]

A static method for getting a string representation for the Registration enumeration.

Parameters:

code	a Registration enumeration.

Returns:: the enumeration name as a string.

Definition at line 38 of file Cellular.cpp.

int getSignalStrength ( ) [virtual]

A method for getting the signal strength of the radio.

This method allows you to get a value that maps to signal strength in dBm. Here 0-1 is Poor, 2-9 is Marginal, 10-14 is Ok, 15-19 is Good, and 20+ is Excellent. If you get a result of 99 the signal strength is not known or not detectable.

Returns:: an integer representing the signal strength.

Definition at line 107 of file Cellular.cpp.

bool GPSdisable ( ) [virtual]

Disables GPS.

Returns:: true if GPS is disabled, false if GPS does not disable.

Reimplemented in EasyIP.

Definition at line 541 of file Cellular.cpp.

bool GPSenable ( ) [virtual]

Enables GPS.

Returns:: true if GPS is enabled, false if GPS is not supported.

Reimplemented in EasyIP.

Definition at line 537 of file Cellular.cpp.

bool GPSenabled ( ) [virtual]

Checks if GPS is enabled.

Returns:: true if GPS is enabled, false if GPS is disabled.

Reimplemented in EasyIP.

Definition at line 545 of file Cellular.cpp.

Cellular::gpsData GPSgetPosition ( ) [virtual]

Get GPS position.

Returns:: a structure containing the GPS data field information.

Reimplemented in EasyIP.

Definition at line 548 of file Cellular.cpp.

bool GPSgotFix ( ) [virtual]

Check for GPS fix.

Returns:: true if there is a fix and false otherwise.

Reimplemented in EasyIP.

Definition at line 554 of file Cellular.cpp.

bool init ( MTSBufferedIO * io ) [virtual]

This method initializes the object with the underlying radio interface to use.

Note that this function MUST be called before any other calls will function correctly on a Cellular object. Also note that MTSBufferedIO is abstract, so you must use one of its inherited classes like MTSSerial, MTSSerialFlowControl or write a class similar to MTSSerialFlowControl which maps the MTSBufferedIO API to your favorite serial library.

Parameters:

io	the io interface that is attached to the cellular radio. The default is not connected.

Returns:: true if the init was successful, otherwise false.

Reimplemented in EasyIP, and UIP.

Definition at line 8 of file Cellular.cpp.

bool isOpen ( ) [virtual]

Checks if a socket is open.

Returns:: true if socket is open, false if socket is closed

Definition at line 513 of file Cellular.cpp.

unsigned int readable ( ) [virtual]

Checks if there is data available from the socket.

Returns:: number of bytes of data available to read.

Definition at line 414 of file Cellular.cpp.

Code sendBasicCommand	(	const std::string &	command,
		unsigned int	timeoutMillis,
		char	esc = `CR`
	)		`[virtual]`

A method for sending a basic AT command to the radio.

A basic AT command is one that simply has a response of either OK or ERROR without any other information. Note that you cannot send commands and have a data connection at the same time.

Parameters:

command	the command to send to the radio without the escape character.
timeoutMillis	the time in millis to wait for a response before returning.
esc	escape character to add at the end of the command, defaults to carriage return (CR).

Returns:: the standard Code enumeration.

Definition at line 162 of file Cellular.cpp.

string sendCommand	(	const std::string &	command,
		unsigned int	timeoutMillis,
		char	esc = `CR`
	)		`[virtual]`

A method for sending a generic AT command to the radio.

Note that you cannot send commands and have a data connection at the same time.

Parameters:

command	the command to send to the radio without the escape character.
timeoutMillis	the time in millis to wait for a response before returning.
esc	escape character to add at the end of the command, defaults to carriage return (CR). Does not append any character if esc == 0.

Returns:: all data received from the radio after the command as a string.

Definition at line 181 of file Cellular.cpp.

Code sendSMS	(	const std::string &	phoneNumber,
		const std::string &	message
	)		`[virtual]`

This method is used to send an SMS message.

Note that you cannot send an SMS message and have a data connection open at the same time.

Parameters:

phoneNumber	the phone number to send the message to as a string.
message	the text message to be sent.

Returns:: the standard AT Code enumeration.

Definition at line 266 of file Cellular.cpp.

Code sendSMS ( const Sms & sms ) [virtual]

This method is used to send an SMS message.

Note that you cannot send an SMS message and have a data connection open at the same time.

Parameters:

sms	an Sms struct that contains all SMS transaction information.

Returns:: the standard AT Code enumeration.

Definition at line 157 of file Cellular.cpp.

virtual Code setApn ( const std::string & apn ) [pure virtual]

This method is used to set the radios APN if using a SIM card.

Note that the APN must be set correctly before you can make a data connection. The APN for your SIM can be obtained by contacting your cellular service provider.

Parameters:

the	APN as a string.

Returns:: the standard AT Code enumeration.

Implemented in EasyIP, and UIP.

bool setDeviceIP ( std::string address = "DHCP" ) [virtual]

Sets the device IP (Not implemented, IP address values are assigned by DHCP)

Returns:: true if the IP was set, false if IP address assignment failed.

Definition at line 466 of file Cellular.cpp.

Code setDns	(	const std::string &	primary,
		const std::string &	secondary = `"0.0.0.0"`
	)		`[virtual]`

This method is used to set the DNS which enables the use of URLs instead of IP addresses when making a socket connection.

Parameters:

the	DNS server address as a string in form xxx.xxx.xxx.xxx.

Returns:: the standard AT Code enumeration.

Definition at line 152 of file Cellular.cpp.

Code setSocketCloseable ( bool enabled ) [virtual]

This method can be used to trade socket functionality for performance.

Can disable checking socket closed messages from the data socket, and thus the socket will only be visibly closed to the local side if the radio is explicitly checked, or the socket is closed by the local side through the use of physical pin manipulation.

Uses the Hayes escape sequence (1 second pause, "+++", 1 second pause) to exit the socket connection to check if a received "NO CARRIER" string is from the radio indicating the socket has been closed, or is merely part of the data stream. Should not occur very often, however, if data carrying the string "NO CARRIER" is going to be transmitted frequently, then the socket should be set closeable and physical-socket-closing-means be used instead to reduce the large amount of overhead switching from checking the validity of the "NO CARRIER" message being and indication of the socket connection being closed.

Parameters:

enabled set to true if you want the socket closeable, otherwise false. The default is true.

Returns:: the standard AT Code enumeration.

Definition at line 497 of file Cellular.cpp.

Code test ( ) [virtual]

A method for testing command access to the radio.

This method sends the command "AT" to the radio, which is a standard radio test to see if you have command access to the radio. The function returns when it receives the expected response from the radio.

Returns:: the standard AT Code enumeration.

Definition at line 93 of file Cellular.cpp.

unsigned int writeable ( ) [virtual]

Checks data to output on the socket.

Returns:: number of bytes to be written to the socket.

Definition at line 452 of file Cellular.cpp.

Type:	Library
Created:	27 Mar 2015
Imports:	45
Forks:	4
Commits:	83
Dependents:	4
Dependencies:	0
Followers:	87

Cellular Class Reference

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Cellular Class Reference

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning