FTP Connector Configuration

• Connector configuration: ftp.json
  • General section
    • Subsection “security”
  • Section “paths”
  • Section “attributeUpdates”
  • Server side RPC commands
• Next steps

This guide will help you to get familiar with FTP Connector configuration for ThingsBoard IoT Gateway. Use general configuration to enable this Connector. The purpose of this Connector is to connect to an external FTP server and get data from files from specific paths. The connector is also able to push data to FTP server files based on the updates/commands from ThingsBoard.

This connector is useful when you have some FTP server in your device or some data in an external resource and you would like to push this data to the ThingsBoard.

We will describe the connector configuration file below.

Connector configuration: ftp.json

Connector configuration is a JSON file that contains information about how to connect to an external FTP server, what paths to use when reading data, and how to process the data.
Let’s review the format of the configuration file using the example below.

Example of FTP Connector config file.

The example listed below will connect to FTP server in a local network deployed on server with IP 0.0.0.0. The connector will utilize basic FTP auth using username and password. Then, connector will subscribe to a list of paths from the mapping section. See more info in the description below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
{
  "host": "0.0.0.0",
  "port": 21,
  "TLSSupport": false,
  "security": {
    "type": "basic",
    "username": "admin",
    "password": "admin"
  },
  "paths": [
    {
      "devicePatternName": "asd",
      "devicePatternType": "Device",
      "delimiter": ",",
      "path": "fol/*_hello*.txt",
      "readMode": "FULL",
      "maxFileSize": 5,
      "pollPeriod": 5,
      "txtFileDataView": "SLICED",
      "withSortingFiles": true,
      "attributes": [
        {
          "key": "temp",
          "value": "[1:]"
        },
        {
          "key": "tmp",
          "value": "[0:1]"
        }
      ],
      "timeseries": [
        {
          "type": "int",
          "key": "[0:1]",
          "value": "[0:1]"
        },
        {
          "type": "int",
          "key": "temp",
          "value": "[1:]"
        }
      ]
    }
  ],
  "attributeUpdates": [
    {
      "path": "fol/hello.json",
      "deviceNameFilter": ".*",
      "writingMode": "WRITE",
      "valueExpression": "{'${attributeKey}':'${attributeValue}'}"
    }
  ],
  "serverSideRpc": [
    {
      "deviceNameFilter": ".*",
      "methodFilter": "read",
      "valueExpression": "${params}"
    },
    {
      "deviceNameFilter": ".*",
      "methodFilter": "write",
      "valueExpression": "${params}"
    }
  ]
}

General section

Subsection “security”

Subsection “security” provides configuration for client authorization at FTP Server.

1
2
3
4
5
    "security": {
      "type": "basic",
      "username": "username",
      "password": "password"
    }

1
2
3
    "security": {
      "type": "anonymous"
    }

Section “paths”

This configuration section contains an array of objects with paths that the gateway will try to read after connecting to the server.
Also, this section contains settings for processing incoming messages (converter).

Note Make sure that your file extension is one of the supported extensions by FTP connector (.txt, .json, .csv)

The path supports special symbols, such as ‘*’ to allow subscription to multiple paths and files. Let’s look at another example of using path parameter:

Now let’s review another required parameter in path section.

Let’s look at how we can configure this section for different file extensions:

1. For .txt with TABLE data view and .csv files

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
      "paths": [
        {
          "devicePatternName": "${temp}",
          "devicePatternType": "Device",
          "delimiter": ",",
          "path": "fol/*.*",
          "readMode": "FULL",
          "maxFileSize": 5,
          "pollPeriod": 60,
          "txtFileDataView": "TABLE",
          "withSortingFiles": true,
          "attributes": [
            {
              "type": "int",
              "key": "key",
              "value": "${temp}"
            }
          ],
          "timeseries": [
            {
              "type": "int",
              "key": "${hum}",
              "value": "${temp}"
            },
            {
              "type": "int",
              "key": "temp",
              "value": "${hum}"
            }
          ]
        }
      ]
   

   That means that FTP converter will look for the following file structure:

    temp,hum
    1,2
    23,34
   

2. For .txt file with SLICED data view

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
      "paths": [
        {
          "devicePatternName": "DeviceName",
          "devicePatternType": "[0:1]",
          "delimiter": ",",
          "path": "fol/table.txt",
          "readMode": "FULL",
          "maxFileSize": 5,
          "pollPeriod": 60,
          "txtFileDataView": "SLICED",
          "withSortingFiles": true,
          "attributes": [
            {
              "key": "temp",
              "value": "[1:]"
            },
            {
              "key": "tmp",
              "value": "[0:1]"
            }
          ],
          "timeseries": [
            {
              "type": "int",
              "key": "[0:1]",
              "value": "[0:1]"
            },
            {
              "type": "int",
              "key": "temp",
              "value": "[1:]"
            }
          ]
        }
      ]    
   

   That mean that FTP converter will look for the next file structure:

    1,2
    23,34
   

3. For .json file

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
    "paths": [
        {
          "devicePatternName": "${temp}",
          "devicePatternType": "Device",
          "delimiter": ",",
          "path": "fol/*.json",
          "readMode": "FULL",
          "maxFileSize": 5,
          "pollPeriod": 60,
          "withSortingFiles": true,
          "attributes": [
            {
              "type": "int",
              "key": "key",
              "value": "${temp}"
            }
          ],
          "timeseries": [
            {
              "type": "int",
              "key": "key",
              "value": "${temp}"
            },
            {
              "type": "int",
              "key": "temp",
              "value": "${tmp}"
            }
          ]
        }
      ]
   

4. Combine attributes, telemetry, and serverSideRpc section, for example, in a .json file:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
     "paths": [
          {
            "devicePatternName": "${temp}",
            "devicePatternType": "Device",
            "delimiter": ",",
            "path": "fol/*.json",
            "readMode": "FULL",
            "maxFileSize": 5,
            "pollPeriod": 60,
            "withSortingFiles": true,
            "attributes": [],
            "timeseries": [
              {
                "type": "int",
                "key": "hum",
                "value": "${hum}"
              },
              {
                "type": "int",
                "key": "temp",
                "value": "${tmp}"
              },
              {
                "type": "string",
                "key": "combine",
                "value": "${tmp}::${hum}"
              }
            ]
          }
        ]
   

Section “attributeUpdates”

This configuration section is optional. ThingsBoard allows the provisioning of device attributes and fetches some of them from the device application. You can treat this as a remote configuration for devices, enabling them to request shared attributes from ThingsBoard. See user guide for more details.

The “attributeRequests” configuration allows you to configure the format of the corresponding attribute data that will be written to the specific files.

This section in configuration file looks like this:

1
2
3
4
5
6
7
8
  "attributeUpdates": [
    {
      "path": "fol/${attributeKey}/${attributeValue}.txt",
      "deviceNameFilter": ".*",
      "writingMode": "OVERRIDE",
      "valueExpression": ",,,,${attributeKey},,,${attributeValue}"
    }
  ]

Server side RPC commands

ThingsBoard allows for sending RPC commands to devices connected directly to ThingsBoard or via Gateway.

Configuration, provided in this section uses for sending RPC requests from ThingsBoard to device.

This section in configuration file looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
"serverSideRpc": [
  {
    "deviceNameFilter": ".*",
    "methodFilter": "read",
    "valueExpression": "${params}"
  },
  {
    "deviceNameFilter": ".*",
    "methodFilter": "write",
    "valueExpression": "${params}"
  }
]

Let’s look at an examples.

Read data example

Suppose you want to read data from the file on connected FTP server. Go to enabled FTP connector RPC page and fill in fields with the following configuration and click on “Send” button:

After that, response will be shown in the “Response” field:

Write data example

Make sure the file you want to write data to has the appropriate permissions. Otherwise, you will get a 550 Permission denied error.

Suppose you want to write some data to the file on connected FTP server. Go to enabled FTP connector RPC page and fill in fields with the following configuration and click on “Send” button:

After that, response will be shown in the “Response” field:

Let’s check if the data was written to the file on the FTP server, for this purpose use the previously described “Read data” example:

Your response should contain the data you wrote to the file as in the image below:

Next steps

Explore guides related to main ThingsBoard features:

• Data Visualization - how to visualize collected data.
• Device attributes - how to use device attributes.
• Telemetry data collection - how to collect telemetry data.
• Using RPC capabilities - how to send commands to/from devices.
• Rule Engine - how to use rule engine to analyze data from devices.