Getting Started with Hologram SIM and RAK iTracker Module

Introduction.

We have seen quite a lot of projects on the RAK itracker and i definitely had a blast using this board to its full potential. With som many onboard sensors and connectivity option, this is a beast of a board and definitely a complete solution in the TRACKER BOARD department. 5/5 for that

This tutorial will cover the GSM parts of the board. we will be using Mbed for programming our nrf52 based iTracker board. Lets jump in..

Hologram.io services

According to the Hologram website:

Hologram provides flexible tools for securely connecting IoT devices. Whether you're deploying at scale or building your first connected product, Hologram's products handle all your connectivity infrastructure needs.

Hologram provides the cellular connectivity across continents to enable GSM connectivity for your end devices. Its really cool. They support nb iot wherever the services are enabled (sadly in india, nb-iot is yet to reach mainstream public consumption). However in countries like China, USA, you can use the sim for nb iot connectivity as well (do check the coverage for narrow-band connectivity before going in for the nb-iot options.)

Lets get started !!!

Visit the official website of Hologram. Click on "DASHBOARD" in the upper right corner @ Hologram.io and create your account.

Then click on "sign up" at the bottom of the page. Enter the registration interface. Follow theprompts to fill in the information to register.

Activate SIM card

After successful registration, log into your Hologram account and enter your Dashboard interface.Next you need to activate your purchased Hologram SIM card. Click on "Activate you first SIM" in the upper right corner of the page.

Enter the activation interface, according to the given prompts, fill in the information, you cancomplete the activation of the SIM car

After successful registration, enter the SIM card information interface. After waiting for a period oftime, you will see the “Live” status.

Hurray your sim is now activated. You can start using your sim to now send and receive data. you can also use it for sms send and receive as well. Make sure you check out the FUP for your plans and use the features accordingly to avoid additional costs.

Off to Mbed land then......

The beauty of the itracker board is the ability to progam it in a variety of ways. one of them is using the online mbed compiler.

In case you missed setting up your mbed account and other details. Please check out the tutotrials below where i have explanied the step-by-step procedure to use the online compiler.

https://www.hackster.io/naresh-krish/getting-started-with-mbed-development-on-rak-itracker-be47d7

The GSM hardware:

The GSM hardware on the itracker has a variety of versions available.

1) Quectel M35

2) Quectel BC-95-G

3) Quectel BG-96

The quectel BG96 version is versatile as it supports both regualr 3g/4g connectivity and LTE CAT m1/Nb-iot connectivity on the same board.

We will consider the BG96 version for now. but running the samples below should be the same for the other two boards as well; except when trying to use nbiot features. We will cover the nbiot specifics in a later tutorial.

Switching on the GSM module.

The GSM module is connected to the power rails by a TPS2708 siwtching module like so:

The PWR_GPRS_ON pin on the nrf52 corresponds to the pin number P0.06 and the pwrkey key corresponds to the pin P.0.15.

The pseudo code for sending the power on signal is like so:

GPRS power on:

gsm_on = 0;

wait_ms(200 millis);

gsm_on = 1;

wait_ms(200 millis);

GPRS Boot (start the module):

gsm_pwrkey = 0;

wait(2.0 secs);

gsm_pwrkey = 1;

wait(1.0 seconds);

Once the module is powered on and booted, you can communicate with the module via the normal tx rx lines (pin p20, p12 respectively).

So lets see a small skeleton code for testing the hello world of all GSM modules; "Sending the AT command"

#include "mbed.h"
#include "SEGGER_RTT.h"
DigitalOut gsm_on(p6);
DigitalOut gsm_pwrkey(p15);
void gsm_pwr_on();
void gsm_boot();
void check_gsm();
Serial gsm(p20, p12); // tx, rx
//Serial callback when the serial port has data in it
//read the buffer here.
void callback_ex()
{
   // Note: you need to actually read from the serial to clear the RX interrupt
   while(10) {
       SEGGER_RTT_printf(0, "content from serial :: %c \n", gsm.getc());
   }
}
// main() runs in its own thread in the OS
int main()
{
   gsm.baud(9600);
   gsm.attach(&callback_ex);
   SEGGER_RTT_printf(0, "POWERING GSM Module \n");
   gsm_pwr_on();
   SEGGER_RTT_printf(0, "INITIATING GSM MODULE bootup \n");
   gsm_boot();
   SEGGER_RTT_printf(0, "GSM power up sequence complete...check LED1 \n");
   wait(30);
   for(int i=0; i<5; i++) check_gsm();
}
void gsm_pwr_on()
{
   gsm_on = 0;
   wait_ms(200);
   gsm_on = 1;
   wait_ms(200);
}
void gsm_pwr_off()
{
   gsm_on = 1;
   wait_ms(200);
   gsm_on = 0;
   wait_ms(200);
}
void gsm_boot()
{
   gsm_pwrkey = 0;
   wait(2.0);
   gsm_pwrkey = 1;
   wait(1.0);
}
void check_gsm()
{
   SEGGER_RTT_printf(0, "send ATI command to check GSM module \n");
   gsm.printf("ATI\r\n");
   wait(1);
}

I have added some helper functions to power down the module as well if you need to.

Now the main test function that we have is the check_gsm function that send the ATI command. This command returns the following:

Example:
ATI
Quectel
BG96
Revision: BG96MAR01A01M1G
OK

Once you test that your module is pwoered on and responding to your ATI request. It time to mode forward.

Sending an SMS:

For sending and SMS these are the steps involved:

First, enter the command line "AT+CMGF=1" in the terminal to instruct the GSM/GPRS modem to operate in SMS text mode. Below is the response returned from the module after the execution of the command line "AT+CMGF=1":

Request: AT+CMGF=1Response: OK

You can alternately check the current test mode selected in the module by sending

Request: AT+CMGF=?

Response: +CMGF: (0,1)OK

Sending Text Messages

Next, use the +CMGS AT command to send a text message to the SMSC. Suppose you want to send a text message to the mobile phone number +1234567891, you should enter something like this in a terminal program:

Request: AT+CMGS="+1234567891"

Then, send the carriage return newline feed combo to the serial port of modem. The GSM/GPRS modem will send back a prompt formed by four characters. They are the carriage return character, the linefeed character, the ">" character and the space character. If all characters are to be displayed, the characters you have sent to and received from the GSM/GPRS modem so far are:

Request: AT+CMGS="+1234567891"<CR><CR><LF>><Space>

AT+CMGS="+1234567891"Response: >

Here the serial port is waiting for you to type your text and send the data to the sms command.

So continue sending your string of characters to the command and then once finished, send the <Ctrl+z> characters to tell the module that the sms message is complete. This will trigger the module to send the sms to the SMSC.

AT+CMGS="+85291234567"> It is easy to send text messages. <send ctrl-z here>+CMGS: 12

Response: OK

The OK corresponds to a successful sms delivery to the SMSC. Further the sms center will forward the SMS to the concerned target number.

So a quick sample function for sending sms would be

void send_sms(){
   gsm.printf("AT+CMGF=1\r\n");
   wait_ms(200);
   gsm.printf("AT+CMGS=\"+1234567891\"\r\n");
   wait_ms(200);
   gsm.printf("Hello world from itracker");
   gsm.printf("%c", 0x1a);
   wait_ms(200);
}

The 0x1a is the hex form of the ctrl-z command that needs to be sent to mark the end of the message string.

You should see the sms land in the number that you mentioned in the second gsm.printf statement.

Throughout this time, you can monitor your serial port log messages using the callback function and the data it returns. debugging is possible by simply reading the output in the cuffer inside the callback function.

Receiving SMS:

For receiving SMS here is the At commands list:

AT+CMGF=1 --> Establishes text mode in modem
AT+CMGL="REC UNREAD",1 --> Checks if exists unread SMS. Return OK if not exist any SMS, in other case returns a list with them (the first number of each of them are the index of each of them).
AT+CMGR=[sms_index],0 --> Read SMS with index sms_index from modem memory (ej: AT+CMGR=1,0).
AT+CMGD=[sms_index] --> Delete SMS with index sms_index from modem memory (ej: AT+CMGD=1).

I'll leave the code for this as an excercise for the reader. Remember, the callback function will return the input buffer on the serial port. so reading your sms would return the sms data in the callback function. :)

Sending and receiving TCP data:

Here is the AT commands set for sending TCP data over GSM:

AT+COPS=? // Find nearby network information
AT+COPS=1,0,”Vodafone”,0 // Manually set up a connected network
AT+CREG? // Check whether the device is registered on the network
AT+QNWINFO // Query connected network information
AT+COPS? // Query the connected web server information
AT+QICSGP=1,1,"hologram","","",1 // Set APN network to hologram
AT+QIACT=1 // Activate the APN network
AT+QIACT? // Query the APN assigned IP address
AT+QIOPEN=1,0,"TCP","23.253.146.203",9999,0,1 // Create a TCP, connection hologram test server
AT+QISEND=0,48 // Send data, send data length is 48
{"k":"bZmmdbAg","d":"Hello,World!","t":"TOPIC1"} //Send Packets.The data format is a hologram-defined format.( For details, please see: https://hologram.io/docs/reference/cloud/embedded/ )\
AT+QISEND=0,0 // Query data is sent successfully

The command set is pretty straight forward and you should be able to send the individual lines using the serial API printf statement. Remember to always terminate each command with the "\r\n" combo.

After the device is sent successfully, you can see the sent information on your interface of the Hologram Dashboard:

The Mbed Firmware:

Important stats about the firmware will be present in the left hand side pane on the compiler called 'build':

The firmware is be default a combination of the softdevice for the nrf52 and the Mbed OS+app. The Softdevcie is nothing but the bare metal BLE stack provided by Nordic for its BLE chipsets. The Mbed online compiler will always choose the latest softdevice for you so you don't need to worry about the version being used.

Now lets flash the firmware.

Flashing the firmware:

The firmware is always a hex file. Our firmware wouldnt have the bootloader also in built which we will get to in the upcoming tutorials in much more detail. For now we will just flash the hex directly.

Open a commandline prompt. I will consider Ubuntu OS for this.

Run the following commands:

cd to the folder containing the firmware you just downloaded
nrfjprog -e -f nrf52
nrfjprog --program xxx.hex -f nrf52 --verify
nrfjprog -f nrf52 --reset

Your board should reset and now open your favorite BLE app on your android/ios phone/tab. I prefer the NRFtoolbox app. Install the app and scan for BLE devices. You should see the itracker show up on the app.

Flashing firmware using nrfGo:

This firmware upgrade scenario involves uploading the application onto the board using a cable connection.

You will require nRFgo Studio to run this procedure. Alternatively, you can use a J-Link programmer.

Follow these steps to update Thingy using your own compiled application:

• Start nRFgo Studio.

• Connect your board to the host.

• Select nRF52 development boards.

• Click Erase all.

• In the Program SoftDevice tab, browse for the S132 v4.0.2 HEX file and click Program.

• In the Program Application tab, browse for your application HEX file and click Program.

Follow these steps to flash the factory image:

• Start nRFgo Studio.

• Connect your board to the host.

• Select nRF52 development boards.

• Click Erase all.

• In the Program Application tab, browse for the factory HEX file and click Program.