HBlink3-WebUI

English | 简体中文

An embedded web console for HBlink3, the open-source HomeBrew Protocol DMR master.

The console runs inside the HBlink3 process, mounted on the same Twisted reactor that carries DMR traffic. It reads the live state of the running systems directly, so it needs no extra dependencies, no second process and no IPC, and it works even on a host with nothing else installed.

The current version is VERSION in webui.py; it is logged at startup and shown in the page footer and in /api/snapshot.

Features

• Live dashboard -- systems, online peers, uptime, pushed to the browser over Server-Sent Events.
• Peer table -- callsign, radio ID, connection state, arrival time, duration, last ping, location and host software for every connected repeater.
• Call table -- transmissions from the last 24 hours (configurable): time, timeslot, call type, voice or data, source, target talkgroup or radio, which peer it came through, duration, frame count and lost frames measured from DMRD sequence gaps. Text messages and other UDT traffic are recorded alongside voice, and standalone CSBK frames are listed as signalling events that can be hidden with a toggle.
• Log viewer -- tail of the HBlink log, with severity and level shown.
• Graphical configuration editor -- edit every field the configuration parser actually reads, with per-field validation, atomic writes and an automatic hblink.cfg.bak backup. Add and remove system sections (MASTER / PEER / XLXPEER / OPENBRIDGE) from preset templates.
• HTTP basic auth on every page and endpoint.
• No dependencies beyond Twisted, which HBlink3 already requires.

Requirements

• Linux with systemd (for the supplied unit; the console itself does not need it)
• Python 3.7 or newer
• Twisted, bitstring, bitarray, dmr_utils3 -- see requirements.txt

Install

git clone https://github.com/<you>/HBlink3-WebUI.git
cd HBlink3-WebUI
sudo ./install.sh

The installer checks the Python dependencies, copies the tree to /opt/HBlink3-webui, generates a random console password, writes and enables a systemd unit with Restart=always, starts the service and prints the URL and credentials.

By default the console binds to 127.0.0.1 and is only reachable from the machine itself. To expose it, run sudo ./install.sh --expose -- and read the security section below first.

sudo ./install.sh                 # localhost only
sudo ./install.sh --expose        # reachable from the network
sudo ./install.sh --port 8080     # different console port
sudo ./install.sh --prefix /opt/x # different install location
sudo ./install.sh --no-start      # install without starting

Re-running the installer upgrades the code in place. An existing hblink.cfg is left untouched, so it doubles as the update path.

Configuration

The installer creates hblink.cfg from hblink.cfg.example on a fresh install; the real hblink.cfg is gitignored so live credentials never end up in the repository. Everything lives in the [WEBUI] section:

[WEBUI]
ENABLED: True
IP: 127.0.0.1
PORT: 60808
USER: admin
PASSWORD: change-me
REFRESH: 5
ALLOW_EDIT: False
ALLOW_RESTART: False
CALL_HOURS: 24

Key	Meaning
ENABLED	start the console at all
IP	interface to bind. 127.0.0.1 keeps it local, 0.0.0.0 exposes it
PORT	console port
USER / PASSWORD	HTTP basic auth. An empty PASSWORD disables auth
REFRESH	seconds between live state pushes
ALLOW_EDIT	let the console rewrite hblink.cfg from the browser
ALLOW_RESTART	let the console stop the process, so systemd restarts it
CALL_HOURS	how long finished calls stay in the call table, in hours

Removing the whole [WEBUI] section disables the console; the configuration parser fills in safe defaults, so an existing hblink.cfg without the section keeps working unchanged.

Security

The console is a DMR master's control panel. Treat it accordingly:

• Basic auth over plain HTTP sends the password in the clear. Put it behind TLS (nginx, Caddy) or restrict it to trusted addresses before exposing it.
• With ALLOW_EDIT: True, anyone who can reach the port and log in can rewrite hblink.cfg -- including the master's passphrase and ACLs. The console warns on every page while it is reachable from the network with editing enabled.
• ALLOW_RESTART is only meaningful when something like systemd is configured to start the process again; the supplied unit does that.
• Every save is validated field by field, written atomically, re-parsed before it replaces the original, and preceded by a hblink.cfg.bak backup. A save that would put two enabled systems on the same port is refused, because that would stop HBlink from starting.

What a master cannot do

Two things hotspot dashboards show are simply not available at a master:

• Bit error rate. BER is measured on the RF side by the repeater or hotspot and is not carried in the HomeBrew Protocol. A master never sees it.
• Audio. DMR voice is AMBE+2, which needs a DVSI vocoder or licensed software to encode or decode. This project ships no codec -- voice_lib.py holds a fixed table of pre-encoded words and mk_voice.py packs those into a transmission, which is the only way it can originate speech.

Updating

git pull
sudo ./install.sh

deploy.sh does the same sync without touching systemd, which is handy while working on the code:

./deploy.sh --check     # report whether a live install differs from this tree
./deploy.sh --restart   # copy the tree in and restart the service

API

The console exposes a JSON API for every view; see API.md or API.zh-CN.md.

Changelog

See CHANGELOG.md.

Credits and licence

This is a modified fork of HBlink3 by Cortney T. Buffington, N0MJS, and the K0USY Group, and it remains under the GNU General Public License v3 -- see LICENSE.txt.

Files changed relative to upstream HBlink3:

• webui.py, webui_static/ -- new, the embedded console
• hblink.py -- console mount point, detailed peer session logging, call logging and the call history that feeds the call table
• config.py -- parses the [WEBUI] section
• hblink.cfg, hblink-SAMPLE.cfg, README.md -- documentation and defaults

The HomeBrew Repeater Protocol is the work of Jonathan Naylor G4KLX, Hans Barthen DL5DI and Torsten Shulze DG1HT; this implementation is based on their 2015-07-26 specification.