ShackLink for Home Assistant
Two custom Lovelace cards turn any HA dashboard — wall tablet, phone, kiosk, or HA Cloud Nabu Casa — into a live ham radio monitoring surface. Tune the rig, watch the SDR panadapter, decode all twelve digital modes, and listen in real time. Same unified port (8084) as the web client, so a Home Assistant accessible from outside your home is also a ham radio remote-control panel from outside your home. The cards are receive-only — transmit lives in the desktop client and mobile app.
💡 Two Cards, One Server
The package ships two independent custom cards. Drop either or both onto any dashboard.
shacklink-radio-card
Full radio control surface — frequency, mode, multi-rig switcher, memories, decoders, audio, antenna. The do-everything card, receive-only by design.
sdr-waterfall-card
Standalone SDR panadapter — live scope + scrolling waterfall with click-to-tune and a multi-SDR slot selector (pick which of the server’s SDR devices to view). Pin to a wall tablet next to the operating position, or run kiosk-style.
💡 Key Features
Control From Anywhere
If your HA is reachable through Nabu Casa, a Cloudflare Tunnel, or any other HTTPS path, your radio is reachable through the same path. One port (8084) on the server, optional HMAC auth.
Full Radio Control
Frequency tuning (touch / scroll / arrows), mode selection, multi-rig switching with custom names, VFO A/B, Split, RIT, XIT.
Audio Streaming
12 kHz PCM stream piped through the same WebSocket as control. The SDR card stays silent (visualization only); the radio card handles audio.
Receive-Only by Design
These cards are a monitoring and control surface: tune, listen, decode. They do not transmit — there is no compose box, PTT, or voice uplink on either card. For TX, use the desktop client, the mobile app, or the web client (text, voice and image TX). The rig is still fully tunable from the dashboard.
Antenna Switching
An antenna row on the radio card: pick the antenna for the operating rig, toggle Follow / Manual, and read the path confidence as a colour. ASSUMED is deliberately not an alert — it is the honest ceiling of a write-and-assume relay board, and colouring every one of those red would train you to ignore the colour. The device lamp is not drawn here: that is Antenna Studio’s business on the server, and two “is it working” indicators on one dashboard card is one too many. The row is hidden in the markup until the first state arrives, because this card is often a wall tablet and a control that flashes in is one you reach for and lose. Since 2026-08-27, a rig the server has given a separate receive antenna gets a second picker for it.
Station Power & Duplex, Read-Only
New 2026-08/09. On a station with switched loads the radio card shows what each load is doing, and while the station walks its power up or down it says so. It cannot switch them, deliberately: a wall tablet’s controls sit beside a volume slider, and the card has nowhere to show a numbered plan or a Stop. Use the desktop, web or mobile client for that. Likewise the card shows the station’s full-duplex state but does not arm it, and it carries no Winlink mail (no remote client does: Winlink is operated at the station).
All Twelve Digital Decoders
CW (40+ WPM), RTTY (auto-detect), PSK31 (9 BPSK / QPSK variants with FEC), FT8 and FT4 (colour-coded by SNR), SSTV (image canvas with progressive rendering, 19 modes), WEFAX (weather-fax, IOC 576/288 at 60/120 LPM), NAVTEX (SITOR-B maritime safety), APRS (AX.25 packet radio), WSPR (spots with distance and bearing), JS8 (directed messages, with traffic to your own callsign highlighted), and Olivia / Contestia. Full parity with the server as of card v1.11.0, which added FT4. WSPR and JS8 are bridged modes — they need WSJT-X or JS8Call running alongside the server; FT8/FT4 decode on the server itself unless the operator points them at WSJT-X.
SDR Panadapter
Real-time scope + waterfall on the dedicated card. Multi-SDR slot selector — when the server has several SDR devices active, pick which slot to view. Tap-to-tune and drag-to-pan with shift / ctrl modifiers, gain / contrast sliders, kiosk-friendly read-only mode for wall tablets. Since 2026-10 gain and contrast colour only the waterfall, as on the server; the spectrum trace is a straight dB plot.
Audio Spectrum Visualization
Live spectrum + waterfall on the radio card, separate from the SDR panadapter. Adjustable gain, ham-radio palette, click-to-tune for PSK31 in-passband signal selection.
48 Server-Synced Memories
Tap to recall, long-press to save. The card renders the server’s full bank by default; lower memory_count for a small wall tablet. The same slots appear on the desktop client, web client, and mobile app — one source of truth.
HMAC-SHA-256 Auth
Paste the server’s shared secret into the card YAML (auth_secret:). The card handles the challenge-response handshake transparently using the browser’s native crypto.
Theme Support
Dark, light, or auto (follows the HA / system theme). Both cards accept the same theme option.
Touch Friendly
Tablet / phone / kiosk-ready. Long-press for memory save, drag-pan on the SDR waterfall, tap-to-tune everywhere. Identical UI on every screen size.
The radio card and the SDR waterfall card side by side, dark theme, decoding CW on the Test Band
📋 Requirements
- Home Assistant 2021.12 or newer
- ShackLink Server running with the unified HTTP + WebSocket server on port 8084
- Network access from Home Assistant to the server (LAN, VPN, or reverse-proxy hostname)
- Modern browser with Web Audio API +
crypto.subtlesupport (any non-IE browser from 2017+)
🛠 Installation
Copy Files to Home Assistant
Copy the card files to your Home Assistant config/www folder
config/www/shacklink/
shacklink-radio-card.js
pcm-player-processor.js
You can copy the files via:
- File Editor add-on: Navigate to /config/www and create the omnirig folder
- Samba share: Access the config share and copy files
- SSH/SCP: Copy files via command line
Add as Lovelace Resource
Register the card as a custom resource in Home Assistant
- Go to Settings > Dashboards
- Click the three-dot menu (top right) and select Resources
- Click Add Resource
- Enter URL:
/local/shacklink/shacklink-radio-card.js - Select type: JavaScript Module
- Click Create
Restart Home Assistant
Restart Home Assistant or perform a hard refresh (Ctrl+Shift+R) in your browser
📝 Adding the Card
Using the UI Editor
- Edit your Lovelace dashboard
- Click Add Card
- Scroll down and select Manual
- Paste the YAML configuration (see below)
- Click Save
Basic Configuration
type: custom:shacklink-radio-card
server: 192.168.1.100
port: 8084
Full Configuration
type: custom:shacklink-radio-card
server: 192.168.1.100 # IP, hostname, or tunnel URL
port: 8084 # Unified HTTP + WebSocket port
auth_secret: "" # HMAC-SHA-256 hex secret from server's Station Settings → Security
# Required when server has Enable authentication on
# (and Require auth on LAN, if HA is on the same network)
title: Shack Radio
show_memories: true
show_morse: true
memory_count: 48
theme: auto
🔧 Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
server | string | required | IP address (or hostname / tunnel URL) of ShackLink Server |
port | number | 8084 | Unified HTTP + WebSocket port |
auth_secret | string | “” | HMAC-SHA-256 hex secret. Required when the server has Station Settings → Security → Enable authentication on (and Require auth on LAN if HA is on the same network). Leave blank when auth is off. |
title | string | “ShackLink Radio” | Card title displayed at top |
show_memories | boolean | true | Show memory buttons |
show_morse | boolean | true | Show Morse decoder section |
memory_count | number | 48 | Number of memory buttons. 48 is the server’s full bank; lower it for a small wall tablet |
theme | string | “dark” | Color theme: “dark”, “light”, or “auto” |
🎮 Using the Card
Frequency Tuning
- Tap any digit to select it (highlighted with glow)
- Tap arrows to adjust the selected digit
- Long-press arrows for continuous tuning
- Label shows current step size (e.g., “10 kHz”, “100 Hz”)
Mode and Rig Selection
- Tap Mode dropdown to change: USB, LSB, CW, AM, FM, etc.
- Tap Rig dropdown to switch between configured radios
Memory Buttons
- Tap a memory button to recall frequency (uses server’s recall mechanism)
- Long-press (800ms) to save current frequency and mode to that slot
- Right-click to clear a programmed slot
- Labels — custom labels assigned on the server or desktop client appear on buttons
- Active memory is highlighted when current frequency and mode match
- Memories are synced with the server — changes from any client appear on all others
Audio Streaming
- Tap Start Audio to begin streaming
- Audio plays through your browser/device speakers
- Tap Stop Audio to end streaming
⚠ Browser Audio Policy
Browsers require user interaction before playing audio. The first time you tap “Start Audio”, you may need to interact with the card first.
Digital Decoder
- Mode buttons – Switch between CW, RTTY, FT8, FT4, SSTV, FAX (WEFAX), PSK, NTX (NAVTEX), APRS, WSPR, JS8, and OLI (Olivia) decode modes. The choice is broadcast to every connected client — switching mode here switches the desktop / web / mobile clients too.
- Enable/Disable – Toggle decoding subscription. For WSPR and JS8 this is also what replays the server’s backlog (the last 100 spots / 50 directed messages), so you see history rather than waiting for the next decode.
- Decoded text – Shows characters as they are decoded (CW/RTTY/PSK31/NAVTEX/Olivia), one line per packet for APRS, and colour-coded records for FT8/WSPR/JS8
- SSTV / WEFAX display – Shows image canvas with progress bar (image modes)
- FT8 color coding – Messages are color-coded by SNR signal strength
- RDS & FM stereo – When receiving broadcast FM (WFM), the card shows an RDS data strip (station name / PI / radiotext) and an ST indicator that lights on FM stereo pilot lock
FT8 Color Coding
FT8 messages are displayed with colors indicating signal strength:
| SNR Range | Color | Meaning |
|---|---|---|
| 0 dB and above | Bright Green | Strong signal |
| -10 to -1 dB | White | Moderate signal |
| -15 to -11 dB | Orange | Weak signal |
| Below -15 dB | Red | Very weak signal |
SSTV Image Decoder
When SSTV mode is selected, the card displays a canvas for image reception:
- Image canvas – Shows the decoded image as it builds line by line
- Mode display – Shows the detected SSTV mode name
- Progress bar – Visual indicator of decode progress
- Auto-detect – Automatically identifies mode from VIS code
Supported modes (20 total): Robot 36 / 72 / 8BW / 24BW, Martin M1 / M2, Scottie S1 / S2 / DX, PD 90 / 120 / 160 / 180 / 240 / 290, Wraase SC2-120 / SC2-180, Pasokon P3 / P5 / P7
FT8 / FT4 Source
FT8/FT4 decodes displayed by the card come from a WSJT-X instance running on the ShackLink Server machine. The server listens on UDP port 2237 for WSJT-X decode reports and relays them to every connected client (including this Lovelace card). To see decodes, enable WSJT-X’s File → Settings → Reporting → UDP Server on port 2237.
🎨 Theme Options
Dark Theme
Optimized for dark Home Assistant themes. Uses dark backgrounds with light text and accent colors.
Light Theme
Bright backgrounds with dark text for well-lit environments.
Auto Theme
Automatically follows Home Assistant’s current theme. Switches between dark and light based on your HA settings or system preference.
🔧 Troubleshooting
Card Not Loading
- Verify the resource URL is correct:
/local/shacklink/shacklink-radio-card.js - Check that both .js files are in the www/omnirig folder
- Clear browser cache and hard refresh (Ctrl+Shift+R)
- Check browser console for errors (F12 > Console)
Cannot Connect to Server
- Verify server IP address in card configuration
- Ensure ShackLink Server is running
- Check that port 8084 is not blocked by firewall
- If the dot turns green briefly then red: the server’s authentication is on but the card’s
auth_secretis missing or wrong. Open Station Settings → Security on the server, copy the secret, paste it into the card YAML, and save. The card auto-reconnects.
No Audio
- Click inside the card first (browser autoplay policy)
- Check browser allows audio for your Home Assistant URL
- Ensure audio streaming is enabled on the server
🔒 Security Notes
WebSocket connection is unencrypted (ws://). Intended for local network use only. For remote access, use Home Assistant’s built-in remote access (Nabu Casa) or VPN.