Avian Visitors

One Raspberry Pi, one USB lavalier mic. Runs BirdNET-Pi (Cornell's acoustic classifier) 24/7 and builds the live collage as a local website.

Parts list — Station 1

Build steps — Station 1

1. FLASHUse Raspberry Pi Imager → pick Raspberry Pi OS Lite (64-bit). In the customisation dialog set: username, WiFi SSID + password, hostname birdnet, and enable SSH with password auth.
2. MOUNTPlug the USB mic into the Pi. Place it in a window, or mount it outside (weatherproofing needed if so).
3. BOOTInsert the SD card, power on, wait ~60–90 seconds for first boot.
4. SSH INFrom another computer on the same network:

   ssh <your-username>@birdnet.local

5. INSTALLRun the installer:

   curl -s https://raw.githubusercontent.com/Twarner491/AvianVisitors/avian-visitors/newinstaller.sh | bash

   Clones the repo, installs BirdNET-Pi, wires up the collage overlay. Takes 20–40 minutes and reboots automatically when done.
6. DONECollage: http://birdnet.local/ — Stock BirdNET-Pi admin UI: http://birdnet.local/index.php

A second Pi drives a Pimoroni Inky Impression 13.3" e-ink panel, mounted in a wood frame. It screenshots Station 1's collage, mats it, and pushes it to the display every 15 minutes when something changes.

Parts list — Station 2

Build steps — Station 2

1. FLASHSame as Station 1: Raspberry Pi Imager → OS Lite (64-bit) → this time set hostname birdpic, SSH enabled.
2. MOUNTPress the Pi onto the panel's 40-pin header, seat both into the printed backing, power up.
3. SSH IN + CLONE

   ssh <your-username>@birdpic.local
   sudo apt update && sudo apt install -y git
   git clone https://github.com/Twarner491/AvianVisitors
   cd AvianVisitors/frame

4. CHOOSE SOURCEPick how the frame gets its birds, then run one of:

   # Default — pairs with your Station 1 mic on the same network
   ./install.sh
   
   # No mic: pull from BirdWeather for any ZIP code
   ./install.sh --bird-weather --zip 94107
   
   # No mic: follow one specific public BirdWeather station
   ./install.sh --station-id 12345
   
   # Point at a mic hosted at a public URL
   ./install.sh --image-url https://bird.onethreenine.net/frame.png?k=YOUR_FRAME_KEY

   Enables SPI + I2C, installs dependencies and a systemd timer, writes ~/.birdframe/config.toml, reboots once.
5. TUNE (optional)Toggle species-name labels anytime:

   birdframe-names on
   birdframe-names off

   If your frame uses a different mat than the A4/A5 default, set opening in the config file — 0.7071 is the default A5 ratio, up to 0.98 for a bare panel, ~0.84 as a B5 starting point.

Needed if you want a different art style, or your region's birds aren't in the bundled Western-US set.

pip install -r ~/BirdNET-Pi/avian/scripts/requirements.txt
export GEMINI_API_KEY='your-key'

python3 ~/BirdNET-Pi/avian/scripts/pregen.py --labels ~/BirdNET-Pi/model/labels.txt --force
python3 ~/BirdNET-Pi/avian/scripts/cutout.py
python3 ~/BirdNET-Pi/avian/scripts/build_masks.py

# optional region filter (needs EBIRD_API_KEY set)
python3 ~/BirdNET-Pi/avian/scripts/pregen.py --ebird-region US-CA

Community-shared illustration bundles for other regions/styles: illustration-bundles.md — worth checking before generating your own, may save the Gemini cost entirely.