MultiTech
Cellular library for MTS Socket Modem Arduino Shield devices from Multi-Tech Systems
Dependents: mtsas mtsas mtsas mtsas
UIP Class Reference
This is a class for communicating with a Multi-Tech Systems SocketModem iCell. More...
#include <UIP.h>
Inherits mts::Cellular.
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 | |
| UIP (Radio type) | |
| This static function is used to create or get a reference to a Cellular object. | |
| ~UIP () | |
| Destructs a Cellular object and frees all related resources. | |
| virtual bool | init (MTSBufferedIO *io) |
| This method initializes the object with the underlying radio interface to use. | |
| virtual bool | connect () |
| Initiates a PPP connection between the radio and the cell network. | |
| virtual void | disconnect () |
| Disconnects the PPP connection between the radio and the cell network. | |
| virtual bool | isConnected () |
| Checks if the radio has a PPP connection established with the cell network (Can reach the internet essentially) | |
| virtual void | reset () |
| Resets the radio, must first close active socket and PPP connections to do so. | |
| virtual Code | setApn (const std::string &apn) |
| A method for setting the APN. | |
| 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 | 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 Multi-Tech Systems SocketModem iCell.
The SocketModem iCell is a family of carrier certified embedded cellular radio modules with a common hardware footprint and AT command set for built in IP-stack functionality. This class supports three main types of cellular radio interactions including: configuration and status AT command processing, SMS processing, and TCP Socket data connections. It should be noted that the radio can not process commands or SMS messages while having an open data connection at the same time. The concurrent capability may be added in a future release. This class also inherits from IPStack providing a common set of commands for communication devices that have an onboard IP Stack. 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.
All of the following examples use the Pin Names for the STMicro Nucleo F401RE board coupled with the SocketModem Shield Arduino compatible board. Please chage Pin Names accordingly 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 default baud rate for the cellular radio is 115200 bps.
Example code is found under Cellular.h
Definition at line 36 of file UIP.h.
Member Enumeration Documentation
enum Radio [inherited] |
Enumeration for different cellular radio types.
Definition at line 247 of file Cellular.h.
enum Registration [inherited] |
An enumeration of radio registration states with a cell tower.
Definition at line 253 of file Cellular.h.
Constructor & Destructor Documentation
This static function is used to create or get a reference to a Cellular object.
Cellular uses the singleton pattern, which means that you can only have one existing at a time. The first time you call getInstance this method creates a new uninitialized Cellular object and returns it. All future calls to this method will return a reference to the instance created during the first call. Note that you must call init on the returned instance before mnaking any other calls. If using this class's bindings to any of the Socket package classes like TCPSocketConnection, you must call this method and the init method on the returned object first, before even creating the other objects.
- Returns:
- a reference to the single Cellular object that has been created.
| ~UIP | ( | ) |
Member Function Documentation
| bool bind | ( | unsigned int | port ) | [virtual, inherited] |
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 |
||
| ) | [inherited] |
Sets up the physical connection pins (DTR,DCD, and RESET)
Definition at line 18 of file Cellular.cpp.
| bool connect | ( | ) | [virtual] |
| Code deleteAllReceivedSms | ( | ) | [virtual, inherited] |
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, inherited] |
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.
| void disconnect | ( | ) | [virtual] |
| Code echo | ( | bool | state ) | [virtual, inherited] |
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, inherited] |
Gets the device IP.
- Returns:
- string containing the IP address
Definition at line 476 of file Cellular.cpp.
| std::string getEquipmentIdentifier | ( | ) | [inherited] |
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, inherited] |
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 | ( | ) | [inherited] |
| std::string getRadioTypeString | ( | ) | [inherited] |
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, inherited] |
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, inherited] |
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, inherited] |
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, inherited] |
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, inherited] |
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, inherited] |
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, inherited] |
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, inherited] |
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, inherited] |
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 from Cellular.
| bool isConnected | ( | ) | [virtual] |
| bool isOpen | ( | ) | [virtual, inherited] |
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, inherited] |
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.
| void reset | ( | ) | [virtual] |
| Code sendBasicCommand | ( | const std::string & | command, |
| unsigned int | timeoutMillis, | ||
| char | esc = CR |
||
| ) | [virtual, inherited] |
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, inherited] |
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 Sms & | sms ) | [virtual, inherited] |
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.
| Code sendSMS | ( | const std::string & | phoneNumber, |
| const std::string & | message | ||
| ) | [virtual, inherited] |
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 setApn | ( | const std::string & | apn ) | [virtual] |
| bool setDeviceIP | ( | std::string | address = "DHCP" ) |
[virtual, inherited] |
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, inherited] |
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, inherited] |
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, inherited] |
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, inherited] |
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.
Generated on Tue Jul 12 2022 21:59:42 by
1.7.2