Documentation

1. Requirements

The host needs very little. If the machine is on your WiFi and stays powered, it will do.

• A 64-bit system: Debian, Ubuntu, Raspberry Pi OS or a derivative. Other distributions work, but these are the tested ones.
• Architecture x86_64 (PC, laptop, mini-PC, NAS) or ARM64 (Raspberry Pi 3, 4 or 5 on a 64-bit system).
• A WiFi adapter joined to a network. The sensor measures the quality of that link, so the machine has to be associated with your router over WiFi, not over Ethernet.
• A Telegram account to receive the alerts.
• Optional: a USB webcam and a microphone if you want photo and audio evidence.

Where to put it

Place it so that anyone walking in passes between the machine and the router — that is where the signal changes most. A hallway, an entrance, or the line from the front door to the living room all work well. Avoid sitting it right next to the router: a signal that strong barely varies, and the sensor loses sensitivity.

2. Installation

If you would rather install it by hand, or you are using a PC instead of a Pi, carry on here. Three commands: the binary carries everything inside, so there is no apt install, no virtual environment, no pip.

Or straight from the machine's terminal. Swap x86_64 for arm64 on a Raspberry Pi:

# 1. Download
curl -L -o viewifi-host \
  https://github.com/pipe9494/viewifi-releases/releases/latest/download/viewifi-host-linux-x86_64

# 2. Make it executable
chmod +x viewifi-host

# 3. Start it
./viewifi-host

On first start the host creates its config folder, measures the WiFi signal for a few seconds to set a baseline, and brings up the web panel. You will see something like this:

Viewifi Host v1.0.0
WiFi interface: wlan0  ·  SSID: MyHome  ·  RSSI: -48 dBm
Calibrating baseline... done
Web panel: http://192.168.1.42:8080

Not sure whether your Pi is 64-bit?

Run uname -m on the machine. If it answers aarch64 you need the ARM64 binary; x86_64 means the other one. If it answers armv7l, your Raspberry Pi OS is 32-bit and you will need to reinstall the 64-bit version of the system.

Trying it without hardware

To see how it behaves before mounting it in place, start it with a simulated signal:

./viewifi-host --sim

It generates fake readings with periodic events, so you can walk through the panel and the alerts without waving at your router.

3. The web panel

Everything is configured from the browser. Open http://DEVICE-IP:8080 from any device on the same network — your phone, your laptop, whatever is at hand. On the machine itself, http://localhost:8080.

The panel shows:

• A live signal chart, with the baseline and the trigger threshold drawn over it. It is the quickest way to understand why it fires, or why it does not.
• Status: armed or disarmed, WiFi interface, SSID, current RSSI and the time of the last detection.
• Buttons to arm, disarm and recalibrate.
• A Telegram test, which sends a sample message to confirm the bot is set up correctly.
• Event history recorded by this host.
• Full configuration: thresholds, protected schedule, evidence, daily digest and account.

Changing the port

If 8080 is already taken by another service, start the host on a different one:

./viewifi-host --port 8099

4. Connecting Telegram

Alerts go to your bot, created by you, with your token. Neither we nor anyone else sees them pass.

Step 1: create the bot

1. Open Telegram and search for @BotFather.
2. Send /newbot and follow the prompts: it asks for a name and a username ending in bot.
3. At the end it gives you a token shaped like this: 7123456789:AAE.... Copy it.

Step 2: get your chat ID

1. Search for @userinfobot in Telegram and send it any message.
2. It replies with your Id, a number like 123456789. That is your chat ID.
3. Send a first message to your own bot (a plain /start). Telegram does not let a bot write to someone who has never written to it.

Step 3: paste it into the panel

In the Telegram section of the panel, paste the token and the chat ID, save, and press Send test. If the message arrives, you are done.

5. Linking your account

This step is optional, but it is what makes the Linux host and the Android app one system rather than two separate things.

If you enter your Viewifi account email and password in the panel, the host:

• Shows up in the app's host list, alongside every other sensor you have.
• Obeys the geofence: when you leave home with your phone it arms itself; when you come back it disarms.
• Receives commands you send from the app to one specific host or to all of them at once.

The password is stored only on that machine, in a file with 600 permissions that only your user can read.

6. Calibration and sensitivity

Every home has a different radio fingerprint, so the host calibrates itself at startup: it listens to the signal for a few seconds with nobody moving and takes that as the baseline. Anything that deviates from it beyond the threshold counts as movement.

When to recalibrate

Press Recalibrate in the panel when you:

• Move the machine or the router.
• Change WiFi network or band.
• Rearrange large, metallic furniture or appliances in between.

Always do it with the place empty, or at least with nobody crossing the watched area.

Tuning the threshold

The panel chart is your best guide: walk through the area and watch how far the line pulls away from its baseline.

7. Running it 24/7

Launching it by hand is fine for testing, but a real sensor has to start with the machine and pick itself up if something fails. That is what the systemd unit is for.

Copy the binary to a system path and create the service:

# Install the executable
sudo cp viewifi-host /usr/local/bin/
sudo chmod +x /usr/local/bin/viewifi-host

# Create the service for your user
sudo tee /etc/systemd/system/viewifi-host@.service > /dev/null <<'EOF'
[Unit]
Description=Viewifi Host
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=%i
ExecStart=/usr/local/bin/viewifi-host
Restart=always
RestartSec=5
MemoryMax=256M
Nice=-5

[Install]
WantedBy=multi-user.target
EOF

# Enable and start it (replace "pi" with your user)
sudo systemctl daemon-reload
sudo systemctl enable --now viewifi-host@pi

Check that it is healthy and read the logs:

systemctl status viewifi-host@pi
journalctl -u viewifi-host@pi -f

8. Bot commands

Send these to your bot from anywhere. You do not need to be on the home network.

What each alert carries

An alert always includes the time, the level (normal or high) and an image of the signal waveform at the moment of the event, where you can see the spike that triggered it. If you enabled evidence, it also carries the photo and the audio clip.

WiFi-drop alarm

If the host is armed and loses its WiFi connection for more than ten seconds, it sends a high-level alert. A network outage while you are watching is not a minor detail: it may be a power cut, but it may also be someone unplugging the router.

9. Photo and audio

Image and sound capture ship switched off. You turn them on by hand, in the panel, and only if you want to.

Photo

You need a USB webcam and one of these two tools:

sudo apt install fswebcam     # lightweight, the recommended one
# or
sudo apt install ffmpeg       # if you already use it for something else

Check the system can see the camera with ls /dev/video*. If /dev/video0 shows up, you are set.

Audio

The clip is recorded with arecord, which comes with alsa-utils:

sudo apt install alsa-utils
arecord -l                    # lists the detected microphones

10. Schedules and routine

Protected schedule

Define the window in which the space should be empty — 11 p.m. to 7 a.m., or Monday to Friday 9 a.m. to 6 p.m. in an office. Inside that window any detection is escalated to high. Outside it, ordinary movement is logged without pinging you, so you never end up muting the bot out of fatigue.

Daily digest

At a time you choose, the bot sends a summary of the day: how many events there were, when they clustered, and whether the sensor was down at any point. It is how you find out everything is working without having to look at anything.

Routine watch

The host learns which time blocks usually have activity and warns you when the pattern breaks. What makes it interesting is that it works both ways: it warns you if there is movement where there never is, and also if there is none where there always was. That second half is what turns Viewifi into a discreet way of knowing that an elderly relative living alone has started their day as usual.

Heartbeat

The host periodically reports that it is still alive. If the heartbeat stops arriving, you know that sensor is off or offline — far better than finding out on the day it mattered.

11. Files and paths

Everything the host creates lives in your home folder. It writes nothing outside it.

Backups

Saving ~/.viewifi/ saves everything. To move the sensor to another machine, copy that folder and start the binary there: it picks the configuration straight back up, though it is worth recalibrating because the new location's radio fingerprint will differ.

Disk space

The local history is not purged automatically: it grows over time, though very slowly, because each event takes a few hundred bytes. Even with constant detections it would take years to become a problem on a Pi's card. If you want to clear it anyway, stop the service and delete events.db; a fresh empty one is created at the next start.

12. Troubleshooting

"No WiFi interface found"

The host looks for the interface three ways: iw dev link, then /proc/net/wireless, and finally iwconfig. If none returns anything, the machine is not on WiFi. Check with iw dev that a wireless interface exists, and with iwconfig that it is associated with your network. Remember: connected over Ethernet does not count.

The panel will not open from another device

Confirm the machine's IP with hostname -I and that you are both on the same network — a phone on the guest network cannot see the rest. If you run a firewall, open the port:

sudo ufw allow 8080/tcp

Telegram alerts never arrive

• Did you send /start to your bot? Without that first message from you, Telegram blocks the bot.
• Check the token is complete, colon included.
• The chat ID is a number; for a group it starts with -100, and the minus sign is part of it.
• Use the panel's test button: it reports exactly what the Telegram API answers.

Too many false alarms

The usual causes are a threshold set too low or a neighbour saturating the channel. Raise the threshold, recalibrate with the place empty, and if it persists, change the router's WiFi channel. A fan or a curtain moved by air conditioning also produces genuine signal variation.

The service restarts in a loop

Read the logs with journalctl -u viewifi-host@YOURUSER -n 50. The most common cause is the service starting before the network is ready; the unit's After=network-online.target prevents that, so check the line is actually there.

Checking that the detection engine itself works

Start the host with --sim: if it detects and alerts correctly on a simulated signal, the problem is in the WiFi reading or the placement, not in the program.

13. Uninstalling

Leave the machine as you found it, with nothing left behind:

# Stop and remove the service
sudo systemctl disable --now viewifi-host@$USER
sudo rm /etc/systemd/system/viewifi-host@.service
sudo systemctl daemon-reload

# Remove the executable
sudo rm /usr/local/bin/viewifi-host

# Remove configuration and history
rm -rf ~/.viewifi

If you linked the account, open the app and delete that host from the list so it stops appearing.