Articles in this section

See more

Data source - Plain-text TCP

  • Updated
Supported hardware
IXrouter3, firmware 3.7 and up (upgrade)
IXrouter2, firmware 2.11 and up (upgrade)

For Live data, Historical data, Datalogging to MQTT broker, and Alarming you'll need to set up a data source and add variables. This article shows you how to do this for communication via Plain-text TCP (previously called LoggerAPI).

Contrary to the other supported protocols, with Plain-text TCP the machine data is not requested by the IXrouter but needs to be actively sent by the machine to the IXrouter. This effectively means that from the machine you'll need to establish a TCP connection to the IXrouter and then send data over that connection using plain-text. Plain-text TCP is a line based protocol where each line is terminated by a newline (\n), or carriage return (\r).

Manufacturers that support Plain-text TCP: Beckhoff, Lenze, Sigmatek and more.

Add a data source

The machine will need to be added as a Plain-text TCP data source.

  1. Go to Fleet Manager > Devices and click on your device name.
  2. In the left menu, at Services, click on the add.svg icon and select Data source > Plain-text TCP.
  3. Enter the requested information (details below) and click on Add.
    Field Description
    Name Enter a name for the data source.
    Identifier The identifier is entered automatically and ensures that every data source remains unique, even if they share the same name.
    IP address Enter the IP address of your machine. Leave empty if you're using an IXagent.
    Password Choose a password of at least 6 characters. You will need this later on.
    Polling sleep time

    The IXrouter will continuously request data from the machine. This then enables you to log aggregated values, like the average value or the maximum value that occurred, and to trigger alarms when certain conditions are met.

    The polling sleep time is the time that the machine can wait between sending data to the IXrouter. It is optional, but recommended to prevent flooding the IXrouter with data.

    A polling sleep time of 100ms is recommended. This value can be requested by the machine by sending an INFO request to the IXrouter after establishing a TCP connection to the IXrouter (step 8):

    INFO

Add variables

Once you've added a data source, you can start adding variables.

  1. Under your data_source_outline.svg Data source, go to Variables and click onadd.svgAdd variable.
  2. Enter the requested information (details below) and click on Add.
    Field Description
    Name Enter a name for the variable.
    Identifier The identifier is entered automatically and ensures that every variable remains unique, even if they share the same name.
    Type Select the variable's data type (bool, int, float, etc).
    Address Choose an address for this variable (e.g. b1 or TemperatureZone6), you will need this later on.
    Factor Multiplies the value. Leave empty if the data type is boolean.
    Unit Displayed behind the value (e.g. kg).
  3. Repeat step 5 for every variable you want to add or click Import from CSV-file near the top right corner to add variables in bulk instead.
    • The structure of the CSV file is explained here: Import variables: CSV file structure.
    • Using Export to CSV-file and Import from CSV-file enables you to easily copy variables from one device to another device. Alternatively, you can also use device templates.

You have now made the changes in the IXON Cloud, but these are not yet active in your device. You will need to push your changes to your device for them to take effect.

Temporary disconnect

After this next step, the config push, the device may temporarily disconnect and LAN communication may be temporarily interrupted while it's applying the new settings. This only takes a moment.
  1. Click on Push config to device in the top right corner.

Send data from the machine to the IXrouter

The IXrouter is now listening and waiting for data. From the connected machine, you'll now need to connect to the IXrouter and then send data.

Connect to the IXrouter

The IXrouter is listening on port 9230 for a TCP connection. The exact steps on how to establish a TCP connection from your machine may differ per manufacturer.

  1. Establish a TCP connection from your machine to the IXrouter's LAN IP address on port 9230 (use 127.0.0.1 if you're using an IXagent). For example, using netcat:
    netcat 192.168.140.1 9230
    Note that you can close the connection using the EXIT command: 
    EXIT

If all went well, you should see the IXrouter's reply "HELO".

Now that you have a TCP connection, you need to connect to the data source that you created. To do so you'll need to know the IP address and password you entered when you created the data source.

  1. Run the following command to establish a connection to the data source. Replace DataSourceIpAddress and DataSourcePassword with the IP address and password you entered for the data source earlier:
    DEVC DataSourceIpAddress DataSourcePassword
    For example:
    DEVC 192.168.140.10 1234

If all went well, you should see the IXrouter's reply "DEVC OK".

Send data to the IXrouter

Now that you're connected, you can start sending data. To do so, you'll need to know the variable's address that you chose when you created the variable in the IXON Cloud.

  1. Send data to the IXrouter using this syntax for one variable:
    @address=value
    Or multiple variables separated by a newline (\n) or carriage return (\r).
    @address=value\n@address=value\n@address=value\n

    Note that newlines are not allowed in arguments unless escaped. Arguments may be separated by several spaces, though recommended is the absolute minimum: no spaces if another separator was used or one space if the space is the separator.

    The syntax differs per data type. Below is an overview including examples.
    Data type Details and example
    Boolean t=True
    f=False
    Example:
    @bool=f
    Integer Numerical value. Example:
    @int=153
    Float Point separated value. Example:
    @float=152.7
    String The exact string length (max. 254) separated from the string value by a comma. Example:
    @string=6,Halted

    Are you receiving an error back from the IXrouter? Below is an overview of common errors.

    Error Description
    EROR <message> A general error response. The message should contain a readable explanation of what went wrong. The message may contain spaces, everything that comes after EROR will be the message.
    TGNF @<address> The tag with the given address was not found. The machine should stop sending data values for this address or the address should be added in the IXON Cloud data source and pushed to the IXrouter.
    INVL <message> The value received by the IXrouter does not match the variable definition as it is configured in the IXON Cloud data source. The machine should stop sending invalid data values for this address.

Test variables

The variables test is recommended to check if all added variables are configured correctly. It shows the value of all variables if everything is configured correctly and shows an error if something is not configured correctly.

  1. Click on Run test near the top right corner and start sending data from your machine to the IXrouter.
    • The test will attempt to update values every 0.5 seconds.
    • Is the test showing unexpected values? Check the addresses and data types of the variables.
    • Is the test showing a timeout error? Check that the data source is configured correctly and the machine is connected and powered on. If you are still getting a timeout error, contact your IT to make sure the test is not blocked. The test sets up an outgoing connection from your computer to the IXrouter using:
      Port Transport protocol Application protocol
      443 TCP WebSocket

Live data, Historical data, Alarming

Now that the data source and variables have been set up, you can continue below.

  1. Click below to continue in the feature specific articles.