.. _tools:

Tools
=====

.. module:: PyWrtd

WRTD provides two comand-line, Python based tools for accessing a :ref:`node`. One
(:ref:`wrtd_config`) is used to add/remove/configure :ref:`Rules <rule>` and :ref:`Alarms <alarm>`,
and to display information about the :ref:`node` while the other (:ref:`wrtd_logging`) is used for
reading entries from the :ref:`event_log`.

Both tools have a built-in help system that can be accessed by passing the ``--help`` (or ``-h``)
option to the tool.

Both tools take an obligatory ``-D`` option to specify the :ref:`node` to access. For more details,
please refer to :ref:`node_id`. You also need to run them with the proper :ref:`permissions`.

For details on how to install these tools (and their dependencies), please refer to
:numref:`installation`.

.. _wrtd_config:

wrtd-config
-----------

``wrtd-config`` is a command-line tool that implements several different operations on a
:ref:`node`. It supports most of the functionality provided by the :ref:`pywrap`.

A list of the available commands can be retrieved by passing the ``-h`` option to the tool:

.. code-block:: console

   > wrtd-config -h
   usage: wrtd-config [-h] -D DEV <command> ...

   WRTD node configuration tool

   optional arguments:
     -h, --help            show this help message and exit
     -D DEV, --dev-id DEV  MockTurtle device ID (integer) to open

   Available commands:
     <command>             (Use "<command> -h" to get more details)
       sys-info            Show system information
       sys-time            Show current system time
       set-log             Enable/Disable logging
       clear-log           Clear pending log entries
       list-rules          List all defined Rules
       add-rule            Define a new Rule
       set-rule            Configure a Rule
       remove-rule         Delete a Rule
       remove-all-rules    Delete all Rules
       enable-rule         Enable a Rule
       disable-rule        Disable a Rule
       disable-all-rules   Disable all Rules
       rule-info           Display information about a Rule
       reset-rule-stats    Reset all statistics of a Rule
       list-alarms         List all defined Alarms
       add-alarm           Define a new Alarm
       set-alarm           Configure an Alarm
       remove-alarm        Delete an Alarm
       remove-all-alarms   Delete all Alarms
       enable-alarm        Enable an Alarm
       disable-alarm       Disable an Alarm
       disable-all-alarms  Disable all Alarms
       alarm-info          Display information about an Alarm

Each command has its own built-in help system as well, which can be invoked by selecting a command
and passing the ``-h`` option after the command:

.. code-block:: console

   > wrtd-config set-alarm -h
   usage: wrtd-config set-alarm [-h] -d DELAY [-s SETUP] [-p PERIOD]
                                [-c COUNT] [-e] name

   positional arguments:
     name                  The name of the Alarm to configure

   optional arguments:
     -h, --help            show this help message and exit
     -d DELAY, --delay DELAY
                           Set the delay for this Alarm wrt now. Default
                           unit is ns, but an 'n','u','m' or 's' can be
                           appended to the value to set it explicitly to
                           nano, micro, milli or full seconds
     -s SETUP, --setup SETUP
                           Set the setup time for this Alarm. Default
                           unit is ns, but an 'n','u','m' or 's' can be
                           appended to the value to set it explicitly to
                           nano, micro, milli or full seconds
     -p PERIOD, --period PERIOD
                           Set the period for this Alarm. Default unit
                           is ns, but an 'n','u','m' or 's' can be
                           appended to the value to set it explicitly to
                           nano, micro, milli or full
     -c COUNT, --count COUNT
                           Set the repeat count for this Alarm
     -e, --enable          Also enable the Alarm after configuring it.

If a command returns an :ref:`Error Code <api_error_codes>`, the underlying :ref:`pywrap` will raise
an OSError exception and will provide all the available details coming from
:py:meth:`PyWrtd.get_error`:

.. code-block:: console

   > wrtd-config -D 1 remove-alarm alarm5
   OSError: [Errno -1074122744] Error 0xbffa3008: WRTD_ERROR_ALARM_DOES_NOT_EXIST wrtd_remove_alarm/wrtd_find_alarm: The specified alarm has not been defined

.. _wrtd_logging:

wrtd-logging
------------

wrtd-logging is a simple command-line tool that monitors the :ref:`event_log` of a :ref:`node`.

A list of the available options can be retrieved by passing the ``-h`` option to the tool:

.. code-block:: console

   > wrtd-logging -h
   usage: wrtd-logging [-h] -D DEV [-c COUNT]

   WRTD node log monitoring tool

   optional arguments:
     -h, --help            show this help message and exit
     -D DEV, --dev-id DEV  MockTurtle device ID (integer) to open
     -c COUNT, --count COUNT
                           Number of entries to read (0 = infinite)
     -e, --enable          Enable event logging on the Node if not already
                           enabled.

Log entries are printed using the format presented in :cpp:func:`wrtd_get_next_event_log_entry`.
