WavelogQSOStats2Awtrix

WavelogQSOStats2Awtrix – Display your Wavelog QSO Stats on Awtrix Pixel Clocks

WavelogQSOStats2Awtrix is a Node.js application that fetches your Wavelog QSO statistics and displays them on an Awtrix LED clock. Configure station IDs, API key, modes, icons, and display duration via a responsive web interface. Automatically updates stats and cycles them on Awtrix for near-real-time log monitoring.

Screenshot WavelogQSOStats2Awtrix

✨ Features

Fetch Wavelog QSO statistics using the Wavelog WP API
Display Total QSOs, QSOs this year, FT8, FT4, FT8/FT4 combined, CW, SSB, FM, PSK, JS8, RTTY, and a configurable Digi total
Configurable modes and icons per mode
Responsive web interface for configuration and mode management
Test API connection and view all current QSO totals directly in the web interface
Upload amateur radio icons to the Awtrix device with a single click
Clear stale Awtrix apps with a single click
Auto-restart on crash, config is re-read on every cycle – no restart needed after changes
Built with Node.js and Express

https://youtu.be/kS_QYKCJ7ps

🖥️ Prerequisites

A running Wavelog instance with API access enabled
A Ulanzi TC001 Pixel Clock (Amazon Affiliate Link) flashed with Awtrix3 firmware
One of the following to run the app:
- Node.js v18 or newer, or
- Docker / Docker Compose, or
- Portainer (e.g. on a Synology NAS)

🚀 Installation

Option A – Node.js (classic)

Clone the repository

git clone https://github.com/HochdruckHummer/WavelogQSOStats2Awtrix.git
cd WavelogQSOStats2Awtrix

Install dependencies
```
npm install
```
Start the app
```
node WavelogQSOStats2Awtrix.js
```
Open the web interface in your browser and configure everything there:
```
http://localhost:3000
```

A config.json is created automatically on first start.

Option B – Docker Compose

No Node.js installation required.

Clone the repository

git clone https://github.com/HochdruckHummer/WavelogQSOStats2Awtrix.git
cd WavelogQSOStats2Awtrix

Start the container
```
docker compose up -d
```
Open the web interface:
```
http://localhost:3000
```

The config.json is stored on your host machine and survives container updates.

To update to the latest version later:

docker compose pull && docker compose up -d

Option C – Portainer / Synology NAS (no terminal needed)

Open Portainer → Stacks → Add Stack
Give it a name, e.g. wavelog-awtrix
Select Web editor and paste the following:

services:
  wavelog-awtrix:
    image: ghcr.io/hochdruckhummer/wavelogqsostats2awtrix:latest
    container_name: wavelog-awtrix
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./config.json:/app/config.json

Click Deploy the stack
Open the web interface on port 3000 of your NAS:
```
http://<your-nas-ip>:3000
```

To update: Portainer → Stacks → wavelog-awtrix → Pull and redeploy

⚙️ Configuration

Everything is configurable through the web interface. The settings are saved to config.json automatically. Here is an overview of the available fields:

Field	Description
`wavelogBaseUrl`	Base URL of your Wavelog instance, e.g. `https://wavelog.example.com`
`apiKey`	Your Wavelog API key (found under User Settings in Wavelog)
`stationIds`	Array of station IDs to query, e.g. `["01", "11"]`
`awtrixUrl`	Local IP address of your Awtrix clock, e.g. `192.168.1.50`
`fetchInterval`	How often Wavelog is queried and stats pushed to Awtrix (in seconds)
`displayItems`	List of modes: label, icon name, duration, and enabled/disabled

Example config.json:

{
  "wavelogBaseUrl": "https://wavelog.example.com",
  "apiKey": "your-api-key",
  "stationIds": ["01", "11"],
  "awtrixUrl": "192.168.1.50",
  "fetchInterval": 300,
  "displayItems": [
    { "key": "totalQso",     "text1": "Total",   "text2": "QSOs", "icon": "wavelog",  "duration": 10, "enabled": true  },
    { "key": "totalQsoYear", "text1": "Year",    "text2": "QSOs", "icon": "year",     "duration": 10, "enabled": true  },
    { "key": "FT8",          "text1": "FT8",     "text2": "QSOs", "icon": "ft8",      "duration": 10, "enabled": true  },
    { "key": "FT4",          "text1": "FT4",     "text2": "QSOs", "icon": "ft4",      "duration": 10, "enabled": true  },
    { "key": "ft8ft4",       "text1": "FT8/FT4", "text2": "QSOs", "icon": "ft8ft4",  "duration": 10, "enabled": false },
    { "key": "CW",           "text1": "CW",      "text2": "QSOs", "icon": "key",      "duration": 10, "enabled": true  },
    { "key": "SSB",          "text1": "SSB",     "text2": "QSOs", "icon": "ssbwave",  "duration": 10, "enabled": true  },
    { "key": "FM",           "text1": "FM",      "text2": "QSOs", "icon": "radioblue","duration": 10, "enabled": false },
    { "key": "PSK",          "text1": "PSK",     "text2": "QSOs", "icon": "psk31",    "duration": 10, "enabled": false },
    { "key": "JS8",          "text1": "JS8",     "text2": "QSOs", "icon": "js8",      "duration": 10, "enabled": false },
    { "key": "RTTY",         "text1": "RTTY",    "text2": "QSOs", "icon": "rtty",     "duration": 10, "enabled": false },
    { "key": "digi",         "text1": "Digi",    "text2": "QSOs", "icon": "digi",     "duration": 10, "enabled": false }
  ]
}

Note: The default config.json (with empty values) is included in the repository so Docker and Portainer users don’t need to create it manually. If you want to keep your personal configuration out of git, add config.json to your local .gitignore.

🖱️ Web Interface Features

Button	Function
Save Configuration	Saves all settings to `config.json`
Test Wavelog API	Fetches current stats and displays them in the mode table
Push to Awtrix Now	Immediately pushes current stats to the clock
Upload Icons to Awtrix	Uploads all icons from `AmateurRadioIcons/` to the clock’s `/ICONS/` folder
Clear all Awtrix Apps	Removes all `wavelog_*` apps from the clock, including stale ones from older versions

The mode table shows all configured modes with their labels, icon name, display duration, on/off toggle, and the live QSO count after a test or push. Rows can be dragged to reorder the display sequence on the clock.

🔁 How Updates Work

The app runs a continuous background loop:

Reads the current config (picks up any changes saved in the UI without a restart)
Fetches QSO statistics from Wavelog
Pushes each enabled mode as a named custom app to Awtrix
Waits for fetchInterval seconds, then repeats

Each Awtrix app has a lifetime of 2 × fetchInterval seconds. If the server stops, the displays disappear from the clock automatically after that time.

🎨 Icons

A set of amateur radio icons sized for Awtrix is included in the AmateurRadioIcons/ folder. Use the Upload Icons to Awtrix button in the web interface to transfer them to your clock in one step.

Icon names used in the default configuration:

Icon file	Used for
`wavelog`	Total QSOs
`year`	QSOs this year
`ft8`, `ft4`, `ft8ft4`	FT8, FT4, combined
`key`	CW
`ssbwave`	SSB
`radioblue`	FM
`psk31`	PSK
`js8`	JS8
`rtty`	RTTY
`digi`	Digi total

🛠️ Notes

Awtrix must be running firmware v0.96 or newer – see Awtrix3 on GitHub
The Wavelog API key needs at least read access; a read-only key is sufficient
Multiple station IDs are supported – stats are summed across all configured stations
The digi total is calculated as FT8 + FT4 + PSK + JS8 + RTTY

💛 Support the Development

Did this application help you? If you like, you can send me a beer via PayPal:

📜 License

This project is licensed under the MIT License.

📡 Author

Created by Daniel Beckemeier, DL8YDP – pull requests and contributions are welcome!

This site is open source. Improve this page.