raspberry_wifi_scanner package

Submodules

raspberry_wifi_scanner.calculations module

raspberry_wifi_scanner.calculations.convert_dbm_to_mw(dbm: int | float) → float

Convert dBm to value representing milliwatts of power

Parameters:

dbm (int) – numerical value dBm, example -50

Returns:

milliwatts of power

Return type:

float

raspberry_wifi_scanner.calculations.convert_mw_to_dbm(mw: float) → int | float

Convert mW of power representing dBm signal strength

Parameters:

mw (int) – numerical value of mW, example 0.0001

Returns:

dBm signal strength

Return type:

float

raspberry_wifi_scanner.calculations.power_leakage(dbm: int, center_channel: int, valid_channels: list[int], drop_db_per_channel: int = 10, floor_dbm: int = -120, spread: int = 3) → dict[int, float]

Approximate signal leakage onto nearby Wi-Fi channels. This is a very rough estimation suited for 20 MHz channel width and will not be helpful for varied widths.

Parameters:

• dbm (int) – signal level on center channel

• center_channel (int) – channel on which network is located

• valid_channels (list[int]) – list of valid channels for a given area

• drop_db_per_channel (int) – signal level in dbm of expected drop in channel moving away from center channel

• floor_dbm (int) – lowest dbm value, essentially the noise floor

• spread (int) – number of channels away from center that experience power leakage, everything beyond to be valued at floor_dbm

Returns:

key/value of all valid channels and approximate power transmission (mW) on that channel

Return type:

dict[int, float]

raspberry_wifi_scanner.data_collection module

raspberry_wifi_scanner.data_collection.generate_df_from_cells(cells: list[dict[str, str]], location: str | None = None) → DataFrame

Return pandas DataFrame from parsed cells with appropriate dtypes for desired columns, add time and quality_decimal columns

Parameters:

• cells (list[dict[str, str]]) – parsed values from ‘iwlist <interface> scan’

• location (str) – (optional) User defined location, will create additional column

Returns:

Dataframe with columns [“time”, “mac”, “essid”, “channel”, “frequency_GHz”, “signal_dBm”, “quality”, “quality_decimal”] with optional “location”

Return type:

pd.DataFrame

raspberry_wifi_scanner.data_collection.get_cells(iwlist_string: str) → list[str]

Return a list of strings from joined lines for each cell in string output of ‘iwlist (interface) scan’

Parameters:

iwlist_string (str) – string output of ‘iwlist <interface> scan’ command

Returns:

list of raw strings, one for each cell discovered during scan: empty list if nothing found

Return type:

list[str]

raspberry_wifi_scanner.data_collection.get_wireless_interfaces(net_path: str = '/sys/class/net') → list[str] | None

Returns a list of wireless interface names by checking /sys/class/net, or other designated path

Parameters:

net_path (str) – directory for installed network interface

Returns:

list of valid wireless interfaces or None if not found

Return type:

list[str], None

raspberry_wifi_scanner.data_collection.iwlist_command(interface: str = 'get') → str

Return raw string text output of command ‘iwlist <interface> scan’

Parameters:

interface (str) – name of wireless interface or ‘get’ to run get_wireless_interfaces()

Returns:

raw string output of subprocess command

Return type:

str

raspberry_wifi_scanner.data_collection.parse_cells(cells: list[str]) → list[dict[str, str]]

Parse string outputs of cells and return a list of dictionaries for appropriate keys/values

Parameters:

cells (list[str]) – list of raw strings, one for each cell discovered during scan or None

Returns:

list of dictionaries with parsed values for appropriate fields

Return type:

list[dict[str, str]]

raspberry_wifi_scanner.data_collection.scan(interface: str = 'get', location: str | None = None) → DataFrame

Generate a pandas DataFrame by parsing lines from iwlist <interface> scan

Parameters:

• interface (str) – name of wireless interface or ‘get’ to run get_wireless_interfaces()

• location (str) – (optional) User defined location, will create additional column

Returns:

Dataframe with columns [“time”, “mac”, “essid”, “channel”, “frequency_GHz”, “signal_dBm”, “quality”, “quality_decimal”] with optional “location”

Return type:

pd.DataFrame

raspberry_wifi_scanner.dataframe_functions module

raspberry_wifi_scanner.dataframe_functions.dbm_per_channel(df: DataFrame, valid_channels: list[int], overlap: bool = False) → DataFrame

Return a DataFrame that provides overall dBm activity for all channels in the given list, overlap optional.

Parameters:

• df (pd.DataFrame) – Dataframe containing columns [“channel”, “signal_dBm”]

• valid_channels (list[int]) – list of channels to investigate

• overlap (bool) – (Optional) if True, take overlapping channel approximations into account

Returns:

DataFrame with summed values for all provided channels

Return type:

pd.DataFrame

raspberry_wifi_scanner.dataframe_functions.split_by_band(df: DataFrame) → tuple[DataFrame, DataFrame]

Return two dataframes: 2.4 GHz networks and 5/6 GHz networks

Parameters:

df (pd.Dataframe) – Dataframe containing a “channel” column

Returns:

2.4 GHz networks and 5/6 GHz networks

Return type:

tuple[pd.DataFrame, pd.Dataframe]

raspberry_wifi_scanner.dataframe_functions.split_by_mac_list(df: DataFrame, macs_to_include: list[str]) → tuple[DataFrame, DataFrame]

Return to dataframes: one for mac addresses that are included in the list, one for macs that are not. This can be useful to isolate your own network(s) from the local area to analyze channel occupancy, dbm, etc.

Parameters:

• df (pd.DataFrame) – Dataframe containing a “mac” column

• macs_to_include (list[str]) – list of mac addresses in a format matching the scan data: ie [“00:00:00:00:00:00”, …]

Returns:

One DF for rows whose mac address is included in the list, and a second for rows that are not

Return type:

tuple[pd.DataFrame, pd.Dataframe]

raspberry_wifi_scanner.definitions module

raspberry_wifi_scanner.plotting module

raspberry_wifi_scanner.plotting.gaussian_curve(center: int, quality: float, spread: int = 2, step: float = 0.1) → tuple[ndarray, ndarray]

Return a tuple of ndarray (x,y) for plotting approximate curves

Parameters:

• center (int) – channel at which network is centered

• quality (float) – signal quality of the network (typically between 0 and 1)

• spread (int) – number of channels for the curve to reach on either side of center (typically around 2 for 20 MHz width)

• step (float) – increments on the x-axis to calculate, typically a smaller number will produce a smoother curve

Returns:

two arrays of x, y values for plotting

Return type:

tuple[np.ndarray, np.ndarray]

raspberry_wifi_scanner.plotting.plot_curves(df: DataFrame, title: str, spread: int = 2) → Figure

Return a Plotly Figure of plotted curves based on signal_quality column and defined channel spread

Parameters:

• df (pd.DataFrame) – Dataframe containing signal quality and channel columns along with essid for its name

• title (str) – Title of plot

• spread (int) – number of channels on left/right side of center to cover

Returns:

Figure with a curve for every supplied row/network

Return type:

go.Figure

raspberry_wifi_scanner.plotting.plot_over_time(df: DataFrame, y_column: str, category: str, title: str) → Figure

Return a figure of a given column plotted over time based on a given category

Parameters:

• df (pd.DataFrame) – Aggregated/sorted DataFrame recommend to sort_values(by=[‘time’, category]) in advance

• y_column (str) – Given column to plot on the Y-Axis

• category (str) – column name to separate the data into groups for individual traces, examples: “channel”, “mac”, “essid”, etc

• title (str) – Title for the plot

Returns:

A figure with a trace for each unique value in the category column

Return type:

go.Figure

Module contents