Alnasl

Alnasl reads the electronic boards in a playing hall, works out the moves from where the pieces stand, and sends the moves and the clock times to the results site while the games are played. This chapter says what it is, the two ways to run it, how to install it, and what to check before the first round.

What Alnasl does#

Who plays whom, Alnasl learns from OpenPairings. What each board saw goes back there, beside the pairing. The moves and the clocks go to the results site (OpenResults), where spectators follow them. Alnasl keeps everything itself first, so a hall without internet loses nothing: what could not be sent goes out, in order, when the connection is back.

You work with it in a browser, on the box itself or on your laptop in the hall. The places are in the rail on the left, in groups:

At the top of the rail: the box's name (on the server, "server") and, when you have more than one hall, the hall picker. At its foot: the account button, with your language, the colour theme and Sign out.

On a phone the rail becomes a bar along the top (the name, the hall picker and the account button) and the places a bar along the bottom: Live, Boards, Results and More, which holds the rest. Nothing is missing on a phone; it is one tap further.

Notices (the results site cannot be reached, a board plays outside its tournament, a question about tables, a new version) stand above the page, at most two at a time. The rest wait behind "1 more notice"; press it to see them.

A page or a list with nothing in it yet says so in a sentence, and says what brings something: a connection for the tournaments, a bridge for a hall's boards, a board for a round. Where there is one obvious next step, a button takes you there.

Setup is in sections, each with its own address and a list beside it (a drop-down on a phone): the Setup wizard (see below), Tournaments (a line each; open one for its details, its halls and tables and its automatic start; the ones with boards in this hall come first, the finished and the not started are behind a toggle), Connections (codes and account links, a line each with a menu for Test, Retry and Remove, and "+ Add"), Results and Lichess, This box (on the server This server), Access and Updates (a box only) and Advanced (the tracker, for admins). A section your edition or role cannot use is not drawn.

The setup wizard#

The first section of Setup is the Setup wizard. Until every step of it is done, Setup opens there; after that it opens on Tournaments, and the wizard stays in the list for the next change. It is per hall: on the server, open it in each hall with the hall picker at the top.

It starts with a few questions: what the hall looks like (one hall with one tournament, one hall with several tournaments, or several halls or rooms), how many Arkab bridges (on the server always; on a box only for rooms beyond its own), roughly how many boards, and what else you want: results for spectators, a Lichess broadcast, a print station, a hall announcer, and on a box phones and laptops behind a PIN. One cable chain takes up to twelve boards; more boards is a second chain on a port of its own.

Then it lists the steps for exactly that hall, in order, with one button each that goes where the step is done. The first step not done is the current one. Each tick comes from what Alnasl really has, not from anybody pressing Next:

The connect code comes from OpenPairings: open the tournament, then Settings, Live boards, and press "New code". A step you cannot act on with your role keeps its tick, loses its button and says who can. Only the hall's owner answers the questions; "Change the answers" asks them again and the ticks carry on.

Two ways to run it#

It is the same program either way. What differs is where it runs and what is plugged into it.

A box in the hall. A small computer (a Raspberry Pi, a mini PC, the arbiter's laptop) with the boards plugged into it by USB or serial cable. It reads them itself. This is the normal case, and it works with no internet at all.

The hosted server. The same program runs on a server, at alnasl.zerotwo.cloud. A server has no boards of its own: it has no ports to read. It takes bridges instead: Arkab, a small program in a hall that read the boards there and send them on over the internet (see Bridges). The pages are the ones you know: the round, the games, the corrections. The difference is that every page asks who you are, always, and accounts come by invitation only (see Accounts, halls and roles).

The server leaves out what only a box can do, instead of greying it out: adding boards and the list of serial ports on the Boards page, simulator boards, the Updates panel and starting with Windows, the PIN and the hall network, and the box's name. Setup, This server, says which edition you are looking at, under "This copy of Alnasl"; the sections Access and Updates are not there at all.

Installing#

Windows. Alnasl-Setup.exe installs for you alone, without an administrator, and puts "Alnasl" in the Start menu. The program is not signed, so the first time Windows says "Windows protected your PC": choose "More info", then "Run anyway". The small Alnasl window is the program: closing it stops Alnasl, and while it is stopped the boards are not read. There is also a zip that installs nothing: unzip it and start Alnasl.exe.

Linux and the Raspberry Pi. One line installs Alnasl as a service that starts with the box (64-bit; Debian 12, Ubuntu 22.04, Raspberry Pi OS Bookworm, or newer):

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

Mac. Download alnasl-macos-aarch64.zip for a Mac with an Apple chip (M1 and later; there is no build for Intel Macs), open it, and drag Alnasl into Applications. Apple has not signed it yet, so the first time macOS refuses to open it: in System Settings, Privacy & Security, click "Open Anyway" beside the message about Alnasl. Quitting Alnasl (Cmd-Q) asks first, because while it is stopped the boards are not read.

Then open the site in a browser: on the box itself at http://localhost:4040; from a laptop on the hall's network, the box's address with the same port (Boards and Setup, Access, show it, with a QR code for a phone, once other machines are let in).

Updating#

The box asks once every half hour whether a newer version is out, and says so at the top of the page. It downloads nothing until you say yes under Setup, Updates, where it also says how big the download is. It will not restart while a game is being played unless you insist: the moves played during the restart are not read. "Later" asks again tomorrow; "Don't ask again" stops the looking, and Setup switches it back on.

What changed in each version is on the same page, under the button, so nobody has to leave Alnasl to read it. The notes that came with your version are there at once; the newer ones are fetched from GitHub when you open the section, and kept for six hours so the hall's internet is not asked twice. Your version is marked, newer ones are marked and open, older ones are folded. Offline, you get the notes that came with your version and a calm remark that anything newer needs the internet. A small "View on GitHub" link remains for anyone who wants the original, though a hall kiosk should not need it.

Where your data is#

Not in the program's folder. Windows: %LOCALAPPDATA%\AlnaslData (type that in Explorer's address bar). Linux, installed: /var/lib/alnasl. Mac: ~/Library/Application Support/AlnaslData. It holds the database, the PGN of every game, the raw recordings, and the keys and codes you pasted. Updating and uninstalling leave it alone; installing again finds it. To move to another computer, copy that folder while Alnasl is stopped.

Setup, This box, "This copy of Alnasl", says the version, how this copy was started and where its data folder is. A second copy started another way on the same computer has a data folder of its own: its own boards, numbers and tournaments.

Before the round#

The same short list every time. Each step has a page that says in words what is wrong, if something is.

1. Setup, Connections: paste the connect code from OpenPairings (and, under Tournaments, say which tables play in which tournament) (see OpenPairings, OpenResults and Lichess). Press "Test connection".
2. Boards: every board should show a state other than "No signal", and its picture should match the pieces on it.
3. Boards: the column "Start position" must say "Right" for every board. If not, it names the pieces and squares. A king and queen swapped is the usual one.
4. A board with a clock is only "Right" when its clock is too: to the right of the board, the lever up on White's side so that White's time runs first.
5. Boards: give each board its table number (see Boards and ports).
6. Boards: "Ready for round N?" must say Ready. If not, it lists what is wrong, board by board.
7. Live: every tile should read "Waiting for start".

Language and colours#

The site is in English or Dutch. The language is yours, not the box's: choose it in the account menu (the button at the foot of the rail, top right on a phone). With an account, the choice is kept with the account and follows you to any browser; without accounts, it is kept in that browser. Either way nobody else's language changes, and this manual follows yours.

Whoever has chosen nothing reads Alnasl's default language. An admin sets it under Setup, "This box" ("This server"), Default language.

The colours come in the same themes as OpenResults: Paper, Night, Board, Slate and High contrast, and Match device, which follows the phone or computer. Choose in the account menu, under Colour theme; it is the only place. The choice is kept in that browser only. High contrast is the one for a projector at the back of the hall.

More themes can be added as theme packs: one folder per theme, in the folder themes inside the data folder. On the next page load they are offered after the built-in ones. A pack Alnasl will not load is listed in grey, with the reason.

The tour#

The first time you open the site (with accounts: the first time you sign in), a small card in the corner offers a tour. It walks through the pages in the order a hall is set up and played: the places, the setup wizard, bridges, connecting OpenPairings, tournaments and their tables, the boards and their numbers, the check before the round, Live, Results, and fair play. Each step points at the thing it is about, says what it is for in a sentence or two, and links to the section of this manual that says the rest. A step on another page takes you there.

You only see the steps for what your role lets you use: a viewer is not shown the setup wizard or the bridges, and fair play is shown to the hall's owner only. Where a page has nothing to point at yet (no boards, no tournaments), the step says what will appear there.

Use Next and Back (or the arrow keys), or Skip the tour; Escape closes it too. Press Not now on the card and it is not offered again. To take it later, open the account menu (the button at the foot of the rail, top right on a phone) and choose Take the tour. With accounts, whether you took it is kept with your account; on a box without accounts it is kept for the box.

Words used here#

The screens and this manual use one word for each thing:

A game that "stays in Alnasl" is kept here and not sent anywhere; the log says "Arbiter in Alnasl" when a person changed a game through these pages.