From b27eb0e07920c1e0bc5e59642162b5e0d857471a Mon Sep 17 00:00:00 2001
From: Arnaud Watlet <arnaud.watlet@umons.ac.be>
Date: Thu, 18 Jan 2024 10:00:02 +0100
Subject: [PATCH] update software doc
---
doc/source/source_rst/software/index.rst | 3 +--
doc/source/source_rst/software/monitoring.rst | 16 ------------
doc/source/source_rst/software/operations.rst | 13 ----------
.../source_rst/software/operations/config.rst | 25 +++++++------------
.../source_rst/software/operations/index.rst | 5 ++--
.../software/operations/interfaces.rst | 16 +++---------
.../software/operations/monitoring.rst | 23 +++++++++++++++++
.../software/operations/settings.rst | 10 +++-----
8 files changed, 44 insertions(+), 67 deletions(-)
delete mode 100644 doc/source/source_rst/software/monitoring.rst
delete mode 100644 doc/source/source_rst/software/operations.rst
create mode 100644 doc/source/source_rst/software/operations/monitoring.rst
diff --git a/doc/source/source_rst/software/index.rst b/doc/source/source_rst/software/index.rst
index 039f1fb5..76636de6 100644
--- a/doc/source/source_rst/software/index.rst
+++ b/doc/source/source_rst/software/index.rst
@@ -13,6 +13,5 @@ Contents:
Software architecture <architecture>
Getting started <installation>
- Operation <operations/index>
- Monitoring <monitoring>
+ Operating the system <operations/index>
API reference <api>
diff --git a/doc/source/source_rst/software/monitoring.rst b/doc/source/source_rst/software/monitoring.rst
deleted file mode 100644
index 3d4d8c76..00000000
--- a/doc/source/source_rst/software/monitoring.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-Monitoring application
-**********************
-
-This section details ways to automate measurement acquisition in order to set up the OhmPi as a monitoring tool.
-
-Repeated acquisition at fixed intervals
-=======================================
-Example run_multiple sequence script
-
-Scheduled acquisition using crontab
-===================================
-Example run_sequence script and crontab screenshot
-
-IoT acquisition and sensor trigger
-==================================
-Example node-red experiment
\ No newline at end of file
diff --git a/doc/source/source_rst/software/operations.rst b/doc/source/source_rst/software/operations.rst
deleted file mode 100644
index 1cd3af85..00000000
--- a/doc/source/source_rst/software/operations.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-Operation
-#########
-
-This section details describes how to operate an OhmPi instrument.
-
-.. toctree::
- :maxdepth: 2
-
- config
- interfaces
- loggers
-
-
diff --git a/doc/source/source_rst/software/operations/config.rst b/doc/source/source_rst/software/operations/config.rst
index 15d6b455..d4c49cfd 100644
--- a/doc/source/source_rst/software/operations/config.rst
+++ b/doc/source/source_rst/software/operations/config.rst
@@ -63,7 +63,7 @@ The configuration is written in a python file structured in a series of dictionn
#. HARDWARE_CONFIG: the hardware system in which the five different modules 'ctl' (controller), 'tx' (transmitter), 'rx' (receiver), 'mux' (multiplexers), 'pwr' (power).
.. code-block:: python
- :caption: Dictionnary containing the configuration of the hardware system.
+ :caption: Dictionary containing the configuration of the hardware system.
r_shunt = 2.
HARDWARE_CONFIG = {
@@ -101,12 +101,10 @@ The configuration is written in a python file structured in a series of dictionn
}
}
-#. the logging dictionnaries divided in:
-
- * EXEC_LOGGING_CONFIG
+#. the logging dictionaries divided in:
.. code-block:: python
- :caption: Dictionnary containing the configuration of the hardware system.
+ :caption: EXEC_LOGGING_CONFIG
# SET THE LOGGING LEVELS, MQTT BROKERS AND MQTT OPTIONS ACCORDING TO YOUR NEEDS
# Execution logging configuration
@@ -121,10 +119,10 @@ The configuration is written in a python file structured in a series of dictionn
'interval': 1
}
- * DATA_LOGGING_CONFIG
+*
.. code-block:: python
- :caption: Dictionnary containing the configuration of the hardware system.
+ :caption: DATA_LOGGING_CONFIG
# Data logging configuration
DATA_LOGGING_CONFIG = {
@@ -140,7 +138,7 @@ The configuration is written in a python file structured in a series of dictionn
* SOH_LOGGING_CONFIG
.. code-block:: python
- :caption: Dictionnary containing the configuration of the hardware system.
+ :caption: Dictionary containing the configuration of the hardware system.
# State of Health logging configuration (For a future release)
SOH_LOGGING_CONFIG = {
'logging_level': logging.INFO,
@@ -154,13 +152,10 @@ The configuration is written in a python file structured in a series of dictionn
}
-#. the MQTT dictionnaries divided in:
-
- * MQTT_LOGGING_CONFIG
+#. the MQTT dictionaries divided in:
.. code-block:: python
- :caption: Dictionnary containing the configuration of the hardware system.
-
+ :caption: MQTT_LOGGING_CONFIG
# MQTT logging configuration parameters
MQTT_LOGGING_CONFIG = {
@@ -184,10 +179,8 @@ The configuration is written in a python file structured in a series of dictionn
}
- * MQTT_CONTROL_CONFIG
-
.. code-block:: python
- :caption: Dictionnary containing the configuration of the hardware system.
+ :caption: MQTT_CONTROL_CONFIG
# MQTT control configuration parameters
MQTT_CONTROL_CONFIG = {
diff --git a/doc/source/source_rst/software/operations/index.rst b/doc/source/source_rst/software/operations/index.rst
index e96ab18f..dbed05b0 100644
--- a/doc/source/source_rst/software/operations/index.rst
+++ b/doc/source/source_rst/software/operations/index.rst
@@ -1,5 +1,5 @@
-Operation
-#########
+Operating the system
+####################
This section details describes how to operate an OhmPi instrument.
@@ -12,5 +12,6 @@ Contents:
interfaces
settings
loggers
+ monitoring
diff --git a/doc/source/source_rst/software/operations/interfaces.rst b/doc/source/source_rst/software/operations/interfaces.rst
index 03289028..910561a3 100644
--- a/doc/source/source_rst/software/operations/interfaces.rst
+++ b/doc/source/source_rst/software/operations/interfaces.rst
@@ -1,12 +1,10 @@
Interfaces
**********
-Different interfaces can be used to interact with the OhmPi.
-
-Available interfaces are:
-- `Web interface`_ (=HTTP interface): run in bash: `bash run_http_interface.sh`
-- Python API: import the OhmPi class from Python script: `from ohmpi import OhmPi` (see `Python interface`_)
-- MQTT: IoT messaging through a broker (see `MQTT interface`_)
+Three interfaces can be used to interact with the OhmPi:
+* a `Web interface`_: user friendly graphical interface to achieve basic operations for everyday use, such as running a sequence or repeated sequences.
+* a `Python interface`_: based on the `api`_, the Python interface allows basic and more advanced operations such as custom acquisition strategies and automation.
+* a `IoT interface`_: based on the MQTT messaging protocol used in IoT, it is a framework to incorporate the OhmPi system within complex experiments designs comprising other IoT sensors.
Web interface
@@ -83,12 +81,6 @@ To access the Python API, make sure that the PYTHONPATH has been correctly confi
# time.sleep(2)
# k.interrupt() # kill the asynchron sequence
- ### Run multiple sequences at given time interval
- k.settings['nb_meas'] = 3 # run sequence three times
- k.settings['sequence_delay'] = 100 # every 100 s
- k.run_multiple_sequences() # asynchron
- # k.interrupt() # kill the asynchron sequence
-
### Single measurement can also be taken with
quadrupole = [1, 4, 2, 3]
k.run_measurement(quadrupole) # use default acquisition parameters
diff --git a/doc/source/source_rst/software/operations/monitoring.rst b/doc/source/source_rst/software/operations/monitoring.rst
new file mode 100644
index 00000000..198734de
--- /dev/null
+++ b/doc/source/source_rst/software/operations/monitoring.rst
@@ -0,0 +1,23 @@
+Monitoring application
+**********************
+
+This section details ways to automate measurement acquisition in order to set up the OhmPi as a monitoring tool.
+
+Repeated acquisition at fixed intervals
+=======================================
+The easiest way to set up time-lapse acquisition is to perform repeated acquisition of a sequence at fixed intervals.
+Repeated acquisition can be initiated from the three different `interfaces`_.
+
+ ### Run multiple sequences at given time interval
+ k.settings['nb_meas'] = 3 # run sequence three times
+ k.settings['sequence_delay'] = 100 # every 100 s
+ k.run_multiple_sequences() # asynchron
+ # k.interrupt() # kill the asynchron sequence
+
+Scheduled acquisition using crontab
+===================================
+Example run_sequence script and crontab screenshot
+
+IoT acquisition and sensor trigger
+==================================
+Example node-red experiment
\ No newline at end of file
diff --git a/doc/source/source_rst/software/operations/settings.rst b/doc/source/source_rst/software/operations/settings.rst
index dee64482..29a6e8d6 100644
--- a/doc/source/source_rst/software/operations/settings.rst
+++ b/doc/source/source_rst/software/operations/settings.rst
@@ -1,11 +1,10 @@
-.. _settings:
Acquisition settings
********************
This section details the acquisition settings that can be specified for measurement on a quadrupole.
-.. code-block:: json
- :caption: Dictionnary containing the default settings contained in ´settings/default.json`
+.. code-block:: python
+ :caption: json dictionary containing the default settings contained in ´settings/default.json`
{
"injection_duration": 0.2, # injection duration of one pulse within an injection cycl
@@ -24,7 +23,7 @@ This section details the acquisition settings that can be specified for measurem
For more information on these settings, see the API doc for :func:`ohmpi.ohmpi.OhmPi.run_measurement`, :func:`ohmpi.ohmpi.OhmPi.run_measurement` and :func:`ohmpi.ohmpi.OhmPi.run_measurement`
In addition to these default settings, and for advanced users, additional settings related to the injection strategy "vmax" and "vmin" can also be specified in the json settings file as follows:
-.. code-block:: json
+.. code-block:: python
:caption: Dictionnary containing the default settings contained in ´settings/default.json`
{
@@ -34,5 +33,4 @@ In addition to these default settings, and for advanced users, additional settin
"vmn_min": null, # minimum V_mn (in mV) bounding the vmax injection strategy. Value is capped by vmn_min from hardware config. Default is None, which means vmax strategy bounded by hardware vmn_min from hardware config.
}
-For more information on these settings, see the API donc for :func:`ohmpi.ohmpi.OhmPi.run_measurement`.
-:py:meth;`ohmpi.ohmpi.OhmPi.run_measurement`.
+For more information on these settings, see the API donc for :func:`OhmPi.run_measurement`.
\ No newline at end of file
--
GitLab