13.1. Analog and digital I/O Overview

13.1. Analog and digital I/O Overview
	Chapter 13. IOBOX

From release 7-5-0 added a new web application that permits the handling of analog and digital I/O made available with the following hardware:
- MFIO embedded in Microabilis-C3;
- IOBOX.
  The application permits:
- Use of .jpg, .png, .gif, .bmp images as background.
- A visual creation of maps (up to 10) and the placement on the map of indicators and actuators.
- Drive toggle or pulse output just by clicking on the icon.
- "By user" access rights to the maps, and different rights for design and for control.
  The urls used by IO are:
  - /sys/io : main page;
  - /sys/io/control/map<X>: control maps, where <X> is the map number between 1 and 10;
  - /sys/io/design/map<X>: design maps, where <X> is the map number between 1 and 10.
- Real-time indication of states and values of the monitored I/O.
- Configurable labels.
- Javascript required (recent version of Firefox, Chrome, Safari, Opera, IE 7/8/9).

See below a couple of example screenshots.

Figure 13.1. I/O Maps index

Figure 13.2. I/O Map1 control

Software Resource Gpio

From release 7-5-0 added handling of analog inputs values.
Analog signals are digitized by ADC converters present in the interface hardware. The numerical value is read by Abilis and converted to the measure unit by means of the analog input configuration parameters:
UNIT
Measure unit.
MIN
The lowest value, in measure unit, to be assigned to DAC value 0.
MAX
The highest value, in measure unit, to be assigned to DAC value 1023.
UPD
When monitored via GPIOPC protocol this is the difference that must occur between current value and previously read value in order to deliver the new value to the GPIOPC client.
When analog inputs are monitored via GPIOPC two more parameters are involved:
UPD
Difference that must occur between current value and previously read value in order to deliver the new value to the GPIOPC client.
POOL
The interval between values read.

Added handling of analog inputs alarms.
The measured analog values are verified against thresholds in order to generate LOW and HIGH alarms.
Analog alarms parameters:
UNIT
Measure unit.
ALM-LO
The value, in measure unit, below which the ALARM LOW is triggered.
ALM-HI
The value, in measure unit, above which the ALARM HIGH is triggered.
HYST
Hysteresis for ALM-LO and ALM-HI for returning to NORMAL state.
Added PULSE mode for digital output.
Three parameters have been added:
MODE
To choose between VALUE operational mode and PULSE.
PULSE-T
The duration of the pulse, in milliseconds.
PULSE-GAP
The minimal guaranteed pause between two pulses, in milliseconds.

Configuration example.

[13:30:35] ABILIS_CPX:d p gpio

RES:Gpio-1 - Not Saved (SAVE CONF), Not Refreshed (INIT) ----------------------
       ------------------------------------------------------------------------
Run    DESCR:
       LOG:NO               ACT:YES              LIVE-EXPIRY:10
       -------+-------------------- Digital Input lines -----------------------
       D-IN:  | [DESCR:]
       -------+----------------------------------------------------------------
       1      | Input 1
       2      | Input 2
       3      | Input 3
       4      | Input 4
       5      | Input 5
       6      | Input 6
       7      | Input 7
       8      | Input 8
       -------+-------------------- Digital Output lines ----------------------
       D-OUT: | [DESCR:]
              | MODE:    PULSE-T:    PULSE-GAP:
       -------+----------------------------------------------------------------
       1      | Output 1
       2      | Output 2
       3      | Output 3
       4      | Output 4
              | PULSE    500          250
       -------+-------------------- Analog Input lines ------------------------
       A-IN:  | [DESCR:]
              | UNIT:    MIN:    MAX:    ALM-LO: ALM-HI: HYST:  UPD:    POLL:
       -------+----------------------------------------------------------------
       1      | Analog 2
              | C        20      21      20      21      5.0     1.0     1.0
       2      | C        -10     40      0.0     40      5.0     1.0     1.0
       ------------------------------------------------------------------------
       
[13:30:36] ABILIS_CPX:d d gpio

RES:Gpio-1 --------------------------------------------------------------------
STATE:UP             USB-STATE:CONNECTED
       - Digital Input Lines State --------------------------------------------
        1..16| off off off off off off off off .   .   .   .   .   .   .   .
       17..32| .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .
       33..48| .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .
       49..64| .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .
       ------------------------------------------------------------------------
       - Digital Output Lines State -------------------------------------------
        1..16| off off off off .   .   .   .   .   .   .   .   .   .   .   .
       17..32| .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .
       33..48| .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .
       49..64| .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .
       ------------------------------------------------------------------------
       - Analog Input Lines ---------------------------------------------------
             | State  Value   Unit     ADC    | State  Value   Unit     ADC
------+--------------------------------+--------------------------------
        1.. 2| LOW    20      C        1      | NORMAL 14      C        495
        3.. 4| .      .       .        .      | .      .       .        .
        5.. 6| .      .       .        .      | .      .       .        .
        7.. 8| .      .       .        .      | .      .       .        .
        9..10| .      .       .        .      | .      .       .        .
       11..12| .      .       .        .      | .      .       .        .
       13..14| .      .       .        .      | .      .       .        .
       15..16| .      .       .        .      | .      .       .        .
       ------------------------------------------------------------------------

	Important
	The D P GPIO command shows only the lines which have been configured with a description or that have the parameters different from the default. To enforce the view of all theoretically possible 64 digital inputs, 64 digital outputs, 16 analog inputs, use D PE GPIO command.

Software Resource Mfio (Microabilis-C3)

From release 7-5-0 added PULSE mode for digital output.
Three parameters have been added:
MODE
To choose between VALUE operational mode and PULSE.
PULSE-T
The duration of the pulse, in milliseconds.
PULSE-GAP
The minimal guaranteed pause between two pulses, in milliseconds.

13.1.1. Physical connections

The IOBOX provides 8 digital inputs, 4 digital output and 2 analog inputs.

The MFIO embedded in Microabilis-C3 provides 7 digital Inputs and 7 Digital Outputs.

13.1.2. Activating GPIO device and GPIOPC resource

Add the GPIO device and GPIOPC resource with the following commands:

[11:43:32] ABILIS_CPX:a dev:gpio-1

COMMAND EXECUTED

[11:43:33] ABILIS_CPX:a res:gpiopc-1

	Caution
	Remember to save the configuration using save conf and an Abilis restart are required (i.e. With warm start command).

The GPIO and GPIOPC resources must be activated with the commands:

[09:43:22] ABILIS_CPX:s p gpiopc-1 act:yes

COMMAND EXECUTED

[09:52:19] ABILIS_CPX:d p gpiopc

RES:GpioPc --------------------------------------------------------------------
Run    DESCR:General_Purpose_I/O_Panel_Collector
       LOG:NO        ACT:YES  maxclients:10   XML-TOUT:60    XML-MIN-DELAY:50
- I/O Service ----------------------------------------------------------
wdir:C:\APP\IO\

Use the following command to display resource parameters; the command d p gpio-1 ? displays the meaning of all parameters.

[10:10:53] ABILIS_CPX:d p gpio-1
RES:Gpio-1 --------------------------------------------------------------------
Run    DESCR:
       LOG:NO               ACT:YES              LIVE-EXPIRY:10
       -------+-------------------- Digital Input lines -----------------------
       D-IN:  | [DESCR:]
       -------+----------------------------------------------------------------
       1      | 1
       2      | 2
       3      | 3
       4      | 4
       5      | 7
       6      | 5
       7      | 6
       -------+-------------------- Digital Output lines ----------------------
       D-OUT: | [DESCR:]
              | MODE:    PULSE-T:    PULSE-GAP:
       -------+----------------------------------------------------------------
       1      | 1
       2      | 2
       3      | 3
       4      | 4
       -------+-------------------- Analog Input lines ------------------------
       A-IN:  | [DESCR:]
              | UNIT:    MIN:    MAX:    ALM-LO: ALM-HI: HYST:  UPD:    POLL:
       -------+----------------------------------------------------------------
       1      | C        20      21      20      21      5.0     1.0     1.0
       2      | C        -10     40      0.0     40      5.0     1.0     1.0
       ------------------------------------------------------------------------

Meaning of the most important parameters:

LOG: State changes log and alarm generation [NO, D, S, A, L, T, ALL] [+E] (D: Debug Log; S: System Log; A: Alarm view; L: Local audible alarm; T: SNMP traps; +E: Extended Log of state changes).
ACT: Operation activation [NO, YES].
LIVE-EXPIRY: Expiry timeout programmed to GPIO device [10..600 sec].
D-IN: Digital Input Line identifier [1..64].
D-OUT: Digital output Line identifier [1..64].
MODE: Operatinal mode [VALUE, PULSE].
PULSE-T: Duration of ON pulse [1..4294967295 ms]. Only for MODE:PULSE.
PULSE-GAP: Minimum OFF time after ON pulse [1..65535 ms]. Only for MODE:PULSE.

Meaning of the Analog Input Lines parameters:

A-IN: Analog Input Line identifier [1..16].
UNIT: Unit of subsequent values. Empty or from 1 up to 8 characters (e.g. kWh, J, Volts, m, km, miles, myunit). Case is preserved.
MIN: Value corresponding to 0x0000. It must be < MAX. String representing a floating point number from -9999 to +9999. From 1 up to 6 characters in ['+', '-', '0'..'9', '.'].
MAX: Value corresponding to 0x03FF. It must be > MIN. String representing a floating point number from -9999 to +9999. From 1 up to 6 characters in ['+', '-', '0'..'9', '.'].
ALM-LO: Low threshold for alarm. It must be < ALM-HI and >= MIN, autoadjust against MIN. String representing a floating point number from -9999 to +9999. From 1 up to 6 characters in ['+', '-', '0'..'9', '.'].
ALM-HI: High threshold for alarm. It must be > ALM-LO and <= MAX, autoadjust against MAX. String representing a floating point number from -9999 to +9999. From 1 up to 6 characters in ['+', '-', '0'..'9', '.'].
HYST: Hysteresis for ALM-LO and ALM-HI for returning to NORMAL state. String representing a floating point number from -9999 to +9999. From 1 up to 6 characters in ['+', '-', '0'..'9', '.'].
UPD: Difference that must occur between the last value delivered and the current value read in order to make a new value delivery. Absolute value, valid for positive and negative variations. String representing a floating point number from -9999 to +9999. From 1 up to 6 characters in ['+', '-', '0'..'9', '.'].
POLL: Polling period [0.1..300.0 sec].

The following command allows the administrator to change the configuration of the resource:

s p gpio-1 parameter:value...

	Caution
	To activate the changes made on the upper case parameters, execute the initialization command init res:gpio; while to set act the changes made on the lowercase parameters a save conf and an Abilis restart are required (i.e. With warm start command).

Example: to set a pulse of 500 ms on Digital Out number 1 to open the Gate #1 type the following command:

[12:38:32] ABILIS_CPX:s p gpio-1 d-out:1 descr:Gate#1 mode:pulse pulse-t:500

COMMAND EXECUTED

Initialize the device and save the configuration with init res:gpio-1 and save conf.

[18:50:51] ABILIS_CPX:d p gpio-1

RES:Gpio-1 - Not Saved (SAVE CONF), Not Refreshed (INIT) ----------------------
       ------------------------------------------------------------------------
Run    DESCR:
       LOG:NO               ACT:YES              LIVE-EXPIRY:10
       -------+-------------------- Digital Input lines -----------------------
       D-IN:  | [DESCR:]
       -------+----------------------------------------------------------------
       1      | 1
       2      | 2
       3      | 3
       4      | 4
       5      | 7
       6      | 5
       7      | 6
       -------+-------------------- Digital Output lines ----------------------
       D-OUT: | [DESCR:]
              | MODE:    PULSE-T:    PULSE-GAP:
       -------+----------------------------------------------------------------
       1      | Gate#1
              | PULSE    500          250

The GPIO resource allows to view the state of each digital input/output line and to read values from analog inputs.

[13:44:42] ABILIS_CPX:d d gpio-1

RES:Gpio-1 --------------------------------------------------------------------
       STATE:UP             USB-STATE:CONNECTED      
       - Digital Input Lines State --------------------------------------------
        1..16| off off off off off off off off .   .   .   .   .   .   .   .   
       17..32| .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   
       33..48| .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   
       49..64| .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   
       ------------------------------------------------------------------------
       - Digital Output Lines State -------------------------------------------
        1..16| off off off off .   .   .   .   .   .   .   .   .   .   .   .   
       17..32| .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   
       33..48| .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   
       49..64| .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   
       ------------------------------------------------------------------------
       - Analog Input Lines ---------------------------------------------------
             | State  Value   Unit     ADC    | State  Value   Unit     ADC
       ------+--------------------------------+--------------------------------
        1.. 2| LOW    0.0     %        1      | LOW    0.0     %        1      
        3.. 4| .      .       .        .      | .      .       .        .      
        5.. 6| .      .       .        .      | .      .       .        .      
        7.. 8| .      .       .        .      | .      .       .        .      
        9..10| .      .       .        .      | .      .       .        .      
       11..12| .      .       .        .      | .      .       .        .      
       13..14| .      .       .        .      | .      .       .        .      
       15..16| .      .       .        .      | .      .       .        .      
       ------------------------------------------------------------------------

The GPIO resource permits to pilot the digital outputs state typing the command:

[11:14:46] ABILIS_CPX:s s res:gpio-1 d-out:1 ON

COMMAND EXECUTED

[19:03:43] ABILIS_CPX:s s res:gpio-1 d-out: ?

S S RES:Gpio-n D-OUT:val ON|OFF     Set status of Digital Output Line [ON, OFF]
                                    of the specified Gpio resource

D-OUT:     One value in the range [1..64] or a range of values 'xx-yy'
           or a list of values 'xx,yy,...' separated by ',' (comma) or
           "A" or "ALL".

	Tip
	Information about management I/O via WEB Chapter 69, Automation.

13.1.3. Activating MFIO resource

Add the MFIO resource with the following command:

[12:34:17] ABILIS_CPX:a res:mfio

COMMAND EXECUTED

	Caution
	Remember to save the configuration using save conf and an Abilis restart are required (i.e. With warm start command).

The MFIO resources must be activated with the command:

[12:38:18] ABILIS_CPX:s p mfio act:yes    

COMMAND EXECUTED

Use the following command to display resource parameters; the command d p mfio ? displays the meaning of all parameters.

[12:38:27] ABILIS_CPX:d p mfio

RES:MfIo ----------------------------------------------------------------------
Run    DESCR:Abilis_Multi_Function_IO_Interface
       LOG:DS        ACT:YES  
       -------+-------------------- Digital Input lines -----------------------
       D-IN:  | [DESCR:]
       -------+----------------------------------------------------------------
       -------+-------------------- Digital Output lines ----------------------
       D-OUT: | [DESCR:]
              | MODE:    PULSE-T:    PULSE-GAP:
       -------+----------------------------------------------------------------
       1      | Gate#
              | PULSE    500          250
       2      | Test
       ------------------------------------------------------------------------

Meaning of the most important parameters:

LOG: State changes log and alarm generation [NO, D, S, A, L, T, ALL] [+E] (D: Debug Log; S: System Log; A: Alarm view; L: Local audible alarm; T: SNMP traps; +E: Extended Log of state changes).
ACT: Operation activation [NO, YES].
D-IN: Digital Input Line identifier [1..7].
D-OUT: Digital output Line identifier [1..7].
MODE: Operatinal mode [VALUE, PULSE].
PULSE-T: Duration of ON pulse [1..4294967295 ms]. Only for MODE:PULSE.
PULSE-GAP: Minimum OFF time after ON pulse [1..65535 ms]. Only for MODE:PULSE.

The following command allows the administrator to change the configuration of the resource:

s p mfio parameter:value...

	Caution
	To activate the changes made on the upper case parameters, execute the initialization command init res:mfio; while to set act the changes made on the lowercase parameters a save conf and an Abilis restart are required (i.e. With warm start command).

Example: to set a pulse of 500 ms on Digital Out number 1 to open the Gate #1 type the following command:

[12:38:32] ABILIS_CPX:s p mfio d-out:1 descr:Gate#1 mode:pulse pulse-t:500

COMMAND EXECUTED

Initialize the device and save the configuration with init res:mfio and save conf.

[18:50:51] ABILIS_CPX:d p mfio

RES:MfIo ----------------------------------------------------------------------
Run    DESCR:Abilis_Multi_Function_IO_Interface
       LOG:DS        ACT:YES  
       -------+-------------------- Digital Input lines -----------------------
       D-IN:  | [DESCR:]
       -------+----------------------------------------------------------------
       -------+-------------------- Digital Output lines ----------------------
       D-OUT: | [DESCR:]
              | MODE:    PULSE-T:    PULSE-GAP:
       -------+----------------------------------------------------------------
       1      | Gate#
              | PULSE    500          250
       ------------------------------------------------------------------------

The MFIO resource allows to view the state of each digital input/output line.

[08:29:04] ABILIS_CPX:d d mfio

RES:MfIo ----------------------------------------------------------------------
       Abilis_Multi_Function_IO_Interface                                      
       STATE:ACTIVE
       - Digital Input Lines State --------------------------------------------
        1..7| off off off off off off off 
       ------------------------------------------------------------------------
       - Digital Output Lines State -------------------------------------------
        1..7| off off off off off off off 
       ------------------------------------------------------------------------

The MFIO resource permits to pilot the digital outputs state typing the command:

[11:14:46] ABILIS_CPX:s s res:mfio d-out:1 ON

COMMAND EXECUTED

[19:03:43] ABILIS_CPX:s s res:mfio d-out: ?

S S RES:Mfio-n D-OUT:val ON|OFF     Set status of Digital Output Line [ON, OFF]
                                    of the specified Gpio resource

D-OUT:     One value in the range [1..64] or a range of values 'xx-yy'
           or a list of values 'xx,yy,...' separated by ',' (comma) or
           "A" or "ALL".

	Tip
	Information about management I/O via WEB Chapter 69, Automation.

13.1.4. Activation of the alarms for the MFIO/GPIO

In case of Digital or Analog input variation is possible to activate alarms.

Example: send an e-mail if Digital Input 1 becomes ON.

[19:06:49] ABILIS_CPX:d p alarm

RES:Alarm ---------------------------------------------------------------------
Run    DESCR:Alarms_manager
       LOG:NO        ACT:YES            fifo-size:100
       MAIL-FROM:SYS (AbilisCPX<AbilisCPX@abilis>)
       MAIL-RCPT:#
       MAIL-BODY:STANDARD
       SMS-SENDER:CP-PI             SMS-CDO:#                              

[19:06:49] ABILIS_CPX:a alarm id:2 enabled:yes res:gpio-1 action:mail io:d-in-1 monitor:on MAIL-RCPT:alarms@mydomain.com

COMMAND EXECUTED

[19:32:28] ABILIS_CPX:d alarm id:2

-------------------------------------------------------------------------------
ID: |[DESCR:]
    |ENABLED:|RES:              |IO:         |MONITOR: |ACTION:
    |MAIL-RCPT:
    |MAIL-RCPT-LIST:
    |MAIL-BODY:
    |SMS-CDO:
    |DISA-USER:                 |DISA-PIN:   |DISA-SERVICE:
    |DISA-CDO:                  |DISA-CGO:
-------------------------------------------------------------------------------
2     YES      Gpio-1             D-IN-1       ON        MAIL
     - MAIL -------------------------------------------------------------------
alarms@mydomain.com
     #
     SYS
-------------------------------------------------------------------------------

Corresponding command for MFIO:

[19:06:49] ABILIS_CPX:a alarm id:2 enabled:yes res:mfio action:mail io:d-in-1 monitor:on MAIL-RCPT:alarms@mydomain.com

COMMAND EXECUTED

[19:32:28] ABILIS_CPX:d alarm id:2

-------------------------------------------------------------------------------
ID: |[DESCR:]
    |ENABLED:|RES:              |IO:         |MONITOR: |ACTION:
    |MAIL-RCPT:
    |MAIL-RCPT-LIST:
    |MAIL-BODY:
    |SMS-CDO:
    |DISA-USER:                 |DISA-PIN:   |DISA-SERVICE:
    |DISA-CDO:                  |DISA-CGO:
-------------------------------------------------------------------------------
2     YES      Mfio            D-IN-1       ON        MAIL
     - MAIL -------------------------------------------------------------------
alarms@mydomain.com
     #
     SYS
-------------------------------------------------------------------------------

To see the help online use the following command:

[19:06:49] ABILIS_CPX:a alarm id:2  res:gpio-1 action:mail ? monitor : io: 

Alarm management rule parameter(s):

MONITOR:   Alarm/event to be monitored [NONE, TRAP, ALARM-ON, ALARM-OFF,
           ALARM-*, ON, OFF, LOW, NORMAL, HIGH, *]
           'TRAP', 'ALARM-ON', 'ALARM-OFF' are allowed only for IO equal to #;
           'TRAP' is allowed only for ACTION not equal to DISA-CB;
           'ON', 'OFF', '*' are allowed only for Digital lines;
           'LOW', 'NORMAL', 'HIGH', '*' are allowed only for Analog lines.
IO:        Input/output line for which the alarm/event is monitored. "#" or
           - "D-IN-n", where 'n' can be
             - for GPIO Digital IN line, [1..64, *];
             - for MFIO Digital IN line, [1..7, *];
           - "D-OUT-n", where 'n' can be
             - for GPIO Digital OUT line, [1..64, *];
             - for MFIO Digital OUT line, [1..7, *];
           - "A-IN-n", where 'n' can be [1..16, *], for GPIO Analog IN line;
                                                 <Only for Gpio/MfIo resources>

	Tip
	Others informations about Alarm resource are available in the Section 32.1, “ALARM resource”.

Tip

Interesting chapters:

Section 72.24, “Sending Alarm through a call”;

Section 72.25, “Sending Alarm through SMS”.