USB Stick Installation

What The USB Installer Does

The installation page shows the steps: download the installer, copy it to a USB stick, restart the GX with the stick inserted and finish in your browser. This chapter explains what happens on the GX and what to do when something goes wrong.

When the GX starts, Venus OS finds the installer on the stick and runs it. The installer:

• Checks that the GX runs Venus OS on a supported processor, that Settings → General → Modification checks → Modifications enabled is on, and that the GX has enough free storage.
• Checks the signature and checksum of the Phaeton package, and stops if either does not match.
• Stops a running Phaeton and backs up the existing installation before it replaces any files.
• Installs Phaeton in /data/phaeton and adds its own startup line to /data/rc.local, keeping any other startup commands.
• Starts Phaeton and checks that its web interface answers.
• Writes the result to the stick, and ejects the stick when the installation succeeded.

The GX needs no internet connection, and you need no SSH, root password or setup code. A new installation connects to the GX over MQTT and can be opened through VRM Control Panel before setup, once the GX is online.

Allow five minutes and wait for USB activity to stop before you remove the stick. Do not remove a busy stick or interrupt the GX power. Five minutes alone do not prove that the stick is safe to remove; if you are unsure, leave it inserted and contact support. You can finish setup in the browser with the stick still in.

Which GX Devices It Supports

• GX devices with 32-bit Venus OS, such as the Cerbo GX, Cerbo-S GX, Ekrano GX, Venus GX, Octo GX, MultiPlus-II GX and EasySolar-II GX, and Venus OS on a Raspberry Pi 2, 3 or 4. The installer checks for 32-bit Venus OS and stops with a message on any other device.
• Newer Cerbo GX units and the Raspberry Pi 5 run 64-bit Venus OS. The USB installer stops there with a message; use the SSH installation instead.
• Another Linux computer cannot use the USB installer; see Install on other Linux systems.
• The USB installer installs and updates the first Phaeton installation on the GX, in /data/phaeton, which opens on port 8088. Chargers you added under System → Chargers on this GX keep their own software; update them on that page.
• Only the file named venus-data-phaeton-VERSION-armv7.tgz works from a stick. A .phaeton-update file updates Phaeton on its Updates page, and the regular .tar.gz packages are for the advanced installation. Older releases may have no USB installer.
• You need physical access to the GX and a restart, a dedicated FAT32 stick with an MBR partition table and at least 256 MB free, and free storage on the GX for the new version plus a backup of the existing installation.

Files On The Stick

After an installation attempt, take the stick out and open it on your computer. You find:

• venus-data-phaeton-VERSION-armv7.tgz: the installer. Keep it unopened, with its original name, at the top level of the stick. Keep only one installer on the stick.
• PHAETON-RESULT.html: the result of the latest attempt. It shows Phaeton's local address and the SHA-256 fingerprint of its certificate, which you compare with your browser before you sign in. It contains no password or setup code.
• PHAETON-<GX-identity>.log: a log for each GX the stick was used on. It lists the installer steps with UTC times and OK or FAIL, without configuration, passwords or license data. A later attempt on the same GX adds to the same log.
• vrmlogger-backlog.sqlite3: Venus OS may create this for its own VRM logging. Phaeton does not need it; keep it if the GX has VRM data that has not been uploaded yet.

The log times come from the GX clock, which can be wrong on a GX without internet.

Remove Or Run It Again

• Take the stick out once the installation is done and USB activity has stopped. A stick that stays in installs its Phaeton version again at every GX restart, also over a newer version you installed later.
• To repair or reinstall, insert the stick and restart the GX. The installer installs the version on the stick, also an older one, and keeps the configuration, identity, license and saved state. If the new version does not start, it restores the previous files.
• To update, use System → Updates in Phaeton, online or with a .phaeton-update file, without restarting the GX. To update from a stick instead, replace the installer on it with a newly downloaded one.
• You can use the same stick on several GX devices. Each GX writes its own log; the result file always shows the latest attempt.
• To uninstall Phaeton, take the stick out first, then follow Uninstall Phaeton.

Recovery

When Phaeton does not open after five minutes, or you want to know what happened, wait until USB activity stops, take the stick out and open PHAETON-RESULT.html and the log for this GX on your computer. The result page shows its message in English and Dutch. In the log, a step that failed is marked FAIL with its reason. A successful attempt ends with an END line and the start of the USB eject; any other log that ends on a START line was interrupted.

What The Result Says

• Phaeton started. Finish setup in your browser: The installation worked. Open the address on the result page, compare the certificate fingerprint and follow First-run onboarding.
• Phaeton was installed and started: An existing installation was updated with its configuration, identity and license kept. Open Phaeton and check Settings for notices.
• Phaeton started in configuration recovery: Phaeton runs with safe settings and charging stays off. Open Settings, correct what it reports and save; Phaeton restarts by itself.
• Installation in progress: The attempt has not finished. Wait until USB activity stops. If the message stays, restart the GX with the stick inserted to try again, and read the log.
• This USB package does not match the GX architecture: The GX runs 64-bit Venus OS, as a newer Cerbo GX or a Raspberry Pi 5 does. Use the SSH installation.
• This is not Venus OS, or the GX lacks installer tools or flock: Use the SSH installation, or contact support.
• Enable modifications: Turn on Settings → General → Modification checks → Modifications enabled, then restart with the stick.
• Not enough GX storage: Free storage through the GX settings and try again. Do not delete Phaeton data to make room.
• Phaeton storage is not writable, or the Phaeton directory is a symlink: Contact support.
• The archive could not be read: Download the installer again and copy it to a different writable FAT32 stick.
• Signature or checksum failed: Download a new installer from the installation page. Nothing was started. Never try to get around this check.
• Another installer owns the installation lock: Another installation is running or stopped halfway. Restart the GX and try again; contact support if it persists. The USB installer never removes the lock of an SSH installation.
• Installation write failed: Your existing data is kept. Restart with the same stick to resume. If the stick is failing, copy the same unopened installer to a new FAT32 stick, disconnect the old one and try again.
• Phaeton did not pass the startup check: Phaeton did not start, and the installer could not yet put back what was there before: the log shows FAIL rollback.restore, the backup stays on the GX and the restore is tried again when the GX restarts. Another program on port 8088 can cause this. Restart the GX to try again; if it repeats, contact support with the result and the log.
• The update could not start: The new version did not start, and the installer put back what was there before. After an update, the previous installation runs again, so open Phaeton as before. After a first installation, Phaeton is not installed. Another program on port 8088 can cause this. Restart the GX with the stick to try again; if it repeats, contact support with the result and the log.

No Result On The Stick

When the stick has no PHAETON-RESULT.html, or still shows the result of another GX, the installer did not run on this GX. Check that:

• You restarted the GX with the stick inserted. The installer runs only while the GX starts.
• The file is the unopened .tgz with its original name, at the top level of the stick and not in a folder. Safari on macOS can unpack downloads; turn off its option Open "safe" files after downloading and download again.
• The stick is FAT32 with an MBR partition table, writable and not write-protected.
• There is only one Phaeton installer on the stick, and no other USB stick or memory card is connected.
• The stick is in a USB data port, not the power-only port for a GX Touch.
• Settings → General → Modification checks → Modifications enabled is on.

Still nothing? Try another stick and download the installer again. A stick the GX cannot write to cannot receive a result even when the installation worked, so also try https://GX-IP:8088/ in your browser.

Before You Try Again

• On your computer, delete the old PHAETON-RESULT.html and any temporary .phaeton-result files from the stick, so an old result is not mistaken for a new one. Keep the installer.
• An update that was interrupted, for example by a power cut, is restored first at the next attempt, also with a different stick.
• If the result says Existing Phaeton preserved, the stick holds an old installer. Download the current one to update.
• Never reset the GX to factory settings or delete Phaeton's configuration or license files to recover. Contact support and send the result and the log; they contain no secrets.
• A successful installation does not prove that the charger is connected and configured. Check the Charging page and the charger connection before you rely on charging.

Next Steps

Install on Victron GXFirst-run onboardingOpen through VRM Control Panel