feat(content): add plugin carbon

.tx/config

@@ -477,4 +477,56 @@ source_file = build/locale/agent_config/index.pot
 source_lang = en
 type = PO
 
+[o:teclib:p:glpi-plugins-documentation:r:carbon--index]
+file_filter = source/locale/<lang>/LC_MESSAGES/carbon/index.po
+source_file = build/locale/carbon/index.pot
+source_lang = en
+type = PO
+
+[o:teclib:p:glpi-plugins-documentation:r:carbon--carbon_reports]
+file_filter = source/locale/<lang>/LC_MESSAGES/carbon/carbon_reports.po
+source_file = build/locale/carbon/carbon_reports.pot
+source_lang = en
+type = PO
+
+[o:teclib:p:glpi-plugins-documentation:r:carbon--configuration]
+file_filter = source/locale/<lang>/LC_MESSAGES/carbon/configuration.po
+source_file = build/locale/carbon/configuration.pot
+source_lang = en
+type = PO
+
+[o:teclib:p:glpi-plugins-documentation:r:carbon--features]
+file_filter = source/locale/<lang>/LC_MESSAGES/carbon/features.po
+source_file = build/locale/carbon/features.pot
+source_lang = en
+type = PO
+
+[o:teclib:p:glpi-plugins-documentation:r:carbon--installation]
+file_filter = source/locale/<lang>/LC_MESSAGES/carbon/installation.po
+source_file = build/locale/carbon/installation.pot
+source_lang = en
+type = PO
+
+[o:teclib:p:glpi-plugins-documentation:r:carbon--limitations]
+file_filter = source/locale/<lang>/LC_MESSAGES/carbon/limitations.po
+source_file = build/locale/carbon/limitations.pot
+source_lang = en
+type = PO
+
+[o:teclib:p:glpi-plugins-documentation:r:carbon--reading]
+file_filter = source/locale/<lang>/LC_MESSAGES/carbon/reading.po
+source_file = build/locale/carbon/reading.pot
+source_lang = en
+type = PO
+
+[o:teclib:p:glpi-plugins-documentation:r:carbon--recommandations]
+file_filter = source/locale/<lang>/LC_MESSAGES/carbon/recommandations.po
+source_file = build/locale/carbon/recommandations.pot
+source_lang = en
+type = PO
 
+[o:teclib:p:glpi-plugins-documentation:r:carbon--requirements]
+file_filter = source/locale/<lang>/LC_MESSAGES/carbon/requirements.po
+source_file = build/locale/carbon/requirements.pot
+source_lang = en
+type = PO

source/carbon/carbon_reports.rst

@@ -0,0 +1,10 @@
+Carbon reports
+==============
+
+A dashboard is available and customizable.
+Several types of data are available such as monthly carbon emissions, biggest monthly averaged carbon emissions per model, handled assets ratio, etc.
+
+This dashboard works like the classic GLPI dashboard and can be customized in the same way.
+
+.. note:: The plugin is still under development, so some changes are still being made.
+    Since the dashboards are not finalized, we are not yet able to provide you with a visual.

source/carbon/configuration.rst

@@ -0,0 +1,102 @@
+Configuration
+=============
+
+Automatic actions
+-----------------
+
+The plugin requires a working configuration of `automatic actions with CLI mode <https://glpi-user-documentation.readthedocs.io/fr/master/modules/configuration/crontasks.html>`_.
+Check carefully that GLPI scheduler is running every minute.
+
+Downloading carbon intensitiy data
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The plugin implements an automatic action for each data provider. Supported sources are :
+
+* **RTE** for France (free, data back to 2012-01-01)
+* **Electricity Map** for most countries and regions in the world (free access limited to last 24 hours)
+
+When an automatic action runs for the first time it setups supported regions in database. Once done, you may activate downloads for regions of interest.
+
+Enable / disable carbon intensity data download
+-----------------------------------------------
+
+* Navigate in GLPI to **Setup > Dropdowns > box GLPI Carbon > Carbon intensity sources**
+
+.. image:: images/plugin_dropdowns_intensity.png
+    :alt: select carbon in dropdown tab
+    :scale: 38%
+
+* Select a data provider
+* Open the tab **Carbon intensity zones**
+* Find the country you want to check or set
+
+.. image:: images/choose_country.png
+    :alt: select the country
+    :scale: 44%
+
+
+* Toggle the flag **Download enabled** by clicking on its status
+
+.. image:: images/enable_download.png
+    :alt: enable download of the country
+    :scale: 44%
+
+.. note::
+    If the list of regions or countries is empty then you need to run the automatic action of this source first.
+
+
+
+
+Inventory requirements
+----------------------
+
+All assets
+^^^^^^^^^^
+
+1. To calculate the emission of greenhouse gas related to energy consumed during use of your assets, the plugin needs to know when an asset is used for the first time and when its services is stopped.
+
+To do so, the plugin seearches for the following dates on order of decreasing precedence:
+
+* **startup date** (Financial and administrative informations) : **this information is mandatory**
+* **delivery date** (Financial and administrative informations)
+* **date of purchase** (Financial and administrative informations)
+* **creation date in inventory**
+* **modification date in inventory**
+
+.. image:: images/financial_information.png
+    :alt: view financial information
+    :scale: 36%
+
+.. note:: Monitors rely on the location of the computer it is connected to, so there is no need to add it manually
+
+2. The plugin needs to know where is an asset to determine which carbon intensity is applied to its energy consumption. The associated location mist have the field **Country** filled
+
+3. Each asset must be associated with a model so that the plugin can estimate CO2 emissions as closely as possible. This information can be pre-filled from a `template <https://glpi-user-documentation.readthedocs.io/fr/latest/modules/overview/templates.html>`_
+
+.. image:: images/computer_model.png
+    :alt: Asset's model
+    :scale: 45%
+
+
+4. It is preferable that the machines be inventoried by an agent so that the **components** tab is filled in as accurately as possible.
+It is possible to do this manually but the automatic inventory seems more reliable.
+
+.. image:: images/computer_components.png
+    :alt: Asset's components
+    :scale: 43%
+
+Computers
+^^^^^^^^^
+Computers are usually powered on depending on working days and hours. You msut tell when computers are turned on in their tab **Environnemental impact**. In this place you can assign a usege profile which describes how the computers are powered on.
+
+To create an usage profile, go in **Setup > Dropdowns > box GLPI Carbon > Computer usage profiles**.
+
+.. image:: images/plugin_dropdowns.png
+    :alt: select carbon in dropdown tab
+    :scale: 38%
+
+.. image:: images/usage_profile.png
+    :alt: select carbon in dropdown tab
+    :scale: 38%
+
+.. note:: It is considered that the network equipment is on 24/7 and therefore does not have an associated profile

source/carbon/features.rst

@@ -0,0 +1,13 @@
+Features
+--------
+
+* Collect carbon intensity of electricity from various sources
+  * RTE (France)
+  * Electricity Map (most countries and regions of the whole world)
+* Supports constant carbon intensity for the following regions
+  * Quebec
+* Fallbacks to yearly world carbon intensity if no data is available for the region of an asset
+* Estimate consumed energy and carbon emission of assets
+* Show results as charts
+
+.. note:: RTE is free and ElectricityMaps but is very limitative in free version

source/carbon/index.rst

@@ -0,0 +1,16 @@
+Carbon
+============
+
+Carbon is a plugin which helps you to monitor environmental footprint of your asset. The plugins is under active development.
+
+.. toctree::
+   :maxdepth: 2
+
+   requirements
+   features
+   installation
+   configuration
+   reading.rst
+   carbon_reports
+   limitations
+   recommendations

source/carbon/installation.rst

@@ -0,0 +1,39 @@
+Install the Plugin
+------------------
+
+From the marketplace
+^^^^^^^^^^^^^^^^^^^^
+.. warning::
+
+   The plugin is not available in the marketplace yet.
+
+   You can install it manually from the archive.
+
+Manually
+^^^^^^^^
+
+* Uncompress the archive.
+* Move the ``carbon`` directory to the ``<GLPI_ROOT>/plugins`` directory
+* Navigate to the *Configuration > Plugins* page,
+* Install and activate the plugin.
+
+.. warning::
+
+   The plugin's directory must have the same name as the plugin:
+
+     * **Good**: `glpi/plugins/carbon`
+     * **Bad**: `glpi/plugins/carbon-master`
+     * **Bad**: `glpi/plugins/carbon-1.0.0`
+
+   Only one directory must contains the plugin's files of a single plugin in the GLPI plugins directory. **Don't rename the plugin's directory for backup, move it!**
+
+Install plugin dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The plugin requires Boavizta to calculate non-GWP impact of assets. It is recommended to set it up using Docker as described in the README file of the project https://github.com/Boavizta/boaviztapi.
+
+The access URL of this service must be set in the configuration page of the plugin.
+
+.. note::
+
+   The plugin will work without Boavizta, but the non-GWP impact of assets will not be calculated.

source/carbon/limitations.rst

@@ -0,0 +1,49 @@
+Limitations
+============
+
+Carbon intensity of electricity
+-------------------------------------
+
+The plugin can collect carbon intensity from several sources. The accuracy if these datas varies :
+
+- Data from RTE which represents the carbon intensity of electricity production
+- Data from Electricity Map represents the carbon intensity oc electricity consumption (which is more accurate)
+
+.. warning:: Electrcitymaps license keys. Some limitations may apply to free keys. With the free version, electricitymaps only provides intensity history for the last 24 hours.
+
+Dates handling
+--------------
+
+The plugin heavily relies on dates manipulation. Dates stored in its tables are set on time zone configured in general configuration of GLPI (**Setup > General > tab Personnalization**).
+
+Dates are manipulated in the context of automatic actions, this means that changing the above setting **will** impact the timezone of dates manipulates after this change. This may will have an effect charts and reports. It is advised to carefully check the configuration of time zone before starting to use the plugin and avoid any change after it began to download data from external sources.
+
+Daylight saving time
+--------------------
+
+Handling timezones with daylight saving time (DST) is challenging because it is not possible to reliably convert dates from / to UTC.
+
+**Example** :
+France switches from GMT +01:00 to GMT+02:00 in last sunday of march and switches back to GMT+01:00 in last sunday of october. This event occurs at 02:00AM.
+
+Therefore the time 2024-03-01 02:00:00 is not visible in the table of carbon intensities if its date is displayed with time zine Europe/Paris and 2 rows have the same date. However if the timezone is UTC the 2 rows show an interval of 1H.
+
+The reverse occurs on 2023-10-29 02:00:00 where there are two rows with the same date (visible when the table displayed with timezone Europe/Paris) but internally, there is an interval of 1H between them (visible when the table is displayed with UTC)
+
+Not used assets
+---------------
+
+computer
+^^^^^^^^
+
+When a computer is not used it is recommended to remove its usage profile.
+
+Monitor
+^^^^^^^
+
+If there are laptops in the inventory, their internal display may be inventoried. In this case, ensure that it has a model and a type without any power consumption set, or no type or model at all.
+
+Deleted asset
+-------------
+
+GLPI usually handles a trash for assets. A deleted asset will be ignored. When an asset enters or exists the trash then it will be respectively excluded or included in the environmental impact history calculation.

source/carbon/reading.rst

@@ -0,0 +1,66 @@
+Reading datas
+=============
+
+In each asset, an Environmental impact tab is now visible.
+
+.. image:: images/dashboard_view.png
+    :alt: Global view of dashboard
+    :scale: 21%
+
+
+Asset usage
+-----------
+
+You can (for computers) select the appropriate profile as well as the planned lifespan (in months)
+
+.. image:: images/asset_usage.png
+    :alt: Setup the asset usage
+    :scale: 51%
+
+
+Historization status
+--------------------
+
+The logging status tells you whether all requirements are correctly met, ensuring that the data sent by Carbon is as accurate as possible.
+
+.. image:: images/historization_status.png
+    :alt: Read the historization status
+    :scale: 61%
+
+If an item is in red, the plugin will operate in a degraded manner, providing less accurate, aggregated estimation information.
+Data in orange are optional items with a slight impact on data quality
+
+Usage
+-----
+
+A graph displays energy consumption and carbon emissions per month
+
+.. image:: images/usage.png
+    :alt: Read the graph of energy consumption and carbon emissions per month
+    :scale: 49%
+
+* Consumption in appears in red
+* Carbon emissions in green
+
+Using the toolbar at the top right, you can:
+
+* Zoom in/out on a specific period
+* Zoom through a selection
+* Scroll
+* Return to the initial presentation
+* Export (SVG, PNG, CSV)
+
+Additional data, ``gSbeq``, is available.
+These are grams of antimony equivalent. This index is used to measure the depletion of abiotic resources (rare earths, minerals, etc.).
+
+You can reset and calculate this data with the corresponding buttons (There is an automatic action ``UsageImpact`` to set them if they are not already calculated.
+The buttons may be useful to update values after we change an asset property.)
+
+Embodied data
+-------------
+
+In the life cycle of an asset, we can measure the environmental impact associated with its manufacture/destruction/recycling. 
+This data is visible in this insert
+
+.. image:: images/embodied_impact.png
+    :alt: Data summary

source/carbon/recommendations.rst

@@ -0,0 +1,32 @@
+Recommmendations
+----------------
+
+The plugin provides a diagnosis view for supported assets, in the tab Environmental impact. The administrator
+should refer to this page to easily find out which data is missing for a single asset.
+
+Mandatory informations are:
+
+*  A location with a country or a state filled
+*  A startup date or a delivery date
+*  A usage profile for computers
+*  A model or a type
+*  A power consumption in the model or the type of the asset
+*  Financial information enabled with one of the fllowing dates filled (ordered by precedence)
+  * use date
+  * delivery date
+  * order date
+
+.. tip:: It is possible to automatically add carbon intensity zones but under conditions. The asset location field must be written in English and strictly identical to the Bovizta zone field.
+
+  .. image:: images/location_carbon.png
+    :alt: see the location en carbon intensity zones
+    :scale: 49%
+
+  .. image:: images/location_asset.png
+   :alt: Report the location on the asset
+   :scale: 69%
+
+Optional informations are:
+
+* Category of computer filled in each computer type
+