@spec device_count() :: non_neg_integer()

Number of devices running under the device supervisor.

@spec list_devices() :: [device_info()]

Lists the devices running under the device supervisor.

Each entry has :pid, :device_id, :device_type and :port; the last three are nil if a device did not answer its info call in time.

@spec load_config(Path.t()) :: {:ok, map()} | {:error, term()}

Loads a configuration file. .json files are decoded with Jason; .yaml / .yml files require the optional yaml_elixir dependency.

A complete example configuration, useful as a starting point.

@spec start(config()) :: {:ok, pid()} | {:error, term()}

Starts every device group in config under the device supervisor.

config is a configuration map (with or without the top-level :snmp_sim key) or the path of a JSON / YAML file. Returns {:ok, supervisor_pid}; the started devices are available through list_devices/0.

@spec start_device(
  map(),
  keyword()
) :: GenServer.on_start()

Starts one device from a SnmpKit.SnmpSim.ProfileLoader profile.

Options: :port (required), :device_id (default "<type>_<port>"), :community (default "public"), :bind_address (default all IPv4 interfaces; an IPv6 address such as "::1" binds an IPv6 socket), :v3_users (a list of %{name:, auth:, auth_password:, priv:, priv_password:} maps that enables SNMPv3, see SnmpKit.SnmpSim.Core.UsmAgent), :engine_id, :seed (an integer that makes the device's error injection reproducible, see SnmpKit.SnmpSim.Device) and :mac_address. The device is linked to the caller.

{:ok, profile} = SnmpKit.SnmpSim.ProfileLoader.load_profile(:cable_modem, {:walk_file, "priv/walks/cable_modem.walk"})
{:ok, device} = SnmpKit.SnmpSim.start_device(profile, port: 9001)

A bare %{objects: %{oid => value}} map (OID keys as strings or lists) is accepted in place of a profile.

Starts a population of devices with mixed types through SnmpKit.SnmpSim.LazyDevicePool.

Devices are pre-warmed unless pre_warm: false is given and run under the device supervisor (stop them with stop_device/1 or stop/0). Returns {:ok, [%{type, port, pid, target}]}. A list of explicit %{type:, port:, community:} maps is also accepted, one device each.

{:ok, devices} = SnmpKit.SnmpSim.start_device_population(
  [
    {:cable_modem, {:walk_file, "priv/walks/cable_modem.walk"}, count: 1000},
    {:switch, {:walk_file, "priv/walks/switch.walk"}, count: 50}
  ],
  port_range: 30_000..39_999
)

@spec start_link(config()) :: {:ok, pid()} | {:error, term()}

Same as start/1.

The name is kept for compatibility with the original draft of this module. Note that the devices are supervised by the application, not linked to the caller, so this is safe to call from any process.

@spec stop() :: :ok

Stops every device running under the device supervisor.

@spec stop_device(pid() | non_neg_integer()) :: :ok | {:error, :not_found}

Stops one device, given its pid or its UDP port.

@spec supervisor() :: {:ok, pid()} | {:error, :not_started}

The device supervisor pid, or {:error, :not_started} if the application is not running.

@spec validate_config(map()) :: :ok | {:error, term()}

Validates a configuration map without starting anything.

Writes sample_config/0 to path as :json or :yaml.