FTP Interface

The FTP interface can be used for:

  • Updating the Software
  • Updating the configuration *
  • Support

* NOTE: Multiples configuration's updates can be done simultaneously : (Thoses will be done in this order)
1. License update
2. Device update
3. Output update

If the license's check is KO, the product will not start.

Setup FTP client

Connect to µWiotys using a FTP client (ex:filezilla)

  • Host: $UWIOTYS_IP_ADDRESS
  • Port: 2222
  • Protocol: SFTP (SSH File Transfer Protocol)

Warning, the answer time of µWiotys' FTP can be very long, especially on fixed IP. If necessary, you should extend your FTP Client timeout to 60 seconds, see Application Example

Contact Wi6labs support team for user/password

End device configuration

LoraWan device provisioning on µWiotys can be done by FTP transfer. First, create the configuration file with proper parameters and format then connect to µWiotys with FTP and copy the configuration file into the proper directory.

Configuration file

File name

The name of the devices configuration file can be: devices_update.json or devices_update_XXXXXXXX.json

“XXXXXXXX” is the hardware serial number of the board (8 digits, upper case), it can be found on the web interface in the Overview ⇒ Information menu.

One or many devices can be add or deleted with the same update file. You can use µWiotys Online support interface to help create your update file.

Parameters for each device
Field Mandatory description Possible value
uwiotys.state yes Required action
"add" to configure a new device
"delete" to remove a configured device
if set to "active", nothing will be done		 "add"/"delete"/"active"
uwiotys.reference yes End device manufacturer reference Manufacturer reference : see list device
uwiotys.output_protocols.modbus.@modbus yes Modbus slave ID 1 to 200
spn.activation_type yes End device activation type, only OTAA supported "OTAA"
spn.dev_eui yes String of 16 hexadecimal characters "70B3D5E75E008888"
spn.app_eui yes String of 16 hexadecimal characters "70B3D5E75F600000"
spn.app_key yes String of 32 hexadecimal characters "78FF2CDE6D2C657F09981C3332096DF9"
spn.dev_addr no For future use
spn.nwks_key no For future use
spn.apps_key no For future use
spn.end_device_parameters.rx_window yes End device rx windows This parameters cannot be change
spn.end_device_parameters.rx_frequency yes End device rx frequency This parameters cannot be change
spn.end_device_parameters.rx_datarate yes End device data rate This parameters cannot be change
spn.end_device_parameters.class yes End device class A or C

Configuration file will be rejected at first error, missing field or wrong parameters.

File format

The file format should be as follow, several device can be listed in the sensors table.

{
  "sensors": [
    {
      "uwiotys": {
        "state": "add",
        "reference": "50-70-139",
        "output_protocols": {
          "modbus": {
            "@modbus": 1
          }
        }
      },
      "spn": {
        "activation_type": "OTAA",
        "dev_eui": "70B3D5E75E008D35",
        "app_eui": "70B3D5E75F600000",
        "app_key": "725070411F8720932F4A56B6117D0638",
        "dev_addr": "",
        "nwks_key": "",
        "apps_key": "",
        "end_device_parameters": {
          "rx_window": 3,
          "rx_frequency": 869525000,
          "rx_datarate": 0,
          "class": "A"
        }
      }
    },
    {
      "uwiotys": {
        "state": "add",
        "reference": "50-70-053",
        "output_protocols": {
          "modbus": {
            "@modbus": 2
          }
        }
      },
      "spn": {
        "activation_type": "OTAA",
        "dev_eui": "70B3D5E75E008888",
        "app_eui": "70B3D5E75F600000",
        "app_key": "78FF2CDE6D2C657F09981C3332096DF9",
        "dev_addr": "",
        "nwks_key": "",
        "apps_key": "",
        "end_device_parameters": {
          "rx_window": 3,
          "rx_frequency": 869525000,
          "rx_datarate": 0,
          "class": "A"
        }
      }
    }
  ]
}

Upload configuration

Upload the configuration file

Once connected to FTP server, copy the devices configuration file into the directory: /uwiotys/update_config/

You need to reboot to process the device update, you can reboot the gateway by two ways:

  • With ftp :

    • Create a file named "reboot" in directory "/update/".
    • A file XXXXXXXX_reboot_processed_yy is created once command processed.
    • Command reboot is processed if XXXXXXXX_reboot_processed_yy does not exist and each time the command file is edited.

  • With Kerlink gateway button:

    • iFemToCell: Press the reset button located on the side of the gateway.
    • iStation: Press once (and only once) the On/Off button.

Warning: an electric reboot can corrupt the update process

After a few seconds the LEDs stop blinking, wait another minute then it's possible to reconnect to the FTP. The status file will created in: /uwiotys/update_config/

  • If the update failed, you will find information into the file: devices_updates_$DATE_ERROR.log
  • If the update success, the file the devices configuration file is deleted and you will find the file: devices_updates_$DATE_SUCCESS.log

Current configuration

The devices current configuration of µWiotys is available in the directory: /uwiotys/current_config/

The file format is the same as the devices configuration file, it can be used to remove device for µWiotys config by simply changing "state" from "active" to "remove" for one or several devices and then follow the regular update procedure.

Output configuration

Configuration file

File name

The name of the output configuration file can be: output_update.json or output_update_XXXXXXXX.json

“XXXXXXXX” is the hardware serial number of the board (8 digits, upper case), it can be found on web interface in the Overview ⇒ Information menu.

Parameters
Field Mandatory description Possible value
http_data_server.active yes activation status of the HTTP output, if activated all device data will be sent to HTTP server, if not no messages will be sent. This does impact modbus output true / false
http_data_server.url yes url of the external server, it must be accessible from the network of the GW valid URL
http_data_server.headers yes header information for the server valid key / value list
csv.active yes activation status of the csv output, if activated all device data be stored in csv files. This does impact modbus output true / false
csv.nb_week yes Number of week the csv files will be keep. Be careful not to keep the files too long so as not to saturate the storage space [1:52]
mqtt.active yes activation status of the mqtt output. This does impact modbus output true / false
mqtt.host yes External Mqtt Broker valid host

Http output support both http and https protocols. Mqtt output support both mqtt and mqtts protocols. IN both cases, auto signed certificate are not suppoerted.

File format

The file format should be as follow.

Exemple 1
{
  "http_data_server": {
    "active": true,
    "url": "https://webhook.site/102211e8-f30f-4117-82fa-999e1fd47caa",
    "headers": {}
  },
  "csv":{
    "active": true,
    "nb_week": 15
  },
  "mqtt":{
    "active": true,
    "host": "mqtt.uWiotys.io",
    "port": 1883,
    "topic": "MyTopic",
    "login": "",
    "password": "",
    "secure(TLS)": false
  }
}

Exemple 2
{
  "http_data_server": {
    "active": false,
    "url": "http://MyHTTPServer:8080",
    "headers": {
      "Content-Type": "application/x-www-form-urlencoded",
      "Authorization": "Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJBTDBERmROLW1DNFpMTFJCVXh4OFdxN1RNZTVmQ3NNSE1FV1FsUklNYmRjIn"
    }
  },
  "csv":{
    "active": true,
    "nb_week": 15
  },
  ,
  "mqtt":{
    "active": true,
    "host": "mqtt.uWiotys.io",
    "port": 8883,
    "topic": "MyTopic",
    "login": "MyLogin",
    "password": "MyPass",
    "secure(TLS)": true
  }
}

Upload configuration

Upload the configuration file

Once connected to FTP server, copy the output configuration file into the directory: /uwiotys/update_config/

You need to reboot to process the device update, you can reboot the gateway by two ways:

  • With ftp :

    • Create a file named "reboot" in directory "/update/".
    • A file XXXXXXXX_reboot_processed_yy is created once command processed.
    • Command reboot is processed if XXXXXXXX_reboot_processed_yy does not exist and each time the command file is edited.

  • With Kerlink gateway button:

    • iFemToCell: Press the reset button located on the side of the gateway.
    • iStation: Press once (and only once) the On/Off button.

Warning: an electric reboot can corrupt the update process

To test the HTTP configuration, µwiotys will send a test request with information about the Gateway (EUI, IP and MAC) and wait for a 200 OK response.

{
    "EUI": "7076FF0056050190",
    "IP": "192.168.100.143",
    "MAC": "70:76:ff:03:02:e1"
}

After a few seconds the LEDs stop blinking, wait another minute then reconnect you to the FTP. The status of the output configuration update can be found in /uwiotys/log/uwiotys_functionnal.log

Current configuration

The output current configuration of µWiotys is available in the directory: /uwiotys/current_config/

License Configuration

Configuration file

Where to get the license

See with Wi6labs if not already provided with the product.

File name

The license's file's name look like : license_XXXXXXXX.json. With "XXXXXXXX" as the hardware serial number.

Upload configuration

Upload the license

To give or update a license, the license's file has to be put in the following folder using FTP : /uwiotys/update_config/
After that step, a reboot is needed to take this license into account. You can reboot by two ways:

  • With ftp :

    • Create a file named "reboot" in directory "/update/".
    • A file XXXXXXXX_reboot_processed_yy is created once command processed.
    • Command reboot is processed if XXXXXXXX_reboot_processed_yy does not exist and each time the command file is edited.

  • With Kerlink gateway button:

    • iFemToCell: Press the reset button located on the side of the gateway.
    • iStation: Press once (and only once) the On/Off button.

See How to know if the product has a license to know if the license is correctly added.

How to know if the product has a license

You can find the information in the file : uwiotys/log/uwiotys_functional.log.

Logs can be :

  • "No license found, µWiotys will not start. Please configure a valid license for your µWiotys gateway XXXXXXXX" when NO license is present.
  • "The license is VALID. µWiotys will start." when the product have a license.

How to know the license's type and state

When the license is valid, you can find informations in the file : uwiotys/log/uwiotys_functional.log.

Logs can contain :

  • "Check license success. license type SIMPLE - C license in use, out of M license." for the SIMPLE license.
  • "Check license success. license type: LISTED : L" for the LISTED license.

With C as the currently used number of sensors, M as the maximum possible sensors' number.
And L as the list of authorized references.

How to know what outputs can be used with the current license

When the license is valid, you can find informations in the file : uwiotys/log/uwiotys_functional.log.

Logs contain :

License allow user to activate the following output:
Modbus output:  true/false
Csv output: true/false
Http output:    true/false
Mqtt output:    true/false

Software Update

It is possible to update the installation of µwiotys to benefit from recent evolutions.

Updating files

Please contact Wi6labs support to get software files updates.

Update process

From 1.2.x to 1.3.0

  1. Replace the XXXXXXX of the provided file : XXXXXXXX_data.json to be the 8 lasts digits of µwiotys' EUI.
  2. Push the renammed file to the configuration folder.
  3. Check that a file (XXXXXXXX_set_configuration_processed_ok) is created in the configuration folder. (TIPS: Don't forget to refresh, if the file isn't created please reboot the GW and restart from step 1)
  4. Push the file : uwiotys-update_1.3.0_klkgw.ipk to the update folder.
  5. Push the update file to the update folder.
  6. Check that a file (XXXXXXXX_update_processed_ok) is created in the update folder. (TIPS: Don't forget to refresh)
  7. Push the reboot file to the update folder.
  8. Check that a file (XXXXXXXX_reboot_processed_yy) is created in the update folder. (TIPS: Don't forget to refresh)
  9. Wait. (Take arround 5 minutes to complete)
  10. If everything is ok, you must find in uwiotys/devices_current_config the following file : devices_date-time.json

From 1.3.x to 2.x.x

  1. Push the file : uwiotys-update_2.x.x.xxxx.ipk to the update folder.
  2. Push the update file to the update folder.
  3. Check that a file (XXXXXXXX_update_processed_ok) is created in the update folder. (TIPS: Don't forget to refresh, if the file isn't created please reboot the GW and restart from step 1)
  4. Push the reboot file to the update folder.
  5. Check that a file (XXXXXXXX_reboot_processed_yy) is created in the update folder. (TIPS: Don't forget to refresh)
  6. Wait. (Take arround 5 minutes to complete)
  7. Push the license to µwiotys, see how to in : Upload the license chapter.
  8. If everything is ok, you must find in the last part of uwiotys/log/uwiotys_functional.log the following line : The license is VALID. µWiotys will start.

From 2.x to 2.x and 3.x to 3.x

Warning upgration from 2.x to 3.x is not supported !

  1. Push the file : uwiotys-update_2.x.x.xxxx.ipk to the update folder.
  2. Push the update file to the update folder.
  3. Check that a file (XXXXXXXX_update_processed_ok) is created in the update folder. (TIPS: Don't forget to refresh, if the file isn't created please reboot the GW and restart from step 1)
  4. Push the reboot file to the update folder.
  5. Check that a file (XXXXXXXX_reboot_processed_yy) is created in the update folder. (TIPS: Don't forget to refresh)
  6. Wait. (Take arround 5 minutes to complete)
  7. If everything is ok, you must find in the last part of uwiotys/log/uwiotys_functional.log the following line : The license is VALID. µWiotys will start.

Note

The update do not affect your current device and network configuration.