Blues.ONE Quick Start Guide

Prerequisites

Before going through each step in the installation guide of the Blues.ONE WisTrio LTE-M NB-IoT LoRaWAN Development Board, make sure to prepare the necessary items listed below:

Hardware

Blues.ONE LTE-M, NB-IoT, GSM cellular and LoRaWAN Development Board
USB-C Cable
Li-Ion 3.7 V rechargeable battery
5 V Solar Panel (optional)
Nano SIM card if you are using the Blues.IO Notecard in a region that is not supported by the eSIM of the Notecard. You can check the coverage on the Blues.IO Coverage Overview

Software

Download and install the ArduinoIDE.
To add the RAKwireless Core boards on your Arduino Boards Manager, install the RAKwireless Arduino BSP.
Blues WisBlock Tracker- the default firmware that is pre-flashed on the Blues.ONE Solution.

Package Inclusion

When you buy Blues.ONE, you can choose between two variants: one with bare modules and antennas and one with an enclosure and more optimized antennas.

Figure 1: Blues.ONE modules without Enclosure

Figure 1: Blues.ONE with Enclosure

Product Configuration

Hardware Setup

Blues.ONE Without Enclosure

Assemble each module, including the respective antenna. Refer to Figure 3 for the connections.

Figure 1: Blues.ONE Modules and Antenna Connection

When the modules are plugged in together, they should look the same as in Figures 4 and Figure 5:

Figure 1: Blues.ONE Modules top view

Figure 1: Blues.ONE Modules bottom view

Blues.ONE With Enclosure

If you have the Blues.ONE with enclosure, you have to prepare the WisBlock Modules together with the WisBlock Baseplate with antenna, circular connector, IPEX-SMA cellular antenna connector, and GPS antenna.

Figure 1: Blues.ONE with Enclosure

On the WisBlock Baseplate, you have to remove the cutout that is designed to be used for the mini-base board. This cutout part must be removed for Blues.ONE.

Figure 1: Removing the cutout section of the WisBlock Baseplate

After removing the cutout, you can now attach the WisBlock Base Board to the WisBlock Baseplate using screws.

Figure 1: Attaching the WisBlock Base board to WisBlock Baseplate with PCB Antenna

The next step is to connect the IPEX-IPEX from the WisBlock Core to the WisBlock Baseplate with an antenna.

Figure 1: IPEX-to-IPEX connector

Then, you can now attach it to the enclosure and complete it with the rest of the parts.

Figure 1: Mounting the modules to Blues.ONE enclosure

Figure 1: Assembled Blues.ONE with all the parts

NOTE

After assembling all the parts, connect the battery to the WisBlock Base. Without the battery connected, the Blues.IO Notecard will not be able to function correctly due to a lack of power source. The USB connection will not be able to provide enough power to achieve enough performance stability.

Power Supply with External 5V

warning

The RAK13102 module and the connected WisBlock Base Board and Core module can be supplied with a regulated 5V DC supply through the P1 connector on the bottom. A matching connector is available with our M8 Power Connector

Figure 1: 5V supply through M8 power connector

Figure 1: M8 power connector

Software Setup

Setup Using the Pre-installed Firmware

The Blues.ONE WisBlock Solution comes pre-flashed with location-tracking firmware that utilizes both cellular and LoRaWAN connectivity to transmit the acquired location to the cloud.

You have to set up your Notecard at Blues.IO before it can be used. There are two options for setting up the Notecard:

To follow the Quickstart guides provided by Blues. To set up the device with AT commands directly through the WisBlock's USB.

Option One: Notecard Setup Through the USB of the RAK13102 Notecard

Connect the RAK13102 NoteCarriers USB to your computer. WisBlock has to be powered separately, and then use the Blues Quickstart.

Option Two: Set Up Through AT commands

warning

If setting up the Notecard through AT commands, these settings will always override settings that are stored in the Notecard. To remove settings saved from AT commands, use the AT command ATC+BR to delete all settings saved from AT commands before.

Connect the WisBlock USB port to your computer and connect a serial terminal application to the COM port.

Setup the Product UID

To connect the Blues Notecard to the NoteHub, a Product UID is required. This product UID is created when you create your project in NoteHub as shown in Set up Notehub.

Get the Product UID from your NoteHub project:

Figure 1: Notecard PUID

Then use the ATC+BEUI command to save the Product UID in the WisBlock:

ATC+BUID=com.my-company.my-name:my-project

Replace com.my-company.my-name:my-project with your project EUI.

The current product UID can be queried with

ATC+BUID=?

Select the SIM card

There are two options for the Blues Notecard to connect. The primary option is to use the eSIM that is already on the Notecard. However, there are countries where the eSIM is not working yet. In this case, you need to use an external SIM card in the RAK13102 WisBlock module. This can be a SIM card from your local cellular provider or an IoT data SIM card like for example a SIM card from Monogoto↗️ or from another provider.

Use the AT command ATC+BSIM to select the SIM card to be used.

The syntax is ATC+BSIM=<SIM>:<APN>

<SIM> == 0 to use the eSIM of the Notecard only
<SIM> == 1 to use the external SIM card of the RAK13102 NoteCarrier only
<SIM> == 2 to use the external SIM card as primary and the eSIM of the Notecard as secondary
<SIM> == 3 to use the external SIM card as secondary and the eSIM of the Notecard as primary

If the external SIM card is selected (<SIM> is 1, 2, or 3), the next parameter is the APN that is required to connect the Notecard <APN> e.g. internet to use with the Filipino network provider SMART. Several carriers will have a website dedicated to manually configuring devices, while others can be discovered using APN discovery websites like apn.how↗️

The current settings can be queried with AT+BSIM=?

Select Notecard Connection Mode

The Blues Notecard supports different connection modes. For testing purposes, it might be required to have the Notecard connected continuously to the cellular network, but in a battery-powered application, the preferred connection type would be minimal, which connects to the cellular network only when data needs to be transferred.

The connection mode can be set up with the AT command AT+BMOD.

The syntax is AT+BMOD=<mode> <mode> == 0 to use the minimal connection mode <mode> == 1 to use the continuous connection mode

The default is to use minimal connection mode.

The current status can be queried with AT+BMOD=?.

Delete Blues Notecard settings

If required, all stored Blues Notecard settings can be deleted from the WisBlock Core module with the AT+BR command.

NOTE

Requires restart or power cycle of the device

The syntax is AT+BR

Reset Blues Notecard to Factory Settings

If required, the Blues Notecard can be reset to factory default.

warning

⚠️ THIS WILL ERASE ALL SETTINGS IN THE NOTECARD! ⚠️

All saved settings like Product UID, connection settings, and the APN in the Notecard WILL BE ERASED

Syntax: AT+BRES.

Get Blues Notecard Status

Show Notecard connection status with req:hub.status.

Syntax: AT+BLUES

Send Request to the Notecard

warning

⚠️ This works only for simple requests without parameters, like hub.status or hub.sync ⚠️

Sends a simple request to the Notecard and returns the response from the Notecard

Syntax: AT+BREQ=<request> <request> is the Notecard request, e.g. card.version or card.location

⚠️ LoRaWAN Setup ⚠️

Besides the cellular connection, you also need to set the LoRaWAN connection. The WisBlock solutions can be connected to any LoRaWAN server like Helium, Chirpstack, TheThingsNetwork, or others. Details on how to set up the device on a LNS are available in the RAK Documentation Center.

On the device itself, the required setup with AT commands is:

        // Setup AppEUI
AT+APPEUI=70b3d57ed0abcdef
        // Setup DevEUI
AT+DEVEUI=ac1f09fffabcdef
        // Setup AppKey
AT+APPKEY=2b84e0b09b68e5cb42176fe753abcdef
        // Set automatic send interval in seconds
AT+SENDINT=60
        // Set data rate
AT+DR=3
        // Set LoRaWAN region (here US915)
AT+BAND=5
        // Reset node to save the new parameters
ATZ
        // After reboot, start join request
AT+JOIN=1,0,8,10

A detailed manual for the AT commands is in the AT-Command-Manual.

Using the WisBlock Blues Tracker

Once the WisBlock Blues Tracker is set up for both cellular and LoRaWAN connections, it will connect to the cellular network and join the LoRaWAN server. Independent of a successful connection it will start acquiring the location with the GNSS engine that is built into the Notecards cellular modem.

The current application is not yet (work in progress) sending data based on movement, only in the specified time interval. The send interval can be set with an AT command as well:

ATC+SENDINT=300 will set the sendinterval to 300 seconds.

The current send interval can be queried with ATC+SENDINT=?

NOTE

Inaccurate location As with most location trackers, an accurate location requires that the GNSS antenna can receive signals from the satellites. This means that it is working badly or not at all inside buildings. If there is no GNSS location available, the device is using the tower location information from the Blues Notecard instead!

WisBlock Blues Tracker in Action

LoRaWAN server

For testing, I used Chirpstack V4 as a LoRaWAN server. The tracker has to be set up with its DevEUI and AppEUI in an application on the Chirpstack LNS. Optional you can add a payload decoder in the Device Profile. Then you can see the decoded payload in the events list of the device. Here is an example log output with the result of the CayenneLPP data parson the LNS before it is sent to the Blues NoteHub:

Figure 1: LoRaWAN Gateway

Within the Chirpstack LNS application, integration is needed to forward the data to Datacake, for the visualization. The integration is a simple webhook to Datacake:

Figure 1: Chirpstack

You can of course use other LoRaWAN servers like TTN or Helium for the LoRaWAN devices connection. For the location visualization, only the Datacake solution is explained here. If you want to use another location visualization, you need to figure out how to connect one device through both LoRaWAN and cellular connections.

Blues Notehub

The notes sent to the Blues Notehub can be seen in the Events listing of the Nothub

Figure 1: Notehub Event Log

The location and sensor data are sent as binary payloads, so there is nothing to see here in the body field.

The next step is to create the Route in NoteHub that forwards the data to Datacake. Instead of the default URL for the Datacake route, use the URL for LoRaWAN devices. Also, the note you want to forward is the data.qo note.

Figure 1: Notehub Route Setup

NOTE

At this point, it is getting a little bit complicated because the location data sent to Datacake can come EITHER from the LoRaWAN server OR from NoteHub.IO. The JSON object sent by the two looks of course very different.

Because of the different formats, you can use a very appreciated feature available in the NoteHub Routes, the JSONata Expression. With this data transformation option, make the JSON packet coming from the NoteHub look like a packet coming from a LoRaWAN server. I suggest reading the Blues documentation about JSONata to understand how it works.

The JSONata expression needed is very simple. You can simulate a LoRaWAN packet format with just a few JSON fields:

{
    "deviceInfo": {
       "tenantName":"ChirpStack",
       "devEui": body.dev_eui
    },
    "fPort": 6,
    "data": payload
}

In the Route setup, scroll down to the Data section. Select JSONata Expression to transform the data, then copy the JSONata expression into the entry field.

Figure 1: Notehub Routes Transform

The JSONata is pulling the required info from the Blues JSON data packet to build the "fake" LoRaWAN packet. You can check the functionality with the JSONata Exerciser:

Figure 1: JSONata Exerciser

The resulting JSON object is then sent to Datacake, which handles it as if it comes from a LoRaWAN server.

The routing events are shown in the Routes log view:

Figure 1: Notehub Routed Log

Datacake

To visualize the data in Datacake, a matching device has to be defined. As the data can come from two different paths, you should transform the packet forward in NoteHub to look like a LoRaWAN packet. The device must be a LoRaWAN device.

NOTE

On the device, the payload is formatted in Cayenne LPP format. Both the LoRaWAN server and NoteHub are forwarding the data in this format, so a single payload decoder can be used.

To distinguish whether the data is coming from the LNS or NoteHub, a different fPort is used in the packets.

fPort 5 ==> data coming from the LNS.
fPort 6 ==> data coming from NoteHub (see above in the JSONata expression that it sets the fPort to 6).

The payload decoder I used can be found in the file Decoder.js in the Github repository. The content of this file has to be copied into the Payload Decoder of the device configuration in Datacake:

Figure 1: Payload Decoder

Then the matching fields for the sensor data have to be created. The easiest way to do this is to wait for incoming data from the sensors. If no matching field is existing, the data will be shown in the Suggested Fields list in the configuration.

Figure 1: Suggested Fields

The sensor data can be easily assigned to fields using the Create Field button.

It will take some time before the suggested fields are listed as complete. Instead of using the suggested fields, you can just create the following fields manually:

Name	Identifier	Type	Role
Voltage	VOLTAGE_1	Float	Device Battery
Source	SOURCE	String	Primary
Islorawan	ISLORAWAN	Boolean	N/A
Location	LOCATION_10	Location	Device Location
Temperature (only if RAK1906 is present)	TEMPERATURE	Float	Secondary
Humidity (only if RAK1906 is present)	HUMIDITY	Float	N/A
Barometer (only if RAK1906 is present)	BAROMETER	Float	N/A

Figure 1: Create Fields

Once all the sensor data is assigned to fields, you can start with the visualization of the data.

Figure 1: Created Fields

In Datacake, each device has its own Device Dashboard which is used to display the location data. Details on how to create visualization widgets in Datacake is in the other tutorials already.

The final result for the WisBlock Blues Tracker:

You can see life data on the public dashboard.

In the top part of the dashboard are the locations of the device (history enabled) on the map and device sensor values on the side (temperature and humidity are only available if a RAK1906 is present).

Figure 1: Locations

In the lower part, a chart shows at what times the sensor used LoRaWAN to transmit data and when it used the cellular connection.

Figure 1: Data transmission mode

Using Custom Firmware From Other Rakwireless Examples

Install the RAKwireless Arduino BSP for WisBlock by using the https://raw.githubusercontent.com/RAKwireless/RAKwireless-Arduino-BSP-Index/main/package_rakwireless_index.json board installation package, the WisBlock Core RAK4631 should now be available on the Arduino IDE.
Blues.ONE uses RAK4631 WisBlock Core as the main processor.

Figure 1: Selecting RAK4631 WisBlock Core of Blues.ONE

Once you are ready with the Arduino IDE software and the RAK4631 board has already been added, you can now check the Cellular examples available for the Blues.IO Notecard.

Blues Note

NOTE

Blues.ONE software guide is focused on Cellular applications. If you are looking for its LoRa and LoRaWAN functionality, you can check the the RAK4631 LoRa/LoRaWAN examples repository.

For low-power examples, you can check:

The basic software example you can run is the WisBlock-Blues-Sensor. This is a simple example that sends sensor data through the Blues.IO Notecard from RAK4631. This code will power up the module correctly and after initialization, start sending sensor data to the Blues.IO Notehub.

warning

This example requires to have the Blues.IO Notecard setup correctly using the Blues Quickstart.
Without the setup, the Blues.IO Notecard is not able to connect to the Blues.IO Notehub.

NOTE

This example works without any other WisBlock modules added. But it also supports as well the RAK1906 environment sensor to acquire real sensor data. Without the RAK1906, the example will send fixed virtual sensor data only.

Figure 1: UART output of Blues Sensor example

Other Software Examples

There are several examples, utilizing the WisBlock Blues.ONE you can find them in our GitHub repositories together with guides and tutorials:

Blues WisBlock Tracker - The default firmware that is pre-flashed on the Blues.ONE Solution.
Blues Sensor Network - Multiple sensors deployed in a building that is communicating over LoRa P2P to an endpoint that has connectivity to the cloud. This endpoint can be a sensor by itself as well.
Cellular LoRaWAN Modbus
Indoor Floor Level Tracker
CAN bus vehicle monitor
Greenhouse Monitor

Check out some Tutorials and Guides repos on Github for more examples.