Caution! Article for developers

Information on this page is intended particularly for users with advanced technical knowledge.

Change the Wirepas network parameters

Nov 1, 2021 · 9 minutes to read

If you want to change the Wirepas network parameters of your devices, you must follow this guide. First you will have to connect to the Gateway via SSH (See Connecting to the Gateway via SSH). You need root user rights which you can acquire by typing in ‘sudo -i’. This example shows you how to move your Gateway and the nodes to another Wirepas network. First you should check that all the nodes are connected to the Gateway. (See How to check the Node data flow) Then you can change the network, channel, keys etc. of your nodes and after that you can move the Gateway to the same network.

How to change the node parameters:

After you have connected via SSH as mentioned above, you can first check that your nodes are connected to the Gateway. For that you will need the Wirepas addresses of your nodes. If you don’t have those yet, you can collect them from cloud messages (named as “SourceAddress”) or you can run a scan to get them. One way to scan them is to use the same tool that you are going to use to do the configuration. First you have to stop the ‘iotgw’ application. The stop command depends on the Gateway software version. That can be checked by typing in ‘cat /etc/build’.

For versions below 6.0: ‘/etc/init.d/iotgw stop’

For versions 6.0 and above: ‘systemctl stop iotgw’

After the ‘iotgw’ application has stopped, you can use the configuration tool. First you can scan for the nodes e.g. reading the Wirepas network address with this command ‘python /usr/lib/python2.7/site-packages/wirepas/tools/set_attribute_by_remoteAPI.py –read 2’. If that runs into a timeout, you can run it again. The process can also be interrupted by pressing ‘Ctrl + C’ if it freezes for some reason (Caution: the changes you made might be still applied).

The command mentioned above runs the ‘read’ command in a broadcast mode so you should know how many nodes you expect to be responding. For example, the network 12345 has five nodes online so the response looks like this: “Responses from 5 nodes: 44114,4492910,4843721,6122173,16368447”

Those numbers are the Wirepas addresses of the nodes responding to this command. The response value is displayed like this: “response_csap_attribute_value:12345”

As you can see, all the nodes responded that they are in network 12345. Write commands can also be run in the broadcast mode but if you have many nodes in the network, you might accidentally apply those settings to nodes you don’t want to. For that reason this guide shows how to do the configuration only for the nodes you have specified. You can copy the Wirepas addresses of your nodes from the response (in this case 44114,4492910,4843721,6122173,16368447).

To change the parameters, you have to form the correct write command. Number 2 is the network address, 3 is the channel, 13 is the cipher key and 14 is the authentication key. Write down the values you are going to use because otherwise you may not find the nodes anymore after you apply them.

Please note: Our support cannot recover the network or keys if you move your nodes to a network that you don’t know.

The keys must be 32 digit hexadecimal numbers. To disable them, you can write ‘ffffffffffffffffffffffffffffffff’ into both fields. Otherwise you should generate a unique 32 digit hexadecimal string for both fields. To keep the network as secure as possible, keys should be used. In this example the nodes are moved to network 54321 with channel 26 and keys disabled. For the five nodes mentioned above the command would be: ‘python /usr/lib/python2.7/site-packages/wirepas/tools/set_attribute_by_remoteAPI.py –nodelist 44114,4492910,4843721,6122173,16368447 –write 2=54321,3=26,13=ffffffffffffffffffffffffffffffff,14=ffffffffffffffffffffffffffffffff’.

Notice that now we are not using the broadcast mode. Instead we define the nodes after the ‘–nodelist’ flag. If you have a big amount of nodes, you can increase the waiting time with the ‘–wait’ flag (e.g. ‘–wait 300’). Run the command and wait for every node to respond. If all nodes did not respond, you can run the command again. Do not turn off the nodes right after applying this command. Otherwise your changes might be lost.

Next you can start the ‘iotgw’ application again. The start command depends on the Gateway software version.

For versions below 6.0: ‘/etc/init.d/iotgw start’

For versions 6.0 and above: ‘systemctl start iotgw’

Next step is to change the Gateway to match those settings.

How to change the Gateway parameters:

To change the Wirepas network and channel, you have to create or modify a configuration file. The Treon IoT Gateway application reads its configurations from an auto-generated file stored in ‘/opt/iotgw/gw.conf’.

This configuration file is generated by the application on boot by combining ‘/opt/iotgw/base.conf’ and config files located in ‘/opt/iotgw/conf.d/’. Basic configuration changes should always be applied by creating a configuration file with .conf-postfix in ‘/opt/iotgw/conf.d’/.

The files override options located in ‘/opt/iotgw/base.conf’ and are applied in alphabetical order so that the last option is chosen. There is a file in the ‘conf.d’ folder which contains the network and channel configuration which is created in the production (the name contains usually numbers). Best practice would be to leave that file alone and create a new one. In this case the file could be called e.g. ‘wpconf.conf’.

1. Navigate to the 'conf.d' folder using the following command: 'cd /opt/iotgw/conf.d'.
2. Create a configuration file using a text editor, e.g. Nano: 'nano wpconf.conf'

That file must contain following items:
[WpAdapter]
NetworkId=54321
NetworkCh=26

Replace those values with the ones you used for your nodes.

3. Save the file by pressing Ctrl + S. Then exit from Nano by pressing Ctrl + X. 

If there is a file called ‘wirepas_override.conf’ in the ‘conf.d’ folder, it will override the settings (you can check the existence with the ‘ls -al’ command. That file contains your old network information. You can read the file e.g. like this ‘cat wirepas_override.conf’. If your Gateway software version is 5.12.2 and the diagnostic interval is something else than zero, you should copy that to the file you created like this:

[WpAdapter]
NetworkId=54321
NetworkCh=26
DiagnosticInterval=300

Please Note: In Gateway software 5.12.2 the diagnostic interval must match with the current sink configuration.

Next you have to delete the ‘wirepas_override.conf’ file with the command ‘rm wirepas_override.conf’. That way your new network parameters are applied after you restart the ‘iotgw’ application again. The restart command depends on the Gateway software version.

For versions below 6.0: ‘/etc/init.d/iotgw restart’ For versions 6.0 and above: ‘systemctl restart iotgw’

Now you can check that your settings have been applied. For Gateway software versions 5.12.2 and later you can type ‘configure_sink -r’ and that should tell the current sink settings (‘iotgw’ must be running). If you have older Gateway software release, you can check from the auto-generated file stored in ‘/opt/iotgw/gw.conf’ if the configurations from you configuration files have been applied (do NOT edit the ‘gw.conf’ file). If your settings are applied, you must also change the Gateway keys to match the keys set for the nodes.

The keys can be changed like this:

For versions below 5.12.2:

1. Copy the JSON template file to '/tmp' like this: 'cp /usr/treon/wirepas/node_config.json /tmp'. Next edit the template file e.g. with Nano: 'nano /tmp/node_config.json'.

2. The template file looks like this:

        "network_address": "15731624",
        "network_channel": "1",
        "role": "1",
        "node_address": "REPLACE",
        "cipher_key":"",
        "authentication_key":"",
        "diagnostic_interval":"0",
        "app_config_sequence":"1",
        "app_config_data":"Treon",
        "channel_map":"",
        "access_cycle_range_min": 2000,
        "access_cycle_range_max": 8000

3. Only edit the field "node_address", "cipher_key" and "authentication_key" and don't mind the others (Unless you have Asset Nodes or Asset Sensors. Then you have to add the correct "app_config_data" and "app_config_sequence" number high enough). You can write e.g. number '1' to the "node_address" field because it will be overridden anyway. Next you must copy your desired keys to the key fields. In example it would look like this:

        "network_address": "15731624",
        "network_channel": "1",
        "role": "1",
        "node_address": "1",
        "cipher_key":"ffffffffffffffffffffffffffffffff",
        "authentication_key":"ffffffffffffffffffffffffffffffff",
        "diagnostic_interval":"0",
        "app_config_sequence":"1",
        "app_config_data":"Treon",
        "channel_map":"",
        "access_cycle_range_min": 2000,
        "access_cycle_range_max": 8000

4. Save the file by pressing Ctrl + S. Then exit from Nano by pressing Ctrl + X. 
5. Stop the 'iotgw' application by typing in '/etc/init.d/iotgw stop'.
6. Run the script: 'python -m wirepas.tools.configure_node -c /tmp/node_config.json' (If you edited the 'app_config' fields for asset devices, you must use also '-x' flag in the command).
7. Start the 'iotgw' application by typing in '/etc/init.d/iotgw start'.
8. The edited template file is removed when the Gateway is rebooted if it is in the '/tmp' folder. You can also delete it manually by typing in: 'rm /tmp/node_config.json'.

For versions 5.12.2 and above: 1. Copy the JSON template file to ‘/tmp’ like this: ‘cp /usr/treon/wirepas/node_config.json /tmp’. Next edit the template file e.g. with Nano: ‘nano /tmp/node_config.json’. 2. Remove the additional lines that we don’t want to edit. If you are using Nano, you can use ‘Ctrl + k’ to delete the lines. After that the file should look e.g. like this:

{
        "cipher_key":"",
        "authentication_key":""
}

Remember to delete the comma after the "authentication_key":"" because it is the last item. That way the JSON format is correct. 
3. Add your keys like this:

{
        "cipher_key":"ffffffffffffffffffffffffffffffff",
        "authentication_key":"ffffffffffffffffffffffffffffffff"
}

4. Save the file by pressing Ctrl + S. Then exit from Nano by pressing Ctrl + X. 
5. Run the tool: 'configure_sink -c /tmp/node_config.json'. (If you edited the 'app_config' fields for asset devices, you must use also '-x' flag in the command).
6. The edited template file is removed when the Gateway is rebooted if it is in the '/tmp' folder. You can also delete it manually by typing in: 'rm /tmp/node_config.json'.

Now your keys and network settings should be set correctly. Next you can press the Industrial Node’s button to see if the node is turned on and connected to the Gateway. One option is to use the ‘read’ command described above to see if every node is connected again to the Gateway with the new Wirepas parameters.


Was this article helpful? Let us know.