The instrument has in-app help accessible from the Settings Page. Boxes that require more complex configuration have help accessible from their configuration pages.
To install the Boat Instrument follow these instructions.
The configuration is stored in JSON format in the “boatinstrument.json” file. This can be exported and imported from the Settings Page. Its on disk location depends upon the OS being used.
Note: before starting on flutter-pi installs, if “/boot/boatinstrument.json” exists it is moved to “/boatinstrument.json” and if “/boot/boatinstrument.config” exists it is moved to “/etc/boatinstrument-fpi/config”.
This allows you to update the configuration on a minimal OS via the SD Card, e.g. one without SSH or other access.
If you exit the instrument (from the Settings Page) the configuration file is copied to “/boot/boatinstrument.json.running”. The instrument is then restarted.
If required, the config can be manually edited. This is easier if it is reformatted with:
python3 -m json.tool boatinstrument.json >boatinstrument-formatted.json
If the “–enable-set-time” command line option is given, e.g. in “/etc/boatinstrument-fpi/config”, then you can set the Operating System time from the “navigation.datetime” path by enabling “Set Time” in the Advanced Settings.
The aim of the app is to provide an instrument closer to a standard marine display, rather than a general dashboard like Kip and without the overhead of a browser. The app can also be run without a desktop environment on dedicated hardware.
The app displays Pages of Boxes in very flexible layouts and has a framework designed to imposes the minimum amount of restrictions on the contents of a Box, whilst also providing simple APIs for subscribing to SignalK data.
The aim was to allow multiple developers to produce Boxes that fitted their particular needs, without having to worry about or re-code things like connection handling, path subscriptions, data timeouts, Page layouts and Box selection.
The Boxes are generally designed to provide the most relevant information in the clearest possible way. There are some base Boxes and gauges that can easily be extended to display new data values, but you are not forced to use these if a different display represents the data better, e.g. the rudder angle Box is specifically designed so it can be place along the bottom of a Page, in contrast to other dashboards where you have to display the rudder angle in a standard needle gauge.
For a fuller example, the design decisions for the wind rose include:
This is in contrast to trying to replicate a classic physical instrument, like a Raymarine i60. The physical instrument can’t switch between a standard and close hauled rose, is cluttered with text and boat outline and has a small speed display that’s difficult to see from a distance and can be obscured by the needle.
If the app is missing a Box for data you would like, then please raise an request/issue, or if you would like to collaborate please get in touch.
When a page is displayed, the Boxes register the paths they require. After consolidation to remove any duplicates, the app then subscribes to these via a SignalK WebSocket.
The current list of subscriptions being used by the app can be viewed from the Settings page.
This is list of Box to Path Mappings.
The Service Discovery API on Linux returns IP addresses, whereas the other OSs return hostnames. This causes issues if your SignalK host has an IPv6 address, as the API may return this without the Scpoe ID suffix. This causes the connection to fail.
The simple fix is to disable IPv6 on your SignalK host using the NetworkManger, e.g. nmtui.
If you leave it enabled, then to connection will likely succeeded after some failed attempts as the Service Discovery will eventually return the IPv4 address.
If you need to use IPv6 addresses for your SignalK server, then explicitly specify the required URL, including the local Scope ID/Interface Name, e.g. “http://[fe80::bf92:7cd4:fbb:1234%wlp1s0]:3000”
Full functionality requires the acceptance of this pull request to the signalk-starlink plugin.
Previous to version 3 of the config settings, authentication was stored on a Box Type basis. This allowed different Boxes to have different levels of authentication. From App version 0.8.0, when Remote Control functionality was introduced, the main App needed authentication. So authentication was simplified and moved to a single “Auth Token” at the App level.
The migration to the v3 config attempts to pick the best “Auth Token” from any already in the config and favoured the Box that required the highest level, i.e. the Anchor Alarm.
The issue that can arise, is that the user may have deleted that device from the SignalK security settings. This results in the following rather cryptic exception when connecting:
WebSocketChannelException: WebSocketException: Connection to 'http://signalk-server:3000/signalk/v1/stream?subscribe=none#' was not upgraded to websocket, HTTP status code: 401
This can be fixed by either deleting the “Auth Token” or requesting a new one with the required access level.
Note: the sample configuration files prior to version 0.10.0 also contained Auth Tokens by mistake. These could also be migrated by mistake.
Bareboat Necessities (BBN) installs are currently done from a separate clone of the Boat Instrument repo and therefore do not update.
Mikhail is working on an fix, but he’s a very busy man.
In the interim you can remove the install before subscribing to the repo:
rm $HOME/.local/share/applications/boatinstrument.desktop
rm -rf $HOME/boatinstrument
rm $HOME/.config/autostart/boatinstrument.desktop
Install the latest version by following these instructions. The app will then auto update.
If you would like the app to continue auto-starting:
ln -s /usr/share/applications/name.phil.seeley.boatinstrument.desktop $HOME/.config/autostart/
If you do not or cannot install the signalk-boatinstrument-plugin, then you may experience odd timing issues when using functionality like Timers or Remote Control.
These functions update paths on the SignalK server and this can result in multiple instances of the same path if done without the plugin. This happens because SignalK treats updates over WebSockets from different clients as different sources.
The plugin is considered the source when it performs updates and therefore avoids the multiple instance issue.
Most issues only become apparent when subscribing to paths, as SignalK will initially send the values of all instances, e.g. if you switch to a Page with a Timer Display Box, then all instances of that Timer’s path will be sent. If one value is Running and one is Stopped the results are indeterminate.