PLC / FTP mode

  7 minute read  

Application Settings

The appsettings.json document is a structured settings file.

Note
 The application settings file uses parameters with the full name, referring to the structure in the BeeYard. For example, Client is named as input_gateway in the BeeYard, but the full ID includes its Tenant and is displayed as public.input_gateway. Similarly, Tags use the Namespace as a prefix in the application settings.

FTP

The Input Gateway has an active FTP client, which can be connected to the FTP Server to receive files from it. To connect to the Server, set the Host IP address, Username, and Password.

FTP Settings
"Ftp": {
    "Host": "127.0.0.1",
    "Username": "username",
    "Password": "password"
  }

Hive

The Hive collection contains information about the BeeYard Hive and Input Gateway connection. The Hive is defined by the HiveUri and IdUri`, while the connection is defined by the ClientID and ClientSecret. The Uri is the address of the Hive, which can be a local installation or a server reachable from the application. To create the Client in the BeeYard, open the Users and Roles app, go to the Clients tab and Add Client. The Client’s secret is available right after the Client is created, so make sure to copy it. Alternatively, you can regenerate the Client’s secret and use the new one.

Example Hive settings for a local BeeYard installation
"Hive": {
    "HiveUri": "http://localhost/hive/",
    "IdUri": "http://localhost/id/",
    "ClientId": "public.inputgw",
    "ClientSecret": "secret_copied_from_the_BeeYard"
  }
Example Hive settings for BeeYard server
"Hive": {
    "HiveUri": "https://demo.beeyard.ai/hive/",
    "IdUri": "https://demo.beeyard.ai/id/",
    "ClientId": "public.inputgw",
    "ClientSecret": "secret_copied_from_the_BeeYard"
  }

Upload

The data is uploaded into the selected Workspace, which is defined in the Input Gateway by its Namespace. This information is visible in the Workspace settings.

Target Workspace
"Upload": {
  "Namespace": "input_gateway"
}

TCP

The Input Gateway has an active TCP server, which allows Tags and Properties belonging to the data to be sent from a TCP Client.

TCP Settings
"Tcp": {
    "Enabled": true,
    "Host": "127.0.0.1",
    "Port": 1234,
    "MaxConnections": 1,
    "AllowedHosts": [
      "127.0.0.1"
    ],
    "DecimalSeparator": "."
  }

PLC / FTP

These settings describe the PLC connection and the source of the uploaded Images and other data. Here are specified all the Tags used to annotate the data source. The Timeout` parameter defines a time window in which all the necessary data need to arrive in order to be placed in the same Cell. After the Timeout, the Cell is closed, and newly arrived data is put into another Cell.

The Tags are defined by Category, which is built from the Namespace as a prefix and the Tag category from the BeeYard. The Name is the same as a Tag name in the BeeYard. The image source fis described in the Cameras section. It can either be a FTP or a local drive directory. If the parameter UseFtp is disabled, then the local disk is used with Folder as a directory without connecting to the FTP server. If UseFtp is enabled, then the Input Gateway uploads images from FTP server.

PLC and camera devices settings
"PlcFtp": {
    "Enabled": true,
    "TimeoutMs": 5000,
    "Tag": {
      "Category": "input_gateway.device",
      "Name": "input_gateway"

    },
    "Plc": {

      "Tag": {
        "Category": "input_gateway.device",
        "Name": "plc"
      }
    },
    "Cameras": [
      {
        "Tag": {
          "Category": "input_gateway.device",
          "Name": "camera1"
        },
        "UseFtp": true,
        "Folder": "/camera1",
        "ImageName": "image.jpg"
      }
    ]
  }
Tip
 The Gateway can collect data from multiple camera devices and upload them into the same Cell, but each camera must have a different Folder and Image name. If multiple camera devices share the same directory, only one image is uploaded into the Cell, and all others created before the Timeout are ignored.
Example with one FTP camera
"Cameras": [
  {
    "Tag": {
      "Category": "input_gateway.device",
      "Name": "camera1"
    },
    "UseFtp": true
    "Folder": "/camera1",
    "ImageName": "image.jpg"
  }
]
Example with two FTP cameras
"Cameras": [
  {
    "Tag": {
      "Category": "input_gateway.device",
      "Name": "camera1"
    },
    "UseFtp": true,
    "Folder": "/camera1",
    "ImageName": "image1.jpg"
  },
  {
    "Tag": {
      "Category": "input_gateway.device",
      "Name": "camera2"
    },
    "UseFtp": true,
    "Folder": "/camera2",
    "ImageName": "image2.jpg"
  }
]

Urls

The Urls is an endpoint that can be used to obtain information about the health of the Input Gateway, e.g. by calling curl localhost:5001/api/v1/health.

URLs settings
"Urls": "http://localhost:5001"

Allowed Hosts

Keep the value as * to allow all connections.

Allowed hosts
"AllowedHosts": "*"

Report Metrics

Enable or disable metrics. They can be reached by calling curl localhost:5001/api/v1/metrics.

Report metrics enable / disable
"ReportMetrics": true

Serilog

These settings contain parameters setting up the level of information displayed in the Console and saved into the Log file. Depending on the amount and level of required information, use Information, Warning, or Error values. In the Write To setting, both outputs, the Console and the Log file, are described. Parameters such as path or file size limit can be set.

Serial log settings
"Serilog": {
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft": "Warning",
        "Microsoft.Hosting.Lifetime": "Information",
        "System": "Warning",
        "FluentFTP.FtpClient": "Warning"
      }
    },
    "Using": [
      "Serilog.Sinks.Async",
      "Serilog.Sinks.Console",
      "Serilog.Sinks.File"
    ],
    "WriteTo": [
      {
        "Name": "Async",
        "Args": {
          "configure": [
            {
              "Name": "Console",
              "Args": {
                "formatter": "Serilog.Formatting.Compact.RenderedCompactJsonFormatter, Serilog.Formatting.Compact"
              }
            },
            {
              "Name": "File",
              "Args": {
                "path": "log/input_gateway.log",
                "fileSizeLimitBytes": 10000000,
                "rollOnFileSizeLimit": true,
                "retainedFileCountLimit": 10,
                "rollingInterval": "Day",
                "formatter": "Serilog.Formatting.Compact.RenderedCompactJsonFormatter, Serilog.Formatting.Compact"
              }
            }

          ]
        }
      }
    ]
  }

Uploading Data

The data are uploaded into the selected Workspace in the BeeYard Hive. New Cells with Tags and Properties are created along with the received Images. The Gateway uploads all received data into the one (new) Cell until the Timeout is reached. Then the Gateway leaves the Cell, and with new data and messages, creates a new Cell again and resets the timer.

Tip
 The data can be uploaded using multiple Input Gateways, but each Gateway works with its own Cells; there are no shared Cells. Howerver, it is possible to connect more devices using one Input Gateway as well, and the data from all the devices are uploaded into the same Cells.
The Flow describing 2 camera devices connected to the BeeYard using one Input Gateway

  1. The Input gateway is up and running.

  2. Camera_1 sends an image (Image_1) to the FTP server.

  3. The Gateway finds Image_1.

  4. The Gateway creates a new Cell (Cell_1) and:

    • Uploads Image_1 (using the ImageName in the PlcFtp settings, camera section).

    • Adds the Gateway Tag (using the Tag in the PlcFtp section).

    • Adds the Camera_1 Tag (using the Tag in the PlcFt settings, camera section).

    • Starts the timer.

  5. Camera_2 sends an image (Image_2) to the FTP server.

  6. The Gateway finds Image_2.

  7. The Gateway opens Cell_1 and:

    • Uploads Image_2 (using the ImageName in the PlcFtp settings, camera section).

    • Adds the Camera_2 Tag (using the Tag in the PlcFtp settings, camera section).

  8. The PLC sends a message to the Gateway, with Tags and/or Properties.

  9. The Gateway opens Cell_1 and:

    • Adds the Tag from the message.

    • Adds the Property from the message.

    • Adds the PLC Tag (using the Tag in the PlcFtp settings, Plc section).

  10. Cell_1 is considered complete once all the needed data arrives or the Timeout is reached.

  11. The Gateway is ready to upload a new Cell.

TCP Messages - Uploading Tags and Properties

Tags and Properties are added to the open Cell by sending a message from a TCP client e.g. PLC.

The messages can be in a XML format or a string format. Possible property types are: number (int64 or float64), string (string), and bool (possible values are 0 for false or 1 for true).

Message components

  • Start character

    • <STX>

  • End character

    • <ETX>

  • Decimal point separator character

    • .

String components

  • Separator character

    • ;

    • This symbol is used among all components in the message.

  • Start value character

    • :

    • This symbol is used to set a value for the component.

  • Tag

    • TAGCATEGORY and TAGNAME

    • 0 .. n Tags can be defined in the message. Each Tag is defined by TAGCATEGORY composed from the Namespace and the Category itself, and TAGNAME component containing the name.

  • Property

  • PROPERTYKEY, PROPERTYTYPE and PROPERTYVALUE

    • 0 .. n Properties can be defined in the message. Each Property is defined by PROPERTYKEY, PROPERTYTYPE and PROPERTYVALUE components with set values.

    • PROPERTYTYPE can be a number, string, or bool.

XML elements

  • Frame

    • <FRAME>..</FRAME>

  • Tag

    • <TAG><CATEGORY>..</CATEGORY><NAME>..</NAME></TAG>

    • 0 .. n Tags can be defined in the message. Each Tag is defined by <TAG>, <CATEGORY>, and <NAME> elements with set values. The value of the Tag Category is composed of the Namespace and the Tag Section.

  • Property

    • <PROPERTY><KEY>..</KEY><VALUE>..</VALUE></PROPERTY>

    • 0 .. n Properties can be defined in the message. Each Property is defined by <PROPERTY>, <KEY>, and <VALUE> elements with set values.

XML example
---
<FRAME>
    <TAG>
      <CATEGORY>input_gateway.Status</CATEGORY>
      <NAME>OK</NAME>
    </TAG>
    <TAG>
      <CATEGORY>input_gateway.DeviceName</CATEGORY>
      <NAME>TestDevice</NAME>
    </TAG>
    <PROPERTY>
      <TYPE>number</TYPE>
      <KEY>Qvality</KEY>
      <VALUE>0.8</VALUE>
    </PROPERTY>
    <PROPERTY>
      <TYPE>string</TYPE>
      <KEY>SerialNo</KEY>
      <VALUE>SN123456</VALUE>
    </PROPERTY>
</FRAME>
---
Note
 The XML message needs to be enclosed within STX and ETX characters.
String example
<STX>PROPERTYKEY:Quality;PROPERTYTYPE:number;PROPERTYVALUE:0.8;PROPERTYKEY:Area;PROPERTYTYPE:number;PROPERTYVALUE:500;<ETX>
<STX>TAGCATEGORY:input_gateway.Status;TAGNAME:OK;TAGCATEGORY:input_gateway.DeviceName;TAGNAME:TestDevice;PROPERTYKEY:Quality;PROPERTYTYPE:number;PROPERTYVALUE:0.8;PROPERTYKEY:Area;PROPERTYTYPE:number;PROPERTYVALUE:500;<ETX>
Note
 Only the Tags with already existing Tag Templates in the Workspace can be used.