Before You Begin

What you’ll need on hand

A display

Any HDMI monitor or TV, 1080p or 4K. Helioclock ships set to 1080p by default for the smoothest, most responsive experience out of the box, even on a 4K screen. You can switch to native 4K anytime in Settings if you prefer the sharper image and don’t mind a bit less snappiness.

A keyboard and mouse

USB works everywhere. Wireless is a nice touch if you’d rather not have cables running to the display, but it’s entirely optional.

A network connection

Wired Ethernet or WiFi, either works fine. If you’re going wireless, the first-run wizard includes a built-in scan that lists nearby networks so you can find and select yours instead of typing it from memory, then you’ll enter your WiFi password once.

SKU1 · Preloaded SD Card

For your Raspberry Pi 4 or 5

1. Insert the card

Insert the preloaded microSD card into your Pi 4 or Pi 5. A Pi 4 needs 4GB of RAM or more to run Helioclock comfortably; Pi 1, 2, and 3 are not supported and will not boot the card.

2. Connect everything, then power on

Connect your HDMI monitor, USB mouse, and keyboard first, then apply power. The Pi boots straight into Helioclock, no login screen, no desktop to navigate through first. It typically takes under a minute from power-on to the first-run screen, so give it a moment before assuming something’s wrong.

A few things worth doing before you power on for the first time: use a case with a fan and heatsink, since Helioclock runs the CPU hard and an uncooled Pi can show strange or inconsistent boot behavior. Use an adequate power supply too (5V/3A for Pi 4, 5V/5A or the official Pi 5 supply), since a weak or damaged cable can cause flaky boots that look like a bad card. If you’re on a Pi 5, connect your display to the HDMI port closest to the USB-C power port. The other port gives no output at boot.

3. Follow the on-screen setup

The first-run wizard walks you through the license agreement, your network connection, and your timezone, in that order. If you’re connecting over WiFi, use the built-in scan to find and select your network rather than typing it in by hand. Once you confirm the last screen, Helioclock loads the world map and starts pulling live data immediately.

4. Also: browse from any device on your network

Once it’s running, open a browser on your phone, laptop, or tablet and go to helioclock.local, no IP address to look up. You’ll see the same live display, and can change settings from there too. Keep in mind that any settings you change from a remote browser stay local to that device, they don’t get pushed to the main display or to any other device browsing in.

Before you ever power this off, see How to Shut Down Safely to avoid corrupting the card.

SKU2 · Live USB Stick

For your existing PC (Intel/AMD)

1. Insert the USB stick, then power on

Insert the USB stick into a high-speed USB port, usually colored blue or red on the outside of your PC, then connect your monitor, keyboard, and mouse if they aren’t already. 4GB of RAM minimum is required on the host PC. Power on or restart. Give it under a minute to reach the boot menu and start loading, PCs vary a bit more than a Pi in exact timing. If the only port available is an older USB 2.0 port (usually black instead of blue or red), boot can take a couple of minutes instead of under one, that’s normal for that port type and won’t affect how Helioclock performs once it’s running.

2. Enter your BIOS/boot menu

As the PC starts up, press the key that opens your boot menu or BIOS, usually F2, Esc, F10, or DEL, depending on the manufacturer. Select the USB drive as the first boot device.

3. Save and exit

Choose Save and Exit. The PC boots straight into Helioclock from the USB stick, nothing is installed to your hard drive, and your existing OS is untouched. The same setup wizard runs: license agreement, network connection, timezone. If you’re connecting over WiFi, use the built-in scan to find and select your network rather than typing it in by hand.

4. Also: browse from any device on your network

Just like the SD card version, open helioclock.local in a browser on any other device on the same network to view or configure it remotely. Settings changed from a remote browser stay local to that device, they don’t get pushed to the main display or to any other device browsing in.

Before you ever power this off, see How to Shut Down Safely to avoid corrupting the stick.

SKU3 · Turnkey Appliance

Helioclock Turnkey Appliance

1. Connect your display, keyboard, and mouse

The turnkey appliance connects just like any other computer. Keyboard, mouse, and display needed, same as you’d hook up to a desktop PC: any HDMI monitor or TV, plus a USB keyboard and mouse.

2. Power on

The appliance boots straight into Helioclock. There’s no OS to configure and nothing to install first. Under a minute from power-on to the first-run screen is typical.

3. Follow the on-screen setup

Same wizard as the other SKUs: license agreement, network connection, timezone. If you’re connecting over WiFi, use the built-in scan to find and select your network rather than typing it in by hand. Once it’s done, you’re looking at your live world map.

Before you ever power this off, see How to Shut Down Safely.

All SKUs

Setting your callsign, QTH, and “you are here”

Open Settings

Once you’re past the first-run wizard, open ⚙ SETTINGS from the bottom bar. This is where your personal details live, separate from the one-time setup screens.

Fill in your profile

Under PROFILE, enter your callsign and QTH (grid square or coordinates). This is what personalizes panels like greyline, sunrise/sunset, and DX distance calculations to your actual location, rather than a generic default.

Confirm “You Are Here”

The YOU ARE HERE marker on the world map is set from the same PROFILE information. Double check it lands on the right spot, especially if you entered a grid square rather than exact coordinates, since grid squares cover an area rather than a single point.

All SKUs

Showing your callsign and a Morse CQ at startup

Display your callsign on screen

Once your callsign is entered under SETTINGS > PROFILE, it displays automatically on screen alongside your QTH, no separate toggle needed. If you haven’t entered it yet, this is where to do it.

Play CQ in Morse at startup

Open SETTINGS and turn on MORSE ALERT TONE. With it enabled, Helioclock sends CQ in Morse code once at boot, and switches your alert tone from the default chime to a Morse-keyed tone for the rest of the time it’s running. Turn it back off anytime to return to the standard chime.

All SKUs

Setting up your free API keys

Why you need your own keys

A handful of panels pull from data providers that require a free API key tied to an individual registration, rather than a shared key we could bake into every unit. These providers rate-limit by key: a set number of requests per minute or per day. If every Helioclock in the field shared one key baked into the software, every customer would be pulling from that same limit simultaneously, and the whole network of units would get throttled or blocked within minutes of the first Hamfest sale. Each key is also free and takes a couple of minutes to register, so there’s no cost to you, just a one-time signup.

Wildfire Hotspots panel — NASA FIRMS

Register a free key at firms.modaps.eosdis.nasa.gov/api/map_key/. Enter it under SETTINGS > DATA SOURCES. Until a key is entered, the Wildfire Hotspots layer won’t display any data.

Air Quality panel — AirNow and WAQI

Two keys cover this panel, both free: AirNow for US, Canada, and Mexico locations, registered at docs.airnowapi.org/account/request/ (the key arrives by email rather than showing on the page), and WAQI as the fallback for everywhere else, registered at aqicn.org/data-platform/token. Enter both under SETTINGS > DATA SOURCES. Helioclock automatically uses AirNow inside North America and WAQI outside it. Until at least one key is entered, the panel shows SET API KEY instead of data.

Markets panel — Financial Modeling Prep

Register a free key at site.financialmodelingprep.com/register. Enter it under SETTINGS > DATA SOURCES to unlock stock ticker quotes and the DOW/NASDAQ index row. The crypto watchlist works immediately with no key required.

Everything else needs nothing from you

These four keys are the only ones you’ll ever need to touch. Every other panel, radar, GOES cloud cover, space weather, DX Cluster, tides, and the rest, pulls from sources that don’t require any registration at all.

All SKUs

Shutting down safely

Why this matters

Never disconnect power or remove the storage media without shutting down first. This applies whether you’re running from the MicroSD card on a Raspberry Pi or the Live USB Stick on a PC: cutting power abruptly, or removing the stick while Helioclock is running, can corrupt the storage and make it unbootable.

How to power off

The control bar is hidden by default. Show it by clicking the double-chevron tab at the bottom of the screen, or by pressing Alt+B on a connected keyboard. Once the bar is open, tap ⏻ POWER, then choose SHUT DOWN. Wait for the screen to go completely dark before doing anything further, that’s your confirmation the system has actually finished shutting down.

Then, and only then

MicroSD card: unplug power from the Pi. Live USB Stick: power off the computer, then remove the stick.

All SKUs

Getting help after setup

The built-in help screen

Press ALT+H at any time once the world map is displayed, or open it from the menu bar at the bottom of the screen. It covers every panel, every keyboard shortcut, and every setting, written in plain language and kept current with every release.

Checking that the unit itself is healthy

A built-in Health Report shows disk usage, memory, CPU temperature, uptime, and NTP time-sync status at a glance, no terminal required. Handy any time you want to confirm everything’s running smoothly, not just that the screen is displaying.

Software updates

Updates are delivered automatically in the background. There’s nothing to click, download, or run yourself, no SSH, no package manager, no git pull. If a fix or new feature ships, your unit picks it up the same way it arrived.

Still stuck?

Check the full documentation, ask in The Greyline community forum, or get in touch directly.

Ready to see it running? Browse full documentation