WebbotLib AVR library
WebbotLib It just does it
  C++ documentation  C documentation

Communication/DroneCell.h

Adds support for the DroneCell - currently limited to text messaging.
This device is only supported in WebbotLib Version 2.03 or higher.
 
dronecell.jpg
When you use this device in Project Designer you will need to give it some power, as well as specifying the UART for transmitting and receiving data. The only other compulsory pin is the RESET pin which is used to initialise the device, The remaining pins are all optional input pins to the micro controller:-
Although the DroneCell is capable of much more - the only features currently supported by WebbotLib are to receive and send SMS messages when there is a signal. You will need to provide an appropriate SIM card for the telephone network of your choice.
One other thing you will need to define, in Project Designer, is the SMSC (SMS Message Center) number for your network provider. Project Designer gives a list for some combinations of operator and the country you are in but is not exhaustive and I cannot guarantee that they are, or will always be, correct. If you are using the SIM card from your phone then first try going in to Phone Settings, Network Settings, Configuration etc until you can find the appropriate SMSC number. This number is in international format ie a '+' followed by the country code, then the number with the leading '0' removed.
Messages sent and received through WebbotLib always go via the SIM card ie received messages are received directly to the SIM and then WebbotLib reads them out; and sent messages are first written to the SIM card and are then sent in the background as and when you have a signal. Note that if you have problems sending lots of SMS messages one after the other then it may be that the SIM card is full - mine can only queue up a total of 10 messages 'in and out'.
The message queue, signal strength, operator name (eg 'T-Mobile' etc) are processed by WebbotLib in the background.
Obviously sending an SMS Message may have financial implications - WebbotLib makes no warranty for the open source libraries. So if you write code that sends 100s of messagess and you get a big bill - then its not my fault !
Here is some example code:-
Showing the signal strength and network operator name
TICK_COUNT appControl(LOOP_COUNT loopCount, TICK_COUNT loopStart) {
    rprintf("Signal Strength=%u, Operator='%s'\n",
            droneCellGetSignalStrength(&myDroneCell),
            droneCellGetOperator(&myDroneCell)
    );
}
Sending an SMS Message
Sending a message is not necessarily guaranteed to happen - the DroneCell may be doing something else - or you may have accidentally switched it off - there are lots of reasons! So there are lots of 'if' statements to keep track of where we are. Just add this inside your appControl logic:-
// Try to set up for sending a text message to a given number
// I've changed the destination number to contain 'x' characters so you
// dont get to see my work mobile number !
if(droneCellSMSInit(&myDroneCell,"+44789xxxx638")){
    // Ok the drone cell is free so put body of message
    DRONECELL_WRITE_SMS(&myDroneCell){
        rprintf("Hello World");
        ... add any more text you like using the commands from rprintf.h ...
    }
    // Now try to send it - may still fail eg SIM card is full or device not connected
    boolean sent = droneCellSMSSend(&myDroneCell);
    // We now know if the message has been sent or not so your program
    // can decide what to do !
}
Auto Responder
Here is a neat way to test your code. This will listen for incoming texts from another telephone number and will then reply to the same number by prefixing the message with 'Got ya'.
So send a message saying 'WebbotLib is cool' and get a reply of 'Got ya: WebbotLib is cool'.
// See if there is a received text
uint8_t msgNo = droneCellMessageWaiting(&myDroneCell);
if(msgNo != 0){
    // Yes there is - print out which SIM card slot
    rprintf("FG: Message Waiting %u\n",(unsigned int)msgNo);
    // Try to read the message in that slot 
    if(droneCellReadMessage(&myDroneCell, msgNo)){
        // we have read it - so dump it out
        rprintf("\nFG Msg: From \"%s\": '%s'\n",
                 myDroneCell.incomingPhoneNumber,
                 myDroneCell.incomingMessage);
 
        // If from my work mobile
        if(strcmp_P(myDroneCell.incomingPhoneNumber,PSTR("+44789xxxx638"))==0){
            // reply
            if(droneCellSMSInit(&myDroneCell,myDroneCell.incomingPhoneNumber)){
                // put body of message
                DRONECELL_WRITE_SMS(&myDroneCell){
                    rprintf("Got ya: %s",myDroneCell.incomingMessage);
                }
                // Try to send the reply
                if(droneCellSMSSend(&myDroneCell)){
                    // Success so delete the original message
                    rprintf("FG:Try Delete msg\n");
                    while(!droneCellDeleteMessage(&myDroneCell, msgNo)){
                        rprintf("FG:Delete failed\n");
                    }
                    rprintf("FG:OK Delete msg\n");
                }else{
                    // Couldn't send the reply - since we haven't deleted
                    // the original message then we will reply again later
                    rprintf("FG:Send reply failed\n");
                }
            }
        }
    }
}

 

Function

 


droneCellPowerOn(DRONECELL* dc)

Starts the power up sequence for the device.
This is called automatically when your micro controller starts up and toggles the RESET line of the DroneCell to begin its power up sequence. Consequently~ you won't normally need to call this unless you have used the 'droneCellPowerOff' command to put it in low power stand by mode and want to wake it up again.
Note that this function will return immediately but it may take 5 seconds or more for the device to be up and running.

droneCellPowerOff(DRONECELL* dc)

Places the DroneCell into a low power standby mode.

boolean droneCellSMSInit(DRONECELL* dc, const char callNumber[])

Attempts to place the DroneCell into a mode where you can send an SMS text message.
Example: (assuming that your device is called myDroneCell in Project Designer and you want to send a message to phone number +19876543221):-
boolean ok = droneCellSMSInit(&myDroneCell, "+1987654321" );
Note that the phone number is in the international format ie '+', country code ('1'=USA), followed by the rest of the number excluding any '0' prefix.
This function will return FALSE if the DroneCell is too busy doing something else, or TRUE if it is now ready for you to start entering text body of your message. Your code must check this return value otherwise the compiler will generate a warning message.
Assuming that this function returns TRUE:- The text body of the message should be surrounded by DRONECELL_WRITE_SMS which makes sure that the output of your rprintf statements are put into the text message. You will then need to call droneCellSMSSend to complete the SMS text message.
See Communication/DroneCell.h for a complete example.

boolean droneCellSMSSend(DRONECELL* dc)

Attempts to send the SMS text message you have written since the call to droneCellSMSInit.
This function will return FALSE if the message has not been sent. This may be because the DroneCell is not plugged in, not powered on, or the SIM card is currently full.
If this function returns TRUE it doesn't mean that the text message has actually been sent yet - but rather that it has been queued up on the SIM card. Consequently it is guaranteed to be sent once the DroneCell gets a signal even if the DroneCell is turned off and back on in the meantime.
For a complete example see Communication/DroneCell.h

boolean droneCellReadMessage(DRONECELL* dc, uint8_t msgIndex)

Attempt to read an incoming message from a particular SIM card slot.
The SIM card slots are normally numbered 1 to 10.
Assuming your device is called myDroneCell in Project Designer and you want to read the message in slot 5 then call:
boolean ok = droneCellReadMessage(&myDroneCell, 5);
The function will return FALSE if the specified slot is empty, invalid, or is not an incoming message.
The easiest way to find the slot number to use is by calling droneCellMessageWaiting
If the function returns true then two member string variables are set: one holds the phone number of the sender, and the other is the message body. For example:
uint8_t msgNo = droneCellMessageWaiting(&myDroneCell); // Get next received msg no
if(msgNo != 0){
    rprintf("FG: Message Waiting %u\n",(unsigned int)msgNo);
    if(droneCellReadMessage(&myDroneCell, msgNo)){
        rprintf("\nFG Msg: From \"%s\": '%s'\n"
            myDroneCell.incomingPhoneNumber,                    
            myDroneCell.incomingMessage);
    }
}

boolean droneCellDeleteMessage

Delete the message in the specified SIM card slot.
This function will return FALSE if the slot is invalid or if the device is currently busy.

uint8_t droneCellGetSignalStrength(const DRONECELL* dc)

Get the current signal strength.
Assuming your device is called myDroneCell in Project Designer then:-
uint8_t signalStrength = droneCellGetSignalStrength(&myDroneCell);
The returned value should be interpreted as follows:-
0 = none
1= -111dBm
2..30 = -109dBm ... -53dBm
31 = -51dBm or better
99 = not known

boolean droneCellIsRegistered(const DRONECELL* dc)

Test if the DroneCell is currently registered with a cell phone network operator.
Return FALSE if not, TRUE if yes.

uint8_t droneCellMessageWaiting(const DRONECELL* dc)

Test if a message has been received.
This will return 0 if there is no message, otherwise it is the SIM slot message index that should be passed into droneCellReadMessage(DRONECELL* dc, uint8_t msgIndex) to read the message.

const char* droneCellGetOperator(DRONECELL* dc)

Get the name of the current network operator.
The return value is a string which may be blank if the device is still trying to find a network, otherwise it is the name of the network operator being used.
Example (assuming you have called your device myDroneCell in Project Designer):
// Write name of the operator to the output
rprintf("Operator='%s'\n",droneCellGetOperator(&myDroneCell));

Valid XHTML 1.0 Transitional