Connectivity

Topologies

Several LoRa modules can be set in a star topology to create a network. A star network has a central node, which is linked to all other nodes in the network. The central node gathers all data coming from the network nodes.

It is not possible to set mesh networks with the LoRa module.

Libelium offers the following options for the central node:

  • Gateway LoRa: This special Gateway enables the user to receive data directly in a standard PC. It is interesting for the first development phase, and can be used to test a real project or to do less advanced tasks.

Figure: Star topology with Gateway as central node
  • Waspmote: It is the less interactive option. In order to send the data to Cloud or via wireless, it is necessary to have another radio module available. Since Plug & Sense! can only have one radio, the user can just receive packets and output them via USB port.

Figure: Star topology with Waspmote as central node

Connections

Every packet sent contains a Source Address byte and Destination Address byte in its payload field. The module supports only 8-bit addresses. For every node, a unique 8-bit Source Address (Node Address) must be chosen by the user and assigned each time the module is powered on. This address can be set and read with the functions explained in chapter "Node Parameters".

The LoRa module supports Unicast and Broadcast transmissions.

Unicast

Unicast is used to send a packet to one specific node in a network through its Node Address. Unicast always performs control time mechanisms (time-out) to prevent perpetual waiting for a packet. Unicast mode is the only one that supports additional services for more robust communication like:

1 - ACK confirmation: if the developer uses functions like sendPacketTimeoutACK() and receivePacketWithTimeoutACK(), receiving modules will send an ACK (packet which aim is to confirm the packet was correctly received) to the transmitter.

Figure: ACK confirmation diagram

Unicast mode with ACK example:

2 - Retries: this option is only available with ACK confirmation. If the transmitting module does not receive the ACK, it will re-send the packet up to the configured number of times or until the ACK is received.

Figure: ACK and retries diagram

Unicast mode with ACK and retries example:

Broadcast

Broadcast is used to send a packet to all nodes in a network. Any module within range will accept a packet that contains the broadcast address (0). To send a broadcast message, the Destination Address should be set to BROADCAST_0. While in this mode, there is no possibility to use ACK confirmations or retries.

Connection parameters

There are some parameters related to connections and their configurations.

Setting retries

It specifies the number of retries than can be sent for a given Unicast packet and stores it in the global variable _maxRetries. Parameter range: from 0x00 to 0x05. Default value: 0x03.

Example of use:

{
sx1272.setRetries(2); // Sets the number of retries that can be sent
}

Related variables:

sx1272._maxRetries → stores the maximum number of retries that can be sent

Sending process

Sending data is a complex process which needs some special structures and functions.

SX1272 API packet structure

The API packet structure used to transmit packets with LoRa modules is specified in the following figure. It shows how the payload is included inside the RF Data field:

Figure: Frame structure inside a packet structure

Generally, the user will add the information to be sent with the Frame library (frame.addSensor()). The Frame library encapsulates it in a frame instance. Then, the user will pass this frame instance to the send function, which will encapsulate it inside a packet. Finally, the LoRa module will encapsulate that in a RF packet and send it.

Using Frame class to create SX1272 packets

Frame is a class that allows the user to create data frames with a specified format. It is a very useful tool to set the payload of the packet to be sent. It is recommended to read the Waspmote Data Frame Guide in order to understand the LoRa module examples:

SX1272 sending Frame examples:

Sending data

This is the process to send a packet between SX1272 devices.

Send data

The API function responsible for sending data is called indicating the Destination Node Address and the payload data to send:

sx1272.sendPacketTimeout(destination, payload);

Related variables:

sx1272.packet_sent → stores the structure of the packet to send

SX1272 sending example:

The user may want to add services for more robust communication, like ACK confirmation or retries. In order to send ACK confirmation, there are some special functions and a specific packet format, shown in the following figure. We also show examples for these services next:

Figure: ACK structure inside a packet structure

Send packets in unicast mode and wait for a response:

Send packets in unicast mode, wait for a response and retry to send the packet if there is no response:

Receiving data

Normally, the only receiver node in a network is the central node.

Receiving data in Waspmote is a complex process which needs some special structures to carry out. These operations are transparent to the API user, so it is going to be explained the necessary information to be able to read properly a received packet.

Before any packet has been received, an structure of pack is created. This pack is called packet_received.

The size of this array is defined by a field in the structure.

How to receive packets in Waspmote

To receive any packet, first it is necessary to know what kind of communication is being used. The used function will be different if we want to receive packets or if we want to receive packets and answer with an ACK confirmation too. All receiving functions are protected with a time-out method to avoid perpetual waiting.

In the case of ACK receiving functions, the SX1272 library automatically sets the destination address of the ACK packet to the sender node.

Example of use:

{
sx1272.receivePacketTimeout(); // Receive packets
sx1272.receivePacketTimeoutACK(); // Receive packets and response to the sender with ACK
}

Related variables:

sx1272.packet_received → stores the structure of the last packet received

sx1272.ACK → stores the structure of the ACK

Receiving packets example:

Receiving packets and answering with ACK example:

Receiving packets, sending a response and retrying to receive the packet example:

How to show received Frames

If the received packet has the structure of a Waspmote Frame inside the payload, there is a specific function to show it correctly, after being received.

Example of use:

{
sx1272.showFramefromPacket(); // Show a Waspmote frame properly
}

If the received packet is just a plain-text message or the user prefers to know the packet contents: destination, source, packet number and retry fields, there is other function for that purpose.

Example of use:

{
sx1272.showReceivedPacket(); // Show received packet contents
}

Receiving frames insides packets examples:

Receiving all packets

Due to the architecture of the LoRa module, all nodes in a channel with the same configuration mode listen any packet. Depending on the destination address, each node will hold packets addressed to it, and discard others.

The user can decide to receive all packets, no matter the destination address. This is called promiscuous mode. The user should know that the only way to protect transmissions is using Encryption libraries.

Receive all the packets sent to any destination:

Receive all the packets sent to any destination and send a response back to the sender: