OVMS3/OVMS.V3/components/ovms_webserver/docs/metrics.rst

79 lines
2.5 KiB
ReStructuredText

===============
Metric Displays
===============
OVMS V3 is based on metrics. Metrics can be single numerical or textual values or complex values
like sets and arrays. The web framework keeps all metrics in a global object, which can be read
simply by e.g. ``metrics["v.b.soc"]``.
Metrics updates (as well as other updates) are sent to all DOM elements having the
``receiver`` class. To hook into these updates, simply add an event listener for
``msg:metrics``.
Listening to the event is not necessary though if all you need is some metrics
display. This is covered by the ``metric`` widget class family as shown here.
----------------------
Single Values & Charts
----------------------
.. image:: metrics.png
:scale: 50%
:align: right
The following example covers…
- Text (String) displays
- Number displays
- Progress bars (horizontal light weight bar charts)
- Gauges
- Charts
Gauges & charts use the HighCharts library, which is included in the web server. The other widgets
are simple standard Bootstrap widgets extended by an automatic metrics value update mechanism.
Highcharts is a highly versatile charting system. For inspiration, have a look at:
- https://www.highcharts.com/demo
- https://www.highcharts.com/docs
We're using `styled mode <https://www.highcharts.com/docs/chart-design-and-style/style-by-css>`_
so some options don't apply, but everything can be styled by standard CSS.
Install the example as a web page plugin:
:download:`metrics.htm <../dev/metrics.htm>` (hint: right click, save as)
.. literalinclude:: ../dev/metrics.htm
:language: html
:linenos:
-------------
Vector Tables
-------------
.. image:: metrics-table.png
:scale: 50%
:align: right
Some metrics, for example the battery cell voltages or the TPMS tyre health data, may contain
vectors of arbitrary size. Besides rendering into charts, these can also be displayed by their
textual values in form of a table.
The following example shows a live view of the battery cell voltages along with their recorded
minimum, maximum, maximum deviation and current warning/alert state. Alert states 0-2 are translated
into icons.
The metric table widget uses the DataTables library, which is included in the web server. The
DataTables Javascript library offers a wide range of options to create tabular views into
datasets.
Install the example as a web page plugin:
:download:`metrics-table.htm <../dev/metrics-table.htm>` (hint: right click, save as)
.. literalinclude:: ../dev/metrics-table.htm
:language: html
:linenos: