==============
Using DistWAGO
==============

Run "distkv client wago monitor" to connect to the server on localhost.

See "distkv dump cfg wago" for configuration options.

Data structure
==============

On disk, the path to the port is ".distkv wago SERVER TYPE CARD PORT" by
default. All attributes are also looked up in the higher nodes, so you can
set per-type or per-server defaults easily.

Server attributes
+++++++++++++++++

* server: a dict with host and port. Set by ``distkv client wago server``.

* poll: The cylce time of the controller. Typical: 0.05 seconds.

* ping: The interval between keep-alive messages from the controller.
  Typical: a few seconds.

Port attributes
+++++++++++++++

* mode: a string. Allowed values and their meaning depend on the port's
  type.

``input`` ports
---------------

read
~~~~

The current value of a wire on the controller is mirrored to some DistKV entry.

* dest: the path to store the result at.

* rest: Flag whether the line is inverted / active-low. Default False.

count
~~~~~

The number of transitions of a wire on the controller is mirrored to some DistKV entry.

* dest: the path to store the counter at.

* count: Flag whether to count L>H transitions (True), H>L (False) or both (None).

* interval: The time after which the counter is flushed, to avoid overwhelming the system when impulses arrive too fast.

``output`` ports
----------------

write
~~~~~

The current value of some DistKV entry is mirrored to a wire on the controller.
Also, the current output state is mirrored to a "state" entry in DistKV.

* src: the path to monitor the valoe of.

* rest: Flag whether the line is inverted / active-low. Default False.

* state:

oneshot
~~~~~~~

The current value of some DistKV entry is mirrored to a wire on the controller for some time (max).
Also, the current output state is mirrored to a "state" entry in DistKV.

The wire is cleared when the time has passed, or when the DistKV entry is set to `False`.

* src

* rest

* state

* t_on: seconds the signal should be on.

  This can be a float or a tuple, in which case the value will be read from
  that location.

pulse
~~~~~~~

If some DistKV entry is set, a wire on the controller flips between on and
off. The "on" ratio is mirrored to a "state" entry in DistKV.

The wire is cleared (and the state entry set to zero) when the DistKV entry is set to `False`.

* src
* src

* rest

* state

* t_on

* t_off: seconds the signal should be off.

  This can be a float or a tuple, in which case the value will be read from
  that location.


Command line
============


.. program:: distkv client wago

The main entry point for this extension.


.. program:: distkv client wago port

Print or modify port settings.

This is a shortcut for ``… attr`` that evaluates various attributes and
lets you easily change more than one at a time.

.. option:: -m, --mode MODE

   Set the port's mode. See help text for known modes.

   Allowed modes depend on the type of the input or output.

.. option:: -a, --attr name value

   Adds an attribute. This option converts ``value`` to a tuple (if it
   contains spaces), integer or float (if possible).

   This option can be used more than once.

.. option:: path

   The path to the port to be modified. Must be "SERVER TYPE CARD PORT".
   Card and port are numeric, starting with 1.


.. program:: distkv client wago attr

Print, modify or delete a single attribute.

If you set a value that is evaluated to a mapping, exising values will be merged.

.. option:: -a, --attr NAME

   The name of the attribute to display, change or delete. Use more than
   once for nested values.

   Default: show all attributes.

.. option:: -v, --value VALUE

   The new value of the attribute.

   To delete an attribute, use ``-ev-``.

   Do not feorget ``-e`` if the value is numeric!

.. option:: -e, --eval

   The attribute's value is a Python expression.


.. program:: distkv client wago list

Print the current state of your Wago controllers.

This command does not access the device; it is solely for displaying the
configuration of its interaction with DistKV.

.. option:: server

   The Wago controller to access.

.. option:: type

   The type of connection. Currently supported: ``input`` and ``output``
   for 24 volt controls.

.. option:: card

   The card number. The first card should be 1 (assuming that it's recognized).

.. option:: port

   The port number. Ports are numbered starting with 1.


.. program:: distkv client wago monitor

This is a stand-alone Wago monitor. It connects to a single controller
and runs polls and monitors.

.. option:: server

   The controller to connect to. Do not run this more than once for any given
   server.



Configure polling.

If the device (and the given attribute) supports simultaneous conversion,
this might cause results to be read more often than configured here.

.. option:: -f, --family <code>

   Change the poll interval's default for this family code.

.. option:: -d, --device <family.device>

   Change the poll interval for this device.

.. option:: <attribute>

   Set the interval on this attribute. Use a ``/`` separator for sub-attributes.

.. option:: <interval>

   The interval to poll at. Use ``-`` to disable polling.


.. program:: distkv client wago set

You can use this command to add arbitrary values to a device's entry. Use
this e.g. to add a note where the device is located, or to signal your own
code.

.. option:: -f, --family <code>

   Change an attribute on this family code.

.. option:: -d, --device <family.device>

   Change an attribute on this device.

.. option:: -v, --value

   The value to set.

.. option:: -e, --eval

   Flag that the value is a Python expression and should be evaluated.

.. option:: <name>…

   The attribute name to set. Use more than once for accessing sub-dicts.

