Venus OS hosted web app

The "app" is a single page application that communicates to the rest of Venus OS via MQTT over websockets. It uses React with ES6 for the UI layer and also includes a wrapper service for the MQTT interface.

Its primary purpose is to be a simple to use and nice looking UI for a Victron system on marine Multi Functional Displays, such as the ones from Garmin, Simrad and others. This removes the need for a Victron panel at the helm: less clutter on the dashboard.

The secondary purpose is to help OEMs, boat builders and motorhome builders for example, make their own custom UI.

0. Contents

Chapters in this readme:

1. Functionality.
2. Development
3. Testing
4. Making a release
5. Device error logging
6. Device debugging

1. Functionality

1.1 Documentation per Box

Boxes are the various designed visualisation: there is a Battery box, a Generator box, a Shorepower box, and so forth.

How certain devices are visualised/rendered on HTML5, ie. in to what box(es), and what topics are used for what parameter, and more is documented in three places:

• TOPICS.md
• wiki/Translating system components into the HTML5 app
• wiki/Dashboard overview

1.2 Handling disconnects

When devices are disconnected from the GX Device, see this issue for what happens on the D-Bus.

On MQTT, this is translated into sending an empty message on the subs which depend on the lost service. Depending on the element we show either -- for the value (in the case of numeric values) or another default state for the component (like disconnected for the active source).

2. Development

2.1 Initial setup

If it's the first time you run the app:

• make sure to have node & npm installed on your machine
• run npm install in the root folder

2.2 Development

To run the app locally for development, run:

npm run dev

And then open the app in the browser at http://localhost:8000.

This will start the webpack dev server, which will recompile the app on code changes and hot reload the UI.

You can change the host and port (although the default 9001 is usually correct) query parameters to point to your Venus device:

http://localhost:8000?host=localhost&host=<VENUS_DEVICE_IP>&port=9001

This way you can run the local app against venus device data if the venus device is on the same network as your computer.

2.3 Running the app with no Venus device available

The mqtt mock is no longer mainainted. Use venus-docker instead or a Venus GX in demo mode (below).

If there is no real device to be used for MQTT data, you can run the app with a fake MQTT broker:

npm run dev:mocked This shallowly fakes the MQTT implementation in the Venus device.

Also keep in mind the Venus device also has a Demo mode, which allows you to get useful data if you only have the Venus device available, without requiring various Victron devices to be connected to the Venus device. To enable it, navigate to the Venus Remote Console -> Settings -> General.

2.4 Device radiator

Since the app will be run on a plethora of different resolutions and split screens there is a "radiator" available which has iframes for all the basic combinations of display "splits". The base 1/1 ui is 1280 x 720, which can be changed in the header. In the radiator there are the basic ui and multiple split screen variations available relative to the "base" size.

To run this ui it is recommended to use mocked data. Run the mocked mqtt as described above and navigate to the radiator ui with http://localhost/radiator.html. Since it is still served through the webpack dev server, the app will hot reload any time there are code changes.

2.5 Metrics available

• Identify the D-bus channel that you want to read from here
• Create a component using MqttSubscriptions or MqttTopicWildcard and pass the topic as the wrapper topi. See examples in other components

2.6 Deploying to a device during development

2.6.1 Get the device ip

In order to deploy you need to know the target device's IP. It can be connected to by ethernet, LAN or the device's own WLAN. Instructions on how to find the IPs can be found here for the Venus GX device.

2.6.2 Run deploy script

In the project main folder run ./bin/deploy.sh <ip> where ip is the target device's IP. The script also accepts an additional --user|-u param that defines the user for the deployment connection. This defaults to root.

The deploy script also bundles the app. Nore that the script assumes that it's run from the root folder of the application.

2.6.3 Navigate to the app address again on the target device

Once deployed reload the page by navigating to the Venus host IP on the target device. If you have enabled dev features and have previously deployed a new version of the UI to the device you can press the reload page on the top left corner of the page.

3. Testing

3.1 Venus OS Release test plan

In the Venus OS release test plan there is a tab containing all tests.

3.2 Enzyme

Most components have Enzyme unit tests. Run all of these tests with npm run test:unit

3.3 Cypress

Cypress is used to run integration tests on the compiled ui to make sure it opens and operated correctly in different display sizes. To run cypress you need to run the live server and an instance of venus docker in the Venus GX demo mode (z):

(in html5 app repo): npm run dev

(in venus docker repo): ./run.sh -s z

Then you can run the cypress ui with npm run cypress.

To run the ui tests in CI-style use npm run test:e2e

4. Making a release

Whenever a new tag is created, GitHub Actions will build the app, archive the built files and upload them as venus-html5-app.tar.gz to the Github Release associated with the tag. The app can then be downloaded from https://github.com/victronenergy/venus-html5-app/releases/download/<TAG_NAME>/venus-html5-app.tar.gz. The build script expects the tags to follow semantic versioning (e.g. 1.2.3, 1.2, etc.) and will not trigger for tags that don't follow this convention (e.g. v1.0, test).

To include the HTML5 app in the next Venus OS version:

1. Increment the version number in package.json. Create and push a commit.
2. Create & push a tag for the version (do not use v in the version name, just the number)
3. Update the todo page for the build

You should add a note under "waiting for recipe", containing the tag name and the changes included:

html5-app - <tag name>
<message>

For example:

html5-app - 0.2 \* Reworked the UI

If you need any changes to the how the app is included inside Venus, please specify in the TODO file as well what changes need to be made to the recipe. All Venus recipes are found here. A sample recipe for the HTML5 app is here

5. Device error logging

When the app is hosted from a VenusGX, there is no convenient way to see the errors in the js console. To make troubleshooting easier the app sends (at least attempts) to send the error messages through websocket to the device. The log can be found at /var/log/venus-html5-app/current.

6. Device debugging

By adding debug=true to the query params you can enable some convenience features for debugging on actual devices:

• "Reload page" button - refreshes the page
• "Browser info" button - links to page containing basic information about the browser in which the app is running
• A debug log element, which redirects all console messages to a visible element in the ui

To enable this on a device set the debugReload and debugLog elements to visible in index.html and deploy to the device.