GsmModule Class Reference

GSM module class. More...

#include <GsmModule.h>

List of all members.

Public Types

enum  ModuleFreqBand {
  FREQ_AUTODETECT = -1, FREQ_900X1800 = 0, FREQ_900X1900, FREQ_850X1800,
  FREQ_850X1900
}
enum  ModulePowerMode {
  POWER_MINIMAL = 0, POWER_FULL = 1, POWER_NOTX = 2, POWER_NORXTX = 4,
  POWER_FULL_SAVE = 5
}

Public Member Functions

 GsmModule (const char *portName)
 Class constructor.
virtual ~GsmModule ()
 Class destructor.
bool open ()
 Open GSM module port.
bool close ()
 Close GSM module port.
bool lock ()
 Lock GSM module.
void unlock ()
 Unlock GSM module.
bool writeCommand (const char *atCmd)
 Send AT command.
ModemAnswerType readAnswer (std::string *pAnswer, int timeOut)
 Read AT command answer.
ModemAnswerType readAnswer (int timeOut=DEFAULT_AT_TIMEOUT)
 Read AT command answer.
bool initComm ()
 Initialize communication.
bool initSIM (const char *pinCode)
 Initialize SIM card.
bool searchNetwork (int waitMax)
 Register in GSM network.
bool initGprs (const char *gprsApn)
 Initialize GPRS.
bool attachGprs ()
 Attach GPRS.
bool setFrequency (ModuleFreqBand freqBand)
 Set operational band.
bool powerSaveMode (ModulePowerMode pwrMode)
 Set power mode.
bool readNetworkInfo (GSM_NETWORK_INFO &netInfo)
 Get network information.
bool setRTC (tm *pDate)
 Set module RTC.
bool getRTC (tm *pDate)
 Get module RTC.
std::string getPortName ()
 Get the communication port name.
std::string getVersion ()
 Read firmware version.

Static Public Member Functions

static bool answerStartsWith (std::string &answer, const char *str)
 Match modem answer.

Detailed Description

GSM module class.

This is a helper class that handles communication to the Telit GSM communication module of the mobile data terminal. GsmModule class is designed to simplify managing the GSM module and implements basic AT commands.


Member Enumeration Documentation

Available operational frequency bands of the GSM module.

Enumerator:
FREQ_AUTODETECT 

Automatic detection of frequency band

FREQ_900X1800 

European frequency bands, 900 Mhz and 1800 Mhz

FREQ_900X1900 

Mixed frequency bands, 900 Mhz and 1900 Mhz

FREQ_850X1800 

Mixed frequency bands, 850 Mhz and 1900 Mhz

FREQ_850X1900 

American frequency bands, 850 Mhz and 1900 Mhz

Available power modes of the GSM module.

Enumerator:
POWER_MINIMAL 

Minimal functionality mode, communication port is disabled

POWER_FULL 

Full functionality mode

POWER_NOTX 

Radio transmitter disabled

POWER_NORXTX 

Radio transmitter and receiver disabled

POWER_FULL_SAVE 

Full functionality mode with power saving


Constructor & Destructor Documentation

GsmModule::GsmModule ( const char *  portName  ) 

Class constructor.

Initializes the GSM module object.

Parameters:
portName Points to the null terminated string that contains the modem communication port name.
GsmModule::~GsmModule (  )  [virtual]

Class destructor.

Terminates the GSM module object.


Member Function Documentation

bool GsmModule::answerStartsWith ( std::string &  answer,
const char *  str 
) [static]

Match modem answer.

Matches the beginning of a modem answer string to another string.

Parameters:
answer Contains the full modem answer.
str Points to a null-terminated string containing the part that needs to be compared. Returns true if the beginning of the answer string is identical with the specified text string.
bool GsmModule::attachGprs (  ) 

Attach GPRS.

Attaches the mobile data terminal to the GPRS service.

Returns:
Returns true if GPRS was attached successfully.
bool GsmModule::close (  ) 

Close GSM module port.

Closes the communication port of the GSM module.

Returns:
Returns true if the port was closed successfully.
std::string GsmModule::getPortName (  )  [inline]

Get the communication port name.

Returns:
Returns the name of the communication port as string
bool GsmModule::getRTC ( tm *  pDate  ) 

Get module RTC.

Reads integrated RTC of the GSM module and returns its date/time.

Parameters:
pDate Points to the standard date/time structure that receives the data.
Returns:
Returns true if RTC was read successfully.
std::string GsmModule::getVersion (  ) 

Read firmware version.

Retrieves the firmware version of the GSM module.

Returns:
Returns the string containing the firmware version.
bool GsmModule::initComm (  ) 

Initialize communication.

Performs the initial handshake with the GSM modem over the connected communication port. This method should be called after open() call and before any other AT command in order to achieve the best performance.

This method executes the modem auto-bauding sequence, fixes the baud rate, enables flow control and selects AT command interface.

Returns:
Returns true if the handshake succeeded.
bool GsmModule::initGprs ( const char *  gprsApn  ) 

Initialize GPRS.

Initializes GPRS profile parameters. Creates a PDP context and sets basic QoS levels.

Parameters:
gprsApn Points to a null-terminated string that contains the GPRS APN.
Returns:
Returns true if the GPRS profile was initialized successfully.
bool GsmModule::initSIM ( const char *  pinCode  ) 

Initialize SIM card.

Initializes the GSM SIM. If required, sends the specified PIN code to enable the SIM. If SIM PIN is disabled, the passed PIN code is ignored. The method will wait internally if the SIM is busy.

Parameters:
pinCode Points to a null-terminated string that contains the PIN code.
Returns:
Returns true if the SIM was initialized successfully.
bool GsmModule::lock (  ) 

Lock GSM module.

Locks the GSM module and blocks simultaneous access by other threads. A typical application should lock the module before sending an AT command and unlock after receiving an answer.

Returns:
Returns true if the modem was locked successfully.
bool GsmModule::open (  ) 

Open GSM module port.

Opens the communication port of the GSM module. Communication port name is specified in the class constructor.

The communication port is automatically initialized to 115000 bps with hardware flow control.

Returns:
Returns true if the communication port was opened successfully.
bool GsmModule::powerSaveMode ( ModulePowerMode  pwrMode  ) 

Set power mode.

Selects the power management mode of the GSM module. Note that communication with the GSM modem is not possible in POWER_MINIMAL and modes. The modem in POWER_MINIMAL mode will wake up on external events and proceed to POWER_FULL mode. Communication with the modem is possible in POWER_FULL_SAVE mode only if the DTR signal is high. If DTR is low, the GSM module enters a power saving mode.

Parameters:
pwrMode Specifies the new power mode.
Returns:
Returns true if the power mode was set successfully.
ModemAnswerType GsmModule::readAnswer ( int  timeOut = DEFAULT_AT_TIMEOUT  ) 

Read AT command answer.

Retrieves the modem answer type identifier for a previously sent AT command. The function blocks until the answer is received or the timeout expires.

Parameters:
timeOut Specifies the answer timeout, in milliseconds.
Returns:
Returns modem answer type identifier. Returns AT_INVALID if the timeout expired. See ModemAnswerType for more details.
ModemAnswerType GsmModule::readAnswer ( std::string *  pAnswer,
int  timeOut 
)

Read AT command answer.

Retrieves the full modem answer data for a previously sent AT command. The function blocks until the answer is received or the timeout expires.

Parameters:
pAnswer Points to the string that receives the full modem answer. This parameter can be set to NULL if the full answer is not required.
timeOut Specifies the answer timeout, in milliseconds.
Returns:
Returns modem answer type identifier. Returns AT_INVALID if the timeout expired. See ModemAnswerType for more details.
bool GsmModule::readNetworkInfo ( GSM_NETWORK_INFO netInfo  ) 

Get network information.

Requests the network information from the GSM module. The network information structure is filled with available data.

Parameters:
netInfo Contains a reference to the network information structure.
Returns:
Returns true if the information was acquired successfully.
bool GsmModule::searchNetwork ( int  waitMax  ) 

Register in GSM network.

Finds a suitable operator and registers the mobile data terminal with its network. Automatic network search is used based on provided SIM.

The method blocks until the GSM module is registered with the network or the specified timeout expires.

Parameters:
waitMax Specifies the maximum wait time.
Returns:
Returns true if a suitable network was found successfully.
bool GsmModule::setFrequency ( ModuleFreqBand  freqBand  ) 

Set operational band.

Selects GSM operational frequency band. Automatic frequency band detection may be enabled, network searching time will be increased in such case.

Parameters:
freqBand Specifies the frequency band.
Returns:
Returns true if the band was set successfully.
bool GsmModule::setRTC ( tm *  pDate  ) 

Set module RTC.

Sets integrated RTC of the GSM module to the specified date/time.

Parameters:
pDate Points to the standard date/time structure.
Returns:
Returns true if RTC was set successfully.
void GsmModule::unlock (  ) 

Unlock GSM module.

Unlocks the GSM module and makes it available for further communication.

Returns:
Returns true if the modem was unlocked successfully.
bool GsmModule::writeCommand ( const char *  atCmd  ) 

Send AT command.

Writes the specified AT command to the GSM module. The carriage return is inserted automatically after sending the command. All data currently pending in output and input buffers is flushed.

Parameters:
atCmd Points to a null-terminated string containing the AT command.
Note:
There is no need to terminate the command with a carriage return.
Returns:
Returns true if the command was sent successfully.

The documentation for this class was generated from the following files:
Generated on Wed Oct 20 11:13:44 2010 for libspatha by  doxygen 1.6.3