Hamlib.Rig (hamlib_ex v0.1.0)

Copy Markdown View Source

A process-owned Hamlib rig.

Wraps a Hamlib.Nif handle in a GenServer so that:

  • one process owns the serial line (single controlling process — the right model for a UART, and what a consuming app's rig-control layer wants),
  • commands are serialized (no two callers driving the rig at once),
  • the port is opened on start and closed/cleaned up on terminate.

Starting

{:ok, rig} =
  Hamlib.Rig.start_link(
    model: Hamlib.model(:dummy),
    conf: %{}              # config tokens applied before open
  )

For a real serial rig:

{:ok, rig} =
  Hamlib.Rig.start_link(
    model: 3073,           # e.g. an Icom CI-V model number
    conf: %{
      "rig_pathname" => "/dev/tty.usbserial-XXXX",
      "serial_speed" => "19200",
      "ptt_type"     => "RTS"
    }
  )

For NET rigctl (talk to an external rigctld):

{:ok, rig} =
  Hamlib.Rig.start_link(
    model: Hamlib.model(:netrigctl),
    conf: %{"rig_pathname" => "127.0.0.1:4532"}
  )

Android / DigiRig note

On Android there is no /dev/tty* for USB serial; the serial path Hamlib expects must be bridged to the Android USB host API. That bridge is tracked separately; the API here is identical regardless of how the bytes reach the radio.

Summary

Types

option()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

close(server)

Close the rig port (rig stays initialized; reopen with open/1).

get_freq(server)

Get frequency in Hz from the current VFO. {:ok, hz}.

get_mode(server)

Get current {mode_string, passband_hz}.

get_ptt(server)

Get PTT state as a boolean. {:ok, true|false}.

open(server)

Open the rig port (if started with open: false, or after close/1).

set_freq(server, freq_hz)

Set frequency in Hz on the current VFO.

set_mode(server, mode, passband_hz \\ 0)

Set mode by string ("USB", "PKTUSB", …) and passband Hz (0 = normal).

set_ptt(server, on)

Key/unkey the transmitter. true = TX, false = RX.

start_link(opts)

Start a rig process. Options

Types

option()

@type option() ::
  {:model, integer()}
  | {:conf, %{optional(String.t()) => String.t()}}
  | {:name, GenServer.name()}
  | {:open, boolean()}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

close(server)

@spec close(GenServer.server()) :: :ok | {:error, term()}

Close the rig port (rig stays initialized; reopen with open/1).

get_freq(server)

@spec get_freq(GenServer.server()) :: {:ok, float()} | {:error, term()}

Get frequency in Hz from the current VFO. {:ok, hz}.

get_mode(server)

@spec get_mode(GenServer.server()) ::
  {:ok, {String.t(), integer()}} | {:error, term()}

Get current {mode_string, passband_hz}.

get_ptt(server)

@spec get_ptt(GenServer.server()) :: {:ok, boolean()} | {:error, term()}

Get PTT state as a boolean. {:ok, true|false}.

open(server)

@spec open(GenServer.server()) :: :ok | {:error, term()}

Open the rig port (if started with open: false, or after close/1).

set_freq(server, freq_hz)

@spec set_freq(GenServer.server(), number()) :: :ok | {:error, term()}

Set frequency in Hz on the current VFO.

set_mode(server, mode, passband_hz \\ 0)

@spec set_mode(GenServer.server(), String.t(), integer()) :: :ok | {:error, term()}

Set mode by string ("USB", "PKTUSB", …) and passband Hz (0 = normal).

set_ptt(server, on)

@spec set_ptt(GenServer.server(), boolean()) :: :ok | {:error, term()}

Key/unkey the transmitter. true = TX, false = RX.

start_link(opts)

@spec start_link([option()]) :: GenServer.on_start()

Start a rig process. Options:

  • :model (required) — Hamlib model number (see Hamlib.model/1).
  • :conf — map of Hamlib config tokens applied before opening the port.
  • :open — open the port on start (default true). false leaves the rig initialized + configured but closed, to open later with open/1.
  • :name — optional GenServer name.