wifi-presence

README

wifi-presence

The wifi-presence program provides presence detection based on WiFi client activity. This functionality can be useful for home automation. It is intended to be run on a Linux-based router, typically using OpenWRT/LEDE.

The program uses the nl80211 interface (package wifi) in order to receive information about WiFi clients connected to a router.

It exposes a basic TCP line-based interface to allow clients to receive events when a Wifi station connects or disconnects, and also to query the AP for information on connected WiFi stations.

Usage

$ ./wifi-presence -h
Usage of ./wifi-presence:
  -addr string
    	address to accept client requests (default ":5566")

API

All messages are JSON encoded. Messages are wrapped in a generic structure:

{
    "type": "string indicating message type",
    "data": <type-dependent data strucure>
}

• dump\n: Request all WiFi stations

  Example:

  $ echo "dump" | nc 192.168.1.1 5566
  

  Example response:

  {
     "data" : [
        {
           "wifi" : {
              "inactive" : 8588000000,
              "transmit-failed" : 0,
              "received-packets" : 35213,
              "transmit-bitrate" : 144400000,
              "received-bytes" : 1121660,
              "beacon-loss" : 0,
              "interface" : {
                 "mac" : "XX:XX:XX:XX:XX:XX",
                 "device" : 2,
                 "phy" : 1,
                 "type" : 3,
                 "name" : "wlan1",
                 "frequency" : 2412,
                 "index" : 23
              },
              "connected" : 881741000000000,
              "transmit-retries" : 34,
              "received-bitrate" : 1000000,
              "signal" : -36,
              "transmitted-packets" : 5288,
              "mac" : "XX:XX:XX:XX:XX:XX",
              "transmitted-bytes" : 461361
           },
           "ip" : "192.168.1.3"
        },
        {
           "ip" : "192.168.1.106",
           "wifi" : {
              "beacon-loss" : 0,
              "received-bytes" : 233450736,
              "mac" : "XX:XX:XX:XX:XX:XX",
              "transmitted-bytes" : 933813681,
              "transmitted-packets" : 4430335,
              "transmit-retries" : 351509,
              "signal" : -49,
              "received-bitrate" : 11000000,
              "interface" : {
                 "index" : 23,
                 "frequency" : 2412,
                 "name" : "wlan1",
                 "type" : 3,
                 "phy" : 1,
                 "device" : 2,
                 "mac" : "XX:XX:XX:XX:XX:XX"
              },
              "connected" : 229724000000000,
              "transmit-failed" : 1288,
              "inactive" : 1468000000,
              "transmit-bitrate" : 130000000,
              "received-packets" : 8203571
           }
        }
     ],
     "type" : "dump-response"
  }
  

• get $MAC\n: Request a WiFi station based on MAC address

  Example:

  $ echo "get XX:XX:XX:XX:XX:XX" | nc 192.168.1.1 5566
  

  Example response:

  {
     "data" : {
        "ip" : "192.168.1.106",
        "wifi" : {
           "transmitted-packets" : 4440036,
           "mac" : "XX:XX:XX:XX:XX:XX",
           "received-packets" : 8218227,
           "beacon-loss" : 0,
           "transmit-bitrate" : 144400000,
           "transmit-failed" : 1297,
           "transmit-retries" : 352343,
           "inactive" : 544000000,
           "received-bitrate" : 11000000,
           "connected" : 231136000000000,
           "received-bytes" : 235828738,
           "signal" : -47,
           "interface" : {
              "type" : 3,
              "index" : 23,
              "device" : 2,
              "phy" : 1,
              "frequency" : 2412,
              "mac" : "XX:XX:XX:XX:XX:XX",
              "name" : "wlan1"
           },
           "transmitted-bytes" : 938348025
        }
     },
     "type" : "get-response"
  }
  

• Unsolicited events will be sent to connected clients for station connect and disconnect events.

  Example connect event:

  {
     "type" : "station-event",
     "data" : {
        "action" : "connect",
        "station" : {
           "wifi" : {
              "transmit-failed" : 0,
              "transmit-bitrate" : 0,
              "transmitted-packets" : 0,
              "received-bytes" : 0,
              "signal" : 0,
              "connected" : 0,
              "interface" : {
                 "name" : "wlan0",
                 "phy" : 0,
                 "type" : 3,
                 "index" : 21,
                 "mac" : "XX:XX:XX:XX:XX:XX",
                 "frequency" : 5500,
                 "device" : 2
              },
              "mac" : "XX:XX:XX:XX:XX:XX",
              "inactive" : 0,
              "transmitted-bytes" : 0,
              "transmit-retries" : 0,
              "received-bitrate" : 0,
              "beacon-loss" : 0,
              "received-packets" : 0
           },
           "ip" : "192.168.1.100"
        }
     }
  }
  

  Example disconnect event:

  {
     "type" : "station-event",
     "data" : {
        "action" : "disconnect",
        "station" : {
           "wifi" : {
              "received-bitrate" : 24000000,
              "connected" : 85504000000000,
              "received-packets" : 335588,
              "transmitted-bytes" : 957580351,
              "transmitted-packets" : 706268,
              "inactive" : 4000000,
              "interface" : {
                 "frequency" : 5500,
                 "device" : 2,
                 "name" : "wlan0",
                 "phy" : 0,
                 "index" : 21,
                 "type" : 3,
                 "mac" : "XX:XX:XX:XX:XX:XX"
              },
              "received-bytes" : 74319550,
              "transmit-failed" : 0,
              "transmit-retries" : 0,
              "signal" : -49,
              "mac" : "XX:XX:XX:XX:XX:XX",
              "beacon-loss" : 0,
              "transmit-bitrate" : 6000000
           },
           "ip" : "192.168.1.100"
        }
     }
  }
  

Build

Example command to build wifi-presence for an OpenWRT router. This requires Go and upx to be installed. Upx is optional and is used to compress the binary for space-constrained environments.

GOARCH=mips GOOS=linux GOMIPS=softfloat \
  go build \
    -a \
    -ldflags="-s -w" \
    -o wifi-presence && \
  upx --ultra-brute -9 -qq wifi-presence