Skip to main content
Version: 1.0

WiFi

The WiFi component handles wireless connection services of a device. The Wifi component uses Wifi as RPC namespace and provides the methods:

It uses the key wifi when enumerated in objects including multiple component payloads, like Shelly.GetStatus.

RangeExtender​

Since version 0.11.0

Range extender functionality is part of the device's WiFi characteristcs. It enables a Gen2+ Shelly device to provide internet connectivity to other shellies connected to its access point with otherwise poor WiFi coverage. It is available on non battery operated devices. Some of the configuration and status properties are specific to this functionality and only available when it is present. It is advisable to enable range extender functionality only when the AP is secured.

Methods​

Wifi.SetConfig​

Find more about the config properties in config section

Wifi.GetConfig​

Find the Wifi.GetConfig response properties in config section

Wifi.GetStatus​

Find more about the status response properties in status section

WiFi.Scan​

This method returns list of all available networks.

Request​

This method takes no parameters.

Response​

Attributes in the result:

PropertyTypeDescription

results

array of objects

Each of these JSON object contains:

PropertyTypeDescription

ssid

string or null

Ssid of the network (null in case of hidden network)

bssid

string

Bssid of the network

auth

number

Authentication method. Range of values: 0->OPEN, 1->WEP, 2->WPA_PSK, 3->WPA2_PSK, 4->WPA_WPA2_PSK, 5->WPA2_ENTERPRISE

channel

number

Network channel

rssi

number

Strength of the signal in dBms

WiFi.ListAPClients​

This method returns list of clients currently connected to the device's access point. Available only when the range extender functionality is available on the device and both AP and RangeExtender are enabled. This method does not require authentication (even when authentication is enabled).

Request​

This method takes no parameters.

Response​

Attributes in the result:

PropertyTypeDescription

ts

number or null

Unix timestamp of the request, null if device is not synced with SNTP

ap_clients

array of objects

List of objects with information about clients currently connected to the AP of the device containing:

PropertyTypeDescription

mac

string

MAC address of the client

ip

string

IP address of the client

ip_static

boolean

True if the IP is static, false otherwise

mport

number

Mapped port, 0 if range extender is not enabled or the port used by NAT. It maps to port 80 of the client.

since

number

Unix timestamp of the moment the client connected to the AP

Configuration​

The configuration of the WiFi component contains information about the access point of the device, the network stations and the roaming settings.

Properties:

PropertyTypeDescription

ap

object

Information about the access point

PropertyTypeDescription

ssid

string

readonly SSID of the access point

pass

string or null

Password for the ssid, writeonly. Must be provided if you provide ssid

is_open

boolean

True if the access point is open, false otherwise

enable

boolean

True if the access point is enabled, false otherwise

range_extender

object

Range extender configuration object, available only when range extender functionality is present.

PropertyTypeDescription

enable

boolean

True if range extender functionality is enabled, false otherwise

sta

object

Information about the sta configuration

PropertyTypeDescription

ssid

string or null

Ssid of the network.

pass

string or null

Password for the ssid, writeonly. Must be provided if you provide ssid

is_open

boolean

True if the network is open, i.e. no password is set, false otherwise, readonly

enable

boolean

True if the configuration is enabled, false otherwise

ipv4mode

string

IPv4 mode. Range of values: dhcp, static

ip

string or null

Ip to use when ipv4mode is static

netmask

string or null

Netmask to use when ipv4mode is static

gw

string or null

Gateway to use when ipv4mode is static

nameserver

string or null

Nameserver to use when ipv4mode is static

sta1

object

Identical to sta. It will be used as fallback when the device is unable to connect to the sta network.

roam

object

WiFi roaming configuration

PropertyTypeDescription

rssi_thr

number

Rssi threshold - when reached will trigger the access point roaming. Default value: -80

interval

number

Interval at which to scan for better access points. Enabled if set to positive number, disabled if set to 0. Default value: 60

note

When changing WiFi station configuration the proccess of applying it causes the Shelly to perform reconnection to the AP(s) about a second after the new config is stored. Connected agents, inbound websocket or outbound MQTT, might experience disconnect events if IP connectivity is over WiFi. Implementations should consider timeouts, LWT notifications, and reconnects after this configuration change.

caution

In case you want to set a new password-protected WiFi network in your configuration through WiFi.SetConfig, you must include the property pass: string (specifying the network password), together with the ssid in the config object. This property is not shown in the response of WiFi.GetConfig to prevent leaking credentials.

Status​

The status of the WiFi component contains information about the state of the WiFi connection of the device.

Properties:

PropertyTypeDescription

sta_ip

string or null

Ip of the device in the network (null if disconnected)

status

string

Status of the connection. Range of values: disconnected, connecting, connected, got ip

ssid

string or null

Ssid of the network (null if disconnected)

rssi

number

Strength of the signal in dBms

ap_client_count

number

Number of clients connected to the access point. Present only when AP is enabled and range extender functionality is present and enabled.

Notifications​

This section describes notifications for events specific to the Wifi component. For general information please see this page.

Example​

Wifi.SetConfig example​

http://192.168.33.1/rpc/WiFi.SetConfig?config={"sta":{"ssid":"Shelly","pass":"Shelly","enable":true}}

Response

{
  "restart_required": false
}

Wifi.GetConfig example​

http://192.168.33.1/rpc/WiFi.GetConfig

Response

{
  "ap": {
    "ssid": "ShellyPlus2PM-A8032AB636EC",
    "is_open": true,
    "enable": true,
    "range_extender": {
      "enable": false
    }
  },
  "sta": {
    "ssid": "Allterco WiFi",
    "is_open": false,
    "enable": true,
    "ipv4mode": "dhcp",
    "ip": null,
    "netmask": null,
    "gw": null,
    "nameserver": null
  },
  "sta1": {
    "ssid": null,
    "is_open": true,
    "enable": false,
    "ipv4mode": "dhcp",
    "ip": null,
    "netmask": null,
    "gw": null,
    "nameserver": null
  },
  "roam": {
    "rssi_thr": -80,
    "interval": 60
  }
}

Wifi.GetStatus example​

http://192.168.33.1/rpc/WiFi.GetStatus

Response

{
  "sta_ip": "192.168.206.97",
  "status": "got ip",
  "ssid": "Allterco WiFi",
  "rssi": -56,
  "ap_client_count": 0
}

WiFi.Scan example​

http://192.168.33.1/rpc/WiFi.Scan

Response

{
  "results": [
    {
      "ssid": "ShellyPro4PM-F008D1D89064",
      "bssid": "f0:08:d1:d8:90:65",
      "auth": 0,
      "channel": 11,
      "rssi": -70
    },
    {
      "ssid": "Shelly",
      "bssid": "26:18:d6:82:2b:80",
      "auth": 3,
      "channel": 11,
      "rssi": -87
    },
    {
      "ssid": "Allterco Guests",
      "bssid": "ba:fb:e4:f7:0f:7f",
      "auth": 0,
      "channel": 6,
      "rssi": -59
    }
  ]
}

Wifi.ListAPClients example​

http://192.168.33.1/rpc/WiFi.ListAPClients

Response

{
  "ts": 1655723139,
  "ap_clients": [
    {
      "mac": "a4:97:b1:d0:59:65",
      "ip": "192.168.33.64",
      "ip_static": false,
      "mport": 0,
      "since": 1655723070
    }
  ]
}

Notifications example​

The Wifi component can send notifications for the following events:

  • Wifi STA connection attempt failed:

Example 1:

Notify that Wifi STA connection attempt has failed.
{
   "src": "shellypro4pm-f008d1d8b8b8",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1631267074.94,
      "events": [
         {
            "component": "wifi",
            "event": "sta_connect_fail",
            "reason": 15,
            "ts": 1631267074.94
         }
      ]
   }
}

reason: number, see this reference for details

  • Wifi STA disconnect:

Example 2:

Notify that Wifi STA has disconnected.
{
   "src": "shellypro4pm-f008d1d8b8b8",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1631267029.96,
      "events": [
         {
            "component": "wifi",
            "event": "sta_disconnected",
            "sta_ip": null,
            "ssid": null,
            "reason": 8,
            "ts": 1631267029.96
         }
      ]
   }
}

reason: number, see this reference for details