From 4641c9fb3afbd37fbb8675eeed4865e322376fdf Mon Sep 17 00:00:00 2001
From: stedif <stefano.difrischia@inaf.it>
Date: Wed, 15 Sep 2021 15:17:32 +0200
Subject: [PATCH] L2SS-235: add readme file and minor bug fixing
---
devices/toolkit/README.md | 42 +++++++++++++++++++
devices/toolkit/archiver.py | 2 +-
jupyter-notebooks/PCC_archive_attribute.ipynb | 2 +-
3 files changed, 44 insertions(+), 2 deletions(-)
create mode 100644 devices/toolkit/README.md
diff --git a/devices/toolkit/README.md b/devices/toolkit/README.md
new file mode 100644
index 000000000..e3fd6c9af
--- /dev/null
+++ b/devices/toolkit/README.md
@@ -0,0 +1,42 @@
+# Tango Archiving Framework
+
+The Archiver class in archiver.py defines the methods to manage the device attributes archiving allowed by Tango.
+
+The main components (and the relative Docker containers) are:
+
+- Configuration Manager (container: hdbpp-cm): Device server that assists in adding, modifying, moving, deleting an Attribute to/from the archiving system
+- Event Subscriber (container: hdbpp-es): The EventSubscriber TANGO device server, is the archiving system engine. On typical usage, it will subscribe to archive events on request by the ConfigurationManager device. The EventSubscriber is designed to start archiving all the already configured Attributes, even if the ConfigurationManager is not running. Moreover, being a TANGO device, the EventSubscriber configuration can be managed with Jive.
+- Archiving DBMS (container: archiver-maria-db): Specific Database devoted to storing attribute values.
+- (Optional) HDB++ Viewer (container: hdbpp-viewer): Standalone JAVA application designed to monitor signals coming from database
+
+## Archiver creation
+When an Archiver object is created, we can define three of its properties:
+- the ConfigurationManager name (Tango namespace)
+- at least one EventSubscriber name (Tango namespace)
+- the default context archiving for the subscribers. This means that a default archiving strategy will be applied to
+all the attributes. Of course this strategy can be tuned individually for each attribute if needed.
+Archiving strategies are ['ALWAYS','RUN','SHUTDOWN','SERVICE']
+- ALWAYS:always stored
+- RUN:stored during run
+- SHUTDOWN:stored during shutdown
+- SERVICE:stored during maintenance activities
+
+## Add an attribute
+When adding an attribute to the archiving framework, we must define the following properties:
+- the EventSubscriber name that will take charge of the attribute
+- the archiving strategy (4 options defined above)
+- the attribute polling period (it should have been already defined in TangoDB)
+- the archive event period (MOST IMPORTANT, it defines the frequency rate at which an attribute is archived in the DBMS)
+
+It is important to understand that, when an attribute is successfully added to the EventSubscriber list, the archiving begins without an explicit 'Start' command, rather it follows the archiving strategy already defined.
+
+The 'Start' command is used instead during a session when an attribute has been paused/stopped for any reason, or it has raised some kind of issue.
+
+## Difference between Stop and Remove an attribute
+When stopping an attribute archiving, the framework does not remove it from the list.
+This means that archiving is stopped for the current session, but if the device is restarted, the attribute archiving will be restarted as well.
+In order to definitely stop the archiving, the attribute must be removed from the attribute list.
+
+## Update an attribute
+If we want to update the archiving properties of an attribute (e.g. the archive event period), there is a relative method.
+It must be noted that the updating is not istantaneous because, following the framework architecture, an attribute must be first removed from the EventSubscriber list and then re-added with the new properties.
diff --git a/devices/toolkit/archiver.py b/devices/toolkit/archiver.py
index 0b7d8b311..1ec7f642b 100644
--- a/devices/toolkit/archiver.py
+++ b/devices/toolkit/archiver.py
@@ -129,7 +129,7 @@ class Archiver():
else:
print('Attribute %s not found!' % attribute_name)
- def check_attribute_in_archiving_list(self, attribute_name:str):
+ def check_and_add_attribute_in_archiving_list(self, attribute_name:str):
"""
Check if an attribute is in the archiving list
"""
diff --git a/jupyter-notebooks/PCC_archive_attribute.ipynb b/jupyter-notebooks/PCC_archive_attribute.ipynb
index 6c744387f..d2e413b68 100644
--- a/jupyter-notebooks/PCC_archive_attribute.ipynb
+++ b/jupyter-notebooks/PCC_archive_attribute.ipynb
@@ -69,7 +69,7 @@
"# Start the device\n",
"if state == \"OFF\":\n",
" if isProduction():\n",
- " archiver.check_attribute_in_archiving_list(attr_fq_name)\n",
+ " archiver.check_and_add_attribute_in_archiving_list(attr_fq_name)\n",
" else:\n",
" archiver.remove_attribute_from_archiver(attr_fq_name)\n",
" time.sleep(1)\n",
--
GitLab