Engine/Energy¶
DashT EngineDJG Dials are intended for engine and energy data originating typically from NMEA-2000 databus (or its commercial namesakes) of your boat. The data is read from a Signal K server node by Signal K In communication instrument.
“D” as dial, “JG” as justGage - thanks for the great dial, folks!
Introduction¶
DashT EngineDJG Dials are created using modern web techniques and the resulting application is incorporated in OpenCPN dashboard:
A dedicated instrument for Engine and Energy data in Signal K data format
Gets data from DashT plug-in by subscription
Data obtained from a single Signal K server node interconnection
Allowing multiplication of instruments ad infinitum
Instrument is not making data connections, connects only to DashT
Does not interfere with NMEA-0183 data push toward the “traditional” Dashboard instruments
Your good old instruments receiving their data from OpenCPN will continue to work as before
HTML5 and JavaScript based
Plain text customization files provided
Loading from the same or from a remote computer
Installation/Launch¶
The EngineDJG gauge does not require any additional installations, all the components are incorporated in the plug-in and ready to use.
Use Node.js¶
Since you have already a Signal K server node up and running and the network connections all set, we just need to use those connections and use their settings and launch both Signal K server node and an http-server on Node.js. This sounds difficult but there is a helper scripts for that, explained below:
Engine Gage script¶
Windows: a button is installed on your desktop, called Engine Gage.
Linux: on command prompt, type dashtengine (create a desktop button, if you like)
Both are serving the same purpose: launching a script, which starts the Signal K server node on Node.js (if not yet running) and launching a http-server on port 8080, which is serving DashT with the EngineDJG web instruments: the instruments are executed then on “mini-browsers”, incorporated in Dashboard instrument panels.
Later on this document, the usage in feature rich infrastructures will be explained, for now we expect that the instruments are available for DashT.
Configuration¶
This chapter is addressing the first time configuration - i.e. make instruments to learn what data is available in your boat and select the ones you are interested in.
NOTE: Configuration can take place only when the instruments receive data from the Signal K server node.
Adding new dials¶
DashT EngineDJG instruments are compatible with all Dashboard instruments and they can be added in any Dashboard instrument cluster window pane. However, since the number of engine parameters, for example is important it is suggested that you create instruments clusters like for “Engine” data and for “Energy” data.
The adding of instruments is like adding any other Dashboard instrument in DashT’s preferences: scroll all the way down of the list to find the single instrument. Add as many instances of it as you estimate you are going to need to show the data parameters you are interested in.
It is suggested than before the configuration the instrument cluster is in “Horizontal” mode to allow sometime very long menu list presented during the configuration phase to roll out vertically. Once the instrument cluster window pane is configured, one can change, of course to “Vertical” mode if needed.
Subscribe to data¶
Once a new DashT EngineDJG instrument has been created it asks from DashT Signal K In streamer what available data paths there are in your boat. It requires a complete list and, depending of your boat’s instrumentation this can be a pretty long one… Normally, the inquiry hould be finished in less than 10 seconds, though.
Once a list of all available data paths has been received, DashT EngineDJG instrument builds a selection menu out of them and invites you to make your selection using the context menu which is activated by a maintained right click on the upper left hand corner of the instrument.
In the context menu, all available data paths are listed a hierarchical order. The names of the data paths are usually clear enough to understand the nature and the origin of the data. A full list of Signal K keys is also available.
The data path values where the last element is marked in blue means that the DashT installation package has a pre-defined setting for it and it can be shown by simply selecting that data path.
Most common data path values have been included in the DashT installation by default for engine and some most obvious data paths for the energy. If the data path is grayed out, it means that it cannot be selected since no data path rule has been defined. This does not mean that the value cannot be shown, it is just that the development and testing has not been able to test it or is not aware of it - there is really a lot of data paths of all sort, such as status data. A way to define your own configuration for data paths is discussed later in this document.
Search again¶
If you cannot find a data path you are expecting to find from the menu, you can ask for a quick rescan by selecting any of the grayed-out items from the menu, i.e. a menu item which is not in blue color. You may get an alert of a non-existing path, depending of the common configuration file settings. Resulting action is, anyway the same as in Changing EngineDJG instrument’s data path subscription and the data sources are scanned again for new paths.
NOTE: The available data scanning is cumulative and if the data path you are expecting was not available from your data bus within the previous scan’s time window frame (in less than 10 seconds), it may have been omitted. Rescan may help. Once the path is recongnized and configured, the subsription to it will be persistent.
Change Display¶
You can scroll the display types with Ctrl+\(\uparrow\) and Ctrl+\(\downarrow\) (Ctrl-key kept down and press arrow keys up or down): apart the default 180-degree dial type, there is also a 360-degree ‘donut’ and a simple numerical display type available.
Change Subscription¶
While the EngineDJG is running (i.e. data is coming in by an existing subscription a data path from the Signal K streamer) right-click on the upper left corner in order to get the context menu which allows you to stop the data display and force a complete re-initialization of the data path subscription as explained in the previous section.
Customization¶
It goes without saying that nobody else but you will be able to find out the particular data sources available in your own boat! DashT EngineDJG reports you all the data paths but the DashT distribution can make but a modest guess what might interest you in the first place. It is likely that we are missing something.
Unlike the most of the DashT, which is written in C++/wxWidgets requiring compilation/build etc., the EngineDJG instrument is a HTML5/JavaScript program which means there are plain text files which you can modify, allowing you to customize the data paths displayed according to your requirements.
Modern web development techniques have been used which are resulting in a very compact and thus non-human readable run-time program execution format, but configuration files are provided also in plain text without merging and compression, allowing you to make your own customizations.
File location¶
Defaults are for the input JavaScript files:
Windows:
\Users\Public\DashT\www
Linux:
/usr/share/opencpn/plugins/dashboard_tactics_pi/data/instrujs/www/
In case you have a boat full of electronics, computers and servers alike, you know what you are doing but you may still want to follow the instructions for feature rich environments, in which case the above paths would probably be best known by yourself.
NOTE: Make sure to take backups before modifying anything! JavaScript is “easy” but does not have any pity to syntax errors: it is a grinding halt without a visible error message…
Add data paths¶
You would need to modify a configuration file named common.js - here is an excerpt of the instructions in that file
Contribute/report here, please:
- with a screenshot and a short description of your installation, thanks!
SignalK Path keys:
The Signal K values are always in SI units (like m/s, not knots).
Conversion to a wanted unit is made with multipier/division/offset.
Avoid using floating point values like 0.000000003 in JavaScript!
UTF8 - do _not_ change encoding, cf. degree character. Notepad++ recommended.
Usage example: enginedjg/index.html loads a minimized version, common.min.js
- make a copy of common.min.js by renaming it;
- make a copy of this one with name common.min.js and modify it;
- (no need for compression with this non-executing file!)
- or, modify enginedjg/index.html to load your own file, no problem!
- issues? open the index.html in a browser, hit Shift+Ctrl+I and reload;
* Console gives you the reason why it does not load anymore:
* Look for messages in red, a typo, missing comma?
- note: next update/reinstallation overrides this file, keep backups!
Typical change that you may want to do is to have different titles for each battery parks, instead of having a * wildcard. You would copy-paste-modify the below definition by replacing the wildcard with two (or more) individual records, both with a full data path (Signal K key) name and a title for your liking, and this for as many times your system is reporting about those values being available:
{
version : 1,
path : 'electrical.batteries.*.current',
title : 'Battery Current',
symbol : '',
unit : 'Amps',
display : 'dial',
decimals : 1,
minval : -20,
loalert : 0,
hialert : 0,
maxval : 20,
multiplier : 1,
divider : 1,
offset : 0
},
Of course, you may want to simply change units in some entries, like from Celsius to Fahrenheit. Just be careful to preserve the UTF-8 degree sign, will you.
The header part of the file contains some common customizations, like turning off the alerts or giving more time for them to set in. One can also increase the debug level in case the EngineDJG HTML/JS code needs to be inspected in an external browser.
NOTE: the
common.jsfile is not used by default but one needs to replace the compressed version of it with this human readable one ininstrujs/index.html. Follow the instructions incommon.jsfor that. If a need arise, do not hesitate to do the change - there is no performance penalty since the file is read only during the startup of instruments. See also
Language file¶
Unfortunately, it is self service, no community support. Yet! You can participate with your native tongue by submitting your translations here: https://git.io/JejKQ
Meanwhile, you can just replace the lang.js file with yours. Keep a copy of the original, though: JavaScript does not make any gifts but goes to a grinding halt for any syntax error (like a missing comma) and none of the DashT EngineDJG instruments will start! There will be no fancy warning message, just a gray background staring at you… - check this troubleshoot section.
Rich infras¶
The instrument is composed of a HTML file and numerous JavaScript files, like any other browser based application. If you do not run a Node.js on your local computer, the configuration task consist of making them available on your boat’s network infrastructure. It contains many elements being platform specific, explained in below sections.
One needs to explain DashT where it should fetch the EngineDJG components. This is done in ini/conf-file.
NOTE: one might be tempted to use
file://protocol. Please note that in Windows, starting from security update of 2020-01-14 local storage capability, including cookies is disabled forfile://protocol in the back-end the wxWidgets is using on Windows (IE). Therefore we address below only the usage ofhttp://protocol to retrieve files from your files infrastructure to enable persistent EngineDJG configuration settings across platforms. You can setfile://protocol in ini/conf-file but you would probably need to reconfigure your instrument at every restart. In older operating systems without security updates thefile://protocol may work but DashT is not addressing those system configurations so you would experience other issues.
pub Linux¶
First, you have to identify where are the DashT EngineDJG files after the installation and export the directory:
/usr/share/opencpn/plugins/dashboard_tactics_pi/data/instrujs/
Apache2 server¶
Most of the Linux systems provide Apache2 server by default and even start it by default. Navigate to your Linux box’s network IP-address and you will soon find out if this is the case. Otherwise, it is not a big task to get it running but for clarity we presume now that it is already active. You would say:
sudo ln -s /usr/share/opencpn/plugins/dashboard_tactics_pi/data/instrujs /var/www/html/instrujs
Check that it works:
NOTE 1: The IP-address below is an example only, author’s Raspberry: use your own
NOTE 2: The actual content of the directory changes with more DashT instrujs instruments becoming available
http-server node¶
NOTE: If you are running a Signal K server node on your local computer, you do not follow these instructions, the helper script explained above is doing all this work for you. Follow these instructions only if your server is located on another computer.
Since you already have a _ Signal K server node_ you have thus Node.js. If the above Apache2 method seems like an overkill to you, there is this dead simple solution:
npm install -g http-server
You would start the service (and can make a shell script for it):
http-server /usr/share/opencpn/plugins/dashboard_tactics_pi/data/instrujs/www -p 8080
Or from where ever you have put the instrujs directory on this server.
Execute the script, leave the http-server running and verify that files are available on the port 8080 (you can modify the port, of course). The verification, like usual with a normal browser, as above with the Apache server - no need to start OpenCPN for that.
The new server and the port need to be described to DashT in ini/conf-file.
pub Windows¶
NOTE: We suppose below that you are running also the Signal K server node on Windows but locally, i.e. not where OpenCPN is located. With local-only installation, the helper script is doing all the below work.
In addition to the Signal K server node, install also the following server node:
npm install -g http-server
You will find the files to share from
C:\Program Files (x86)\OpenCPN\plugins\dashboard_tactics_pi\data\instrujs\www
You would start the service (and can make a batch or PowerShell script for it):
http-server "C:\Program Files (x86)\OpenCPN\plugins\dashboard_tactics_pi\data\instrujs\www" -p 8080
Or from where ever you have put the instrujs directory on this server.
The new server and the port need to be described to DashT in ini/conf-file.
Troubleshooting¶
Data is bad¶
It is always a good idea to go back as close as possible to the data source, which is Signal K server node. What does it say about that data? If the SI unit value it displays in its own plug-ins and log files makes sense to you, then the issue is probably with the multiplier, divider or offset, or all of them used to convert it (see above sections about the customization).
The floating point data which is coming from Signal K server node is given as such to the DashT EngineDJG instrument, but as a string (we are talking to a JavaScript program) in non-scientific notation, in decimal format. For example, if DashT receives 0.24444444, that usually is alright. But a general rule is that values with too many zeros are not advisable in JavaScript. Avoid calculations where any result, including intermediate values would lead to values like 0.0000003 or similar bunch of zeros.
If things need deep understanding of data which is coming in from your boat’s databus, maybe the easiest place where you can look at it is the log files of Signal K server node’s databus connector. You need to activate them explicilty. The instrujs Developer’s Guide in DashT documentation (in the repository) provides some use cases of deep packet analysis but be warned, it is not for faint hearted!
After config, all dead¶
The good and bad of JavaScript is that as a scripted language it allows you to make as many syntax errors you like. When you are editing, that is… During the development we use TypeScript to avoid this. But when you are editing JavaScript directly, errors are fatal. Since there is no compilation or transpiling, eventual errors are detected only during loading and even worse, sometimes during the run-time when the code execution passes in the faulty section!
Your best friend is your ordinary browser. Point it to the data directory where the EngineDJG index.html file is located and see if you can see an empty dial. If you do not see, then hit Shift+Ctrl+I (Shift and Ctrl-keys hold down and press key “I”) to open the developer tools. Select the Console tab to see the quite verbose DashT InstruJS debug messages and hit Ctrl+F5 to reload the page. Usually, the point where the syntax error is located is clearly shown in red color.
NOTE: Windows owners should not throw away their beloved (?) Internet Explorer. In fact, the wxWidgets WebView back-end library on Windows port is as old as IE8! In that case, having the IE11 is not a bad idea for testing: you would hit key F12 to get the developer tools visible in this case. To reload a page it is F5.
Data “X” not available¶
The DashT EngineDJG dial is configured by selecting from data available on your boat’s NMEA-2000 instrumentation bus and referred as Signal K data key. It may occur that after a reconfiguration of Signal K server node, or from some other reason a data path (a data source) is not available anymore. If there is a EngineDJG instrument on your Dashboard configured to display that data path, it remains waiting for that data forever, in vain.
The simplest remedy for this is to destroy the instrument and create a new one if needed.
But supposing that you are attached to this particular instrument position for some reason (!) there is another way which requires that you shut down OpenCPN first:
Open the OpenCPN ProgramData/opencpn/opencpn.ini file (~/.opencpn/opencpn.conf in Linux) and find the instrument declaration section, easiest by using the dashboard’s title for your search. There is a UID-field with a long, arbitrary string for each instrument based on web-techniques. Now, without altering the total lenght or the format change one single arbitrary number in the UID-field of the instrument you want to reconfigure and save the file.
When you restart OpenCPN, the instrument has forgotten its configuration and you can reconfigure it again to one of the data paths in your new NMEA-2000 configuration.