netdevctl

Scan, categorize, and control devices on your local WiFi network.

Features

• Network Scanning - ARP-based device discovery + mDNS service detection
• Auto-Categorization - Identifies device types (phones, laptops, smart TVs, IoT, etc.) via MAC vendor lookup, hostname patterns, and mDNS services
• Device Control - Ping, Wake-on-LAN, port scanning, and nickname management
• Rich CLI - Beautiful terminal output with tables and status indicators
• REST API - FastAPI-powered web API for integration with other tools
• Persistent Storage - Remembers devices across scans with TinyDB

Installation

pip install -e .

Note: Network scanning requires root/sudo privileges for ARP requests.

CLI Usage

# Scan your network
sudo netdevctl scan

# List discovered devices
netdevctl list

# Filter by category
netdevctl list --category phone
netdevctl list --category smart_tv --online

# Ping a device
netdevctl ping 192.168.1.42

# Wake a device via Wake-on-LAN
netdevctl wake AA:BB:CC:DD:EE:FF

# Set a friendly name
netdevctl nickname 192.168.1.42 "Living Room TV"

# Scan open ports
netdevctl portscan 192.168.1.42

# Show all categories
netdevctl categories

# Start the REST API server
netdevctl serve --port 8585

REST API

Start the server with netdevctl serve, then:

# Scan the network
curl -X POST http://localhost:8585/scan

# List all devices
curl http://localhost:8585/devices

# Filter by category
curl http://localhost:8585/devices?category=phone

# Get a specific device
curl http://localhost:8585/devices/192.168.1.42

# Execute a command
curl -X POST http://localhost:8585/command \
  -H "Content-Type: application/json" \
  -d '{"target": "192.168.1.42", "action": "ping"}'

# List available commands
curl http://localhost:8585/commands

Device Categories

Category	Examples
router	Routers, gateways
phone	iPhones, Android phones
laptop	MacBooks, Windows laptops
desktop	iMacs, desktop PCs
tablet	iPads, Android tablets
smart_tv	LG, Samsung, Vizio TVs
smart_speaker	Echo, HomePod, Google Home
smart_home	Nest, Ecobee, Philips Hue
game_console	PlayStation, Xbox, Nintendo
printer	HP, Canon, Epson printers
camera	Ring, Arlo, Wyze cameras
streaming	Chromecast, Roku, Apple TV
iot	ESP32, Tuya, Shelly devices
network_device	Switches, APs, extenders
wearable	Fitbit, Garmin

Architecture

netdevctl/
├── scanner/        # Network discovery (ARP + mDNS)
├── categorizer/    # Device type classification
├── control/        # Command execution (ping, WoL, etc.)
├── api/            # REST API (FastAPI)
├── cli.py          # CLI interface (Typer)
├── models.py       # Pydantic data models
└── store.py        # Persistent device storage (TinyDB)

License

MIT