Skip to content

Installing the GX app

The GX app displays the regulator's dashboard on any GX device with Venus OS v3.70 or later. Initial installation is (for now) by USB stick or a microSD card. Updates from there are possible over the GX's internet connection.

What you need

  • An XREG-010 regulator on firmware 0.0.10 or later, on the same network as the GX.
  • A USB stick formatted FAT32. A microSD card also works on a GX with a card slot.
  • The file venus-data.zip, which is always the newest release.

Download venus-data.zip

The file must be named exactly venus-data.zip on the stick, at the top level and not inside a folder.

First install

  1. Copy venus-data.zip to the stick.
  2. Plug the stick into a USB port on the GX.
  3. Restart the GX: Settings > General > Reboot, then Reboot now and OK. Venus OS reads the stick only while it starts, so plugging the stick into a running GX does nothing until the next restart.
  4. When the GX has fully restarted, remove the stick.

The install needs no SSH access, no root password, and no change to the GX's settings. If the app does not start after the install, the GX removes it again and is left as it was before. A stick left in the GX does no harm: at each restart the GX compares the release on the stick with the one installed and skips it unless the stick holds a newer one.

The same stick repairs an install. If the app stops starting after a restart, for example because another add-on rewrote /data/rc.local, restart the GX with the stick in. The GX installs the same release again when the app's startup line, its plugin link, or any of its files is missing or changed.

Where the app appears

  • Settings > Integrations, under UI Plugins, as "XREG-010". With one regulator added, this entry opens the app.
  • The alternator's page in the device list (Overview, then the alternator tile), as Dashboard at the bottom of the page.
  • The switch pane, the second icon at the top left of the main pages, once a regulator is added.

With no regulator added yet, the Integrations entry shows a Regulators row. Its page lists the XREG-010 regulators the GX finds on its network: tap Add next to yours and confirm.

Updating from the app

Open the GX app page: in the app's Settings tab, choose System, then Connection, then GX app. With no regulator added, the page is under Settings > Integrations > XREG-010 > GX app.

Opening the page checks X Engineering's server for a newer version, and Check for updates checks again. The GX checks at no other time. The request asks only for the list of releases and sends nothing about the GX, the boat, or the regulator. The GX needs an internet connection for the check and the download.

When a newer version is listed, tap Update and confirm. A version number issued again with a newer build also counts as newer; its build date is listed under the version. The GX downloads the package, checks its signature against X Engineering's key, and installs it. The app's pages and its link to the regulator restart. If the new version does not start, the GX puts the previous version back and lists the reason under Last update. The GX refuses a package with a signature that does not match, and never installs an older version over a newer one.

What the app changes on the GX

The app's files go in /data/apps/available/xregulator and /data/xregulator, both on the GX's data partition. The app starts its bridge at each boot from one line in /data/rc.local, placed right after the file's first line. If that file already exists, its other lines are kept as they are, with two exceptions that Venus OS would otherwise refuse: a file with Windows or old Mac line endings gets Unix line endings, and a file that is not executable is made executable. Either change makes the file's other lines run at boot as well, and the GX app page says so under Last update.

Venus OS lists that file under Settings > General > Support status as a custom startup script. If custom startup scripts are disabled on that page, an install from the stick still starts the app until the next restart, and the GX app page says under Last update that the app will not start after a restart until they are re-enabled. After such a restart the GX app page, and the XREG-010 entry under Settings > Integrations, show that the bridge is not running and why.

Removing the app

  1. If the install stick is still in the GX, remove it. Otherwise the next restart installs the app again.
  2. Open the GX app page and tap Remove the GX app, then OK.

The GX removes the app's pages, its switch pane controls, the bridge, and its startup line. The regulator itself does not change. The list of regulators the GX had added stays in the GX's settings, so a later install picks up the same regulators.

Slowing the plots on an older GX

The Dashboard numbers and the Short Term plots update about 10 times a second. That load can slow an older GX, and the Slower plotting setting drops both to once a second.

The app checks for this once by itself. With Automatic plot rate on, which is the default, it measures the GX's processor load for 30 seconds while Short Term is on screen. It turns Slower plotting on if the GX is at least 70 percent busy, or if drawing the screen takes at least 90 percent of one processor core. The result is listed under Automatic plot rate on the GX app page.

To set it yourself:

  1. Open the GX app page, as described under Updating from the app.
  2. Turn on Slower plotting.

The same switch is below the charts on the Short Term tab under Plots. Changing it yourself turns Automatic plot rate off. Turning Automatic plot rate back on clears the measurement, and the app measures again.