Module network

Data Types
Function Index
Function Details

Data Types

ap_channel_cfg()


ap_channel_cfg() = {ap_channel, wifi_channel()}

ap_config()


ap_config() = {ap, [ap_config_property()]}

ap_config_property()


ap_config_property() = ssid_config() | psk_config() | ap_channel_cfg() | ap_ssid_hidden_config() | ap_max_connections_config() | ap_started_config() | ap_sta_connected_config() | ap_sta_disconnected_config() | ap_sta_ip_assigned_config()

ap_max_connections_config()


ap_max_connections_config() = {ap_max_connections, non_neg_integer()}

ap_ssid_hidden_config()


ap_ssid_hidden_config() = {ap_ssid_hidden, boolean()}

ap_sta_connected_config()


ap_sta_connected_config() = {sta_connected, fun((mac()) -> term())}

ap_sta_disconnected_config()


ap_sta_disconnected_config() = {sta_disconnected, fun((mac()) -> term())}

ap_sta_ip_assigned_config()


ap_sta_ip_assigned_config() = {sta_ip_assigned, fun((inet:ip4_address()) -> term())}

ap_started_config()


ap_started_config() = {ap_started, fun(() -> term())}

app_managed_config()


app_managed_config() = managed | {managed, boolean()}

Setting {managed, true} or including the atom managed in the sta_config() will signal to the driver that sta mode connections are managed in the user application, allowing to start the driver in STA (or AP+STA) mode, configuring ssid and psk if provided, but not immediately connecting to the access point. If ssid and psk are provided in managed mode, this configuration will be used when starting a connection using sta_connect/0. When using this mode of operation applications will likely need to provide an sta_disconnected_config() to replace the default callback (which attempts to reconnect to the last network) and instead scan for available networks, or use some other means of determining when, and which network to connect to.

db()


db() = integer()

dhcp_hostname_config()


dhcp_hostname_config() = {dhcp_hostname, string() | binary()}

ghz24_channel()


ghz24_channel() = 1..14

This is the global 2.4 Ghz WiFI channel range, check your local jurisdiction for allowed channels in your geographic region.

ghz5_160mhz_channel()


ghz5_160mhz_channel() = 50 | 82 | 114 | 163

This is the global 5 Ghz WiFI channel range when using 160Mhz bandwidth channels, check your local jurisdiction for allowed channels in your geographic region.

ghz5_20mhz_channel()


ghz5_20mhz_channel() = 32 | 36 | 40 | 44 | 48 | 52 | 56 | 60 | 64 | 68 | 96 | 104 | 108 | 112 | 116 | 120 | 122 | 128 | 132 | 136 | 140 | 144 | 149 | 153 | 157 | 161 | 165 | 169 | 173 | 177

This is the global 5 Ghz WiFI channel range when using 20Mhz bandwidth channels, check your local jurisdiction for allowed channels in your geographic region.

ghz5_40mhz_channel()


ghz5_40mhz_channel() = 38 | 46 | 54 | 62 | 102 | 110 | 118 | 126 | 134 | 142 | 151 | 159 | 167 | 175

This is the global 5 Ghz WiFI channel range when using 40Mhz bandwidth channels, check your local jurisdiction for allowed channels in your geographic region.

ghz5_80mhz_channel()


ghz5_80mhz_channel() = 42 | 58 | 74 | 90 | 106 | 122 | 138 | 155 | 171

This is the global 5 Ghz WiFI channel range when using 80Mhz bandwidth channels, check your local jurisdiction for allowed channels in your geographic region.

ip_info()


ip_info() = ipv4_info()

ipv4_info()


ipv4_info() = {IPAddress::inet:ip4_address(), NetMask::inet:ip4_address(), Gateway::inet:ip4_address()}

mac()


mac() = binary()

mdns_config()


mdns_config() = {mdns, [mdns_config_property()]}

mdns_config_property()


mdns_config_property() = mdns_hostname_config() | mdns_ttl_config()

mdns_hostname_config()


mdns_hostname_config() = {host, string() | binary()}

mdns_ttl_config()


mdns_ttl_config() = {ttl, pos_integer()}

network_config()


network_config() = [sta_config() | ap_config() | sntp_config() | mdns_config()]

psk_config()


psk_config() = {psk, string() | binary()}

sntp_config()


sntp_config() = {sntp, [sntp_config_property()]}

sntp_config_property()


sntp_config_property() = sntp_host_config() | sntp_synchronized_config()

sntp_host_config()


sntp_host_config() = {host, string() | binary()}

sntp_synchronized_config()


sntp_synchronized_config() = {synchronized, fun(({non_neg_integer(), non_neg_integer()}) -> term())}

ssid_config()


ssid_config() = {ssid, string() | binary()}

sta_beacon_timeout_config()


sta_beacon_timeout_config() = {beacon_timeout, fun(() -> term())}

sta_config()


sta_config() = {sta, [sta_config_property()]}

sta_config_property()


sta_config_property() = app_managed_config() | ssid_config() | psk_config() | dhcp_hostname_config() | sta_connected_config() | sta_beacon_timeout_config() | sta_disconnected_config() | sta_got_ip_config()

sta_connected_config()


sta_connected_config() = {connected, fun(() -> term())}

sta_disconnected_config()


sta_disconnected_config() = {disconnected, fun(() -> term())}

If no callback is configured the default behavior when the connection to an access point is lost is to attempt to reconnect. If a callback is provided these automatic re-connections will no longer occur, and the application must use network:sta_connect/0 to reconnect to the last access point, or use network:sta_connect/1 to connect to a new access point in a manner determined by the application.

sta_got_ip_config()


sta_got_ip_config() = {got_ip, fun((ip_info()) -> term())}

sta_status()


sta_status() = associated | connected | connecting | degraded | disconnected | disconnecting | inactive

wifi_channel()


wifi_channel() = ghz24_channel() | ghz5_20mhz_channel() | ghz5_40mhz_channel() | ghz5_80mhz_channel() | ghz5_160mhz_channel()

Function Index

sta_connect/0	Connect to an access point after a network disconnection.
sta_connect/1	Connect to a new access point after the network driver has been started.
sta_disconnect/0	Disconnect from access point.
sta_rssi/0	Get the rssi information of AP to which the device is associated with.
sta_status/0	Get the connection status of the sta interface.
start/1	Start a network interface.
start_link/1
stop/0	Stop a network interface.
wait_for_ap/0	Equivalent to wait_for_ap(15000).
wait_for_ap/1	Equivalent to wait_for_ap([], Timeout) or wait_for_ap(StaConfig, 15000).
wait_for_ap/2	Start a network interface in access point mode and wait the AP to be up and running.
wait_for_sta/0	Equivalent to wait_for_sta(15000).
wait_for_sta/1	Equivalent to wait_for_sta([], Timeout) or wait_for_sta(StaConfig, 15000).
wait_for_sta/2	Start a network interface in station mode and wait for a connection to be established.

Function Details

sta_connect/0


sta_connect() -> ok | {error, Reason::term()}

returns: ok, if the network interface was started, or {error, Reason} if a failure occurred (e.g., due to malformed network configuration).

Connect to an access point after a network disconnection.

This function will attempt to connect, in the background, to the last AP endpoint that was configured.

sta_connect/1


sta_connect(Config::network_config() | [sta_config_property()]) -> ok | {error, Reason::term()}

Config: The new station mode network configuration

returns: ok, if the network interface was started, or {error, Reason} if a failure occurred (e.g., due to malformed network configuration).

Connect to a new access point after the network driver has been started.

This function will attempt to connect to a new AP endpoint in the background.

sta_disconnect/0


sta_disconnect() -> ok | {error, Reason::term()}

returns: ok, if the network disconnects from the access point, or {error, Reason} if a failure occurred.

Disconnect from access point.

This will terminate a connection to an access point.

Note: Using this function without providing an sta_disconnected_config() in the sta_config() will result in the driver immediately attempting to reconnect to the same access point again.

sta_rssi/0


sta_rssi() -> {ok, Rssi::db()} | {error, Reason::term()}

returns: {ok, Rssi} in decibels, or {error, Reason}.

Get the rssi information of AP to which the device is associated with.

sta_status/0


sta_status() -> Status::sta_status()

returns: ConnectionState :: sta_status().

Get the connection status of the sta interface.

Results will be one of: associated, connected, connecting, degraded, disconnected, disconnecting, or inactive. The state associated indicates that the station is connected to an access point, but does not yet have an IP address. A status of degraded indicates that the connection has experienced at least one beacon timeout event during the current connection session. This does not necessarily mean the connection is still in a poor state, but it might be helpful diagnosing problems with networked applications.

start/1


start(Config::network_config()) -> {ok, pid()} | {error, Reason::term()}

Config: The network configuration

returns: ok, if the network interface was started, or {error, Reason} if a failure occurred (e.g., due to malformed network configuration).

Start a network interface.

This function will start a network interface, which will attempt to connect to an AP endpoint in the background. If the managed option us used the driver will be started, but the connection will be delayed until network:sta_connect/0,1 is used to start the connection. Specify callback functions to receive definitive information that the connection succeeded; specify a sta_disconnected_config() in the sta_config() to manage re-connections in the application, rather than the default automatic attempt to reconnect until a connection is reestablished.

See the AtomVM Network Programming Manual for more information.

start_link/1


start_link(Config::network_config()) -> {ok, pid()} | {error, Reason::term()}

stop/0


stop() -> ok | {error, Reason::term()}

returns: ok, if the network interface was stopped, or {error, Reason} if a failure occurred.

Stop a network interface.

wait_for_ap/0


wait_for_ap() -> ok | {error, Reason::term()}

Equivalent to wait_for_ap(15000).

wait_for_ap/1


wait_for_ap(TimeoutOrApConfig::non_neg_integer() | [ap_config_property()]) -> ok | {error, Reason::term()}

TimeoutOrApConfig: The AP network configuration or timeout in ms.

Equivalent to wait_for_ap([], Timeout) or wait_for_ap(StaConfig, 15000).

wait_for_ap/2


wait_for_ap(ApConfig::[ap_config_property()], Timeout::non_neg_integer()) -> ok | {error, Reason::term()}

ApConfig: The AP network configuration
Timeout: amount of time in milliseconds to wait for a connection

returns: ok, when the network has started the AP, or {error, Reason} if a failure occurred (e.g., due to malformed network configuration).

Start a network interface in access point mode and wait the AP to be up and running

This function will start a network interface in AP mode, and will wait until the network is up and ready to be connected. This is a convenience function, for applications that do not need to be notified of connectivity changes in the network.

wait_for_sta/0


wait_for_sta() -> {ok, ip_info()} | {error, Reason::term()}

Equivalent to wait_for_sta(15000).

wait_for_sta/1


wait_for_sta(TimeoutOrStaConfig::non_neg_integer() | [sta_config_property()]) -> {ok, ip_info()} | {error, Reason::term()}

TimeoutOrStaConfig: The STA network configuration or timeout in ms.

Equivalent to wait_for_sta([], Timeout) or wait_for_sta(StaConfig, 15000).

wait_for_sta/2


wait_for_sta(StaConfig::[sta_config_property()], Timeout::non_neg_integer()) -> {ok, ip_info()} | {error, Reason::term()}

StaConfig: The STA network configuration
Timeout: amount of time in milliseconds to wait for a connection

returns: {ok, IpInfo}, if the network interface was started, or {error, Reason} if a failure occurred (e.g., due to malformed network configuration).

Start a network interface in station mode and wait for a connection to be established

This function will start a network interface in station mode, and will wait for a connection to be established. This is a convenience function, for applications that do not need to be notified of connectivity changes in the network.