powerapi-ng · roda82 · Oct 4, 2024 · Oct 4, 2024 · Oct 7, 2024 · Oct 8, 2024
diff --git a/README.md b/README.md
@@ -2,3 +2,23 @@
 PowerAPI website use [MKDocs](https://www.mkdocs.org/). 
 
 You can push your changes on `master` branch to deploy them on the website. 
+
+## Local development  
+
+When redacting changes for this documentation, you may want to visualize the 
+output the way it will be presented in the final website once compiled.  
+
+One way to do so is to:  
+
+1. Install the necessary packages : mkdocs, mkdocs-material, mkdocs-material-extensions  
+This can be done with: `pip install mkdocs mkdocs-material mkdocs-material-extensions`  
+
+2. Have a local copy of this repository (taking care of *checkout-ing* the right ref)  
+
+3. From the CLI, have this particular repository as PWD  
+
+4. Use mkdocs in order to serve locally (default on http://localhost:8000)  
+This can be done with: `mkdocs serve -o`  
+
+5. Check the URL it serves to, targets will be rebuild on modifications in the 
+current directory or in any nested elements (use -W to add paths to be considered for hot reloading)  
diff --git a/docs/about.md b/docs/about.md
@@ -0,0 +1,57 @@
+# About Us
+
+## History
+
+PowerAPI was initiated in 2011 by the [ADAM project](http://adam.lille.inria.fr/pmwiki.php/Adam/HomePage.html) team at the [Inria Center of the University of Lille](https://www.inria.fr/fr/centre-inria-de-luniversite-de-lille). The primary motivation was to create a tool that could estimate the energy consumption of software processes without relying on external hardware like wattmeters. This need arose from the limitations of existing tools, which often lacked configurability and required hardware-based measurements.
+
+The initial version of PowerAPI was developed in [Scala](https://www.scala-lang.org/), utilizing the [Akka library](https://doc.akka.io/libraries/akka-core/current/typed/guide/modules.html) for its modular and asynchronous event-driven architecture. This design allowed users to monitor energy consumption at the process level by analyzing hardware resource utilization such as CPU, memory, disk, and network usage. The modularity of PowerAPI enabled users to customize their monitoring setups by adding or removing components as needed.
+
+Between 2015 and 2020, PowerAPI saw significant growth in both functionality and adoption. PowerAPI's architecture was refined to support more diverse monitoring scenarios, including virtual machines and containerized environments.
+
+Since 2021, recognizing the need for broader accessibility and integration with modern software ecosystems, the PowerAPI team initiated a transition from Scala to Python. This shift aimed to leverage Python's widespread use in data science and machine learning communities, facilitating easier adoption and extension of the toolkit.
+
+The Python-based version of PowerAPI introduced several enhancements:
+
+- Improved Extensibility: The new architecture allowed for easier integration of custom sensors and estimation models, accommodating a wider range of monitoring scenarios.
+
+- Real-Time Monitoring: PowerAPI continued to provide real-time energy consumption estimates, now with improved accuracy and support for additional data sources.
+
+- Integration with Visualization Tools: The toolkit offered compatibility with visualization platforms like [Grafana](https://grafana.com/) and [Prometheus](https://prometheus.io/), enabling users to create comprehensive dashboards for energy monitoring.
+
+In June 2022 a Consortium was created for supporting this development and maintenance with 4 founding members: [Inria](https://www.inria.fr/fr), [Orange Labs](https://lelab.orange.fr/), [Ovh Cloud](https://www.ovhcloud.com/fr/) and [Davidson Consulting](https://www.davidson.fr/). The continued evolution of PowerAPI reflects its commitment to advancing energy-aware software development practices.
+
+
+## Consortium members
+
+<div class="sponsors" markdown>
+
+|[![Inria](assets/images/intro/inria.png){ width="309px" }](https://www.inria.fr/fr)|
+|:-----:|
+|Since June 2022|
+
+|[![Orange Labs](assets/images/intro/logo-orange.png){ width="338px" }](https://lelab.orange.fr/)|    
+|:-----:|
+|Since June 2022|
+
+|[![OVH Cloud](assets/images/intro/ovh-cloud.jpeg){ width="225px" }](https://www.ovhcloud.com/fr/)|
+|:-----:|
+|Since June 2022|
+
+|[![La Poste Groupe](assets/images/intro/la-poste-groupe.jpg){ width="300px" }](https://www.lapostegroupe.com/fr)|
+|:-----:|
+|Since October 2023|
+
+</div>
+
+## Past Consortium members
+
+<div style="text-align: center" markdown>
+|[![Davidson Consulting](assets/images/intro/davidson.png){ width="400px" }](https://www.davidson.fr/)|
+|:-----:|
+|From June 2022 to December 2024|
+</div>
+
+
+## How to join the Consortium
+
+If you are interested in join the Consortium please send us an <a href="mailto:powerapi-staff@inria.fr" target="_blank" rel="noopener" title="">email</a>.
diff --git a/docs/assets/images/reference/overview/global-architecture.jpg b/docs/assets/images/reference/overview/global-architecture.jpg
diff --git a/docs/assets/images/reference/sensors/PowerAPI_HWPCSensorOverview.drawio b/docs/assets/images/reference/sensors/PowerAPI_HWPCSensorOverview.drawio
diff --git a/docs/assets/images/reference/sensors/PowerAPI_HWPCSensorOverview.drawio.svg b/docs/assets/images/reference/sensors/PowerAPI_HWPCSensorOverview.drawio.svg
diff --git a/docs/getting_started.md b/docs/getting_started.md
@@ -1,57 +1,54 @@
 # Getting started
 
-If you want to monitor the energy consumption of your process we have some
-ready-to-use tools
+In this tutorial, we will guide you through the first steps to get started with PowerAPI.
+The objective is to get a quick view of the capabilities of PowerAPI.
+A few things are required before we start:
 
-???+ info "Source and Destination"
-    In order to use any Formula, you need to run a Source and a Destination. The former is used by a Sensor to store metrics. The later allows the Formula to make available the estimations. For starting, you can use [MongoDB](https://hub.docker.com/_/mongo) as Source and [InfluxDB:2.X](https://hub.docker.com/_/influxdb) as Destination by installing them as Docker containers.
-    For more details about Sources and Destinations please check this [section](reference/database/sources_destinations.md).
+- A compatible processor (you can see the compatible CPU architecture [here](reference/sensors/hwpc-sensor.md#)). You can take a look on the following links to find your CPU architecture:  
+    * For [Intel Processor](https://en.wikipedia.org/wiki/List_of_Intel_processors).  
+    * For [Intel Xeon Processor](https://en.wikipedia.org/wiki/List_of_Intel_Xeon_processors).  
+    * For [AMD Processor](https://en.wikipedia.org/wiki/Table_of_AMD_processors).  
+- You can also use the `lscpu` command to get information about your processor.
+- Docker & Docker-Compose ready (refer to [this official documentation](https://docs.docker.com/engine/install/) and the [post-install steps](https://docs.docker.com/engine/install/linux-postinstall/) if needed!).
+- Root access.
 
+## Which components to get a complete stack  
 
-<!---
-## **RAPL Formula**
 
-!!! note ""
-    for monitoring the energy consumption of your device
+The complete stack of PowerAPI is composed of:
 
-RAPL Formula is made for tracking the energy consumption of your machine.
-To install RAPL Formula on a baremetal server or a PC run [the following
-script](script/rapl_install.sh) in a Terminal.
+- A Sensor and a Formula that enable us to define a Software Power Meter. The Sensor retrieves power consumption related metrics and the Formula compute an estimation of the power consumption. Currently, PowerAPI provides [HWPC-Sensor](reference/sensors/hwpc-sensor.md) and [SmartWatts Formula](reference/formulas/smartwatts.md)
 
-The script explains what it will do and then pauses before it does it.
+- The Sensor and the Formula need an *output*. The supported *output* are listed [here](reference/sensors/hwpc-sensor.md/#output). The Formula will also use the Sensor *output* as its *input*.
 
-Please notice that you need a **Linux distribution** in order to use the HWPC Sensor installed by the script as
-well as a **comptible Intel** (Sandy Bridge and newer) or **AMD Processor** (Zen). **Power/ARM/RISCV are not supported** architectures. HWPC Sensor will **not work on a Virtual Machine**. However, you can install the Formula by hand in a Virtual Machine if need it.
--->
+- Finally, they need a configuration as described in the [HWPC-Sensor](reference/sensors/hwpc-sensor.md#global-parameters) and [SmartWatts](reference/formulas/smartwatts.md#global-parameters) documentation. The configuration parameters can be defined via a configuration file or via the CLI.
 
-## **SmartWatts Formula**
+To learn more see the [overview section](./reference/overview.md).
 
-!!! note ""
-    for monitoring the power consumption of your process
 
-Smartwatts is made for tracking the power consumption of processes on a
-machine.
-To install Smartwatts on a baremetal server or a PC run [the following
-script](script/smartwatts_install.sh) in a Terminal. Please notice that you will need [pip](https://pip.pypa.io/en/stable/installation/) or [docker](https://docs.docker.com/engine/install/) in order to use the Formula.
+## Executing a Software PowerMeter
 
-The script explains what it will do and then pauses before it does it.
+The following command allow you to setup and run a software PowerMeter by using HWPC-Sensor and SmartWatts Formula via Docker.
 
-Please notice that you need a **Linux distribution** in order to use the HWPC Sensor installed by the script as
-well as a **comptible Intel** (Sandy Bridge and newer) or **AMD Processor** (Zen). You also need [docker](https://docs.docker.com/engine/install/).  **Power/ARM/RISCV are not supported** architectures. HWPC Sensor will **not work on a Virtual Machine**. However, you can install the Formula by hand in a Virtual Machine if need it.
+```sh
+curl -sSL https://raw.githubusercontent.com/Inkedstinct/powerapi-ng.github.io/refs/heads/7_doc/nld_proofread/docs/script/getting_started/curl_version/start.sh | bash
+```
 
+This command will run [this script](script/getting_started/curl_version/start.sh). It will detect the CPU used, and download the appropriate Docker compose file and environment file for your configuration.
 
+It will then execute the Docker compose file, deploying the following elements for 3 minutes:
 
-#### CGroups
-If you need to monitor a process or a group of process via SmartWatts by using HWPC Sensor **version 1.2 or older**, you can follow this [tutorial](reference/cgroup/cgroup.md). Please notice that **cgroup V1** is required **only** for HWPC Sensor **version 1.2 or older**. If you need to enable this `cgroup` version please follow this [tutorial](reference/cgroup/cgroup_v1_activation.md).    
+1. A MongoDB instance to store the [Sensor](reference/sensors/hwpc-sensor.md) reports.
 
-<!---
-## **Jouleit**
+2. An [HWPC-Sensor](reference/sensors/hwpc-sensor.md) that outputs its
+[HWPC Reports](reference/reports/reports.md#hwpc-reports) in a MongoDB Database,
+within the HWPC Report Collection
 
-!!! note ""
-    for mesuring the energy consumption of a program
+3. A [SmartWatts](reference/formulas/smartwatts.md) that streams the
+[HWPC Reports](reference/reports/reports.md#hwpc-reports) from the MongoDB
+Database Collection, processes it and outputs its
+[Power Reports](reference/reports/reports.md#power-reports) into CSV.
 
-Jouleit is made for tracking the energy consumption of a program.
-Jouleit need `gawk` to run.
-You can get the script from the [github repository](https://github.com/powerapi-ng/jouleit)
-Start jouleit by using `./jouleit.sh cmd`.
--->
+In this specific use case, we  use the CLI to set the configuration parameters in the Docker compose file.
+
+After the execution of  result will be visible under the *csv* directory.
diff --git a/docs/publications.md b/docs/publications.md
@@ -3,6 +3,35 @@ hide:
   - navigation
   - toc
 ---
+
+# How to cite PowerAPI
+
+If you use PowerAPI in a scientific publication, please cite:
+
+ - *Guillaume Fieni, Daniel Romero Acero, Pierre Rust, Romain Rouvoy*. [**PowerAPI: A Python framework for building software-defined power meters**](https://joss.theoj.org/papers/10.21105/joss.06670#). Journal of Open Source Software, 2024, 9 (98), pp.6670. [⟨10.21105/joss.06670⟩](https://dx.doi.org/10.21105/joss.06670). [⟨hal-04601379⟩](https://hal.science/hal-04601379)
+
+
+Bibtex entry:
+
+```
+@article{fieni-2024,
+TITLE = {{PowerAPI: A Python framework for building software-defined power meters}},
+AUTHOR = {Fieni, Guillaume and Acero, Daniel Romero and Rust, Pierre and Rouvoy, Romain},
+URL = {https://hal.science/hal-04601379},
+JOURNAL = {{Journal of Open Source Software}},
+PUBLISHER = {{Open Journals}},
+VOLUME = {9},
+NUMBER = {98},
+PAGES = {6670},
+YEAR = {2024},
+MONTH = Jun,
+DOI = {10.21105/joss.06670},
+KEYWORDS = {Power ; Energy ; Toolkit ; Measurement ; Framework},
+PDF = {https://hal.science/hal-04601379/file/10.21105.joss.06670-3.pdf},
+HAL_ID = {hal-04601379},
+HAL_VERSION = {v1},
+}
+```
 # Publications
 
 - **[PowerAPI: A Python framework for building software-defined power meters](https://hal.science/hal-04601379)**: G. Fieni, D. Romero Acero, P. Rust, R. Rouvoy. _[Journal of Open Source Software](https://joss.theoj.org)_. 9(98):6670, June 2024.