Advanced Configuration of the Treon Gateway

Sep 6, 2023 · 12 minutes to read

Introduction

After you have successfully connected to the Treon Gateway, Treon Gateway 2 or Treon Gateway in Protective Enclosure using an SSH connection, you can configure the available advanced parameters and settings.

 ,

Differences Between Gwadmin and Gwuser

The access rights of gwadmin and gwuser user accounts differ:

gwadmin

• Has root privileges and use system commands that gwuser cannot.
• Can edit all available settings.
• Has access to all folders and files.

gwuser

• Has no root privileges.
• Cannot edit all system commands that gwadmin has access to.
• Has access to fewer folders and files.

For example:
In a corporate environment, the company’s IT admin will use the gwadmin username. All regular users can use the gwuser username. For example, regular users may need to view logs or files, but are not supposed to edit any settings.

Give Gwadmin Root Privileges

If you are logged in as gwadmin and want to carry out actions that require root access, you must first give yourself root privileges:

sudo -i

This is required e.g. in cases where you need to edit configuration files that are not owned by gwadmin user.

When you no longer need root privileges, remember to exit.

exit

Alternatively, you can use sudo in front of all commands to run them as root.

It’s a good practice to use root privileges or run commands as root only when it is necessary.

Please note: Some commands are only possible with root access. If you do not have root access, the gateway may return that the command does not exist.

Configure the Treon IoT Gateway Application

The Treon IoT Gateway application collects and transmits the node sensor data to the cloud and back. It is configured to start when the gateway boots up.

The Treon IoT gateway application reads configuration from auto-generated file /opt/iotgw/gw.conf. This configuration file is generated by the application on boot by combining /opt/iotgw/base.conf and config files located under /opt/iotgw/conf.d/.

Customer-specific changes should always be applied by creating configuration files with .conf-postfix under /opt/iotgw/conf.d/. The files override options located in /opt/iotgw/base.conf are applied in alphabetical order so that the latest option is chosen.

Vi and nano are supported editors, but vi is the preferred editor.Configuration file contains Wirepas and cloud connection parameters as well as parser configuration. Each of the layers in the gateway (local connectivity adapter, data processor, and cloud adapter) includes topics for that section. For example, when the IoT gateway application boots, it sends the data processor a message that the data processor should read its settings from the section [WpLogic].

By default, the following sections are used:

[General] DebugLevel: Defines the detail of debug data printed out from the processes. The possible values are: CRITICAL, ERROR, WARNING, INFO, DEBUG, ALL. By default, the debug messages are stored in /opt/iotgw/logs.

[WpAdapter] defines the Wirepas parameters.
Note: Before gw image version 5.2.2 this parameter is named [WpMeshData].
NetworkId: Defines the used Wirepas network ID.
NetworkCh: Defines the used Wirepas network channel.
NodeAddress: Defines the Wirepas address on the gateway’s sink. This MUST be unique for each gateway.
LowLatency: Defines if sink is configured to the low latency mode: true/false.

[WpLogic] defines the parser parameters. Don’t modify these unless you are developing your own parser.
DataParser: Defines the plugin that handles Wirepas TLV messages. Plugin is a module within the handlers/ folder.
MeshTopicFilter: Defines the topics that are handled by the parser. Wirepas endpoint numbers are used as topics.
CloudTopic: Defines the topic name that is used in messages sent to the cloud adapter.
CloudTopicFilter: Defines the topics which the parser listens to from the cloud adapter.

[CloudAdapter] CloudType: Name of the plugin module that handles the cloud messages.
CloudTopicFilter: Data types that are handled by the cloud plugin.
CloudTopic: Topic name which is added to messages from cloud and sent to data parser.

Some parameters in this section depend on CloudType:

azure_paho: 
    ConnectionString: Connection string created by Azure IoT Hub.

http-rest:
    BaseUrl: Base URL used to POST data.

wapice:
    DeviceId: Allocated by iot-ticket.  
    AuthString: Basic HTTP authentication string used to access iot-ticket.  
    BaseUrl: Base URL defined by iot-ticket documentation.

The configuration file section names are defined as processes are started. For example

python data_processor.py -n WpLogic

If you develop your own plugin, you can either define the new values in an existing section, or create a new section in the configuration file, and give its name in the startup script.

Startup configuration

The Treon IoT gateway application startup is defined in configuration Startup-section.

[Startup]
DataProcessors: Comma-separated list of dataprocessors to start, default: WpLogic
CloudAdapters: Comma-separated list of cloud adapters to start, default: CloudAdapter.
CDataProcessors: Comma-separated list of C dataprocessors to start, default is empty
EnableGwSensors: Set this to True if gateway sensors should be used, default: False

The startup section is used by /opt/iotgw/iotgw_manager.py to launch and monitor each component of the application. Modifications should be done the same way as described in section ‘Configure the Treon IoT gateway application’.

Template and more details in /opt/iotgw/base.conf. Default configuration

[Startup]
DataProcessors: WpLogic
CloudAdapters: CloudAdapter
CDataProcessors:
EnableGwSensors: False

How to define cloud connection?

To define cloud connection, edit add your configuration file under /opt/iotgw/conf.d/:

nano /opt/iotgw/conf.d/cloud.conf

or

vi /opt/iotgw/conf.d/cloud.conf

Templates and more details about each config option can be found in /opt/iotgw/base.conf, but you should never modify this file.

Wapice cloud

For reference, find [CloudAdapter] section in /opt/iotgw/base.conf. Add this section to your config file and edit at least DeviceId and AuthString parts and in some cases BaseUrl is needed to change. The configuration file should look like this:

[CloudAdapter]
CloudType: wapice
#Backend specific configuration
DeviceId: IOT-TICKET_DEVICE_ID_HERE
AuthString: AUHENTICATION_HERE
BaseUrl:https://my.iot-ticket.com/api/v1
#Log only, do not really send data to backend: yes/no
TestOnly:no

Save changes and then check that CloudAdapter is used as wanted connection type. By default, a cloud adapter named CloudAdapter is configured to start under Startup-section so modifications shouldn’t be needed, see section ‘Configure the Treon IoT gateway application’.

Finally reboot the gateway to make sure that correct cloud connection is started.

MQTT

This applies to plain MQTT and Azure IoT (connection string, username/pass or x509 authentication). For reference, find [CloudAdapter] section in /opt/iotgw/base.conf. Add this section to your config file and set following parameters depending on which connection type is used:

[CloudAdapter]  
**CloudType: azure_paho**  
#Cloud Backend type: "azure" or "azure_x509" or "mqtt"  
**CloudBackEnd: azure **  

#MQTT AUTHENTICATION  
#  
MqttBaseUrl: MQTT_URL_HERE  
MqttPort: MQTT_PORT_HERE  
MqttUserName: MQTT_USERNNAME_HERE  
MqttPassWord: MQTT_PASSWORD_HERE  
MqttAllowInsecure: Set this to True if mqtt without TLS is allowed (TLS connection is always first tried)  
ServerCaChain: Set path to server ca certificate chain if required  

#CONNECTION STRING AUTHENTIATION  
#  
ConnectionString: CONNECTION_STRING_HERE  

#X509 Authentication  
## Certificates are searched by default in certs-folder at iotgw root  
X509_CertFile: cert.pem  
X509_KeyFile: cert_key.key  
X509_Hostname: HOST_ADDRESS  
X509_DeviceId: TREONTEST  

Save the changes and then check that CloudAdapter is used as wanted connection type. By default, a cloud adapter named CloudAdapter is configured to start under Startup-section so modifications shouldn’t be needed, see section ‘Differences between gwadmin and gwuser’.

Finally reboot the gateway to make sure that correct cloud connection is started.

HTTP Rest

For reference, find [CloudAdapter] section in /opt/iotgw/base.conf. Add this section to your config file and edit following parameters:

[CloudAdapter]  
CloudType:http_rest  
#Backend specific configuration  
DeviceId:  
#AuthString containg http header basic authentication string  
AuthString:  
# Username and password override AuthString if set  
UserName:   
PassWord:   
BaseUrl: Example http://192.168.96.15:3000/insert  
#Log only, do not really send data to backend: yes/no  
TestOnly:No  

Save changes and then check that CloudAdapter is used as wanted connection type. By default, a cloud adapter named CloudAdapter is configured to start under Startup-section so modifications shouldn’t be needed, see section ‘How to define cloud connection?'.

Finally reboot the gateway to make sure that correct cloud connection is started.

Wirepas Network Tool

The Treon IoT gateway application supports wirepas network tool (WNT) starting from release version 5.1.1. It is configured by adding a configuration file to /opt/iotgw/conf.d/ with contents:

[WNTCloudAdapter]
CloudInbox = tcp://127.0.0.1:5500
CloudOutbox = tcp://127.0.0.1:5501
CloudTopic = wnt
CloudTopicFilter = wnt
CloudType = azure_paho
CloudBackend = mqtt
#MqttBaseUrl = MQTT_BASE_URL
#MqttPort = MQTT_PORT
#MqttUserName = MQTT_USERNAME
#MqttPassWord = MQTT_PASSWORD
#MqttAllowInsecure = True
#ServerCaChain = /home/gwadmin/certificate.pem
DataProcessors = WNT
DataFormatter = None
ControlFormatter = None

[WNT] CloudInbox = tcp://127.0.0.1:5510
CloudOutbox = tcp://127.0.0.1:5511
MeshInbox = tcp://127.0.0.1:6010
MeshOutbox = tcp://127.0.0.1:6011
DataParser = wnt
MeshTopic =
MeshTopicFilter = 254,253,252,251,240
CloudTopic = wnt
CloudTopicFilter = wnt

[WpAdapter]
OutMessageExtended = true

# This is optional and can be set remotely using WNT and this will most likely be overridden by WNT when cloud connection is made

DiagnosticInterval: 30

[Startup] # Startup section to enable WNT adapters, see section 3.3.1 for more details
CloudAdapters = WNTCloudAdapter
CDataProcessors = WNT

Parameters are specific to your instance for WNT. Diagnostic interval can be specified also via WNT application. Valid values for diagnostic interval are: 0,30,60,120,300,600,1800. Values are seconds. 0 disables sending of diagnostic messages. Keep in mind that smaller values increase network load and sensor node power consumption.

By default, WNT adapter listens for diagnostics endpoints, you can modify this behaviour by adding following section to your config file

[WNT]
MeshTopicFilter = 254,253,252,251,240

Note that when using WNT, the configuration changes made to NodeAddress, DiagnosticInterval, NetworkId and NetworkCh of the sink will generate a config file conf.d/wirepas_override.conf. This file will always override any settings found in other configuration files so that changes done over WNT will take precedence.

Enable or disable an IoTGW application

The IoTGW application is started by a system initialisation process. The startup script is located in /etc/init.d/iotgw.

Activate the initialisation script using the following command:

sudo update-rc.d iotgw defaults 99

However, this script is normally already activated, and there’s no need to execute this command.

If the command

ls /etc/rc5.d

shows S99iotgw file, then the script is active. To stop IoTGW from starting, remove it from the init process using the following command:

sudo update-rc.d -f iotgw remove .

Note: The dot at the end of the command is required.

The above command removes the script from startup, but it won’t remove the actual file so that it can be reactivated later.

System services are added or removed using update-rc.d.

Processes can be added to init and they start during boot.

Configure the Wirepas settings

The Wirepas stack uses more configuration parameters than what are set in the gw.conf file, and you may need to edit node_config.json in /usr/treon/wirepas.

node_config.json sets and resets the default values for the basic parameters (such as the network ID) for the Wirepas mesh. If there is an IoT gateway application, it overrides the values set by node_config.json.

Use configure_node.py with -c switch to set the new configuration from node_config.json.

python -m wirepas.tools.configure_node -c node_config.json

The parameters are:
network_address: Wirepas network address. Must be the same for all devices in the network.
network_channel: Channel for discovering other devices. Must be the same for all devices in the network.

role: Role of the device in the network. Must be “1” which indicates a sink to “17” which indicates a sink that keeps the receiver on all the time.
node_address: Address of the device in the network. Must be unique.

cipher_key: A 128-bit communication cipher key, 16 bytes presented as a hex formatted string, for example “12c 45ff34…etc“.

Warning: Remove the keys from this configuration file after you have set the values with configure_node.py. Otherwise there is a risk that the secret keys are leaked. Executing configure_node.py with empty key will erase any key possibly set earlier.

authentication_key: A 128-bit authentication key, 16 bytes presented as a hex formatted string.

Warning: Remove the keys from this configuration file after you have set the values with configure_node.py. Otherwise there is a risk that the secret keys are leaked.
Executing configure_node.py with empty key will erase any key possibly set earlier.

diagnostic_interval: Interval (in seconds) which each device uses to report the network status. The valid values: 0, 30, 60, 120, 300, 600, 1800. The value “0” disables the diagnostic messages.

app_config_sequence: Sequence number for configuration. Must be changed every time when diagnostic_interval or app_config_data is changed.

app_config_data: Data sent to each device in the network.

channel_map: 4 bytes containing the bit mask that allocates respective channels to low latency traffic. For example, the value “286331153” → 0x1111 1111 dedicates every 4th channel to low latency traffic. Should be left empty if Wirepas stack 4.0 is used.

access_cycle_range_min: Minimum access cycle (ms) for contention free traffic. The valid values: 2000, 4000, 8000.

access_cycle_range_max: Minimum access cycle (ms) for contention free traffic.

Configure communication settings

Cellular connectivity may be configured by editing file /opt/nbiot_connection/modem.cfg

sudo nano /opt/nbiot_connection/modem.cfg

or

sudo vi /opt/nbiot_connection/modem.cfg

The parameters are:

MODEM_URAT: priority list of cellular technologies used for connectivity

PIN: SIM PIN code

APN: access point name override

ROAMING: defines if cellular roaming is allowed

UMNOPROF: Defines modem network profile, should not be modified unless there are connectivity issues.

PIN code can be set and enabled by using a helper script in the same folder. Note that pin have to be enabled before changing it is possible.

\#sudo python ofono_control.py –enable-pin
\#sudo python ofono_control.py –change-pin old_pin new_pin

Treon Support

You still have questions? Our dedicated team of experts is happy to help you! Please contact Treon Support directly by e-mail.

Did you know? Treon offers Premium Support and Maintenance Packages for our customers. Get even more out of Treon and boost your sales - inquire now about features and prices!