Metadata-Version: 2.4
Name: raspberry-wifi-scanner
Version: 0.1.0
Summary: Scanning Local Wi-Fi Networks with Raspberry Pi
Author-email: Caleb Yourison <caleb.yourison@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Caleb Yourison
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        
Project-URL: homepage, https://github.com/calebyourison/raspberry_scanner
Keywords: raspberry,wifi,scan
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: plotly>=6.0.0
Requires-Dist: template-log-parser>=0.8.0
Dynamic: license-file

# raspberry-wifi-scanner: Identify and Analyze Local Wi-Fi Networks with Raspberry Pi
---
This project is designed with Raspberry Pi's portability in mind, though many of the functions could also be used on other Debian based systems.

The primary objective is aid in the Wi-Fi optimization process, ideally by scanning the local area every so often to see which channels are the best choice for your network.  
You can take samples in different locations around your site to gauge performance.

Generally speaking, it is recommended to disconnect from any Wi-Fi networks prior to scanning.

Feel free to modify the code to fit your use case.

**Ensure that you are acting in accordance with local regulations regarding wireless activity and that scanning via wireless interfaces is permitted.  
Do not use these tools to violate the privacy of others, or for any other malicious purposes.**

#### Getting Started
---

```bash
pip install raspberry-wifi-scanner
```

By default, the `scan()` function will attempt to determine a valid wireless interface.  On Raspberry, this is often wlan0.

It is recommended to designate one explicitly. Call a function to see a list of discovered interfaces.

The scan function will parse the contents of "iwlist <interface> scan" into a pandas DataFrame.

```bash
from raspberry_wifi_scanner import get_wireless_interfaces, scan

interfaces = get_wireless_interfaces()

local_networks = scan(interface="wlan0", location="My Front Door")

print(local_networks.columns)
Index(['time', 'mac', 'essid', 'channel', 'frequency_GHz', 'signal_dBm', 'quality', 'quality_decimal', 'location'])
```

If desired, the data can be further separated and plotted to see a visual display:

```bash
from raspberry_wifi_scanner.dataframe_functions import split_by_band, split_by_mac
from raspberry_wifi_scanner.plotting import plot_curves

local_2_4_GHz, local_5_6_GHz = split_by_band(df=local_networks)

fig_all_2_4 = plot_curves(df=local_2_4_GHz, title="All Channel Usage On 2.4 GHz Band")

my_network_macs = ["00:00:00:00:00:00", "11:11:11:11:11:11"]

my_networks, local_noise = split_by_mac(df=local_2_4_GHz, macs_to_include=my_network_macs)

fig_local_noise = plot_curves(df=local_noise, title="Channel Usage On 2.4 GHz Band Excluding My Networks")

fig_all_2_4.show()
fig_local_noise()
```

Observe transmission power on a band of channels over time:

```bash
import pandas as pd

from raspberry_wifi_scanner import scan
from raspberry_wifi_scanner.dataframe_functions import split_by_band, dbm_per_channel
from raspberry_wifi_scanner.plotting import plot_over_time

one = scan(interface="wlan0")
time.sleep(60)
two = scan(interface="wlan0")
time.sleep(120)
three = scan(interface="wlan0")

valid_2_4_channels = [1,2,3,4,5,6,7,8,9,10,11]
dbm = []
for df in [one, two, three]:
    two_four_GHz, five_GHz = split_by_band(df)

    dbm_calcs = dbm_per_channel(df=two_four_GHz, valid_channels=valid_2_4_channels)
    dbm_calcs['time'] = df['time'].max()
    dbm.append(dbm_calcs)
    
dbm_calculations = pd.concat(dbm)

fig = plot_over_time(df=dbm_calculations, y_column="overall_dBm", category="channel", title="2.4 GHz Overall dBm Per Channel Over Time")

fig.show()

```

## DISCLAIMER
**Prior to using wireless tools such as these or any others, please confirm the regulations in your area.
Some jurisdictions have strict policies and might consider this to be surveillance.  
If required, it is recommended to aggregate the data by signal strength, channel usage, etc. and discard information that could be tied to a specific entity.
This project is not responsible for any misuse or abuse, nor does it condone such practices.**
