Panther Logger 4: Sending Data with Cellular

We will send data first to ThingSpeak using the GET method. Your ThingSpeak account and channels should be setup just as we did in tutorials for WiFi communications in the Panther Logger 3 tutorial. See that tutorial to setup your account and the channels we will use.

We need to change some things in the SendData_Cellular_GET code to send data to a specific ThingSpeak channel just like we did for WiFi.  Find this section in the code near the beginning on the first tab:

char Token[] = "XXXXXXXXXXXXXXXXXX";

Replace the X's with your api_key from ThingSpeak.

Then find this code:

char Endpoint[] = "https://api.thingspeak.com/update.json?api_key";

This shows the ThingSpeak endpoint for making a GET call. After the "?" is the name of the credential we need to include. ThingSpeak calls this the "api_key" whereas other sites might call it just "key" or "token." See the API documentation for a REST HTTP GET method for the site you are communicating with. ThingSpeak's API documentation is here. Since we are sending data to ThingSpeak with this tutorial nothing needs to be changed, but if sending to a different database then the name of this "Token" might need to be changed based on the API documentation.

The code is going to build up this url with the api_key and the data we want to send. It will use the sprintf function to do this. See this function below:

sprintf(Payload, "%s=%s&field1=%.2f&field2=%.2f&field3=%.2f&field4=%.2f&field5=%d&field6=%.2f&field7=%.2f&field8=%.2f",

          Endpoint,

          Token,                           

          AirTemp,                               

          Humidity,

          BaroPressure,

          WindSpeed,

          WindDirection,                         

          DewPoint,

          WindChill,

          Batv

         );

This function takes three arguments. The first is the character string, in this case we called it "Payload." This is the character string we will fill with the url. The second argument is the url text or characters. Any text with a percent in front of it refers to an injected variable from the third argument and in the order listed with a comma in between. So the first text with a percent is %s which means fill this with a string variable. The first variable is "Endpoint" define in the sketch as a C string or char variable and it is the first part of the url we need to send (i.e. https://api.thingspeak.com/update.json?) . Others are floats and ints or integers containing the data we want to send so we use %f or %d, respectively for those variables.

sprintf is a very important and useful function when the concatenate function strcat cannot be used because you need to inject various number and text formats into a string variable.

Here is an example of a GET url generated by this code. We replaced our api_key with X's.

https://api.thingspeak.com/update.json?api_key=XXXXXXXXXXXXXX&field1=16.00&field2=60.00&field3=995.00&field4=39.00&field5=158&field6=7.00&field7=21.00&field8=4.13

ThingSpeak expects data in "fields" so data is specified by field numbers instead of variable names. Sensor data is inserted into this url with the sprintf function in the GET Functions tab. It is worth some time studying how this sprintf function works as it is very useful for getting sensor data into a string. Most modems expect or at least can use strings to send data. They usually do not or cannot expect float or int data. 

We are going to send random numbers for weather data and actual measured battery voltage.  

Sensors are measured on the Sensor Functions tab. We have a function to measure battery voltage that also makes use of a function to read millivolts on any analog pin (battery voltage is measured on analog pin 4 on the Panther Logger).

We have a function called readSensors() that puts random numbers into mock weather sensor variables and implements the battery voltage measurement. In other tutorials in our Learning Center we show how to measure various kinds of sensors using the Panther Logger. We are not showing that here in this tutorial so as not to complicate the task of sending data to the internet.  In an actual application one would add additional functions here to read actual sensors on this tab, like weather and water quality sensors, soil moisture etc and then that data would get sent using the cellular modem provided that the sprintf function is updated to include them and that the server database is setup to receive them.  

On the GET Functions tab there is a function to make the url (i.e. the payload) and a function to send the payload using the HTTP GET method called "GetData." The GetData command sends multiple AT commands to the modem to setup communications and finally sends the data. Note that many of these AT commands are universal to all modems whereas some are specific to this Quectel modem. We put comments in the Arduino sketch indicating what each command is doing. 

Finally, the Cellular Functions tab contains functions to interact with the cell modem. This includes a function "sendAT" to send AT commands to the cell modem and read its response. It takes three arguments:

sendAT("AT+Command", "Response1", "Response2", Wait Time);

1. AT+Command = The AT command to send to the modem
2. Response1 = One of the expected responses from the modem, usually positive
3. Response2 = A second response expected from the modem, usually expected error code
4. Wait Time = Amount of time to wait for either response above

It is very important that code to send AT commands waits for an expected response from the modem whether it is a positive response or error before your program continues and sends another AT command. Sending multiple AT commands to the modem without waiting for each response from each AT command can cause the modem to freeze. This is why the code has multiple delays between sending AT commands along with this "sendAT" function to wait for expected responses. The AT command documentation for the Quectel BG96 modem provides the expected responses for each AT command. Generally a one second delay between sending AT commands is recommended.

This Cellular Functions tab in the sketch also contains functions to read network registration status, signal strength and quality. In other tutorials we will show how to read the date and time from the modem, get geolocation information and basic modem information like modem model number, SIM number, and network tower ID to which the modem is connected as well as the service provider.

Now we will send data using HTTP POST. We will also send the data over a secure sockets layer connection (HTTPS). We are going to send data to Ubidots so make sure you have setup an account as described in Panther Logger 3

Go to our Github respository page for the SendData_Cellular_POST code here. As with the GET code above there are multiple files, each one corresponding to a tab in the Arduino sketch. Copy the contents of each file and put into tabs in a new Arduino sketch as done for the GET code. Name the tabs according to the file names. The main (first) tab should be the code in the SendData_Cellular_POST.ino file.

Go to this code in the main tab:

char url[] = "https://industrial.api.ubidots.com";

char Host[] = "industrial.api.ubidots.com:443";

char Token[] = "X-Auth-Token: XXXXXXXXXXXXXXXXXXX";                                                                  

char Destination[] = "/api/v1.6/devices/XXXXXXXXXX";

The char url holds the endpoint address for Ubidots API and this is obtained from the Ubidots API documentation (here). The Host char will be inserted into the header information sent with the data and it should just be the domain name with a port of 443 since we are sending data over HTTPS. If sending over HTTP then the default is port 80. Again, check the API documentation for port settings. The token holds the API key or token or in this case "X-Auth-Token." The name of the token and the token itself will need to be changed according to the API documentation and of course your device's given token. The token from Ubidots is on your device information page. Copy the token from Ubidots and replace the X's in the Token char. In the Destination char ubidots used the device name that you gave your device when creating a new device at ubidots. In our case we called our device "Panther Logger" Replace the X's in the Destination char with your device name at Ubidots (see video on the right).

That's all that needs to be edited in the code. Go ahead and upload to your board and open the serial monitor.

As with the GET code above you will see AT commands sent to the modem and the modem responses. These AT commands register the modem on the network, get it setup for a POST request and then sends the data with a post command. Here is an example of a successful post request to Ubidots.

If you want to practice sending AT commands to the modem then you can upload our Cellular_Terminal sketch here. This will create a terminal from the serial monitor to talk to the modem. Upload the sketch and then open the serial window. The modem will be reset and then wait for "APP RDY."

At the bottom of the window set the line ending to "Both NL & CR." Then in the "send" box at the top of the serial window enter the simple AT command, AT, and then hit enter. The modem will respond with "OK." 

See video on the right for a demonstration and be sure to turn on captions.

You can now send any AT command here and see how the modem responds. This can be a good way to try out AT commands, see how the modem works, and troubleshoot problems with sending data or getting data from the modem. 

The AT command manual for the BG96 modem is here. Below are some useful AT commands. Try entering them into the serial monitor window and see the modem response.

The AT command below is in bold and the response in italics.

//Get modem model and revision number

ATI

Quectel

BG96

Revision: BG96MAR02A07M1G

//Get SIM card number. I replaced some numbers with X's

AT+GSN

8662330515XXXX

//Get the modem temperature. Returns temperature of three different parts of the modem (in Celsius)

AT+QTEMP

+QTEMP: 40,35,36

//Get the current date and time. Note this requires that the modem is registered on the network

AT+CCLK?

+CCLK: "23/12/11,08:13:15-24"

//Get signal strength and quality as well as current network.

//As you will see right now we are on a Cat-M1 network

//There are four numbers. The second and last numbers are the RSRP and RSRQ

//RSRP is strength and RSRQ is quality. See here for nice description.

AT+QCSQ

+QCSQ: "CAT-M1",-95,-125,108,-14

//Get network registration status

//We can send three commands at once

//This gets registration status for the three network types GPRS, ESD and CSD

//Look at the AT command manual for explanation of modem responses

//A response of 5 means registered and roaming

AT+CREG?;+CGREG?;+CEREG?

+CREG: 2,5,"4301","4A00F09",8

+CGREG: 2,4

+CEREG: 2,5,"4301","4A00F09",8

//Set to choose network automatically

AT+COPS=0

//Search for available networks

//This can take up to 30 minutes

//In my experience usually takes about 2 minutes

//This can be useful to do to get the modem registered initially

//Set AT+COPS=0 first and then:

AT+COPS=?

+COPS: (1,"311 589","311 589","311589",8),(1,"Verizon","Verizon","311480",8),(1,"311 588","311 588","311588",8),(1,"U.S.Cellular","USCC","311580",8),(2,"AT&T","AT&T","310410",8),(1,"313 100","313 100","313100",8),(3,"T-Mobile","T-Mobile","310260",8),(1,"311 490","311 490","311490",8),,(0,1,2,3,4),(0,1,2)

Get GPS Information

First we need to setup how we want to receive GPS information and then turn it on.

//Turn on the DC power to the GNSS antenna, and save it in this state across power off

AT+QCFG="gpio",1,64,1,0,0,1

OK

AT+QCFG="gpio",3,64,1,1

OK

//Query status of the antenna pin

AT+QCFG="gpio",2,64

+QCFG: "gpio",1

//Turn on GPS

AT+QGPS=1

OK

//Turn on NMEA output

AT+QGPSCFG="nmeasrc",1

OK

//Request NMEA sentences containing GNSS information. See here.

//The NMEA sentences "GGA" and "RMC" provides most information available.

AT+QGPSGNMEA="GGA"

+QGPSGNMEA: $GPGGA,,,,,,0,,,,,,,,*66

//The above response indicates we do not have GPS fix. Move device to clear view of the sky

We can enter the AT commands in the SendData_Cellular_GET sketch manually to send data to ThingSpeak. Copy and paste the AT commands below into the serial monitor line by line hitting enter to send each one. Replace the X's in the URL with your API key from ThingSpeak. This assumes you are using a Hologram.io SIM card. If not then change the APN in the AT+QICSGP command to your provider's APN. In the video to the right I am using a SIM card from Soracom, so the APN is set to "soracom.io" instead of "hologram"

AT+CFUN=1,1

ATE

AT+QCFG="nwscanseq"

AT+COPS=0

AT+QICSGP=1,1,"hologram"

AT+CREG=2;+CGREG=2;+CEREG=2

AT+QHTTPCFG="contextid",1

AT+QHTTPCFG="responseheader",1

AT+QHTTPCFG="requestheader",0

AT+QHTTPCFG="sslctxid",1

AT+QSSLCFG="seclevel",1,0

AT+QIACT?

AT+QIACT=1

AT+QIACT?

//After entering the AT command below the modem will respond with "CONNECT" and then you can enter the URL. 

//The first number is the length of the URL (number of characters), which you will need to determine manually

AT+QHTTPURL=165,80

https://api.thingspeak.com/update.json?api_key=XXXXXXXXXX&field1=23.00&field2=43.00&field3=962.00&field4=29.00&field5=300&field6=18.00&field7=22.00&field8=4.15

AT+QHTTPGET=80

//You will receive "ok" from the modem, but now wait for "+QHTTPGET: 0,200" (successful transmission) or at least some other response before continuing 

//Issue read command to get response from ThingSpeak server

AT+QHTTPREAD=80