Agents

Agents are components of the Connectware that are not running with the central installation but can be deployed and started individually. They solve the requirement for “computing on the edge”, i.e. they are bringing code close to the hardware and allow data-processing at a very early stage of the pipeline.

For agents to work only a single pre-condition must be met: agents must be in a network that allows them to reach the (central) Connectware.

Note

Agents solely use MQTT for communication and hence act as network clients. They do not require any inbound traffic and no special network configuration is needed.

Depending on the use-case the agent itself can be deployed as docker-container or “natively” in form of a Windows or Linux system service.

As “native” deployments are always highly customized, the following documentation will focus on the docker-based agent setup.

Installation

To run the agent, only a single docker container has to be started. The container image to be used is identical to the Connectware’s protocol-mapper image.

Starting the container can be accomplished by executing a docker run command in a terminal or by using docker-compose with a corresponding docker-compose.yml file.

In either case the agent must be configured through environment variables made available to the container.

The following environment variables are required:

  • CYBUS_AGENT_MODE=distributed (switches protocol-mapper to run in agent mode)

  • CYBUS_AGENT_NAME=<agentName> (unique name identifying this agent instance)

  • CYBUS_MQTT_HOST=<connectwareHost> (the IP/hostname of the connectwareHost)

The following environment variables are optional:

  • CYBUS_MQTT_USERNAME=<userName> (default is <agentName>)

  • CYBUS_MQTT_SCHEME=<scheme> (mqtts or mqtt, default: mqtt)

  • CYBUS_MQTT_PORT=<port> (default: 1883)

It is strongly recommended to persist the data (credentials and resources) of the agent, guaranteeing unsupervised and automatic availability (even after power cycles). To add this persistency, use a docker volume mount against the container-internal /data directory. The agent will automatically store the credentials on that volume and re-use them on subsequent start-up.

Example 1 (docker-compose)

version: '2.0'
services:
  protocol-mapper-agent:
    image: protocol-mapper
    environment:
      CYBUS_AGENT_MODE: distributed
      CYBUS_AGENT_NAME: myAgent
      CYBUS_MQTT_HOST: 10.11.12.13
    volumes:
      - protocol-mapper-agent:/data
    restart: unless-stopped
    network_mode: host
volumes:
  protocol-mapper-agent:

To start, create a new directory (e.g. myAgent). Inside, create a new file called docker-compose.yml with the above content and finally run:

docker-compose up -d

Example 2 (docker run)

docker run --rm --net=host -v /tmp/cybus:/data -e CYBUS_MQTT_HOST=10.11.12.13 -e CYBUS_AGENT_MODE=distributed -e CYBUS_AGENT_NAME=myAgent registry.cybus.io/cybus/protocol-mapper:1.0.0

This will start an agent named myAgent that persists data to /tmp/cybus on the host OS.

Registration

Registration describes the process of authorizing an agent to connect to the Connectware.

In the recommended setup where the agent has persistency enabled (see above), this step is needed only once upon initial deployment. In other words, this registration is needed only in one of these cases:

  • the agent is started the very first time, or

  • the persisted credentials got deleted, or

  • the agent could not login to the Connectware with its cached credentials.

In all other cases the registration process is not needed and the agent will seamlessly start working with the persisted credential from the storage volume.

In the initial deployment, the registration is performed as follows: First the agent container must be started. Then, the console log output of the container should look as follows:

{"level":30,"time":1590665714502,"msg":"Starting in distributed (edge) mode","pid":6,"hostname":"someHost","v":1}
{"level":30,"time":1590665714568,"msg":"Generating new credentials and asking for Connectware registration...","pid":6,"hostname":"someHost","v":1}
{"level":30,"time":1590665714568,"msg":"The registration process must be finished using the web-interface.","pid":6,"hostname":"someHost","v":1}
{"level":30,"time":1590665714568,"msg":"Navigate to \"User Management -> Client Registry\", click unlock and authorize this client.","pid":6,"hostname":"someHost","v":1}
{"level":30,"time":1590665714568,"msg":"Pairing ID (should match in UI): a82123","pid":6,"hostname":"someHost","v":1}

To finalize the registration process, log into the Connectware Admin-UI and authorize the client as described in the chapter Client Registry.

Note

Besides the agent name you can use the Pairing ID to verify that you are granting access to the correct agent instance.

Usage

Agents are able to provide two resource types:

The endpoint resource can also use the rules property to enable direct data-manipulation on the edge using the rule engine (edge processing).

In order to start such resources on the agent, you must set the agentName property at each of those resources in your commissioning file.

Important

The value of the agentName property (as available for Cybus::Connection and Cybus::Endpoint resources) must match the value of the CYBUS_AGENT_NAME environment variable used during agent startup.

You can find an example commissioning file here.

Monitoring

At any time you can monitor the connectivity status of your agents by navigating to System > Agents in the UI.

../_images/agents.png