Skip to main content
Version: 5.3.0

REST Source

The Tributech Agent supports the integration of external data sources using REST with the Tributech REST Source. The REST Source is configured via the Twin Configuration and is used to send data to the Tributech Agent via MQTT. The data can be send to the Tributech Source via Swagger.

We currently support two types of data format for the REST Source:

  • REST Pre-defined Payload: Data will be provided in a pre-defined format containing a unique combination of MachineId and SensorId to identify the DataStreamId of the Twin Configuration (see Swagger for details)
  • REST Stream: Data will be provided with the DataStreamId of the Twin Configuration contained in the data (see Swagger for details)

We will show in Configuration how to configure the REST Source to accept data for each specific stream type and provide the examples for Swagger.

The Source will return a status code 200 OK if the data was successfully received and is queued to be published to the Tributech Agent. The status code does not indicate that the data was successfully transferred to the Tributech Agent or Tributech Node. Queueing the data to be published means that the Source received the data and publishes the data after applying options contained by the Twin configuration if defined, e.g. ValueChangeOptions.

Setup​

The Tributech REST Source image can be started without any dependencies but will not be functional without a valid Twin Configuration or MessageBroker connect to the Tributech Agent. The TwinConfiguration can be provided via the Tributech Node (recommended) or MessageBroker (see Source Integration). The REST Source will automatically connect to the Tributech Agent if the Tributech Agent is running and correct MessageBroker settings are set.

In the following part we will describe the setup of a Tributech REST Source.

  • Create a docker-compose.yml file with the following content (adjustments required):
docker-compose.yml
version: "3.6"

services:
  source-rest:
    image: ${DOCKER_REGISTRY-tributech.azurecr.io/}tributech-source-rest:${SOURCE_TAG:-5.3.0}
    depends_on:
      - mosquitto-server
      - tributech-agent
    environment:
      - MqttOptions__MQTTHost=mosquitto-server
      - Logging__LogLevel__Default=Information
    ports:
      - "5080:8080"
    networks:
      - rest-net
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "2m"
        max-file: "5"

  tributech-agent:
    image: ${DOCKER_REGISTRY-tributech.azurecr.io/}tributech-agent:${AGENT_TAG:-5.4.2}
    depends_on:
      - mosquitto-server
    environment:
      - Logging__LogLevel__Default=Information
      - Logging__Console__FormatterName=simple
      - MqttOptions__MQTTHost=mosquitto-server
      - EdgeDeviceOptions__NodeUrl=${NODE_URL:?"The Tributech Node Url is required"}
    networks:
      - rest-net
    ports:
      - "5001:8080" # enable access to agent REST-API (e.g. for configuration with Agent-Companion)
    volumes:
      - app-data:/app/data # volume mapping for permanent storage of keys and datatwin file
      - ./enrollment:/app/enrollment # local enrollment folder mounted to /app/enrollment
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "2m"
        max-file: "5"

  mosquitto-server:
    image: eclipse-mosquitto:${MQTT_TAG:-1.6}
    networks:
      - rest-net
    # ports:
    # - '1883:1883' # MQTT
    # - "127.0.0.1:9001:9001" # web-socket
    restart: unless-stopped


volumes:
  app-data:

networks:
  rest-net:

Adjust the setting for the Tributech Agent to your environment, sample value:

env specific settings
tributech-agent:
    ...
    environment:
      ...
      - EdgeDeviceOptions__NodeUrl=https://my-environment.tributech-node.com

The Tributech Agent authenticates with the Tributech Node using enrollment certificates provided through a local enrollment folder mounted into the container (the ./enrollment:/app/enrollment volume in the docker-compose.yml above). See Authentication Certificates (Enrollment) and Docker volumes in the Setup guide for how to create and provide it. If no Agent ID is configured, the agent generates a random one on first start.

Configuration​

After setting up the Tributech REST Source we need to activate it in the Tributech Node (see Agent Management) and configure the TwinConfiguration. For both Streams we need first to create a new Source in the Tributech Node and then add the Streams to the Source. The following sections will show how to create a new Source and add the Streams to the Source. One Source can include multiple Streams of both types.

Add REST SourceAdd REST Source

REST Stream​

At first we add the REST Stream to our newly created Tributech REST Source. The REST Stream will be used to send data to the Tributech Node based on an unique identifier contained in the json payload. The REST Stream can be added by right clicking the REST Source and selecting Add Streams. The following dialog will appear:

Add REST StreamAdd REST Stream

After adding the REST Stream we configure the Data Encoding (in red). The REST Stream is now configured but can only be used to send data to the REST Source after submitting the changes to the Tributech Source via APPLY CONFIGURATION. The REST Stream will only accept data that contains the DataStreamId of the REST Stream. The DataStreamId can be found on the top of the REST Stream configuration (in green):

REST Stream configREST Stream config

After we have configured the REST Source we can apply the configuration to the Tributech Agent by clicking on the APPLY CONFIGURATION button in the top right corner.

Pre-defined Payload Stream​

In contrast to a generated identifier of the REST Stream we can now define a two string's used to identify the DataStreamId for the REST Source. The pre-defined payload will be added by right clicking the REST Source and selecting Add Streams. The following dialog will appear:

Add Pre-defined Payload StreamAdd Pre-defined Payload Stream

After adding the REST Stream we configured the Data Encoding and one or both of the identifiers (Source/Value). The Source Identifier and Value Identifier will be used to uniquely match data to the DataStreamId (not contained in payload).

Pre-defined Payload Stream configPre-defined Payload Stream config

After we have configured the REST Source we can apply the configuration to the Tributech Agent by clicking on the APPLY CONFIGURATION button in the top right corner. The REST Stream is now configured and can be used to send data to the REST Source. The REST Stream will only accept data that contains the same combination of source identifier and value identifier.

Value Change Options​

The basic handling of Value Change Options (VCO) can be found in Source Integration. This section contains the concrete handling of the Step (Delta) for the simulated source. The following list contains the description for each supported Stream Data Encoding where X represents the value for Step (Delta):

  • Double, Int32, Long, Float: defines the minimum difference between values to be submitted, the change is always compared to the last successful submitted value, e.g. if X= 3 if the double values 1, 2, 5, 8, 10, 11, 14 are received by the Tributech Source only 1, 5, 8, 11, 14 will be submitted.
  • Byte Array: will only be submitted if the current and last submitted value are not equal
  • String UTF 8: will only be submitted if the current and last submitted value are not equal
  • Boolean: will only be submitted if the current and last submitted value are not equal

Providing Data​

In the following section we describe how to provide data to the REST Source using the Swagger UI. The following sections show how to send data to the REST Source for each type of Stream.

REST Endpoint/Swagger​

The REST Source provides a Swagger UI to send data to the REST Source. The Swagger UI can be accessed via the following url: http://<host>:5080/swagger/index.html. There are different endpoints available for each type of Stream and type of data (encoding provided values based on .NET Framework BitConverter).

REST Stream​

The data for the REST Stream needs to be submitted in the Endpoint Group Stream and contain the DataStreamId (previously marked green in the configuration section) of the REST Stream. The Swagger UI will only accept data that contains the same DataStreamId in the json payload as defined in the TwinConfiguration for a REST Stream. Examples on how to submit data to the REST Source can be found in the Swagger UI under Stream directly, e.g. double stream:

&quot;Stream Double Example

REST Pre-defined Payload​

The data for the Pre-defined Payload Stream needs to be submitted in the Endpoint Group Pre-defined Payload and contain the same identifier combination as the TwinConfiguration (Set the previously, in the configuration section, i.e. defined source identifier value as MachineId and value identifier as SensorId of the json payload). Examples on how to submit data to the REST Source can be found in the Swagger UI under Pre-defined Payload directly, e.g. double stream:

&quot;Stream Double Example