Setup and usage

KOFA Lite: exporting a graph as a standalone program

KOFA Lite is a standalone program that also runs offline, built from a finished graph. It is a smaller KOFA that can do less: the graph is fixed, the program only runs it and shows the profile's dashboard. It has no graph editor, Komod list, Komod store, MCP, user management or database; only the Komod packages used by the graph and the instances' files (for example ONNX models) are included.

Typical example: a sailing "advisor" (GPS + wind → route following → steering and sail instructions) on the Raspberry Pi aboard, with its own display in kiosk mode; the phone joins the machine's own Wi-Fi hotspot, and there is no internet.

What you get and what you do not

Preparing the export

The export uses the saved state of the graph, so:

1. On the full KOFA's Gráf (Graph) page open the profile you want to export.
2. Check that every Komod used is installed and enabled (Komodok).
3. Check that every Komod you want to operate in the program has a widget on the dashboard: in Lite you cannot edit the graph, only operate it from the dashboard.

Exporting from the interface

In the top row of the Gráf page click the Exportálás programként (KOFA Lite) (Export as program) icon (next to Export to file). Only an admin can do this, because the export takes packages, models and Wi-Fi passwords out of the machine.

The dialog shows everything on one page; the sections follow.

Program, access, sign-in

The roles:

Kiosk mode, network and Bluetooth

Kiosk mode: when on, a full-screen browser with the Lite interface opens on the machine's own display (HDMI or touch screen) at start-up, and it cannot be exited (no address bar, no developer tools, no console switching). You can set the browser (Chromium or the lighter cog), screen rotation (0/90/180/270°), screen blanking (minutes, 0 = never) and hiding the cursor for touch screens. Exiting is for admins: from the interface (Kiosk kikapcsolása) or over SSH (sudo kofa-app kiosk off).

Network and Bluetooth:

Other settings and preview

The Preview shows, before you download, what goes into the package:

• the file name and the estimated size (before compression),
• the list of packages with version, the Komods in them and size,
• the instance files (models, routes): they can be excluded per folder, for example a recorder's gigabyte-sized recordings,
• the errors (these block the export) and warnings.

The Komod beállítások tab (only if the package has such a Komod) shows the Komods' deployment settings, for example the Bluetooth name or the simulator connector's addresses; these are written over the instances' own settings.

The Exportálás (Export) button downloads a kofa-app-<name>-linux-arm64.tar.gz file.

Common export errors

Exporting from the command line

You can use the same service without the server (in CI, in scripts):

dotnet run --project tools/Kofa.Export -- \
  --graph examples/graphs/vitorlas-tanacsado-szimulator.kofa-graph.json \
  --packages artifacts/komods \
  --template artifacts/lite \
  --options options.json \
  -o ./out

The --options file holds the dialog's settings in JSON, for example:

{
  "name": "Vitorlas tanacsado",
  "rid": "linux-arm64",
  "access": { "mode": "lan", "port": 5090 },
  "auth": { "mode": "password", "operatorPassword": "…", "adminPassword": "…" },
  "hardwareBackend": "auto",
  "instanceControl": true
}

The --preview switch only prints the preview, without a file. The runtime template is built by tools/build-lite.sh (artifacts/lite/<rid>/); in a release it is the kofa-lite-<version>-<rid>.tar.gz file.

What is in the exported package

kofa-app-<name>/
  install.sh, uninstall.sh   installer and uninstaller
  bin/                       the Kofa.Lite program and client, the kofa-app helper
  app/                       app.json, graph.json, dashboard.json, komods/, instances/
  system/                    systemd units, polkit rules, browser policy
  OLVASS-EL.txt              short instructions for this export

Installing on the target machine

The target machine is a fresh Ubuntu Server 24.04 arm64 on a Raspberry Pi 4 (with SSH). The program is self-contained: no .NET is needed on the machine.

scp kofa-app-vitorlas-linux-arm64.tar.gz ubuntu@<machine>.local:/tmp/
ssh ubuntu@<machine>.local
cd /tmp && tar xzf kofa-app-vitorlas-linux-arm64.tar.gz
cd kofa-app-vitorlas
sudo ./install.sh

The installer, in order:

1. checks the machine (root, aarch64, systemd, Ubuntu, free space) and the package (format, platform, SHA-256);
2. stops and disables the full KOFA if it runs on the same machine (they would claim the same hardware); when replacing another program it asks first and backs up the old data under backup-<date>;
3. installs the missing system packages, only those the settings need: BlueZ (Bluetooth), NetworkManager + dnsmasq-base + avahi-daemon + iw (network), cage + a browser (kiosk), libusb for USB Komods; enables I2C if the graph has a hardware Komod;
4. creates the kofa-app system user (and kofa-kiosk for the kiosk);
5. copies the program to /opt/kofa-app, processes the secrets (Wi-Fi passwords) and creates the machine settings file /etc/kofa-app/local.json;
6. sets up the network (hotspot / client) and installs the kofa-app.service unit, and the kofa-kiosk.service unit for the kiosk;
7. starts the program, waits for it to respond and prints a summary: the interface addresses (IP, <hostname>.local, and for a hotspot the SSID and 10.42.0.1), the kiosk state and where to change passwords.

Installer options

They override what was chosen at export time:

Re-running is an update: the program is replaced, while /var/lib/kofa-app (data) and /etc/kofa-app (machine settings) are kept.

With one command from the development machine

tools/deploy-lite.sh --host 192.168.2.224 --user kofa-hw1 --key ~/.ssh/KOFA-HW1 \
    --app ~/Downloads/kofa-app-vitorlas-linux-arm64.tar.gz [--remove-full] [-- --no-kiosk --port 5090]

The script unpacks the export, completes it with the runtime template, uploads it and runs sudo ./install.sh --yes on the target (it asks for the sudo password in the terminal). --remove-full deletes the full KOFA from the machine after a successful install. Options after -- go to install.sh. For several machines, use the same package with a different --host.

Where everything is after installation

The Lite interface

Open http://<machine>:5090 (or http://<hostname>.local:5090, on the hotspot http://10.42.0.1:5090); in kiosk mode it appears on the machine's display by itself.

Sign-in

In password mode the pages ask for the operator password. For admin functions, Belépés adminként (Sign in as admin) in the menu takes you to the admin password page.

Dashboard

The fixed dashboard with the graph's Komod views. The header always has the red STOP (emergency stop), the warning badge (it leads to the Status page) and the menu.

Status

The Állapot (Status) page shows the program name and revision, the graph state, the hardware backend, the start time, the number of emergency stops, the connection and the graph's problems.

Network

The Hálózat (Network) page (admin) is the same as in the full KOFA: Wi-Fi status, connecting, own hotspot, fallback hotspot, Bluetooth and the connection QR code for the KOFA app. Whatever could break the connection starts in trial mode: if you do not confirm within 2 minutes, the previous setting is restored.

Administration

On the Adminisztráció (Administration) page (admin) you change passwords, upload a newer export (Frissítés új exporttal), restart the program and power the machine off (so on a boat the power can be removed safely). In relay mode the pairing code is shown here too.

Managing the machine over SSH: kofa-app

After installation the kofa-app command always lets you manage the program on the machine, even if the interface is unreachable.

Uninstalling: sudo ./uninstall.sh (or sudo kofa-app uninstall) stops and removes the services and /opt/kofa-app; --purge also removes the data and machine settings. It does not touch the network settings.

Updating

Two ways:

• From the interface (if the export allowed it): Adminisztráció → Frissítés új exporttal: upload a newer kofa-app-….tar.gz export. The machine checks it, installs it as root and restarts the program. If the new program does not start, the previous one is restored; the Administration page shows the result (succeeded, rolled-back, failed) and the installer's log. Passwords, kiosk, port and data are kept.
• Over SSH: sudo ./install.sh from the new package, or tools/deploy-lite.sh.

Troubleshooting

More: Installing KOFA and first-time setup, Troubleshooting.