This is the 6th generation of software implementing LoRa gateway function on a platform consisting of an ESP8266 mcu and a SX1276 radio. Unlike the previous versions of the gateway, this version will listen for all available Spreading Factors on a single frequency. Also for well know nodes it will show the name instead of its DevAddr and if configured it will also decode messages coming from these well-known sensor nodes.
This section describes the first important decisions you have to take with your Gateway and how to configure the gateway to get you going. By no means this chapter is meant to be exhaustive, detailed or complete, it merely gives a hint how to start and go from here. The reader is advised to read the rest of this chapter and finish the configuration after reading it.
So what do you need:
- ESP6288 including Comresult board or Halard board and a SX1276/RFP95 LoRa chip
- OR a Heltec board with ESP32 and LoRa schip loaded
- Computer with Arduino IDE Version 1.8.5 or later
- micro USB to USB cable for downloading the Gateway software to your node
And to easy compile:
All other parameters in the configGway.h file can be left to their default values initially. Please connect to the USB port and look at the console. It will show at what IP address the sensor node connects. You can then open that IP address in your browser and manage the gateway through the web browser.
In order to avoid having to use both options, we try to make most settings available on both interfaces. But in practice the .h file is used to make configuration changes that are more permanent and the user interface is used to set everyday parameters and things that change more often.
There are at least two major ways to set the configuration of the Gateway:
Most parameters that can be set are compile-time directives so that code is compiled or not based on the value of the directive in the configGway.h file. This way, the code base can be kept small when functions are not used. Example: Support for USB Debugger can be turned ON or OFF based on the setting of _DUSB in the configGway.h file. For example:
#define _DUSB 0
By changing the definition to "1" the complete functionality to use Wifi Manager is included in the code and compiled. By using "0" all functions relating to this functionality is excluded from the gateway code.
Several parameters or #define compiler directives can be set in the configGway.h file as follows:
#!defined _SPIFFS_FORMAT
# define _SPIFFS_FORMAT 0
#endif
This parameter defines whether the device node should start with a SPIFFS filesystem format be fore use. The parameter can be set in PlatformIO as well. If set to 0 (default) the filesystem will not be formatted and if set to 1 it will start with format. This way the user can force (!) the filesystem to be reset before operation and clean corrupt files of empty the memory (if it is full).
This parameter can be set to 0 (off) and 1 (on). It defines whether the WifiManager module is activated or not.
DUSB sets the debugging/Output for the Serial USB port. If _DUSB is set to 0, minimal (almost 0) output should be sent to the Serial Port. I like to switch off ANY communication to the USB port if _DUSB is set to 0 (and will probably).
If _DUSB is set to 1, it will allow any USB communciation which is permitted by the debug level set in the Webserver GUI.
This compile switch defines whather the print-outs need to be handled by the gateway and prints need to be made visible on the GUI (monitor). This setting when greater than 0 defines the number of lines in the monitor section of the GUI. In this monitor setting al the print-outs of the gatesway are collected and displayed.
The _DUSB define makes the _MONITOR function to print also output to the USB output. SO it is possible to switch on _MONITOR to enable output to the screen and at the same moment disable output to the serial line.
Specify whether you want the gateway to gather statics information. There are three values possible:
Set the region for the single channelgateway. The Europe region is the default one but can be changed by the user.
Define the class support for the gateway. Initially this is set to "A" and the other modes are not used in this version.
This parameter sets the initial value for the Spreading Factor (SF) which i used in STD mode of operation, If _CAD is enabled the value of _SPREADING is not of use anymore. Valid choiced are SF7 - SF12.
Set the paramet Channel Activity Detection and the corresponding mode of operation of the Single Channel Gateway. In CAD mode the gateway is set to one frequency (mostly 0) and listens to all Spreading Factor messages of coming in on that frequency.
The default value fr this parameter is 1 (ON) and you are advised to keep CAD on since it does ot seem to be missing messages.
Specify whether or not to use the Webserver for this Single Channel Gateway. Although it is possible to switch the Webserver off, for example for security reasons, I recommend to use it as it provides good information on the Gateway operation and the setting of all parameters.
This parameter determines whether the Webserver should refresh every XX seconds. At this moment the Webserver will refresh every 60 seconds by default (It is possible to set other values). It may be possibel that you miss some LoRa packages as the Webserver takes some time and compute power, but for debugging a Single Channel Gateway it is a nice feature to have.
Leave at 80 (The standard Webserver port).
This should be the maximum size of a message going up. Standard value is 192 and should not be changed.
Over the air download of new gateway code is enabled by default. The download itself is not protected by passwords or so, but the SSID of the WiFi server is of-course so we expect that people that have access to the WiFi environment will also be able to download new software versions to the gateway.
This defines the pin-out for the gateway device we use. At this moment there are a few standard gateway boards defined:
The STRICT 1-CHANNEL configuration parameter determines the behaviour of the gateway during downstream messaging. The downstream messaging protocol is descripbed in the docuentation, but where necessary important parts are discussed here as well.
For CLASS A devices the downstream messages are sent by the gateway upon receiving a message from a mote. For regular messages, two timeslots are available for sending downstream messages, and for JOIN messages another two are defined.
Note, that the timslots start after the last byte has been received from the mote, so the mote must determine and send its tmst values as late as possible.
This definition defines a standard 0.9 inch OLED display. If another size is connected to the gateway, then specify its size as defined by the include file. If no OLED display is connected then do not bother as this definition does no cost any performance
This parameter defines whether we do (extensive) logging to files. As this might cost a lot of performance for Downstream messages we do not enable this setting by default (but it could).
This parameter and the ones below define for the single channel gateway how the clock time (seconds since 1/1/1970) is retrieved. The user will have to set the timeserver to the one which is closest to his/her location. And after that, the clock may need some correctiojn for summer/winter time but hat is cosmetic. Please remember that the time is not used internally other than for GUI purposes.
As UTC or GMT is standard for Europe. we use a correction of +2 to make it summer time compliant.
Most values below need no changing
The default setting is 20 lines of statistics in the GUI. This setting can be changed in the GUI in expert mode.
The default setting is 20 for the number of lines in the GUI o show the lst seen statistics. This setting can be changed in the GUI in expert mode.
The default setting is 20 for the number of monitor lines.
The interval settings below define the behaviour of the user interface GUI and the intervals in which the gateway has to take action for File storage and LoRa communication (PULL, STAT). Best is to leave the settings as they are, but it is possible to tweak these.
The value of BAUDRATE 115200 // Do not touch
Do not touch this value, it seems to be a working value.
Normally do not change the _TTNPORT settings
Most parameters starting with a "_" are parameters only. Please only change these if you know what you are doing. If the parameter contains a "<xxx>" it means that you have to put your own values there. After all, it does not make sense to put my email address or GPS data in your configuration.
The remaning part of the #define settings should be to include or not include certain parts of the code based on your own preference.
The configNode.h file contains configuration parameters that are specific to the current single channel gateway. That means it contains passwords, and other paraneters that are specific to the current gateway operation.
The following parameters are set in the configNode.h file:
_GATEWAYNODE definitions when this is 1
#if _GATEWAYNODE==1
#define _DEVADDR { 0x26, 0x01, 0x15, 0x3D }
#define _APPSKEY { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }
#define _NWKSKEY { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }
#define _SENSOR_INTERVAL 300
#endif_TRUSTED_NODES definitions when this parameter is larger or equal to 1_LOCALSERVER Definition
// If you have a second back-end server defined such as Semtech or loriot.io
// your can define _THINGPORT and _THINGSERVER with your own value.
_THINGSERVER "<Your server>" // if(!) defined contains the secondary server name_THINGPORT 1700 // contains the secondary server port.// Define the name of the accesspoint if the gateway is in accesspoint mode (is
// getting WiFi SSID and password using WiFiManager).
// If you do not need them, comment out.
AP_NAME "<Name your gateway accesspoint>"AP_PASSWD "<Your AccessPoint password>"// Gateway Ident definitions. What is its name and where is the gateway located?
_DESCRIPTION "<Contains a description of this gateway>"_EMAIL "your.email@provider.com"_PLATFORM "ESP"_LAT 52.00 // Latitude_LON 6.00 // Longtitude_ALT 14 // Altitude
This part describes the GUI and how to set parameters. And of course my advise what parameters to set :-).
First of all: Determine the IP address of your single channel gateway. It can be that you set a fixed address in your router, but it could also be tat the router hands out addresses based on its own preference. Should you not know what addres is assigned by the router, remember that the single channel gateway will output the IP address and other important settings over USB during boot-up. So looking at the output on USB is a simple way to get the IP address (and it may be the only way for you).
The Basic mode is the default mode for the Single Channel Gateway to operate on the GUI. So when starting your GUI this is the first screen you will see is the following:
The GUI has the following sections:
The title part contains a little information about the Gateway such as the time it was activated and how long the gateway is active. It also contains the version of the software.
A few important buttons that activate pop-up screens showing other information that is not present on the main GUI screen. The LOG button for example opens a popup with a text editor containing all messages received by the gateway (.csv style). When a message isreceived the system will log its details in the SPIFFS filesystem. Because of the memory limitation of the ESP module, the last 100 files are saved on the chip and previous ones are deleted as soon as memory runs out. Still, it allows te used to anayse messages longs after these have been received by the gateway.
This section contains the statistical info of all the messages that have been received by the gateway. It displays per spreading factor and per channel how many messages were received and display the amount of messages processed per hour.
This section shows the last messages received by the gateway. Of every message we record the time that it was received, the sensor ID, the channel and the spreading factor used for sending the message etc. As of version 5.3.2 of the gateway another column can be added to this section: The data sent by sensors. When enabled in the configGway.h file with
#define _LOCALSERVER 1
It is possible to add NwkSKey and AppSKey in the configNode.h file and enable for some well known nodes the decoding of their data. With this, the sensors do the same thing as the TTN backend, but enable this ith the local GUI Webserver or through the local USB interface. Just enable GUI on the webserver to send output to the USB port.
| Parameter | Allowed Values | Default Value | Description |
| CAD | Yes or No | Yes | Set the Channel Activity Detection option. CAD allows the gateway to scan all Spreading factors in the frequency band |
| HOP | Yes or No | NO | Specify whether frequency hopping should be enabled. Frequency hopping will make the gateway work on more than one channel. This mode is highly experimental and does not work correctly. the user is strongly advised NOT to use HOP. |
| SF | 7 to 12 | 9 | Spreading Factor setting SF7 to SF12. If CAD is enabled (see above) the Spreading Factor is automatically set (AUTO) |
| Channel | 0 to 9 | 0 | The channel that the Gateway should work on. If HOP is set (see above) the frequency will shift between the first 3 well known frequencies |
| Debug Level | 0 to 3 | 1 | The debug level specifies what debugging info is output to the USB Console and what info not. With debug level 0, almost no messages are shon on the console. Debug level 1 displays a minimal (essential set) without influencing the performance of the gateway. Debug levels 2 and up should only be used for debugging |
| Debug Pattern | SCN, CAD, RX, TX, PRE,MAI, GUI, RDIO buttons | All Off | The buttons allow use to specify which section is activated for sending debugging info to the Console. |
| Usb Debug | 1 | This is the value of DUSB (see configGway.h file) | |
| WWW Refresh | ON or OFF | OFF | By setting this parameter to ON, the Webserver will every 60 seconds renew the page. |
| Update Firmware | -- | -- Not used at the moment -- | |
| Format SPIFFS | -- | By pressing the button the user can format the filesystem at any time. | |
| Statistics | This parameter defines what kind of statistcis info is gathered and computed by the gateway system. | ||
| Boots and Resets | The number of times the system was rebooted. This can be a "on purpose" boot or can be due to an error for example. The number of boots is shown, by pressing RESET the user can reset the counter. | ||
With the command buttons on top of the screen it is always possible to return to the basic screen.
The buttons on the top section give more and special capabilities:
The using this button, the user is referred to the User Guid documentation (this document).
When the Login Files option is selected, the log files are output by the browser.
When this button is selected for the expert mode of operations, three extra sectors are added to the bottom of the GUI User Interface,
This section shows several WiFi parameters that are set by the gateway.
This section shows some system parameters. There is nothing to set here except when using an ESP8266 module, in this case the yser can set the system clock either to 80MHz or 160MHz.
Also, this section contains a few parameters rthat can be set by the user such as trhe exact number of on-screen message history and the number of last-seen records shown. The user is advised to keep the number of lastSeen messages between 15 and 20 and only increase if the number of nodes matched by the gateway exceeds this number.
The number of gateway history messages is initially put at 20 by the compiler nut the user is advised to change this to a larger number if he/she wants to see more message history.
This section contains the state in which the system is in. So stateMachine, Interrupts and number of errors are displayed. This section does not contain parameters that can be directly changed by the user.
This button toggles the section of the monitor in the GUI screen.
This button toggles the selection of the LastSeen information displayed in the GUI.
For those that use the PlatformIO compiler and configuration instead of the original Arduino IDE, it is possible to set a few parameters of the Singkle Channel Gateway using the pre-Compiler interface.
For this, use the platform.ini file of the PlatformIO interface and list the parametyers you want to change in this file together with the normal compile options you need to compile the source code.
This is feature not normally found on LoRa Gateways, but implemented for the Single Channel Gateway as a means to help with debugging LoRa sensors.
The Gateway program enables use of sensors that are connected to the gateway, but reported as if they are orininatin from an ordinary LoRa sensor. The gateway will fake in this case that the message is coming from a real sensor but measure the sensor vaues, encode them as a sensor node would do and sends them to the server backend (of TTN or example).
Especially for Gateways based on the TTGOT-Beam board and others there are several on-board sensors such as GPS and local battery voltage that are very useful to report to the server. And also when debugging a LoRa environment it is good if there are sensors that canbe reported to the server without having the actual LoRa component and a sensor node involved: It enables you to check the gateway-server connection.
The TTGO T-Bone board has both the possibility to use the local GPS as a sensor and send the voltage of the local battery to the server. The first is well documenten in the code.
For the battery voltage reporting the GPIO35 pin should be measured by the A0 analog pin and its value should be multiplied by 2 to get the accurate voltage of the battery. The sensor works between 3.5 and 4.2V battery power so reading the value of GPIO35 pin enables the user to receive information about the battery, indicating the USB power is lost, and repair power before it is too late.
There are (at least) two y seperate documents that apply to this gateway:
Datasheets for RFM95 and SX1276 should be the same. However, the HopeRF document dontains confusing information especially in the registers description are where RSSI for example (regaister 0x1B ?) is concerned.
RSSI stands for Received Signal Strength Indicator is is measured on the receiver to determine the signal quality of the sender. Normal RSSI can be measured any time at the receiver side by reading regaister 0x1B. The SX1276/RFM95 transceiver contains a special register 0x1A that contains theaverage packet RSSI information.
The RSSI function is used by CAD to determine if we have received a message. This is not as the RFM95 is designed, after all new messages might be received that are below the noise floor and this using RSSI is not the most reliable process.
The correct RSSI sample can be computed (according to the RFM95 manual para 4.2.5.3) by adding TS_RE + TS_RSSI
In the sx1276 datasheet we find that DIO 0 and DIO 1 are used to handle CAD interrupts and for message reception. So where we would only use dio0 in the version 3.x of the gateway, we now use dio0 AND dio1 in order to detect CAD and RX Timeout events. This also means for users that the have to modify their gateway and set the pins correctly in the loraModem.h file.
The are several ways you can use the single channel gateway:
If teh conly thing you want is running it as just a (standalone) gateway, please keep the following things in mind:
If you want to use the device for debugging of the gateway and sensor functiojn, please do teh following: