nerves_network

v0.5.5

nerves_network v0.5.5 Nerves.Network

The Nerves.Network application handles the low level details of connecting to networks. To quickly get started, create a new Nerves project and add the following line someplace early on in your program:

Nerves.Network.setup "wlan0", ssid: "myssid", key_mgmt: :"WPA-PSK", psk: "secretsecret"

To configure multiple wireless networks, nest a list of wireless configurations under the :networks key:

Nerves.Network.setup "wlan0", networks: [
  [ssid: "myssid", key_mgmt: :"WPA-PSK", psk: "secretsecret"],
  [ssid: "myotherssid", key_mgmt: :"WPA-PSK", psk: "othersecret", priority: 10]]

When you boot your Nerves image, Nerves.Network monitors for an interface called “wlan0” to be created. This occurs when you plug in a USB WiFi dongle. If you plug in more than one WiFi dongle, each one will be given a name like “wlan1”, etc. Those may be setup as well.

When not connected, Nerves.Network continually scans for the desired access point. Once found, it associates and runs DHCP to acquire an IP address.

Link to this section Summary

Types

setup_setting()

Settings to setup/2

setup_settings()

Keyword List settings to setup/2

wifi_settings()

WiFi Settings

Functions

scan(ifname)

If ifname is a wireless LAN, scan for access points

set_regulatory_domain(country)

Change the regulatory domain for wireless operations. This must be set to the two character alpha2 code for the country where this device is operating. See the kernel database for the latest database and the frequencies allowed per country

setup(ifname, settings \\ [])

Configure the specified interface

status(ifname)

Convenience function for returning the current status of a network interface from SystemRegistry

teardown(ifname)

Stop all control of ifname

Link to this section Types

Link to this type setup_setting() 
setup_setting() ::
  {:ipv4_address_method, :dhcp | :static | :linklocal}
  | {:ipv4_address, Nerves.Network.Types.ip_address()}
  | {:ipv4_subnet_mask, Nerves.Network.Types.ip_address()}
  | {:domain, String.t()}
  | {:nameservers, [Nerves.Network.Types.ip_address()]}
  | {:networks, [[wifi_settings()]]}
  | wifi_settings()

Settings to setup/2

Link to this type setup_settings() 
setup_settings() :: [setup_setting()]

Keyword List settings to setup/2

Link to this type wifi_settings() 
wifi_settings() ::
  {:ssid, String.t()}
  | {:key_mgmt, :"WPA-PSK" | :NONE}
  | {:psk, String.t()}
  | {:priority, non_neg_integer()}

WiFi Settings

Link to this section Functions

Link to this function scan(ifname) 
scan(Nerves.Network.Types.ifname()) :: [String.t()] | {:error, any()}

If ifname is a wireless LAN, scan for access points.

Link to this function set_regulatory_domain(country) 
set_regulatory_domain(String.t()) :: :ok

Change the regulatory domain for wireless operations. This must be set to the two character alpha2 code for the country where this device is operating. See the kernel database for the latest database and the frequencies allowed per country.

The default is to use the world regulatory domain (00).

You may also configure the regulatory domain in your app’s config/config.exs:

config :nerves_network,
  regulatory_domain: "US"
Link to this function setup(ifname, settings \\ []) 
setup(Nerves.Network.Types.ifname(), setup_settings()) :: :ok

Configure the specified interface.

## Common settings Settings contains one or more of the following IP address settings:

  • :ipv4_address_method - :dhcp, :dhcpd, :static, or :linklocal

  • :ipv4_address - e.g., “192.168.1.5” (specify when :ipv4_address_method = :static)

  • :ipv4_subnet_mask - e.g., “255.255.255.0” (specify when :ipv4_address_method = :static)

  • :domain - e.g., “mycompany.com” (specify when :ipv4_address_method = :static)

  • :nameservers - e.g., [“8.8.8.8”, “8.8.4.4”] (specify when :ipv4_address_method = :static)

    ## WiFi settings

  • networks - a list of one or more network settings. Should contain one or more of the following settings:

    • :ssid - “My WiFi AP” (specify if this is a wireless interface)
    • :key_mgmt - e.g., :"WPA-PSK" or :NONE
    • :psk - e.g., “my-secret-wlan-key”

See t(Elixir.Nerves.Network.setup_setting) for more info.

Link to this function status(ifname) 
status(Nerves.Network.Types.ifname()) ::
  Nerves.NetworkInterface.Worker.status() | nil

Convenience function for returning the current status of a network interface from SystemRegistry.

Link to this function teardown(ifname) 
teardown(Nerves.Network.Types.ifname()) :: :ok

Stop all control of ifname