From 4adccc24a6447e9452e70525ab6ea8300f39732f Mon Sep 17 00:00:00 2001 From: Theophane Boue Date: Wed, 13 Aug 2025 10:51:25 +0200 Subject: [PATCH 1/4] add Metrology foundation documentation. --- ApplicationDeveloperGuide/metrology.rst | 135 +++++++++++++++++++++++ VEEPortingGuide/appendix/llapi.rst | 22 ++++ VEEPortingGuide/index.rst | 1 + VEEPortingGuide/metrology.rst | 44 ++++++++ VEEPortingGuide/pack.rst | 1 + VEEPortingGuide/veePortQualification.rst | 9 ++ 6 files changed, 212 insertions(+) create mode 100644 ApplicationDeveloperGuide/metrology.rst create mode 100644 VEEPortingGuide/metrology.rst diff --git a/ApplicationDeveloperGuide/metrology.rst b/ApplicationDeveloperGuide/metrology.rst new file mode 100644 index 000000000..e56669223 --- /dev/null +++ b/ApplicationDeveloperGuide/metrology.rst @@ -0,0 +1,135 @@ +.. _metrology_api: + +Metrology +========= + +Introduction +------------ + +The Metrology Library provides APIs to retrieve metrology and metrology related data. + +.. _metrology_api_usage: + +Usage +----- + +The Metrology Library is provided as a Foundation Library. + +To use the `Metrology Library `_, add the following line to the project build file: + +.. code-block:: kotlin + + implementation("ej.api:metrology:3.2.0") + +Building or running an Application which uses the Metrology Library requires a SDK6 VEE Port that provides the :ref:`Metrology Pack `. + +APIs +---- + +The Metrology API isn't KF compatible, use in a multi-application context may lead to unexpected results. +It is recomended to use the Energy framework API to interact with the Metrology API. + +Static Configurations +~~~~~~~~~~~~~~~~~~~~~ + +Meter static configuration can be retrieved with the following methods: + +- `ej.energy.metrology.Metrology.getMeterForm()int` +- `ej.energy.metrology.Metrology.getMeterServiceCurrent()int` +- `ej.energy.metrology.Metrology.getMeterServiceVoltage()int` + +Event API +~~~~~~~~~ + +This API is based on the :ref:`Event Pack ` and allows notification of Metrology data. +It is appropriate to retrieve periodaically mean values, or process values over a period of time over 1 second. + +Streaming API +~~~~~~~~~~~~~ + +This API + +Classes Summary +~~~~~~~~~~~~~~~ + +* `Metrology`_: Get static configuration, register event listener and wait for streamed data. +* `MetrologyEventListener`_: Interface to implement to retrieve Metrology event. + +.. _metrology_configuration: + +Configuration +------------- + +The :ref:`Metrology Pack ` can be configured by defining the following :ref:`Application Options `: + +You can hook a DLMS server as data event data source on simulator, switch to a dlms source with: + +- com.microej.energy.metrology.mock.dlms=true + +You must provide the following properties in order for the Metrology mock to communicate with a DLMS server: + +- com.microej.energy.metrology.mock.dlms.objects=,,,;etc... +- com.microej.energy.metrology.mock.dlms.client.address=[0-9*] +- com.microej.energy.metrology.mock.dlms.server.logical.address=[0-9*] +- com.microej.energy.metrology.mock.dlms.server.physical.address=[0-9*] +- com.microej.energy.metrology.mock.dlms.server.host= +- com.microej.energy.metrology.mock.dlms.server.port=[0-9*] + +Configure the available immortal size to accomodate both streaming buffer: + +- core.memory.immortal.size=[0-9*] + +Streaming data source: + +- com.microej.energy.metrology.mock.stream.data.file= + +Example +------- + +Event Data +~~~~~~~~~~ + +The following snippet registers a Metrology listener: + +.. code-block:: java + + String[] names = new String(){"Parameter1","Parameter2",...}; + Metrology.setParameterNames(names); //Sets names and max number of parameters + + OnMetrologyEventListener listener = new OnMetrologyEventListener(); + Metrology.setListener(listener); + +The following snippet process data: + +.. code-block:: java + + private static class OnMetrologyEventListener implements MetrologyEventListener { + + @Override + public void onParametersReceived(final float[] parametersValues) { + //Business logic here + } + +Streaming Data +~~~~~~~~~~~~~~~ + +The following snippet wait for streaming data and process it: + +.. code-block:: java + + byte[] buffer; + while (PROCESS) { + buffer = Metrology.waitStreamBuffer();// Get next data buffer. + Metrology.lockStreamBuffer(); // Lock native buffer to prevent data overwrite. + + //Process the stream here + + Metrology.unlockStreamBuffer(); //Unlock native buffer. + } + +.. + | Copyright 2025, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification + is subject to MicroEJ Corp prior approval. + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + copyrights are the property of their respective owners. diff --git a/VEEPortingGuide/appendix/llapi.rst b/VEEPortingGuide/appendix/llapi.rst index 940a8caf8..130837b2b 100644 --- a/VEEPortingGuide/appendix/llapi.rst +++ b/VEEPortingGuide/appendix/llapi.rst @@ -1136,6 +1136,28 @@ Several C header files are provided: to manage X509 certificates operations like getting the public key, extracting the issuer, etc. +.. _LLMETROLOGY-API-SECTION: + +LLMETROLOGY: METROLOGY +====================== + +Naming Convention +----------------- + +The Low Level METROLOGY API (LLMETROLOGY), relies on functions that need to +be implemented by engineers in a driver. The names of these functions +match the ``LLMETROLOGY_IMPL_*`` pattern. + +Header Files +------------ + +One header file is provided: + +- LLMETROLOGY_impl.h + + Defines the set of functions that the BSP must implement to manage and configure + METROLOGY engine. + .. | Copyright 2008-2025, MicroEJ Corp. Content in this space is free for read and redistribute. Except if otherwise stated, modification diff --git a/VEEPortingGuide/index.rst b/VEEPortingGuide/index.rst index 345bb058d..a9fe3dd52 100644 --- a/VEEPortingGuide/index.rst +++ b/VEEPortingGuide/index.rst @@ -23,6 +23,7 @@ VEE Porting Guide net bluetooth audio + metrology microai packEventQueue fs diff --git a/VEEPortingGuide/metrology.rst b/VEEPortingGuide/metrology.rst new file mode 100644 index 000000000..086938321 --- /dev/null +++ b/VEEPortingGuide/metrology.rst @@ -0,0 +1,44 @@ +.. _pack_metrology: + +========= +Metrology +========= + +Principle +========= + +The Metrology Foundation Library defines an interface to retrieve underlying metrology data. + +Functional Description +====================== + +A typical Application using Metrology will register a data listener, receive new data notification, and finally perform data processing. + +The Metrology integration in a VEE port relies on a native metrology data source to implement all of the above functionalities. + +Dependencies +============ + +- ``LLMETROLOGY_impl.h`` implementation (see :ref:`LLMETROLOGY-API-SECTION`). + +Installation +============ + +Metrology is an additional module. +To enable it, the Metrology :ref:`Pack ` must be installed in your VEE Port: + +.. code-block:: kotlin + + api("ej.api:metrology:3.1.2") + +Use +=== + +See :ref:`Metrology API ` chapter in Application Developer Guide. + +.. + | Copyright 2025, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification + is subject to MicroEJ Corp prior approval. + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + copyrights are the property of their respective owners. diff --git a/VEEPortingGuide/pack.rst b/VEEPortingGuide/pack.rst index 90d2b37a7..975f3482e 100644 --- a/VEEPortingGuide/pack.rst +++ b/VEEPortingGuide/pack.rst @@ -14,6 +14,7 @@ On top of a MicroEJ Architecture can be imported MicroEJ Packs which provide add - :ref:`Networking `, - :ref:`Bluetooth `, - :ref:`Audio `, +- :ref:`Metrology `, - :ref:`MicroAI `, - :ref:`File System `, - etc. diff --git a/VEEPortingGuide/veePortQualification.rst b/VEEPortingGuide/veePortQualification.rst index 371623eb1..3b2a44089 100644 --- a/VEEPortingGuide/veePortQualification.rst +++ b/VEEPortingGuide/veePortQualification.rst @@ -326,6 +326,15 @@ EVENT QUEUE Pack .. [1] Test Suite available on demand, please contact :ref:`MicroEJ Support`. +Metrology Pack +------------ + +.. list-table:: Metrology Library and Validation + :widths: 20 20 + + * - Metrology Library + * - 3.2.0 (On demand [1]_) + .. | Copyright 2008-2025, MicroEJ Corp. Content in this space is free for read and redistribute. Except if otherwise stated, modification From d6029ade81e8dabe179ad63f9bc878685141de49 Mon Sep 17 00:00:00 2001 From: Theophane Boue Date: Thu, 14 Aug 2025 11:01:42 +0200 Subject: [PATCH 2/4] improve metrology app developer guide wording. --- ApplicationDeveloperGuide/metrology.rst | 74 +++++++++++++------------ 1 file changed, 40 insertions(+), 34 deletions(-) diff --git a/ApplicationDeveloperGuide/metrology.rst b/ApplicationDeveloperGuide/metrology.rst index e56669223..738a295c1 100644 --- a/ApplicationDeveloperGuide/metrology.rst +++ b/ApplicationDeveloperGuide/metrology.rst @@ -6,7 +6,7 @@ Metrology Introduction ------------ -The Metrology Library provides APIs to retrieve metrology and metrology related data. +The Metrology Library provides APIs for retrieving metrology data and managing metrology-related configurations. .. _metrology_api_usage: @@ -26,13 +26,15 @@ Building or running an Application which uses the Metrology Library requires a S APIs ---- -The Metrology API isn't KF compatible, use in a multi-application context may lead to unexpected results. -It is recomended to use the Energy framework API to interact with the Metrology API. +.. warning:: + + The Metrology API is not KF-compatible. Using it in a multi-application context may cause unexpected behavior. It is recommended to use the Energy Framework API to interact with the Metrology API. + Static Configurations ~~~~~~~~~~~~~~~~~~~~~ -Meter static configuration can be retrieved with the following methods: +The following methods allow you to retrieve static meter configurations: - `ej.energy.metrology.Metrology.getMeterForm()int` - `ej.energy.metrology.Metrology.getMeterServiceCurrent()int` @@ -41,47 +43,49 @@ Meter static configuration can be retrieved with the following methods: Event API ~~~~~~~~~ -This API is based on the :ref:`Event Pack ` and allows notification of Metrology data. -It is appropriate to retrieve periodaically mean values, or process values over a period of time over 1 second. +This API is based on the :ref:`Event Pack ` and provides notifications for Metrology data. +It is suitable for retrieving processed data, like mean values, over periods of 1 second or more. Streaming API ~~~~~~~~~~~~~ -This API +The `waitStreamBuffer` method is a blocking call that returns when a streaming buffer is full. +The application can lock the buffer during processing to prevent its data from being overwritten by the native process. +The buffer must be released after processing. Classes Summary ~~~~~~~~~~~~~~~ -* `Metrology`_: Get static configuration, register event listener and wait for streamed data. -* `MetrologyEventListener`_: Interface to implement to retrieve Metrology event. +* `Metrology`: Access static configurations, register event listeners, and wait for streamed data. +* `MetrologyEventListener`: Interface to implement for receiving Metrology events. .. _metrology_configuration: Configuration ------------- -The :ref:`Metrology Pack ` can be configured by defining the following :ref:`Application Options `: - -You can hook a DLMS server as data event data source on simulator, switch to a dlms source with: +The :ref:`Metrology Pack ` can be configured by defining the following :ref:`Application Options `. -- com.microej.energy.metrology.mock.dlms=true +You can configure a DLMS server as the data source in the simulator by setting:: -You must provide the following properties in order for the Metrology mock to communicate with a DLMS server: + com.microej.energy.metrology.mock.dlms=true -- com.microej.energy.metrology.mock.dlms.objects=,,,;etc... -- com.microej.energy.metrology.mock.dlms.client.address=[0-9*] -- com.microej.energy.metrology.mock.dlms.server.logical.address=[0-9*] -- com.microej.energy.metrology.mock.dlms.server.physical.address=[0-9*] -- com.microej.energy.metrology.mock.dlms.server.host= -- com.microej.energy.metrology.mock.dlms.server.port=[0-9*] +The following properties must be provided for the Metrology mock to communicate with a DLMS server:: -Configure the available immortal size to accomodate both streaming buffer: + com.microej.energy.metrology.mock.dlms.objects=,,,;etc... + com.microej.energy.metrology.mock.dlms.client.address=[0-9*] + com.microej.energy.metrology.mock.dlms.server.logical.address=[0-9*] + com.microej.energy.metrology.mock.dlms.server.physical.address=[0-9*] + com.microej.energy.metrology.mock.dlms.server.host= + com.microej.energy.metrology.mock.dlms.server.port=[0-9*] -- core.memory.immortal.size=[0-9*] +Set the immortal memory size to accommodate streaming buffers:: -Streaming data source: + core.memory.immortal.size=[0-9*] -- com.microej.energy.metrology.mock.stream.data.file= +For streaming data source:: + + com.microej.energy.metrology.mock.stream.data.file= Example ------- @@ -89,17 +93,17 @@ Example Event Data ~~~~~~~~~~ -The following snippet registers a Metrology listener: +The following snippet demonstrates how to register a Metrology listener: .. code-block:: java String[] names = new String(){"Parameter1","Parameter2",...}; - Metrology.setParameterNames(names); //Sets names and max number of parameters + Metrology.setParameterNames(names); // Sets names and max number of parameters OnMetrologyEventListener listener = new OnMetrologyEventListener(); - Metrology.setListener(listener); + Metrology.setListener(listener); // Register the listener -The following snippet process data: +Processing the data: .. code-block:: java @@ -107,24 +111,26 @@ The following snippet process data: @Override public void onParametersReceived(final float[] parametersValues) { - //Business logic here + + //Process the values here + } Streaming Data ~~~~~~~~~~~~~~~ -The following snippet wait for streaming data and process it: +The following snippet waits for streaming data and processes it: .. code-block:: java - byte[] buffer; - while (PROCESS) { + byte[] buffer; // local buffer pointer, no buffer content copy + while (PROCESS) { // PROCESS the process condition buffer = Metrology.waitStreamBuffer();// Get next data buffer. Metrology.lockStreamBuffer(); // Lock native buffer to prevent data overwrite. - //Process the stream here + //Process the stream buffer here - Metrology.unlockStreamBuffer(); //Unlock native buffer. + Metrology.unlockStreamBuffer(); // Unlock native buffer. } .. From 01da905f43357789e09e1215db53aec16b0355a0 Mon Sep 17 00:00:00 2001 From: Theophane Boue Date: Thu, 14 Aug 2025 11:04:34 +0200 Subject: [PATCH 3/4] remove some metrology mentions, update library version. --- ApplicationDeveloperGuide/libraries.rst | 1 + VEEPortingGuide/metrology.rst | 2 +- VEEPortingGuide/pack.rst | 1 - VEEPortingGuide/veePortQualification.rst | 9 --------- 4 files changed, 2 insertions(+), 11 deletions(-) diff --git a/ApplicationDeveloperGuide/libraries.rst b/ApplicationDeveloperGuide/libraries.rst index ecd1eb761..8cec9421c 100644 --- a/ApplicationDeveloperGuide/libraries.rst +++ b/ApplicationDeveloperGuide/libraries.rst @@ -47,6 +47,7 @@ To consult its libraries APIs documentation, please visit `` must be installed in you .. code-block:: kotlin - api("ej.api:metrology:3.1.2") + api("ej.api:metrology:3.2.0") Use === diff --git a/VEEPortingGuide/pack.rst b/VEEPortingGuide/pack.rst index 975f3482e..90d2b37a7 100644 --- a/VEEPortingGuide/pack.rst +++ b/VEEPortingGuide/pack.rst @@ -14,7 +14,6 @@ On top of a MicroEJ Architecture can be imported MicroEJ Packs which provide add - :ref:`Networking `, - :ref:`Bluetooth `, - :ref:`Audio `, -- :ref:`Metrology `, - :ref:`MicroAI `, - :ref:`File System `, - etc. diff --git a/VEEPortingGuide/veePortQualification.rst b/VEEPortingGuide/veePortQualification.rst index 3b2a44089..371623eb1 100644 --- a/VEEPortingGuide/veePortQualification.rst +++ b/VEEPortingGuide/veePortQualification.rst @@ -326,15 +326,6 @@ EVENT QUEUE Pack .. [1] Test Suite available on demand, please contact :ref:`MicroEJ Support`. -Metrology Pack ------------- - -.. list-table:: Metrology Library and Validation - :widths: 20 20 - - * - Metrology Library - * - 3.2.0 (On demand [1]_) - .. | Copyright 2008-2025, MicroEJ Corp. Content in this space is free for read and redistribute. Except if otherwise stated, modification From b43ba806e340fbb02f32a267703742bce3f85400 Mon Sep 17 00:00:00 2001 From: Theophane Boue Date: Thu, 14 Aug 2025 11:13:21 +0200 Subject: [PATCH 4/4] fix metrology code snippet indentation. --- ApplicationDeveloperGuide/metrology.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/ApplicationDeveloperGuide/metrology.rst b/ApplicationDeveloperGuide/metrology.rst index 738a295c1..9e85322e2 100644 --- a/ApplicationDeveloperGuide/metrology.rst +++ b/ApplicationDeveloperGuide/metrology.rst @@ -98,7 +98,7 @@ The following snippet demonstrates how to register a Metrology listener: .. code-block:: java String[] names = new String(){"Parameter1","Parameter2",...}; - Metrology.setParameterNames(names); // Sets names and max number of parameters + Metrology.setParameterNames(names); // Sets names and max number of parameters OnMetrologyEventListener listener = new OnMetrologyEventListener(); Metrology.setListener(listener); // Register the listener @@ -109,8 +109,8 @@ Processing the data: private static class OnMetrologyEventListener implements MetrologyEventListener { - @Override - public void onParametersReceived(final float[] parametersValues) { + @Override + public void onParametersReceived(final float[] parametersValues) { //Process the values here @@ -125,8 +125,8 @@ The following snippet waits for streaming data and processes it: byte[] buffer; // local buffer pointer, no buffer content copy while (PROCESS) { // PROCESS the process condition - buffer = Metrology.waitStreamBuffer();// Get next data buffer. - Metrology.lockStreamBuffer(); // Lock native buffer to prevent data overwrite. + buffer = Metrology.waitStreamBuffer();// Get next data buffer. + Metrology.lockStreamBuffer(); // Lock native buffer to prevent data overwrite. //Process the stream buffer here