Description
GsmAsync was implemented to reduce the complexity of communicating with GSM (SIM800, SIM900) modules. The solution GsmAsync performes an event-driven communication, so user code doesn't need to wait for answer arriving from the GSM module.
GsmAsync provides two basic features:
- You can add commands to the command-queue, where next command will be executed automatically uppon success.
- You can register callbacks that are called, when the designated answer arrives from the GSM module.
Besides that, GsmAsync also provides timeout and error handling.
Working principals
Command execution
Fortunatelly the communication protocol of the GSM modules is very consistent. You will issue an AT command to the module, where it will respond with an answer. And the sentence always finished with OK on success.
You put your commands to the command-queue provided by GsmAsync, and the commands will be executed automatically one after an other. The next command will be sent when got OK answer for the previous one. If no answer arrives within a time period*, the command will be resent. The sending will be retried for some times** but finally a timeout event will be generated if the GSM module is not responding.
If an ERROR result arrives instead of the OK, an error event will be generated by the GsmAsync library.
Response subscription
When you request a value from the GSM module the module will likely answer with a strict format. E.g.
> AT+CSQ <--- Signal quality request
+CSQ: 31,0 <--- Response
OK <--- End of result marker
Using this example you can subscribe to an answer "+CSQ:" with specifying a custom callback method. Your method will be called, when the response prefix matches with your subscription.
Interface description
This is an informal description of the GsmAsync class methods, for more detailed documentation please wisit GsmAsync.h .
void timeoutHandler();
void errorHandler();
GsmAsync gsmAsync(&Serial1, timeoutHandler, errorHandler);
...
void loop()
{
gsmAsync.doLoop();
}
When you create the GsmAsync instance, you will need to provide a reference to the communication channel. Usually this is a HardwareSerial port. You can also provide a timeout handler and an error handler method reference to control problems. doLoop() must be called as frequently as possible to let GsmAsync check for input and to handle timings.
gsmAsync.addCommand("AT+CSQ"); // Ask for signal quality report
gsmAsync.addCommand("AT+CCLK?"); // Ask for the time
You can add commands to the command queue. Commands will be executed one after an other.
void handleCsq(char* result);
GsmHandler csqHandler = { "+CSQ:", handleCsq };
...
void setup() {
...
gsmAsync.registerHandler(&csqHandler);
}
...
void handleCsq(char* result)
{
int rssi;
sscanf(result, "%d", &rssi);
Serial.print("Signal quality:");
Serial.println(rssi);
}