corrections of mb.2024.rst

doc/build/html/_sources/index.rst.txt

@@ -36,8 +36,8 @@ Contents:
    source_rst/Ohmpi
    source_rst/hardware
    source_rst/software
-   source_rst/api
    source_rst/troubleshooting
+   source_rst/developments
    source_rst/gallery
    source_rst/developing_hardware_components
    source_rst/archived_version

doc/build/html/_sources/source_rst/developments.rst.txt

+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

doc/build/html/_sources/source_rst/software.rst.txt

@@ -9,7 +9,9 @@ This section details describes the Python software and how to interact with an O
 .. toctree::
 
    Software architecture <software/architecture>
-   Installation <software/installation>
-   Operating the instrument <software/operations>
-   How to contribute <software/developments>
+   Getting started <software/installation>
+   Operation <software/operations>
+   Monitoring <software/monitoring>
+   API reference <software/api>
+
 

doc/build/html/_sources/source_rst/software/api.rst.txt

+API reference
+#############
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+.. automodule:: ohmpi.ohmpi
+   :members:
+
+.. automodule:: ohmpi.hardware_system
+   :members:

doc/build/html/_sources/source_rst/software/architecture.rst.txt

 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
 communication protocols (e.g. MQTT) and/or directly through the Python API.
 
-.. figure:: ../../img/architecture.png
+.. figure:: ../../img/software/ohmpi_2024_architecture.png
 
      Software architecture of OhmPi V2024.
 
 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
+
+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.
\ No newline at end of file
+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

doc/build/html/_sources/source_rst/software/installation.rst.txt

-Installation
-************
+Getting started
+***************
 
-Step 1: Connect to the Raspberry Pi
-===================================
+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
+
+Then connect to the Raspberry Pi either via ssh or using an external monitor.
+
+For all questions related to Raspberry Pi operations, please refer to the official documentation_.
+.. _documentation: https://www.raspberrypi.com/documentation/
 
 Step 2: Clone the OhmPi project
 ===============================
 
+You need to clone the OhmPi repository on the Raspberry Pi with the following command:
+.. code-block:: bash
+
+   $ git clone https://gitlab.irstea.fr/reversaal/OhmPi.git
+
 Step 3: Run the installation script
 ===================================
 
@@ -46,4 +58,6 @@ If you need to leave the virtual environment, simply type:
 
 .. code-block:: bash
    
-   $ deactivate
+   $ deactivate
\ No newline at end of file
+
+Following these steps, you are now ready to operate the OhmPi.
\ No newline at end of file

doc/build/html/_sources/source_rst/software/monitoring.rst.txt

+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

doc/build/html/_sources/source_rst/software/operations.rst.txt

+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).

doc/build/html/genindex.html

@@ -43,8 +43,8 @@
 <li class="toctree-l1"><a class="reference internal" href="source_rst/Ohmpi.html">OhmPi project</a></li>
 <li class="toctree-l1"><a class="reference internal" href="source_rst/hardware.html">Hardware</a></li>
 <li class="toctree-l1"><a class="reference internal" href="source_rst/software.html">Software and operation</a></li>
-<li class="toctree-l1"><a class="reference internal" href="source_rst/api.html">API reference</a></li>
 <li class="toctree-l1"><a class="reference internal" href="source_rst/troubleshooting.html">Troubleshooting</a></li>
+<li class="toctree-l1"><a class="reference internal" href="source_rst/developments.html">How to contribute</a></li>
 <li class="toctree-l1"><a class="reference internal" href="source_rst/gallery.html">Examples of applications</a></li>
 <li class="toctree-l1"><a class="reference internal" href="source_rst/developing_hardware_components.html">Software interface to new hardware components</a></li>
 <li class="toctree-l1"><a class="reference internal" href="source_rst/archived_version.html">Archived versions</a></li>

doc/build/html/index.html

@@ -45,8 +45,8 @@
 <li class="toctree-l1"><a class="reference internal" href="source_rst/Ohmpi.html">OhmPi project</a></li>
 <li class="toctree-l1"><a class="reference internal" href="source_rst/hardware.html">Hardware</a></li>
 <li class="toctree-l1"><a class="reference internal" href="source_rst/software.html">Software and operation</a></li>
-<li class="toctree-l1"><a class="reference internal" href="source_rst/api.html">API reference</a></li>
 <li class="toctree-l1"><a class="reference internal" href="source_rst/troubleshooting.html">Troubleshooting</a></li>
+<li class="toctree-l1"><a class="reference internal" href="source_rst/developments.html">How to contribute</a></li>
 <li class="toctree-l1"><a class="reference internal" href="source_rst/gallery.html">Examples of applications</a></li>
 <li class="toctree-l1"><a class="reference internal" href="source_rst/developing_hardware_components.html">Software interface to new hardware components</a></li>
 <li class="toctree-l1"><a class="reference internal" href="source_rst/archived_version.html">Archived versions</a></li>
@@ -85,7 +85,7 @@
 <dd class="field-odd"><p>v2024rc</p>
 </dd>
 <dt class="field-even">Date<span class="colon">:</span></dt>
-<dd class="field-even"><p>Jan 09, 2024</p>
+<dd class="field-even"><p>Jan 11, 2024</p>
 </dd>
 <dt class="field-odd">Date start<span class="colon">:</span></dt>
 <dd class="field-odd"><p>July 2016</p>
@@ -132,12 +132,10 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="source_rst/software.html">Software and operation</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="source_rst/software/architecture.html">Software architecture</a></li>
-<li class="toctree-l2"><a class="reference internal" href="source_rst/software/installation.html">Installation</a></li>
-<li class="toctree-l2"><a class="reference internal" href="source_rst/software/operations.html">Configuration file</a></li>
-<li class="toctree-l2"><a class="reference internal" href="source_rst/software/operations.html#interfaces-and-applications">Interfaces and applications</a></li>
-</ul>
-</li>
-<li class="toctree-l1"><a class="reference internal" href="source_rst/api.html">API reference</a><ul class="simple">
+<li class="toctree-l2"><a class="reference internal" href="source_rst/software/installation.html">Getting started</a></li>
+<li class="toctree-l2"><a class="reference internal" href="source_rst/software/operations.html">Operation</a></li>
+<li class="toctree-l2"><a class="reference internal" href="source_rst/software/monitoring.html">Monitoring</a></li>
+<li class="toctree-l2"><a class="reference internal" href="source_rst/software/api.html">API reference</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="source_rst/troubleshooting.html">Troubleshooting</a><ul>
@@ -146,6 +144,13 @@
 <li class="toctree-l2"><a class="reference internal" href="source_rst/troubleshooting.html#communication-issue-between-components">Communication issue between components</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="source_rst/developments.html">How to contribute</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="source_rst/developments.html#developing-hardware-components">Developing hardware components</a></li>
+<li class="toctree-l2"><a class="reference internal" href="source_rst/developments.html#developing-software-features">Developing software features</a></li>
+<li class="toctree-l2"><a class="reference internal" href="source_rst/developments.html#software-interface-to-new-hardware-components">Software interface to new hardware components</a></li>
+<li class="toctree-l2"><a class="reference internal" href="source_rst/developments.html#hardware-components-api">Hardware components API</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="source_rst/gallery.html">Examples of applications</a></li>
 <li class="toctree-l1"><a class="reference internal" href="source_rst/developing_hardware_components.html">Software interface to new hardware components</a></li>
 <li class="toctree-l1"><a class="reference internal" href="source_rst/archived_version.html">Archived versions</a><ul>