Setup and usage

Installing KOFA and first-time setup

This guide covers installing the full KOFA and the first settings: where to get it, how to start it, what is where in the interface, and how to get to your first working vehicle. The screenshots were taken on a fresh installation (the interface language is Hungarian).

What you get

KOFA consists of a server and a browser-based interface. Features are provided by Komod plugins (sensor, controller, camera, AI, display); you connect them on the Graph page, and the Dashboard shows the result.

Which edition to choose

The installers and releases can be downloaded from kofa.kncsk.hu.

Installing on Windows

1. Download the KOFA-Setup-<version>-win-x64.exe installer and run it (administrator rights are required).
2. The wizard asks you to accept the license, then installs KOFA Developer (by default to C:\Program Files\KOFA Developer). Data goes to C:\ProgramData\Kofa and is not removed on uninstall.
3. Start the KOFA Developer shortcut from the Start menu. A console window with the log opens, and the browser opens http://localhost:5080.

The Windows edition is for development: hardware Komods (PCA9685, camera, INA219) run with simulated hardware, and Wi-Fi and Bluetooth management are simulated or unavailable.

Installing on a Raspberry Pi (Ubuntu Server / Raspberry Pi OS)

Preparation

• The recommended system is Ubuntu Server 24.04 LTS (64-bit) or Raspberry Pi OS Lite 64-bit (Bookworm). No desktop is needed.
• In the Raspberry Pi Imager settings (gear icon) set the host name, the user, SSH and, if needed, Wi-Fi.
• The package is self-contained: no .NET needs to be installed on the machine.

With one command (internet required)

curl -fsSL https://kofa.kncsk.hu/install-kofa.sh | sudo bash -s -- --lan

Manually, from the release package

Copy kofa-linux-arm64.tar.gz to the machine, unpack it and run the installer:

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

The installer creates the kofa system user, enables I2C, installs the Bluetooth packages, copies the program to /opt/kofa and starts the kofa systemd service. At the end it prints the address and the setup token.

On Ubuntu, I2C is enabled in /boot/firmware/config.txt; after that the machine must be rebooted once. Detailed options, wiring and the network steps: docs/DEPLOY-rpi.md.

Where everything is after installation

Useful commands:

sudo systemctl status kofa          # is it running
journalctl -u kofa -f               # live log
journalctl -u kofa | grep "one-time token"   # the setup token

First start: creating the admin account

There is no default password. On first open, a fresh KOFA takes you to the Első indítás (First start) page.

1. Setup token: the server prints it into the log at start-up (on Windows into the console window, on Linux at the end of the installer and in journalctl -u kofa). It is a one-time, 16-character code.
2. Admin user name and password (at least 10 characters, twice).
3. E-mail: optional, but can be used to sign in.
4. Click Admin létrehozása (Create admin): you are signed in right away.

From then on, every sign-in happens on the sign-in page.

The interface: what is where

After signing in, use the menu on the left. An Admin sees everything; an Operator can edit graphs and drive the vehicle; a Viewer is read-only. The system, network and user management pages are for admins.

The Komodok page shows what is installed:

Installing Komods

In the Linux release package the Komods are not included: they are installed from the Komod store (kofa.kncsk.hu). Reading the store does not require signing in.

1. Open Komodok → Komod tár (Komod store).
2. Search by name, description or port type, and filter by category or vehicle.
3. Before pressing Telepítés (Install) you can inspect the package contents; KOFA compares the downloaded file's checksum with the index.
4. Update package by package or with the Mind frissítése (Update all) button.

Packages from other sources (.komod files) can be installed by dropping them on the upload area of the Komodok page; KOFA shows the contents before installing. Writing your own Komod: Komod development.

Network: Wi-Fi, hotspot, Bluetooth

The Hálózat page (admin) manages the machine's Wi-Fi and Bluetooth adapter. On Linux, NetworkManager does the work: pass --network to the installer. (On Windows and development machines the page shows a simulated network.)

• Connect to another Wi-Fi (hidden networks too); order and removal of saved networks.
• Own hotspot: the machine shares Wi-Fi itself (SSID, password, band); a phone that joins reaches it at 10.42.0.1. Where there is no internet (on the water, at the track) this is the most common access.
• Fallback hotspot: if the machine finds no known network at start-up, it starts a hotspot by itself.
• Connection QR code for the KOFA app.

Your first graph

The graph is your vehicle's "wiring": Komod instances connected through typed ports (an output can only be linked to an input of the same type).

There are two ways to get a first graph:

• Import a ready example (recommended to start): the examples/graphs/ folder of the release and the repository contains ready profiles (car, sailboat, simulator and live variants). Choose the *.kofa-graph.json file with the Import graph icon. The examples are also available on kofa.kncsk.hu, where you can build your own graph from them and from the Komods of the Komod store: Example graphs and the graph builder. The import always creates a new profile and warns about missing or differing Komod versions (install those from the Komod store first).
• Build from scratch: put a Komod on the canvas from the palette with the + button or by dragging, then drag a link from an output (right side) to an input (left side). Click a node to edit its settings. Delete: Delete.

The icons of the editor's top row (from the left): profile selector, New profile, Rename / vehicle type, Delete profile, Undo and Redo, Fit all, Versions, Export to file, Export as program (KOFA Lite), Import graph.

Activation

The Aktiválás (Activate) button brings the graph to life. KOFA first shows the validation (errors, warnings) and the changes: which instances are created, which are removed, which links change. Activation replaces the graph that is running now with this one.

After activation, the button is replaced by the Alkalmazva (Applied) indicator and the Leállítás (Stop) button.

The dashboard

The Dashboard shows the widgets of the active graph's Komods. With the Elrendezés button the tiles can be moved by dragging and resized in both directions; the icons in a tile's header open the Komod's interface in a larger view or in a dialog window.

Users and roles

On the Felhasználók page (admin) you add further accounts. Roles:

Access from elsewhere

Backup and update

• Backup: sudo systemctl stop kofa && sudo cp -a /var/lib/kofa ~/kofa-backup && sudo systemctl start kofa.
• Update: on the Rendszer → Frissítés card (admin) with one button, or by re-running the one-line installer (install-kofa.sh). The configuration (/etc/kofa) and data (/var/lib/kofa) are kept; on failure the previous version is restored.
• Updating Komods: Komodok → Komod tár → Mind frissítése.

Troubleshooting

More: Troubleshooting.

Next steps

• Make an offline program for the vehicle from your graph: KOFA Lite.
• Write your own Komod: First Komods (tutorial).