.. _user/examples/modbus/baz-agent-mode:

**************************************
"Bearbeitungszentrum BAZ" - Agent Mode
**************************************

This example shows an entire BAZ setup expressed within a single commissioning
file, using explicit topics and involving an agent for providing the connection
and endpoint resources.

The name of the :ref:`agent <user/agents>` must be specified in the `agentName`
parameter, for example `connectware-agent` or whatever other name has been given
to the agent instance.

Download: :download:`bazAgentMode.yml`

.. note:: |registry_images_license_note|

.. literalinclude:: bazAgentMode.yml
  :language: yaml
  :linenos:

How to deploy the agent
-----------------------

To run the above example, you must also deploy and run an agent, which is a
container using the Connectware's image `protocol-mapper` with some special
environment variables (see also :ref:`Agent Installation
<user/agents/installation>`).

The first thing you need to set is the image and image tag (i.e. version) you
are going to use. The agent's container must use the protocol-mapper image of
the exact same version as the Connectware, otherwise the system may run into
unspecified behaviour. For the subsequent command the image tag (version) is
stored as IMAGE_TAG= |release|

Using the IMAGE_TAG environment variable, the following command will run the
agent directly (but with the comment lines removed):

.. code-block:: bash

  # The docker run command
  docker run --rm \
      # Attach a volume so the agent can store data across restarts
    -v /tmp/cybus:/data \
      # Set the name of the agent. This must match the agentName used in the commissioning file.
    -e CYBUS_AGENT_NAME=connectware-agent \
      # The IP address where the Connectware is running.
    -e CYBUS_MQTT_HOST=10.11.12.13 \
      # Make it run as an agent
    -e CYBUS_AGENT_MODE=distributed \
      # Some suitable hostname of the container.
    --hostname=${HOSTNAME} \
      # Run it in host mode networking
    --net=host \
      # The image to use
    registry.cybus.io/cybus/protocol-mapper:${IMAGE_TAG}

Then, complete the set up by registering the new agent’s user in the Connectware
using the “Client Registry” process, see :ref:`Agent Registration
<user/agents/registration>` and :ref:`Client Registry <user/client-registry>`

Alternative ways to run the agent can be found on :ref:`Agent Installation
<user/agents/installation>`.