SMS Messages
A super cool feature of the shield is that you can also send and receive text messages! This can be very useful for SMS-initiated sensors, security system SMS alerts, etc. For this tutorial I'll be using the Hologram.io developer SIM card and I'll explain the different ways you can send and receive texts and automatic replies to certain text messages!
The easiest way to send a test text message is to load the "LTE_Demo" sketch as described here. Enter the "s" command and then type in your phone number, making sure to also type the country code at the beginning without spaces or "+" sign. The country code prefix should always be 3 digits long. For example, I live in the United States with country code "001" so I would simply type "001XXXYYYZZZZ" without spaces or dashes. It should send the SMS and you should see it on your phone within a few seconds!
NOTE: For Hologram SIM cards sending texts is $0.19/message per the Hologram pricing page. However, incoming texts are totally free! To avoid the outgoing SMS charges, consider using data to send the messages through the Hologram API instead!
Furthermore, all Hologram SIM cards have an outbox number with a +882 country code that appears on all outbound SMS messages. This country code may be blocked by certain carriers, and Verizon seems to be one of them (for more info please see this question on the Hologram forum). However, AT&T does not have this issue (at least in the US). If you are running into this issue with Verizon, either switch to AT&T instead, or you might need to ask the carrier that is blocking the SMS messages to whitelist the specific number. Furthermore, please see the "Hologram SMS Route" section at the end of this page for a workaround.
Now to test receiving a text, let's first go to the Hologram Dashboard and click on the "Devices" tab on the left hand side. Click the device you're interested in and then click on the "SMS" tab:
Simply enter the message you want to send to the SIM7000 shield and press Send!
Using the same "LTE_Demo" sketch, enter the command "R" to read all SMS messages. You should see the test message appear! To delete it so that you don't stockpile messages, use the command "d" and enter the one you want to delete.
One thing that might be cool is to send an automated reply to a message. Upload the example sketch here that I've created based on an example sketch from Adafruit. This code allows the shield to send different responses based on the contents of an incoming text. Whenever the shield receives an SMS it will reply with a response to the originator of the text (your phone) depending on what was in the text message. For example, you could program it to look for a magic password like "OPEN SESAME!" for it to do something special. In the example sketch it will just reply with a text message but you can add things like a special command to activate a relay or solenoid, read GPS location data, or trigger something else! If the password isn't in the text message it simply sends back arbitrary sensor data (from analogRead).
To test it out, go to the same Hologram Dashboard and this time enter your phone number in the second field, including your country code (no special characters or spaces!). Type a random message and press Send.
This time when you send the SMS the shield will know where it's supposed to reply to and send the sensor data to the phone number you specified! Now send "OPEN SESAME!" and you should get a text "Treasure chest unlocked!" because your text matches the password exactly. You can also try sending "123 OPEN SESAME!" and it should now respond with "Opening secret door!" because the text message included the password but had other stuff in it. Lastly, try anything that doesn't have the password and it should text your phone with the sensor data!
Another thing you can try is not including the return phone number in the SMS that you send from the Hologram Dashboard. In this case, instead of sending a reply to your phone it will send it back to the cloud. So if you send "testing 123" to the shield without specifying a return phone number, the shield will send the "Sensor reading: 349.25" to the cloud and you can see the value under the "Console" tab on the left hand side of the Hologram Dashboard.
Now that the data is being sent to the cloud instead of to your phone you can do some interesting things with it. Under the "Routes" tab you can set up email or SMS alerts, send an HTTP POST request to a URL of your choice, interface with IFFFT for even more options, etc. etc.! As you can see you can do a lot of cool stuff with this! One practical example would be if you want your device to send you an email every once in a while when it reads data from a sensor. Normally with AT commands this would be tricky to implement if not impossible. However, by creating a route on Hologram you can simply make the device text Hologram (check for this number in serial monitor when your device sends a text to Hologram) or do an HTTP POST request to the Hologram REST API and it can handle the email for you!
First of all I should mention that full documentation for Hologram Dashboard features can be found here but I'll attempt to summarize.
Let's begin by adding a new route under the Console tab. Enter a descriptive name like "Email alerts" or something. Now it's time to select a "topic" which is essentially where data is coming from. By selecting topics you are telling the route to listen to those data sources and perform the actions of the route you are creating. For now let's just choose our SIM7000 device, although note that there are more options that might be worth investigating!
Next up is to insert an operation if required. For example, you can add a "Heartbeat" operation that will trigger the route to send an alert (next section) when the device hasn't posted within the last 15 minutes. For now we'll skip this and go to the action section. For simplicity let's just choose the Email option and type in our email address and subject. This action will send an email and include the data in the body of the email if we use "<>". Note that if you are sending JSON data to the Hologram HTTP API you can do stuff like "<<decdata.temperature>>" and parse the JSON!
Send a text to the shield using the dashboard's SMS feature without specifying a return number. Shortly after sending you should see a new sensor reading pop up in the Console and you should receive an email with the data in it!
So now let's say you want your device to send an SMS to your phone but for some reason you don't want to send it directly or you're running into the issue where the number is being blocked (as mentioned above for some carriers). In this case it's very easy to create a route on the Hologram dashboard to re-route your SMS for you; so instead of having the device send directly to your phone, the device sends an SMS to the Hologram dashboard, then the Hologram route turns around and sends that same SMS to your phone.
The first thing to do is create a new route like we did before and this time we'll enter the "SMS_DO" topic on the "IN" side of the equation:
Note that you should also be able to use the topic with your SIM card name but it will be triggered any time your device sends anything to Hologram, including through the API, not just text messages. Next, on the "OUT" section choose the SMS action and enter your phone number with "+" sign and country code.
After creating your route, make sure to enable it by clicking the little slider icon! Now we're ready to test! If you don't already know the Hologram number to text to, simply go to the Hologram "Devices" tab, click the SIM card that's tied to your device, send an SMS to your device, then use the "r" command in the LTE_Demo sketch and read text #0 (though it could be a different number if you have more than 1 text message). Copy this number and now use the "s" command to send a text to that number. Soon after you send the text you should see the message appear in the "Console" tab and you should also get the message on your phone!
Pretty cool huh? Now experiment away and share your cool projects! For example, you could program your device to text the Hologram API, connect it to IFTTT via a route, and then have IFTTT turn on your smart lights in your home or something crazy! Also please let me know if you would like me to show you how to do something specific. I'm sure I will have more tutorials coming soon illustrating some practical examples!