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)

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

Note: If multiple agents will be run on the same computer, each agent must use its own volume mount, as otherwise agents would overwrite each other’s data.

It may also be useful to set the hostname property of the docker container to the local host’s hostname, because this name will be displayed in the Admin-UI overview page. If it is not set, the local docker container ID will be displayed instead (e.g. d172c8c3667b), which might look rather confusing in this overview page. Depending on the operating system, the suitable value for the hostname may be available as an environment variable ${HOSTNAME} or it must be specified manually, as noted in the example below.

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
    hostname: <some-suitable-hostname>
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

Again it is noted that if multiple agents should run on the same computer, each agent must have defined its own docker volume, otherwise different agents would overwrite each other’s persisted data.

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 --hostname ${HOSTNAME} 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. To be precise, 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. (Again note: If multiple agents should run on the same computer, each agent must use its own volume mount, as otherwise agents would overwrite each other’s credentials.)

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