=======
IO-PORT
=======

.. sidebar:: Contents

  .. contents::
      :depth: 3
      :local:

The digital I/O ports configuration allows the device to monitor the digital Input and control the digital Output.
This can be useful to interoperate with external devices.

Digital Input allows a signal connected to the input port to be monitored. The input signal monitor includes configura-
tion options to eliminate switching transients. The signal state can be monitored via CLI.

Digital Output allows the signal to the output port to be controlled (ON/OFF switch). The output signal monitor in-
cludes configuration options to set the default state after device start-up. The signal state can be monitored via CLI.

The device can generates an event (alarms) whenever changes in state are detected at the Input port.



Configuration
=============

This service is only available in devices with DI/DO ports and its configuration is under the 'system' path.
The syntax to configure :osdx:cfg:`system io-port`: is:

.. code-block:: none

  set system io-port [ ... ]

This path have two parameter:

  * ``gpio``: the path to configure the behavior of the DI/DO port.
  * ``log-level``: set the priority of logs related to io-port. By default is error.

.. code-block:: none

    set system io-port gpio gpio0 in-parameter alarm
    set system io-port gpio gpio0 in-parameter enable
    set system io-port gpio gpio0 in-parameter off-time
    set system io-port gpio gpio0 in-parameter on-time
    set system io-port gpio gpio0 out-parameter start-value

The number of DI/DO ports depends on the device. Each port can be configured as input or output and is represented as 'gpioX'. 
The behavior if determined by the use of input parameter or output parameter:

    * ``in-parameter alarm``: define an alarm to be launched when the state of the input port change.
    * ``in-parameter enable``: activate the continuous monitoring of the input port.
    * ``in-parameter off-time``: time to validate a change from ON to OFF. Default value is 50 ms.
    * ``in-parameter on-time``: time to validate a change from OFF to ON. Default value is 50 ms.
    * ``out-parameter start-value``: initial value of the output port. Can be ON or OFF.

A basic configuration can be:

.. code-block:: none

    set system alarm DIO0
    set system io-port gpio gpio0 in-parameter enable
    set system io-port gpio gpio0 in-parameter alarm DIO0
    set system io-port gpio gpio1 in-parameter enable
    set system io-port gpio gpio2 out-parameter start-value ON
    
Examples
========

This example shows how to set to ON an output port when two input ports are ON. It's possible to configure the script with
any configuration that use alarms.

Check :doc:`here <../../system/script/index>` for more information about how to configure scripts in OSDx.

.. code-block:: none

    set system advisor ADVISOR1 test 'DIO0 and DIO1'
    set system alarm DIO0
    set system alarm DIO1
    set system io-port gpio gpio0 in-parameter alarm DIO0
    set system io-port gpio gpio0 in-parameter enable
    set system io-port gpio gpio1 in-parameter alarm DIO1
    set system io-port gpio gpio1 in-parameter enable
    set system io-port gpio gpio2 out-parameter start-value off
    set system io-port log-level debug
    set system script SCRIPT_1 advisor ADVISOR1

After commited the configuration, add:

.. code-block:: none

    set system script SCRIPT_1 operational 1 command "system io-port gpio2 output-value on"

.. :doc:`Here </examples/system/io-port/index>`, you can find an example related to io-ports.

Monitoring commands
===================

The io-port service has multiple monitoring commands:

    * ``system io-port status``: show the status of all ports configured.
    * ``system io-port clear``: reset to zero the number of changes of all ports configured.
    * ``system io-port <id> status``: show the status of a single port.
    * ``system io-port <id> clear``: reset to zero the number of changes of a single port.
    * ``system io-port <id> output-value``: set to ON/OFF the value of a single output port. Only available to ports configured as output.

*Example:*

.. code-block:: none

    admin@osdx$ system io-port status 

    gpio0 configured as input port:
    Input signal:
        Monitoring control....: ENABLED
        OFF validation time...: 50 ms
        ON validation time....: 50 ms
        State.................: ON
        Number of changes.....: 1
    Output signal:
        Inital default state.: OFF
        State................: OFF
        Number of changes....: 0

    gpio1 configured as input port:
    Input signal:
        Monitoring control....: ENABLED
        OFF validation time...: 50 ms
        ON validation time....: 50 ms
        State.................: ON
        Number of changes.....: 1
    Output signal:
        Inital default state.: OFF
        State................: OFF
        Number of changes....: 0

    gpio2 configured as output port:
    Input signal:
        Monitoring control....: DISABLED
        OFF validation time...: 50 ms
        ON validation time....: 50 ms
        State.................: unknown
        Number of changes.....: 0
    Output signal:
        Inital default state.: OFF
        State................: ON
        Number of changes....: 1

Command Summary
===============

.. osdx:cmdtree:: cfg
  :maxdepth: 8

  system io-port

.. osdx:cmdtree:: op
  :maxdepth: 5

  system io-port