From a folder
to a device.

Before you start

The example throughout is a gym's member check-in kiosk: tenant Northgate Fitness, project Check-in, a Raspberry Pi in a frame on the reception desk. Swap the names for yours; nothing else changes.

You need a workstation (Linux, macOS or Windows), a GitHub account, and a portal account (create one — the free plan needs no card). For steps 1 and 2 you need nothing else. For step 4 you need a Raspberry Pi 3 or 4 with a card, or an x86-64 machine with a USB stick.

The layout is fixed and small. app/ is the whole application — index.html at its root and every asset it uses — and it is the only thing that is ever sent to a device. Everything beside it stays yours, apart from an optional gui/ that the portal reads (below).

checkin/
├── app/
│   ├── index.html          ← the app's root; the player serves app/ and only app/
│   ├── app.js
│   ├── style.css
│   └── manifest.json       ← optional: datasets, settings, files the app needs at boot
├── arda.dev.json           ← developer settings, BESIDE app/, never packed
├── gui/                    ← optional: the app's own settings page, for the portal
├── seed/
│   └── members.json        ← optional: local records for developing without a server
├── data/  storage/  state/ ← the player's own; created on first run, keep out of git
└── .gitignore

The page is ordinary HTML. The one ArdaForm-specific thing is window.Arda, which the player puts in the page before your first line runs — no script tag, no import.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Northgate · check-in</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <header><b id="kiosk"></b> <span id="state"></span></header>
  <main>
    <h1>Scan your member code</h1>
    <button id="type">Type a number instead</button>
  </main>
  <script src="app.js"></script>
</body>
</html>

// Settings the operator typed in the portal — a frozen object, readable on line one.
// A setting nobody set is ABSENT, which is why ?? is right and || is wrong.
document.getElementById('kiosk').textContent = Arda.config.kiosk_name ?? 'Reception'

// Device state: registered? locked? what can a person do at this machine?
Arda.device().then(function (d) {
  document.getElementById('state').textContent = d.phase        // local · unregistered · initialising · ready
  document.body.classList.toggle('touch', d.can.touch && !d.can.keyboard)
})
Arda.on('device', function () { location.reload() })

// A synced dataset. Asking is subscribing; the first answer is usually {} — listen for 'sync'.
var members = {}
Arda.db.dataset('members').then(function (m) { members = m })
Arda.on('sync', function (name) {
  if (name === 'members') Arda.db.dataset(name).then(function (m) { members = m })
})

// A barcode reader is a keyboard wedge; the player says which reader it came from.
Arda.on('barcode', function (s) { checkIn(s.text) })

// No keyboard on the kiosk: ask for one. Resolves the string, or null on cancel.
document.getElementById('type').onclick = function () {
  Arda.keyboard({ layout: 'numeric', title: 'Membership number' }).then(function (n) {
    if (n !== null) checkIn(n)
  })
}

function checkIn(number) {
  var m = members[number]
  if (!m) return say('Not a member — see the desk')
  // Durable: written to the outbox on disk, delivered when the line is up, at least once.
  Arda.db.push('visits', { member: m.id, at: Date.now() }).then(function (r) {
    say('Welcome back, ' + m.name)       // r.seq is the outbox sequence number
  })
}

// Let an update in between check-ins, not during one.
Arda.on('updateStart', function (u) {
  if (!busy()) return                // say nothing: it applies in 5 s
  Arda.update.pause()                  // buys 60 s, up to 5 times
  whenIdle(function () { Arda.update.apply() })
})

// console.* is kept on the device and shipped to the portal when somebody switches capture on.
console.log('check-in ready')

app/manifest.json — what the app needs

The manifest is the developer's declaration of the datasets the app reads, the settings an operator may type, and the files it wants before it starts. The portal creates and updates these definitions when a release is packed; it never deletes one. Values stay the operator's.

{
  "datasets": [
    { "key": "members", "access": "ro", "api": "rw", "partition": "site", "needForBoot": true },
    { "key": "passes",  "access": "ro", "needForBoot": true },
    { "key": "visits",  "access": "rw", "retention": { "days": 400 }, "size": "50MB" }
  ],
  "settings": [
    { "key": "currency",   "caption": "Currency",        "type": "select", "options": ["GBP", "EUR"], "default": "GBP" },
    { "key": "pass_price", "caption": "Day pass price",  "type": "number", "unit": "£", "default": 8 },
    { "key": "kiosk_name", "caption": "Kiosk name",      "type": "text",   "perDevice": true }
  ],
  "files": { "needForBoot": ["banners"] }
}

Setting fields take key (lower-case; arda_ is reserved), caption, type (text memo number bool select color list image rows), default (seeds the value once, when the field is created), perDevice, help, options, unit. files.needForBoot is "*", a folder name or a list of folders under /storage/ that must be present before the app starts.

A rows setting is a list of small objects an operator adds to and removes from — a set of cameras, say. It takes min, max (up to 100), item (what one row is called) and fields of the plain types (text memo number bool select color), each of which may be required and secret (masked in the portal). Arda.config.cameras is then an array of objects in the operator's order. A top-level partition block makes the portal offer a device's data partition by name:

{
  "settings": [
    { "key": "cameras", "caption": "Cameras", "type": "rows", "perDevice": true,
      "min": 0, "max": 4, "item": "Camera",
      "fields": [
        { "key": "url", "caption": "Stream URL", "type": "text", "required": true, "secret": true },
        { "key": "fit", "caption": "Fit", "type": "select", "options": ["contain", "cover"] }
      ] }
  ],
  "partition": { "caption": "Site", "required": true,
    "options": [ { "value": "northgate-01", "caption": "Northgate" },
                 { "value": "northgate-02", "caption": "Riverside" } ] }
}

The portal uses the partition block only when the project's Setup has Data partition: use the app's list turned on. It is off by default, and then a device's partition is typed in.

gui/ — a settings page of the app's own

The portal's standard form shows every setting the manifest declares. An app can bring its own page for them instead: gui/settings/index.html and its files, in a gui/ folder beside app/. The portal then shows that page under Setup › App settings, and on a device's Setup tab for the per-device settings, with the standard form one click away. The settings are still the manifest's: the page proposes values, and nothing is saved until the operator presses Update. gui/ is never sent to a device, and a commit that changes only gui/ does not update the devices. Settings pages come with every package but Free.

checkin/
├── app/                    ← the app, packed and sent to devices as before
│   └── manifest.json       ← the settings, as before
└── gui/                    ← read by the portal, never sent to a device
    ├── icon.svg            ← optional (or icon.png)
    ├── gui.json            ← optional: {"settings": {"title": "Check-in screen", "height": 520}}
    └── settings/
        ├── index.html      ← the settings page
        └── page.css  app.js …

The page runs in a sandboxed frame with no network, no cookies and no local storage, and talks to the portal only through a small helper, ArdaGUI — its calls are on the API page. Files may be HTML, CSS, JS, JSON, images and fonts, up to 200 files and 5 MB; anything else and the portal shows the standard form and says why, without stopping the app's deploy. In developer mode the player prints settings page: http://127.0.0.1:<port>/__arda/gui/ and hosts the page the same way; its Apply puts the accepted values into the running app's Arda.config, in memory only (from ArdaPlayer v1.1.13).

arda.dev.json — your settings for this folder

Beside app/, not inside it. It is read only in developer mode, never packed, and a device refuses to start if it finds one — so it cannot reach a fleet by accident. An unknown key is refused, not ignored.

{
  "window":  "1280x800",
  "scale":   "75%",
  "bg":      "#000",
  "console": true,
  "watch":   true,
  "can":     { "touch": true, "keyboard": false, "mouse": false },
  "screens": [ { "name": "main", "primary": true }, { "name": "queue", "size": "800x480" } ],
  "partition": "northgate-01",
  "settings":  { "kiosk_name": "Desk (dev)" },
  "devices":   { "wifi": { "enabled": true, "networks": [{ "ssid": "Northgate staff", "key": "secret" }] } },
  "webhooks":  [{ "slug": "visits", "url": "http://localhost:8080/hook", "key": "dev" }],
  "device":  false
}

The file is plain JSON — no comments, or the player refuses it. What the keys do:

• window, scale, bg: the app's screen size, how big the window is drawn, and the colour before the app paints.
• console opens the inspector at start; watch reloads the page on every save.
• can is what the app is told this machine has; screens are the displays it pretends to have.
• partition cuts partitioned datasets to this one slice, locally; settings are your values for the app's settings.
• devices is a pretend Wi-Fi radio; webhooks are called from this machine, signed as ArdaForm would sign them.
• device: true enrols this folder as a real device and syncs for real.

Download the build for your workstation from the portal's Downloads page. The Linux desktop build opens a WebKit window of its own; the Windows and macOS builds open the app in your browser. Put it on your PATH.

portal.ardaform.netTap to enlarge

• Local by default. Nothing dials out. Every dataset in the manifest gets a store; what you push is read back at once; seed/<dataset>.json fills an empty store; Arda.config is built from the manifest's defaults plus the settings in your dev file.
• The device you develop on is not touched. Arda.system.shutdown() shows a notice instead; brightness and volume writes answer simulated: true; Wi-Fi uses the pretend radio from the dev file.
• Every app folder is its own device. Set "device": true and the folder enrols with an identity kept under state/, syncs for real, and appears in the portal like any other device — adopt it in step 5. Two folders are two devices.
• No screen? ardaplayer -headless . runs the same page with no DOM. Arda.headless is true before your first line; classic scripts only.
• Other screens. A screens list in the dev file opens each extra display as a window, and Arda.screen['queue'] is that window's document.

$ cd checkin
$ printf 'state/\ndata/\nstorage/\n' > .gitignore      # the player's own directories; arda.dev.json may stay, it is never packed
$ git init && git add -A && git commit -m "check-in kiosk"
$ gh repo create northgate-digital/checkin-kiosk --private --source . --push

1. Install the ArdaForm GitHub App on the account or organisation that owns the repository: github.com/apps/ardaform. Give it the repositories it may read. This is the one prerequisite the Connectors tab cannot do for you.
2. Every project starts with a branch called main, its default — new devices go on it. Add more under Code → Add branch; the branch dialog's Default branch switch moves the default.
3. Open Connectors → Connect GitHub. GitHub asks you to authorise ArdaForm once; if you already installed the App from its own page, press Connect anyway — the portal adopts the installation.
4. Add connection: project branch ← repository, folder, GitHub branch. After the first, add each connection with + — it passes through GitHub and comes back to this dialog. The folder is the directory whose index.html is the app's root — here app. One connection per project branch; two branches may read two repositories.

portal.ardaform.netTap to enlarge

portal.ardaform.netTap to enlarge

Now the branch has a source. The Code tab shows each branch's latest push, how many devices run the branch, and its apply policy — when a device that received an update may apply it:

portal.ardaform.netTap to enlarge

portal.ardaform.netTap to enlarge

$ xz -dc ardaplayer-rpi-arm64.img.xz | sudo dd of=/dev/sdX bs=4M status=progress conv=fsync
# /dev/sdX is the card (lsblk shows it). On macOS use Raspberry Pi Imager or balenaEtcher, which take the .img.xz directly.

Wi-Fi before the first boot

A Pi with a cable needs nothing. For Wi-Fi, either give it the network afterwards over Bluetooth (step 5), or put a file on the card's boot partition before the first boot — the player reads it at every start and restores the profile if it is ever lost:

ssid=Northgate staff
psk=the-password
# hidden=1 for a hidden network

On the USB installer the Wi-Fi step joins the stick itself to prove the password, then writes the same profile to the installed disk.

Your own SSH key

A published image carries no credentials. To be able to log in yourself, put your public key — one per line, several if you like — in arda-ssh.pub on the same boot partition (the Pi's card, the PC image, or the USB stick, which copies it to the disk it installs). The device adds it for its login user (pi on the Raspberry Pi image, arda on the PC) at every start. SSH from the network still stays closed until you open it from the portal (step 6); keys can also be installed from there.

What the first boot looks like

The ArdaForm logo is drawn about 1.3 seconds after power, from the initramfs. (The PC image and the stick also carry it as BMP files on the boot partition, for firmware that lets you pick a boot logo.) The player starts, finds the display, and shows its boot screen until the app is running. Three states you will see:

portal.ardaform.net/projects/12/devices

ArdaFormProjects / Check-inNorthgate Fitness · 121/137

Code Connectors Data Devices Install codes Webhooks API keys People Marketplace

DevicesProfilesAdoptBT↻

2 waiting

Raspberry Pi 3 Model B Rev 1.2on your network …7c19e4 player v1.1.16 just now

Adopt

arda-7pm2Bluetooth …a83f02 player v1.1.16 no network yet

Adopt

portal.ardaform.netTap to enlarge

Add device

DeviceRaspberry Pi 3 Model B Rev 1.2Hardware…7c19e4Runtimelinux/arm64 · player v1.1.16

Name

Studio door

Location

Studio 2, by the door

Branch

main

Data partition

Northgate

Which partition of the shared datasets this device reads.

CancelAdd device

portal.ardaform.netTap to enlarge

portal.ardaform.netTap to enlarge

Within half a minute of adoption the device fetches its branch's package, walks its datasets and files, and starts the app when the boot set is current. Profiles (Devices → Profiles) are Wi-Fi networks kept per project. The active one is handed to a device you adopt over Bluetooth; a running device gets another network on its Peripherals tab.

portal.ardaform.netTap to enlarge

portal.ardaform.netTap to enlarge

Above every tab sits the actions bar: Screenshot (a lossless picture of every attached screen), Approve (a device an install code held back), New password, Apply update, Reboot, Shut down and Remove.

portal.ardaform.net/projects/12/devices/40/view

ArdaFormProjects / Check-in / Devices / ReceptionNorthgate Fitness · 121/137

DevicePeripheralsSetupAlerts & logDevice viewSSHBluetooth↻

Device view Manual5s10s30s▭</>

Northgate Fitness · Reception online · 07:41

Scan your member codeHold your member QR to the scanner, or type your number.

Visits today 212

Spin · 08:00 4 places

Day pass £8.00

v1.4.1

Check inType numberDay passHelp

Connected · 1280 × 800 · 61 KB

Arda.db.status()

07:41:02 > Arda.db.status() 07:41:02 < {ready: true, datasets: {members: {synced: true, boot: true, records: 1842}, visits: {synced: true, records: 12930}}, files: {done: 20, total: 20, complete: true}} 07:41:19 app welcome: member 10231 · visit queued seq 4471 07:41:19 app outbox: 1 delivered

portal.ardaform.netTap to enlarge

portal.ardaform.net/projects/12/devices/40/shell

ArdaFormProjects / Check-in / Devices / ReceptionNorthgate Fitness · 121/137

DevicePeripheralsSetupAlerts & logDevice viewSSHBluetooth↻

SSH External SSH · open · 28 min left>_+

root@arda-9k2f:/# uptime  07:52:10 up 6 days, 4:11, load average: 0.21 root@arda-9k2f:/# journalctl -u ardaplayer -n 2 -o cat INFO webhook called slug=visits status=200 ok=true ms=143 INFO ssh key installed user=sam sudo=false expires=8 Oct root@arda-9k2f:/#  

Add an ssh user

Install your public key on this device. A user that does not exist yet is created without a password: it can watch the app in the device view and read the logs, and is not root unless you tick passwordless sudo.

User

sam

Public key

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK… sam@laptop

Valid for

1 day

Passwordless sudo (root)

CancelInstall

The data behind the app

The project's Data tab holds the datasets the manifest declared, the records in them, and the files the devices sync. Records reach a dataset from devices (Arda.db.push), from the portal, or from the HTTP API with a key minted under API keys — api.ardaform.net/v1, described by /v1/openapi.json. A partitioned dataset sends each device only the records whose partition field matches the device's partition.

portal.ardaform.netTap to enlarge

portal.ardaform.netTap to enlarge

portal.ardaform.netTap to enlarge

portal.ardaform.netTap to enlarge

portal.ardaform.netTap to enlarge

Webhooks — calling your own servers

The project's Webhooks tab — or /v1/webhooks in the HTTP API — defines endpoints of yours the app may call: a name, a slug, the URL, the method (POST, GET or PUT), an optional key, Verify, and enabled. The app names one by its slug; ArdaForm makes the request from its own servers, so the key never reaches a device and your firewall has one source to allow. Every delivery is logged on the tab with its status, time and device. Leave the URL empty and nothing is sent: the calls are only recorded (the app gets ok: true, status 202), each opens in Deliveries as its JSON, and your own systems can read them back through /v1/webhooks/{slug}/deliveries.

// Resolves {id, ok, status, ms, body, error}. ok is a 2xx; a 4xx or 5xx is an answer.
// It rejects only when nobody was asked: offline, unknown or disabled webhook, the limit.
Arda.webhook.call('visits', { member: m.id, kiosk: Arda.config.kiosk_name })
  .then(function (r) { if (!r.ok) console.warn('CRM answered', r.status) })
  .catch(function (e) { console.warn(e.message) })

If you write the server at the other end: it receives JSON — {id, webhook, project, device: {uid, name}, at, verify, data} (a GET webhook gets the same fields as query parameters, device as its uid and data JSON-encoded) — with X-Arda-Delivery, X-Arda-Webhook, X-Arda-Project and X-Arda-Timestamp. With a key it also gets Authorization: Bearer <key> and X-Arda-Signature: sha256= the hex HMAC-SHA256 of timestamp + "." + body; with Verify on, a one-time X-Arda-Verify token it can confirm with POST /v1/webhooks/verify. ArdaForm waits 10 seconds, follows no redirects, refuses private addresses, and hands the app the first 4 KiB of the answer; data may be up to 64 KiB. Whether webhooks are included, how many an account may define and how many calls a minute it may make come with the package. On your desk, the webhooks list in arda.dev.json stands in for them.

portal.ardaform.netTap to enlarge

portal.ardaform.netTap to enlarge

1. 01
   The head movesGitHub tells ArdaForm; the Connectors row shows the new commit, "ahead of what is deployed".
2. 02
   Packed once, sent to each deviceA signed instruction per device, with the sha256 and the key. A device that is offline gets it when it returns.
3. 03
   Fetched, verified, stagedThe device checks the bytes against the signed sha, proves the container opens, writes it beside the running app with a READY marker last. The old app keeps running.
4. 04
   The app picks the momentupdateStart fires. Say nothing and it applies in 5 seconds; pause() buys 60 seconds, up to five times; apply() does it now. After five pauses it stays staged until the next restart or an operator's Apply update.
5. 05
   Everything at onceDevices in one shop apply within tens of milliseconds of each other. The portal shows what each runs and what it holds staged.

The player updates itself

A new ArdaPlayer release is a signed instruction too, naming the build for the device's OS and architecture with its sha256. The device downloads it, runs it once to prove it starts, and arms it for the next restart — the running process is untouched until then. If the new build cannot stay up for ninety seconds three starts in a row, the device puts the previous one back by itself. A release marked important goes through the same five-second negotiation with your app instead of waiting for a restart.

• Remove on the device screen issues a wipe. The device acknowledges it, flushes what its outbox still holds for up to thirty seconds, erases its identity, its app and its data, and restarts as a fresh device showing a code. The row stays as "decommissioned". A device that is switched off takes the wipe whenever it next connects — the wipe waits for it for a year — and so does a stolen one.
• ardaplayer -unbind at the device does the same from its own side. It asks for the device password — eight characters the portal shows on the Device tab and can reissue with New password; the device holds only a hash of it. The control plane forgets first and the device erases itself second, so an interruption is safe to repeat. The row fades as a "ghost" over seven days.
• Forget completely deletes the row — its alerts, log and settings — for a device that is gone: a card you reflashed, hardware you retired. The wipe does not go with the row. ArdaForm keeps it apart for a year, so if that card is ever switched on again it is wiped the moment it connects (within a minute, if it is connected when you press it) and shows a new code. A device with a wipe already waiting offers Delete anyway instead, with the same guarantee.

Deleting a whole project does the same for every device in it: each one stops being able to fetch code or files at once, is wiped the next time it connects, and has to be claimed again in person, from the code on its own screen. A device removed in any of these ways no longer goes on running what it had.

When something looks wrong

app folder     myapp/app/index.html (+assets), myapp/app/manifest.json (datasets, settings, files.needForBoot)
dev file       myapp/arda.dev.json beside app/ — never packed; keys: window scale bg console watch can screens device settings partition devices webhooks
settings page  myapp/gui/settings/index.html beside app/ — never sent to a device; shown in Setup › App settings and a device's Setup tab (paid plans); helper <script src="/_arda/gui.js"> (ArdaGUI)
run locally    ardaplayer -dev myapp/      (local; "device": true enrols the folder as a device)
headless       ardaplayer -headless myapp/ (no DOM; Arda.headless === true)
api            window.Arda — device() config db.dataset() db.push() db.status() on() update.* keyboard() screens.* screen[name] audio.* camera.* webhook.call() system.* wifi.* printers.* serial.*
deploy         GitHub App https://github.com/apps/ardaform → portal project → Code (branch) → Connectors (branch ← repo, folder, ref) → git push
images         portal Downloads: ardaplayer-rpi-arm64.img.xz · ardaplayer-linux-amd64.img.xz · ardaplayer-linux-amd64-installer.img.xz
wifi on a Pi   /boot/firmware/arda-wifi.conf: ssid=… psk=… [hidden=1]
adopt          activation code (Devices › Add device) · Devices › Adopt (same network) · Bluetooth (Chrome/Edge, arda-xxxx) · Install codes (XXXX-XXXX-XXXX, optional approval)
apply policy   per branch: asap (default) · timed HH:MM–HH:MM device time · manual; app: Arda.on('updateStart'), Arda.update.pause()/apply()
retire         portal Remove (wipe) · Forget completely (row deleted, wipe kept a year) · deleting the project (every device wiped on its next connection) · ardaplayer -unbind (device password)