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.
Chapters in this readme:
- Functionality.
- Development
- Testing
- Making a release
- Device error logging
- Device debugging
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:
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).
If it's the first time you run the app:
- make sure to have
node&npminstalled on your machine - run
npm installin the root folder
To run the app locally for development, run:
npm run start
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.
The MQTT mock is no longer maintained. Use venus-docker instead or a Venus GX in demo mode (below).
You can run multiple venus-docker simulations by executing: echo {a..z} | xargs -n1 ./run.sh -s. Each container running a simulation will expose MQTT on
an increasing port number starting from 9001.
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.
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.
- 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
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.
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.
Since Venus OS 2.80, placing the build of the app in /data/www/app allows for serving a different version of the app than the one bundled with Venus OS at /var/www/venus/app. When the /data/www/app is present, it'll be server at venus.local/app and the original application at venus.local/default/app.
By creating an archive named venus-data.zip that contains the build files from the dist inside an www/app/ folder will ensure that the /data/www/app folder will be created and the content of the archived extracted when the GX device is rebooted.
The content of the /data partition is persistent across firmware updates.
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.
POEditor is used as localization management platform for this project. In order to sync the translations using the scripts from the poeditor folder, an API key has to be placed in the .env.local according to the .env.local.example file.
yarn poeditor:push
Running the command will trigger the following actions:
- Add the terms of the main language file (default: en)
- Add new languges to the POEditor project if they are available locally but missing in POEditor
- Add the local translations for all the languages
- Mark translations as fuzzy if there are changes in the translation of the main language
yarn poeditor:push -f
Running the comamnd with the -f flag will delete the terms from POEditor that are not present in the local file.
Please use with caution. If wrong data is sent, existing terms and their translations might be irreversibly lost.
yarn poeditor:pull
In the Venus OS release test plan there is a tab containing all tests.
Most components have Enzyme unit tests. Run all of these tests with npm run test:unit
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
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:
- Increment the version number in
package.json. Create and push a commit. - Create & push a tag for the version (do not use
vin the version name, just the number) - Update the todo page for the build
You should add a note under Done - waiting for recipe / venus maintainer, containing the tag name and the changes included:
html5-app - <tag name>
<message>For example:
html5-app - 0.2 \
* Reworked the UIIf 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
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.
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.