icom-lan 0.8.1

Python library for controlling Icom transceivers over LAN (UDP) — no wfview/hamlib required

icom-lan

Python library for controlling Icom transceivers over LAN (UDP).

Direct connection to your radio — no wfview, hamlib, or RS-BA1 required.

Features

• 📡 Direct UDP connection — no intermediate software needed
• 🎛️ Full CI-V command set — frequency, mode, filter, power, meters, PTT, CW keying, VFO, split, ATT, PREAMP
• 🔍 Network discovery — find radios on your LAN automatically
• 💻 CLI tool — icom-lan status, icom-lan freq 14.074m
• ⚡ Async API — built on asyncio for seamless integration
• 🚀 Fast non-audio connect path — CLI/status calls don't block on audio-port negotiation
• 🧠 Commander queue — wfview-style serialized command execution with pacing, retries, and dedupe
• 📊 Scope/waterfall — real-time spectrum data with callback API
• 🌐 Built-in Web UI — spectrum, waterfall, controls, meters, and audio in your browser (icom-lan web):
  • 🎛️ Dual-receiver display — MAIN and SUB receiver state (IC-7610)
  • 📻 Band selector — one-click band buttons (160m–10m)
  • 🔊 Browser audio TX — transmit from your microphone via Opus codec
  • 🎚️ Full control panel — AF/RF/Squelch sliders, NB/NR/DIGI-SEL/IP+ toggles, ATT/Preamp, VFO A/B
  • 📊 Meters — S-meter, SWR (color-coded), ALC, Power, Vd, Id
  • 🔄 Live state sync — HTTP polling at 200ms, no page refresh needed
• 🔌 Hamlib NET rigctld server — drop-in replacement for rigctld, works with WSJT-X, JS8Call, fldigi
• 🎛️ Dual-receiver support — MAIN/SUB via Command29 (IC-7610)
• 🎤 Browser audio TX — transmit from browser microphone
• 📡 UDP relay proxy — remote access via VPN/Tailscale
• 🔒 Zero dependencies — pure Python, stdlib only
• 📝 Type-annotated — full py.typed support

Supported Radios

Radio	Status	CI-V Address
IC-7610	✅ Tested	0x98
IC-705	Should work	0xA4
IC-7300	Should work	0x94
IC-9700	Should work	0xA2
IC-7851	Should work	0x8E
IC-R8600	Should work	0x96

Any Icom radio with LAN/WiFi control should work — the CI-V address is configurable.

Installation

pip install icom-lan

From source:

git clone https://github.com/morozsm/icom-lan.git
cd icom-lan
pip install -e .

Quick Start

Python API

import asyncio
from icom_lan import IcomRadio

async def main():
    async with IcomRadio("192.168.1.100", username="user", password="pass") as radio:
        # Read current state
        freq = await radio.get_frequency()
        mode = await radio.get_mode()
        s = await radio.get_s_meter()
        print(f"{freq/1e6:.3f} MHz  {mode.name}  S={s}")

        # Tune to 20m FT8
        await radio.set_frequency(14_074_000)
        await radio.set_mode("USB")

        # VFO & Split
        await radio.select_vfo("MAIN")
        await radio.set_split_mode(True)

        # CW
        await radio.send_cw_text("CQ CQ DE KN4KYD K")

        # Scope / Waterfall
        def on_frame(frame):
            print(f"{frame.start_freq_hz/1e6:.3f}–{frame.end_freq_hz/1e6:.3f} MHz, {len(frame.pixels)} px")
        radio.on_scope_data(on_frame)
        await radio.enable_scope()

asyncio.run(main())

CLI

# Set credentials via environment
export ICOM_HOST=192.168.1.100
export ICOM_USER=myuser
export ICOM_PASS=mypass

# Radio status
icom-lan status

# Frequency (multiple input formats)
icom-lan freq             # Get
icom-lan freq 14.074m     # Set (MHz)
icom-lan freq 7074k       # Set (kHz)
icom-lan freq 14074000    # Set (Hz)

# Mode
icom-lan mode USB

# Meters (JSON output)
icom-lan meter --json

# CW keying
icom-lan cw "CQ CQ DE KN4KYD K"

# PTT
icom-lan ptt on
icom-lan ptt off

# Attenuator & Preamp (Command29-aware for IC-7610)
icom-lan att              # Get attenuation level
icom-lan att 18           # Set 18 dB
icom-lan preamp           # Get preamp level
icom-lan preamp 1         # Set PREAMP 1

# Scope / Waterfall snapshot (requires: pip install icom-lan[scope])
icom-lan scope                      # Combined spectrum + waterfall → scope.png
icom-lan scope --spectrum-only      # Spectrum only (1 frame)
icom-lan scope --theme grayscale    # Grayscale theme
icom-lan scope --json               # Raw data as JSON (no Pillow needed)

# Example output
![Scope + waterfall example](docs/assets/scope-example.png)

# Remote power on/off
icom-lan power-on
icom-lan power-off

# UDP relay proxy (for VPN/Tailscale remote access)
icom-lan proxy --remote-host 192.168.55.40 --listen-port 50001

# Discover radios on network
icom-lan discover

# Built-in Web UI (spectrum, waterfall, controls, audio)
icom-lan web                            # Start on 0.0.0.0:8080
icom-lan web --port 9090                # Custom port
# Then open http://your-ip:8080 in a browser

# Hamlib NET rigctld-compatible server (use with WSJT-X, JS8Call, fldigi)
icom-lan serve                          # Listen on 0.0.0.0:4532
icom-lan serve --port 4532 --read-only  # Read-only mode (no TX control)
icom-lan serve --max-clients 5          # Limit concurrent clients
icom-lan serve --wsjtx-compat           # Pre-warm DATA mode for WSJT-X CAT/PTT flow

# Then in WSJT-X: Rig → Hamlib NET rigctl, Address: localhost, Port: 4532
# Or test with: rigctl -m 2 -r localhost:4532 f
# Note: --wsjtx-compat enables DATA mode automatically on first client
# when radio is in USB/LSB/RTTY with DATA off (opt-in behavior).

API Reference

IcomRadio Methods

Method	Description
get_frequency() → int	Current frequency in Hz
set_frequency(hz)	Set frequency
get_mode() → Mode	Current mode
get_mode_info() → (Mode, filter)	Current mode + filter number (if reported)
set_mode(mode, filter_width=None)	Set mode (optionally with filter 1-3)
get_filter() / set_filter(n)	Read/set filter number
get_power() → int	RF power level (0–255)
set_power(level)	Set RF power
get_s_meter() → int	S-meter (0–255)
get_swr() → int	SWR meter (0–255, TX only)
get_alc() → int	ALC meter (0–255, TX only)
set_ptt(on)	Push-to-talk on/off
select_vfo(vfo)	Select VFO (A/B/MAIN/SUB)
set_split_mode(on)	Split on/off
get_attenuator_level(receiver) → int	Read attenuator in dB (Command29)
set_attenuator_level(db, receiver)	Set attenuator dB (0–45, 3 dB steps)
get_preamp(receiver) → int	Read preamp level (Command29)
set_preamp(level, receiver)	Set preamp (0=off, 1=PRE1, 2=PRE2)
on_scope_data(callback)	Register callback for scope/waterfall frames
enable_scope(output=True)	Enable scope display + data output
disable_scope()	Disable scope data output
send_cw_text(text) / stop_cw_text()	Send/stop CW via built-in keyer
power_control(on)	Remote power on/off
snapshot_state() / restore_state(state)	Best-effort state save/restore
send_civ(cmd, sub, data)	Send raw CI-V command
get_nb(receiver) / set_nb(on, receiver)	Noise Blanker on/off (Command29)
get_nr(receiver) / set_nr(on, receiver)	Noise Reduction on/off (Command29)
get_digisel(receiver) / set_digisel(on, receiver)	DIGI-SEL on/off (Command29)
get_ip_plus(receiver) / set_ip_plus(on, receiver)	IP+ on/off (Command29)
get_data_mode() / set_data_mode(on)	DATA mode on/off
get_af_level(receiver) / set_af_level(level, receiver)	AF gain level (0-255, Command29)
get_rf_gain(receiver) / set_rf_gain(level, receiver)	RF gain level (0-255, Command29)
set_squelch(level, receiver)	Squelch level (0-255, Command29)
start_audio_rx() / stop_audio_rx()	Start/stop RX audio stream
start_audio_tx() / stop_audio_tx()	Start/stop TX audio stream
push_audio_tx_opus(data)	Push Opus audio frames for TX
vfo_exchange()	Exchange VFO A↔B frequencies
vfo_equalize()	Copy active VFO to inactive

HTTP Endpoints

Endpoint	Description
GET /api/v1/state	HTTP endpoint: dual-receiver state JSON (MAIN+SUB)

Configuration

Parameter	Default	Env Var	Description
host	—	ICOM_HOST	Radio IP address
port	50001	ICOM_PORT	Control port
username	""	ICOM_USER	Auth username
password	""	ICOM_PASS	Auth password
radio_addr	0x98	—	CI-V address
timeout	5.0	—	Timeout (seconds)

How It Works

The library implements the Icom proprietary LAN protocol:

1. Control port (50001) — UDP handshake, authentication, session management
2. CI-V port (50002) — CI-V command exchange
3. Audio port (50003) — RX/TX audio streaming (including full-duplex orchestration)

Discovery → Login → Token → Conninfo → CI-V Open → Commands

See the protocol documentation for a deep dive.

Testing

# Unit tests (no radio required) — 1265 tests
pytest tests/test_*.py

# Mock integration tests (full UDP protocol, no radio required)
pytest tests/test_mock_integration.py

# Integration tests (real radio required)
export ICOM_HOST=192.168.55.40
export ICOM_USER=your_username
export ICOM_PASS=your_password
pytest -m integration tests/integration

# Guarded power-cycle test (will actually power off/on radio)
export ICOM_ALLOW_POWER_CONTROL=1
pytest -m integration tests/integration/test_radio_integration.py::TestPowerHardware::test_power_cycle_roundtrip -q -s

# Soak test (seconds)
export ICOM_SOAK_SECONDS=120
pytest -m integration tests/integration/test_radio_integration.py::TestSoak::test_soak_retries_and_logging -q -s

Documentation

📖 Full documentation: morozsm.github.io/icom-lan

• Getting Started
• CLI Reference
• API Reference
• Protocol Internals
• Security

Security

• Zero external dependencies — minimal attack surface
• Credentials passed via env vars or parameters, never stored
• The Icom protocol uses UDP without encryption — see SECURITY.md

License

MIT — see LICENSE.

Protocol knowledge based on wfview (GPLv3) reverse engineering. This is an independent clean-room implementation, not a derivative work.

Acknowledgments

• The wfview project for their extensive reverse engineering of the Icom LAN protocol
• The amateur radio community for testing and feedback

Trademark Notice

Icom™ and the Icom logo are registered trademarks of Icom Incorporated. This project is not affiliated with, endorsed by, or sponsored by Icom. Product names are used solely for identification and compatibility purposes (nominative fair use).

---

73 de KN4KYD 🏗️