.. _user/protocols/pfannenberg-connect:

***********************************
Pfannenberg Connect
***********************************

Overview
========

The Pfannenberg Connect System is a wireless sensor mesh. The system consists
of a single access point (Manager) and multiple (hundreds of) sensor nodes providing
various IO capabilities.

The Cybus Protocol Mapper integration of Pfannenberg Connect provides an API
using MQTT/JSON to the application layer data and events of a particular node like GPIO
status, sensor reads, etc.

At the same time, the Cybus Device Mapper automates the security management for the
network by synchronizing the mesh ACLs with configured node MAC Addresses from the
commissioning files.

Commissioning file specifics
============================

The connection part of the commissioning file always references a particular node
connected to a particular manager.
As the manager is connected through a USB interface, the USB Device descriptor is
the most important configuration property of the connection.

A typical commissioning file for the Pfannenberg Connect protocol looks like this:

Click here to download: :download:`pfannenberg-connect-example.yml`

.. literalinclude:: pfannenberg-connect-example.yml
  :language: yaml
  :linenos:

.. _user/protocols/pfannenberg_connection:

.. include:: ../protocolSchemas/PfannenbergConnection.rst

.. _user/protocols/pfannenberg_endpoint:

.. include:: ../protocolSchemas/PfannenbergEndpoint.rst

Mapping Fields
--------------

  path
    the path of the node application endpoint to read or write. A list of valid endpoints is available
    for the specific device.

  inputPin
    special field for addressing pins on an IO Connect module. Pins have a number from 1 to 8. It is recommended
    to use inputPin over path because this selects a more efficient interrogation strategy.

  method
    may be either `observe` or `poll`. In `observe` mode, data updates are sent asynchronously by the node
    e.g. when values change or at a fixed interval. In `poll` mode, the protocol mapper triggers explicit
    reads at a defined interval.

  interval
    only required in `poll` mode.

  format
    only available values currently are `raw` and `dio-bd` (Digital IO with blink detection). The latter maps
    the raw received data to a string `on`, `off`, `blink` or `err`. In `raw` mode, a BASE64 encoded binary value
    is returned.

Received data
-------------

The response message on any `read` endpoint has the following format, where
`timestamp` is the unix timestamp, `id` is the (optional) correlation id that
can be included in the request, and `value` is the actual result:

.. code-block:: javascript
  :linenos:

  {
    timestamp: <unix timestamp in ms>,
    id: <value as given in input request message>,
    value: <depends on format>
  }

For `write` endpoints, there is no response message.