Set up a display

A new display goes through three steps: you find it over Bluetooth, claim it for your account, and give it your Wi‑Fi network. After that it reaches LEDABLE's servers on its own, and every other command works over the internet from wherever you are.

Before you start, sign in, power the display on and keep it near your computer with Bluetooth on.

Claim a display

The quickest way claims the first free display the CLI finds and names it:

ledable ble link --first --name Kitchen

ble link --first scans, reads each display it finds, and claims the first one that belongs to no account. While it works it prints the pairing page's progress, one {"state": …} line at a time, and it ends with the new display's id and name:

{
  "device_id": "…",
  "nickname": "Kitchen"
}

Without --name, the display is named after the model it reports. The rules for a name are under devices rename. If the name is refused, the command fails but the display is claimed all the same: name it with devices rename.

Claiming also gives the display this computer's language and time zone, where it has none yet, so its clock and alarms are right from the start. You can change both in Settings and alarms.

Pick one display

With several displays in range, --first takes whichever free one it reads first, which need not be the one in front of you. List what is nearby and claim one by its id instead:

ledable ble scan
ledable ble pair <peripheral_id> --name Hall

ble scan listens for 8 seconds and prints a line for every advertisement it hears, so each display shows up many times:

{"kind":"found","deviceId":"…","name":"…","rssi":-58}

deviceId is this computer's handle for the display while it is nearby, not its id in your account. ble info reads a display's model and hardware id by that handle without claiming it; its is_linked is true when the display already belongs to an account, and left out when it is free.

ble pair claims exactly that display and ends the same way as ble link --first, with the id and the name.

Claim from the pairing page

ble link without --first runs the app's pairing page and leaves the choice to you. It prints the displays it finds, each with its peripheral_id, its name, and probe: pending while it is being read, ready when it can be claimed, failed when it could not be read, and excluded when it already belongs to an account (one of yours, or someone else's). Type a line to act:

pair <peripheral_id>

The page then shows the claim's progress and ends once the display is yours. It leaves the name as it is, so name the display with devices rename. The other lines it takes (probe, retry, cancel, rescan) are listed in its reference; Scripting explains how page commands work.

Choose the display a command acts on

Every command that acts on one display takes its id as --device (or -d). There is no default display: a command without it stops with Specify the device with --device <id>. The only exception is store preview, where the display is optional.

devices list prints your displays, each with its id and nickname. In a shell, keep the id you need in a variable, here with jq; the examples in these pages use $DEVICE:

DEVICE=$(ledable devices list | jq -r '.[0].id')

Put it on Wi‑Fi

With the display still nearby, hand it your network. The password is asked for without being shown.

ledable wifi join "Home Wi-Fi" --device "$DEVICE"

wifi join reaches the display over Bluetooth, sends the network and waits until the display has joined it. It works the same for a network that does not broadcast its name. Use --open for a network without a password, and --password-stdin to pipe the password in from a script.

A display already connected to another network may save the new one and stay where it is. The command then fails with a message such as Saved Home Wi-Fi. The device stays on Office until it restarts. Restart the display with devices reboot to move it.

These read or change the display's networks, also over Bluetooth:

• wifi scan: the networks the display can see.
• wifi status: the network it is on, and how the connection is doing.
• wifi known: the networks it has saved, without their passwords.
• wifi forget: forget a saved network. A display that is on that network stays on it until it restarts.

wifi setup runs the app's whole Wi‑Fi page, with the networks the display sees and knows, for when you want to look around before you choose.

Keep track of your displays

ledable devices list
ledable devices info --device "$DEVICE"
ledable devices rename "Living room" --device "$DEVICE"

• devices info prints one display's record, as devices list has it.
• devices rename changes its name.
• devices ping asks the display to answer and waits for it, so it shows whether the display is online. It prints the firmware version the display runs. A display that does not answer makes the command time out.
• devices presence watches the display: a line each time it goes online or offline, with its firmware version and what it plays, until the command's timeout.
• devices remove unlinks the display from your account. It does nothing without --yes.

ledable devices remove --device "$DEVICE" --yes

Next, put apps on your display.