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: pfannenberg-connect-example.yml

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
# ----------------------------------------------------------------------------#
# Commissioning File
# ----------------------------------------------------------------------------#
# Manufacturer: Pfannenberg
# Device: Pfannenberg Connect
# Copyright: Cybus GmbH (2020)
# Contact: support@cybus.io
# ----------------------------------------------------------------------------#
description: >
  Pfannenberg-Connect sample commissioning file

metadata:
  name: Pfannenberg-Connect commissioning file
  icon: https://www.cybus.io/wp-content/uploads/2020/05/IRES-Shopfloor-Analytics-News-Article-780x400.png
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0

parameters:

  agentName:
    type: string
    description: Name of the pfannenberg agent
    default: pfannenberg-edge-mapper

  usbDevice:
    type: string
    description: The USB device where the pfannenberg smart mesh master is connected
    default: /dev/ttyUSB3

  initialReconnectDelay:
    type: integer
    default: 1000

  maxReconnectDelay:
    type: integer
    default: 30000

  factorReconnectDelay:
    type: integer
    default: 2

resources:
  pfannenbergConnection:
    type: Cybus::Connection
    properties:
      agentName: !ref agentName
      protocol: Pfannenberg
      targetState: connected
      connection:
        device: !ref usbDevice
        connectionStrategy:
          initialDelay: !ref initialReconnectDelay
          maxDelay: !ref maxReconnectDelay
          incrementFactor: !ref factorReconnectDelay

  observeSubscription1:
    type: Cybus::Endpoint
    properties:
      agentName: !ref agentName
      protocol: Pfannenberg
      connection: !ref pfannenbergConnection
      subscribe:
        mote: 00170d0000316177
        path: /in/1
        method: observe
        format: dio-bd

  pollSubscription1:
    type: Cybus::Endpoint
    properties:
      agentName: !ref agentName
      protocol: Pfannenberg
      connection: !ref pfannenbergConnection
      subscribe:
        mote: 00170d0000316177
        path: /in/port
        method: poll
        interval: 1000
        format: dio-bd

  writeOperation1:
    type: Cybus::Endpoint
    properties:
      agentName: !ref agentName
      protocol: Pfannenberg
      connection: !ref pfannenbergConnection
      write:
        mote: 00170d0000316177
        path: /out/1

  mapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref observeSubscription1
          publish:
            topic: 'pfannenberg-connect-example/observe-subscription-1'
        - subscribe:
            endpoint: !ref pollSubscription1
          publish:
            topic: 'pfannenberg-connect-example/poll-subscription-1'
        - subscribe:
            topic: 'pfannenberg-connect-example/write-operation-1'
          publish:
            endpoint: !ref writeOperation1

Connection Properties

device (string, required)

The device used to connect

connectionStrategy (object)

If a connection attempt fails, retries will be performed with increasing delay (waiting time) in between. The following parameters control how these delays behave.

Properties of the connectionStrategy object:

initialDelay (integer)

Delay (waiting time) of the first connection retry (in milliseconds). For subsequent retries, the delay will be increased according to the parameter incrementFactor which has a default value of 2.

Default: 1000

Additional restrictions:

  • Minimum: 1000

maxDelay (integer)

Maximum delay (waiting time) to wait until the next retry (in milliseconds). The delay (waiting time) for any subsequent connection retry will not be larger than this value. Must be strictly greater than initialDelay.

Default: 30000

incrementFactor (integer)

The factor used to increment initialDelay up to maxDelay. For example if initialDelay is set to 1000 and maxDelay to 5000 the values for the delay would be 1000, 2000, 4000, 5000.

Default: 2

Additional restrictions:

  • Minimum: 2

Endpoint Properties

method (string, enum)

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 device mapper triggers explicit reads at a defined interval.

This element must be one of the following enum values:

  • observe

  • poll

interval (integer)

The amount of milliseconds between polls

Default: 1000

cronExpression (string)

The Cron expression used to poll the endpoint. (For examples, see: https://github.com/node-cron/node-cron)

Examples: "1,2,4,5 * * * *", "1-5 * * * *", "*/2 * * * *", "* * * January,September Sunday"

path (string)

The path of the node application endpoint to read or write. A list of valid endpoints is available for the specific device. Either path or inputPin should be specified.

Examples: "/in/port", "/in/1"

mote (string, required)

The device mac address. hex encoded

Example: "00170d0000316177"

format (string, enum)

The format of the data received on subscriptions of type observe. 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. It should only be specified for subscribe operations.

This element must be one of the following enum values:

  • raw

  • dio-bd

inputPin (integer)

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. Either inputPin or path should be specified.

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:

1
2
3
4
5
{
  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.