ARP-Scan Device Tracker Integration

A Home Assistant custom integration that tracks devices on your network using ARP (Address Resolution Protocol) scanning. Which works very fast and is very accurate. This integration uses a pure Python implementation - no external arp-scan command required!

Supported Features

• Pure Python: No external dependencies like arp-scan command needed
• GUI Configuration: Easy setup through Home Assistant's UI (no YAML required)
• Auto-detection: Automatically detects network interface and range
• Vendor Lookup: Identifies device manufacturers via OUI database
• Include/Exclude Lists: Filter devices by IP address
• Fast Scanning: Configurable scan intervals and timeouts
• YAML Migration: Automatically imports existing YAML configurations

Device Tracker

The integration created device trackers for each device found on your network. With a status home/not_home.

Entity Attributes

Each tracked device exposes these attributes:

Attribute	Description
mac	MAC address of the device
ip	Current IP address
vendor	Device manufacturer (from OUI database)
last_seen	Timestamp of last detection

Screenshots

Installation

HACS (Recommended)

Alternatively:

1. Ensure HACS is installed
2. Search for "ARPScan" in HACS
3. Click Download
4. Restart Home Assistant
5. Add via Settings → Devices & Services
6. Search for "ARP-Scan" and follow the setup wizard

Manual Installation

1. Copy the custom_components/arpscan_tracker folder to your <config>/custom_components/ directory
2. Restart Home Assistant
3. Add via Settings → Devices & Services

Configuration

GUI Setup

1. Go to Settings → Devices & Services
2. Click + Add Integration
3. Search for "ARPScan"
4. Select your network interface (auto-detected)
5. Optionally adjust the network range, scan interval, and other settings
6. Click Submit

Configuration Options

Option	Default	Description
Network Interface	Auto-detect	Network interface to scan (e.g., eth0, wlan0)
Network Range	Auto-detect	Network in CIDR notation (e.g., 192.168.1.0/24)
Scan Interval	15 seconds	How often to scan for devices (5-300)
Consider Home	180 seconds	Time before marking device as not_home (10-1800)
ARP Timeout	1.0 seconds	Timeout for each ARP request (0.5-10)
Resolve Hostnames	Enabled	Look up device hostnames via reverse DNS
Enable Found Devices	Enabled	Enable newly found device tracker entities by default
Track New Devices	Enabled	Automatically create entities for newly discovered devices
Specific Hosts	Empty	Probe only these IPs (for ZeroTier/VPN networks)
Include IPs	Empty	Only track these IP addresses (comma-separated)
Exclude IPs	Empty	Skip tracking these IP addresses (comma-separated)

Device Name Resolution

When Resolve Hostnames is enabled, the integration performs reverse DNS lookups to find device hostnames:

• If a hostname is found (e.g., skull-nuc), it becomes the entity's display name
• If no hostname is found, the IP address is used as the display name
• Hostnames are cached per scan, so there's minimal performance impact

This is useful for identifying devices by their configured network names rather than just IP addresses.

Options Flow

After initial setup, you can modify settings via:

1. Go to Settings → Devices & Services
2. Find the ARP-Scan integration
3. Click Configure

Note

All device trackers are separate devices—they aren't linked to ARP-Scanner instance by design. If you see devices linked to the ARP-Scanner in the UI, it's Home Assistant linking other known devices because of MAC address matches. When Enable Found Devices is off, new device trackers are added but disabled by default—enable them in the Home Assistant UI. When Track New Devices is off, only previously known devices are tracked—new discoveries are ignored.

Migration from YAML

If you have an existing YAML configuration, it will be automatically imported on first startup after upgrading to version 2.0.0. You'll see a warning in the logs:

YAML configuration for arpscan_tracker is deprecated. Your configuration has been imported. 
Please remove the device_tracker configuration from YAML and restart Home Assistant.

After migration:

1. Remove the YAML configuration from configuration.yaml
2. Restart Home Assistant
3. Manage settings through the UI

Note

known_devices.yaml settings are not migrated. You need to reconfigure the entities in the Home Assistant UI.

Permissions

This integration uses raw sockets to send ARP packets. Depending on your installation type:

Installation	Status
Home Assistant OS	✅ Works out of the box
Supervised	✅ Works out of the box
Container	⚠️ Requires --cap-add=NET_RAW
Core	⚠️ Requires CAP_NET_RAW capability

Docker Example

docker run -d --name homeassistant \
  --cap-add=NET_RAW \
  --network=host \
  -v /path/to/config:/config \
  homeassistant/home-assistant:latest

Troubleshooting

Common Issues

No devices found

1. Verify the correct network interface is selected
2. Check that the network range is correct
3. Ensure Home Assistant has network permissions (see Permissions section)
4. Check logs for permission errors

Permission denied errors

If you see "Permission denied for ARP scan" in the logs:

• Docker: Add --cap-add=NET_RAW to your container
• Core: Run with sudo or add CAP_NET_RAW capability

ZeroTier / VPN networks not detecting devices

ZeroTier and similar VPN solutions intercept ARP broadcasts, so the normal network scan won't find devices. Use the Specific Hosts option to probe individual IPs:

1. Go to Settings → Devices & Services → ARP-Scan → Configure
2. In Specific Hosts (IPs), enter the IP addresses you want to track: 192.168.0.20, 192.168.4.20
3. Click Submit

The scanner will send individual ARP requests directly to those IPs instead of broadcasting to the subnet.

Note

Specific Hosts vs Include IPs:

• Specific Hosts changes how the scanner works (probes only listed IPs)
• Include IPs is a filter on the results (still scans everything, but only tracks listed IPs)

Enable Debug Logging

Enable debug logging in configuration.yaml:

logger:
  default: info
  logs:
    custom_components.arpscan_tracker: debug

Alternatively, enable debug logging via the UI in Settings → Devices & Services → ARP-Scan → Enable debug logging:

Then perform any steps to reproduce the issue and disable debug logging again. It will download the relevant log file automatically.

Automation Examples

Notify When Device Leaves Network

Send a notification when a device has been away for 1 hour:

alias: "Device Left Network"
triggers:
  - trigger: state
    entity_id:
      - device_tracker.arpscan_tracker_1c697a658c2  # Replace with your device
    from: home
    to: not_home
    for:
      hours: 0
      minutes: 10
      seconds: 0
conditions: []
actions:
  - action: notify.mobile_app_phone
    data:
      message: "Device {{ trigger.to_state.name }} has left the network"
mode: single

Notify When Device Comes Online

alias: "Device Connected"
triggers:
  - trigger: state
    entity_id:
      - device_tracker.arpscan_tracker_1c697a658c2
    from: not_home
    to: home
conditions: []
actions:
  - action: notify.mobile_app_phone
    data:
      message: "{{ trigger.to_state.name }} is back online!"
mode: single

Template Sensor: Convert to Online/Offline

Create a binary sensor that shows on/off instead of home/not_home:

# configuration.yaml
template:
  - binary_sensor:
      - name: "Server Online"
        unique_id: server_online_status
        device_class: connectivity
        state: "{{ is_state('device_tracker.arpscan_tracker_1c697a658c2', 'home') }}"
        attributes:
          ip: "{{ state_attr('device_tracker.arpscan_tracker_1c697a658c2', 'ip') }}"
          mac: "{{ state_attr('device_tracker.arpscan_tracker_1c697a658c2', 'mac') }}"
          last_seen: "{{ state_attr('device_tracker.arpscan_tracker_1c697a658c2', 'last_seen') }}"

This creates a binary_sensor.server_online entity with:

• State: on (Connected) / off (Disconnected)
• Device class connectivity for proper UI icons

Turn Off Lights When Everyone Leaves

alias: "Everyone Left - Lights Off"
triggers:
  - trigger: state
    entity_id:
      - device_tracker.arpscan_tracker_phone1
      - device_tracker.arpscan_tracker_phone2
    to: not_home
    for:
      minutes: 10
conditions:
  - condition: state
    entity_id: device_tracker.arpscan_tracker_phone1
    state: not_home
  - condition: state
    entity_id: device_tracker.arpscan_tracker_phone2
    state: not_home
actions:
  - action: light.turn_off
    target:
      entity_id: light.living_room
mode: single

Development

Quick-start (from project root):

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements_lint.txt
./scripts/lint    # runs pre-commit + vulture
# or: ruff check .
# to auto-fix: ruff check . --fix

💖 Support This Project

If you find this library useful for your projects, please consider supporting its continued development and maintenance:

🌟 Ways to Support

• ⭐ Star this repository - Help others discover the project
• 💰 Financial Support - Contribute to development and hosting costs
• 🐛 Report Issues - Help improve stability and compatibility
• 📖 Spread the Word - Share with other developers

💳 Financial Support Options

Why Support?

• Keeps the project actively maintained
• Enables faster bug fixes and new features
• Supports infrastructure costs (testing, AI, CI/CD)
• Shows appreciation for hundreds of hours of development

Every contribution, no matter the size, makes a difference and is greatly appreciated! 🙏

License

This project is licensed under the MIT License - see the LICENSE file for details.

---