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.

For a container installation, select a published version rather than a source checkout. The version-specific image for this release is:

docker pull theboyd78/sdsctl:0.30.0

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.30.0 includes local-date TUI headers/status timestamps, readable Diagnostics connection ages, dashboard theme corrections, and remote TUI continuity while recordings start and stop. It also includes opt-in experimental managed-browser foundations. See the release scope for included changes, acceptance evidence and deferred work.

The transport-aware Raspberry Pi TUI retains observe-only preflight and managed outage waiting/recovery. Scanner model/firmware presentation, ordinary Ingress and manual dashboard login remain separate from experimental browser enrollment. An upgrade does not enable automatic sign-in in existing installations. Secure unattended keyring, abrupt power-loss, cross-build and alternative-engine acceptance are not claimed. The repository App retains its existing option schema; experimental App activation remains an isolated lab workflow, not a production upgrade step. 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.