Commit 646bdd0e authored by Micha Mueller's avatar Micha Mueller
Browse files

Update README

parent ad6e8558
......@@ -106,82 +106,125 @@ GET https://localhost:8000/sysfs/freq1/avg?authkey=myToken;interval=15
PUT https://localhost:8000/bacnet/stop?authkey=myToken
```
## <a name="MQTT">MQTT topic</a>
## MQTT topic
For communication between the different DCDB-components (database, dcdbpusher) the [MQTT protocol](https://mqtt.org/) is used. In order to identify each sensor, everyone has to have a unique MQTT topic assigned. A MQTT topic for DCDB consists of exactly 128 bits (= 32 hex characters), not including '/' separators.
For communication between the different DCDB-components (database, dcdbpusher) the [MQTT protocol](https://mqtt.org/) is used. In order to identify each sensor, everyone has to have a unique MQTT topic assigned. A MQTT topic for DCDB consists of exactly 128 bits (= 32 hex characters), not including '/' separators. The topic for a sensor is build by appending up to 4 parts:
1. mqttprefix (e.g. /00112233445566778899AA)
2. mqttpart of entity (if supported by plugin, e.g. /BB)
3. mqttpart of group (e.g. /1122)
4. mqttsuffix (e.g. /3344)
Then the topic for the sensor is /00112233445566778899AA/BB/1122/3344.
# Plugins
The core of dcdbpusher is responsible of collecting all the sensor values and sending them to the database. However, the main functionality of the sensors comes from the various plugins. Every plugin corresponds to a special sensor functionality.
Although every plugin requires different configuration parameters for its sensor functionality, some parameters are required equally for every sensor. The config-files for the plugins can follow two schemes: one where every sensor is defined on his own, and one (e.g. for IPMI and PDU) where sensors are aggregated to a higher level unit. The two possible schemes and uniformly needed sensor parameters shall be explained below. Configuration parameters which are only required specifically for sensors within a plugin are explained in the corresponding [subsections](#IPMI). For every plugin an example configuration file is supplied in the `/config` directory. One should use them as a starting point to write own configuration files.
The core of dcdbpusher is responsible of collecting all the values read by the sensors and sending them to the database. However, the main functionality of the sensors comes from the various plugins. Every plugin corresponds to a special sensor functionality.
All the different plugins share some same general principles in common regarding the sensor structure and configuration. Those principles should also be obeyed when [writing own plugins](#WOP).
1. There are three hierarchical levels (from bottom up):
1.1 Sensors
1.2 Groups
1.3 Entities (optional)
2. There are no sensors on its own. Every sensor belongs to a group.
3. Multiple groups may or may not be aggregated by an entity. Entities can be optionally used by the plugin developer to aggregate groups which belong together, e.g. because they all query the same host.
4. Every hierarchical level is associated with some attributes. In the following are some hints on how one should decide which attributes are associated with which level. Also for every level the common base attributes are listed (with explanation), which are specified independently of a plugin:
4.1 Entities (if present) hold all attributes which are required to query the represented entity or all its associated groups have in common. As an entity is optional there are no mandatory base attributes. However, here are some examples which could be entity attributes: mqttPart, protocol-version, host address and port.
4.2 Groups hold all attributes which multiple sensors belonging to it share in common. Common for all plugins are:
* interval (Time in [ms] between two consecutive sensor reads. Default is 1000[ms] = 1[s])
* minValues (Minimum number of sensor reads the sensors in a group should gather before they are sent together to the database. Useful to reduce MQTT-overhead. Default is 1 (every sensor value is sent on its own))
* mqttPart (Part for the [mqtt-topic](#MQTT) all sensors in this group should share in common)
* default (One can define the name of a template sensor (see below) which values and sensors should be used as default)
4.1 Sensors hold only those attributes which are necessary to uniquely identify the target sensor. Common base attributes:
* mqttsuffix (to make its [mqtt-topic](#MQTT) unique)
5. Be aware that naming of sensor/group/entity is not fixed. A plugin developer can name them as he likes, e.g. counter/multicounter/host.
6. It is possible to define template groups or entities in the config file, but not template sensors (as a sensor should only consists of attributs which make him unique this would not be too useful). To specify a template group/entity simply prefix its definition with `template_` (see the example below). You can reference them later by using the `default` attribute. A template entity can consist of groups and these in turn can consist of sensors. When using a template, all of its attribute values are copied to the actual sensor. Copied attributes can be overwritten in the actual entity/sensor (some of them even should be overwritten, e.g. the mqttPart). However, groups/sensors associated with a template are copied to the actual entity/group and can NOT be overwritten. One can specify further groups/sensors which are then added to those copied from the template. Template entitys/groups itself or sensors within them are never used in live operation of the plugin. They are purely cosmetic for convenient configuration.
In the following two abstract config files are shown to visualize the structure, one with the optional entity level and one without. A real example configuration file for every plugin should be provided in the `/config` directory. One should use them as a starting point to write own configuration files.
```
Standalone sensors: | Sensors divided into units:
------------------------------------------------+------------------------------------------------
|
global { |global {
mqttprefix /00112233445566778899AABB0000 | mqttprefix /00112233445566778899AABB0000
cacheInterval 120 | cacheInterval 120
} |}
|
SensorTemplate { |SensorTemplate {
sensor name { | sensor name {
... | ...
} | }
|
... | ...
} |}
|
sensors { |Units {
sensor name1 { | sensorUnit u1 {
default A | unitParams ?
interval 1000 |
mqttsuffix 0000 | sensors {
minValues 1 | sensor name1 {
params ? | default A
} | interval 1000
| mqttsuffix 000
sensor name2 { | minValues 1
... | params ?
} | }
|
... | sensor name2 {
} | ...
| }
| ...
| }
| }
|
| sensorUnit u2 {
| ...
| }
|
| ...
|}
Without entity:
------------------------------------------------
global {
mqttprefix /00112233445566778899AABB0000
cacheInterval 120
...
}
template_group temp1 { ;template group named temp1 (is not used in live operation)
interval 1000 ;While it is possible define entities/groups/sensors without
minValues 3 ;name it is strictly disregarded. Naming entities/groups/sensors
mqttPart AA ;simplifies debugging and especially enables one to reference
;templates later on. Also names should be always unique.
sensor s1 {
mqttsuffix 01
... ;usually the sensor would require additional attributes
}
sensor s2 {
mqttsuffix 02
...
}
}
group g1 {
default temp1 ;use temp1 as template group
mqttPart BB ;overwrite the mqttPart from temp1, to avoid identical
;mqtt-topics if another group uses the same template
sensor s3 { ;g1 has now 3 sensors: s1, s2 (both taken over from temp1)
mqttsuffix 03 ;and s3
...
}
}
group g2 { ;g2 consists of only one sensor (s21) and uses
sensor s21 { ;for every attribute the default value
mqttsuffix 0000 ;by using a longer mqttsuffix we do not need a
... ;group mqtt-part
}
}
...
```
Explanation of the values:
| Value | Explanation |
|:----- |:----------- |
| global | Here one can overwrite the global values defined in `global.conf`. The overwritten values are only used in the scope of the specific plugin. Overwriting of global values is completely optional. However, even if no global values are overwritten at least the `global{}` struct should be present.
| mqttprefix | Define separate MQTT prefix for this plugin.
| cacheInterval | Overwrite global caching interval with plugin specific value.
| | |
| SensorTemplate | Define template sensors to be used later in the configuration. This feature is mainly for convenience reasons. One is not obligated to define any template sensors. However it is required to at least define an empty SensorTemplate {} structure.
| sensor name | Every template sensor needs a name for future reference. A template sensor can define every value (including values specific to a plugin) a normal sensor can (see below).
| | |
| Units | Section to define different units where sensors may be aggregated to. Not every plugin makes use of this subdivision. Where it is used it the Units may be named different.
| sensorUnit u1 | If the unit subdivision is used, subunits need to be used and also need to be named.
| unitParams | One may be able to define special parameters specific to the subunits. They should be explained with the corresponding plugin if it makes use of subunits.
| | |
| sensors | Define in this section the sensors for the plugin/subunit
| sensor name | Every sensor needs a unique name
| default | Mention here the name of the template sensor to be used. The sensor will be initialized with the exact same values as the template sensor. This field can be left out if all required values for the sensor are defined manually.
| interval | Time in [ms] between two consecutive sensor reads. Default is 1000[ms] = 1[s]
| mqttsuffix | Suffix which is appended to the MQTT-prefix. Together with the prefix this should be a globally unique MQTT-topic for every sensor.
| minValues | Minimum number of sensor reads the sensor should gather before they are sent together to the database. Useful to reduce MQTT-overhead. Default is 1 (every sensor value is sent on his own).
| params | Every plugin requires additional configuration parameters. Those may be unique to every plugin and are explained in the corresponding subsections below.
```
With entity:
------------------------------------------------
global {
...
}
template_entity temp1 { ;template entity which is not used in live operation
... ;here go entity attributes
group g1 {
interval 1000
minValues 3
mqttPart AA
sensor s1 {
mqttsuffix 01
... ;usually the sensor would require additional attributes
}
sensor s2 {
mqttsuffix 02
...
}
}
}
entity ent1 {
default temp1 ;use temp1 as template entity
group g2 { ;ent1 has now two groups (g1 and g2) with a total of
sensor s21 { ;3 sensors (s1, s2, s21)
mqttsuffix 0000
...
}
}
}
...
```
## <a name="IPMI">IPMI</a>
......@@ -195,7 +238,6 @@ Explanation of the values specific for the IPMI plugin:
| retransmissiontimeout | Retransmission timeout value for the IPMI-connection
| username | For the remote IPMI-connection login credentials are required
| password | For the remote IPMI-connection login credentials are required
| mqttprefix | One can define a different MQTT-prefix per host
| cmd | One can define a raw IPMI-command (in hex-notation) to be sent. In this case also the start and stop fields for the response have to be defined. Alternatively, one can define the record-ID of the sensor (see below).
| start | Required if raw command is sent
| stop | Required if raw command is sent
......@@ -349,7 +391,6 @@ Explanation of the values specific for the BACnet plugin:
| templates | One can define template properties in this section for convenience.
| factor | Described in the section for the [IPMI-plugin](#IPMI).
| devices | Starts the part in the config file where the actual BACnet devices are configured. A BACnet device consists of multiple nested parts: device > objects > properties.
| mqttPart | One can define a partial MQTT topic on each nesting level, which will be appended to the MQTT prefix. Together with the mqttsuffix of a property this will make up the whole MQTT topic of a property (aka sensor). MQTT topic = mqttPrefix + mqttPart (device) + mqttPart (object) + mqttsuffix.
| instance (device) | Instance of the BACnet-device.
| type | Type of the object within the device.
| instance (object) | Instance of the object within the device.
......@@ -400,11 +441,10 @@ Possible values for cntData:
* linkDowned
* uncorrectableErrors
## Writing own plugins
## <a name="WOP">Writing own plugins</a>
Try out the `pluginGenerator/generatePlugin.sh` script!
TODO!
#### TODOS
* explain sensor group concept
* rework pdu plugin: should be more generic XML plugin
* explain special cases in the code for every plugin?
* more about mqtt-topic
\ No newline at end of file
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment