icom-lan 0.3.0

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, power, meters, PTT, CW keying, VFO, split
• 🔍 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
• 🔒 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")

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

# Discover radios on network
icom-lan discover

API Reference

IcomRadio Methods

Method	Description
get_frequency() → int	Current frequency in Hz
set_frequency(hz)	Set frequency
get_mode() → Mode	Current mode
set_mode(mode)	Set mode (enum or string)
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
set_attenuator(on)	Attenuator on/off
set_preamp(level)	Preamp (0/1/2)
send_cw_text(text)	Send CW via built-in keyer
power_control(on)	Remote power on/off
send_civ(cmd, sub, data)	Send raw CI-V command

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) — Opus audio streaming (coming soon)

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

See the protocol documentation for a deep dive.

Testing

# Run all 151 unit tests (no radio required)
pytest tests/test_*.py

# Or with uv
uv run pytest tests/test_*.py

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 🏗️