Skip to content

W
White Rabbit Trigger Distribution
Commit 7cb88275 authored by Dimitris Lampridis's avatar Dimitris Lampridis
Browse files
Options

[doc] update documentation for new node ID API and updated wrtd tools

parent 13af669b
Hide whitespace changes
Inline Side-by-side
Showing with 139 additions and 96 deletions
doc/installation.rst
View file @ 7cb88275
......@@ -11,8 +11,3 @@ Installation
Permissions
===========
.. _node_id:
Node Identification
===================
doc/usage_clib.rst
View file @ 7cb88275
......@@ -98,15 +98,27 @@ The initialisation API provides the functions to initiate/close a connection to
well as to reset it.
:cpp:func:`wrtd_init` is the first function that should be called by any program, in order to obtain
the "device token" to be used in all subsequent function calls. See also :ref:`node_id` on how to
figure out the ``resource_name`` of a :ref:`node`.
the "device token" to be used in all subsequent function calls.
Conversely, :cpp:func:`wrtd_close` should be called before exiting the program. No further WRTD
library functions can be used after that.
In order to identify the :ref:`node` to connect to, it is necessary to provide the ID of that
:ref:`node`. This ID is simply an integer that uniquely identifies a Node within a given host
system. Functions :cpp:func:`wrtd_get_node_count` and :cpp:func:`wrtd_get_node_id` can help you
figure out the ID of each :ref:`node`.
.. important::
The Node ID is not sequential, nor does it start counting from zero (or one). It might well be
that you only have one Node in a given host, and that it has an ID different than 1. Always
retrieve therefore the Node ID with :cpp:func:`wrtd_get_node_id`.
.. doxygenfunction:: wrtd_init
.. doxygenfunction:: wrtd_close
.. doxygenfunction:: wrtd_reset
.. doxygenfunction:: wrtd_get_node_count
.. doxygenfunction:: wrtd_get_node_id
.. code-block:: c
:caption: Opening and closing a connection to a Node.
......@@ -115,8 +127,17 @@ library functions can be used after that.
int main(void) {
wrtd_dev *wrtd;
wrtd_status status;
uint32_t node_count;
uint32_t node_id;
status = wrtd_init("MT01", false, NULL, &wrtd);
/* Not really used in this example */
status = wrtd_get_node_count(&node_count);
/* Get the ID of the first Node */
status= wrtd_get_node_id(1, &node_id);
/* Access the first Node */
status = wrtd_init(node_id, false, NULL, &wrtd);
/* This will erase all defined rules and alarms
from the Node, so it might not be what you want
......
doc/usage_pywrap.rst
View file @ 7cb88275
......@@ -16,61 +16,51 @@ The wrapper is provided as a Python package with a single class that encapsulate
All the provided class methods have exactly the same names (and function) as their C counterparts,
without the "wrtd\_" prefix.
To start using it, simply import the PyWrtd package and instantiate a :py:class:`PyWrtd` object,
passing to it the :ref:`identifier of the Node<node_id>` you wish to access.
If the identifier is wrong or if the user does not have the correct permissions to access it, WRTD
will return :cpp:enumerator:`WRTD_ERROR_RESOURCE_UNKNOWN`.
.. code-block:: python
.. hint::
>>> from PyWrtd import PyWrtd
>>> wrtd = PyWrtd("bad id")
Error 0xbffa0060: WRTD_ERROR_RESOURCE_UNKNOWN
>>> wrtd = PyWrtd("MT01")
>>> wrtd
<PyWrtd.PyWrtd object at 0x7fa9aeeaee48>
Compared to the :ref:`clib`, the Python wrapper lacks the :cpp:func:`wrtd_init`,
:cpp:func:`wrtd_close`, :cpp:func:`wrtd_get_error` and :cpp:func:`wrtd_error_message` functions,
because the Python wrapper performs these tasks (initialisation and error handling) internally.
.. hint::
The provided :ref:`tools <tools>` are built on top of this Python wrapper, so they also serve as
a good example of how to use the wrapper.
Error Handling API
------------------
.. automethod:: PyWrtd.get_error
.. code-block:: python
>>> wrtd.get_error()
(0, 'WRTD_SUCCESS ')
.. automethod:: PyWrtd.error_message
.. code-block:: python
>>> wrtd.error_message(PyWrtd.WRTD_SUCCESS)
'WRTD_SUCCESS'
.. _pyapi_init:
Initialisation API
------------------
Compared to the :ref:`clib` :ref:`api_init`, the Python version lacks the :cpp:func:`wrtd_init` and
:cpp:func:`wrtd_close` functions, because the Python wrapper performs these tasks internally.
To start using it, simply import the PyWrtd package and instantiate a :py:class:`PyWrtd` object,
passing to it the ID of the Node you wish to access.
In order to retrieve the ID of the :ref:`node`, the :py:class:`PyWrtd` class provides the static
methods :py:meth:`PyWrtd.PyWrtd.get_node_count` and :py:meth:`PyWrtd.PyWrtd.get_node_id` that can be
used before you instantiate the :py:class:`PyWrtd` object.
If the ID is wrong or if the user does not have the correct :ref:`permissions <permissions>` to
access it, WRTD will return :cpp:enumerator:`WRTD_ERROR_RESOURCE_UNKNOWN`.
.. automethod:: PyWrtd.reset
.. code-block:: python
>>> from PyWrtd import PyWrtd
>>> wrtd = PyWrtd(11)
OSError: [Errno -1074134944] WRTD_ERROR_RESOURCE_UNKNOWN
>>> PyWrtd.get_node_id(3)
OSError: [Errno -1074134944] WRTD_ERROR_RESOURCE_UNKNOWN
>>> PyWrtd.get_node_count()
2
>>> PyWrtd.get_node_id(1)
10
>>> wrtd = PyWrtd(10)
>>> wrtd
<PyWrtd.PyWrtd object at 0x7fa9aeeaee48>
>>> wrtd.reset()
>>> wrtd.add_rule('rule1')
>>> # Query number of declared rules
>>> wrtd.get_attr_int32(PyWrtd.WRTD_GLOBAL_REP_CAP_ID, PyWrtd.WRTD_ATTR_RULE_COUNT)
1
>>> # After reset, 'rule1' should be gone
>>> wrtd.reset()
>>> wrtd.get_attr_int32(PyWrtd.WRTD_GLOBAL_REP_CAP_ID, PyWrtd.WRTD_ATTR_RULE_COUNT)
0
.. automethod:: PyWrtd.get_node_count
.. automethod:: PyWrtd.get_node_id
.. automethod:: PyWrtd.reset
.. _pyapi_attr:
......
doc/usage_tools.rst
View file @ 7cb88275
......@@ -5,46 +5,43 @@ 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`.
WRTD provides a comand-line, Python based tool (:ref:`wrtd_tool`) for accessing a :ref:`node`.
Both tools have a built-in help system that can be accessed by passing the ``--help`` (or ``-h``)
option to the tool.
.. hint::
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`.
Please make sure that you run the tool wih the proper :ref:`permissions <permissions>`.
For details on how to install these tools (and their dependencies), please refer to
For details on how to install the tool (and their dependencies), please refer to
:numref:`installation`.
.. _wrtd_config:
.. _wrtd_tool:
wrtd-config
-----------
wrtd-tool
---------
``wrtd-config`` is a command-line tool that implements several different operations on a
``wrtd-tool`` 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-tool -h
usage: wrtd-tool [-h] <command> ...
WRTD node configuration tool
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)
list-nodes List the IDs of all detected WRTD Nodes
sys-info Show system information
sys-time Show current system time
set-log Enable/Disable logging
enable-log Enable logging
disable-log Disable logging
show-log Show log entries
clear-log Clear pending log entries
list-rules List all defined Rules
add-rule Define a new Rule
......@@ -71,12 +68,14 @@ 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
> wrtd-tool set-alarm -h
usage: wrtd-tool set-alarm [-h] -d DELAY [-s SETUP] [-p PERIOD]
[-c COUNT] [-e] <node_id> <alarm_id>
positional arguments:
name The name of the Alarm to configure
<node_id> The ID of the WRTD Node (int, can be hex with "0x"
prefix)
<alarm_id> The ID of the Alarm (string up to 15 characters)
optional arguments:
-h, --help show this help message and exit
......@@ -100,36 +99,58 @@ and passing the ``-h`` option after the command:
-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`:
an OSError exception and will provide all the available details:
.. 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-tool remove-alarm 1 alarm5
OSError: [Errno -1074122744] 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:
Here's an example on how to configure a :ref:`rule` and check the :ref:`event_log` for :ref:`Events
<event>`:
.. 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`.
> wrtd-tool list-nodes
-> WRTD Node detected with ID: 10
> wrtd-tool list-rules 10
0 Rules defined.
> wrtd-tool add-rule 10 rule0
> wrtd-tool set-rule 10 rule0 LC-I1 NET0
> wrtd-tool list-rules 10 -v
1 Rule defined:
+ rule0
+ Configuration
- Name..............: rule0
- Source............: LC-I1
- Destination.......: NET0
- Enabled...........: False
- Send Late.........: True
- Repeat Count......: 0
- Delay.............: 0.000ns
- Holdoff...........: 0.000ns
- Resync Period.....: 0.000ns
- Resync Factor.....: 0
+ Statistics
- RX Events.........: 0
- Last RX...........: Never
- TX Events.........: 0
- Last TX...........: Never
- Latency (min).....: 0.000ns
- Latency (avg).....: 0.000ns
- Latency (max).....: 0.000ns
- Missed (late).....: 0
- Missed (holdoff)..: 0
- Missed (no sync)..: 0
- Missed (overflow).: 0
- Last Missed.......: Never
> wrtd-tool enable-rule 10 rule0
> wrtd-tool enable-log 10
> wrtd-tool show-log 10 -c 6
Id:LC-I1 |Seq:0000|...|...|GENERATED|DEVICE_0
Id:NET0 |Seq:0016|...|...|NETWORK |TX
Id:LC-I1 |Seq:0000|...|...|GENERATED|DEVICE_0
Id:NET0 |Seq:0017|...|...|TX
Id:LC-I1 |Seq:0000|...|...|GENERATED|DEVICE_0
Id:NET0 |Seq:0018|...|...|TX
software/lib/libwrtd.c
View file @ 7cb88275
......@@ -20,6 +20,12 @@
* @{
*/
/**
* Retrieve the number of detected WRTD Nodes.
*
* @param[out] count number of detected WRTD Nodes
* @return #wrtd_status
*/
wrtd_status wrtd_get_node_count(uint32_t *count)
{
int i;
......@@ -53,6 +59,16 @@ wrtd_status wrtd_get_node_count(uint32_t *count)
return WRTD_SUCCESS;
}
/**
* Retrieve the ID of a WRTD Node.
*
* Before calling this function, you should probably call #wrtd_get_node_count to know the
* number of Nodes.
*
* @param[in] index The index of the Node ("1" for the first Node, etc.)
* @param[out] node_id The retrieved ID of the Node
* @return #wrtd_status
*/
wrtd_status wrtd_get_node_id(uint32_t index, uint32_t *node_id)
{
int i;
......
software/lib/python/PyWrtd.py
View file @ 7cb88275
......@@ -76,7 +76,7 @@ def errcheck_static(ret, func, args):
class PyWrtd():
"""Top-level Python wrapper class for WRTD library.
:param node_id: WRTD Node ID. See also :ref:`node_id`.
:param node_id: WRTD Node ID.
"""
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment