sdsctl

sdsctl is a Python library and toolkit for controlling and monitoring Uniden SDS100, SDS150, and SDS200 scanners. It provides USB serial control for all three models and native Ethernet control and network audio for the SDS200.

Use it from the command line, a full-screen terminal interface, a responsive web dashboard, Home Assistant, containers, MQTT, or a typed Python API.

[!IMPORTANT] This project is alpha software. The public API may change before version 1.0. It is not affiliated with or endorsed by Uniden.

Start here

Choose the installation that matches where you want to run sdsctl:

The Installation wiki page explains prerequisites, virtual environments, Linux audio packages, Home Assistant, containers, upgrades, and how to verify each target.

Install the Python package

Python 3.11 or newer is required.

Install the base CLI and library:

python -m pip install sds200

Install all optional Python runtime interfaces:

python -m pip install "sds200[all]"

The all extra is exactly the union of tui, web, mqtt, and playback. It does not install operating-system packages, Home Assistant, Docker or Podman, audio servers, or FFmpeg. Linux local playback also needs a working PortAudio runtime; Debian and Raspberry Pi OS users normally install libportaudio2.

Published container users can pull the current exact release image:

docker pull theboyd78/sdsctl:0.29.4

theboyd78/sdsctl:latest follows the newest successfully published release. The repository Compose files remain source-built; see the generic container deployment guide.

First connection

Connect a scanner by USB in serial mode, then run:

sdsctl discover
sdsctl info
sdsctl monitor

Stop the monitor with Ctrl+C.

For an SDS200 on an authorized local network:

sdsctl discover --network 192.168.1.0/24 --network-only
sdsctl --host SCANNER_IP info

Only probe networks you own or are authorized to scan. The First Connection guide covers USB permissions, multiple scanners, stable Linux device paths, SDS200 Ethernet, profiles, expected success, and common failures.

What you can do

• Discover and control supported scanners over USB, plus SDS200 Ethernet
• Monitor structured scanner state and model-aware capabilities
• Use a responsive Textual terminal interface with semantic controls
• Run one daemon-owned scanner, PSI, audio, recording, event, and Waterfall runtime for local or explicitly authenticated private-network CLI/TUI clients
• Use a loopback web dashboard or explicit authenticated native-TLS LAN mode
• Publish bounded MQTT state, events, Home Assistant Discovery, and controls
• Play live SDS200 network audio and create finalized WAV recordings
• Run the Home Assistant App with Ingress, MQTT entities, first-party cards, browser audio, recordings, and an optional media-source integration
• Edit supported Favorites fields through exact review, backup, confirmation, execution, rollback, and readback boundaries
• Review and explicitly adopt supported RadioReference-assisted changes
• Capture and replay sessions for hardware-independent development
• Install and manage modular web, Home Assistant, and TUI themes

The Using sdsctl guide routes each task to its shortest workflow and detailed reference.

Supported scanners

SDS200 USB, Ethernet control, and network audio have been validated on physical firmware 1.26.01. SDS100 core USB behavior has also been hardware-validated on firmware 1.26.01. SDS150 support follows the shared SDS-series remote-command specification and still needs physical-hardware validation. See Supported scanner models for the exact capability and validation matrix.

Interfaces and guides

• Installation and target selection
• First connection
• CLI, TUI, web, daemon, MQTT, controls, and themes
• Audio and recordings
• Home Assistant
• Advanced Home Assistant access
• Managed Raspberry Pi display
• Favorites and RadioReference
• Operations and diagnostics
• Python API
• Troubleshooting

Advanced, version-controlled references remain in the repository:

• Control transports
• Layered configuration
• Daemon deployment
• Authenticated remote daemon clients
• Managed Raspberry Pi TUI display
• Remote daemon container deployment
• Web dashboard
• Network audio
• Home Assistant App
• Advanced Home Assistant App access
• Favorites Workspace
• Capability and field-parity audit

Security and safety

The SDS200 network-control protocol is unauthenticated and unencrypted. Keep it on a trusted LAN or access it through a secured VPN. Do not expose UDP port 50536 directly to the public Internet.

The default web service is loopback-only. Remote LAN access requires the documented authenticated native-TLS mode. Home Assistant uses a separate authenticated Ingress boundary. Reverse-proxy, public, and anonymous exposure are not supported by implication.

Favorites data, RadioReference credentials and payloads, scanner addresses, recordings, captures, Home Assistant capabilities, and diagnostics may be private. Review and sanitize complete artifacts before sharing them.

This project is not a safety-critical or emergency-dispatch system. Do not rely on it as the sole means of receiving urgent communications. Read SECURITY.md for vulnerability reporting and the transport limits before deployment.

Project naming

The product, repository, and executable are named sdsctl. The compatible Python distribution and import package remain named sds200. New Python code should use SDSScanner; the historical SDS200 class name remains an alias.

Development

git clone https://github.com/stevenboyd78/sdsctl.git
cd sdsctl
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev,all]"

See CONTRIBUTING.md for the complete development and test workflow. Hardware-independent tests must not require a physical scanner.

Project status

Version 0.29.4 repairs certificate-verification tests across OpenSSL versions after the partial v0.29.3 release. It retains the transport-aware managed-display security and usability features for public-terminal and browser deployments: an opt-in native display login with separate operator/display credentials, a hardened browser kiosk HTTPS launch flow, and tighter split-screen layout behavior on constrained displays. The /dev/tty1 managed TUI flow keeps observe-only preflight, bounded recovery, private credentials, and exact cleanup while preserving compatibility with existing daemon versions. Unattended browser-device enrollment remains experimental: the packaged production launchers do not enable it. Browser kiosks still require manual sign-in after session expiry or a server restart. See the latest GitHub Release, CHANGELOG.md, ROADMAP.md, and project vision for released changes, ordered work, and deferred product direction.

Acknowledgments

See ACKNOWLEDGMENTS.md.

License

MIT. See LICENSE.