Development

Networking:

» LoRa Gateway tutorial

1 - LoRa vs LoRaWAN

The LoRa module and the LoRaWAN module are not compatible because the protocols are different. The LoRa module implements a simple link protocol, created by Libelium. However, the LoRaWAN module runs the LoRaWAN protocol, a much richer and more advanced protocol, created by the LoRa Alliance.

The LoRa Gateway provided by Libelium does not support any LoRa Alliance feature.

2 – Introduction

The SX1272 LoRa module can work in Waspmote, Plug & Sense!, Arduino, Raspberry Pi or Intel Galileo. The normal topology for this technology is a star: all the nodes transmit towards a central sink node. This central sink node can be:

  • another LoRa node (Waspmote, Plug & Sense!, Arduino, ..)
  • one LoRa Gateway

This tutorial will guide you in the process of configuring a LoRa module in a PC with the aid of a LoRa Gateway, and testing the reception and sending of LoRa packets from Waspmote, Plug & Sense!, Arduino, Raspberry Pi or Intel Galileo.

To perform these actions you need a LoRa node and a LoRa Gateway, the device that allows you to communicate through a USB port with the module.

You also need a terminal program like Cutecom (Linux), Hyperterminal or Putty (Windows). There are plenty of this type of program, so you can use the one you are comfortable with.

3 – Comunications setup

The communication with the Gateway has to have this setup:

  • Baudrate: 38400
  • 8 Data bits
  • No parity
  • 1 Stop bit

You have to select the port in which your system has detected the gateway. It’s usually /dev/ttyUSBX in Linux and COMX in Windows.

cutecom_gateway_lora

Note: In Unix-based systems (Linux, MacOSX) you need to be part of the dialout group to access the serial ports

The communication between the PC and the module uses a protocol designed for this specific use. The protocol uses some special characters that ensure the orders are properly read and a checksum to avoid possible transmission errors:

Special characters:

  • SOH (Start of Header – ASCII 0×01)
  • CR+LF (Carry return + line feed -ASCII 0x0D and 0x0A)
  • EOT (End of Transmission – ASCII 0×04)

Error check:

  • CRC16-Modbus. You can perform this calculation on this site (or any other site of your confidence).[We do not offer any warranty of this calculation as is an external site, if you want reliability, program a function to calculate CRC16-Modbus]

The commands used for the module are:

  • READ – Gets the current setup of the module
  • SET – Set a new configuration in the module
  • DATA – Sends data from the module to a Waspmote
  • ERROR – Notifies an error in the information received
  • INFO – With this command, the module gives its setup.
  • ACK – With this command the module notifies that a message has been successfully sent

As you need to send non-printable characters hexadecimal characters, you will need a way to enter these characters in the terminal.

Programs as Cutecom allow to enter hexadecimal numbers to enter these characters. In this case, translate to hexadecimal all the characters in the command. If you are using another program, you can use some tools to edit hexadecimal characters.

You can find here a useful tool for this conversion (again without any warranty): here

An hexadecimal read command would be:
01 52 45 41 44 0D 0A 32 41 33 31 04

Some programs like Cutecom also allow to send hexadecimal characters mixed with ASCII (0×01 – SOH, 0×04 – EOT, 0x0D – CR, etc ), the last command could be sent in Cutecom with:

0x01READ0x0D0x0A2A310x04

4 – Module setup instructions

4.1 – Read current setup of the module

In order to read the setup of the module, you have to send a READ command.

The READ command has this structure:

  • SOH character (Start of Header – ASCII 0×01)
  • command: READ
  • CR+LF characters (Carry return + line feed -ASCII 0x0D and 0x0A).
  • CRC16-Modbus code of the bytes between SOH and CR+LF (not including these) (2 hexadecimal bytes)
  • EOT character (End of Transmission – ASCII 0×04)

The frame would be:

[SOH]READ[CR+LF]2A31[EOT]

The same command in hexadecimal format: 01 52 45 41 44 0D 0A 32 41 33 31 04

The module will reply with an INFO frame. This frame has this structure:

  • SOH character (Start of Header – ASCII 0×01)
  • Reply command: INFO
  • Separator # (ASCII 0×23)
  • Setup data “;” separated. Each data will have the format “NAME:value”. The fields of this command are: FREC, ADDR, BW, CR, SF, RSSI and SNR. Last two parameters are optional.
  • CR+LF characters (Carry return + line feed – ASCII 0x0D and 0x0A).
  • CRC16-Modbus code of the message between SOH and CR+LF (these not included) (2 hexadecimal bytes)
  • EOT character (End of Transmission – ASCII 0×04)

An example would be:

[SOH]INFO#FREC:CH_13_868;ADDR:3;BW:BW_125;CR:CR_6;SF:SF_6;RSSI:32;SNR:21[CR+LF]FB05[EOT]

4.2 – Write a new setup to the module

In order to configure the module, you have to send a SET command. The command has this structure:

  • SOH character (Start of Header – ASCII 0×01)
  • command: SET
  • Separator # (ASCII 0×23)
  • Configuration data separated by “;”. Each parameter has the format:
  • NAME:value
  • Fields required are: FREC, ADDR, BW, CR y SF. Accepted values are:
  • FREC (frequency and channel): CH_X_Y where X is the channel and Y the frequency band. Bands allowed are 900 and 868 (MHz). Channels allowed are 10 to 17 for 868 MHz band and 00 to 12 for 900 MHz band.
  • ADDR (address): Number between 1 and 255.
  • BW (Bandwidth): BW_X where X can be 125, 250 or 500 kHz
  • CR (coding rate): CR_X where X is a number between 5 and 8.
  • SF (Spreading factor): SF_X where X is a number between 6 and 12.
  • CR+LF characters (Carry return + line feed – ASCII 13 and 10).
  • CRC16-Modbus code of the message between SOH and CR+LF (these not included) (2 hexadecimal bytes)
  • EOT character (End of Transmission – ASCII 04)

Let’s see a complete example step by step.

Step 1: The user chooses the settings. For example: FREC is set to 868 MHz channel 13, ADDR is set to ’3′, BW is set to 125 kHz, CR is set to 4/5 and SF is set to ’12′. The command to be generated is:

[SOH]SET#FREC:CH_13_868;ADDR:3;BW:BW_125;CR:CR_5;SF:SF_12[CR+LF]245A[EOT]

Step 2: In order to generate the CRC which value is 245A, the user must copy the contents between [SOH] and [CR+LF]: SET#FREC:CH_13_868;ADDR:3;BW:BW_125;CR:CR_5;SF:SF_12 and convert it to hexadecimal format using the proper tool. The result of this operation is:

53 45 54 23 46 52 45 43 3a 43 48 5f 31 33 5f 38 36 38 3b 41 44 44 52 3a 33 3b 42 57 3a 42 57 5f 31 32 35 3b 43 52 3a 43 52 5f 35 3b 53 46 3a 53 46 5f 31 32

After this, the HEX data is used for generating the CRC16-Modbus thanks to the proper converter. The result is: 245A

Step 3: Finally, it is necessary to include the special characters [SOH], [CR+LF] and [EOT] to the frame as seen in step 1 and convert all the frame to hexadecimal format. The final command is:

01 53 45 54 23 46 52 45 43 3a 43 48 5f 31 33 5f 38 36 38 3b 41 44 44 52 3a 33 3b 42 57 3a 42 57 5f 31 32 35 3b 43 52 3a 43 52 5f 35 3b 53 46 3a 53 46 5f 31 32 0d 0a 32 34 35 41 04

When the resulting command is executed, the module will try to setup these parameters and in case of success, it will reply with an INFO frame confirming the new setup data. In case of one of the parameters couldn’t be set in the module, it will keep its old setup in ALL the parameters and reply with an ERROR frame.

4.3 – ERROR message
If the controller of the module detects a problem in the communication, it will reply with an ERROR frame. This frame informs of the problem, that could be for example a CRC error in the command or an error in one of the parameters to write.

The ERROR frame has this structure:

  • SOH character (Start of Header – ASCII 0×01)
  • command: ERROR
  • Separator # (ASCII 0×23)
  • Error Message in ASCII. This will be an explicit message of what the error is.
  • CR+LF characters (Carry return + line feed -ASCII 0x0D and 0x0A).
  • CRC16-Modbus code of the message between SOH and CR+LF (these not included) (2 hexadecimal bytes)
  • EOT character (End of Transmission – ASCII 0×04)

An example of this message would be:

[SOH]ERROR#BAD CRC[CR+LF]6BED[EOT]

5 – Reading data from Waspmote

When you have started a connection with the module in your terminal application, the module will automatically send through the serial port the frames received from any Waspmote. These frames will have the data frame structure described in the Waspmote frame guide. You can read further about Waspmote data frame here.

6 – Sending data to Waspmote

You can send data from your LoRa gateway to any other LoRa equipped device. You can send data to Waspmote and Meshlium.

In order to send data, you have to use the DATA command. The structure of this command is:

  • SOH character (Start of Header – ASCII 0×01)
  • command: DATA
  • Separator # (ASCII 0×23)
  • Destination address: Number between 1 and 255. 0 for broadcast message.
  • Separator # (ASCII 0×23)
  • Message type. Allowed type is ASCII (text). Also binary type is allowed but it is not implemented.
  • Separator # (ASCII 0×23)
  • Message to send. If you want to send non-printable ASCII chars you need to escape them before with the character ESCAPE (ASCII 0x1B) and the character you want to send. You have to escape too the character # (ASCII 0×23) in order to put it in a message.
  • CR+LF characters (Carry return + line feed -ASCII 0x0D and 0x0A).
  • CRC16-Modbus code of the message between SOH and CR+LF (these not included) (2 hexadecimal bytes)
  • EOT character (End of Transmission – ASCII 0×04)

An example would be:

[SOH]DATA#2#ASCII#THIS IS THE MESSAGE[CR+LF]9DD5[EOT]

The command to be executed in HEX format:

01 44 41 54 41 23 32 23 41 53 43 49 49 23 54 48 49 53 20 49 53 20 54 48 45 20 4d 45 53 53 41 47 45 0d 0a 39 44 44 35 04

If the message is properly sent, the module will reply with an ACK message. The structure of this frame is:

  • SOH character (Start of Header – ASCII 0×01)
  • command: ACK
  • CR+LF characters (Carry return + line feed -ASCII 0x0D and 0x0A).
  • CRC16-Modbus code of the message between SOH and CR+LF (these not included) (2 hexadecimal bytes)
  • EOT character (End of Transmission – ASCII 0×04)

An example of this message would be:

[SOH]ACK[CR+LF]D350[EOT]

In case of a broadcast message, there is no way to ensure that the message has been delivered. No ACK will be received in this case.

If the message could not be delivered, the module will return an ERROR message with “NOT SENT” in case of the module could not send the message and “NOT RECEIVED” in case it could not confirm that the message has been properly received.