Wifi monitor that utilizes nmap and AT&T M2X to track devices connected to a local network
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
master.py strip all whitespace in APIKEY May 26, 2016



PyFi Logo

A Python 3 based network monitor that utilizes nmap to report devices connected to a local network and sends that information to AT&T M2X.

See https://pyfi.herokuapp.com to see PyFi data being displayed by the PyFi-Web demo flask application.

What you need

  • Familiarity with the AT&T M2X API.
  • Raspberry Pi running RaspBian or another unix system capable of running nmap v6.01+.
  • A free AT&T M2X Account.


  • Python3 running on your chosen machine
  • pip3 for installing Python 3 version of packages
  • nmap installed on your machine - written for v6.01+
  • Python packages outlined in requirements.txt


  1. Clone this repository

  2. In keys.txt replace <MASTER_API_KEY> with your master api key. You can obtain your Master API Key from your M2X Account Settings.

  3. Install dependencies:

    $ sudo apt-get update; sudo apt-get install -y python3 nmap python3-pip
    $ pip3 install -r requirements.txt
  4. From within the PyFi root folder run:

    $ sudo python3 master.py
  5. Log in to M2X, access your device, and you will see data about your local wifi network!

** If something does go wrong, check errors.log in the directory containing master.py

Optional: Run as a service using systemd

First, check if your system is using systemd. You'll know by running man init and seeing which program's man page you end up on.

The unit file included in this repo (pyfi.service) can be used by systemd to run PyFi as a service that start on system start-up and will auto restart in the event of an unforseen crash. Follow the instructions given in the file to customize it for your setup.

Then follow these steps:

  1. Copy pyfi.service to default location used by systemd.

    $ cp /home/pi/pyfi-monitor-m2x/pyfi.service /lib/systemd/system/pyfi.service
  2. Set correct permissions on the unit file.

    $ chmod 644 /lib/systemd/system/pyfi.service
  3. Load the service into systemd.

    $ sudo systemctl daemon-reload
    $ sudo systemctl enable pyfi.service
  4. Now PyFi will automatically start when your machine boots or manually start it using sudo systemctl start pyfi. You can check on it's status with sudo systemctl status pyfi and stop it with sudo systemctl stop pyfi.


Make sure the version of nmap installed is at least v6.01 or else reading MAC addresses will not be possible.

If you are running Raspbian on a Raspberry Pi, the easiest way to go about it is to run Raspbian Jessie instead of Raspbian Wheezy. This way the packages installed with apt-get are all up to date.

A common issue installing netifaces with pip is that you are missing header files for python. If this happens try installing python3-dev on your machine (sudo apt-get install python3-dev).


This library is released under the MIT license. See LICENSE for the terms.