LTE Cat M1/NB-IoT Shield Hookup Guide

Contributors: jimblom

Example 3: Receive a Hologram Message

Now that you've sent a message via TCP/IP services, this example demonstrates how to create a local listening socket on your LTE Shield to receive data.

Again, this example uses Hologram to send a message from a web portal down to the shield. If you don't have a Hologram SIM, consider checking out the library-how-to at the end.

To load up the TCP receive example go to File > Examples > SparkFun LTE Shield Arduino Library > 03_TCP_Receive_Hologram.

You shouldn't need to modify anything in this example. Just upload away! After uploading open up your serial monitor. Then open up your Hologram dashboard.

Next, from your device's Hologram dashboard type a message to send **via Cloud Data* and send that data message (keep the Port as 4010 and protocol as TCP).

After not too-long, you should see the message pop up in your Serial Monitor.

Listening, Callbacks, and Polling

This example builds on using sockets from the last example, and introduces a couple new concepts as well.

socketListen can be used after opening a socket to set up a listening port on the SARA-R4 module. This function takes a socket to use and a port to listen on -- 4010 in this example.

language:c
if (lte.socketListen(socket, 4010) == LTE_SHIELD_SUCCESS) {
  Serial.println("Listening on socket 4010");
}

While a socket is open and listening, data comes into the SARA-R4 module asynchronously. To catch this data, the library implements a poll function, which should be called as often as possible in the loop(). poll() is designed to monitor the UART, and, if it sees data come in from a socket, relay that back to the Arduino sketch.

To pull in data from the poll() function, a callback is used. This callback should provide two parameters: an int socket and a String message. The example below demonstrates how to declare a socket-read callback, register it, and poll for data:

language:c

void processSocketRead(int socket, String message) {
  Serial.println("Read: " + message);
  Serial.println("From: " + String(lte.lastRemoteIP()));
  Serial.println("Socket: " + String(socket));
}

void setup() {
  // Provide setSocketReadCallback a pointer to our socket-read callback
  lte.setSocketReadCallback(&processSocketRead);
}

void loop() {
  // Poll as much as possible to catch asynchronous data coming into LTE Shield
  lte.poll();
}

This example also demonstrates a similar callback functionality to take action on an asynchronously-closed socket. setSocketCloseCallback() can be used to set a closed-socket callback. The callback should take a single parameter -- the socket closed. The example uses this callback to re-open a listening socket if that's what the closed socket was.