vintage_net

v0.3.0

vintage_net v0.3.0 VintageNet View Source

VintageNet is network configuration library built specifically for Nerves Project devices. It has the following features:

  • Ethernet and WiFi support included. Extendible to other technologies
  • Default configurations specified in your Application config
  • Runtime updates to configurations are persisted and applied on next boot (can be disabled)
  • Simple subscription to network status change events
  • Connect to multiple networks at a time and prioritize which interfaces are used (Ethernet over WiFi over cellular)
  • Internet connection monitoring and failure detection (currently slow and simplistic)

See github.com/nerves-networking/vintage_net for more information.

Link to this section Summary

Types

ifname()

A name for the network interface

Functions

all_interfaces()

Return a list of all interfaces on the system

configuration_valid?(ifname, config)

Check if this is a valid configuration

configure(ifname, config)

Update the settings for the specified interface

configured_interfaces()

Return a list of configured interface

get(name, default \\ nil)

Get the current value of a network property

get_by_prefix(prefix)

Get a list of all properties matching the specified prefix

get_configuration(ifname)

Return the settings for the specified interface

info()

Print the current network status

ioctl(ifname, command, args \\ [])

Run a command on a network interface

scan(ifname)

Initiate an access point scan on a wireless interface

subscribe(name)

Subscribe to receive property change messages

unsubscribe(name)

Stop subscribing to property change messages

verify_system(opts \\ nil)

Check that the system has the required programs installed

Link to this section Types

Link to this type

ifname() View Source 
ifname() :: String.t()

A name for the network interface

Names depend on the device drivers and any software that may rename them. Typical names on Nerves are:

  • "eth0", "eth1", etc. for wired Ethernet interfaces
  • "wlan0", etc. for WiFi interfaces
  • "ppp0" for cellular modems
  • "usb0" for gadget USB virtual Ethernet interfaces

Link to this section Functions

Link to this function

all_interfaces() View Source 
all_interfaces() :: [ifname()]

Return a list of all interfaces on the system

Link to this function

configuration_valid?(ifname, config) View Source 
configuration_valid?(ifname(), map()) :: boolean()

Check if this is a valid configuration

This runs the validation routines for a settings map, but doesn't try to apply them.

Link to this function

configure(ifname, config) View Source 
configure(ifname(), map()) :: :ok | {:error, any()}

Update the settings for the specified interface

Link to this function

configured_interfaces() View Source 
configured_interfaces() :: [ifname()]

Return a list of configured interface

Link to this function

get(name, default \\ nil) View Source 
get(VintageNet.PropertyTable.property(), VintageNet.PropertyTable.value()) ::
  VintageNet.PropertyTable.value()

Get the current value of a network property

See get_by_prefix/1 to get some or all properties.

Link to this function

get_by_prefix(prefix) View Source 
get_by_prefix(VintageNet.PropertyTable.property()) :: [
  {VintageNet.PropertyTable.property(), VintageNet.PropertyTable.value()}
]

Get a list of all properties matching the specified prefix

To get a list of all known properties and their values, call VintageNet.get_by_prefix([])

Link to this function

get_configuration(ifname) View Source 
get_configuration(ifname()) :: map()

Return the settings for the specified interface

Link to this function

info() View Source 
info() :: :ok

Print the current network status

Link to this function

ioctl(ifname, command, args \\ []) View Source 
ioctl(ifname(), atom(), any()) :: :ok | {:ok, any()} | {:error, any()}

Run a command on a network interface

Commands are mostly network interface-specific. Also see the VintageNet PropertyTable fo getting status or registering for status changes.

Link to this function

scan(ifname) View Source 
scan(ifname()) :: :ok | {:error, any()}

Initiate an access point scan on a wireless interface

The scan results are posted asynchronously to the ["interfaces", ifname, "access_points"] property as they come in. It appears that there's some variation in how scanning is implemented on WiFi adapters. One strategy that seems to work is to call scan/1 every 10 seconds or so while prompting a user to pick a WiFi network.

This is a utility function for calling the :scan ioctl.

Link to this function

subscribe(name) View Source 
subscribe(VintageNet.PropertyTable.property()) :: :ok

Subscribe to receive property change messages

Messages have the form:

{VintageNet, property_name, old_value, new_value, metadata}
Link to this function

unsubscribe(name) View Source 
unsubscribe(VintageNet.PropertyTable.property()) :: :ok

Stop subscribing to property change messages

Link to this function

verify_system(opts \\ nil) View Source 
verify_system(keyword() | nil) :: :ok | {:error, String.t()}

Check that the system has the required programs installed

NOTE: This isn't completely implemented yet!