hs.wifi
ModuleControl and query Wi-Fi interfaces, scan for networks, and watch for Wi-Fi events.
Built on CoreWLAN. Fields that reveal network identity — ssid, bssid, countryCode,
and BSSIDs inside scan results — are only populated once Location Services is enabled and
the user has authorized this app; call hs.permissions.requestLocation() first (the same
gate hs.location uses). Without authorization these fields are null/omitted, not errors.
Watching for Wi-Fi events
hs.wifi.on('ssidChange', info => console.log("SSID changed on " + info.interface))
Properties
This module has no properties.
Methods
hs.wifi.interfaces() -> string[]
Returns the names of all Wi-Fi interfaces attached to the system (e.g. `["en0"]`).
Declaration
hs.wifi.interfaces() -> string[]Returns
string[]
an array of interface name strings
Example
console.log(hs.wifi.interfaces())hs.wifi.interfaceDetails(interface) -> [String: Any]
Returns detailed information about a Wi-Fi interface.
Declaration
hs.wifi.interfaceDetails(interface) -> [String: Any]Parameters
| Name | Type | Description |
|---|---|---|
| interface | string | the interface name as returned by `interfaces()`; omit for the system's default Wi-Fi interface |
Returns
[String: Any]
a table with keys `interface, active, power, ssid, bssid, security, interfaceMode, activePHYMode, rssi, noise, transmitRate, transmitPower, countryCode, hardwareAddress, wlanChannel, supportedChannels, cachedScanResults, configuration`; or null if the interface doesn't exist. `ssid`/`bssid`/`countryCode`/`wlanChannel` may be absent without Location Services authorization.
Example
const info = hs.wifi.interfaceDetails()
if (info) console.log(info.ssid + " on channel " + info.wlanChannel.number)hs.wifi.currentNetwork(interface) -> string
Returns the SSID of the network currently joined on an interface.
Declaration
hs.wifi.currentNetwork(interface) -> stringParameters
| Name | Type | Description |
|---|---|---|
| interface | string | the interface name as returned by `interfaces()`; omit for the system's default Wi-Fi interface |
Returns
string
the SSID string, or null if not joined to a network (or Location Services is not authorized)
Example
console.log(hs.wifi.currentNetwork())hs.wifi.setPower(state, interface) -> boolean
Turns a Wi-Fi interface on or off.
Declaration
hs.wifi.setPower(state, interface) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| state | boolean | true to power the interface on, false to power it off |
| interface | string | the interface name as returned by `interfaces()`; omit for the system's default Wi-Fi interface |
Returns
boolean
true if the power state was changed successfully, false if the interface doesn't exist or the change failed (see the Console for the reason)
Example
hs.wifi.setPower(false) // turn Wi-Fi offhs.wifi.disassociate(interface) -> None
Disconnects an interface from its current network.
Declaration
hs.wifi.disassociate(interface) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| interface | string | the interface name as returned by `interfaces()`; omit for the system's default Wi-Fi interface |
Returns
None
Example
hs.wifi.disassociate()hs.wifi.associate(ssid, passphrase, interface) -> Promise<boolean>
Scans for a network by SSID and joins it. Enterprise networks are not supported.
This can take several seconds; it runs off the main thread so it does not block the app.
Declaration
hs.wifi.associate(ssid, passphrase, interface) -> Promise<boolean>Parameters
| Name | Type | Description |
|---|---|---|
| ssid | string | the SSID of the network to join |
| passphrase | string | the network passphrase; required for WEP/WPA/WPA2/WPA3 Personal networks |
| interface | string | the interface name as returned by `interfaces()`; omit for the system's default Wi-Fi interface |
Returns
Promise<boolean>
A Promise that resolves `true` if joined successfully, `false` if no network with that SSID was found, or rejects if the interface doesn't exist or the association attempt fails
Example
hs.wifi.associate("MyNetwork", "hunter2")
.then(joined => console.log(joined ? "Joined" : "Network not found"))
.catch(err => console.log("Error: " + err))hs.wifi.scanNetworks(interface) -> Promise<object[]>
Scans for visible Wi-Fi networks.
This can take a few seconds; it runs off the main thread so it does not block the app.
Declaration
hs.wifi.scanNetworks(interface) -> Promise<object[]>Parameters
| Name | Type | Description |
|---|---|---|
| interface | string | the interface name as returned by `interfaces()`; omit for the system's default Wi-Fi interface |
Returns
Promise<object[]>
A Promise that resolves to an array of network tables, each with keys `ssid, bssid, rssi, noise, ibss, countryCode, beaconInterval, security, phyModes, wlanChannel, informationElementData`; or rejects if the interface doesn't exist or the scan fails. `bssid`/`countryCode` may be absent without Location Services authorization. `informationElementData` is raw beacon/probe-response data returned as an array of byte values (0-255) rather than a string, since it can contain sequences that are unsafe to render as text.
Example
hs.wifi.scanNetworks().then(networks => {
networks.forEach(n => console.log(n.ssid + " (" + n.rssi + " dBm)"))
})hs.wifi.on(event, listener) -> None
Register a listener for a Wi-Fi interface event.
Declaration
hs.wifi.on(event, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| event | any | The event to listen for |
| listener | any | Called with an info dictionary describing the event; see the keys listed above |
Returns
None
Example
hs.wifi.on('ssidChange', info => console.log("SSID changed on " + info.interface))
hs.wifi.on('linkQualityChange', info => console.log(info.interface + ": " + info.rssi + " dBm"))hs.wifi.off(event, listener) -> None
Remove a previously registered Wi-Fi event listener.
Declaration
hs.wifi.off(event, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| event | any | The event the listener was registered for |
| listener | any | The function originally passed to `on` |
Returns
None
Example
const onSsidChange = info => console.log(info)
hs.wifi.on('ssidChange', onSsidChange)
// later…
hs.wifi.off('ssidChange', onSsidChange)hs.wifi.once(event, listener) -> None
Register a listener that fires at most once for a Wi-Fi interface event.
Declaration
hs.wifi.once(event, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| event | any | The event to listen for |
| listener | any | Called once, then automatically removed |
Returns
None
Example
hs.wifi.once('ssidChange', info => console.log("First SSID change: " + info.interface))