[DXWaterfall] DX Waterfall for QSO page #2429

szporwolik · 2025-10-22T20:46:22Z

Background

This one falls into the "love it or hate it" category... 😉

As an amateur-amateur ham radio operator with a simple wire antenna setup and a single TRX at QTH, I decided to switch from desktop logging software to Wavelog. It works well for most of my needs, but I really miss having a convenient DXCluster view directly on the logging page to quickly check what's happening on the bands.

That’s where the proposed DX Waterfall feature comes in. 🎉

Overview

The DX Waterfall is a JavaScript object built on a canvas element.
It appears above the QSO logging section on the QSO page when operating in Live Logging mode.

Main Features

Uses Wavelog’s cluster model to pull DX spots.
A minor change was proposed to the DXClusterAPI to improve SOTA integration (a fallback is included if the change is not accepted).
Works with or without CAT control.
When CAT control is active, the radio frequency has priority — moving the dial updates the center marker (red line), and changing bands on the radio triggers a DXCluster update.
It can also work in reverse, allowing the waterfall to control the radio.
Mouse interaction: users can click anywhere on the waterfall to jump to a frequency or manually enter a value.
Keyboard navigation (similar to N1MM Logger+):
Users can control the waterfall using keyboard shortcuts to:
- Move between spots (Next/Previous).
- Jump to new Continents/DXCCs (DX Hunter).
- Adjust zoom levels.
  This allows for fast and efficient operation without relying on the mouse.
Navigation buttons:
- Next / Previous – cycle through spots on the band.
- DX Hunter – cycles through new Continents/DXCCs (if available).
Supports 5 zoom levels, covering everything from HF CW to VHF/UHF operation.
Quick switching of spot origins and mode filters.
The spot age and continent defaults are taken from existing Wavelog global options.
Displays the appropriate band plan section based on the selected continent (TODO: improve Wavelog's Bandedges).
When near a spot:
- The top bar shows spot info.
- Two buttons appear:
  - Tune to the exact spot frequency.
- Detected references (WWFF, IOTA, POTA, SOTA) are automatically filled, and spot details are fetched.

General Notes

While this feature introduces over 7500 lines of code, most of it resides in a single monolithic JS file managing the DXWaterfall object. Only minor changes were made to the QSO page and qso.js for integration.
I had to touch user settings, so per comment in the code I'm tagging @int2001 @phl0 .

The feature can be enabled per user in their settings and is disabled by default.

This is draft pull request, there is still lots to improve and especially to test - I will let you guys now when ready for the testing. If in the meantime anybody will be willing to check/test I'm open to the feedback.

TODO

Prior merge

Remove js inclusion cache avoidance in dxwaterfall.php component
Remove redundant tune to workaround related to Change Mode/QRG Order to FLRig WaveLogGate#83
Remove debug logs
Final code refactor
Final testing

int2001 · 2025-10-23T04:32:43Z

WOW!
Simply WOW!

i just read your description and pulled it on my dev. stunning.
this is really really nice.

i need to dig in a bit and have already a few questions (just testing it out for about 5mins, not more):

Great, you even thought about dis- and enabling. I like!!! This feature could be so hot, that one wants to "toggle" the view from QSO to QSO. 1st thought was/is: what about a "show/hide" element at QSO?
You're using the DXCluster-Endpoints WL provides. this is neat. so information about QSL-Status is included, right?
Clicking on a spot tunes the Radio to that spot, but call doesn't seem to be copied to QSO-Form. Perhaps i am using it wrong?
Bandplan: i saw you implemented a static JSON for the Edges. Qustion: Why not use those from the database instead?

i grabbed my 1st cup of coffee a few minutes ago and i am flashed about your PR. This is one of the best things i've seen during the last few months. Respect!

Let's try to make it production-ready together. however: really great work.

int2001 · 2025-10-23T05:17:53Z

Minor Issues i found so far:
Using a Mac here.

HotKey CTRL-Space doesn't seem to work (Chrome). Consider preparing the log, if one clicks on cluster?!
CTRL-Shift-Space doesn't work either here (QSY to Spot)
The "Spots fetched message" prevents the user from clicking on the buttons
Zooming/Moving in/out via Mouse? No real issue, just nice 2 have

This feature is really amazing. It even works together with the actual Bandlist at tools. i am flashed.

AndreasK79 · 2025-10-23T05:45:47Z

@szporwolik looking at the pictures, I gotta say WOW myself. This looks really nice, and once we iron out the bugs, I guess it can be merged.

I stumbled onto an error here, that seems to kill most functionality:

int2001 · 2025-10-23T06:27:06Z

application/views/interface_assets/footer.php

+	    // Add a small delay (500ms) before first poll to allow radio interface to initialize
+	    setTimeout(function() {
+	        updateFromCAT();
+	        // Then poll every 500ms


This is far too much. We know of instances running a thousand users and more. 3seconds was set for a reason.
i know: websockets would make it much more easier here. but we're on PHP and websockets are not really possible without a daemon (which can't be started/run on "el-cheapo-hosters")

suggestion, as a compromise:
set it back to 3000 (as default), and make it configurable at config.php (for small instances).
please no configuration in UI. Reason: some admin without deeper knowledge could set it accidently to 500ms (or even lower) and crash the whole instance

Yep, the thing is that the lower you go, the more responsive it get's when you are dialing radio.

What about new global setting for that - single, small instances hosted locally would probably go as low as 100ms, while admin's of the big ones could set it to 3 or event 5 secs. ?

100ms? that even more than the 500ms atm.
i'd vote for a default of 3000ms.

and instance-owner can adjust the value within config.php. put a warning to config.php that this may cause a DoS when set too aggressive.

i think with that compromise even "hold my beer while instance is burning"-owners could set it (on their own risk) to 100ms or less.
But default should be rock-solid and stable. 3000ms was and is tested even with huge instances in the wild.

[edit - thinking loud]
One could implement a Websocket-Server to WavelogGate and use that, instead of doing the roundtrip via old'n'busted PHP. but that's another huge refactor.

I will go with the config.php for now that is a good proposal and in fact it's easier than anything else. 😉

There is a locking mechanism, so timer ticks every value given (like 500ms), but actual request is being send only if the previous was has completed.

i just released WLGate V1.1.10 which supports websockets.
in combination with #2434 it reduces the load in a massive way. There are little delays when doing QSY, but that's because the Gate "debounces" every QSY/ModeChange to make sure frequency is settled.

Perfect! The websocket is the way to go, question about the back combability - having the current DX Waterfall to work with CAT and handling all async cases requires a lot of code. Implementing WebSocket in parallel will make everything even more complicated.

Proposal: I would drop support of the legacy code (CAT with MySQL in between) and make to code working only with the websockets.

What do you @int2001 think about ?

i built a ready 2 use codesnippet into footer.php and contesting.js. it supports both. see here:
on WebSocket: Realtime with pushes.
on Fallback/Roundtrip mySQL: 3000ms

once this is merged i could help you to refactor this beauty in a way it works with both.

Backwards-Compat is important. not everyone uses WLGate. Lots of people use own python/bash/$whatever scripts.

Got you, will check in the evening. Everything is possible, it's only just about additional lines of code. 😄

szporwolik · 2025-10-23T06:34:45Z

@szporwolik looking at the pictures, I gotta say WOW myself. This looks really nice, and once we iron out the bugs, I guess it can be merged.

I stumbled onto an error here, that seems to kill most functionality:

Will check, you are clearly using other PHP version than myself. Any chance to provide PHP version which you are on ?

int2001 · 2025-10-23T06:37:15Z

sure. i noticed the bug as well. but only once. my dev runs on 8.4.12. production on 8.3.24.
there are multiple versions used out there. it should work with every PHP version >=8.0.

Hint: @AndreasK79 found already out a possible root-cause: see here: https://github.com/wavelog/wavelog/pull/2429/files#diff-75a656aa0d26b2f4cb87a9a884fac77b4f8913708ad7abf984bdefe1d2b05324R227

the clubstation thing has to be the last parameter

AndreasK79 · 2025-10-23T06:37:49Z

@szporwolik PHP 8.2.4 here.

szporwolik · 2025-10-23T07:15:52Z

Great, you even thought about dis- and enabling. I like!!! This feature could be so hot, that one wants to "toggle" the view from QSO to QSO. 1st thought was/is: what about a "show/hide" element at QSO?

I was thinking about it as well, so enabling the feature would give you an option to then later turn of/off the feature.
This will complicate things a little as the main challenge is to handle all of those race conditions with async calls to CAT and DX cluster. Will think about.

You're using the DXCluster-Endpoints WL provides. this is neat. so information about QSL-Status is included, right?

Yes, this is not the most intuitive thing in the world, but the spot labels have meaning: red (not worked), orange (worked not confirmed), green (confirmed). The border goes for continent, label's background for DXCC and the small dot next to the callsign - the callsign. I was space limited and did not wanted to clutter the view to much.

When spot is active, the gold, silver and bronze are displayed as well.

Clicking on a spot tunes the Radio to that spot, but call doesn't seem to be copied to QSO-Form. Perhaps i am using it wrong?

This is correct behavior, you can click/scroll through the band and the nearest spot information will be displayed at the top bar. Then you can use those two small icons at the top to copy info to QSO Form or tune to exact frequency.
I you want to tune and copy, CTRL+Arrow keys is a way to go.

Bandplan: i saw you implemented a static JSON for the Edges. Qustion: Why not use those from the database instead?

This is one of the features which we miss, the Edges does some of the job - but I wanted to really mark the available band depending on the IARU region you are work for. So, now there is json in the future I would probably go with the full region support in the Wavelog backend with bandplans stored in the MySQL.

int2001 · 2025-10-23T07:33:59Z

Great, you even thought about dis- and enabling. I like!!! This feature could be so hot, that one wants to "toggle" the view from QSO to QSO. 1st thought was/is: what about a "show/hide" element at QSO?

I was thinking about it as well, so enabling the feature would give you an option to then later turn of/off the feature. This will complicate things a little as the main challenge is to handle all of those race conditions with async calls to CAT and DX cluster. Will think about.

Great. could make it much more useful

You're using the DXCluster-Endpoints WL provides. this is neat. so information about QSL-Status is included, right?

Yes, this is not the most intuitive thing in the world, but the spot labels have meaning: red (not worked), orange (worked not confirmed), green (confirmed). The border goes for continent, label's background for DXCC and the small dot next to the callsign - the callsign. I was space limited and did not wanted to clutter the view to much.

once understood (you even thought about tooltips - wow!) it is a nice approach.

When spot is active, the gold, silver and bronze are displayed as well.

Clicking on a spot tunes the Radio to that spot, but call doesn't seem to be copied to QSO-Form. Perhaps i am using it wrong?

This is correct behavior, you can click/scroll through the band and the nearest spot information will be displayed at the top bar. Then you can use those two small icons at the top to copy info to QSO Form or tune to exact frequency. I you want to tune and copy, CTRL+Arrow keys is a way to go.

Yes, sure. but it isn't intuitive. i had to search by myself how to copy the spot into the QSO-Form. i'd still vote for "copy it automatically to qso-form" when clicked. if you feel uncomfortable with it, what about a compromise: some switch at the waterfall, where one could say: "Take the clicked spot automatically to the form" when enabled (default). And when disabled he has to click on the icon or use the keyboard-shortcut? One main mantra of Wavelog is: keep it simple, reduce support for end-users.

Bandplan: i saw you implemented a static JSON for the Edges. Qustion: Why not use those from the database instead?

This is one of the features which we miss, the Edges does some of the job - but I wanted to really mark the available band depending on the IARU region you are work for. So, now there is json in the future I would probably go with the full region support in the Wavelog backend with bandplans stored in the MySQL.

tbh: we're trying to get rid of redundant Bandplan-Data during the last months. i strongly recommend to use the data which is in database. even if Regions are missing there. Way forward could be: add regions later to the existing DB it and use them. but for now i'd rather see it without the Region-Edges than implementing an extra source for the data

szporwolik · 2025-10-23T07:54:21Z

HotKey CTRL-Space doesn't seem to work (Chrome). Consider preparing the log, if one clicks on cluster?!

CTRL-Shift-Space doesn't work either here (QSY to Spot)

I'm not the Mac person, what would be the default key at Mac to modify role of the button ?

The "Spots fetched message" prevents the user from clicking on the buttons

This will be displayed when there is no spot nearby, I wanted to limit the place the feature takes, so this is kind of workaround.

Zooming/Moving in/out via Mouse? No real issue, just nice 2 have

Good idea! 😄

szporwolik · 2025-10-23T08:01:15Z

Added TODO list to the PR description to better track the suggestion/bugs.

int2001 · 2025-10-23T08:06:41Z

HotKey CTRL-Space doesn't seem to work (Chrome). Consider preparing the log, if one clicks on cluster?!

CTRL-Shift-Space doesn't work either here (QSY to Spot)

I'm not the Mac person, what would be the default key at Mac to modify role of the button ?

i can only tell what's working: all those Hotkeys which are based on "ALT" as modifier key. but: sometimes Firefox overrides keybindings with its own hotkeys. E.g.: Have a look at ALT+L binding.

The "Spots fetched message" prevents the user from clicking on the buttons

This will be displayed when there is no spot nearby, I wanted to limit the place the feature takes, so this is kind of workaround.

Understand. but without the "click and log"-Feature i already mentioned, there's no copying of spot/call possible. i noticed the message as well, when there's a spot. not intutive, as told. it could all be solved with that "click and log"-feature.

Zooming/Moving in/out via Mouse? No real issue, just nice 2 have

Good idea! 😄

szporwolik · 2025-10-23T08:14:29Z

I'm not the Mac person, what would be the default key at Mac to modify role of the button ?

i can only tell what's working: all those Hotkeys which are based on "ALT" as modifier key. but: sometimes Firefox overrides keybindings with its own hotkeys. E.g.: Have a look at ALT+L binding.

Thanks, will think what to do with it.

The "Spots fetched message" prevents the user from clicking on the buttons

This will be displayed when there is no spot nearby, I wanted to limit the place the feature takes, so this is kind of workaround.

Understand. but without the "click and log"-Feature i already mentioned, there's no copying of spot/call possible. i noticed the message as well, when there's a spot. not intutive, as told. it could all be solved with that "click and log"-feature.

Added to todo, I think I have an idea how to handle this.

szporwolik · 2025-10-23T21:36:49Z

Implemented initial changes after your feedback (thanks!):
@int2001 - please check the Mac support, I would need to visit my friends or family to test it - according to prof. GPT5 this shall work for you 😉; Cmd key is used as modifier now
@AndreasK79 - please check the PHP error, It was not smart of me to put non optional argument after optional - fixed, but I think I've also found the same bug already in the code - see #2435

Items changed:

CTRL-Space, CTRL-Shift-Space button presses (with Mac support?)
Mouse zoom-in / zoom-out
PHP error in User_mode.php
CAT puling rate into config.php, defaulted to 3000ms
Clicking near spot shall fill out the QSO form
Get rid of json file with IARU bandplan, use the build in Bandplan-Data
Rework/re-think display of the cluster data status
Turn On/Turn Off feature, even if feature is enabled in options

More to come... Any feedback is more then welcome!

AndreasK79 · 2025-10-24T06:14:02Z

PHP error in User_mode.php

The error is gone now, so great work! As for the other issue you raised, I'll look into it at a later point (probably this weekend).

One thing I noticed though. The labels are very small, and I need to increase the zoom level in the browser to read them.
I have a couple of suggestions:

Make font size configurable
Implement size control buttons some place in the waterfall gui
Have a mouseover with information about the spot (time of spot, spotter, needed for what etc)

Keep it up!

int2001 · 2025-10-28T14:24:05Z

From my point of view it works very good now.

szporwolik · 2025-10-29T21:49:31Z

Tested, verified, and refactored — this will still require extensive testing while in the dev branch.

I understand this review won’t be easy — it’s a massive one (sorry 🫨 ). My suggestion: focus mainly on the common file changes.
The main dxwaterfall.js file can be treated as an external library — no need to dive deep into it. I’ll handle any initial bugs that appear there.

Note:
To be completely honest, there are still some rare race conditions causing occasional strange UX behavior.
They don’t block the user, but may not look the nicest.

Tuning and band changes are asynchronous, with no instant confirmation from the radio that tuning succeeded.
Making this component “perfect” would require dropping polling support and moving fully to WebSockets, plus some work on WLGate to ensure proper confirmations are sent.

Considering all the great discussions above — and keeping backward compatibility and WLGate simplicity in mind — I decided to release it as it is. In my humble opinion, it’s more than “good enough”, though not “perfect”.

As we often say in Poland: Lepsze jest wrogiem gorszego / Le mieux est l’ennemi du bien / Das Bessere ist der Feind des Guten / Perfect is the enemy of good - so, let’s review, fix and go with it. 🙂

AndreasK79 · 2025-10-30T07:56:43Z

@szporwolik sorry for the merge conflict. Please fix :) It will be good to have this merged into dev, to avoid too many of these conflicts. I will try to test this tonight.

int2001

Minor things i noticed b4 approving it. nothing wild

application/views/qso/index.php

szporwolik · 2025-10-30T09:03:36Z

@AndreasK79 no problem an easy one!
@int2001 fixed

int2001

Yeah. Finally. Very Very good.

Since this is a really huge PR, we should at least wait for some other Core-Team-Members to approve b4 merging.

phl0

I just tested this PR in my dev environment (which does not have CAT control). Waterfall display works and all the logic with clicking callsigns, changing bands / modes works. Thumbs up from my side.

AndreasK79 · 2025-10-30T15:40:50Z

Tested this a bit, and it worked here. I say it's ready to merge into dev for further use and testing.

szporwolik · 2025-10-30T15:49:50Z

🎉 Thanks for support and - again - please excuse it's size.

DL2CC · 2025-12-12T08:56:34Z

On my screen the background is constantly kind of flickering, like noise in a real waterfall.
Lacking real signal information there is no sense in showing noise flickering, it is just straining the eyes.
Can there be an option to permanently turn this off and just show a black background when there is no real spectrum signal source?

szporwolik added 2 commits October 22, 2025 21:52

Initial commit of DX Waterfall for Wavelog

a0659bb

Fix for own sideband

9bda720

int2001 added frontend things which are affecting Frontend/UI new feature labels Oct 23, 2025

int2001 reviewed Oct 23, 2025

View reviewed changes

szporwolik added 9 commits October 23, 2025 19:29

Mac support

877c22c

Mac support - translation

d88f32e

Mouse support

d3f80c7

Fix for PHP error related to User add/edit functionality

a0434ee

CAT polling interval into config file

4e67b78

Click near spots detection

d34ae84

Bandplan used from database, cluster data moved to bottom menu

5d4bc31

Minor fixes

78dc64c

Initial load fix

b64f71a

szporwolik mentioned this pull request Oct 23, 2025

Incorrect function call in User controller #2435

Closed

Turn On and Turn Off feature

1a6fb76

szporwolik added 8 commits October 27, 2025 17:04

Visual improvment for choosen spot

4c31049

Logging cleanup

75b7797

Fixed band change (again)

09c87d6

Logs gone completly

6410843

Race condition handled

7b94245

Refactoring and error handling

9662707

Error handling

ca8a6e0

Minor fixes

4d2585f

szporwolik added 2 commits October 29, 2025 22:19

Final refactoring, fixes and improvments

a28793c

Merge branch 'dev' into dev_dx_widget

3ac8dd3

szporwolik marked this pull request as ready for review October 29, 2025 21:25

Fixed the welcome message.

0acbf2f

int2001 requested changes Oct 30, 2025

View reviewed changes

application/views/qso/index.php Outdated Show resolved Hide resolved

application/views/qso/index.php Outdated Show resolved Hide resolved

szporwolik added 2 commits October 30, 2025 09:51

Merge branch 'dev' into dev_dx_widget

b486390

Fixed typo, WLGate version and intends in translations

5cd7f53

int2001 approved these changes Oct 30, 2025

View reviewed changes

Added <hr> to seperate DX Waterfall at option list

33094e9

phl0 approved these changes Oct 30, 2025

View reviewed changes

AndreasK79 approved these changes Oct 30, 2025

View reviewed changes

AndreasK79 merged commit 4a8b4ea into wavelog:dev Oct 30, 2025

int2001 mentioned this pull request Nov 4, 2025

Don't clear on Bandchange! #2487

Closed

szporwolik deleted the dev_dx_widget branch November 7, 2025 22:11

int2001 mentioned this pull request Dec 12, 2025

On my screen the background is constantly kind of flickering, like noise in a real waterfall. #2675

Open

[DXWaterfall] DX Waterfall for QSO page #2429

[DXWaterfall] DX Waterfall for QSO page #2429

Uh oh!

Conversation

szporwolik commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

Overview

Main Features

General Notes

TODO

Uh oh!

int2001 commented Oct 23, 2025

Uh oh!

int2001 commented Oct 23, 2025

Uh oh!

AndreasK79 commented Oct 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

int2001 Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

szporwolik commented Oct 23, 2025

Uh oh!

int2001 commented Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AndreasK79 commented Oct 23, 2025

Uh oh!

szporwolik commented Oct 23, 2025

Uh oh!

int2001 commented Oct 23, 2025

Uh oh!

szporwolik commented Oct 23, 2025

Uh oh!

szporwolik commented Oct 23, 2025

Uh oh!

int2001 commented Oct 23, 2025

Uh oh!

szporwolik commented Oct 23, 2025

Uh oh!

szporwolik commented Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AndreasK79 commented Oct 24, 2025

Uh oh!

int2001 commented Oct 28, 2025

Uh oh!

szporwolik commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AndreasK79 commented Oct 30, 2025

Uh oh!

int2001 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

szporwolik commented Oct 30, 2025

Uh oh!

int2001 left a comment

Choose a reason for hiding this comment

szporwolik commented Oct 22, 2025 •

edited

Loading

int2001 Oct 23, 2025 •

edited

Loading

int2001 commented Oct 23, 2025 •

edited

Loading

szporwolik commented Oct 23, 2025 •

edited

Loading

szporwolik commented Oct 29, 2025 •

edited

Loading