Skip to content
Guru-RFPublic

About

VFO via WiFi or USB-C with touchscreen

Resources

Stars

6 stars

Watchers

1 watching

Forks

Latest commit

 

History

165 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

VFO-Knob

Buy me a coffee

A hardware VFO knob and control head for AetherSDR, FlexRadio, the Icom IC-705, IC-7610, IC-9700 and IC-R8600, and the Xiegu X6100 and X6200 on OpenX6X00, built on the Waveshare ESP32-S3-Knob-Touch-LCD-1.8. Tune, change step, key the transmitter, watch the S-meter — over a USB-C cable or over WiFi. And, with firmware of their own, SVXConnect, a talkgroup knob for SvxLink reflectors, a dial for UberSDR web receivers, one for KiwiSDR and Web-888 receivers, and a telephone.

Receiving: the S-meter rises to S9+20 and falls back while its readout follows and the 100 Hz digit ticks; S-units marked around the blue 66 mm body   Transmitting: SWR on the left, forward power on the right with the mic level inside it, both readouts following their bars; red PTT slab

Receiving, and transmitting, to scale in the 66 mm body. The readouts follow the bars. The meter blocks are notched in the background colour, so the separators appear where the bar has reached and vanish where it has not. Everything outside the body is annotation: the knob draws the S-meter scale as bare ticks, so its values are marked around the rim.

It speaks TCI v2.0 over a WebSocket, which is AetherSDR's own control protocol — so the knob is not polling, it is told. Tune at the desktop and the knob follows; turn the knob and the desktop moves.

With an IC-705 it talks to the radio itself, over WiFi, in Icom's network protocol — the one RS-BA1 and wfview use — with receive and transmit audio, so knob and radio are a complete station with no computer in between. Its face wears Icom's colours, so which radio a knob is for shows at a glance. The same firmware runs the IC-7610, with MAIN or SUB and its antennas on a swipe, the IC-9700 on 2 m, 70 cm and 23 cm, and the IC-R8600 receiver, 10 kHz to 3 GHz, which it never keys. It also knows the IC-7300MK2, the IC-7760 and the IC-905 (up to 10 GHz), from wfview's descriptions, not yet tried on the radios themselves. The guide says how to set each radio up for it: see the Icom guide.

With an Elecraft K4, a beta tried on one radio, it is a remote client of the radio over WiFi, as K4remote is, with audio both ways. See Elecraft K4.

With a FlexRadio it is one of the radio's MultiFlex stations, over the radio's own API: a station of its own, with Opus audio both ways, or the dial and PTT for a SmartSDR, AetherSDR or Maestro station already on the radio. In the Maestro's colours. See FlexRadio.

With an X6100 or X6200 running OpenX6X00, the radios' open firmware, the knob talks to the radio's own TCI server over WiFi, with audio both ways and no computer in between. It finds the radio as x6100.local or x6200.local, and its face wears OpenX6X00's RF.Guru colours. See OpenX6X00.

With Zeus SDR, the JupiterSDR firmware, a beta, is a client of Zeus SDR's TCI server over WiFi, as WSJT-X is, with audio both ways, in Zeus SDR's colours. See JupiterSDR.

With the SVXConnect firmware there is no radio at all: the knob is an SvxLink reflector client over WiFi, in the style of SVXConnect and in its colours. The dial picks the talkgroup, the S-meter shows who is talking, and the built-in microphone and the jack are the station. See SVXConnect.

With the ubersdr firmware the knob is a dial for an UberSDR web receiver, over the receiver's own protocol: through its tunnel or on the LAN, with its audio on the jack, the spots and voices on the band along the bottom, its noise filters and SNR beside the S-meter, and its SSTV pictures on the glass. It only receives. See UberSDR.

With the Kiwi888 firmware the knob is a dial for KiwiSDR and Web-888 web receivers, over KiwiSDR's own protocol: up to four of them, another taken over at once with a swipe up, a second in the right ear on the same dial, each owner's limits kept, in the receivers' own look. It only receives. See Kiwi888.

With the Telephone firmware the knob is a telephone on one SIP account, in SVXConnect's colours: favourites on the dial, a keypad for any number, your starred Google contacts as the favourites, the caller's name in a call, and both voices on the split arc. See Telephone.

With the EpiBeam firmware, a beta, the knob is the beam switch for a phased array — a 4-square or an array of 8 directions — on its way to EpiCenter, the station's master: a direction a detent, counted out in clicks once the dial rests. See EpiBeam.

With the ADS-B Radar firmware the knob is a radar of the aircraft round you, from adsb.fi, adsb.lol, airplanes.live or your own receiver: the range on the dial, each aircraft coloured by its altitude, an emergency or a type you watch for called out, and a tap for an aircraft's route. See ADS-B Radar.

With the Clock firmware the knob is a clock for the shack: local time on the hands, UTC on a 24-hour ring, four faces on the dial, ten alarms. See Clock.

With the Weather firmware the knob is a weather station for one place, from Open-Meteo's forecast: now, the next 24 hours and the next 5 days, the pages rolling on by themselves or a detent each. See Weather.

With the WiFi Test firmware the knob measures the WiFi network it is on, for a knob whose links drop: the signal, every drop and the reason the access point gave, pings to the router, your radio and the internet, and the networks round it. After an hour or more it says in a few words what is wrong, and its report goes into a problem report. See WiFi Test.


Reporting a problem

Open a bug report, one problem per issue, after a look at the open issues. The quickest way is from the knob itself: Report a problem, at the bottom of its configuration page, opens the form with the firmware and the knob's report filled in. The form asks for these; please give:

  1. The firmware and its version, as the address card says it (hold a finger on the S-meter until the knob clicks): OpenX6X00 1.21.1.
  2. The radio, receiver or reflector, with its own software: an IC-705 and its firmware, a FLEX-6600 and SmartSDR's version, AetherSDR's version and the computer it runs on, an X6100 or X6200 and its OpenX6X00 version, a receiver's or a reflector's address. And how the knob reaches it: WiFi, the USB cable, or SmartLink.
  3. What happened: what you did, what you expected and what you got. Give what the face says (NO LINK and the reason under it, a message in amber or red), and the frequency, the mode and the screen you were on. A photo of the knob's face helps.
  4. The knob's report: Make a report on the configuration page gathers its firmware, how it last started (a crash, a watchdog, safe mode), its power, network and link, a crash it remembers, and its recent log, with the passwords the knob keeps starred out; Open it on GitHub puts it in the form. Make it right after the problem: the log is kept in the knob's memory, and a restart begins it again. The issue is public, so read the report before you send it, and take out anything you would rather keep to yourself. Without the page, nc <the knob's address> 3333 on a computer prints the same log.
  5. WiFi: for a WiFi problem, the exact message on the face, the router's security (WPA2, WPA2/WPA3, WPA3 only), its 2.4 GHz channel, whether the network has more than one access point (a mesh, a repeater), and whether a phone's hotspot works. For links that drop, install the WiFi Test firmware where it happens, leave it an hour or more, and paste its report.
  6. Audio and Bluetooth: what you heard (the radio's audio, or your own transmission), the volume and the mic gain, and where: the jack, or a headset or speaker, by its make and model.

Requesting a feature

Open a feature request whose title starts with Feature: and names it in a few words (Feature: CW from a SmartCW keyer on SVXConnect), one feature per issue. Look at the open ones first: if the feature is there, add what you would use it for to that issue. Please give:

  1. The firmware: the one it is for, or several, and the version you run (on the address card).
  2. What you want to do: the operating it is for (portable, a contest, a remote station, a net on a reflector, listening on a web SDR), not only the feature: "send CW on a talkgroup from my paddle, as the others hear it" says more than "add CW".
  3. How you do it today: on the radio itself, with a program on a computer, a phone app or another control head, and what is missing or awkward about it.
  4. Where it would live: on the face (a swipe, a tap, an editor, the dial), on the configuration page, or in the API; what you would do and what you would see. A sketch, or a screenshot of another program that does it, helps.
  5. What it depends on: a radio's protocol or command (CI-V, the FlexRadio API, TCI, SvxLink), a service or a device, with a link to its documentation, and whether it needs an account or a key.
  6. How you can help: testing it on your radio, a pull request, the documentation.

The form asks for each of these, and labels the issue enhancement. One feature per issue lets each be answered, built and closed on its own.

What it does

Tune Per-digit step selection: tap a digit to set the decade. Acceleration on top, so a flick crosses a band and a slow turn lands on 10 Hz.
PTT Toggle — tap to key, tap anywhere along the bottom to unkey. It keys as the finger lifts from a tap, so a swipe that starts on the bottom of the face never keys; on the air, a touch there unkeys at once. On a radio with a choice of antennas — a FlexRadio's slice, the IC-7610, the IC-R8600 — a press held half a second opens them instead, with a buzz, and keys nothing; there a tap keys 0.15 s after the lift, so that the glass losing a held finger for a moment is never taken for a tap. Nothing vibrates while you transmit: the motor sits beside the microphone and would be heard on the air, so the red screen alone says you are keyed, and you feel the unkey once the radio is back on receive. A four-rung teardown ends in dropping the socket. The transmit time-out is the radio's own.
Meters S-meter in receive; SWR, auto-ranging forward power (to 2.5 kW) and mic level in transmit, each holding its peak for a second before it falls, so SSB reads as speech rather than flicker. The mic level uses AetherSDR's own scale: amber from −10 dB, red from 0. SWR above 2.5 turns its reading red.
Audio RX audio out of the 3.5 mm jack, TX audio from the onboard mic, both with adjustable level. The jack is a line output: for wired earphones or a headset still too quiet at a volume of 100, its level on the configuration page goes up to 12 dB above the volume, in steps of 3, a loud passage turned down rather than clipped. The built-in microphone is very good — clear, natural speech on the air, ideal for amateur radio — so the knob needs no headset or hand mic. On AetherSDR and the Icoms the page can have the knob key the radio's own microphone input instead, as a foot switch would: AetherSDR's — the computer's, a USB microphone say — or the Icom's own MIC, USB or ACC, as the radio has it set.
Headset A Bluetooth headset through the board's second chip, with the companion firmware on it: the knob's audio in the headset, its microphone the one you transmit with — the knob's own is then off — and its call button a PTT beside the slab, which keys as always. The slab keeps its caption and shows the headset's logo at its right end, red while the headset's microphone is muted, when neither keys, with its battery beside it — green, yellow or red — where the headset reports it; optionally the boom arm is the PTT, down to talk. The knob's own microphone and a headset's each keep their own mic gain; the dial turns the one in use. On the receivers' firmwares (UberSDR, Kiwi888, OpenWebRX and WebSDR), only for listening. On the Clock, its alarms ring in it. A Bluetooth speaker plays the knob's audio as well as the jack, a fifth of a second or so behind it, and the knob's own microphone transmits: a speaker shows at the slab's end, and it falls silent while you do; one that takes its volume from what plays to it has the knob's VOLUME for its own, both ways. Each headset or speaker has its own level on the configuration page, 24 dB down to 12 dB up — a speaker 12 dB down until it is set. The second chip tells a speaker from a headset by itself; the configuration page can say otherwise.
Mode / filter / RIT Tap to open and turn to choose. Filter and RIT take effect as you turn, and a tap anywhere closes them; band and mode take a tap on their panel, and a tap anywhere else leaves them as they were.
DSP On the FlexRadio and AetherSDR firmwares, swipe from the right: NB, NR, ANF, and APF in CW — and WNB on a FlexRadio — each switched on and off with a tap, lit when on, as SmartSDR's buttons are. Their levels stay as the radio has them.
AGC / gain Either side of the S-meter's reading, edited like the filter: the AGC on the left, and on the right the front end's gain — P.AMP on the IC-705, RF.G on the FlexRadio, greyed out on AetherSDR until its TCI can carry it.
Memories On the IC-705, the IC-9700 and the FlexRadio, V/M, last on the swipe down: MEMORY, and the frequency readout becomes the channel — its name, number, frequency, shift and tone — and the knob steps through the programmed channels of one group (tap the group, where the band was, to choose another; on the IC-9700 the group is the band it is on). A FlexRadio's memories have no groups: the knob steps through all of them in order of frequency, each put on the slice by the radio's own memory apply. VFO again for the VFO, simplex.
Radios Up to four per firmware on the configuration page — an IC-705, an IC-7610, an IC-9700 and an IC-R8600, two FlexRadios, AetherSDR on two computers — and, on the FlexRadio firmware, the SmartLink account's. Swipe up, turn to one, tap on it: the knob restarts into it (SWITCHING TO …), with or without a link to the one it leaves; under the name, LAN or SmartLink says how it is reached. Not over the USB cable, which reaches one computer or one radio.
Gain, power, tuner On the Icom firmware, swipe from the left for RF GAIN, and tap it for POWER, in watts; both apply as the knob turns (with a web SDR chosen, BALANCE comes first). Swipe from the right to put the IC-7610's antenna tuner in the line or out of it — only that: no tune cycle, nothing transmitted.
Web SDR On the Icom and FlexRadio firmwares, a KiwiSDR, a Web-888 or an UberSDR as a second receiver beside the radio (and beside an UberSDR, a KiwiSDR): swipe down, turn to LOCAL or a receiver, and tap. It follows the radio's frequency, mode and passband. The radio is in the left ear and the SDR in the right, brought to the same loudness, and BALANCE — first on the swipe from the left — fades from one to the other. See Web SDRs. On the Kiwi888 firmware a second of its own receivers plays in the right ear: RIGHT EAR, OFF or a receiver, and BALANCE from LEFT to RIGHT — see Kiwi888.
Network Hold a finger on the S-meter until the knob clicks: the card comes up with the firmware and its version (UberSDR 1.19.0, or … dev for a build that is not a release), the knob's power — battery 85 %, or on USB power — and its addresses; tap the card to put it away. With the card up, hold the S-meter again, until the knob buzzes, for the firmware picker.
Lock With the address card up, tap LOCK over the S-meter: a padlock shows at the top of the arc (on EpiBeam, which has the gear for the card, inside the ring; on ADS-B Radar, which has one too, under the range), and the knob ignores turns, taps and swipes and keys nothing — not the slab, a headset's button or its boom arm. Unkeying is never locked, and the telephone's slab still hangs up. A question the knob asks still takes its answer. UNLOCK on the card again, or a restart, frees it. On every firmware but the setup one.
Screen Its brightness on the configuration page, 10 to 100 % (80 % until it is set). Left alone for a minute, the knob shows a screensaver — Matrix rain until set, or an analog clock, a digital clock, the frequency drifting round the glass, or none — dims it a minute later and goes dark a minute after that, all three times set there too; a turn, a touch or transmitting brings the dial back, and that first turn or touch does nothing else. The Clock, the Weather and the WiFi Test have none and stay lit until set. Step by step: the screensaver guide. The knob comes with its USB cable at the top; for a stand or a mount with the cable at the bottom, The USB cable: At the bottom there turns the screen the other way up, and the touch with it.
Battery Unplugged, the knob runs on its own battery and shows its charge at the top of the arc, over the S-meter's reading, as a phone does, on every firmware's face — on EpiBeam inside the ring, over the array, on ADS-B Radar under the range, on the Weather under the time, on the WiFi Test under the page's name, on the Clock only once it is low: full to empty by the quarter, green from half its charge up, yellow under that, red at a fifth and below — a headset's battery's look. None on USB power, where the charge cannot be read, nor on a radio's face on the air, where the transmit scale is. The configuration page says the same, with the voltage the knob reads.
Branding RF.Guru boot splash in the palette of rfguru.app, over the site's own backdrop.

Two transports

The knob runs from USB as well as from its own battery — and whatever runs AetherSDR is a computer with a USB port.

  • USB-C (preferred). The knob enumerates as a USB network adapter (CDC-NCM), hands your machine an address and talks TCI over the cable. No configuration at all, and immune to what a machined metal case does to 2.4 GHz.
  • WiFi. Configure an SSID on the configuration page and power the knob from any charger, or run it on its battery.

The cable wins whenever a computer is on the other end of it as the knob starts — the knob then waits for AetherSDR there rather than switching networks. With no computer on its side of the cable — a charger, the plug the wrong way round, or no cable at all — it goes to WiFi straight away. It looks only then: a knob already running on its battery stays on WiFi when it is plugged in, until Reboot on its page, with the cable in, starts it on the cable. When the cable is chosen, WiFi is shut down — that frees about 40 kB of internal RAM, which this board genuinely needs.

First run

Knobs ship with the setup firmware, vfo-knob-setup: it puts the knob on your WiFi from a phone and installs the firmware for your radio. No computer needed. Step by step, with the knob's own screens: the setup guide (one guide per firmware in docs/).

  1. The knob comes up as an open WiFi network, VFOKnob. Join it with a phone, and the phone opens the knob's sign-in page by itself (if it does not, browse to http://192.168.4.1).
  2. Choose your network, enter its password — Show shows it as you type — and tap Connect. The page says whether the knob got on, and if not, why — a wrong password, a network out of reach — so you can try again.
  3. The knob then lists the firmwares on its dial, with their versions: turn to yours and tap the panel to install it. It downloads the image, checks its signature and restarts into it, and the WiFi settings go with it.
  4. Tell the knob where its radio is, on its configuration page: hold a finger on the S-meter, at the top of the face, until the knob clicks, and browse to the address on the card that comes up — user admin, password admin. The page first asks for a password of the knob's own, 8 to 32 characters, and shows nothing else until it has one, since the knob can key a transmitter; your browser then asks for the new one.

The list comes from the update server each time, so a knob set up long after it was made still shows every firmware there is then. A knob that already knows a network joins it and goes straight to the list; the list's last entry, WIFI, brings the hotspot back to set up another.

The knob keeps up to four networks — home, and a phone's hotspot, say — and joins whichever is in reach. Taken where none of them is, any firmware puts up VFOKnob again after about 25 seconds, with WIFI SETUP on its face, to add one from a phone; it keeps looking for the ones it knows meanwhile.

Back to the list, from any firmware: hold a finger on the S-meter until the knob clicks and the address card comes up, and let go. Then hold the S-meter (or the card) again, for three seconds, until the knob buzzes. The dial asks FIRMWARE? — turn the knob for yes; a tap, or ten seconds of nothing, says no. The knob restarts, installs the setup firmware over WiFi and shows the list again, keeping the WiFi settings. With something wrong — NO LINK, say, on a knob with another radio's firmware — the warning panel shows the addresses in the card's place: hold that until the knob buzzes. It needs WiFi: on the cable the knob says so and carries on as it was.

AetherSDR over the cable

The AetherSDR firmware also runs over the USB-C cable, from the computer running AetherSDR (step by step: the AetherSDR guide):

  1. Plug the knob into the computer running AetherSDR. Windows 10 (version 1903 or later), Windows 11, macOS and Linux all bring it up as a network adapter by themselves — there is nothing to install — as the knob starts: one already running on its battery stays on WiFi until Reboot on its page restarts it with the cable in. The USB-C socket only works one way round: the other way it reaches the board's second chip, the knob finds no computer, and it says FLIP USB-C. Turn the plug over.
  2. In AetherSDR, enable the TCI server — the TCI panel in the button bar — and set it to start automatically in Settings, so the knob finds it every time. That is the only setup on the computer.
  3. Open http://10.55.42.1 — user admin, password admin.
  4. Change the password. The page will nag until you do; it can key a transmitter. Over the cable admin keeps opening it; over WiFi the page asks for a password of the knob's own first, and shows nothing else until it has one.
  5. If you want WiFi, set an SSID and the AetherSDR host. The host is only used on WiFi: over the cable the knob always talks to the computer it is plugged into.
  6. Optional: for the knob's clock and its own update checks, let the computer pass the knob's traffic on to the internet: the internet over the cable.

If the page does not open

Give the knob about ten seconds after it starts with the cable in: for the first six it is a serial port, which keeps it flashable, and only then a network adapter. A knob already running on its battery when it is plugged in stays on WiFi: Reboot it from its page, with the cable in.

  1. FLIP USB-C on the knob, or the computer finds a USB Serial (CH340) port instead — USB\VID_1A86… in Windows' Device Manager: the plug is the wrong way round. Turn it over. With WiFi set up the knob only says so for a few seconds after the splash before carrying on over WiFi, so watch it start, or look for that CH340 port.
  2. Windows. The knob is under Network adapters in Device Manager — Windows 10 names it after its driver, UsbNcm Host Device — with Hardware Ids (Properties → Details) starting USB\VID_303A&PID_4000. Windows 10 before version 1903 has no driver for it: update Windows, or set WiFi up once over the cable from a computer where it works and run the knob from a charger. Firmware 1.3.2 and older is the exception to "nothing to install": update it. Until then, on Windows 10 it shows as an unknown device (Code 28) and needs its driver chosen by hand — right-click → Update driver → Browse my computer for drivers → Let me pick from a list of available drivers on my computer → Network adapters → Microsoft, UsbNcm Host Device — and on an up-to-date Windows 11 it fails with Code 10, which no driver choice fixes.
  3. Check the address. The computer's side of the link should be 10.55.42.2 (ipconfig on Windows). A 169.254.x.x address means it got no lease: renew it, or set 10.55.42.2, mask 255.255.255.0, no gateway and no DNS by hand. ping 10.55.42.1 should then answer.
  4. Open the page with the scheme typed out, http://10.55.42.1/. If ping answers but the browser does not, a VPN or a proxy is taking the request — disconnect it, or add 10.55.42.* to the proxy exceptions.

WiFi instead of the cable. With no computer on its side of the cable the knob goes to WiFi by itself, a few seconds after powering up — so a charger is all it needs, once an SSID and the AetherSDR host have been set over the cable from a computer where it works. Plugged into a computer it stays on the cable even if that computer could not set the adapter up; keep a finger on the screen from its start until the dial appears to skip USB networking for that boot.

If the knob says NO LINK

The page opens but the knob stays on NO LINK: either AetherSDR's TCI server is not running — see First run — or the computer's firewall is turning the knob away. The knob connects to AetherSDR, so the computer has to let it in.

Over the cable the link has no internet access, which is correct: nothing lies behind the knob. With no gateway on it, Windows lists it as Unidentified network and treats it as Public, so if AetherSDR's firewall prompt was answered for private networks only, the knob cannot reach AetherSDR's TCI port over the cable. Allow it once, from an administrator PowerShell — 50001 is AetherSDR's default; use the port set on the configuration page:

New-NetFirewallRule -DisplayName "VFO-Knob TCI (USB)" -Direction Inbound `
  -Protocol TCP -LocalPort 50001 -RemoteAddress 10.55.42.1 -Action Allow -Profile Any

A Block rule always beats an Allow, and that prompt may have left one for AetherSDR on public networks. If the rule above changes nothing, open Windows Defender Firewall with Advanced Security (wf.msc), find AetherSDR's Public TCP rule under Inbound Rules, switch it from Block to Allow, and on its Scope tab set Remote IP address to 10.55.42.1. Left unscoped, that opens AetherSDR's TCI port — which can key the transmitter — to everyone on every public network the computer joins.

A Linux firewall that drops inbound connections by default (ufw, or firewalld's public zone) stops the knob the same way — on the cable, and on WiFi from wherever your network puts it. Let both in once, e.g. sudo ufw allow proto tcp from 10.55.42.1 to any port 50001 for the cable and sudo ufw allow proto tcp from 192.168.1.0/24 to any port 50001 with your own LAN's range for WiFi.

FlexRadio (MultiFlex)

The multiflex firmware (vfo-knob-multiflex) talks to a FLEX-6000 or FLEX-8000 itself, over the radio's own API on the LAN — no SmartSDR, no AetherSDR, no computer. Step by step: the FlexRadio guide. The knob is one of the radio's MultiFlex stations, beside SmartSDR, AetherSDR or a Maestro, in the Maestro's colours.

The multiflex face: S9+20 on 20 m, 14.200.00 USB with a 2700 Hz filter, AGC MED and RF.G +8 dB, in the Maestro's blue

At boot the knob looks at who is already on the radio and, if anyone is, asks on the dial what to be:

  • STATION OWN — a station of its own. Its own slice, which the radio gives back where it was after a restart; its own audio both ways, as Opus over WiFi, so the jack and the built-in microphone are the station; and its own transmit settings, which leave the other stations' alone.
  • DIAL FOR station — the dial and PTT for a station already there, like a FlexControl on its computer. The knob works that station's active slice, and follows when its operator clicks another; PTT keys that station's transmitter, with that station's microphone. The knob plays no audio.

The last choice is offered first, and taken after 30 s without an answer. With nobody else on the radio the knob does not ask.

The dial Tunes the slice. Mode, filter, AGC, RIT and RF.G — the panadapter's RF gain, which the radio's API carries — are edited as on the other radios.
Swipe from the right TUNE, a carrier at the tune power, for an external tuner or to check SWR — PTT stops it, and it stops by itself after 30 s. ATU, one cycle of the radio's tuner. MEM, the tuner's memories, lit when on; a tap switches them and the menu stays. Then the slice's DSP: NB, WNB, NR, ANF, and APF in CW, each switched as MEM is. The menu opens on MEM: TUNE and ATU are a turn one way, the DSP the other.
PTT Refused with the reason when the radio will not transmit here: out of band, or another station on the air. Held half a second, until it buzzes: the slice's antennas, RX ANT and then TX ANT, by the radio's own names (ANT1, ANT2, RX_A, XVTA ...).
Swipe down After the web SDRs, the antennas, and last V/M: the radio's memories on the dial, as an Icom's memory channels — the memory's name where the frequency was, one memory a detent in order of frequency, each put on the slice with the radio's own memory apply.

MultiFlex must be enabled on the radio. A FlexRadio announces itself on its network: the configuration page lists every one the knob hears, with Add, and the swipe up offers those not yet listed — or give the radio's IP address there, as for one on another subnet.

SmartLink

A radio away from home is reached through FlexRadio's own service, as SmartSDR and AetherSDR reach it. Log in under SmartLink on the configuration page with the account's email address and password: the password goes to FlexRadio's login service and is not kept — the knob keeps the login it is given, until you log out there. The account's radios are listed, and with Offer these radios on the knob they come after the configured ones on the swipe up, marked SmartLink under the name; LAN marks the direct ones. The same radio can be in the list both ways.

Chosen, the knob restarts into it: SmartLink's server introduces the knob to the radio, which it then reaches over TLS. The radio's certificate is its own, self-signed; the knob pins it the first time, as AetherSDR does, and refuses a different one until you log in again. After that it is the same station as on the LAN, Opus audio and PTT included. A radio reachable only by hole punching — neither a forwarded port nor UPnP — is listed but not yet connected to.

OpenX6X00

The openx6x00 firmware (vfo-knob-openx6x00) is a dial for a Xiegu X6100 or X6200 running OpenX6X00. It uses the same TCI as the AetherSDR firmware, but talks to the radio itself, over WiFi, on the radio's TCI server (port 50001, on by default).

It looks for the radio as x6100.local, the name OpenX6X00 announces for an X6100 over mDNS, and for x6200.local, an X6200's, when that one does not answer (and the other way round), so it follows the radio when its address changes. A radio given another network name is listed as <name>.local, or by its IP address, with up to four radios in the list. On an X6200 the dial also offers SAM and WFM, and FM broadcast and the airband, receive only.

The radio's audio plays on the jack, and the knob's microphone transmits. The radio unkeys by itself after half a second without the knob's audio, when the link drops, or after three minutes on the air.

Step by step: the OpenX6X00 guide.

Elecraft K4

The k4 firmware (vfo-knob-k4), a beta, makes the knob a remote client of an Elecraft K4, as K4remote and the K4/0 are: over WiFi, to the radio's remote server, with no computer in between. The dial tunes VFO A, the editors set the mode, the passband, the AGC, the RF gain, RIT and the DSP, the slab keys the radio, and its Opus audio plays on the jack while the knob's microphone goes back. The S-meter and, on the air, power, SWR and the microphone's level are the radio's. A key the radio refuses is shown with its reason; a radio that stops answering while keyed gets the PTT ladder's unkey, as on every firmware.

It speaks the radio's clear port, 9205, where the password goes as its SHA-384 hash and nothing else is encrypted: keep it to your own network. The K4's server needs a password and Max Clients of 1 or more (the globe button, then SERVER SETTINGS). Tried on one K4: it is written from Elecraft's programmer's reference and K4remote's notes, and run against a mock K4 as well. The sub receiver, VFO B, the memories and the antennas are not there yet. Help wanted: with a K4, please try it and tell us how it went, with Report a problem on the knob's configuration page.

Step by step: the K4 guide.

JupiterSDR

The jupitersdr firmware (vfo-knob-jupitersdr), a beta, is a client for Zeus SDR. It uses the same TCI as the AetherSDR firmware, over WiFi, on Zeus SDR's TCI server (port 40001): turn TCI on in Zeus SDR, let it listen on the network, and give the knob the computer's address. Zeus SDR's audio plays on the jack, and the knob's microphone transmits through Zeus SDR, which refuses a key outside the bands it allows. Zeus SDR does not unkey when the link drops: the knob sends the unkey again when it is back, and Zeus SDR's own transmit timeout ends the over until then. JupiterSDR is compatible with ZeusSDR, and not made by its authors.

It is for the radios Zeus SDR drives itself. With a FlexRadio, choose the FlexRadio firmware beside Zeus SDR: through Zeus Link for Flex, Zeus SDR's TCI gives receive audio and the frequency, but neither keys the radio nor sends the S-meter.

Help wanted: it has received through Zeus SDR on one station, and has not yet been on the air through it. If you run Zeus SDR, please try it and tell us, in issue #17 or with Report a problem on the knob's configuration page.

Step by step: the JupiterSDR guide.

Web SDRs

On the Icom and FlexRadio firmwares the knob can listen to a web SDR beside the radio — a KiwiSDR, a Web-888, or an UberSDR through its Kiwi input; all three speak KiwiSDR's protocol. Up to four are kept, added on the configuration page with their address (host:port — 8073 on most KiwiSDRs), a password where the receiver has one, and its time-limit password, which lifts the listening limit some receivers put on each address. A receiver behind the kiwisdr.com proxy or Cloudflare, reached only over https, goes by its https:// link, pasted whole (https://n0bqv.proxy.kiwisdr.com): the knob speaks KiwiSDR's protocol to it over TLS, its certificate checked against the authorities a browser trusts, for its name — the first connection a few seconds slower, TLS being done in software, the next ones quick where its front lets the knob resume. An http:// link it answers with a redirect to https on its own host is followed at once, and kept from then on. An UberSDR's Kiwi input is port 8073 on its own address (its enable_kiwisdr on), its bypass password in the password; it centres CW on the carrier where a KiwiSDR centres it on its 500 Hz tone, or wherever its owner set it, and the knob tunes each as its own page would.

Swipe down RX: turn through LOCAL and the receivers by name, tap to listen. The IC-7610 then goes on to MAIN/SUB and the antenna for the radio's side, whichever was chosen: with an SDR the radio still plays in the left ear. The IC-R8600 goes on to its antenna, the IC-705 and the IC-9700 to V/M, a FlexRadio to RX ANT, TX ANT and V/M.
Listening The SDR follows the radio: frequency, mode and passband, retuned as the dial turns; in CW the station on the dial is heard at the receiver's own CW tone, as on its own page — 500 Hz on a KiwiSDR, unless its owner set another. The radio is in the left ear and the SDR in the right, both levelled to the same loudness. When the network holds the SDR's audio up and then hands it over all at once, the right ear leaves the late audio out where it had gone quiet anyway and picks up at the live point, rather than lagging behind or breaking up; where short stalls come again and again it keeps more in hand, up to 0.7 s, and eases back once the stream has been calm for three minutes. It follows the receiver's clock, a hair faster or slower, and every 30 s the log says how its audio came (sdr: ring … ms of …).
Its S-meter A thin blue line just outside the radio's S-meter, on the same scale, and its reading in blue under the radio's, where the dBm is otherwise: S9+20 against the radio's S7. A Web-888 and a KiwiSDR each count it from their own reference. Dots while it connects; a word, in amber, when it cannot — busy, no apps, password?, day limit, time up, kicked, refused, not a kiwi, moved, certificate, one per ip, updating, memory full, try later, no answer — or can't reach: the radio beyond what it covers (6 m on a KiwiSDR), the SDR quiet rather than playing the top of its range, still logged in, and back the moment the radio is within it — unless its owner's limit on idle listening has ended the session meanwhile (time up); the pages say what it covers.
Balance First on the swipe from the left while an SDR is chosen; a tap on it goes on to RF GAIN and POWER. From RADIO, the radio alone, through L | R to SDR, the SDR alone.
Transmitting The SDR goes quiet: it would play the over back a second late, and from a speaker the microphone would hear it.

Test, beside each receiver on the configuration page, logs in and says what the receiver calls itself, how many of its channels are in use, and whether the password is right; a receiver with no name yet gets the one it gives itself in its Name box, which Save keeps. On the dial an unnamed receiver goes by the antenna its status page names, once the knob has read that, else by its address, with the port where another receiver shares it: four on one address stay apart. Your name, for their owners, under the list, is what every receiver's owner sees the knob as among those listening — your callsign, say; left empty, VFO-Knob; told at once to the receiver playing. The knob logs in as the receivers' own apps do, so an owner's limits on apps hold for it: a KiwiSDR can keep its channels for browsers. One whose status page says it lets no apps in is no apps at once, with no login, until it is chosen again; one whose channels for apps are all in use says nothing to the knob — busy, asked again two minutes on, and after the third time no apps. A receiver that is full is asked again 20 s on.

The choice is on the radio page too, and in its API: sdr=local or sdr=0 to 3, by the receiver's place in the list, and balance=-100 to 100.

The receiver's limits

An owner may limit how long one address listens in a day, end a session nobody uses, or send a listener away. A Kiwi also bars an address for good after five logins it refused for its day limit — and every browser behind that address with it. The knob keeps to all of it:

Day limit A receiver that turns the knob away because the day's listening time is used up is marked, and the mark is kept through restarts. The knob does not log in to it again by itself — not at power-on, not after a save, not on a retry. Choosing it again, on the dial (swipe down, tap), on the radio page or with sdr=, is one more try; so is a new time-limit password. The knob takes two such refusals from a receiver at most, until the mark lifts.
No answer A login's answer is always waited for, ten seconds, whatever else happens meanwhile: it may be a refusal the receiver counted. A receiver with time limits that leaves the login unanswered — silence, or a connection that fails — counts as such a refusal, in case, and no second login follows. Without time limits it is tried again after 2 s, then longer each time, up to 30 s.
When it lifts When the receiver's own status page shows it has restarted — read once at power-on and before a try, never polled. On a KiwiSDR also a day after the last refusal, as it clears its count once a day; a Web-888 forgets nothing until it restarts. Its owner taking the time limits away, or a try that plays for ten seconds, lets the receiver go, its refusals still counted: refused again, it has no more tries than it had.
Time up The receiver ended a session nobody used. The knob waits until it is chosen again.
Kicked Its owner sent the knob away. Not again until it is chosen again either.
Refused It will not talk to this address (HTTP 403, badp=3): not again until it is chosen again.
Password?, not a kiwi A wrong password, or something other than a KiwiSDR or a Web-888 answering at the address (HTTP 400 or 404): not again until it is chosen again or the list is saved.
Moved, certificate A redirect the knob does not follow — to another host, or a second one — says where it points (moved to … on the pages and in the log); an https receiver whose certificate does not check out is not spoken to. Both: not again until it is chosen again or the list is saved.
Six tries On its own the knob tries one receiver at most six times in ten minutes, whatever ended them, counting only the tries that reached it; try later meanwhile. Choosing it goes at once.
Memory full With its settings memory full, the knob could not keep a mark through a restart: it logs in to a receiver with time limits only when it is chosen.
Crashes After a run of crashes or brownouts, each soon after the last start, the knob waits before it contacts the receiver on its own — half a minute, longer each time, ten minutes at most: try later. After any crash, time up, kicked and refused still hold until the receiver is chosen again; a power-on starts afresh.
Test Never logs in to a receiver at its day limit — it says how many tries are left, or that the knob leaves it alone until it restarts (a Web-888) or for a day at most (a KiwiSDR) — nor to the one in use while its session is on its way or playing; and the knob waits for a Test's answer before its own login, so the two never log in at once, and a refusal a Test met is no try spent by a choice made before it. A second Test within a minute reads no status page again.

UberSDR

The ubersdr firmware (vfo-knob-ubersdr) makes the knob a dial for an UberSDR: it talks to the receiver over its own protocol, as the receiver's web page does, with Opus audio. It reaches it through UberSDR's tunnel (https://<name>.tunnel.ubersdr.org, over TLS) or on your own network (http://<address>:8080, in the clear, with no password and no time limit where UberSDR lets its own network past them, as it does as it comes), and plays it on the jack. Receive only, in UberSDR's own dark theme. Step by step: the UberSDR guide.

The ubersdr face: S6 on 20 m, 14.215.00 USB, SNR 9 dB and the NR4 noise filter either side of the S-meter, the spot LU7YZ heard now on the bottom, and a guest's 52 min left at its left end

SNR, FIL Either side of the S-meter: the signal's height above the noise in its passband, and the receiver's noise filter — OFF, NR2, RN2 or NR4, whichever it runs — chosen as the knob turns.
Spots and voices Along the bottom, where PTT is on a radio: the one nearest the dial on the band -- the DX cluster's spots and every voice the receiver's detector hears now, named or not (in CW, the CW skimmer's), green while it is heard. A tap puts them all on the dial; tap one and the receiver goes there in its mode.
SSTV Swipe from the right: the receiver's SSTV gallery, newest first, one picture a detent; any tap goes back to the dial.
A KiwiSDR beside it Swipe down for LOCAL or a KiwiSDR (or a Web-888), which follows the UberSDR: the UberSDR left, the KiwiSDR right, BALANCE from the left.
Its limits Without the receiver's password the knob listens as a guest: its time left at the slab's left end, counted as the receiver counts it, the seconds too in the last five minutes, in amber, red in the last one -- or an idle limit's last minute, which a touch gives back. When the receiver ends a session, the dial asks before starting another, as UberSDR's own page does.
Its receivers Up to four in the list. When the one in use cannot be reached -- its name not found, no answer -- the knob goes on to the next by itself, after a second try, with no restart: the first that answers plays and is in use from then on. The face names each as it goes. The one in use that answers but turns the knob away (full, its password, its time up) keeps its turn; a stand-in that does is passed by for the next. See another receiver.

Kiwi888

The kiwi firmware (vfo-knob-kiwi) makes the knob a dial for KiwiSDR and Web-888 web receivers: it talks to each over KiwiSDR's protocol, as the receivers' own apps do, and plays it on the jack. The receivers are the web SDRs' list on the configuration page, up to four by host:port — or by an https:// link, for one behind the kiwisdr.com proxy or Cloudflare, spoken to over TLS — and another is taken over at once, with no restart: a swipe up, a tap on the receiver's name at the bottom of the face, the page's In use, or receiver= in the API. Add RF.Guru's receivers on the page fills in the four Web-888s at Lombardsijde, logging in to none. A second receiver from the list can play in the right ear, on the same dial: one antenna against another. Receive only, in the receivers' own page's look. Step by step: the Kiwi888 guide.

The kiwi face: S8 on 40 m, 7.123.00 LSB, AGC MED and NR OFF either side of the S-meter, its peak held in red, the receiver EchoTracer along the bottom with its model, address and whereabouts

S-meter The receivers' lime bar, the peak held a second as a red mark, as on their own page; OV after the reading, in red, while the receiver's ADC overloads.
AGC, NR Either side of the S-meter: the AGC (FAST, MED, SLOW, the receivers' own presets), sent as the knob turns, and the noise filter (OFF, WDSP, LMS, SPEC, the receivers' own), sent once it has rested half a second.
Squelch Swipe from the right: 0 % OPEN; the receiver's own scale in NBFM, up to 40 dB over its noise in the other modes. A slider on the radio page, squelch= in the API.
The receiver Along the bottom, where PTT is on a radio: its name, its antenna or address, where it is — or connecting.... A tap there, or a swipe up, for another. Without a name of yours, its antenna as its status page names it, else its address, with the port where another receiver shares it.
The right ear Swipe down for RIGHT EAR: OFF, or another of the receivers, on the same frequency, mode and filter, and with the left ear's AGC, noise filter and squelch — the one in use in the left ear, this one in the right, at the same loudness. Where its receiver does not reach the dial (a KiwiSDR beside a Web-888 on 6 m) it goes quiet, can't reach in amber, until the dial is back within its range — or its owner's limit on idle listening ends the session meanwhile (time up). Its S-meter the thin blue line outside the left ear's, its reading in blue under the S-units; BALANCE from the left, LEFT … L | R … RIGHT. One receiver is never in both ears: each ear's chooser shows the other's dimmed and refuses it, and so do the pages and the API (sdr=). Each ear keeps its receiver's owner's limits; a day-limit mark is the receiver's, whichever ear met it.
Its audio A quarter of a second in hand. The knob follows the receiver's clock, a hair faster or slower, so that holds for hours; when the network holds the stream up and then hands it over at once — or at least twice as fast as it plays — the knob leaves the late audio out where the sound had stopped anyway and is back at the live point: one break. Handed over more slowly, it is cut back every few seconds until the network has caught up. Where short stalls come again and again, the knob keeps more in hand, up to 0.7 s, until the stream has been calm for three minutes, then eases back: more delay only while the network is bad, fewer breaks (0.4 s every 8 s: two breaks in two minutes, not fourteen). Each ear alike. Every 30 s the log says how the audio came, what the knob holds against what it keeps it at.
Its limits As for a web SDR beside a radio (The receiver's limits): a day limit is marked through restarts and tried again only when chosen, twice at most, and so is a login left unanswered by one with time limits; time up and kicked ask LISTEN AGAIN; a KiwiSDR's silent door for apps is apps full, three times no apps. On its own the knob tries a receiver at most six times in ten minutes, counting only the tries that reached it; MEMORY FULL and a run of crashes keep it from trying on its own. A tap on the receiver's name, even the only one's, chooses it again.

OpenWebRX

The owrx firmware (vfo-knob-owrx) makes the knob a dial for OpenWebRX and OpenWebRX+ web receivers: it talks to each over the receiver's own web protocol, as its page does, and plays it on the jack. The receivers are the configuration page's list, up to four, each by its address whole — http://sdr.on4pra.be/, https://fms.komkon.org/OWRX/, watou.on4ipr.be:8076 — with Test beside each; when the one in use cannot be reached the knob goes on to the next, as on UberSDR. The dial stays within the receiver's band and stops at its edge; BAND chooses another of the receiver's bands from a list. The meter reads in dB, as OpenWebRX's own page does. Receive only.

WebSDR

The websdr firmware (vfo-knob-websdr) makes the knob a dial for PA3FWM's WebSDR receivers, those listed on websdr.org — the wide-band WebSDR at the University of Twente, and the many others: it takes the receiver's stream as its page does and plays it on the jack. Up to four in the configuration page's list, by address (http://websdr.ewi.utwente.nl:8901/, http://sdr.websdrmaasbree.nl:8901/); the dial moves across the receiver's bands by itself; the S-meter in dBm with S-units (S9 = −73 dBm). The name the receiver lists you by among its listeners is set with the receivers, and the receiver's own idle time-out is kept. Receive only.

SVXConnect

The SVXConnect firmware (vfo-knob-svxconnect) turns the knob into a node on an SvxLink reflector: protocol 3.0, the reflector's own TLS with a client certificate, Opus audio both ways at 16 kHz. It is a port of SVXConnect-CLI's reflector client, and shares its protocol code, talkgroup manager and codec settings. Step by step: the SVXConnect guide.

The svxconnect face: ON6URE talking for 14 s on TG 8, 70cm Repeaters, on be.svx.link; the arc at -14 dBFS, the talkgroup unlocked and the sound on

The face is the radio face, read differently:

The dial Steps through the switchable talkgroups, one a detent. The talkgroup's name, from the reflector's portal, is where the frequency is — looping when it is long — with the reflector under it; TG n is where band and mode are.
Lock Left of the talkgroup: no busier talkgroup takes you away, no quiet spell drops you to monitoring, and the others are not heard. The dial still switches, and the talkgroup it turns to is locked in its turn.
Mute Right of it: the speaker off, the talkgroup still selected, who is talking still shown.
Meter The received audio in dBFS, and in transmit the microphone. Above it, who is talking — with where they are, when the reflector publishes it — or who spoke last and how long ago.
PTT Tap to key, tap to unkey, as on the radios. The reflector's own announcement of your callsign confirms the key; on a busy talkgroup it refuses you the floor and the knob says so with the refusal click.
Link Where the step is: connected, connecting or disconnected.

Talkgroups follow SVXConnect's rules: switchable ones are on the dial and heard only while selected, monitored ones are heard and followed when there is traffic, a + after a monitored number raises its priority (9990, 8++, 1745+), the knob stays on a talkgroup for a while after an over, and drops back to monitoring after a quiet spell, if there is a monitored list to drop back to. A talkgroup can be in both lists. With no lists set it steps through every talkgroup the reflector's portal names.

First run

  1. Set the WiFi on the configuration page, and the reflector: its name, not its host — be.svx.link is found through its SRV record.
  2. Under Station, give your callsign and an email address; the location and position are for the reflector's map.
  3. Press Request certificate. The knob makes its RSA key (a few seconds), sends the reflector a certificate request and keeps asking every 30 s until the sysop has signed it, then logs in by itself. The certificate renews by itself; the key never changes, because the reflector knows the callsign by it. Key and certificate are kept on the SD card with the other settings; while that card does not answer the knob makes no new key.

On an enhanced reflector

Where the reflector has a portal, the knob reads its talkgroups.json for the names (kept on the SD card, refreshed daily) and follows its live feed for where each talker is. The feed is a second connection to the same host; the knob pauses it while it logs in, and it can be switched off on the configuration page.

Telephone

The Telephone firmware (vfo-knob-phone) turns the knob into a telephone on one SIP account, with its own small SIP client: registered over UDP and out through your router by itself (no STUN, no port forwarding), G.722 HD voice where the other side has it and G.711 otherwise, both ways, RFC 4733 DTMF. Step by step: the Telephone guide; for the starred Google contacts, GOOGLE.md.

The telephone face in a call: 02:47, in call; Mum in the middle with her number above; her voice on the left half of the arc, ours on the right; our own number under it; a red HANG UP slab

SVXConnect's face, read as a telephone:

The dial Between calls, steps through the favourites: the name in the middle, its number above it. Up to 40, typed on the configuration page or synced from your starred Google contacts every six hours. In a call, the volume.
The slab The call's next step: CALL the favourite shown, a red HANG UP; a call ringing in splits it, DECLINE left and a green ANSWER right. NO SERVICE while the account is not registered.
Keypad Swipe down: a number by hand, then CALL; a long press on 0 for +. In a call the keys go out as DTMF.
Meter Split in two: the other end's audio on the left half, your microphone on the right, each with a peak that holds and falls. Under it the call's time, or RINGING, CALLING, ENDED and why.
In a call The other end's name in the middle -- your favourites', or the caller's own -- and their number above it; no favourite until the call is over.
History Swipe from the left: the last 20 calls, missed ones in red. Turn through them, tap to call back. A missed call shows under the arc until you look.
Mute The microphone right of the number: the knob's own microphone off, and you still hear them. A headset's mute is the headset's.
Ringing A call coming in vibrates at full strength in the ring's rhythm, the ANSWER slab breathes green inside a green rim, and it rings on the jack and in a headset or speaker.
Audio On the 3.5 mm jack, the knob's own microphone muted until you tap the microphone icon; or, with a headset connected, only in the headset, its microphone live.
Headset Its audio opens for calls only, from the ring or the dialling until the call is over. Its button answers a call ringing in and hangs up one that is up, the slab then declining; its own mute only mutes.
Speaker A Bluetooth speaker plays a call with the jack, a little behind it, its audio open for calls only; the slab answers, you talk into the knob's own microphone, and the knob holds it back while the other end talks, longer by the speaker's lag.

For other programs, GET /api/phone says what the telephone is doing, and GET /api/phone/history lists the recent calls, and /api/phone/dial?number=…, /answer, /hangup and /dtmf?digits=… act, behind the page's login.

EpiBeam

The EpiBeam firmware (vfo-knob-epibeam, a beta) turns the knob into the beam switch for a phased array, in the setup firmware's colours. The beam goes to EpiCenter, the station's master, which switches the array; this first beta has no link to it yet, and says EpiCenter: not connected. Step by step: the EpiBeam guide.

The array Array on the configuration page: 4 directions (N, E, S, W, a 4-square) or 8 (N, NE, E, SE, S, SW, W, NW). Changing it keeps the beam's heading; from 8 to 4 a corner goes to the direction before it.
The dial A direction a detent, round and round. Once it has rested 0.4 s the direction is taken, and the knob counts it out in strong clicks a quarter of a second apart: N one, on round clockwise, so W is four on a 4-square and NW eight on 8. Turning again stops the count.
The ring The directions round the glass's edge, the beam's lit in gold; a tap on one goes straight to it. In the middle the array, the beam's direction and its heading, and the link to EpiCenter.
The gear A tap: the address card, for the configuration page. Held three seconds: FIRMWARE?, the way back to the setup firmware's list.
Kept The direction, across a restart. No PTT, no swipes, no audio and no Bluetooth: the glass is the beam's.

ADS-B Radar

The ADS-B Radar firmware (vfo-knob-adsb) turns the knob into a radar of the aircraft round you, north up, in the setup firmware's colours. It is after Alex-developer's ADSB-Radar (MIT): the same feeds, fields and colours, on the knob's round glass. Step by step: the ADS-B Radar guide.

Radar On the configuration page: the middle, an airport by its ICAO code or a place in degrees, Brussels Airport until set; the feed — adsb.fi until set, adsb.lol, airplanes.live, or your own readsb, dump1090 or tar1090; the units; every aircraft, military ones or interesting ones; airports, coasts and borders, the sweep, aircraft on the ground; the types to call out; how often to ask.
The dial The range, a detent a range with a click: 5 to 250 NM or miles, 10 to 450 km. Kept, and the feed asked at it, once the dial has rested 0.6 s.
The aircraft Arrows along their track, coloured by altitude, the twelve nearest labelled with their callsign and level where there is room. A tap on one: its card — type, registration, level and rate, speed, track, where it is, its squawk — and its route, from adsbdb.
Alerts An emergency squawk always shows, ringed in red, called out at the top, with a buzz; a type on the list in gold, with a click.
The map Coasts and borders from Natural Earth, airports from OurAirports, both public domain and in the firmware; rings at a quarter, half and three quarters of the range; the sweep.
The gear A tap: the address card, for the configuration page. Held three seconds: FIRMWARE?, the way back to the setup firmware's list.
Kept The settings and the range, across a restart. No PTT, no swipes, no audio and no Bluetooth: the glass is the radar's.

Clock

The Clock firmware (vfo-knob-clock) turns the knob into a clock for the shack, the time from the internet over WiFi, with ten alarms. Its faces are drawn by the knob's own code, after ideas from MilovdZee's Analog_Clock-esp32 and Alan Wang's Saiko watch. Step by step: the Clock guide.

The faces The shack clock: local time on the hands, UTC on a 24-hour ring inside the minutes with its own red hand, the date. The Diver: a bezel, lume, a day-date window, a sweeping second hand. Classic white: a station clock. Digital: the time large, the date, UTC.
The dial A face a detent, round and round; the one it rests on 0.6 s is kept.
The page Under Screen: the time zone (the browser's offered), 24 or 12 hours, the face, the second hand on or off. Under Alarms: the ten alarms, the snooze, how long one rings, whether the motor rings, the sound or both, the sound's volume. Under Bluetooth: a headset or speaker for them.
The alarms Ten, each a time, its days (once, or any days) and on or off; the next on the dial with a bell. A tap on the clock's middle shows them, the dial going from one to the next: a tap on the time sets it with the dial, hours, minutes, days; a tap on ON / OFF switches it. Ringing: the screen lit in a flashing red ring, the motor buzzing, beeps growing louder over 30 s — in a Bluetooth headset or speaker while one is connected, on the jack while none is; the page picks the motor, the sound, or both. A tap stops it, a turn snoozes it, locked or not; left alone it stops.
The time From pool.ntp.org, in UTC; until the first answer no hands and NO TIME YET, and grey once it is a day without one. The face moves a pixel every three minutes, so nothing burns in.
A tap Anywhere but the middle: the address card, for the configuration page. Held three seconds: FIRMWARE?, the way back to the setup firmware's list.
Kept The face and the alarms, across a restart. No screensaver and never dark until set. No PTT, no swipes; nothing on the jack or in Bluetooth but the alarms' beeps.

Weather

The Weather firmware (vfo-knob-weather) turns the knob into a weather station for one place, from Open-Meteo's forecast (CC BY 4.0, free for use that is not commercial, no key). Step by step: the Weather guide.

The place On the configuration page: a town or a city found by its name, a latitude and longitude, or a Maidenhead locator; Brussels until set. The units: °C or °F; km/h, m/s, knots, mph or Beaufort. How often to ask, 10 to 60 minutes, 15 until set. How long a page stays, 5 seconds until set, 0 for only the dial.
Now An icon for the sky, the temperature and what it feels like, the weather in words, the wind with its direction and gusts, humidity and pressure, sunrise and sunset.
The next 24 hours The chance of rain as bars and the temperature as a line, its highest and lowest; when rain is likely.
The next 5 days Each day's sky, highest and lowest, and its chance of rain.
The pages They roll on by themselves, sliding out to the left as the next comes in, every 5 seconds until set; waiting under a screensaver.
The dial A page a detent, round and round, rolling the way it turns; the count starts again; the one it rests on 0.6 s is kept, the one the knob starts on.
When it fails The last forecast is kept, with what went wrong at the foot; after three hours without one, NO FORECAST.
A tap Anywhere: the address card, for the configuration page. Held three seconds: FIRMWARE?, the way back to the setup firmware's list.
Kept The place, the units and the page, across a restart. No screensaver and never dark until set. No PTT, no swipes, no audio and no Bluetooth.

WiFi Test

The WiFi Test firmware (vfo-knob-wifitest) is no radio: it measures the WiFi network the knob is on, for a knob whose links drop. Leave it an hour or more where the links drop, read what it says, and paste its report into a problem report. Step by step: the WiFi Test guide.

The signal In dBm and a word, its last minute a bar a second; the network, its channel, mode and security, the access point and how long the knob has been joined.
The pings The router and up to three hosts (a radio, or the computer it talks to) five times a second, the internet (1.1.1.1) once: the mean answer, the share lost, the answers over 100 ms, the longest silence, the last minute a bar a second. The hosts come from the knob's other firmwares at its first start, and are set on the page.
The drops Each with the reason the access point gave, in words and with what it tends to mean; the roams to another access point, the beacons missed, the router going silent while joined, a new address, a name not found.
The channels The 2.4 GHz networks heard on each channel at its start and every half hour, the knob's own channel and those it overlaps, its own network's access points.
The names DNS asked straight of the network's server each minute, and the hosts' .local names by mDNS.
The verdict At the foot of every page, the worst first: red for what breaks a radio's link (a drop, a very weak signal, the router losing or silent for seconds), amber for what its audio would feel, green for WiFi looks fine.
The page All of it, the hosts to ping, a scan on demand, the counts begun again, and the report as text to copy.
The dial A page a detent: the signal, the pings, the drops, the channels, round and round.
A tap Anywhere: the address card, for the configuration page. Held three seconds: FIRMWARE?, the way back to the setup firmware's list, and from there to the radio's firmware, its settings as they were.
Kept The hosts, across a restart; the counts start again with each start. No screensaver and never dark until set. No PTT, no swipes, no audio and no Bluetooth.

A Bluetooth headset

The board carries an ESP32 beside the ESP32-S3, with the classic Bluetooth the S3 lacks, and a UART between the two. The companion firmware (companion/) makes it a headset's audio gateway, as a phone is: hands-free profile, wideband speech where the headset has it, the audio passed to and from the knob at its own rate. It comes on the second chip, and the knob keeps it up to date by itself, at a quiet moment with no headset or speaker connected; pair the headset on the configuration page, and the knob calls it whenever it is switched on. The page lists the last eight devices connected, and Connect goes over to another with no pairing mode. Step by step: the headset guide.

While a headset is connected its call button is a PTT beside the slab, which keys as always, and the knob unkeys by itself if the headset goes out of reach on the air. A headset or speaker that reports its battery, as most made for iPhones do, has it shown beside its logo on the slab — green, yellow or red — and its charge on the configuration page.

A Bluetooth speaker is the knob's ear only: A2DP, as a phone plays music to it, the knob's audio in both its channels a fifth of a second or so behind the jack. You transmit with the knob's own microphone, as with nothing connected; the speaker falls silent while you do, its buttons key nothing, and a speaker shows at the slab's end in the headset logo's place. One that takes its volume from what plays to it, as most do, has the knob's VOLUME for its own: the knob sets it, and its own volume buttons turn the knob's; one that does not keeps its own, and the knob turns down what it sends. Each speaker, and each headset, has its own Level on the configuration page, how loud the knob sends it its audio: a speaker 12 dB down until it is set. The second chip tells a speaker from a headset by its class and the services it lists, or by its hanging up a call's audio at once, as some speakers that call themselves headsets do; Use as on the configuration page switches it. More: A Bluetooth speaker.

Configuration page

Served on port 80 over whichever interface is up. Status, AetherSDR endpoint, the WiFi networks (up to four), audio levels and the jack's level, the screen's brightness, the screensaver and dimming, which way up it is, the time zone and the clock face, access credentials, firmware updates, and a problem report.

Opened over WiFi, the host field offers a green my IP — the address of the computer you are browsing from, one tap to fill in when that is where AetherSDR runs. Over the cable it is not offered: there the knob finds AetherSDR by itself, and the cable's 10.55.42.2 would mean nothing on WiFi, the only place the host setting is used.

The radio section is a list: up to four radios, each with a name for the dial, and one In use — chosen here for the next start, or with a swipe up on the knob, which restarts into it at once. The UberSDR firmware also moves on to the next in the list by itself when the one in use cannot be reached, and the first that answers is in use from then on. (The reflector firmware keeps its single reflector.) Kiwi888 has its Receivers instead: In use there, or a swipe up on the knob, takes one over at once, with no restart. On the FlexRadio firmware a SmartLink section below it logs in to FlexRadio's service and lists the account's radios, each with Use now — see SmartLink.

With the radio connected, the page opens on its controls instead, in the knob's own colours: the frequency, typed or stepped, band, mode, filter, AGC, the preamp or RF gain, power, the tuner, the squelch where the receiver has one (the IC-R8600, a Kiwi), MAIN/SUB and the antenna, RIT, the web SDR and its balance, and the knob's volume and mic gain — everything the knob can set on the radio, and nothing that transmits. Config leads to the settings above, the radio staying connected.

The same, for other programs — a logbook reading the frequency and mode, or anything setting them with a URL:

GET /api/radio                        the state, as JSON; with no link, why
                                      ("why", as the face says it)
GET /api/radio/set?freq=14074000      Hz, or MHz with a point (14.074)
    ...&mode=usb&filter=2&agc=mid&rfgain=80&power=50&tuner=on&rit=-120
    ...&squelch=30                    0-100 %, 0 open, where the receiver has one
    ...&sdr=0&balance=-30             a web SDR beside the radio, "local" for none;
                                      sdr= chooses it, as a tap on the dial does
GET /api/radios                       the radios the knob knows, and the one in use
POST /api/radios/switch  to=1         another in use: the knob restarts into it
GET /api/status                       the knob itself, its power too: on_usb (null
                                      while it settles), rail_mv, batt (-1 on USB)
GET /api/report                       a problem report, as text: the knob's own
                                      lines, then its log, passwords starred out
GET /api/screenshot                   the face as it is drawn, upright: a 24-bit BMP

A POST with the same fields as a form does the same. Both need the page's login (http://user:password@<knob>/api/radio), and no setting is taken while the radio is on the air. While the password is still admin, over WiFi only GET /api/status, GET /api/config and the POST /api/config that sets a new one (user, webpass) are answered, the rest with 403; over the USB cable all of it, as before.

It is HTTP Basic over plain HTTP. A lock on the door, not a safe — treat the knob as something that belongs on a network you trust.

Report a problem, at the bottom of the page, is for a bug report. Make a report shows what the knob knows of itself: its firmware and build, how long it has been up and what started it (power on, a restart, a crash, a watchdog, a brownout, safe mode), a crash its flash still holds — the task, the address and the backtrace, to decode against that build's ELF — its power, its network and the signal, its link and why it is down, where its settings are kept, its memory, and the second chip's firmware with the headset or speaker on it; then its log, as far back as the knob still holds it (16 kB, from the start where it has not run long). Every password the knob keeps (the page's, the WiFi networks', the radios') is starred out; nothing else is, so the page asks the owner to read it first: the issue is public. Open it on GitHub opens the bug form, its firmware and report fields filled in. A link to GitHub can carry only so much — through GitHub's login, for someone not signed in, about 7 kB once encoded twice — so it holds the knob's lines and the newest of the log that fit, and the whole report goes to the clipboard as it opens, to paste over it; Copy it does that alone.

Updates

Images are RSA-3072 signed and the signature is checked before an update is accepted. Nothing is burned into eFuse and Secure Boot is not enabled, so the board always stays ordinarily flashable — this protects the update path, not the hardware.

  • On WiFi the knob checks by itself — at boot, and every 24 h by default — and asks on the dial: UPDATE x.y.z, tap here to install. A tap on the question installs it and restarts into it; anything else — ten seconds, a turn of the knob, a tap elsewhere — and the question goes away and the dial carries on. It never asks while transmitting, and never installs unasked. A yes given mid-session restarts the knob first and installs at boot, where there is room for it. Set the interval to 0 on the configuration page to stop checking.
  • Over USB the knob has no route to the internet — it is the DHCP server on that link. The configuration page does the checking and the downloading instead, then pushes the image over. Same image, same signature check.
  • The second chip's firmware — the Bluetooth headset's and speaker's — is the one update the knob installs without asking: it never transmits, and the chip checks its signature and falls back to the firmware before by itself. The same check finds a newer release of it, or the SD card has one; the knob fetches it, at its start where it can, and sends it to the chip at a quiet moment, never during an over or a call, nor with a headset or speaker connected. On the USB cable the configuration page hands it over. An interval of 0 stops this look too; a copy on the SD card still goes. See the headset guide.

If an update fails to boot, the bootloader rolls back to the previous slot. The confirmation is tied to the same "this boot looks healthy" timer that clears the boot-loop guard.

The SD card. The knob keeps its firmwares on its microSD card, in one folder, VFO-KNOB (components/sd_cache). Every install takes the image from the card when it holds the one wanted — its sha256 against the manifest, then the signature as for any image — and otherwise downloads it straight in, as without a card, and then keeps a copy on the card. The setup firmware fills the card with every firmware published: those the card has none of before it shows its list, with a screen that counts them (so a knob made with only the setup firmware on it has every one before its owner chooses), and newer versions of the rest while the list is up. With no update server in reach it lists and installs what the card holds; a radio's firmware goes back to the setup firmware from the card without a network. Without a card, everything downloads as before. The second chip's firmware is kept there too, COMPANIO.BIN: a radio's firmware sends it to that chip, never installing it on its own.

The settings on the SD card. Every firmware keeps its settings on the card too, in a folder of their own, VFO-CFG (components/kvstore): held in RAM from boot, written by one task, each namespace three copies (A, B, written in turn and read back, and C ten minutes behind), each a preallocated one-cluster file written in place, so a save never touches the FAT and a power cut never loads a torn copy -- only a whole earlier save (tried with the bench knob's card: a save every few seconds, as in use, survived every cut; written 25 times a second nonstop, the card itself lost its last seconds of saves on two cuts in seven). Only the WiFi networks, the Bluetooth records and the boot counter stay in NVS. Without a card the settings stay in NVS as before. For now the NVS copy of what moved stays in place, frozen: a firmware from before the card still finds its settings, and what it changes there is merged back onto the card at the next start (against a base of what NVS held at the last merge). The page's Settings row and the face's NO SD CARD and SD CARD FAULT say when the card (built in) fails; the page then offers to carry on without it, and to take it again should it answer later.

There is one firmware per radio, vfo-knob-<radio> — vfo-knob-aethersdr, vfo-knob-icom, vfo-knob-openx6x00, vfo-knob-multiflex, vfo-knob-k4, vfo-knob-jupitersdr, vfo-knob-svxconnect, vfo-knob-ubersdr, vfo-knob-kiwi, vfo-knob-owrx, vfo-knob-websdr, vfo-knob-phone, vfo-knob-epibeam, vfo-knob-adsb, vfo-knob-clock, vfo-knob-weather and vfo-knob-wifitest — and each has its own update channel, firmware/<radio>/, so a knob is only ever offered its own releases. It also refuses to install another radio's firmware as an update; switching radios is a deliberate choice under Firmware on the configuration page, or on the dial through the setup firmware, vfo-knob-setup.

Publishing a release: tools/release.sh 1.2.3 --push (another radio's: RADIO=<radio> tools/release.sh …). Each release also rewrites firmware/index.json, the list the setup firmware shows, from the channels' manifests — only the channels tools/release.sh names, and a radio is released only once it is named there; one it also lists under BETA gets "beta": true in its entry, and the setup firmware stamps it BETA on the dial (the configuration page's list says "beta" too); the second chip's sits under a key of its own, never in that list. The second chip's firmware is released only when it changed, in two steps with a bench between them: RADIO=companion tools/release.sh 1.2.3 builds and stages it and says what the bench must show; BENCH_LOG=<the knob's log> RADIO=companion tools/release.sh 1.2.3 --push publishes it once that log has it kept on a second chip and then taking an update itself — a broken one would leave every knob's second chip waiting for a cable.

Building

Needs ESP-IDF 5.5.x.

idf.py -B build_usbnet \
       -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.usbnet" \
       build flash

Leave off sdkconfig.usbnet for a WiFi-only build that keeps the serial console. No credentials are compiled in — a unit ships with empty storage and is configured over the cable.

The IC-705 firmware is WiFi only (the radio is reached over WiFi, and the USB link has no route to it):

idf.py -B build_icom -D VFO_RADIO=icom \
       -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.icom" \
       build flash

So are the openx6x00, jupitersdr, multiflex, svxconnect, ubersdr, kiwi, phone and setup firmwares:

idf.py -B build_openx6x00 -D VFO_RADIO=openx6x00 \
       -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.openx6x00" \
       build flash
idf.py -B build_multiflex -D VFO_RADIO=multiflex \
       -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.multiflex" \
       build flash
idf.py -B build_svxconnect -D VFO_RADIO=svxconnect \
       -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.svxconnect" \
       build flash
idf.py -B build_ubersdr -D VFO_RADIO=ubersdr \
       -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.ubersdr" \
       build flash
idf.py -B build_kiwi -D VFO_RADIO=kiwi \
       -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.kiwi" \
       build flash
idf.py -B build_phone -D VFO_RADIO=phone \
       -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.phone" \
       build flash
idf.py -B build_setup -D VFO_RADIO=setup \
       -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.setup" \
       build flash

Host-side tests (no hardware; of ESP-IDF only its mbedTLS sources, for the TLS runs — found at $IDF_PATH or ~/esp/esp-idf, else those runs are left out):

cmake -S test/host -B build_host && cmake --build build_host && (cd build_host && ctest)

tools/mock_aether.py is a fault-injecting TCI server for exercising the error paths without a radio. --rx-tone 700 answers audio_start with a steady 700 Hz tone as receive audio, to hear the audio path end to end. tools/mock_kiwi.py is a KiwiSDR or a Web-888 that keeps its owner's limits — the day limit at login or mid-session, idle and kick, every answer a login can get and one that comes late, /status with its uptime and clock, with or without its hourglass — plays a tone or a carrier at any of the receivers' audio rates, records every SET it is sent, and counts the logins it refused (--help lists its flags): the kiwi_limits test (ctest -L mock) runs the web SDR's code from components/sdr_rx against it, boot after boot, and kiwi_client_limits the kiwi firmware's receiver from components/kiwi_client — its day limit, a login left unanswered, a switch or a Test in the middle of a login, a full NVS, a restart loop, a KiwiSDR's silent door, the HTTP refusals and every login answer, LISTEN AGAIN, the cap on its own attempts, switching live, the keepalive, the idle acknowledgement only after a touch, the first tune only once the receiver has said where it tunes, CW and an offset, CW where its owner centres it (its load_cfg, read as it goes by: --cw), the S-meter's reference, the pitch at every rate, the receivers' names and the slab from their /status, who their owners see (SET ident_user, decoded by the mock), the noise filter and the squelch, OV — so no real receiver's limits are spent on a test. kiwi_audio (ctest -L mock too) plays that receiver's audio through a ring that runs as audio_out's does: a stall's backlog handed over at once or at any pace, short stalls again and again — the ring kept fuller while they come and eased back once calm, the breaks counted against an older build with --before — a calm stream at its quarter second, the drift trim for five minutes (an hour with --minutes 60), the 30 s report in the log, rej= and the saves at quiet moments. kiwi_two_ears runs both ears at once against two and three mocks: the right ear on the left ear's dial, mode and passband, each ear refusing the other's receiver, a list saved under both, both back after a restart, a day-limit mark shared between them, and never two sessions on one receiver — each ear on an UberSDR's Kiwi input (tools/mock_ubersdr.py, below): the app path's ten-digit stamp, the tune, the AGC and the squelch again once the audio flows, CW where each receiver centres it — the right ear on the left ear's AGC, noise filter and squelch, paced alike, both squelches closed a quiet moment, and a right ear whose receiver does not reach the dial quiet, its session kept, no break, back at once; kiwi_limits the same beside a radio, one out of reach from its login on (S0 back within its range, until its first reading), and the reach in CW at a converter's edges. kiwi_limits, kiwi_client_limits and kiwi_two_ears run again behind TLS (ctest -L tls), every receiver an https:// link: the mock behind a front that ends TLS with a certificate of the run's own CA (--tls); their runs in the clear try TLS itself — an http:// link's redirect followed and kept (--redirect), one elsewhere refused, a certificate the knob refuses, a switch in the middle of a slow handshake (--tls-delay). test_mix_tap checks the mix a Bluetooth headset or speaker takes: a block past full scale brought down whole, never clipped; and test_bt_level the level each one is then sent at, on top of the VOLUME: its steps and defaults, the old fixed quarter's sums matched, and above 0 dB a loud passage turned down smoothly ahead of it, never clipped. test_kiwi_proto checks the protocol's plain-C parts, the ADPCM decoder against kiwiclient's among them and where a receiver centres CW (its load_cfg, read whole or in pieces of any size), and fuzz_kiwi feeds them a million rounds of noise and mangled messages. test_sip sends the phone firmware's SIP (components/phone_client/sip.c), over loopback, what anyone who reaches its port could: a request or a response without one of RFC 3261's five mandatory headers is dropped, and a whole INVITE rings. tools/lvhost renders parts of the face with the knob's own LVGL on the PC: make kiwi-check OUT=dir draws the kiwi face's S-meter in one object with its red peak mark beside the arcs it replaced, pixel by pixel, the readout with OV and the noise filter and squelch editors, and the right ear: its line and reading in blue, RIGHT EAR with the left ear's receiver dimmed, BALANCE, and can't reach where its receiver does not reach the dial; make slab-check the same word on every face with a web SDR — the FlexRadio's, the Icoms', the UberSDR's and Kiwi888's — from ui.c itself.

tools/mock_ubersdr.py is an UberSDR on the LAN, in the clear — its own protocol on 8080 with real Opus, spots, voices and an SSTV gallery, and its Kiwi input on 8073 — with a guest's limits (a session's, an idle one, a day's allowance), a restart, refused sockets, a full receiver, one that vanishes and the bypass password to try; two at once are a list of receivers. make -C tools/uberhost test runs the ubersdr firmware's client and the web SDR's (components/uber_client, components/sdr_rx on the session in components/kiwi_proto) on the PC against it, scenario by scenario — the hand-over to the next receiver too, with names that are never looked up on the network; on the Kiwi input the app path's ten-digit stamp, the passband, the AGC and the squelch asked for again once the audio flows, and CW where each flavour centres it (--kiwi-flavour, --kiwi-cw); and WebSocket frames no server sends — masked, a length that wraps round, 32 MB — each the end of the connection, one merely too big let go by (frames). --host 0.0.0.0 puts it on the LAN for a knob.

tools/mock_flex.py is a FlexRadio — its API on 4992 with memories and a slice's antennas, and its discovery broadcast — that never transmits, and says where the slice would after each command. make -C tools/flexhost test runs the multiflex firmware's client (components/flex_client) on the PC against it; make -C tools/lvhost slab-check the face's slab, its taps and holds, with the glass losing the finger.

The companion firmware for the second chip is its own project (target esp32), reached over the USB-C the other way round. A knob's second chip is set up once by tools/install-setup.sh --second-chip — a bootloader that can go back, the partition table, a first firmware — its headset's pairing kept. After that a build goes on by cable with app-flash and an empty otadata, never a plain flash, which would write the bootloader again:

cd companion && idf.py -B build build
idf.py -B build -p /dev/ttyUSB0 app-flash
esptool.py -p /dev/ttyUSB0 erase_region 0xe000 0x2000

or without a cable, POST /api/bt/update?force=1: see the headset guide.

tools/snap.py takes a screenshot of the face as a PNG, over the serial console of a WiFi-only build (x there); the USB build has no console, so its configuration page serves the same picture at /api/screenshot, as a BMP.

To try the face's touch with nothing keyed, -D VFO_PTT_DRY_RUN=1 builds an image whose PTT taps are only logged, never sent to the radio; its slab reads PTT TEST. Never for a release.

Recovering a knob

Once TinyUSB owns the USB pads there is no serial port, and this board makes that awkward: GPIO0 doubles as the audio mux behind a single button inside the case, and the other Type-C plug orientation reaches the board's second chip, not the ESP32-S3. So the firmware leaves its own way back in.

  • Every boot holds the ROM serial port open for 6 seconds before starting USB networking. idf.py flash catches it.
  • The PHY mux is put back to serial on every startup — it lives in the RTC domain and survives a reset, so without that a crash would come back with no serial port at all.
  • echo reboot | nc 10.55.42.1 3333 restarts it and opens that window. Over the USB cable only: on the WiFi the log port refuses it.
  • Holding a finger on the screen through boot skips USB networking entirely.

Port 3333 is also a log stream — the USB build has no console, so it is the only way to watch a boot.

A new knob

tools/install-setup.sh puts the setup firmware — what every knob ships with — on a knob over its USB-C cable: a new board with Waveshare's demo on it, or any knob to be made new again. It erases the whole flash and writes the latest release's setup firmware (checked against its manifest), with the bootloader and partition table from build_setup/, and a one-time mark that has the setup firmware empty the microSD card as it first starts — the demo's pictures off it, and the settings whoever had the knob before left on it; the mark goes only once the card has been emptied. Only then: no knob ever empties its card by itself. Then every firmware published goes down the cable onto the card (tools/knob-card.py), each kept only with its manifest's sha256, so the new knob installs its radio's in seconds; they are fetched once into ~/.cache/vfo-knob, so a row of knobs downloads them once. The knob restarts when they are on, and shows WIFI SETUP. Then the script asks for the plug to be turned over and writes the second chip, its whole flash erased first: a bootloader that can go back, the partition table and the latest release of its firmware, from the bench files published with that firmware's first release, then reads the chip's console as it starts. --second-chip does only that, on a knob in use, keeping its headset's pairing. It waits for the knob and says what to do: plug it in, or, finding the second chip's CH340 instead of the S3, turn the plug over; it starts as soon as the plug sits right. A knob running the USB-networked AetherSDR firmware is asked to restart and caught in those 6 seconds.

For a row of new knobs, tools/install-setup.sh --line: the firmwares are fetched once, then each knob is provisioned as it is plugged in, and the script asks for the next, until Ctrl-C. Each knob gets a line in ~/.local/share/vfo-knob/provisioned.log: its MAC, the setup firmware, how many firmwares its card took, the second chip's version, ok or FAILED, and how long it took.

Safety

The knob keys a transmitter. Two things are worth knowing:

  • Toggle PTT means the radio stays keyed when you let go. That is why the very loud red screen exists (there is no haptic reminder: on the air the motor would be heard through the microphone), and why the radio's transmit time-out should be set: in AetherSDR, Radio Setup → TX → Timeout. The radio enforces it itself, so it holds even if the knob, the link or the computer does not. The knob no longer keeps a second one.
  • A client that loses power while keyed cannot unkey itself. No firmware on this device can fix that; the server has to notice. Filed upstream as aethersdr#5985. On a FlexRadio the knob as a station of its own is safe from this: the radio stops a station's transmission when it leaves. As the dial for another station it is not — that station is still there — so try it before relying on it: key from the knob, pull its power, and see what the radio does. The radio's transmit time-out is the backstop.

Hardware

Waveshare ESP32-S3-Knob-Touch-LCD-1.8: ESP32-S3 with 16 MB flash and 8 MB PSRAM, 360×360 round SH8601 display, CST816 touch, DRV2605L haptics, PCM5100A DAC and a PDM microphone, and beside the S3 an ESP32-U4WDH (classic Bluetooth, 4 MB flash) behind its own CH340 on the other orientation of the USB-C, joined to the S3 by a UART (S3 GPIO38/48 to its IO18/23). Every GPIO number lives in components/board/board_pins.h.

Licence

Apache-2.0. You may use, modify, sell and ship this firmware, including on hardware you sell, with no obligation to publish your changes. It carries an explicit patent grant. Keep the LICENSE and NOTICE files with any redistribution, and state what you changed.

The display initialisation table in components/panel/sh8601_init_cmds.c comes from Waveshare's demo for this board. Waveshare confirmed on enquiry that their ESP32 demo code is Apache-2.0, so it carries the same terms as the rest and redistributes cleanly. Full list in THIRD_PARTY_LICENSES.

About

VFO via WiFi or USB-C with touchscreen

Resources

Stars

6 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages