{"id":13672786,"url":"https://github.com/victronenergy/venus-html5-app","last_synced_at":"2026-01-08T14:59:43.058Z","repository":{"id":38419483,"uuid":"149340893","full_name":"victronenergy/venus-html5-app","owner":"victronenergy","description":"HTML5 App including Javascript library that communicates with Venus OS over MQTT websockets","archived":false,"fork":false,"pushed_at":"2025-03-12T12:52:00.000Z","size":21161,"stargazers_count":110,"open_issues_count":43,"forks_count":33,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-04-22T10:14:35.101Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/victronenergy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-09-18T19:25:03.000Z","updated_at":"2025-04-10T20:57:51.000Z","dependencies_parsed_at":"2023-10-16T22:28:55.389Z","dependency_job_id":"94a1b310-e69e-4df0-8593-a49c5d043cbb","html_url":"https://github.com/victronenergy/venus-html5-app","commit_stats":null,"previous_names":[],"tags_count":98,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victronenergy%2Fvenus-html5-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victronenergy%2Fvenus-html5-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victronenergy%2Fvenus-html5-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/victronenergy%2Fvenus-html5-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/victronenergy","download_url":"https://codeload.github.com/victronenergy/venus-html5-app/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251246394,"owners_count":21558762,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T09:01:48.366Z","updated_at":"2026-01-08T14:59:43.052Z","avatar_url":"https://github.com/victronenergy.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"![screenshot](/legacy/victron-webapp-screenshot.png?raw=true)\n\n# Venus OS hosted web app\n\nThe \"app\" is a single page application that communicates to the rest of Venus OS via MQTT over websockets.\nIt uses React with ES6 for the UI layer and also includes a wrapper service for the MQTT interface.\n\nIts primary purpose is to be a simple to use and nice looking UI for a Victron system on\nmarine Multi Functional Displays, such as the ones from Garmin, Simrad and others. This\nremoves the need for a Victron panel at the helm: less clutter on the dashboard.\n\nThe secondary purpose is to help OEMs, boat builders and motorhome builders for example,\nmake their own custom UI.\n\n## 0. Contents\n\nChapters in this readme:\n\n1. Functionality.\n2. Development\n3. Testing\n4. Making a release\n5. Device error logging\n6. Device debugging\n\n## 1. Functionality\n\n### 1.1 Documentation per Box\n\n`Boxes` are the various designed visualisation: there are a Battery box, a Generator box, a Tanks box, and so forth.\n\nHow 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:\n\n- [TOPICS.md](https://github.com/victronenergy/venus-html5-app/blob/master/TOPICS.md)\n- [wiki/Translating system components into the HTML5 app](https://github.com/victronenergy/venus-html5-app/wiki/Translating-system-components-into-the-HTML5-app)\n- [wiki/Dashboard overview](https://github.com/victronenergy/venus-html5-app/wiki/Dashboard-overview)\n\n### 1.2 Handling disconnects\n\nWhen devices are disconnected from the GX Device, see [this issue](https://github.com/victronenergy/venus-html5-app/issues/49)\nfor what happens on the D-Bus.\n\nOn 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).\n\n## 2. Development\n\n### 2.1 Initial setup\n\nIf it's the first time you run the app:\n\n- make sure to have `node` \u0026 `npm` installed on your machine\n- run `npm install` in the root folder\n\n### 2.2 Setting white label\n\nThis repository contains several white-label apps. To work with a specific app, set the correct `APP` environment variable in the `.env.local` file. For example, to build the `Marine2` app, use:\n\n```\nREACT_APP_WHITELABEL=Marine2\n```\n\nYou can find the list of available apps in the `.env.local.example` file.\n\n### 2.3 Run app locally\n\nTo run the app locally for development, run:\n\n`npm run start`\n\nAnd then open the app in the browser at `http://localhost:8000`.\n\nThis will start the webpack dev server, which will recompile the app on code changes and hot reload the UI.\n\nNote that the app will attempt to connect to MQTT broker served via the same port as the app and path `/websocket-mqtt`, and that will eventually fail.\n\nYou will need to change the `host`, `port`, and `path` (defaults to `/websocket-mqtt`) query parameters to connect to a different Venus websocket MQTT host.\n\nTo connect to a Venus device with `VENUS_DEVICE_IP` running firmware \u003e= 3.50 use the following URL:\n\n`http://localhost:8000?host=\u003cVENUS_DEVICE_IP\u003e\u0026port=80`\n\nTo connect to Venus device with `VENUS_DEVICE_IP` running firmware \u003c 3.50, or to a `venus-docker` simulation, use the following URL:\n\n`http://localhost:8000/app?host=VENUS_DEVICE_IP\u0026port=9001\u0026path=%02%03`\n\nNote: the `port` needs to be overriden to connect directly to `flashmq` provided websocket port.\n\nNote: the `path` URL parameter requires special sequence `%02%03` in order to properly override the default `/websocket-mqtt` path and specify an empty string.\n\nThis way you can run the local app against any Venus device that is reachable via your network.\n\n### 2.4 Using Demo mode on Venus device\n\nEvery 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` -\u003e `Settings` -\u003e `General`.\n\n### 2.5 Running the app with no Venus device available\n\nUse [venus-docker](https://github.com/victronenergy/venus-docker) in demo mode.\n\nYou 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\nan increasing port number starting from `9001`.\n\n### 2.6 Metrics available\n\n- Identify the D-bus channel that you want to read [from here](https://github.com/victronenergy/venus/wiki/dbus)\n- Create a component using MqttSubscriptions or MqttTopicWildcard and pass the topic as the wrapper topic. See examples in other components\n\n### 2.7 Deploying to a device during development\n\n#### 2.7.1 Get the device ip\n\nIn 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.\nInstructions on how to find the IPs can be found [here](https://www.victronenergy.com/media/pg/Venus_GX/en/accessing-the-gx-device.html)\nfor the Venus GX device.\n\nThe default device's IP address is `172.24.24.1`\n\n#### 2.7.2 Run deploy script\n\nIn the project main folder run `./bin/deploy.sh --build \u003cip\u003e` where ip is the target device's IP. The script also accepts an additional\n`--user|-u` param that defines the user for the deployment connection. This defaults to `root`. You will also need a password to connect to the device. To set the password, navigate to the `Venus Remote Console` -\u003e `Settings` -\u003e `General -\u003e Set root password`.\n\nThe deploy script also bundles the app if `--build` or `-b` . Note that the script assumes that it's run from the root folder of the application.\n\n#### 2.7.3 Deploying on multiple devices\n\nTo deploy the app on multiple devices, use `./bin/deploy-multiple.sh` script. This script uses a list of WiFi access points defined in `network.csv` file.\n\n#### 2.7.4 Deploying using a USB stick\n\nSince 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`.\n\nBy 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.\n\nThe content of the `/data` partition is persistent across firmware updates.\n\nTo create the archive, run `./bin/pack.sh` from the root folder of the application. This will create a `venus-data.zip` file. Place this file on a USB stick and insert it into the GX device, then reboot the device.\n\n### 2.8 Translations\n\n#### 2.8.1 Syncronizing the translations files with the POEditor Project\n\n[POEditor](https://poeditor.com/) 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.\n\n#### 2.8.2 Pushing the local translation files to POEditor\n\n```\nnpm run poeditor:push\n```\n\nRunning the command will trigger the following actions:\n\n1. Add the terms of the main language file (default: en)\n1. Add new languges to the POEditor project if they are available locally but missing in POEditor\n1. Add the local translations for all the languages\n1. Mark translations as fuzzy if there are changes in the translation of the main language\n\n```\nnpm run poeditor:push -f\n```\n\nRunning the comamnd with the `-f` flag will delete the terms from POEditor that are not present in the local file.\nPlease use with caution. If wrong data is sent, existing terms and their translations might be irreversibly lost.\n\n#### 2.8.3 Pulling the POEditor translations locally\n\n```\nnpm run poeditor:pull\n```\n\n## 3. Testing\n\n### 3.1 Venus OS Release test plan\n\nIn the Venus OS release test plan there is a tab containing all tests.\n\n### 3.2 Enzyme\n\nMost components have Enzyme unit tests. Run all of these tests with `npm run test:unit`\n\n### 3.3 Cypress\n\nCypress is used to run integration tests on the compiled ui to make sure it opens and operated correctly in different\ndisplay sizes. To run cypress you need to run the live server and an instance of venus docker in the Venus GX demo mode (z):\n\n(in html5 app repo): `npm run start`\n\n(in venus docker repo): `./run.sh -s z`\n\nThen you can run the cypress UI interactively with `npm run cy:open`.\n\nTo run the ui tests in CI-style use `npm run test:e2e`\n\n### 3.4 Simulating/Debugging MFD UI locally\n\nMFDs ship web browsers based on `AppleWebKit/537` or `AppleWebKit/601`.\n\nPartially Simulating the MFD web browser can be achieved by running any browser using the same engine.\n\nGoogle Chrome 49 runs `AppleWebKit/537`, so contains all the same CSS/JS limitations, and can be use to simulate/debug CSS issues faster.\n\n## 4. Making a release\n\nWhenever a new tag is created, GitHub Actions will build the app, archive the built files and upload them as `venus-html5-app-\u003cTAG_NAME\u003e.tar.gz` to the Github Release associated with the tag.\nThe app can then be downloaded from `https://github.com/victronenergy/venus-html5-app/releases/download/\u003cTAG_NAME\u003e/venus-html5-app-\u003cTAG_NAME\u003e.tar.gz`.\nThe 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`).\n\nTo include the HTML5 app in the next Venus OS version:\n\n1. Increment the version number in `package.json`. Create and push a commit.\n2. Create \u0026 push a tag for the version (do not use `v` in the version name, just the number).\n3. Edit the generated release, add the changelog, change title (see previous releases) and set checkbox \"Set as pre-release\" to true.\n4. Update the [todo](https://github.com/victronenergy/venus-private/wiki/todo) page for the build.\n\nYou should add a note under `Done - waiting for recipe / venus maintainer`, containing the tag name and the changes included:\n\n```md\nhtml5-app - \u003ctag name\u003e\n\u003cmessage\u003e\n```\n\nFor example:\n\n```md\nhtml5-app - 0.2 \\\n  * Reworked the UI\n```\n\nIf 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.\nAll Venus recipes are found [here](https://github.com/victronenergy/meta-victronenergy/tree/master/meta-ve-software/recipes-ve).\nA sample recipe for the HTML5 app is [here](https://github.com/victronenergy/meta-victronenergy/tree/master/meta-ve-software/recipes-ve)\n\n## 5. Device error logging\n\nWhen the app is hosted from a Venus device, there is no convenient way to see the errors in the js console.\nTo make troubleshooting easier the app can send the error messages through websocket port 7890 to the device.\nTo enable this debugging mode, setup https://github.com/vi/websocat on your Venus device, uncomment the debug code in `index.html`, and deploy to the device.\n\n## 6. Device debugging\n\nBy adding `debug=true` to the query params you can enable some convenience features for debugging on actual devices:\n\n- \"Reload page\" button - refreshes the page\n- \"Browser info\" button - links to page containing basic information about the browser in which the app is running\n- A debug log element, which redirects all console messages to a visible element in the ui\n\nTo enable this this debugging mode on a MFD device, uncommend the debug code in `index.html`, override the `debug=true` check, and deploy to the device.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvictronenergy%2Fvenus-html5-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvictronenergy%2Fvenus-html5-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvictronenergy%2Fvenus-html5-app/lists"}