Arkab

Electronic chessboard drivers for Elixir, and a bridge that sends a hall's boards to one or more Alnasl servers.

Arkab is used in two ways:

• As a library. Arkab.Driver.DgtSerial, Arkab.Driver.DgtBus, the serial protocol, loop and bus (Arkab.Dgt.*), a board emulator, the UART and fake transports, the capture format (Arkab.Capture), its recorder, and the replay player. Alnasl reads its local boards with these. As a dependency, Arkab starts no processes; whoever uses the drivers supervises them (Arkab.Drivers).
• As a bridge. A small program next to the boards, such as a Raspberry Pi in the hall. It reads every board on its ports, writes each event to a queue on disk first, and sends the queue over an outgoing WebSocket to every server it has joined. It never needs an open port facing the internet.

Install#

Every push to main builds all of these; a release attaches them. The addresses are the same for every release.

Checking a download. From the next release on, every file in a release, SHA256SUMS included, carries signed build provenance: a GitHub artifact attestation, signed keylessly through Sigstore, so there is no key of ours to lose. With the GitHub CLI:

gh attestation verify <file> --repo teapot-chess/Arkab
sha256sum --check --ignore-missing SHA256SUMS

The first line says this exact file was built by this repository's release workflow. SHA256SUMS is attested too, so the second line is as trustworthy as the first.

Linux and the Raspberry Pi, one line, as a service that starts with the machine (Debian 12, Ubuntu 22.04, Raspberry Pi OS "Bookworm" 64-bit, or newer; the runtime is inside):

curl -fsSL https://github.com/teapot-chess/Arkab/releases/latest/download/install.sh | sudo sh

(--local keeps the page to the box itself.) The program lives in /opt/arkab, the data in /var/lib/arkab, and neither an update nor /opt/arkab/uninstall.sh touches the data. Its log is journalctl -u arkab.

Windows: Windows says it does not know the program, as it does of any unsigned installer: "More info", then "Run anyway". The data is in %LOCALAPPDATA%\ArkabData, never in the install folder. macOS: signed and notarised; unzip and open Arkab.app, see docs/macos.md.

An installed copy looks for a newer release now and then (one small request to GitHub, switched off by a checkbox on the status page) and offers it; it installs nothing without a yes. How releases are cut and what each file is: docs/releasing.md.

The bridge#

Install it from the table above; there is nothing to compile and no mix to run. A hall organiser needs a downloaded file and a browser, and the installers are built so that is all it takes: the Windows installer and the Linux script both start the bridge for you, and on a Mac you open Arkab.app. The bridge then keeps running by itself, and the status page described below is how you talk to it.

Open http://localhost:4050 on the machine the bridge runs on (or, from another computer, through an SSH port forward: ssh -L 4050:localhost:4050 user@bridge). Paste or scan the join link that Alnasl shows: Halls, your hall, Bridges, Add a bridge (Alnasl's Setup wizard leads there too). The link is good for fifteen minutes and one bridge. That is the whole setup: the bridge fetches its own key, and the server decides which table each board belongs to. The page is open to the hall's network for looking, but from another computer it is a read-only view (servers, queue, ports, boards), marked as such: joining, removing a server, updating and the settings work from the bridge itself (the peer address of the connection decides, never a header; an SSH port forward counts as the bridge itself) or from a browser unlocked with the remote PIN: set one on the bridge itself under "This program" (4 characters at least, kept only as a salted PBKDF2 hash), and the read-only banner elsewhere offers "Enter PIN"; the right PIN gives that browser every button for 12 hours (also behind tailscale serve or a reverse proxy, which still count as remote), changing or removing the PIN locks them all again, and five wrong tries lock an address out for five minutes. The PIN can only be set from the bridge itself. The page is plain HTTP, so the PIN crosses the hall's network in clear: a lock for the hall, not security against the internet. A request that asks for a host the bridge does not answer to gets a 403. The page speaks English and Dutch, the choice kept in a cookie; /help says what the page's parts mean.

What the bridge promises:

• An event is on disk before it is sent anywhere.
• Each server has its own cursor, so a server that is down holds up nobody else.
• An event leaves the queue only when every server has acknowledged it.
• Commands from the servers (rescan, add or forget a port, send a board again, recording on or off) are applied in the order they arrived. Only a server joined as owner may make the bridge forget a board or a port.
• Remove, on either side, ends the link for both.

The link itself is described in docs/protocol.md.

For developers#

Everything below is for people working on Arkab or building on it. A hall never needs it, because the releases above already contain a built bridge.

Running from a checkout#

This starts the same bridge from source, which is what you want while changing it and nothing else:

mix deps.get
mix run --no-halt          # or: iex -S mix

The status page, the variables and the promises above all apply as they are. A checkout keeps its data in ./data unless ARKAB_DATA says otherwise.

Licence#

Apache-2.0. See LICENSE and NOTICE. Arkab is not affiliated with any board maker.