lua-eco

• Index

Contents

• Functions
• Tables

Modules

• eco
• eco.time
• eco.log
• eco.file
• eco.sys
• eco.sync
• eco.channel
• eco.shared
• eco.uci
• eco.ubus
• eco.socket
• eco.packet
• eco.dns
• eco.ssl
• eco.mqtt
• eco.net
• eco.nl
• eco.genl
• eco.rtnl
• eco.ip
• eco.nl80211
• eco.websocket
• eco.termios
• eco.ssh
• eco.http.server
• eco.http.client
• eco.encoding.hex
• eco.encoding.base64
• eco.hash.md5
• eco.hash.sha1
• eco.hash.sha256
• eco.hash.hmac

Topics

• README

Examples

• channel.lua
• coroutine.lua
• dns.lua
• base64.lua
• hex.lua
• env.lua
• exec.lua
• shell.lua
• dir.lua
• file.lua
• flock.lua
• inotify.lua
• walk.lua
• hmac.lua
• md5.lua
• sha1.lua
• sha256.lua
• hook.lua
• download_file.lua
• get.lua
• post.lua
• post_file.lua
• post_form.lua
• server.lua
• server_multiprocess.lua
• log.lua
• mqtt.lua
• custom-proto.lua
• genl_get_family.lua
• ip-addr-add.lua
• ip-addr-del.lua
• ip-addr-get.lua
• ip-link.lua
• link_del.lua
• link_dump.lua
• link_event.lua
• nl80211_add_interface.lua
• nl80211_del_interface.lua
• nl80211_dump_interface.lua
• nl80211_dump_station.lua
• nl80211_get_freqlist.lua
• nl80211_get_interface.lua
• nl80211_get_station.lua
• nl80211_scan.lua
• nl80211_set_interface.lua
• route_event.lua
• panic_hook.lua
• send-at-command.lua
• shared.lua
• signal.lua
• ping.lua
• ping6.lua
• recver.lua
• sender.lua
• arp-scan.lua
• arping.lua
• capture.lua
• send_tcp.lua
• send_udp.lua
• socketpair_dgram.lua
• socketpair_fork.lua
• socketpair_stream.lua
• client.lua
• server.lua
• client.lua
• server.lua
• client.lua
• dgram_client.lua
• dgram_server.lua
• server.lua
• spawn.lua
• exec.lua
• scp_recv.lua
• scp_send.lua
• client.lua
• server.lua
• cond.lua
• mutex.lua
• wait_group.lua
• termios.lua
• timer.lua
• signatures.lua
• subscribe.lua
• ubus.lua
• client.lua
• server.lua

Module eco.nl80211

Linux nl80211 helpers.

This module is a convenience wrapper for the Linux nl80211 Generic Netlink family (Wi‑Fi configuration and status). It uses eco.genl to resolve the family and multicast group ids, and eco.nl to send/receive netlink messages.

Constants from Linux NL80211_* definitions are exported as:

• commands: CMD_*
• attributes: ATTR_*
• interface types: IFTYPE_*
• bands/channel widths/rate-info keys: BAND_*, CHAN_*, CHAN_WIDTH_*, RATE_INFO_*
• BSS/station/survey attribute keys: BSS_*, STA_INFO_*, SURVEY_INFO_*

In addition, this Lua module defines a few IEEE 802.11 constants (FTYPE_*, STYPE_*, WLAN_EID_*) and helper functions for formatting and parsing.

Most operations require sufficient privileges (typically CAP_NET_ADMIN).

Functions

ftype_name (typ, subtype)	Get readable 802.11 frame type/subtype name.
escape_ssid (ssid)	Escape SSID bytes for display.
iftype_name (iftype)	Get readable interface type name.
width_name (width)	Get readable channel width name.
channel_type_name (typ)	Get readable channel type name.
freq_to_channel (freq)	Convert frequency (MHz) to channel number.
freq_to_band (freq)	Convert frequency (MHz) to band.
phy_lookup (name)	Resolve a PHY name (e.g.
add_interface (phy, ifname[, attrs])	Add a wireless interface.
set_interface (ifname[, attrs])	Set wireless interface attributes.
del_interface (ifname)	Delete a wireless interface.
get_interface (ifname)	Get interface info.
get_interfaces ([phy])	Dump interfaces.
scan (action, params)	Scan operations.
wait_event (grp_name, timeout, cb[, data])	Wait for a nl80211 multicast event.
get_surveys (ifname)	Get survey information.
get_noise (ifname)	Get noise level (dBm).
get_station (ifname, mac)	Get station info for a single peer.
get_stations (ifname)	Dump stations on an interface.
get_protocol_features (phy)	Get protocol features bitmask.
get_freqlist (phy)	Get supported frequencies for a PHY.
get_link (ifname)	Get currently associated BSS on an interface.

Tables

interface	Interface info returned by nl80211.get_interface / nl80211.get_interfaces.
bss	BSS info returned by nl80211.scan dump.
survey	Survey info returned by nl80211.get_surveys.
station	Station info returned by nl80211.get_station / nl80211.get_stations.

Functions

ftype_name (typ, subtype)

Get readable 802.11 frame type/subtype name.

Parameters:

• typ int Frame type (one of FTYPE_*).
• subtype int Frame subtype (one of STYPE_*).

Returns:

string or nil name

escape_ssid (ssid)

Escape SSID bytes for display.

Non-printable bytes are escaped as \xNN.

Parameters:

• ssid string or nil Raw SSID bytes.

Returns:

string escaped

iftype_name (iftype)

Get readable interface type name.

Parameters:

• iftype int Interface type (IFTYPE_*).

Returns:

string name

width_name (width)

Get readable channel width name.

Parameters:

• width int Channel width (CHAN_WIDTH_*).

Returns:

string name

channel_type_name (typ)

Get readable channel type name.

Parameters:

• typ int Channel type (CHAN_*).

Returns:

string name

freq_to_channel (freq)

Convert frequency (MHz) to channel number.

Parameters:

• freq int Frequency in MHz.

Returns:

int channel Channel number, or 0 if unknown.

freq_to_band (freq)

Convert frequency (MHz) to band.

Parameters:

• freq int Frequency in MHz.

Returns:

number or string band One of 2.4, 5, 6, 60, or "Unknown".

phy_lookup (name)

Resolve a PHY name (e.g. "phy0") to PHY index.

Reads /sys/class/ieee80211/<name>/index.

Parameters:

• name string PHY name.

Returns:

int or nil phy PHY index.

add_interface (phy, ifname[, attrs])

Add a wireless interface.

phy may be a PHY name (string) or PHY index (number). Supported attrs keys:

• type (int): interface type (IFTYPE_*)
• mac (string): MAC address as "xx:xx:.."
• 4addr (boolean)

Parameters:

• phy string or int PHY name or index.
• ifname string Interface name to create.
• attrs table Optional attributes. (optional)

Returns:

boolean true On success.

Or

1. nil On failure.
2. string Error message.

set_interface (ifname[, attrs])

Set wireless interface attributes.

Uses the same attrs keys as add_interface.

Parameters:

• ifname string Interface name.
• attrs table Attributes. (optional)

Returns:

boolean true On success.

Or

1. nil On failure.
2. string Error message.

del_interface (ifname)

Delete a wireless interface.

Parameters:

• ifname string Interface name.

Returns:

boolean true On success.

Or

1. nil On failure.
2. string Error message.

get_interface (ifname)

Get interface info.

Parameters:

• ifname string Interface name.

Returns:

interface info

Or

1. nil On failure.
2. string Error message.

get_interfaces ([phy])

Dump interfaces.

If phy is provided, filters by PHY index.

Parameters:

• phy int PHY index. (optional)

Returns:

table interfaces Array of interface.

Or

1. nil On failure.
2. string Error message.

scan (action, params)

Scan operations.

• action == 'trigger': trigger scan (ACK)
• action == 'dump': dump scan results (returns array of bss)
• action == 'abort': abort scan (ACK)

params fields:

• ifname (string, required)
• ssids (table, optional): list of SSIDs; pass {''} for wildcard
• freqs (table, optional): list of frequencies in MHz
• ie (string, optional): extra IEs
• keep_elems (boolean, optional): include raw elems in BSS results

Parameters:

• action string One of trigger, dump, abort.
• params table Parameters.

Returns:

boolean or table ok For trigger/abort returns true; for dump returns array of bss.

Or

1. nil On failure.
2. string Error message.

wait_event (grp_name, timeout, cb[, data])

Wait for a nl80211 multicast event.

Subscribes to the given multicast group and receives messages until the callback stops the loop.

The callback cb(cmd, attrs, data) should return:

• true to stop and return success
• false, err to stop and return error
• nil to continue waiting

Parameters:

• grp_name string Multicast group name (e.g. "scan").
• timeout number Timeout in seconds for each receive.
• cb function Callback.
• data any User data passed to callback. (optional)

Returns:

boolean true On success.

Or

1. nil On failure.
2. string Error message.

get_surveys (ifname)

Get survey information.

Parameters:

• ifname string Interface name.

Returns:

table surveys Array of survey.

Or

1. nil On failure.
2. string Error message.

get_noise (ifname)

Get noise level (dBm).

Convenience wrapper over get_surveys.

Parameters:

• ifname string Interface name.

Returns:

int noise Noise in dBm (0 if not available).

Or

1. nil On failure.
2. string Error message.

get_station (ifname, mac)

Get station info for a single peer.

Parameters:

• ifname string Interface name.
• mac string Station MAC address.

Returns:

station info

Or

1. nil On failure.
2. string Error message.

get_stations (ifname)

Dump stations on an interface.

Parameters:

• ifname string Interface name.

Returns:

table stations Array of station.

Or

1. nil On failure.
2. string Error message.

get_protocol_features (phy)

Get protocol features bitmask.

phy may be a PHY name or PHY index.

Parameters:

• phy string or int PHY name or index.

Returns:

int features Bitmask.

Or

1. nil On failure.
2. string Error message.

get_freqlist (phy)

Get supported frequencies for a PHY.

Returns an array of tables with fields:

• band (number)
• freq (int)
• channel (int)
• flags (table)

Parameters:

• phy string or int PHY name or index.

Returns:

table freqlist

Or

1. nil On failure.
2. string Error message.

get_link (ifname)

Get currently associated BSS on an interface.

This performs a scan dump and finds an entry with status of associated (or ibss_joined). If possible, it also augments the BSS table with station statistics (rates, bytes, signal, etc.).

Parameters:

• ifname string Interface name.

Returns:

bss info

Or

1. nil On failure.
2. string Error message.

Tables

interface

Interface info returned by nl80211.get_interface / nl80211.get_interfaces.

Fields:

• phy int PHY index.
• iftype int Interface type (IFTYPE_*).
• ifname string Interface name.
• ifindex int Interface index.
• wdev number Wireless device id.
• mac string MAC address as "xx:xx:xx:xx:xx:xx".
• ssid string|nil SSID (raw bytes) when available.
• freq int|nil Frequency (MHz).
• channel_width int|nil Channel width (CHAN_WIDTH_*).
• channel_type int|nil Channel type (CHAN_*).
• center_freq1 int|nil Center frequency 1.
• center_freq2 int|nil Center frequency 2.
• txpower int|nil TX power level.
• 4addr boolean Whether 4-address mode is enabled.

bss

BSS info returned by nl80211.scan dump.

Fields:

• bssid string BSSID as "xx:xx:..".
• ssid string|nil SSID (raw bytes).
• caps table Capability flags map.
• freq int Frequency (MHz).
• band number|string Band (2.4/5/6/60 or "Unknown").
• channel int Channel number.
• signal number|nil Signal strength (dBm).
• beacon_interval int|nil Beacon interval.
• rsn table|nil RSN information (parsed).
• wpa table|nil WPA information (parsed).
• status string|nil Link status: authenticated/associated/ibss_joined.
• elems table|nil Raw parsed information elements (when keep_elems is true).

survey

Survey info returned by nl80211.get_surveys.

Fields:

• frequency int|nil Frequency (MHz).
• noise int|nil Noise (dBm).
• in_use boolean|nil Whether currently in use.
• active_time number|nil Active time.
• busy_time number|nil Busy time.

station

Station info returned by nl80211.get_station / nl80211.get_stations.

Fields:

• mac string Station MAC address.
• inactive_time int|nil
• connected_time int|nil
• beacon_loss int|nil
• beacon_rx number|nil
• rx_bytes number|nil
• tx_bytes number|nil
• rx_packets int|nil
• tx_packets int|nil
• tx_retries int|nil
• tx_failed int|nil
• signal int|nil
• signal_avg int|nil
• beacon_signal_avg int|nil
• ack_signal int|nil
• ack_signal_avg int|nil
• noise int|nil
• rx_rate table|nil Parsed bitrate table.
• tx_rate table|nil Parsed bitrate table.
• authorized boolean|nil
• authenticated boolean|nil
• associated boolean|nil
• preamble string|nil "short" or "long".
• wme boolean|nil
• mfp boolean|nil