Help us shape the future of Go! Take the 2026 Go Developer Survey

wifi

package module
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 22, 2026 License: MIT Imports: 16 Imported by: 74

README

wifi Test Status Go Reference Go Report Card

Package wifi provides access to IEEE 802.11 WiFi device operations on Linux using nl80211. MIT Licensed.

Documentation

Overview

Package wifi provides access to IEEE 802.11 WiFi device operations on Linux using nl80211.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrNotSupported      = errors.New("not supported")
	ErrScanGroupNotFound = errors.New("scan multicast group unavailable")
	ErrScanAborted       = errors.New("scan aborted by the kernel")
	ErrScanValidation    = errors.New("scan validation failed")
)

Functions

This section is empty.

Types

type BSS 

type BSS struct {
	// The service set identifier, or "network name" of the BSS.
	SSID string

	// BSSID: The BSS service set identifier.  In infrastructure mode, this is the
	// hardware address of the wireless access point that a client is associated
	// with.
	BSSID net.HardwareAddr

	// Frequency: The frequency used by the BSS, in MHz.
	Frequency int

	// BeaconInterval: The time interval between beacon transmissions for this BSS.
	BeaconInterval time.Duration

	// LastSeen: The time since the client last scanned this BSS's information.
	LastSeen time.Duration

	// Status: The status of the client within the BSS.
	Status BSSStatus

	// Signal: The signal strength of the BSS, in mBm (divide by 100 to get dBm).
	Signal int32

	// SignalUnspecified: The signal strength of the BSS, in percent.
	SignalUnspecified uint32

	// Load: The load element of the BSS (contains StationCount, ChannelUtilization and AvailableAdmissionCapacity).
	Load BSSLoad

	// RSN Robust Security Network Information Element (IEEE 802.11 Element ID 48)
	RSN RSNInfo
}

A BSS is an 802.11 basic service set. It contains information about a wireless network associated with an Interface.

type BSSLoad added in v0.2.0 

type BSSLoad struct {
	// Version: Indicates the version of the BSS Load Element. Can be 1 or 2.
	Version int

	// StationCount: total number of STA currently associated with this BSS.
	StationCount uint16

	// ChannelUtilization: Percentage of time (linearly scaled 0 to 255) that the AP sensed the medium was busy. Calculated only for the primary channel.
	ChannelUtilization uint8

	// AvailableAdmissionCapacity: remaining amount of medium time available via explicit admission control in units of 32 us/s.
	AvailableAdmissionCapacity uint16
}

BSSLoad is an Information Element containing measurements of the load on the BSS.

func (BSSLoad) String added in v0.2.0 

func (l BSSLoad) String() string

String returns the string representation of a BSSLoad.

type BSSStatus 

type BSSStatus int

A BSSStatus indicates the current status of client within a BSS. 

const (
	// BSSStatusAuthenticated indicates that a client is authenticated with a BSS.
	BSSStatusAuthenticated BSSStatus = iota

	// BSSStatusAssociated indicates that a client is associated with a BSS.
	BSSStatusAssociated

	// BSSStatusNotAssociated indicates that a client is not associated with a BSS.
	BSSStatusNotAssociated

	// BSSStatusIBSSJoined indicates that a client has joined an independent BSS.
	BSSStatusIBSSJoined
)

func (BSSStatus) String 

func (s BSSStatus) String() string

String returns the string representation of a BSSStatus.

type ChannelWidth added in v0.7.0 

type ChannelWidth int

A ChannelWidth is the width of a WiFi channel.

On Linux, ChannelWidth copies the ordering of nl80211's channel width constants. This may not be the case on other operating systems. See: https://github.com/torvalds/linux/blob/v6.17/include/uapi/linux/nl80211.h#L5136-L5177 

const (
	ChannelWidth20NoHT ChannelWidth = iota
	ChannelWidth20
	ChannelWidth40
	ChannelWidth80
	ChannelWidth80P80
	ChannelWidth160
	ChannelWidth5
	ChannelWidth10
	ChannelWidth1
	ChannelWidth2
	ChannelWidth4
	ChannelWidth8
	ChannelWidth16
	ChannelWidth320
)

func (ChannelWidth) String added in v0.7.0 

func (t ChannelWidth) String() string

String returns the string representation of an InterfaceType.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

A Client is a type which can access WiFi device actions and statistics using operating system-specific operations.

func New 

func New() (*Client, error)

New creates a new Client.

func (*Client) AccessPoints added in v0.5.0 

func (c *Client) AccessPoints(ifi *Interface) ([]*BSS, error)

AccessPoints retrieves the currently known BSS around the specified Interface.

func (*Client) BSS 

func (c *Client) BSS(ifi *Interface) (*BSS, error)

BSS retrieves the BSS associated with a WiFi interface.

func (*Client) Close 

func (c *Client) Close() error

Close releases resources used by a Client.

func (*Client) Connect 

func (c *Client) Connect(ifi *Interface, ssid string) error

Connect starts connecting the interface to the specified ssid.

func (*Client) ConnectWPAPSK 

func (c *Client) ConnectWPAPSK(ifi *Interface, ssid, psk string) error

Connect starts connecting the interface to the specified ssid using WPA.

func (*Client) Disconnect 

func (c *Client) Disconnect(ifi *Interface) error

Dissconnect disconnects the interface.

func (*Client) GetRegulatoryDomain added in v0.8.0 

func (c *Client) GetRegulatoryDomain() (*RegulatoryDomain, error)

GetRegulatoryRegion gets the system-wide regulatory domain. See https://wireless.docs.kernel.org/en/latest/en/developers/regulatory/wireless-regdb.html

func (*Client) Interfaces 

func (c *Client) Interfaces() ([]*Interface, error)

Interfaces returns a list of the system's WiFi network interfaces.

func (*Client) ReloadRegulatoryDatabase added in v0.8.0 

func (c *Client) ReloadRegulatoryDatabase() error

ReloadRegulatoryDatabase reloads the wireless regulatory database.

This can be used if cfg80211 was built into the kernel and the wireless regulatory database was not available during early boot.

See https://wireless.docs.kernel.org/en/latest/en/developers/regulatory/wireless-regdb.html

func (*Client) Scan added in v0.5.0 

func (c *Client) Scan(ctx context.Context, ifi *Interface) error

Scan requests the wifi interface to scan for new access points.

Use context.WithDeadline to set a timeout.

func (*Client) SetDeadline added in v0.3.0 

func (c *Client) SetDeadline(t time.Time) error

SetDeadline sets the read and write deadlines associated with the connection.

func (*Client) SetReadDeadline added in v0.3.0 

func (c *Client) SetReadDeadline(t time.Time) error

SetReadDeadline sets the read deadline associated with the connection.

func (*Client) SetRegulatoryRegion added in v0.8.0 

func (c *Client) SetRegulatoryRegion(region string, hint RegulatoryHint) error

SetRegulatoryRegion sets the system-wide regulatory region used by all nl80211 devices. You may need to call Client.ReloadRegulatoryDatabase first to ensure the region is updated correctly.

region must be an ISO 3166-1 alpha-2 country code (e.g. "GB" or "US"). hint should almost always be RegulatoryHintUser.

See https://wireless.docs.kernel.org/en/latest/en/developers/regulatory/wireless-regdb.html

func (*Client) SetWriteDeadline added in v0.3.0 

func (c *Client) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the write deadline associated with the connection.

func (*Client) StationInfo 

func (c *Client) StationInfo(ifi *Interface) ([]*StationInfo, error)

StationInfo retrieves all station statistics about a WiFi interface.

Since v0.2.0: if there are no stations, an empty slice is returned instead of an error.

func (*Client) SurveyInfo added in v0.4.0 

func (c *Client) SurveyInfo(ifi *Interface) ([]*SurveyInfo, error)

SurveyInfo retrieves the survey information about a WiFi interface.

type Interface 

type Interface struct {
	// The index of the interface.
	Index int

	// The name of the interface.
	Name string

	// The hardware address of the interface.
	HardwareAddr net.HardwareAddr

	// The physical device that this interface belongs to.
	PHY int

	// The virtual device number of this interface within a PHY.
	Device int

	// The operating mode of the interface.
	Type InterfaceType

	// The interface's wireless frequency in MHz.
	Frequency int

	// The interface's wireless channel width.
	ChannelWidth ChannelWidth
}

An Interface is a WiFi network interface.

func ParseInterfaces added in v0.7.0 

func ParseInterfaces(msgs []genetlink.Message) ([]*Interface, error)

parseInterfaces parses zero or more Interfaces from nl80211 interface messages.

type InterfaceType 

type InterfaceType int

An InterfaceType is the operating mode of an Interface. 

const (
	// InterfaceTypeUnspecified indicates that an interface's type is unspecified
	// and the driver determines its function.
	InterfaceTypeUnspecified InterfaceType = iota

	// InterfaceTypeAdHoc indicates that an interface is part of an independent
	// basic service set (BSS) of client devices without a controlling access
	// point.
	InterfaceTypeAdHoc

	// InterfaceTypeStation indicates that an interface is part of a managed
	// basic service set (BSS) of client devices with a controlling access point.
	InterfaceTypeStation

	// InterfaceTypeAP indicates that an interface is an access point.
	InterfaceTypeAP

	// InterfaceTypeAPVLAN indicates that an interface is a VLAN interface
	// associated with an access point.
	InterfaceTypeAPVLAN

	// InterfaceTypeWDS indicates that an interface is a wireless distribution
	// interface, used as part of a network of multiple access points.
	InterfaceTypeWDS

	// InterfaceTypeMonitor indicates that an interface is a monitor interface,
	// receiving all frames from all clients in a given network.
	InterfaceTypeMonitor

	// InterfaceTypeMeshPoint indicates that an interface is part of a wireless
	// mesh network.
	InterfaceTypeMeshPoint

	// InterfaceTypeP2PClient indicates that an interface is a client within
	// a peer-to-peer network.
	InterfaceTypeP2PClient

	// InterfaceTypeP2PGroupOwner indicates that an interface is the group
	// owner within a peer-to-peer network.
	InterfaceTypeP2PGroupOwner

	// InterfaceTypeP2PDevice indicates that an interface is a device within
	// a peer-to-peer client network.
	InterfaceTypeP2PDevice

	// InterfaceTypeOCB indicates that an interface is outside the context
	// of a basic service set (BSS).
	InterfaceTypeOCB

	// InterfaceTypeNAN indicates that an interface is part of a near-me
	// area network (NAN).
	InterfaceTypeNAN
)

func (InterfaceType) String 

func (t InterfaceType) String() string

String returns the string representation of an InterfaceType.

type RSNAKM added in v0.6.0 

type RSNAKM uint32

RSNAKM represents an Authentication and Key Management suite in RSN IE. Values correspond to OUIs (00-0F-AC-XX) in the wire format as defined in IEEE 802.11-2020 standard, section 9.4.2.24.3 (AKM Suites). 

const (
	RSNAkmReserved0     RSNAKM = 0x000FAC00 // Reserved
	RSNAkm8021X         RSNAKM = 0x000FAC01 // 802.1X (WPA-Enterprise)
	RSNAkmPSK           RSNAKM = 0x000FAC02 // PSK (WPA2-Personal)
	RSNAkmFT8021X       RSNAKM = 0x000FAC03 // FT-802.1X (Fast BSS transition with EAP)
	RSNAkmFTPSK         RSNAKM = 0x000FAC04 // FT-PSK (Fast BSS transition with PSK)
	RSNAkm8021XSHA256   RSNAKM = 0x000FAC05 // 802.1X-SHA256 (WPA2 with SHA256 auth)
	RSNAkmPSKSHA256     RSNAKM = 0x000FAC06 // PSK-SHA256 (WPA2-PSK with SHA256)
	RSNAkmTDLS          RSNAKM = 0x000FAC07 // TDLS TPK handshake
	RSNAkmSAE           RSNAKM = 0x000FAC08 // SAE (WPA3-Personal)
	RSNAkmFTSAE         RSNAKM = 0x000FAC09 // FT-SAE (WPA3-Personal with Fast Roaming)
	RSNAkmAPPeerKey     RSNAKM = 0x000FAC0A // APPeerKey Authentication with SHA-256
	RSNAkm8021XSuiteB   RSNAKM = 0x000FAC0B // 802.1X using Suite B compliant EAP (SHA-256)
	RSNAkm8021XCNSA     RSNAKM = 0x000FAC0C // 802.1X using CNSA Suite compliant EAP (SHA-384)
	RSNAkmFT8021XSHA384 RSNAKM = 0x000FAC0D // FT-802.1X using SHA-384
	RSNAkmFILSSHA256    RSNAKM = 0x000FAC0E // FILS key management using SHA-256
	RSNAkmFILSSHA384    RSNAKM = 0x000FAC0F // FILS key management using SHA-384
	RSNAkmFTFILSSHA256  RSNAKM = 0x000FAC10 // FT authentication over FILS with SHA-256
	RSNAkmFTFILSSHA384  RSNAKM = 0x000FAC11 // FT authentication over FILS with SHA-384
	RSNAkmReserved18    RSNAKM = 0x000FAC12 // Reserved
	RSNAkmFTPSKSHA384   RSNAKM = 0x000FAC13 // FT-PSK using SHA-384
	RSNAkmPSKSHA384     RSNAKM = 0x000FAC14 // PSK using SHA-384
)

RSN AKM suite constants (Wi-Fi Alliance OUI: 00-0F-AC)

func (RSNAKM) String added in v0.6.0 

func (a RSNAKM) String() string

String returns the human-readable name of the RSN AKM.

type RSNCipher added in v0.6.0 

type RSNCipher uint32

RSNCipher represents a cipher suite in RSN IE. Values correspond to OUIs (00-0F-AC-XX) in the wire format as defined in IEEE 802.11-2020 standard, section 9.4.2.24.2 (Cipher Suites). 

const (
	RSNCipherUseGroup        RSNCipher = 0x000FAC00 // Use group cipher suite
	RSNCipherWEP40           RSNCipher = 0x000FAC01 // WEP-40 (insecure, legacy)
	RSNCipherTKIP            RSNCipher = 0x000FAC02 // TKIP (insecure, deprecated)
	RSNCipherReserved3       RSNCipher = 0x000FAC03 // Reserved
	RSNCipherCCMP128         RSNCipher = 0x000FAC04 // CCMP-128 (AES) - WPA2
	RSNCipherWEP104          RSNCipher = 0x000FAC05 // WEP-104 (insecure, legacy)
	RSNCipherBIPCMAC128      RSNCipher = 0x000FAC06 // BIP-CMAC-128 (802.11w MFP/PMF)
	RSNCipherGroupNotAllowed RSNCipher = 0x000FAC07 // Group addressed traffic not allowed
	RSNCipherGCMP128         RSNCipher = 0x000FAC08 // GCMP-128 (AES-GCMP) - WPA3
	RSNCipherGCMP256         RSNCipher = 0x000FAC09 // GCMP-256 (AES-GCMP) - WPA3-Enterprise
	RSNCipherCCMP256         RSNCipher = 0x000FAC0A // CCMP-256 (AES, 256-bit key)
	RSNCipherBIPGMAC128      RSNCipher = 0x000FAC0B // BIP-GMAC-128
	RSNCipherBIPGMAC256      RSNCipher = 0x000FAC0C // BIP-GMAC-256
	RSNCipherBIPCMAC256      RSNCipher = 0x000FAC0D // BIP-CMAC-256
)

func (RSNCipher) String added in v0.6.0 

func (c RSNCipher) String() string

String returns the human-readable name of the RSN cipher.

type RSNInfo added in v0.6.0 

type RSNInfo struct {
	Version         uint16
	GroupCipher     RSNCipher   // Group cipher suite
	PairwiseCiphers []RSNCipher // Pairwise cipher suites
	AKMs            []RSNAKM    // Authentication and Key Management suites
	Capabilities    uint16      // RSN capability flags
	GroupMgmtCipher RSNCipher   // Group management cipher (present only with WPA3/802.11w)
}

Robust Security Network Information Element The RSN IE structure is defined in IEEE 802.11-2020 standard, section 9.4.2.24 (page 1051) .

func (RSNInfo) IsInitialized added in v0.6.0 

func (r RSNInfo) IsInitialized() bool

func (RSNInfo) String added in v0.6.0 

func (r RSNInfo) String() string

type RegulatoryDomain added in v0.8.0 

type RegulatoryDomain struct {
	Region string // ISO 3166-1 alpha-2 country code
}

RegulatoryDomain contains information about the regulatory domain the device or system operates in.

type RegulatoryHint added in v0.8.0 

type RegulatoryHint uint32

RegulatoryHint describes why the regulatory region is being set. See: - https://wireless.docs.kernel.org/en/latest/en/developers/regulatory/processing_rules.html#cellular-base-station-regulatory-hints - https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/nl80211.h?h=a55f7f5f29b32c2c53cc291899cf9b0c25a07f7c#n4803 

const (
	RegulatoryHintUser     RegulatoryHint = 0x0 // Set by the userspace (default)
	RegulatoryHintCellBase RegulatoryHint = 0x1 // Set based on cellular network information
	RegulatoryHintIndoor   RegulatoryHint = 0x2 // Set because the device is indoors
)

type StationInfo 

type StationInfo struct {
	// The interface that this station is associated with.
	InterfaceIndex int

	// The hardware address of the station.
	HardwareAddr net.HardwareAddr

	// The time since the station last connected.
	Connected time.Duration

	// The time since wireless activity last occurred.
	Inactive time.Duration

	// The number of bytes received by this station.
	ReceivedBytes int

	// The number of bytes transmitted by this station.
	TransmittedBytes int

	// The number of packets received by this station.
	ReceivedPackets int

	// The number of packets transmitted by this station.
	TransmittedPackets int

	// The current data receive bitrate, in bits/second.
	ReceiveBitrate int

	// The current data transmit bitrate, in bits/second.
	TransmitBitrate int

	// The signal strength of the last received PPDU, in dBm.
	Signal int

	// The average signal strength, in dBm.
	SignalAverage int

	// The number of times the station has had to retry while sending a packet.
	TransmitRetries int

	// The number of times a packet transmission failed.
	TransmitFailed int

	// The number of times a beacon loss was detected.
	BeaconLoss int
}

StationInfo contains statistics about a WiFi interface operating in station mode.

func ParseStationInfo added in v0.7.0 

func ParseStationInfo(b []byte) (*StationInfo, error)

ParseStationInfo parses StationInfo attributes from a byte slice of netlink attributes.

type SurveyInfo added in v0.4.0 

type SurveyInfo struct {
	// The interface that this station is associated with.
	InterfaceIndex int

	// The frequency in MHz of the channel.
	Frequency int

	// The noise level in dBm.
	Noise int

	// The time the radio has spent on this channel.
	ChannelTime time.Duration

	// The time the radio has spent on this channel while it was active.
	ChannelTimeActive time.Duration

	// The time the radio has spent on this channel while it was busy.
	ChannelTimeBusy time.Duration

	// The time the radio has spent on this channel while it was busy with external traffic.
	ChannelTimeExtBusy time.Duration

	// The time the radio has spent on this channel receiving data from a BSS.
	ChannelTimeBssRx time.Duration

	// The time the radio has spent on this channel receiving data.
	ChannelTimeRx time.Duration

	// The time the radio has spent on this channel transmitting data.
	ChannelTimeTx time.Duration

	// The time the radio has spent on this channel while it was scanning.
	ChannelTimeScan time.Duration

	// Indicates if the channel is currently in use.
	InUse bool
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.