Skip to content

Types & Enums

Core data types used throughout the library.

StateCache

icom_lan.rigctld.state_cache.StateCache dataclass

Last-known radio state with per-field monotonic timestamps.

Each logical value has a corresponding <field>_ts timestamp (time.monotonic()). A timestamp of 0.0 means the field has never been written.

Attributes:

Name Type Description
freq int

Last-known VFO-A frequency in Hz.
freq_ts float

Monotonic timestamp of the last freq update.
mode str

Last-known mode as a hamlib mode string (e.g. "USB").
filter_width int | None

Last-known IC-7610 filter number (1–3) or None.
mode_ts float

Monotonic timestamp of the last mode update.
vfo str

Current VFO name (always "VFOA" for now).
vfo_ts float

Monotonic timestamp of the last VFO update.
ptt bool

Last-known PTT state.
ptt_ts float

Monotonic timestamp of the last PTT update.
s_meter int | None

Last-known raw S-meter value (0–241) or None.
s_meter_ts float

Monotonic timestamp of the last S-meter update.
rf_power float | None

Last-known normalised RF power (0.0–1.0) or None.
rf_power_ts float

Monotonic timestamp of the last RF-power update.
data_mode bool

Last-known IC-7610 DATA mode state (True = DATA1 active).
data_mode_ts float

Monotonic timestamp of the last data_mode update.

invalidate_data_mode()

Mark DATA mode as stale (forces the next read to hit radio).

invalidate_freq()

Mark the frequency as stale (forces the next read to hit radio).

invalidate_mode()

Mark the mode as stale (forces the next read to hit radio).

invalidate_powerstat()

Mark power status as stale (forces the next read to hit radio).

is_fresh(field, max_age_s)

Return True if field was updated within max_age_s seconds.

Parameters:

Name Type Description Default
field CacheField

Cache field name to check.

 required
max_age_s float

Maximum acceptable age in seconds.

 required

Returns:

Type Description
bool

True when the field has a timestamp and the elapsed time
bool

since that timestamp is strictly less than max_age_s.

snapshot()

Return a dict of current values and their ages in seconds.

Age keys are <field>_age. The age is None if the field has never been written (timestamp is 0.0), otherwise it is a non-negative float.

Returns:

Type Description
dict[str, object]

Dictionary with all cached fields and their ages.

update_af_level(value)

Store a new AF level value and record the current timestamp.

update_alc(value)

Store a new ALC meter value and record the current timestamp.

update_attenuator(value)

Store a new attenuator dB value and record the current timestamp.

update_data_mode(on)

Store a new DATA mode state and record the current timestamp.

update_freq(freq)

Store a new frequency value and record the current timestamp.

update_mode(mode, filter_width)

Store a new mode/filter value and record the current timestamp.

Parameters:

Name Type Description Default
mode str

Hamlib mode string (e.g. "USB", "CW").

 required
filter_width int | None

IC-7610 filter number (1–3) or None.

 required

update_powerstat(on)

Store a new power status and record the current timestamp.

update_preamp(value)

Store a new preamp level and record the current timestamp.

update_ptt(ptt)

Store a new PTT state and record the current timestamp.

update_rf_gain(value)

Store a new RF gain value and record the current timestamp.

update_rf_power(value)

Store a new normalised RF-power value and record the current timestamp.

update_s_meter(value)

Store a new raw S-meter value and record the current timestamp.

update_swr(value)

Store a new SWR meter value and record the current timestamp.

Enums

PacketType

from icom_lan import PacketType

UDP packet type codes from the Icom LAN protocol header (offset 0x04, 2 bytes LE).

Value Name Description
0x00 DATA Data packet (CI-V, audio, etc.)
0x01 CONTROL Control / retransmit request
0x03 ARE_YOU_THERE Discovery request
0x04 I_AM_HERE Discovery response
0x05 DISCONNECT Disconnect notification
0x06 ARE_YOU_READY Ready handshake
0x07 PING Keep-alive ping/pong

Mode

from icom_lan import Mode

Icom CI-V operating modes. Values match the CI-V mode byte.

Value Name Description
0x00 LSB Lower Sideband
0x01 USB Upper Sideband
0x02 AM Amplitude Modulation
0x03 CW Continuous Wave
0x04 RTTY Radio Teletype
0x05 FM Frequency Modulation
0x06 WFM Wide FM
0x07 CW_R CW Reverse
0x08 RTTY_R RTTY Reverse
0x17 DV D-Star Digital Voice

Dataclasses

PacketHeader

from icom_lan import PacketHeader

Fixed 16-byte header present in every Icom LAN UDP packet.

Field Type Description
length int Total packet length (bytes)
type int Packet type code
seq int Sequence number
sender_id int Sender's connection ID
receiver_id int Receiver's connection ID

CivFrame

from icom_lan import CivFrame

Parsed CI-V frame.

Field Type Description
to_addr int Destination CI-V address
from_addr int Source CI-V address
command int CI-V command byte
sub int \| None Sub-command byte (if applicable)
data bytes Payload data

AudioCapabilities

from icom_lan import AudioCapabilities

Stable audio capability structure returned by get_audio_capabilities() (and by IcomRadio.audio_capabilities() for legacy use).

Field Type Description
supported_codecs tuple[AudioCodec, ...] Supported codecs in stable order
supported_sample_rates_hz tuple[int, ...] Supported sample rates
supported_channels tuple[int, ...] Supported channel counts
default_codec AudioCodec Deterministic default codec
default_sample_rate_hz int Deterministic default sample rate
default_channels int Deterministic default channel count

Helper Functions

bcd_encode()

def bcd_encode(freq_hz: int) -> bytes

Encode a frequency (Hz) to Icom's 5-byte BCD format (little-endian BCD).

>>> from icom_lan import bcd_encode
>>> bcd_encode(14074000).hex()
'0040071400'

bcd_decode()

def bcd_decode(data: bytes) -> int

Decode 5-byte BCD to frequency in Hz.

>>> from icom_lan import bcd_decode
>>> bcd_decode(bytes.fromhex('0040071400'))
14074000

get_audio_capabilities()

from icom_lan import get_audio_capabilities

Return the static icom-lan audio capability matrix and deterministic defaults.

Constants

HEADER_SIZE

from icom_lan import HEADER_SIZE  # 16 (0x10)

Size of the fixed packet header in bytes.