1. Building the module

Identifying the components

Our bill of materials (Complete Workshop set available at TinyTronics)

• RFM Module RFM95W (868 Mhz)
• Wemos Lora PCB (https://github.com/hallard/WeMos-Lora ) with components 3x 1n4148, R1, R2 (4k7), C1 (1uF) and C2 (10uF)
• Wemos D1 mini v3 – ESP8266
• Micro USB cable

The Wemos Stack

Wemos (http://www.wemos.cc ) offers a broad range of ‘stackable’ modules (displays, LEDs, buttons, power and processor boards) to be ‘stacked’ to your favourite application. We will use the Wemos D1 ESP8266 module and the ‘WeMos-Lora’ board. This offers a module which can connect to both WiFi networks as to LoRaWAN. As long as the right pins are connected, you can ‘stack’ it in different ways. We will use the experimental setup with the ‘through-the-hole’ pins.

2. Starting up the Arduino Environment

You may skip this step if you have:

• Arduino installed with ESP8266 support

• LMIC ‘Charles’ version installed

Setup the Arduino Environment. To use the ESP8266 we need the ESP toolchain. Installation instructions can be found here: https://github.com/esp8266/Arduino/

Installing with Boards Manager

Starting with 1.6.4, Arduino allows installation of third-party platform packages using Boards Manager. We have packages available for Windows, Mac OS, and Linux (32 and 64 bit).

• Install the current upstream Arduino IDE at the 1.8 level or later. The current version is at the Arduino website.

• Start Arduino and open Preferences window.

• Enter http://arduino.esp8266.com/stable/package_esp8266com_index.json into Additional Board Manager URLs field. You can add multiple URLs, separating them with commas.

• Open Boards Manager from Tools > Board menu and install esp8266 platform (and don't forget to select your ESP8266 board from Tools > Board menu after installation).

Close your Arduino IDE software. Remove (if already installed) the current LMIC library. We will use the ‘Charles’ version of the library. This one is compatible with your other projects, but has some special functionality needed for the WeMos LoRa board (supporting one input pin for the three DIO pins).

Download the new library and install the .zip file with library manager:

1. Goto https://github.com/ch2i/arduino-lmic

2. Choose ‘Clone or download’

3. Download ZIP

4. Mark the location

5. Go to Arduino IDE

6. Select ‘Sketch->Include Library->Add .ZIP Library’

7. Select the downloaded Arduino-lmic-master.zip file from your download location

Change the ‘lmic_project_config.h’ file in the project_config folder (remove the remark from CFG_eu868 and add them to CFG_us915):

//#define CFG_us915 1

#define CFG_eu868 1

#define CFG_sx1276_radio 1

Create a new sketch in Arduino IDE (File -> New), remove the content and paste the sketch code from https://raw.githubusercontent.com/galagaking/Wemos_Node/master/Wemos_Node.ino. You can save the sketch under a new choosen name ('Wemos_Node" for example).

3. The Things Network Dashboard

Your applications and devices can be managed by The Things Network Dashboard.

Create an Account

To use the dashboard, you need a The Things Network account. You can create an account here:

https://account.thethingsnetwork.org/users/login .

After registering and validating your email address, you will be able to log in to The Things Network Dashboard.

Create an Application

https://console.thethingsnetwork.org/applications

Choose ‘add application’

Give your Application a unique ID. You can use ONLY lowercase! You can add an unique number to get uniqueness over the ttn network (this is a global ID). If you already use an application you better add another one, because of the specific Payload Function needed here.

Your description can be any description you like.

ABP

Activation by Personalization (ABP) is a method where the security keys are stored in the device. Not as safe as the OTAA method, but for experiments it works OK. There is no join procedure, nodes will work right away.

Choose Register device, give the device a name and select the pencil to generate a Device EUI:

Choose Register

Now edit the settings of the device and choose ABP (OTAA will be selected by default), and uncheck the 'Frame Counter' Check box

Select ‘save’. Now some values are system generated and we have to copy them to our code. Get the code from https://github.com/galagaking/Wemos_Node We use the Wemos_Node.ino example here.

4. Copy Credentials and compile

Copy the following credentials from the dashboard to your Arduino code

• Copy the Device Address as a HEX value to DEVADDR in the example, so 26 01 1A 32 will be 0x26011A32.

• Copy the Network Session Key as MSB to NWSKEY.

• Copy the App Session Key as MSB to APPSKEY.

Select the Wemos board in the Arduino IDE (no debug port, lwIP v2 Prebuilt, CPU 80 Mhz, Upload speed 921200)

Compile and upload the code. Check in the dashboard the working.

You might want to uncheck the frame counter check

If the frame counter is checked, you must respect the sequence number, and probably copied packages are refused on the network. Though restarting you node, and thereby resetting the frame counter, will disable your node. So to get this working, you have to disable this check by unchecking this box.

5. Payload function

To get the right display format, we can create a decoder in our application. Select your application and open the ‘Payload Functions’:

Enter the function below, overwriting the standard function

var hexChar = ["0", "1", "2", "3", "4", "5", "6", "7","8", "9", "A", "B", "C", "D", "E", "F"];

function byteToHex(b) {

 return hexChar[(b >> 4) & 0x0f] + hexChar[b & 0x0f];

}

function hexToInt(hex) {

 var num=hex;

 if (num>0x7F) {

   num=num-0x100;

 }

 return num;

}

function Decoder(bytes) {

 var mac1="";

 for (i = 0; i < 6; i++) {

   mac1 += byteToHex(bytes[i]);

   if (i<5) { mac1+=':';}

}

var rssi1=hexToInt(bytes[6]);

 var mac2="";

 for (i = 0; i < 6; i++) {

   mac2 += byteToHex(bytes[i+7]);

   if (i<5) { mac2+=':';}

}

var rssi2=hexToInt(bytes[13]);

return {

   macaddress: {

     mac_1: mac1,

     rssi_1:rssi1,

     mac_2: mac2,

     rssi_2:rssi2,

   },

  };

}

First test the function with two dummy bytes CE D0, And then Save the function.

Return to your data and look what happens:

The payload contains two BSSIDs and two RSSI values.

6a. Get a Google API Key

Google offers a geolocation API service with good coverage to get the position of your node by sending WLAN info. Unfortunately using their services requires a billing account (ie credit card information). You get free credits, and for experimental usage this will be enough, but you have to be carefull with this. 40.000 requests per month will be free (if you do not use any other paid Google (map) services).

To use Google Maps Platform, you must have a Google account with billing enabled! The billing account is used to track costs associated with your projects. Make sure you understand how the billing account credits work.

Follow the instructions in the Quickstart https://developers.google.com/maps/gmp-get-started

The four steps you have to follow:

1. Create a billing account
2. Create a project
3. Enable one or more APIs or SDKs
4. Get, add, and restrict an API key

You can access your Keys in the cloud.google.com main menu, APIs & Services, Credentials ('inloggegevens'):

Your API key will be listed here. Be aware that the marker should be green, if it is not, you have to restrict your key (step 4 in the get started manual).

Use the Copy symbol to copy the key. If the marker shows yellow, you can restrict the key by clicking on the key name:

Restrict key, and select the Geolocation API in the drop down menu:

6b. Get a HERE API Key

HERE is another geolocation API provider. It will offer you 250K transactions per month in a freemium Plan. Their coverage is not as good as Google, but you do not have to give any payment details in advance. Your service will be blocked after reaching 250K transactions in a month.

Service is described here: https://developer.here.com/documentation/positioning/topics/what-is.html

Data we are going to feed, is the WiFi (WLAN) MAC address of nearby gateways. What you will get back is a GPS coordinate with an accuracy value.

Create a free account at this page: https://developer.here.com/?create=FreemiumBasic&keepState=true&step=account

You will need a name, email address and password, plus type over the shown phrase/code. Also your country/region is asked. Optional you may give your company name or telephone number.

In the next screen you can get your API key:

Choose Generate App in the REST API screen:

Choose Create API Key, and copy your key to the Node RED code, or save it for later use.               <o:p></o:p>

6c. Get a LoRaCloud key

Go to https://www.loracloud.com/ and create a Semtech account.

After e-mail confirmation you can go to the portal, confirm the EULA:

Now you can select the Geolocation services:

Now you can manage tokens, and copy your primary token for later usage in your Node-RED code:

7. Decide for Local or 'Cloud' Node-RED

There are several options: use a local Node-RED installation (step 7a, 7d, 7e), use FRED (step 7b) or use IBM Cloud (step 7c):

A local installation on PC or Raspberry Pi:

Advantages:

• You are the boss of your data and hardware
• Easy, more often used and documented installation
• No Credit Card needed, so no financial risk

Disadvantages

• NodeRed is only running when your system is turned on
• Remote Access has to be configured seperatly
• Extra hardware needed

FRED:

Advantages:

• Always on (no need to run your own server) *Limited to 24 hours
  
• Easy to install
• Free for small usage, no Credit card needed in the free version
• Remote Access by design (no firewall rules, router configuration needed)

Disadvantages:

• Will run only for 24 hours after last login. Will restart after a new login (maintaining your settings)
• Limited number of nodes (50), memory and options (like databases)
  

IBM Cloud

Advantages:

• Always on (no need to run your own server)
• Remote Access by design (no firewall rules, router configuration needed)
• Free for small usage, no Credit card needed in the free version
  
• no extra hardware needed

Disadvantages:

• Big (Blue) Brother watching you?
• More difficult to configure

7a. Install Node-RED [Local Node-RED Setup]

Installation instructions for the Windows Platform can be found at https://nodered.org/docs/getting-started/windows

First you have to install node.js: https://nodejs.org/en/

After installation of node.js, enter the following command to start installation:

<code>npm install -g --unsafe-perm node-red</code>

On other platforms follow the instructions on https://nodered.org/docs/getting-started/local

Node-RED will be available at localhost:1880

7b. Install Node-RED [FRED Setup]

The free version of FRED has some limitations. The maximum number of nodes is 50, and your flow will run only 24 hours after your last login. So if you want to have a permanent flow running, log in every 24 hour, or decide for another Node-RED option.

Go to https://users.sensetecnic.com/register Fill in the form and choose the ‘Short’ plan:

Your environment will be set up, and the main screen will be shown:

To add extra nodes FRED has a function ‘add or remove nodes’ on the left pane:

Search for ‘World’and mark the WorldMap node:

Remove demo sheet 1, use the menu on the right upper corner, select ‘Flows’, ‘Delete’ in the Sheet 1 Flow.

7c. Install Node-RED [IBM Cloud setup]

IBM offers a 'lite' version of their IBM Cloud offering. This will give you one limited instance on a Cloud Server for free. No Credit Card needed!

Go to https://cloud.ibm.com/login

Choose 'create an account' and follow the steps to create a 'lite' account'.

After your account has been created, you have to install IBM Cloud Node Red. We will use a 'Starter Kit' shown in the dashboard:

Select the Node-RED App:

Select 'Get Started' or 'Create':

You may give your instance a name, this name will be used in the URL later on as well. Choose Price plan 'Lite':

The code for your App will be generated, this will last a few minutes. Now you can start your App by deploying it:

The deployment target is 'Cloud Foundry', and you have to generate a API key to connect:

Create a Cloud API key by selecting 'New'

Create a new API key, do not store it (this is not possible in the 'lite' plan) and select 'OK'

Select your nearby region (Londen), organization and space are than filled in for you. You may choose any host name (if it is available), eu-gb.mybleumix.net will be standard. The DevOps toolchain will be created.

Select 'London' als your region and 'Create' to create the toolchain. This brings you back to the 'App detail' screen, progress will be shown in the 'Deployment Automation' tab. After several minutes the status will be 'Success'. Go to the 'resources' list (left top menu'):

Open the 'Cloud Foundry Apps', your App will be shown, open it by clicking on it:

This screen shows all information about your app. By clicking on 'Visit App URL' we will be taken to the previous given URL of your app. You may use this URL anywhere to access your App, so you do not have to enter IBM Cloud first to access your app. That is why we have to protect our Node-RED instance with a username / password. This will be asked in a short wizard:

After this step, you can enter your Node-RED flow editor:

You can login by using your previously given password.

7d. Install Node-RED on HASSIO (Home Assistant)

Home Assistant is a populair Home Automation Platform, which will run on a Raspberry PI. It comes with a virtualization OS (HASSIO), which is usefull for adding additional services like Node-RED.

Choose the 'Supervisor' menu on the left bar and select the 'Add-on store':

Search for 'Node':

And select 'Node-RED'. After downloading you can install:

After installation change the config file. Add some password in the first line ('credential secret'). You might want to use SSL (you need a certificate), if you do not have one: disable SSL by changing true to false:

Save your settings and start Node-RED:

Now you can open the web interface of Node-RED:

The webinterface is also accessible via <hassio-ip>:1880.</hassio-ip>

7e. Install Node-RED on a Raspberry PI

Install and update your Raspberry PI with the latest Raspberry Pi OS (previously called Raspbian) from https://www.raspberrypi.org/downloads/.

Some images provide a Node-RED installation, but use the recommended installation from the Node-RED site: https://nodered.org/docs/getting-started/raspberrypi

Start the script:

<code>bash <(curl -sL https://raw.githubusercontent.com/node-red/linux-installers/master/deb/update-nodejs-and-nodered)</code>

Give 'Y' to Pi specific nodes, and the installation will start:

You can start node-RED with the command: node-red-start. The interface will be available at localhost:1880 or <your pi-ip-address=""><PI-IP-Address>:1880.</your>

<your pi-ip-address=""> You can use:</your>

<your pi-ip-address="">sudo systemctl enable nodered.service
</your>

to start Node-RED on every boot.

8. Node-RED flow

First check if 'Worldmap' is installed in your Node-RED instance. The FRED step already described this step. For other installations, go to the top right menu (three bars / hamburger menu) and choose 'Manage palette':

Choose install, search for 'worldmap' and install the worldmap node:

To import the flow, go to https://raw.githubusercontent.com/galagaking/Wemos_Node/master/NodeRED_Localization.json copy the content (CTRL-A, CTRL-C) and paste it in the import screen.

Top right menu-> Import:

The flow will look like this:

Before starting the flow, you have to configure it with your credentials in the next step.

9. Node-RED: The Things Network connection

We use MQTT to connect with your node on the things network. MQTT uses a username / password we have to fill in. First open the MQTT node ('wemos_localization') en click on the pen symbol:

Fill in the server (mqtt://eu.thethings.network) in the 'Connection tab:

Select the security tab and fill in the user (which equals your Things Network 'application ID') and the password (which equals yourThings Network  'access key'):

Update to save your parameters.

Now replace in the topic app-id with your own The Things Network application ID and device-id with your own The Things Network name of your device:

Done to save your settings. The node will now show 'connected':

If the node will not connect, check the previous steps!

10. Node-RED: Enter API Key(s)

Depending on your whishes you may enter your previous API codes into the selected nodes.

HERE

Open the 'Ask HERE Geolocation API' function node and copy-paste your API code, and save with 'Done':

Google

Open the 'Ask Google Geolocation API' function node and copy-paste your API code, and save with 'Done':

LoRa Cloud

Open the 'Ask LoRa Cloud Geolocation API' function node and copy-paste your API code, and save with 'Done':

Now remove the connections from the nodes you do not use, so if you only want to use 'Google', remove the two connections shown, by selecting them and pressing 'DELETE'. Any combination is possible, LoRa Cloud will work even if no WiFi network is found. In any case, The Things Network coverage is needed!

11. Node-RED: Deploy your flow

To start your flow, press the 'DEPLOY' button on the upper right corner. It will be RED, because you have made changes:

After the first message of your node (it will last max 1 minute), the nodes will blink and the result will be sent to the map. You can show your map with CTRL-SHIFT-M. If you are using HASSIO (Home Assistant) or another VM service, start your node-RED with <HASSIO-addres>:1880, and use CTRL-M, or use the URL http://<HASSIO-address>:1880/endpoint/worldmap/ . A marker will be plotted at your location.

You may want to configure the WorldMap node, the given Coordinates are the 'starting position' of your map, there are different map types, you can select with 'base map:

12. Node-RED: Debug and customization options

On several places in the flow you see green 'DEBUG' nodes. You can turn them on or off by clicking on the button:

You can show the debug messages by pressing CTRL-G D or by clicking the 'bug' icon on the upper right corner:

Now you can see how the information 'flows', and where there is something wrong.

The worldmap node has a lot options, to show single points, tracks, icons. Feel free to alter the 'Convert to GPS-JSON' node to change icons or colors. Be aware that if you use radius to draw a circle to show the estimated position, no icon will be drawn. This can be selected in the 'Convert to Worldmap' node, by comment out the delete msg1.payload.radius line:

You can also decide to add or remove tracks by connecting or disconnecting the nodes to the worldmap node: