GPS seems to be designed for outdoor applications where a satellite fix can be obtained such that one of the remaining problems is to derive some indoor positioning system that would work within the confines of a building.

Find3 is a framework that uses Wifi and Bluetooth signal levels (RSSI) from devices relative to each other and then applies statistical methods such as machine learning in order to track devices indoors.

The following is a hopefully complete guide on getting Find3 to work properly within a building including enhancements created by Wizardry and Steamworks.

Find3 has a server component and a client component for Rasperry Pi and Arduino. The Find3 server is meant to run on a standalone machine and does the heavy-lifting by analyzing the data sent by the various clients.

The clients have two modes of operation:

• learning and,
• tracking or scanning

A client (on a Raspberry or Arduino) is meant to be placed at a named location (for instance, a room) and then with the learning mode enabled the client will continuously scan for Wifi and Bluetooth devices and send the BSSIDs to the server. The server then creates a profile for the named location by analyzing the RSSI signals of the various discovered devices and trains a neural net to recognize the named location with a given probability.

After a certain amount of data has been gathered, a client can be switched to the tracking or scanning mode of operation. When a client operates in scanning mode, neighboring Wifi and Bluetooth devices are detected and sent to the server for processing. Based on the learning process, the server then estimates where each scanned device is located.

There are two scanning methods:

• active,
• passive

Where active scanning represents a voluntary scan by the client that looks for nearby devices whereas passive scanning requires a wireless device that supports monitor mode and passively listens to probes from nearby devices. Passive scanning takes longer but has the advantage that the Wifi radio listens instead of actively sending probes to nearby devices.

Find3 already provides a cloud-based server open for everyone but due to privacy concerns the server is best self-hosted. The easiest way is to use Docker and to run a precompiled image for the server.

To install Docker and all required packages, issue:

curl -sSL https://get.docker.com | sh

and then pull the container:

docker pull schollz/find3

Finally, run the server with the Docker command:

docker run -p 1884:1883 -p 8005:8003 \
    -v /opt/find3/FIND_DATA:/data \
    -e MQTT_ADMIN=MQTT_ADMIN_USER \
    -e MQTT_PASS=MQTT_ADMIN_PASSWORD \
    -e MQTT_SERVER='localhost:1883' \
    -e MQTT_EXTERNAL='PUBLIC_IP' \
    -e MQTT_PORT=1884 \
    --name find3server \
    --restart always \
    -d -t schollz/find3

where the following parameters in the command above have to be changed:

• MQTT_ADMIN_USER must be set to an administrative user that will be able to change parameters for the Find3 server,
• MQTT_ADMIN_PASSWORD must be set to the password for the previously suppliedadministrative user,
• PUBLIC_IP should be set to the public IP address of the machine to which applications can connect to the Find3 server

All the rest of the settings must not be changed and it should be well noted that Find3 supplies its own MQTT server such that changing the MQTT_SERVER parameter for the above command is not suggested.

As with most self-hosted solutions, connections via SSL can be ensured with a reverse proxy such as Apache, nginx or caddy.

With the server set up and running, the dashboard can be accessed by navigating to http://SERVER.TLD:8005. The page will require a "family" to be established - essentially, in Find3 terminology, a "family" is a binder or identifier for a set of devices grouped under the same name. As the name would imply, supposing that Find3 would be set up to manage a household, the "family" binder could perhaps be the family name.

At this point, the dashboard will not display much and there will not be much to do until some clients have been set up.

Mind that Find3 supports both Wifi and Bluetooth scanning such that the best device for such a task would be a device that supports both Wifi and Bluetooth BLE. The Raspberry Pi is - particularly, the Raspberry Pi Zero W is a suitable device yet uses more power than an Arduino ESP32 programmable board (an ESP8266 can be used as well, however the ESP8266 lacks a Bluetooth chip and will only be able to scan Wifi signals).

Let's break down the setup for each device suitable to be used with Find3 and summarize the install procedures for the Find3 client.

The Raspberry Pi W has a SoC that supports both Wifi and Bluetooth. The Raspberry Pi W supports setting the Wifi interface to monitor mode with a custom firmware patch named Nexmon. Unfortunately, only a few specific kernels are supported by Nexmon such that an older Linux distribution must be installed on the Raspberry Pi. At the time of writing, Raspbian Jessie is the most compatible Linux distribution that is supported by Nexmon that will allow setting the interface to monitor mode.

To make a very long story short, the following image created by Wizardry and Steamworks can be written to an SD card and then inserted into a Raspberry Pi W with everything working out of the box:

• Raspbian Jessie Find3 Nexmon Image (may need unzipping before being written to an SD card)

The provided image is an official Raspbian Jessie distribution with the Nexmon drivers and the Find3 client installed that will boot and directly start scanning in passive mode whilst uploading the data to a server.

The image assumes that the Raspberry Pi W has a secondary networking device because the Wifi and Bluetooth interfaces will be uniquely dedicated to scanning for Find3. A secondary network interface will be used to transmit the scanned data to Find3. In order to add a secondary network interface to the Raspberry Pi W, the following options are available:

• an ethernet hat for the Raspberry Pi W,
• use RNDIS to provide both power and networking to the Raspberry Pi W.

Alternatively the image can be slightly modified in order to configure the Find3 client to switch between monitor and master mode such that for a given time devices are scanned and then the data is transmitted.

To use the image, edit /etc/systemd/system/find3scanner.service in order to configure some parameters:

[Unit]
Description=Find3 Passive Scanner
After=network.target

[Service]
ExecStartPre=/usr/local/bin/find3-cli-scanner -i mon0 -monitor-mode
ExecStart=/usr/local/bin/find3-cli-scanner -i mon0 -device zoom -family Vault -server http://find.internal:8005 -bluetooth -wifi -forever -passive -no-modify -all-frequencies -all-packets
Restart=always
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=find3
User=root
Group=root
Environment=PATH=/sbin:/usr/sbin:/usr/local/sbin:/bin:/usr/bin/:/usr/local/bin/:
/usr/local/go/bin

[Install]
WantedBy=multi-user.target

where:

• http://find.internal:8005 has to be changed to point to the HTTP address of the Find3 server,
• Vault has to be changed to the name of the "family" configured for the Find3 server,

and,

• -no-modify can be removed in case it is desirable for the Raspberry Pi Wifi interface to switch between monitor and master mode, alternating between scanning and uploading data to the Find3 server.

With the changes made, issue:

systemctl daemon-reload

in order to load the modified changes for the systemd services.

The image is designed and suitable for provisioning other Raspberry Pi W devices: simply load the image up onto an SD card, boot with a Raspberry Pi W, change /etc/systemd/system/find3.service, reload systemd and then reboot.

Compiling Nexmon and the Find3 command line scanner seems to work provided that the Linux distribution installed on the Raspberry Pi is Raspbian Jessie so make sure to download Raspbian Jessie from the Raspbian archives.

Compile instructions and notes for Nexmon in order to be able to set the Raspberry Pi W Wifi to monitor mode are provided on the Raspberry Pi FUSS page and will not be deduplicated here.

To compile the Find3 command line scanner find3-cli-scanner, first download exactly Go version 1.13 since other Go versions will not manage to compile the command line scanner. Go 1.13 can be downloaded from the official golang archives.

The suitable file is named go1.13.linux-armv6l.tar.gz where armv6l is the Raspberry Pi W platform. With the file downloaded, issue:

tar -C /usr/local -xvf go1.13.linux-armv6l.tar.gz

which will create a directory /usr/local/go.

Next, set up the PATH variable to include the go binaries - this can be done temporarily just to compile the Find3 command line scanner find3-cli-scanner or permanently by changing the path globally.

Issue:

export PATH=/usr/local/go/bin:$PATH

in order to temporarily add the Go binaries to the path.

Additionally, temporarily set the Go home where the necessary packages will be installed and compiled:

export GOHOME=/usr/src/go

and then issue:

GO111MODULE=on go get -v github.com/schollz/find3-cli-scanner

which should compile find3-cli-scanner eventually.

After the compilation, you can search for the binary by issuing:

find . -type f -name find3-cli-scanner \;

and then copy the find3-cli-scanner into /usr/local/bin.

Finally, if it is desirable to start the scanner on boot, create a file /etc/systemd/system/find3scanner.service with the following contents:

[Unit]
Description=Find3 Passive Scanner
After=network.target

[Service]
ExecStartPre=/usr/local/bin/find3-cli-scanner -i mon0 -monitor-mode
ExecStart=/usr/local/bin/find3-cli-scanner -i mon0 -device zoom -family Vault -server http://find.internal:8005 -bluetooth -wifi -forever -passive -no-modify -all-frequencies -all-packets
Restart=always
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=find3
User=root
Group=root
Environment=PATH=/sbin:/usr/sbin:/usr/local/sbin:/bin:/usr/bin/:/usr/local/bin/:
/usr/local/go/bin

[Install]
WantedBy=multi-user.target

and make sure to change http://find.internal:8005 to suit your Find3 server address.

Issue:

systemctl daemon-reload
systemctl enable find3scanner.service

to start find3-cli-scanner when the machine boots and restart the device.

Setting up an Arduino device, preferably ESP32 with Bluetooth BLE support, is very much straight-forward. Following the instructions from the original source, download the Arduino script in the code section and upload it to the ESP.

The script should be changed to set LOCATION to the location where the ESP device will be placed and GROUP_NAME should be set to the "family" name.

With clients in place in all locations of the building, all scanned beacons are transmitted to the server where data is processed. The Find3 server can be instructed to learn from detected devices without having to switch the client into learning mode.

For instance, knowing that a certain device will always be found at a certain location, the Find3 dashboard has a "Toggle learning" section where a device can be pinned to a certain location and further analyzed.

The Find3 server interface displays a map of devices in 2D whereas Wifi and Bluetooth works in 3D such that if the Find3 framework is used in an apartment complex then clients will end up scanning devices in 3D and will be unable to display them properly on the map. Nevertheless, the Find3 API can be used to create some custom displays.

The sketch can be found in the arduino repository.