fty-sensor-gpio

fty-sensor-gpio is an agent to manage GPI sensors and GPO devices. It is able to read status of any kind of GPIO devices or set (enable / disable) any GPO.

GPIO devices are basic dry-contact, which are either 'opened' or 'closed', to indicate a status or enable / disable a device.

How to build

To build fty-sensor-gpio project run:

mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=usr -DBUILD_TESTING=On ..
make
sudo make install

Optionally, to run fty-outage tests run:

make test

How to run

To run fty-sensor-gpio project:

from within the source tree, run:

./src/fty-sensor-gpio

For the other options available, refer to the manual page of fty-sensor-gpio

from an installed base, using systemd, run:

systemctl start fty-sensor-gpio

Configuration file and request

To configure fty-sensor-gpio, a configuration file exists: fty-sensor-gpio.cfg

Beside from the standard configuration directives, under the server and malamute sections, hardware capabilities are requested to the fty-info agents, to adapt to the behavior of fty-sensor-gpio, using:

HW_CAP/'msg-correlation-id'/gpi
HW_CAP/'msg-correlation-id'/gpo

This answer will allow to get:

gpi_count: (mandatory) the number of GPI (10 on IPC3000)
gpo_count: (mandatory) the number of GPO (5 on IPC3000)
gpio_base_address: (optional) the target address of the GPIO chipset (488 for the gpiochip488 on IPC3000)
gpo_offset: (optional) the offset to apply to access GPO pins, from base chipset address. 15 on IPC3000, so GPO pins have +15 offset, i.e. GPO 1 is pin 16, ...
gpi_offset: (optional) the offset to apply to access GPI pins, from base chipset address. -1 on IPC3000, so GPI pins have -1 offset, i.e. GPI 1 is pin 0, ...

Commissioning using CSV file

It is possible to declare GPIO sensors through the CSV file. The following fields and extended attributes are available:

name (mandatory)
type (mandatory): set to 'device'
sub_type (mandatory): set to 'sensorgpio'
parent_name.1 (optional): refer to the IPC to which the sensor is connected.
status (optional): is the standard status 'active' or 'inactive'
priority (optional): is the standard priority, from 'P1' to 'P5'
model (mandatory): is the part number of the GPIO sensor, use for naming the template files
port (mandatory): is the GPI or GPO pin number to which the sensor is connected to. The pin number of the GPIO is then computed based on this number and the configured 'gpi_offset' and 'gpo_offset'.
normal_state (optional): is the status of the sensor under nominal conditions. Possible values are 'opened' or 'closed'. When not provided, the value from the template file is used. Otherwise, the provided value takes precedence.
logical_asset (optional): is the deployment location of the sensor. For example, a door contact sensor can be located on the door of a rack or room. Hence, the value will be the name of this rack or room.
gpo_powersource (optional): some GPI sensors need an external power supply. IPC itself can provide 12V power through its GPO. In such cases, use the present field to indicate which GPO number is used to power a GPI.

Example of entries:

name,type,sub_type,parent_name.1,status,priority,model,port,normal_state,logical_asset,gpo_powersource
GPIO-Sensor-Door1,device,sensorgpio,IPC1,active,P1,DCS001,1,opened,Rack1,
GPIO-Sensor-Smoke1,device,sensorgpio,IPC1,active,P1,DCS001,1,opened,Room1,1
GPIO-Beacon1,device,sensorgpio,IPC1,active,P1,GPOGEN,2,,Room1,

In the above example, we have:

One door contact sensor, 'GPIO-Sensor-Door1', connected to the first GPI of the IPC, and located on the door of 'Rack1',
One smoke detection sensor, 'GPIO-Sensor-Smoke1', connected to the second GPI of the IPC, powered by the first GPO (gpo_powersource = 1), and located in 'Room1',
One beacon, 'GPIO-Beacon1', connected to the second GPO of the IPC, and located in 'Room1'.

Architecture

Overview

fty-sensor-gpio is composed of 3 actors:

assets actor: requests all sensorgpio to the assets agent, and then listen to ASSETS stream (for further addition / deletion / update, to find GPIO sensors and configure the agent. These information are then used by the server.
server actor: handles GPI polling and related metrics publication. This actor also handles mailbox requests, to serve the manifest of supported GPIO devices, create additional template files or act on GPO devices upon command reception
alerts are managed by fty-alert-flexible

Template files

Template files describe a GPIO sensor, and provide default values (such as 'normal-state') in case the user does not provide it through the commissioning.

Warning: Template files are mandatory! If there is no template file for a commissioned sensor, this sensor will not be monitored!

Template files are provided in the 'src/selftest-ro/data/' directory of the source tree, and installed by default to '/usr/share/fty-sensor-gpio/data/'.

Template files are named using the 'part-number' field, with the '.tpl' (template) file extension, and have the following format:

manufacturer   = <value>
part-number    = <value>
type           = <value>
normal-state   = <value>
gpx-direction  = <value>
power-source   = <value>
alarm-severity = <value>
alarm-message  = <value>

For example:

manufacturer   = Eaton
part-number    = DCS001
type           = door-contact-sensor
normal-state   = closed
gpx-direction  = GPI
power-source   = external
alarm-severity = WARNING
alarm-message  = Door has been $status

'power-source' allows to specify if a sensor is:

self-powered, through the GPI itself (value: 'internal'),
external powered, through another GPO or a pure external source (value: 'external'). In case where a GPO is powering a GPI, refer to the Commissioning chapter above, and look at "gpo_powersource".

'alarm-message' can be adapted at runtime through the use of some variables, to adapt the alert message:

"$status": is replaced by the pattern "opened" or "closed"
"$device_name": is replaced by the sensor name which has generated the alert
"$location": is replaced by the sensor location

Protocols

Published metrics

Metrics are published on the '_METRICS_SENSOR' stream.

For example:

stream=_METRICS_SENSOR
sender=fty-sensor-gpio
subject=status.GPI2@sensorgpio-90
D: 13-01-28 10:22:53 FTY_PROTO_METRIC:
D: 13-01-28 10:22:53     aux=
D: 13-01-28 10:22:53         port=GPI2
D: 13-01-28 10:22:53     time=1359368573
D: 13-01-28 10:22:53     ttl=300
D: 13-01-28 10:22:53     type='status.GPI2'
D: 13-01-28 10:22:53     name='sensor-90'
D: 13-01-28 10:22:53     value='opened'
D: 13-01-28 10:22:53     unit=''

Published alerts

Alerts are published on the '_ALERTS_SYS' stream.

Alarm messages:

When new sensor is configured, fty-alert-engine configures rule which is used by fty-alert-flexible to evaluate sensor state.
Rules contain lua functions which are executed everytime metric from the sensor is received.
When value in metric (current sensor state) is not equal to desired state alert is generated by fty-alert-flexible.
Each type of gpio sensor has its own rule.

Example of alert message:

stream=_ALERTS_SYS
sender=fty-alert-flexible
subject=door-contact.state-change@sensorgpio-19/WARNING@sensorgpio-19
D: 17-09-04 08:23:49 FTY_PROTO_ALERT:
D: 17-09-04 08:23:49     aux=
D: 17-09-04 08:23:49     time=1504513429
D: 17-09-04 08:23:49     ttl=750
D: 17-09-04 08:23:49     rule='door-contact.state-change@sensorgpio-19'
D: 17-09-04 08:23:49     name='sensorgpio-19'
D: 17-09-04 08:23:49     state='ACTIVE'
D: 17-09-04 08:23:49     severity='WARNING'
D: 17-09-04 08:23:49     description='Door to Rack01 is opened. Reported '
D: 17-09-04 08:23:49     action='EMAIL'

Mailbox requests

It is possible to request the agent GPIO for:

getting the manifest of one, several or all supported GPIO devices, in simple or detailed format,
creating a new template file, to add support for a new GPIO sensor,
acting on GPO devices, to activate or de-activate,
storing GPO in the agent cache.

Action on GPO sensors

The USER peer sends the following messages using MAILBOX SEND to FTY-SENSOR-GPIO-AGENT ("fty-sensor-gpio") peer:

GPO_INTERACTION/correlation_ID/sensor/action - apply 'action' (open | close) on 'sensor' (asset or ext name)

where

'/' indicates a multipart string message
'correlation_ID' is a zuuid identifier provided by the caller
'sensor' MUST be the sensor asset name or ext name
'action' MUST be one of
- [ enable | enabled | open | opened | high ]
- [ disable | disabled | close | closed | low ]
subject of the message MUST be "GPO_INTERACTION".

The FTY-SENSOR-GPIO-AGENT peer MUST respond with one of the messages back to USER peer using MAILBOX SEND.

correlation_ID/OK
correlation_ID/ERROR/reason

where

'/' indicates a multipart frame message
'correlation ID' is a zuuid identifier provided by the caller
'reason' is string detailing reason for error. Possible values are: ASSET_NOT_FOUND / SET_VALUE_FAILED / UNKNOWN_VALUE / BAD_COMMAND / ACTION_NOT_APPLICABLE.

Detailed manifest of supported sensors

The USER peer sends the following messages using MAILBOX SEND to FTY-SENSOR-GPIO-AGENT ("fty-sensor-gpio") peer:

GPIO_MANIFEST/correlation_ID/sensor_1_part_number/.../sensor_N_part_number - get information on sensor(s)

where

'/' indicates a multipart string message
'correlation_ID' is a zuuid identifier provided by the caller
'sensor_x_part_number' is the part number of the sensor(s), to get information on. When empty, the agent returns information on all supported sensors
subject of the message MUST be "GPIO_MANIFEST".

The FTY-SENSOR-GPIO-AGENT peer MUST respond with one of the messages back to USER peer using MAILBOX SEND.

correlation_ID/OK/sensor_1_description/.../sensor_N_description = non-empty
correlation_ID/ERROR/reason

where

'/' indicates a multipart frame message
'correlation_ID' is the zuuid identifier provided by the caller to match our answer
'reason' is string detailing reason for error. Possible values are: ASSET_NOT_FOUND / BAD_COMMAND
'sensor_x_description' is a string with details on the sensor with the format: sensor_partnumber/manufacturer/type/normal_state/gpx_direction/power_source/alarm_severity/alarm_message

Summary manifest of supported sensors

The USER peer sends the following messages using MAILBOX SEND to FTY-SENSOR-GPIO-AGENT ("fty-sensor-gpio") peer:

GPIO_MANIFEST_SUMMARY/correlation_ID - get the list of supported sensors

where

'/' indicates a multipart string message
'correlation_ID' is a zuuid identifier provided by the caller
subject of the message MUST be "GPIO_MANIFEST_SUMMARY"

The FTY-SENSOR-GPIO-AGENT peer MUST respond with one of the messages back to USER peer using MAILBOX SEND.

correlation_ID/OK/sensor_1_description/.../sensor_N_description = non-empty
correlation_ID/ERROR/reason

where

'/' indicates a multipart frame message
'correlation_ID' is the zuuid identifier provided by the caller to match our answer
'reason' is string detailing reason for error. Possible values are: ASSET_NOT_FOUND / BAD_COMMAND
'sensor_x_description' is a string with details on the sensor with the format: sensor_partnumber/manufacturer

Create a new sensor template file

The USER peer sends the following messages using MAILBOX SEND to FTY-SENSOR-GPIO-AGENT ("fty-sensor-gpio") peer:

GPIO_TEMPLATE_ADD/correlation_ID/sensor_description - request the creation of a sensor template file

where

'/' indicates a multipart frame message
'correlation_ID' is a zuuid identifier provided by the caller
'sensor_description' is a string with details on the sensor with the format: sensor_partnumber/manufacturer/type/normal_state/gpx_direction/power_source/alarm_severity/alarm_message
subject of the message MUST be "GPIO_TEMPLATE_ADD".

The FTY-SENSOR-GPIO-AGENT peer MUST respond with one of the messages back to USER peer using MAILBOX SEND.

correlation_ID/OK
correlation_ID/ERROR/reason

where

'/' indicates a multipart frame message
'correlation_ID' is the zuuid identifier provided by the caller to match our answer
'reason' is string detailing reason for error. Possible values are: ...

Store GPO in the agent cache

The USER peer sends the following messages using MAILBOX SEND to FTY-SENSOR-GPIO-AGENT ("fty-sensor-gpio") peer:

GPOSTATE/asset_name/gpo_number/default_state - store GPO with this properties into cache

where

'/' indicates a multipart frame message
'asset_name' is internal name of the GPO
'gpo_number' is IPC port where the GPO is connected
'default_state' is default state of the GPO
subject of the message MUST be "GPOSTATE".

The FTY-SENSOR-GPIO-AGENT peer MUST NOT respond.

42ity / fty-sensor-gpio

readme

fty-sensor-gpio

How to build

How to run

Configuration file and request

Commissioning using CSV file

Architecture

Overview

Template files

Protocols

Published metrics

Published alerts

Mailbox requests

Action on GPO sensors

Detailed manifest of supported sensors

Summary manifest of supported sensors

Create a new sensor template file

Store GPO in the agent cache