Skip to main content

Wifi

caution

This service is rc and may change in the future.

Discovery and connection to WiFi networks. Separate TCP service can be used for data transfer.

About​

Connection​

The device controlled by this service is meant to connect automatically, once configured. To that end, it keeps a list of known WiFi networks, with priorities and passwords. It will connect to the available network with numerically highest priority, breaking ties in priority by signal strength (typically all known networks have priority of 0). If the connection fails (due to wrong password, radio failure, or other problem) an connection_failed event is emitted, and the device will try to connect to the next eligible network. When networks are exhausted, the scan is performed again and the connection process restarts.

Updating networks (setting password, priorties, forgetting) does not trigger an automatic reconnect.

Captive portals​

If the Wifi is not able to join an AP because it needs to receive a password, it may decide to enter a mode where it waits for user input. Typical example of this mode would be a captive portal or waiting for a BLE interaction. In that situation, the status_code should set to WaitingForInput.

import { Wifi } from "@devicescript/core"

const wifi = new Wifi()

Commands​

addNetwork​

Automatically connect to named network if available. Also set password if network is not open.

wifi.addNetwork(ssid: string, password: string): Promise<void>

reconnect​

Enable the WiFi (if disabled), initiate a scan, wait for results, disconnect from current WiFi network if any, and then reconnect (using regular algorithm, see set_network_priority).

wifi.reconnect(): Promise<void>

forgetNetwork​

Prevent from automatically connecting to named network in future. Forgetting a network resets its priority to 0.

wifi.forgetNetwork(ssid: string): Promise<void>

forgetAllNetworks​

Clear the list of known networks.

wifi.forgetAllNetworks(): Promise<void>

setNetworkPriority​

Set connection priority for a network. By default, all known networks have priority of 0.

wifi.setNetworkPriority(priority: number, ssid: string): Promise<void>

scan​

Initiate search for WiFi networks. Generates scan_complete event.

wifi.scan(): Promise<void>

Registers​

reading​

Current signal strength. Returns -128 when not connected.

  • type: Register<number> (packing format i8)

  • read only

import { Wifi } from "@devicescript/core"

const wifi = new Wifi()
// ...
const value = await wifi.reading.read()
  • track incoming values
import { Wifi } from "@devicescript/core"

const wifi = new Wifi()
// ...
wifi.reading.subscribe(async (value) => {
    ...
})
note

write and read will block until a server is bound to the client.

enabled​

Determines whether the WiFi radio is enabled. It starts enabled upon reset.

  • type: Register<boolean> (packing format u8)

  • read and write

import { Wifi } from "@devicescript/core"

const wifi = new Wifi()
// ...
const value = await wifi.enabled.read()
await wifi.enabled.write(value)
  • track incoming values
import { Wifi } from "@devicescript/core"

const wifi = new Wifi()
// ...
wifi.enabled.subscribe(async (value) => {
    ...
})
note

write and read will block until a server is bound to the client.

ipAddress​

0, 4 or 16 byte buffer with the IPv4 or IPv6 address assigned to device if any.

  • type: Register<Buffer> (packing format b[16])

  • track incoming values

import { Wifi } from "@devicescript/core"

const wifi = new Wifi()
// ...
wifi.ipAddress.subscribe(async (value) => {
    ...
})
note

write and read will block until a server is bound to the client.

eui48​

The 6-byte MAC address of the device. If a device does MAC address randomization it will have to "restart".

  • type: Register<Buffer> (packing format b[6])
  • constant: the register value will not change (until the next reset)
note

write and read will block until a server is bound to the client.

ssid​

SSID of the access-point to which device is currently connected. Empty string if not connected.

  • type: Register<string> (packing format s[32])

  • read only

import { Wifi } from "@devicescript/core"

const wifi = new Wifi()
// ...
const value = await wifi.ssid.read()
  • track incoming values
import { Wifi } from "@devicescript/core"

const wifi = new Wifi()
// ...
wifi.ssid.subscribe(async (value) => {
    ...
})
note

write and read will block until a server is bound to the client.

Events​

gotIp​

Emitted upon successful join and IP address assignment.

wifi.gotIp.subscribe(() => {

})

lostIp​

Emitted when disconnected from network.

wifi.lostIp.subscribe(() => {

})

scanComplete​

A WiFi network scan has completed. Results can be read with the last_scan_results command. The event indicates how many networks where found, and how many are considered as candidates for connection.

wifi.scanComplete.subscribe(() => {

})

networksChanged​

Emitted whenever the list of known networks is updated.

wifi.networksChanged.subscribe(() => {

})

connectionFailed​

Emitted when when a network was detected in scan, the device tried to connect to it and failed. This may be because of wrong password or other random failure.

wifi.connectionFailed.subscribe(() => {

})