Kelly Page

What this gives you

A Raspberry Pi is a small, cheap computer about the size of a deck of cards. Set up this way, it sits beside your radio with the radio's data lead plugged into it, and stays switched on. You then use Kelly Page from any PC, laptop or tablet in the house: just open a bookmark. Your PC no longer needs the lead, or a COM port.

The Pi runs headless: no screen, keyboard or mouse. You set it up once from your PC over your home network, by typing a handful of commands that this guide gives you word for word. Allow about an hour the first time, most of it waiting.

For everything about using Kelly itself (its pages, statuses, texts, maps and how the radio must be programmed), see the operator's manual.

this is a command

What you need

Which Raspberry Pi

The Pi has very little to do. Kelly's screens, maps and buttons all run in the browser on your PC; the Pi only passes the radio's data across the network and hands out Kelly's files. Measured on a Raspberry Pi 4, that job uses about 27 MB of memory and well under 1% of the processor. So any recent Pi feels just as quick in use; a slower one only takes a few seconds longer to load Kelly when you first open the bookmark.

If you want the Pi to keep your station on air with your PC off, the Pi also runs its own copy of Kelly in a hidden web browser. That's a bigger job: about 190 MB of memory and a few percent of the processor on a Pi 4, and a 200 MB download once. Choose a Pi with at least 1 GB of memory for it.

Prepare the SD card

The Pi's "hard drive" is its SD card. You put the operating system on it with Raspberry Pi's free Imager program. The system to choose is Raspberry Pi OS Lite: Debian Linux made for the Pi, with no desktop, which is exactly what a headless Pi needs. Imager also lets you set the Pi's name, your login and the network before the card ever goes in the Pi.

1. On your PC, go to raspberrypi.com/software, download Raspberry Pi Imager for Windows, and install it. Plug the SD card into the PC.
2. Start Imager. On the Device page, choose your Pi model and press Next.
3. On the Operating system page, choose Raspberry Pi OS (other), then Raspberry Pi OS Lite (64-bit). (The 32-bit one only for the old models in the table above.) Don't choose plain "Raspberry Pi OS": that's the desktop version, much bigger and slower.
4. On the Storage page, pick your SD card. Check the size matches your card, so you don't wipe a USB stick or backup drive by mistake.
5. Hostname: type kelly. This is the name you'll reach the Pi by, as kelly.local. (Two Pis on one network need different names, for example kelly2.)
6. Localisation: your capital city or time zone (for example Brisbane, Australia/Brisbane) and keyboard layout us.
7. User: a username and password. Your callsign in small letters makes a good username, for example vk4abc. Pick a password you'll remember and write both down: you need them in a few minutes.
8. Wi-Fi: if the Pi will use Wi-Fi, enter your network name (SSID) and password exactly, capitals included, and the country AU.

   Don't skip the Wi-Fi page

   Even if you're using a network cable, do not press Skip here. Leave the boxes empty and press Next. The very next page is the one that switches on SSH, the remote login this whole guide depends on, and skipping the Wi-Fi page can carry you straight past it. A headless Pi without SSH can't be reached at all; the only cure is to write the card again.

9. Remote access (SSH): turn Enable SSH on, and choose Use password authentication. Press Next.
10. Raspberry Pi Connect: leave it off. Kelly doesn't use it. Press Next.
11. Check the summary, then press Write and confirm. Windows may ask for permission; say yes. Writing and checking takes 5 to 15 minutes. When Imager says it's finished, take the card out.

First power-up

1. Put the SD card into the slot under the Pi (the label faces away from the board).
2. If you're using a cable, plug the Pi into your router. Leave the radio lead out for now.
3. Plug in the power supply. There's no power switch: the red light comes on and the green one flickers.
4. Wait five minutes. The first start sets itself up and may restart once on its own. Don't unplug it during this time.

Log in to the Pi

You control the Pi by typing commands into a window on your PC, using SSH (Secure Shell). Windows 10 and 11 have it built in.

1. On the PC, click Start, type cmd and open Command Prompt. (On a Mac, open Terminal; the commands are the same.)
2. Type this, using your own username from the Imager step, and press Enter:

   ssh vk4abc@kelly.local

3. The first time, it asks "Are you sure you want to continue connecting (yes/no/[fingerprint])?". Type yes and press Enter. That's normal: your PC is meeting the Pi for the first time.
4. Type your Pi password and press Enter. Nothing appears on screen while you type the password, not even dots. That's normal too; just type it and press Enter.
5. You're in when the line ends with something like vk4abc@kelly:~ $. Commands you type in this window now run on the Pi. Leave this window open.

Copy Kelly to the Pi

Kelly Page comes as a zip file, for example KellyPage-0.4.16-2026-10-12-expires-2026-11-28.zip. Leave it zipped; the Pi unpacks it.

1. Open a second Command Prompt window (Start, cmd). This one stays on your PC.
2. Go to the folder holding the zip. If it's in Downloads:

   cd Downloads

3. Type the start of the copy command, scp Kelly, then press Tab: Windows fills in the rest of the zip's name. Then add a space and vk4abc@kelly.local: so the whole line looks like this:

   scp KellyPage-0.4.16-2026-10-12-expires-2026-11-28.zip vk4abc@kelly.local:

   The colon at the very end matters: without it, Windows makes a copy on your own PC instead of sending it to the Pi.
4. Type your Pi password (invisible again) and press Enter. It shows 100% when the copy is done. You can close this window.

Install Kelly

Back in the first window, the one logged in to the Pi:

1. Unpack the zip:

   python3 -m zipfile -e KellyPage-*.zip ~

   This makes a folder called Kelly Page. It prints nothing when it works.
2. Run Kelly's installer. Type it exactly, with the quote marks (the folder name has a space in it):

   sudo bash ~/"Kelly Page/bridge/install-pi.sh"

   Using a MOXA UPort lead? Add --moxa at the end, after a space, to install its firmware too.
3. It asks for your password (sudo means "as the administrator"). It then takes two to five minutes, mostly downloading, and finishes with == Done == and your Kelly address, like this:

   http://kelly.local:8025/?connect=ip&token=k7m2qx9wa4

   The letters after token= are your Pi's own password for Kelly. Copy the whole address into a note; you can show it again any time with cat ~/kelly-address.txt.
4. Log out of the Pi:

   exit

That's the last command you need. From now on the Pi starts Kelly by itself every time the radio lead is plugged in, including after a power cut.

Connect the radio and open Kelly

1. Plug the radio's data lead into one of the Pi's USB sockets and into the radio, and switch the radio on.
2. On your PC, open Chrome or Edge and paste your Kelly address into the address bar (the http://kelly.local:8025/?connect=ip&token=… one).
3. Kelly opens and connects on its own. Within a few seconds the Dashboard shows your radio's model and serial number.
4. Press Ctrl+D to bookmark it. That bookmark is how you open Kelly from now on.
5. If you're new to Kelly, carry on with First start in the operator's manual (choosing Shack mode, your callsign, and so on).

On your phone

The installer finishes with a QR code. Point your phone's camera at it (the phone on the same WiFi as the Pi) and open the link: that's Kelly on your phone, token and all, nothing to type. To show the code again, log in to the Pi and run sudo python3 /opt/kelly-page/bridge/kelly_bridge.py --connect-qr. If the address starts with https and the Pi uses its own certificate, the phone warns once: tap Advanced › Proceed.

You can open Kelly from more than one PC or tablet at once; they all see the same radio. Each browser keeps its own settings, so use Admin › Save config and Load config to copy your set-up between them.

Stay on air with your PC off

Kelly does its work in your web browser. When your PC goes to sleep or you close the tab, nobody is minding the radio: messages for you go unanswered, and after about ten minutes the P25X network marks your station as gone. The Pi can fix that by running its own copy of Kelly, all the time, in a hidden web browser.

How it works

• While nobody has Kelly open, the Pi's Kelly is connected to the radio. It parks the radio for the network, answers messages, and checks in, exactly as your own Kelly would.
• When you open your bookmark, the Pi's Kelly steps aside in the same second and switches itself off, and your Kelly takes over, picking up the Pi's log of everything it heard (see Good to know below). Two copies of Kelly on one radio would both answer the network and send everything twice, so the Pi makes sure that never happens.
• About ten seconds after you close Kelly (or your PC goes to sleep), the Pi's Kelly starts up again, reconnects and parks the radio. The network sees your station come back within half a minute.
• After a power cut it all starts again by itself once the Pi is back up and the radio lead is plugged in.

Setting it up

The Pi's Kelly needs your station's settings (your callsign, your personality such as Shack, your status and preset labels). You give it a copy of them as a configuration file, saved from your own Kelly.

1. Open Kelly from your bookmark and set it up the way you want: Admin › Personality (Shack for most shack radios), your callsign, your labels.
2. Press Admin › Save config (.xml). A file such as kelly-config-VK4ABC-2026-10-13.xml lands in your Downloads folder.
3. Copy it to the Pi under the name kelly-config.xml, from a Command Prompt on your PC. Type the start of your file's name and press Tab to fill in the rest:

   cd Downloads
   scp kelly-config-VK4ABC-2026-10-13.xml vk4abc@kelly.local:kelly-config.xml

   The name after the colon matters: the Pi only looks for kelly-config.xml.
4. Log in to the Pi and run the installer again, exactly as in Install Kelly:

   sudo bash ~/"Kelly Page/bridge/install-pi.sh"

   (If you tidied away the Kelly Page folder, unpack the zip again first.) The first time, it downloads a hidden web browser for the Pi, about 200 MB, so allow a few minutes. It finishes with Kelly also runs on the Pi itself, so your radio stays on the network with your PC off.
5. Close Kelly on your PC and wait half a minute. The Pi's Kelly is now on the radio.

What it sets up for you

• A hidden web browser on the Pi (Chromium, the same browser engine as Chrome), with Kelly open in it.
• A small helper, kelly-keeper, that starts and stops that browser and hands the radio over between it and you. It starts with the Pi and stops whenever the radio lead is unplugged.
• Your settings, loaded into the Pi's Kelly, with a few changes for running on its own: no sounds (the Pi has no speaker), no animations, and no automatic Kelly updates over the air. You update the Pi by running the installer with a new version, as in Moving to a new version; the Pi's Kelly comes back with the new version and your settings.

Changing its settings later

Changed something in your own Kelly that the Pi's should have too, such as a new label? Save the config again and copy it over the old one with the same scp command. The Pi notices the new file within a few seconds and loads it; there's no need to run the installer.

Good to know

• What the Pi heard comes to you. The Pi's Kelly keeps a log of the texts, calls, status changes, bulletins, storm alerts, pictures and positions that arrive while it's in charge. When you open your bookmark, your Kelly picks that log up from the Pi within a few seconds and adds it to your own history, with one message such as While you were away: 3 texts, 12 calls, and the badges show what's new. Nothing is added twice, and nothing goes out over the air to fetch it. If you clear your logs (Admin › Clear logs), the Pi's older log isn't added back.
• Sounds play only on your PC, while your own Kelly is open.
• Opening Kelly on a second PC or a tablet works as before. The Pi's Kelly stays switched off until the last of them is closed.

Checking on it

Log in to the Pi (ssh vk4abc@kelly.local) and type:

journalctl -u kelly-keeper -n 15 --no-pager

The last few lines tell the story, for example:

[keeper] Kelly started in headless Chromium (pid 90415)
[keeper] applied kelly-config.xml (callsign VK4AZ, home transparent) and reloaded Kelly
[keeper] someone opened Kelly from another computer -- stepping aside
[keeper] Kelly started in headless Chromium (pid 90754)

Kelly started as the last line means the Pi's Kelly is on the radio; stepping aside means someone has Kelly open. bridge or radio not up -- waiting means the radio lead isn't plugged in, or the bridge isn't running.

Turning it off

To go back to Kelly only running while your PC has it open, remove the configuration file and run the installer again:

rm ~/kelly-config.xml
sudo bash ~/"Kelly Page/bridge/install-pi.sh"

Or switch it off for now without changing anything else, and back on later:

sudo systemctl disable --now kelly-keeper

sudo systemctl enable --now kelly-keeper

Bluetooth LE presence (optional)

The Pi's own Bluetooth can watch for small Bluetooth LE devices around your home: a keyring beacon, a thermometer, a tag on the go-box. Kelly's BLE Presence page then sends a P25 text to your radio when one arrives, leaves, hasn't been seen for a while, or reads out of range. For example: VK4ABC arrived Home 17:42, or Go-box battery low 15%.

Switching it on

Run the installer once more with --ble added. It installs the Bluetooth software, switches Bluetooth on, and finishes with a short test that should hear a few devices:

sudo bash ~/"Kelly Page/bridge/install-pi.sh" --ble

   self-test on hci0:
   hci0: OK, 42.4 C
   heard 93 adverts from 8 devices in 6 s

The choice is remembered: later upgrades keep Bluetooth on without --ble.

Register a beacon

1. Open Kelly, go to Telemetry › BLE Presence, and press Start scanning.
2. Hold your beacon near the Pi. It appears in Nearby, with what Kelly can read from it (an iBeacon number, a temperature, a battery level). Press Register, give it a name and your callsign, and save it.
3. Go to Rules, press New rule, choose what should happen (arrives, leaves, not seen for some hours, battery low, temperature above a value…) and which radio IDs should be told. The preview shows the exact text and its length. Use Dry run for the first day: Kelly logs what it would have sent and transmits nothing.

Phones and watches can't be used. They change their Bluetooth address every few minutes on purpose, for privacy, so Kelly can't recognise them from one hour to the next. Use a dedicated beacon instead: any iBeacon or Eddystone tag, a Xiaomi LYWSD03MMC thermometer with the free ATC or pvvx firmware, or a BTHome sensor. Kelly only counts other people's phones by maker. It never shows, stores or sends their addresses.

Pets

A Bluetooth tag on a collar lets Kelly text you when your pet slips out. Register the tag with type 🐾 Pet; Kelly then waits until the pet has been out of range for 10 minutes before saying so, since pets wander to the edge of the yard and back. On the Devices tab, 🐾 Pet alerts sets up two rules in one go: an alarm when it leaves, repeated every 15 minutes until it's back or you reply ACK, and a text when it comes home. To look for it, 🔍 Find clicks faster as you get closer.

Which tags work: cheap "iTag" key-finder tags, BLE collar beacons, and any tag that sends an iBeacon or Eddystone ID. Kelly shows them in Nearby, ready to register. Some Tile models keep a fixed address and work; others don't. Apple AirTags, Samsung SmartTags and Google Find My trackers can't be used: they change their address every few minutes on purpose, as protection against stalking, so only their owner's phone can follow them. Kelly recognises and labels them, but never tracks them.

With your PC off

The rules run in whichever Kelly is open: yours while you use it, otherwise the Pi's own Kelly (see Stay on air with your PC off). After setting up your devices and rules, save your config again and copy it to the Pi (the same scp command), so the Pi's Kelly has them too. The Pi's Kelly doesn't play sounds.

How often it transmits

Each alert is a normal P25 text from your radio, unencrypted and under your own radio ID, sent one at a time. By default alarms can go every 20 s, arrivals and departures every 2 minutes (several waiting for the same radio are joined into one text), routine readings every 10 minutes, and no more than 20 non-alarm alerts an hour. If you start Kelly while a device is already home, it doesn't announce it. Reply ACK from your radio to stop an alert that repeats.

A USB Bluetooth dongle

The Pi's built-in Bluetooth shares its radio and aerial with Wi-Fi, so it misses some packets when Wi-Fi is busy, and it doesn't reach far. A USB dongle hears better, especially with a cable to a better spot:

• TP-Link UB5A (Realtek chip): plug it in. If dmesg | grep -i rtl mentions missing firmware, install it with sudo apt install firmware-realtek and replug.
• Nordic nRF52840 USB dongle: flash it once with Zephyr's hci_usb sample so it works as an ordinary Bluetooth adapter. On a PC with the Zephyr tools: west build -b nrf52840dongle/nrf52840 zephyr/samples/bluetooth/hci_usb, press the dongle's side button (its red light pulses), then nrfutil nrf5sdk-tools pkg generate --hw-version 52 --sd-req 0x00 --application build/zephyr/zephyr.hex --application-version 1 hci_usb.zip and nrfutil nrf5sdk-tools dfu usb-serial -pkg hci_usb.zip -p COM7 (its port).

The dongle shows up as hci1 (the built-in one is hci0); ls /sys/class/bluetooth lists them. Scan with the dongle only, or both:

sudo bash ~/"Kelly Page/bridge/install-pi.sh" --ble hci1

To switch the built-in Bluetooth off altogether, add dtoverlay=disable-bt to /boot/firmware/config.txt and reboot. The dongle then becomes hci0, so run the installer with --ble hci0.

Scanners in other places

Another Pi (a Pi Zero 2 W is plenty) in the shed, at the clubhouse or at a repeater site can scan too, and send what it hears to your Kelly over the network: your home network, Tailscale or 4G. It never uses the radio. Its devices count as being in its own zone, so a rule can say moved Home › Shed.

1. In Kelly: BLE Presence › Adapters & nodes › Add a remote node. Give it an id (shed) and a zone (Shed). Kelly shows a token once, together with the line to run on the new Pi.
2. Set the new Pi up as in the first sections of this guide, copy Kelly to it, and run that line, for example:

   sudo bash ~/"Kelly Page/bridge/install-pi.sh" --ble-node --server kelly.local:8025 --node shed --token the-token

3. The node appears as up in Adapters & nodes. It only forwards your registered devices. To register a beacon that lives at that site, press Discover 10 min next to the node and it appears in Nearby.

If the node's link drops, the node keeps what it hears and sends it later, in order, so a slow link never makes a device "leave". If a node is off the air for longer than you set in Settings, Kelly can text you about it.

Keeping it safe. A node is only accepted with its own token. The Pi keeps a scrambled copy of the token, so it can't be read back. Kelly checks everything a node sends and limits how much it may send. A node can't make your radio transmit anything: only your own rules can, within the limits above. New token or ✕ cuts a node off at once. Over the internet, keep the link inside Tailscale, which encrypts it. Why not just share the USB dongle over the network (USB/IP)? It needs a steady, fast link and drops out with the slightest hiccup, while a node keeps working through outages and sends only a few hundred bytes a minute.

If something's wrong

Everyday use

• Leave the Pi on. It uses about as much power as a phone charger.
• Unplugging the radio lead stops Kelly's link to the radio; plugging it back in starts it again within a few seconds. Reload the Kelly page (F5) to reconnect.
• To switch the Pi off, for example to move it, shut it down first so the SD card isn't damaged. Log in (ssh vk4abc@kelly.local) and type:

  sudo poweroff

  Wait until the green light stops flashing, then unplug it. A power cut is usually harmless, but don't make a habit of pulling the plug.
• To restart it instead: sudo reboot.

Moving to a new version

Each version of Kelly works until a set date; this one until the end of 30 April 2027. After that the Pi still shows the page, but won't connect to the radio until you install a newer version. Your Kelly address and bookmark stay the same.

1. In Kelly, Admin › Save config (.xml), to be safe.
2. Log in to the Pi and clear away the old copy you unpacked (Kelly keeps running from its installed copy meanwhile):

   rm -rf ~/"Kelly Page" ~/KellyPage-*.zip

   Leave this window open.
3. Copy the new zip to the Pi exactly as in Copy Kelly to the Pi.
4. Back in the Pi window, unpack it and run the installer again, the same two commands as the first time:

   python3 -m zipfile -e KellyPage-*.zip ~

   sudo bash ~/"Kelly Page/bridge/install-pi.sh"

5. Open your bookmark and press Ctrl+F5 once, so the browser loads the new files.

Troubleshooting

Asking someone for help? Log in to the Pi and run this, then send them what it prints:

systemctl status kelly-bridge --no-pager; ls -l /dev/kelly-radio; lsusb

Keeping it safe

• Anyone who opens your Kelly address can key your radio, so keep the address (with its token) to yourself, the same as a password.
• Never set your router to forward port 8025 to the internet. Kelly is for your home network. For use away from home, ask about a private network such as Tailscale, which the P25X project already uses.
• Use a proper password for the Pi itself, not raspberry or password.
• Everything Kelly sends goes out under your licence; see On air in the operator's manual.