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
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"
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.