LTE Cat M1/NB-IoT Shield Hookup Guide

Contributors: jimblom

Example 2: Send a Hologram Message

Our next example demonstrates how to send a message to the Internet via the SARA-R4's support for TCP/IP protocols.

Load this example by opening File > Examples > SparkFun LTE Shield Arduino Library > 02_TCP_Send_Hologram.

Before uploading this example, you'll need your Hologram device's device key. This can be found in your Hologram dashboard. Navigate to your device, and click the "DEVICE KEY +" in the top-left-ish corner.

With that set, upload away! Then open the serial monitor at 9600 baud. As with the previous example, set your line-ending setting to Newline.

Open up your Hologram dashboard, then, from the serial monitor, type a message you'd like to send to the Hologram messaging server.

After a few seconds, you should see the message appear in your device's Hologram dashboard.

Using TCP/IP Sockets

This example demonstrates how to use the LTE Shield's TCP/IP socket capabilities. Sockets are a very common interprocess communication tool for sending and/or receiving data across a variety of networking protocols. In this case, we'll be using socket to send data over a TCP network link. The SARA-R4 module supports up to seven concurrently-open sockets -- usually we'll only need one-or-two at a time.

To begin, open a socket with the socketOpen function. This function takes one parameter -- an indication of whether you want to open a TCP or UDP socket. Possible parameters are LTE_SHIELD_TCP or LTE_SHIELD_UDP.

language:c
int socket;
socket = lte.socketOpen(LTE_SHIELD_TCP);
if (socket < 0) {
  Serial.println("Unable to open a socket");
}

socketOpen should return a value between 0 and 6. This is your socket -- protect it well!

Once your socket is open, it's time to use it to connect to a server. For that, there's the socketConnect function. This function takes a socket number, URL or IP address, and port to connect to. In this example we use the socket received from socketOpen and use it to connect to hologram.io on port 9999.

language:c
const char HOLOGRAM_URL [] = "cloudsocket.hologram.io";
const unsigned int HOLOGRAM_PORT = 9999;
if (lte.socketConnect(socket, HOLOGRAM_URL, HOLOGRAM_PORT) == LTE_SHIELD_SUCCESS) {
  // Send our message to the server:
  Serial.println("Connected to Hologram server!"));
}

Once you're connected to the server, it's time to send some data! For that, there's the socketWrite function. This function takes, again, a socket, and a String'ed message. You'll need to be careful with the message if you're sending it to the Hologram servers. It should be a JSON-encoded String of the format described here: https://hologram.io/docs/reference/cloud/embedded/#send-a-message-to-the-hologram-cloud. (See the example code for help constructing a compatible JSON string.)

language:c
String message = "{\"k\": \"a8F8asd4\", \"d\":\"Hello, world!\"}"
if (lte.socketWrite(socket, message) == LTE_SHIELD_SUCCESS) {
  Serial.println("Successfully sent message!");
}

Finally, you can close a socket using the socketClose function. Sometimes a server will close the socket on its side, but it helps to sometimes be pre-emptive in your socket-closing.

language:c
if (lte.socketClose(socket) == LTE_SHIELD_SUCCES) {
  Serial.println("Sucessfully closed a socket!");
}