From afb3fafea82ee845ef0eb010a9786461bff14317 Mon Sep 17 00:00:00 2001
From: Arnaud Watlet <arnaud.watlet@umons.ac.be>
Date: Thu, 11 Jan 2024 09:14:45 +0100
Subject: [PATCH] Updates software doc
---
doc/source/source_rst/api.rst | 10 ---
doc/source/source_rst/developments.rst | 80 +++++++++++++++++++
doc/source/source_rst/software/api.rst | 12 +++
.../source_rst/software/architecture.rst | 45 ++++++-----
.../source_rst/software/developments.rst | 0
.../source_rst/software/installation.rst | 4 +-
doc/source/source_rst/software/monitoring.rst | 16 ++++
doc/source/source_rst/software/operations.rst | 56 ++++++-------
8 files changed, 156 insertions(+), 67 deletions(-)
delete mode 100644 doc/source/source_rst/api.rst
create mode 100644 doc/source/source_rst/developments.rst
create mode 100644 doc/source/source_rst/software/api.rst
delete mode 100644 doc/source/source_rst/software/developments.rst
create mode 100644 doc/source/source_rst/software/monitoring.rst
diff --git a/doc/source/source_rst/api.rst b/doc/source/source_rst/api.rst
deleted file mode 100644
index 447c042c..00000000
--- a/doc/source/source_rst/api.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-API reference
-=============
-.. toctree::
- :maxdepth: 2
- :caption: Contents:
-
-.. automodule:: ohmpi.ohmpi
- :members:
-
-
diff --git a/doc/source/source_rst/developments.rst b/doc/source/source_rst/developments.rst
new file mode 100644
index 00000000..27156924
--- /dev/null
+++ b/doc/source/source_rst/developments.rst
@@ -0,0 +1,80 @@
+How to contribute
+#################
+
+OhmPi is an open source system and contributions in terms of hardware and software are welcome. However, in order to
+maintain the project on tracks and promote exchange and reuse, it is necessary that contributors
+wishing to develop new software or hardware components follow a few basic steps detailed below.
+Contributors are also kindly asked to get in touch with the OhmPi developing team.
+
+Developing hardware components
+******************************
+Here is a non exhaustive wish list of new hardware features that are planned/hoped to be developed in the future.
+Contributors are welcomed to join forces to make this list come true, or propose new ideas by creating a new issue in the Gitlab repository.
+
+Wish list of hardware developments:
+- Automatic selection of shunt resistors in a set of shunt resistances (hardware)
+- Add analog low-pass filter on receiver (hardware)
+- Battery recharge manager for monitoring (hardware)
+- Multi-channel acquisition (hardware)
+- Control OhmPi via microcontroller (hardware)
+
+Developing software features
+****************************
+If the new developments purely concern the software (e.g. bug fix, new acquisition strategy, etc.), then please follow the
+git best practices by first creating an new issue and then create a local branch linked to this issue. Once the new feature is implemented, a pull request can be initiated.
+
+Here is a series of software developments that are planned/hoped:
+- Sequence generator (software)
+- Calculate time-variable SP effects (software)
+- Calculate IP from full-waveform (software)
+- Pseudo multi-channel acquisition (software)
+
+Software interface to new hardware components
+*********************************************
+This section is intended for developers of a new hardware component as part of an OhmPi system.
+
+It presents some advices and best practices that should help developing new hardware components to work
+within an OhmPi system.
+
+Two cases should be distinguished when dealing with hardware development components:
+
+1- Developments of a hardware component that comply with the way the OhmPi Hardware System works. Such developments typically
+focus on improving an existing component (reduce cost, improve performance, adapt range to specific applications,
+design with easily available parts...). The newly created hardware component will expose the minimal functionalities required
+by hardware_system for this type of component.
+
+2- Developments of a hardware component that introduce changes in the way the OhmPi Hardware System works. Such
+developments do not only focus on improving a single component but also on the way to operate the system. A
+discussion with developers of the OhmPi_Hardware and OhmPi classes should be initiated at a very early stage to investigate
+the best ways to design and implement a working solution.
+
+If you are dealing with case 1 or have designed a development path and strategy, you are ready to start.
+
+First the hardware board/device should be conceived and designed. The Ohmpi team recommends that contributors design or
+import their boards within KiCAD and that both schemas and PCB are shared.
+
+When developing a new component Class, always start your development in a new branch.
+1- Create a new python file or make a copy and modify an existing similar component file. All hardware component modules
+are stored in the ohmpi/hardware_component directory.
+In the newly created python file, define a new class based on the relevant abstract class of abstract_hardware_components.py.
+Implement the abstract methods to interact with your hardware. Name the file according to the name of the component.
+Make sure to place this new python module in the ohmpi/hardware_component directory.
+
+2- Create a new configuration file or make a copy and modify an existing configuration file. All existing config files
+are stored in the ohmpi/hardware_component directory.
+In this newly created config file, describe your system including the new component in the HARDWARE_CONFIG dictionary.
+Name it config_XXX.py where XXX should be replaced by an expression describing the system.
+Make sure to place your new config file in the ohmpi/configs directory.
+
+3- Create a new script or make a copy and modify of an existing script for testing the component.
+In this script, write python code where you will conduct the tests of the required functionalities of the new component.
+
+Hardware components API
+***********************
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+.. automodule:: ohmpi.hardware_components
+ :members:
\ No newline at end of file
diff --git a/doc/source/source_rst/software/api.rst b/doc/source/source_rst/software/api.rst
new file mode 100644
index 00000000..262bd87f
--- /dev/null
+++ b/doc/source/source_rst/software/api.rst
@@ -0,0 +1,12 @@
+API reference
+#############
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+.. automodule:: ohmpi.ohmpi.OhmPi
+ :members:
+
+.. automodule:: ohmpi.hardware_system.OhmPiHardware
+ :members:
diff --git a/doc/source/source_rst/software/architecture.rst b/doc/source/source_rst/software/architecture.rst
index 36e5d323..1f264b3b 100644
--- a/doc/source/source_rst/software/architecture.rst
+++ b/doc/source/source_rst/software/architecture.rst
@@ -1,5 +1,5 @@
Software architecture
-*********************
+#####################
The OhmPi V2024 software has been completely re-structured to enable increased flexibility for both users and developers. The software is based on an object-oriented module with a class exposing the OhmPi
functionalities used to interact with the OhmPi instrument via a web interface, IoT
@@ -12,21 +12,17 @@ communication protocols (e.g. MQTT) and/or directly through the Python API.
The software is organised in several modules describing the system in a hierarchy including three levels of description and
operation of the OhmPi.
-Hardware components
-===================
-On the base level, the five main hardware components are represented by distinct classes exposing the
-components atomic functionalities. Theses classes are abstract classes in order to provide a common
-interface for different implementations of a component. From these abstract classes concrete classes
-are implemented representing the default properties, actual capabilities and ways to interact with the
-physical modules or boards.
-Improving an existing hardware component or introducing a new design may be desirable in order to,
-e.g. reduce costs, improve performance, adapt measurement range to specific applications, or
-incorporate easily available electronic components. It is at this level that software developments are
-mainly expected to occur following updates on the hardware. The component class should expose the
-minimal functionalities required by the hardware system (see below) for this type of component.
+Acquisition
+***********
+On the top level, the OhmPi class (in ohmpi/ohmpi.py) includes all the higher-level methods and properties allowing to
+operate the system (e.g. acquire measurement sequences). The OhmPi class exposes the user-oriented
+API, generates logs and handles IoT messages. Generic users are expected to interact with the system
+through these higher-level functionalities, which are designed to remain as stable as possible while the
+hardware evolves. Only the introduction of new end-user functionalities should imply new
+developments at this level.
Hardware system
-===============
+***************
On the medium level, the OhmPiHardware class provides a mean to assemble and operate the
acquisition system. The methods of this class orchestrate atomic operations of the system components
in order to expose basic system functionalities such as cross-MUX switching, square wave voltage
@@ -42,11 +38,16 @@ This part of the software architecture should remain stable if the overall syste
evolve. However, the introduction of new functionalities at the system level or radical changes in the
way the components work together will require adaptations at this level.
-Acquisition
-===========
-On the top level, the OhmPi class (in ohmpi/ohmpi.py) includes all the higher-level methods and properties allowing to
-operate the system (e.g. acquire measurement sequences). The OhmPi class exposes the user-oriented
-API, generates logs and handles IoT messages. Generic users are expected to interact with the system
-through these higher-level functionalities, which are designed to remain as stable as possible while the
-hardware evolves. Only the introduction of new end-user functionalities should imply new
-developments at this level. See
\ No newline at end of file
+
+Hardware components
+*******************
+On the base level, the five main hardware components are represented by distinct classes exposing the
+components atomic functionalities. Theses classes are abstract classes in order to provide a common
+interface for different implementations of a component. From these abstract classes concrete classes
+are implemented representing the default properties, actual capabilities and ways to interact with the
+physical modules or boards.
+Improving an existing hardware component or introducing a new design may be desirable in order to,
+e.g. reduce costs, improve performance, adapt measurement range to specific applications, or
+incorporate easily available electronic components. It is at this level that software developments are
+mainly expected to occur following updates on the hardware. The component class should expose the
+minimal functionalities required by the hardware system (see below) for this type of component.
\ No newline at end of file
diff --git a/doc/source/source_rst/software/developments.rst b/doc/source/source_rst/software/developments.rst
deleted file mode 100644
index e69de29b..00000000
diff --git a/doc/source/source_rst/software/installation.rst b/doc/source/source_rst/software/installation.rst
index 95c1f5bc..dea18295 100644
--- a/doc/source/source_rst/software/installation.rst
+++ b/doc/source/source_rst/software/installation.rst
@@ -1,8 +1,8 @@
Getting started
-************
+***************
Step 1: Set up the Raspberry Pi
-==================================
+===============================
First, install an operating system on the Raspberry Pi by following the official instructions_.
.. _instructions` : https://www.raspberrypi.com/documentation/computers/getting-started.html#install-an-operating-system
diff --git a/doc/source/source_rst/software/monitoring.rst b/doc/source/source_rst/software/monitoring.rst
new file mode 100644
index 00000000..3d4d8c76
--- /dev/null
+++ b/doc/source/source_rst/software/monitoring.rst
@@ -0,0 +1,16 @@
+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
index c19b404c..79d3d237 100644
--- a/doc/source/source_rst/software/operations.rst
+++ b/doc/source/source_rst/software/operations.rst
@@ -1,6 +1,8 @@
+Operation
+#########
Configuration file
-==================
+******************
The configuration of the OhmPi file `config.py` allows to configure the OhmPi.
A default version of `config.py` is provided in the repository.
@@ -10,10 +12,8 @@ The configuration includes setting the logging level desired for the different l
One should make sure to understand the parameters before altering them. It is also recommended to keep a copy of the default configuration.
-
-
-Interfaces and applications
-===========================
+Interfaces
+**********
Different interfaces can be used to interact with the OhmPi.
@@ -24,7 +24,7 @@ Available interfaces are:
Web interface
-.............
+=============
This is a user friendly graphical interface for new users as well as running quick and easy acquisitions.
@@ -55,31 +55,21 @@ to access the interface.
Contact resistance check.
-
Python interface
-................
+================
-This interface offers a more direct access to the software components especially well suited for testing or automation on the Raspberry Pi.
+This interface offers a more direct access to the software components, specifically suited for testing or automating acquisition.
-By importing the `OhmPi` class from the ohmpi.py, one can control the OhmPi using interactive IPython.
-Typically, it involves using the terminal or an Python IDE such as Thonny on the Raspberry Pi. One can also connect using
-ssh and run the Python interface (see PuTTY on Windows or ssh command on macOS/Linux).
-
-To access the Python API, make sure the file ohmpi.py is in the same
-directory as where you run the commands/script. The file ohmpi.py can
-be found on the OhmPi gitlab repository. We recommend downloading the
-entire repository as ohmpi.py import other .py files and default configuration
-files (.json and .py).
+By importing the `OhmPi` class from the ohmpi.py, we can control the OhmPi instrument via a Python script or interactively with IPython.
+It involves using the terminal or a Python IDE such as Thonny on the Raspberry Pi. A connection can also be established via
+SSH (see PuTTY on Windows or ssh command on macOS/Linux).
+To access the Python API, make sure that the PYTHONPATH has been correctly configured to export the location of the ohmpi module.
.. code-block:: python
:caption: Example of using the Python API to control OhmPi
- import os
- import numpy as np
- import time
- os.chdir("/home/pi/OhmPi")
- from ohmpi import OhmPi
+ from ohmpi.ohmpi import OhmPi
### Define object from class OhmPi
k = OhmPi() # this loads default parameters from the disk
@@ -114,19 +104,19 @@ files (.json and .py).
# k.interrupt() # kill the asynchron sequence
### Single measurement can also be taken with
- k.switch_mux_on([1, 4, 2, 3])
- k.run_measurement() # use default acquisition parameters
- k.switch_mux_off([1, 4, 2, 3]) # don't forget this! risk of short-circuit
+ quadrupole = [1, 4, 2, 3]
+ k.run_measurement(quadrupole) # use default acquisition parameters
### Custom or adaptative argument, see help(k.run_measurement)
- k.run_measurement(nb_stack=4, # do 4 stacks (8 half-cycles)
- injection_duration=2, # inject for 2 seconds
- autogain=True) # adapt gain of ADS to get good resolution
-
+ k.run_measurement(quadrupole,
+ nb_stack=4, # do 4 stacks (8 half-cycles)
+ injection_duration=1, # inject for 2 seconds
+ duty_cycle = 0.5) # duty_cycle is
+For detailed usage, please see the Python API or look at the examples.
-MQTT interface
-..............
+IoT interface
+=============
This is an interface designed for an advanced remote usage of the OhmPi such as remote automation, data consumption by multiple processes and interaction with other sensors in the scope of a monitoring. It is based on the MQTT protocol, designed for the Internet of Things (IoT), to interact with the OhmPi.
@@ -218,7 +208,7 @@ For more documentation dedicated to node-red, please refer to the Node-red `cook
Loggers
--------
+*******
Loggers have been introduced in this release. They use the excellent logging python package.
Specific handlers have been implemented for running with ohmpi.py (one for logging to an mqtt broker (see `MQTT interface`_ for more details) and one for creating zipped rotated logs on disk).
--
GitLab