diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000..0a3d70f Binary files /dev/null and b/.DS_Store differ diff --git a/docs/.DS_Store b/docs/.DS_Store new file mode 100644 index 0000000..30e4290 Binary files /dev/null and b/docs/.DS_Store differ diff --git a/docs/dashboards/dashboards_app.md b/docs/dashboards/dashboards_app.md deleted file mode 100644 index 7f4eb0a..0000000 --- a/docs/dashboards/dashboards_app.md +++ /dev/null @@ -1,5 +0,0 @@ -# Dashboards - -Coming soon. - -In the meantime you can consult previous versions of [this chapter for older versions of OpenPlotter](https://openplotter.readthedocs.io/3.x.x/dashboards/dashboards_app.html) keeping in mind that there are things that have changed. \ No newline at end of file diff --git a/docs/dashboards/dashboards_app.rst b/docs/dashboards/dashboards_app.rst new file mode 100644 index 0000000..51fd9ae --- /dev/null +++ b/docs/dashboards/dashboards_app.rst @@ -0,0 +1,75 @@ +.. |DB| image:: img/openplotter-dashboards.png +.. |mhelp| image:: ../img/help.png +.. |mSettings| image:: ../img/settings.png +.. |DBshow| image:: img/show.png +.. |DBedit| image:: img/edit.png +.. |DBinstall| image:: img/install.png +.. |DBuninstall| image:: img/uninstall.png +.. |DBrefresh| image:: img/refresh.png +.. |DBstart| image:: img/start.png +.. |DBstop| image:: img/stop.png +.. |DBrestart| image:: img/restart.png +.. |DBprocess| image:: img/process.png +.. |DBhelp| image:: img/help-on-icon.png + +|DB| Dashboards +############### + +.. note:: + To run this app type this in a terminal: + + .. parsed-literal:: + + openplotter-dashboards + +|mhelp| ``Help`` opens an offline copy of this documentation in a browser and |mSettings| ``Settings`` opens the main app *OpenPlotter Settings*. + +.. image:: img/dashboards0.png + +Select any app from the list and click |DBinstall| ``Install`` or |DBuninstall| ``Uninstall``. Click |DBrefresh| ``Refresh`` after any of these actions to refresh the list. + +Most of these dashboards are Signal K server plugins, but some are standalone third-party applications such as Grafana or InfluxDB. Once these applications are installed you can |DBstart| ``Start``, |DBstop| ``Stop``, |DBrestart| ``Restart`` and configure automatic startup by toggling ``Autostart`` in the |DBprocess| Processes tab: + +.. image:: img/dashboards1.png + +KIP +### + +.. image:: img/kip.png + +The most popular Signal K MFD/dashboard app. Using this wonderful Signal K plugin you will be able to easily build sexy dashboards containing graphs, gauges, numeric, charts, digital switch and more... + +You can access this dashboard by selecting *KIP* in the list and clicking |DBshow| ``Open`` or by typing this address in your local browser: *http://localhost:3000/@mxtommy/kip/*. You can also connect to this page from any device connected to the same network as OpenPlotter using the address *http://openplotter.local:3000/@mxtommy/kip/*. + +Go to the plugin homepage for the list of features and tips: https://github.com/mxtommy/Kip + +Instrument Panel +################ + +.. image:: img/instrumentpanel.png + +This is the dashboard built into the Signal K server. It is highly configurable and you can even embed panels from other applications like Grafana. + +You can access this dashboard by selecting *Instrument Panel* in the list and clicking |DBshow| ``Open`` or by typing this address in your local browser: *http://localhost:3000/@signalk/instrumentpanel/*. You can also connect to this page from any device connected to the same network as OpenPlotter using the address *http://openplotter.local:3000/@signalk/instrumentpanel/*. + +Click on the |DBhelp| help icon to access full documentation. + +Node-Red Dashboard +################## + +.. image:: img/nodered_dashboard.png + +`Node-RED `_ is a tool that uses a browser-based visual editor to program the connections between hardware devices, and APIs such as Signal K. It allows you to gather, adjust, enhance and deliver the data without needing to understand complex programming languages such as C or Python. + +In OpenPlotter, Node-RED is embedded in the Signal K server as a plugin, and contains some specific nodes to manage Signal K data. Go to the plugin homepage to see the list of nodes and some examples: https://github.com/SignalK/node-red-embedded + +The installation also includes the node-red-dashboard plugin that adds more nodes for creating buttons, graphs, gauges, sliders, and so on. + +You can build Node-RED dashboards by selecting *Node-Red Dashboard* in the list and clicking |DBedit| ``Edit`` or by typing this address in your local browser: *http://localhost:3000/plugins/signalk-node-red/redAdmin/*. You can also connect to this page from any device connected to the same network as OpenPlotter using the address *http://openplotter.local:3000/plugins/signalk-node-red/redAdmin/*. + +You can see your Node-RED dashboards in action by selecting *Node-Red Dashboard* in the list and clicking |DBshow| ``Open`` or by typing this address in your local browser: *http://localhost:3000/plugins/signalk-node-red/redApi/ui/*. You can also connect to this page from any device connected to the same network as OpenPlotter using the address *http://openplotter.local:3000/plugins/signalk-node-red/redApi/ui/*. + +Using and learning Node-RED takes some time and is not the goal of this document. If you are not a programmer but would like to learn some basic principles, Node-RED is the perfect starting point. Everything will be possible in OpenPlotter using Node-RED. + +- Go to the Node-RED homepage to get started: https://nodered.org/docs +- Go to our dedicated forum to share or ask about Node-RED in OpenPlotter: https://forum.openmarine.net/forumdisplay.php?fid=15 \ No newline at end of file diff --git a/docs/dashboards/grafana.rst b/docs/dashboards/grafana.rst new file mode 100644 index 0000000..aa98480 --- /dev/null +++ b/docs/dashboards/grafana.rst @@ -0,0 +1,36 @@ +.. |DBshow| image:: img/show.png + +Grafana +####### + +.. image:: img/grafana.png + +Grafana is one of the most powerful platforms to manage and visualize data. After installation, select *Grafana* in the dashboard list and click |DBshow| ``Open``: + +.. image:: img/grafana0a.png + +The browser will open and show us the page *http://localhost:3001*. You can also connect to this page from any device connected to the same network as OpenPlotter using the address *http://openplotter.local:3001*. + +The initial username and password are both set to *admin*. On the next page we will be asked to change and verify a new password. + +.. image:: img/grafana0b.png + +There are many ways to manage and display data in OpenPlotter using Grafana, but in this short tutorial we will focus on how to display data from the Signal K server in real time. We want to catch the delta messages that the server sends over the websocket connection, so we will use the *WebSocket API* plugin that is pre-installed in OpenPlotter. + +Go to :menuselection:`Configuration --> Data sources` and click ``Add data source``. Select *WebSocket API* at the end of the list and write *ws://localhost:3000/signalk/v1/stream?subscribe=all* in ``Host``: + +.. image:: img/grafana1.png + +After saving, Grafana will be ready to receive all delta messages for all existing Signal K keys and values. Now we need to filter a Signal K key to be displayed on a dashboard, for this example we will use *environment.outside.temperature*. + +Go to :menuselection:`Create --> Dashboard` and click ``Add a new panel``. In the ``Query`` tab, select *WebSocket API* as the ``Data Source`` and add 3 ``Fields`` by filling in the ``Field``, ``Type`` and ``Alias`` fields using the data from the image below: + +.. image:: img/grafana2.png + +Finally go to ``Transform`` tab and add the ``Filter data by values`` transformation using the settings shown in the image below: + +.. image:: img/grafana3.png + +Signal K uses the Kelvin unit for temperature, so if we want to convert the data to Celsius, we can add another transformation ``Add field from calculation`` using the settings in the image above. + +Once you are happy with your panel click ``Save`` and continue building your perfect dashboard by adding more panels. diff --git a/docs/dashboards/img/add.png b/docs/dashboards/img/add.png new file mode 100644 index 0000000..5dd0ba7 Binary files /dev/null and b/docs/dashboards/img/add.png differ diff --git a/docs/dashboards/img/apply.png b/docs/dashboards/img/apply.png new file mode 100644 index 0000000..ad71f7d Binary files /dev/null and b/docs/dashboards/img/apply.png differ diff --git a/docs/dashboards/img/cancel.png b/docs/dashboards/img/cancel.png new file mode 100644 index 0000000..f846f33 Binary files /dev/null and b/docs/dashboards/img/cancel.png differ diff --git a/docs/dashboards/img/dashboard.png b/docs/dashboards/img/dashboard.png new file mode 100644 index 0000000..1ac55f5 Binary files /dev/null and b/docs/dashboards/img/dashboard.png differ diff --git a/docs/dashboards/img/dashboards0.png b/docs/dashboards/img/dashboards0.png new file mode 100644 index 0000000..05cf845 Binary files /dev/null and b/docs/dashboards/img/dashboards0.png differ diff --git a/docs/dashboards/img/dashboards1.png b/docs/dashboards/img/dashboards1.png new file mode 100644 index 0000000..651b134 Binary files /dev/null and b/docs/dashboards/img/dashboards1.png differ diff --git a/docs/dashboards/img/edit.png b/docs/dashboards/img/edit.png new file mode 100644 index 0000000..7335ec8 Binary files /dev/null and b/docs/dashboards/img/edit.png differ diff --git a/docs/dashboards/img/grafana.png b/docs/dashboards/img/grafana.png new file mode 100644 index 0000000..ec4b3b8 Binary files /dev/null and b/docs/dashboards/img/grafana.png differ diff --git a/docs/dashboards/img/grafana0a.png b/docs/dashboards/img/grafana0a.png new file mode 100644 index 0000000..8225755 Binary files /dev/null and b/docs/dashboards/img/grafana0a.png differ diff --git a/docs/dashboards/img/grafana0b.png b/docs/dashboards/img/grafana0b.png new file mode 100644 index 0000000..55523c2 Binary files /dev/null and b/docs/dashboards/img/grafana0b.png differ diff --git a/docs/dashboards/img/grafana1.png b/docs/dashboards/img/grafana1.png new file mode 100644 index 0000000..325f054 Binary files /dev/null and b/docs/dashboards/img/grafana1.png differ diff --git a/docs/dashboards/img/grafana2.png b/docs/dashboards/img/grafana2.png new file mode 100644 index 0000000..5ace339 Binary files /dev/null and b/docs/dashboards/img/grafana2.png differ diff --git a/docs/dashboards/img/grafana3.png b/docs/dashboards/img/grafana3.png new file mode 100644 index 0000000..fa42c64 Binary files /dev/null and b/docs/dashboards/img/grafana3.png differ diff --git a/docs/dashboards/img/help-on-icon.png b/docs/dashboards/img/help-on-icon.png new file mode 100644 index 0000000..c6724fa Binary files /dev/null and b/docs/dashboards/img/help-on-icon.png differ diff --git a/docs/dashboards/img/influxdb1.png b/docs/dashboards/img/influxdb1.png new file mode 100644 index 0000000..538af24 Binary files /dev/null and b/docs/dashboards/img/influxdb1.png differ diff --git a/docs/dashboards/img/influxdb20.png b/docs/dashboards/img/influxdb20.png new file mode 100644 index 0000000..5e13935 Binary files /dev/null and b/docs/dashboards/img/influxdb20.png differ diff --git a/docs/dashboards/img/influxdb20a.png b/docs/dashboards/img/influxdb20a.png new file mode 100644 index 0000000..8c0449b Binary files /dev/null and b/docs/dashboards/img/influxdb20a.png differ diff --git a/docs/dashboards/img/influxdb21.png b/docs/dashboards/img/influxdb21.png new file mode 100644 index 0000000..597152e Binary files /dev/null and b/docs/dashboards/img/influxdb21.png differ diff --git a/docs/dashboards/img/influxdb22.png b/docs/dashboards/img/influxdb22.png new file mode 100644 index 0000000..42b1ee0 Binary files /dev/null and b/docs/dashboards/img/influxdb22.png differ diff --git a/docs/dashboards/img/influxdb23.png b/docs/dashboards/img/influxdb23.png new file mode 100644 index 0000000..2412c8c Binary files /dev/null and b/docs/dashboards/img/influxdb23.png differ diff --git a/docs/dashboards/img/influxdb24.png b/docs/dashboards/img/influxdb24.png new file mode 100644 index 0000000..92a4d76 Binary files /dev/null and b/docs/dashboards/img/influxdb24.png differ diff --git a/docs/dashboards/img/influxdb25.png b/docs/dashboards/img/influxdb25.png new file mode 100644 index 0000000..98d7cf5 Binary files /dev/null and b/docs/dashboards/img/influxdb25.png differ diff --git a/docs/dashboards/img/influxdb26.png b/docs/dashboards/img/influxdb26.png new file mode 100644 index 0000000..3828ac6 Binary files /dev/null and b/docs/dashboards/img/influxdb26.png differ diff --git a/docs/dashboards/img/influxdb26b.png b/docs/dashboards/img/influxdb26b.png new file mode 100644 index 0000000..df5429a Binary files /dev/null and b/docs/dashboards/img/influxdb26b.png differ diff --git a/docs/dashboards/img/influxdb27.png b/docs/dashboards/img/influxdb27.png new file mode 100644 index 0000000..a68b486 Binary files /dev/null and b/docs/dashboards/img/influxdb27.png differ diff --git a/docs/dashboards/img/influxdb28.png b/docs/dashboards/img/influxdb28.png new file mode 100644 index 0000000..51e0eb7 Binary files /dev/null and b/docs/dashboards/img/influxdb28.png differ diff --git a/docs/dashboards/img/influxdb29.png b/docs/dashboards/img/influxdb29.png new file mode 100644 index 0000000..ab783f5 Binary files /dev/null and b/docs/dashboards/img/influxdb29.png differ diff --git a/docs/dashboards/img/influxdb30.png b/docs/dashboards/img/influxdb30.png new file mode 100644 index 0000000..31ad09d Binary files /dev/null and b/docs/dashboards/img/influxdb30.png differ diff --git a/docs/dashboards/img/influxdb31.png b/docs/dashboards/img/influxdb31.png new file mode 100644 index 0000000..3c36a81 Binary files /dev/null and b/docs/dashboards/img/influxdb31.png differ diff --git a/docs/dashboards/img/influxdb32.png b/docs/dashboards/img/influxdb32.png new file mode 100644 index 0000000..17f043e Binary files /dev/null and b/docs/dashboards/img/influxdb32.png differ diff --git a/docs/dashboards/img/influxdb33.png b/docs/dashboards/img/influxdb33.png new file mode 100644 index 0000000..bd65d8f Binary files /dev/null and b/docs/dashboards/img/influxdb33.png differ diff --git a/docs/dashboards/img/influxdb34.png b/docs/dashboards/img/influxdb34.png new file mode 100644 index 0000000..5f1e668 Binary files /dev/null and b/docs/dashboards/img/influxdb34.png differ diff --git a/docs/dashboards/img/install.png b/docs/dashboards/img/install.png new file mode 100644 index 0000000..d713769 Binary files /dev/null and b/docs/dashboards/img/install.png differ diff --git a/docs/dashboards/img/instrumentpanel.png b/docs/dashboards/img/instrumentpanel.png new file mode 100644 index 0000000..ef59906 Binary files /dev/null and b/docs/dashboards/img/instrumentpanel.png differ diff --git a/docs/dashboards/img/kip.png b/docs/dashboards/img/kip.png new file mode 100644 index 0000000..36bafaa Binary files /dev/null and b/docs/dashboards/img/kip.png differ diff --git a/docs/dashboards/img/nodered_dashboard.png b/docs/dashboards/img/nodered_dashboard.png new file mode 100644 index 0000000..5dfcef1 Binary files /dev/null and b/docs/dashboards/img/nodered_dashboard.png differ diff --git a/docs/dashboards/img/openplotter-dashboards.png b/docs/dashboards/img/openplotter-dashboards.png new file mode 100644 index 0000000..df01e07 Binary files /dev/null and b/docs/dashboards/img/openplotter-dashboards.png differ diff --git a/docs/dashboards/img/process.png b/docs/dashboards/img/process.png new file mode 100644 index 0000000..54db51b Binary files /dev/null and b/docs/dashboards/img/process.png differ diff --git a/docs/dashboards/img/refresh.png b/docs/dashboards/img/refresh.png new file mode 100644 index 0000000..4d3ad01 Binary files /dev/null and b/docs/dashboards/img/refresh.png differ diff --git a/docs/dashboards/img/restart.png b/docs/dashboards/img/restart.png new file mode 100644 index 0000000..8a99433 Binary files /dev/null and b/docs/dashboards/img/restart.png differ diff --git a/docs/dashboards/img/sailgauge.png b/docs/dashboards/img/sailgauge.png new file mode 100644 index 0000000..0b0ad92 Binary files /dev/null and b/docs/dashboards/img/sailgauge.png differ diff --git a/docs/dashboards/img/show.png b/docs/dashboards/img/show.png new file mode 100644 index 0000000..aedef4c Binary files /dev/null and b/docs/dashboards/img/show.png differ diff --git a/docs/dashboards/img/start.png b/docs/dashboards/img/start.png new file mode 100644 index 0000000..eed3786 Binary files /dev/null and b/docs/dashboards/img/start.png differ diff --git a/docs/dashboards/img/stop.png b/docs/dashboards/img/stop.png new file mode 100644 index 0000000..822c044 Binary files /dev/null and b/docs/dashboards/img/stop.png differ diff --git a/docs/dashboards/img/uninstall.png b/docs/dashboards/img/uninstall.png new file mode 100644 index 0000000..a1cea6d Binary files /dev/null and b/docs/dashboards/img/uninstall.png differ diff --git a/docs/dashboards/influxdb.rst b/docs/dashboards/influxdb.rst new file mode 100644 index 0000000..a735dfd --- /dev/null +++ b/docs/dashboards/influxdb.rst @@ -0,0 +1,128 @@ +.. |DBshow| image:: img/show.png +.. |DBedit| image:: img/edit.png +.. |DBadd| image:: img/add.png + +InfluxDB OSS 2.x +################ + +.. image:: img/influxdb1.png + +.. note:: + InfluxDB OSS 2.x is only available for 64 bit systems. + +InfluxDB is a powerful time series database system that can be used to store data and track its' evolution over time. After installation, select *InfluxDB OSS 2.x* in the dashboard list and click |DBshow| ``Open``: + +.. image:: img/influxdb20a.png + +The browser will open and show us the page *http://localhost:8086*. You can also connect to this page from any device connected to the same network as OpenPlotter using the address *http://openplotter.local:8086*. + +Fill in all the required fields using data that you can easily remember later. A *Bucket* is what we normally know as a database: + +.. image:: img/influxdb20.png + +On the next page there are several options to learn the basics of InfluxDB but you can ignore them because here we are going to guide you step by step to store and display data for the Signal K key *environment.outside.temperature*. Click ``Configure Later``. + +The amount of space used by InfluxDB will depend significantly on the volume of data you wish to store, and the amount of data you wish to retain. It is important to control the size of your databases so you do not consume all of your valuable storage space. In InfluxDB this is done by configuring *data retention* on each bucket. The retention policy of the bucket we created during the initial setup is set to *Forever* by default, so we will create a new one. Go to :menuselection:`Data --> Buckets` and click ``Create Bucket``: + +.. image:: img/influxdb21.png + +We will call it *myBucket24h* to signify its retention policy, and we will configure *Older Than 24 hours* in ``Delete Data``: + +.. image:: img/influxdb22.png + +Now we need to create a token so that we are allowed to write data to our buckets from external applications. Go to :menuselection:`Data --> API Tokens` and select *Read/Write API Token* in ``Generate API Token``: + +.. image:: img/influxdb23.png + +Write a description for your token and select *All Buckets* in both ``Read`` and ``Write`` options. This way we will use the same token for all current and future buckets: + +.. image:: img/influxdb24.png + +After saving, open your new token and click ``Copy to Clipboard``: + +.. image:: img/influxdb26b.png + +The most complex part of using InfluxDB is sending data to databases using an external application called *Telegraf* but the good news is that OpenPlotter will do the hard work for you. Go back to the *OpenPlotter Dashboards* app, select *InfluxDB OSS 2.x* and this time click |DBedit| ``Edit``: + +.. image:: img/influxdb25.png + +Fill in ``Organization``, ``Bucket`` and ``Token`` with the data that we have used in the previous steps. Be conservative with the ``Ìnterval``, you do not need to store the air temperature every second because you are only interested in its evolution over time, so 10 minutes will be enough. Note that you can not only monitor your ship's data, but also the data of any ships you have data for, such as ships detected by AIS. For this example we will add *self.environment.outside.temperature* in ``Signal K key`` field. Click |DBadd| to add a new item in the list: + +.. image:: img/influxdb26.png + +When you have added all the items you want to monitor, click ``OK`` to save and your databases will begin storing data as it becomes available: + +.. image:: img/influxdb27.png + +InfluxDB also contains tools for creating dashboards and these tools use *Flux*, an scripting language designed for querying, analyzing, and acting on data. Do not worry, you do not have to learn Flux to create dashboards, just learn how to use these tools and how to make small changes in Flux scripts. + +Go back to the InfluxDB web administrator and click ``Explore``. Select *myBucket24h* in ``FROM`` column and filter by *_measurement: self.environment.outside.temperature* and *_field: value* adding 2 extra ``Filter`` columns. Click ``Submit`` to create a *Graph* cell using this query: + +.. image:: img/influxdb28.png + +As you can see on the y-axis, Signal K uses Kelvin unit for temperature. If we want to convert the data to Celsius we have to make some changes in the Flux script that this *Query Builder* has created. Click ``Script Editor``: + +.. image:: img/influxdb29.png + +Replace these lines: + +.. parsed-literal:: + + aggregateWindow(every: v.windowPeriod, fn: mean, createEmpty: false) + yield(name: "mean") + +By this one: + +.. parsed-literal:: + + map(fn: (r) => ({ r with _value: r._value - 272.15 })) + +.. note:: + To convert the data to other units you just have to apply the formula to this line. For example, to convert from Kelvin to Fahrenheit we have to apply the formula 1.8*(K-273)+32: + + .. parsed-literal:: + + map(fn: (r) => ({ r with _value: 1.8*(r._value-273)+32 })) + +Your final script will look like this: + +.. parsed-literal:: + + from(bucket: "myBucket24h") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => r["_measurement"] == "self.environment.outside.temperature") + |> filter(fn: (r) => r["_field"] == "value") + |> map(fn: (r) => ({ r with _value: r._value - 272.15 })) + +After clicking ``Submit`` you will see that the y-axis now shows the data in Celsius: + +.. image:: img/influxdb30.png + +Finally click ``Customize`` to add some aesthetic settings like labels, ranges or suffixes: + +.. image:: img/influxdb31.png + +Once you are happy with your cell, click ``Save As`` and continue building your perfect dashboard by adding more cells. + +InfluxDB in Grafana +=================== + +You may prefer to use Grafana to unify all your panels or cells with real-time and stored data. To access to the data stored in InfluDB buckets you have to create a new *Data Source* in Grafana. Go to :menuselection:`Configuration --> Data sources`, click ``Add data source``, select *InfluxDB* in the list and use the data from the image below, fill in ``Organization``, ``Bucket`` and ``Token`` with the data that you have used in the previous steps: + +.. image:: img/influxdb33.png + +.. image:: img/influxdb32.png + +Create a new panel, select *InfluxDB* in ``Data source`` and paste here the same Flux script you have generated using the *Query Builder* in the InfluxDB web administrator: + +.. parsed-literal:: + + from(bucket: "myBucket24h") + |> range(start: v.timeRangeStart, stop: v.timeRangeStop) + |> filter(fn: (r) => r["_measurement"] == "self.environment.outside.temperature") + |> filter(fn: (r) => r["_field"] == "value") + |> map(fn: (r) => ({ r with _value: r._value - 272.15 })) + +.. image:: img/influxdb34.png + +Finally modify the display settings of the panel to adapt it to your preferences and you are done.