py-wifi-helper


Namepy-wifi-helper JSON
Version 2.0.1 PyPI version JSON
download
home_pagehttps://github.com/changyy/py-wifi-helper
SummaryA cross-platform WiFi management tool for Windows, macOS, and Ubuntu
upload_time2024-12-13 12:23:29
maintainerNone
docs_urlNone
authorYuan-Yi Chang
requires_python>=3.10
licenseNone
keywords python wifi interface macos ubuntu windows network wireless
VCS
bugtrack_url
requirements pyobjc-core pyobjc-framework-Cocoa pyobjc-framework-CoreWLAN pywifi comtypes
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # py-wifi-helper

This is a Python tool/library developed for macOS 13.5, Ubuntu 22.04, and Windows 10/11, primarily providing operations for wireless interfaces. It includes functionalities such as listing available wireless interfaces, scanning for WiFi signals using a specified wireless interface, connecting a chosen wireless interface to a specific WiFi access point, retrieving information about the connected WiFi access points for the specified wireless interface, and disconnecting the specified wireless interface.

# Installation

## Dependencies

### Windows
```bash
pip install pywifi comtypes
```

### macOS
```bash
pip install "pyobjc-core>=9.2" "pyobjc-framework-Cocoa>=9.2" "pyobjc-framework-CoreWLAN>=9.2"
```

### Ubuntu
Requires `nmcli` to be installed:
```bash
sudo apt-get install network-manager
```

# Usage

```
% py-wifi-helper --help
usage: py-wifi-helper [-h] [--action {device,scan,connect,disconnect}] [--device DEVICE] [--ssid SSID] [--password PASSWORD] [--scanner-path SCANNER_PATH]

options:
  -h, --help            show this help message and exit
  --action {device,scan,connect,disconnect}
                        command action
  --device DEVICE       interface
  --ssid SSID          ssid
  --password PASSWORD   password
  --scanner-path SCANNER_PATH
                        Path to WiFiScanner.app (macOS only)
```

## Windows

```powershell
> py-wifi-helper
{
    "version": "1.0.0",
    "device": {
        "default": "Intel(R) Wi-Fi 6 AX201 160MHz",
        "list": [
            "Intel(R) Wi-Fi 6 AX201 160MHz"
        ],
        "error": null,
        "select": "Intel(R) Wi-Fi 6 AX201 160MHz"
    },
    "connection": {
        "default": {
            "ssid": "MyWiFi",
            "log": null
        },
        "Intel(R) Wi-Fi 6 AX201 160MHz": {
            "ssid": "MyWiFi",
            "log": null
        }
    },
    "action": {
        "name": "device",
        "status": true,
        "error": null,
        "log": null
    }
}
```

## Ubuntu

```
$ lsb_release -a
No LSB modules are available.
Distributor ID:	Ubuntu
Description:	Ubuntu 22.04.3 LTS
Release:	22.04
Codename:	jammy

$ sudo py-wifi-helper
{
    "version": "1.0.0",
    "device": {
        "default": "wlxd1234567890",
        "list": [
            "wlxd1234567890"
        ],
        "error": null,
        "select": "wlxd1234567890"
    },
    "connection": {
        "default": {
            "ssid": null,
            "log": null
        },
        "wlxd1234567890": {
            "ssid": null,
            "log": null
        }
    },
    "action": {
        "name": "device",
        "status": true,
        "error": null,
        "log": null
    }
}
```

## macOS

### Setup Location Services Permission
Starting from macOS 15+, scanning WiFi networks requires Location Services permission. You need to set up WiFiScanner.app first:

```bash
# Default setup (creates WiFiScanner.app in current directory)
py-wifi-helper-macos-setup

# Or specify a custom location
py-wifi-helper-macos-setup --target-path ~/Applications/WiFiScanner.app
```

After setup, you'll need to:
1. Allow Location Services access when prompted
2. Or manually enable Location Services for WiFiScanner in System Settings > Privacy & Security > Location Services

### Basic Usage

```
% sw_vers
ProductName:		macOS
ProductVersion:		13.5
BuildVersion:		22G74

% py-wifi-helper
{
    "version": "1.0.0",
    "device": {
        "default": "en0",
        "list": [
            "en0"
        ],
        "error": null,
        "select": "en0"
    },
    "connection": {
        "default": {
            "ssid": "MyHomeWIFIAP",
            "log": null
        },
        "en0": {
            "ssid": "MyHomeWIFIAP",
            "log": null
        }
    },
    "action": {
        "name": "device",
        "status": true,
        "error": null,
        "log": null
    }
}
```

For scanning operations, you can either use the default WiFiScanner.app location or specify a custom path:
```bash
# Use default WiFiScanner.app location
py-wifi-helper --action scan

# Use custom WiFiScanner.app location
py-wifi-helper --action scan --scanner-path ~/Applications/WiFiScanner.app
```

### Examples

#### Scan for WiFi Networks
```bash
py-wifi-helper --action scan
```

#### Connect to WiFi
```bash
py-wifi-helper --action connect --ssid "MyWiFi" --password "12345678"
```

#### Disconnect from WiFi
```bash
py-wifi-helper --action disconnect
```

#### Use Specific Interface
```bash
py-wifi-helper --action scan --device "wlan0"
```

# Notes

- Windows requires administrator privileges for some operations
- Ubuntu requires sudo for network operations
- macOS requires Location Services permission for WiFi scanning (set up using `py-wifi-helper-macos-setup`)

# Platform Support

- Windows 10/11 (via pywifi)
- macOS 13.5+ (via CoreWLAN)
- Ubuntu 22.04+ (via nmcli)

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/changyy/py-wifi-helper",
    "name": "py-wifi-helper",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": null,
    "keywords": "python, wifi, interface, macos, ubuntu, windows, network, wireless",
    "author": "Yuan-Yi Chang",
    "author_email": "<changyy.csie@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/e5/ef/ac46cf0b942c020139d590745d0a064241f8a7c8a146cd7018b2dfe0aec9/py_wifi_helper-2.0.1.tar.gz",
    "platform": null,
    "description": "# py-wifi-helper\n\nThis is a Python tool/library developed for macOS 13.5, Ubuntu 22.04, and Windows 10/11, primarily providing operations for wireless interfaces. It includes functionalities such as listing available wireless interfaces, scanning for WiFi signals using a specified wireless interface, connecting a chosen wireless interface to a specific WiFi access point, retrieving information about the connected WiFi access points for the specified wireless interface, and disconnecting the specified wireless interface.\n\n# Installation\n\n## Dependencies\n\n### Windows\n```bash\npip install pywifi comtypes\n```\n\n### macOS\n```bash\npip install \"pyobjc-core>=9.2\" \"pyobjc-framework-Cocoa>=9.2\" \"pyobjc-framework-CoreWLAN>=9.2\"\n```\n\n### Ubuntu\nRequires `nmcli` to be installed:\n```bash\nsudo apt-get install network-manager\n```\n\n# Usage\n\n```\n% py-wifi-helper --help\nusage: py-wifi-helper [-h] [--action {device,scan,connect,disconnect}] [--device DEVICE] [--ssid SSID] [--password PASSWORD] [--scanner-path SCANNER_PATH]\n\noptions:\n  -h, --help            show this help message and exit\n  --action {device,scan,connect,disconnect}\n                        command action\n  --device DEVICE       interface\n  --ssid SSID          ssid\n  --password PASSWORD   password\n  --scanner-path SCANNER_PATH\n                        Path to WiFiScanner.app (macOS only)\n```\n\n## Windows\n\n```powershell\n> py-wifi-helper\n{\n    \"version\": \"1.0.0\",\n    \"device\": {\n        \"default\": \"Intel(R) Wi-Fi 6 AX201 160MHz\",\n        \"list\": [\n            \"Intel(R) Wi-Fi 6 AX201 160MHz\"\n        ],\n        \"error\": null,\n        \"select\": \"Intel(R) Wi-Fi 6 AX201 160MHz\"\n    },\n    \"connection\": {\n        \"default\": {\n            \"ssid\": \"MyWiFi\",\n            \"log\": null\n        },\n        \"Intel(R) Wi-Fi 6 AX201 160MHz\": {\n            \"ssid\": \"MyWiFi\",\n            \"log\": null\n        }\n    },\n    \"action\": {\n        \"name\": \"device\",\n        \"status\": true,\n        \"error\": null,\n        \"log\": null\n    }\n}\n```\n\n## Ubuntu\n\n```\n$ lsb_release -a\nNo LSB modules are available.\nDistributor ID:\tUbuntu\nDescription:\tUbuntu 22.04.3 LTS\nRelease:\t22.04\nCodename:\tjammy\n\n$ sudo py-wifi-helper\n{\n    \"version\": \"1.0.0\",\n    \"device\": {\n        \"default\": \"wlxd1234567890\",\n        \"list\": [\n            \"wlxd1234567890\"\n        ],\n        \"error\": null,\n        \"select\": \"wlxd1234567890\"\n    },\n    \"connection\": {\n        \"default\": {\n            \"ssid\": null,\n            \"log\": null\n        },\n        \"wlxd1234567890\": {\n            \"ssid\": null,\n            \"log\": null\n        }\n    },\n    \"action\": {\n        \"name\": \"device\",\n        \"status\": true,\n        \"error\": null,\n        \"log\": null\n    }\n}\n```\n\n## macOS\n\n### Setup Location Services Permission\nStarting from macOS 15+, scanning WiFi networks requires Location Services permission. You need to set up WiFiScanner.app first:\n\n```bash\n# Default setup (creates WiFiScanner.app in current directory)\npy-wifi-helper-macos-setup\n\n# Or specify a custom location\npy-wifi-helper-macos-setup --target-path ~/Applications/WiFiScanner.app\n```\n\nAfter setup, you'll need to:\n1. Allow Location Services access when prompted\n2. Or manually enable Location Services for WiFiScanner in System Settings > Privacy & Security > Location Services\n\n### Basic Usage\n\n```\n% sw_vers\nProductName:\t\tmacOS\nProductVersion:\t\t13.5\nBuildVersion:\t\t22G74\n\n% py-wifi-helper\n{\n    \"version\": \"1.0.0\",\n    \"device\": {\n        \"default\": \"en0\",\n        \"list\": [\n            \"en0\"\n        ],\n        \"error\": null,\n        \"select\": \"en0\"\n    },\n    \"connection\": {\n        \"default\": {\n            \"ssid\": \"MyHomeWIFIAP\",\n            \"log\": null\n        },\n        \"en0\": {\n            \"ssid\": \"MyHomeWIFIAP\",\n            \"log\": null\n        }\n    },\n    \"action\": {\n        \"name\": \"device\",\n        \"status\": true,\n        \"error\": null,\n        \"log\": null\n    }\n}\n```\n\nFor scanning operations, you can either use the default WiFiScanner.app location or specify a custom path:\n```bash\n# Use default WiFiScanner.app location\npy-wifi-helper --action scan\n\n# Use custom WiFiScanner.app location\npy-wifi-helper --action scan --scanner-path ~/Applications/WiFiScanner.app\n```\n\n### Examples\n\n#### Scan for WiFi Networks\n```bash\npy-wifi-helper --action scan\n```\n\n#### Connect to WiFi\n```bash\npy-wifi-helper --action connect --ssid \"MyWiFi\" --password \"12345678\"\n```\n\n#### Disconnect from WiFi\n```bash\npy-wifi-helper --action disconnect\n```\n\n#### Use Specific Interface\n```bash\npy-wifi-helper --action scan --device \"wlan0\"\n```\n\n# Notes\n\n- Windows requires administrator privileges for some operations\n- Ubuntu requires sudo for network operations\n- macOS requires Location Services permission for WiFi scanning (set up using `py-wifi-helper-macos-setup`)\n\n# Platform Support\n\n- Windows 10/11 (via pywifi)\n- macOS 13.5+ (via CoreWLAN)\n- Ubuntu 22.04+ (via nmcli)\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "A cross-platform WiFi management tool for Windows, macOS, and Ubuntu",
    "version": "2.0.1",
    "project_urls": {
        "Download": "https://pypi.org/project/py-wifi-helper/",
        "Homepage": "https://github.com/changyy/py-wifi-helper"
    },
    "split_keywords": [
        "python",
        " wifi",
        " interface",
        " macos",
        " ubuntu",
        " windows",
        " network",
        " wireless"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "86166358b75570862be3d272be79f94fb7de13b465a1f49805f67fded236eb27",
                "md5": "db90466f62df96e4a4c12ba27c273882",
                "sha256": "470da0addea3582e1faf92582366967998634b21a4d87f69ad67eab0316785e1"
            },
            "downloads": -1,
            "filename": "py_wifi_helper-2.0.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "db90466f62df96e4a4c12ba27c273882",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 25104,
            "upload_time": "2024-12-13T12:23:27",
            "upload_time_iso_8601": "2024-12-13T12:23:27.118031Z",
            "url": "https://files.pythonhosted.org/packages/86/16/6358b75570862be3d272be79f94fb7de13b465a1f49805f67fded236eb27/py_wifi_helper-2.0.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "e5efac46cf0b942c020139d590745d0a064241f8a7c8a146cd7018b2dfe0aec9",
                "md5": "1ee3db405894fad0960a1152b2a10688",
                "sha256": "681a283c28a5c7794e95600a54a51efd7a1763c9859397be1b8254643b19ee55"
            },
            "downloads": -1,
            "filename": "py_wifi_helper-2.0.1.tar.gz",
            "has_sig": false,
            "md5_digest": "1ee3db405894fad0960a1152b2a10688",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 22044,
            "upload_time": "2024-12-13T12:23:29",
            "upload_time_iso_8601": "2024-12-13T12:23:29.184967Z",
            "url": "https://files.pythonhosted.org/packages/e5/ef/ac46cf0b942c020139d590745d0a064241f8a7c8a146cd7018b2dfe0aec9/py_wifi_helper-2.0.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-12-13 12:23:29",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "changyy",
    "github_project": "py-wifi-helper",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [
        {
            "name": "pyobjc-core",
            "specs": [
                [
                    ">=",
                    "10.3"
                ]
            ]
        },
        {
            "name": "pyobjc-framework-Cocoa",
            "specs": [
                [
                    ">=",
                    "10.3"
                ]
            ]
        },
        {
            "name": "pyobjc-framework-CoreWLAN",
            "specs": [
                [
                    ">=",
                    "10.3"
                ]
            ]
        },
        {
            "name": "pywifi",
            "specs": [
                [
                    ">=",
                    "1.1.12"
                ]
            ]
        },
        {
            "name": "comtypes",
            "specs": [
                [
                    ">=",
                    "1.2.0"
                ]
            ]
        }
    ],
    "lcname": "py-wifi-helper"
}
        
Elapsed time: 0.49344s