Quickstart

The fastest way from nothing to a picture on your wall. Each step links to its full page.

You need

• A detector: BirdNET-Pi, BirdNET-Go, or a BirdWeather station. See BirdNET hardware.
• A screen: an EE03 or EE02 kit, or a TRMNL, e-reader, or tablet.
• A USB-C cable, and Chrome or Edge on a computer.

1. Set up the server

Choose one. See Install the server.

Hosted: join the waitlist at featherframe.app. You'll get an invitation by email.

On your BirdNET device:

1. SSH into the device, then run:

   git clone https://github.com/wr/featherframe ~/featherframe
   cd ~/featherframe/server
   ./install.sh

2. Open the address the installer prints, for example http://birdnet.local:8181.

On a NAS or home server:

1. Download docker-compose.yml, and set TZ in it to your time zone.

2. In the same folder, run:

   docker compose up -d

3. Open http://<your server>:8181.

2. Connect your detector

1. In your Featherframe webapp, go to Detection source.
2. Choose your detector, and follow its steps in Detection sources.

The Featherframe webapp shows how many detections have arrived.

3. Install the firmware

1. Connect the frame to your computer with a USB-C cable.
2. In the Frames section, click ⋯, then USB firmware update.
3. Click Connect, and choose your frame.
4. Click Install, then enter your Wi-Fi details.

Frames from Wells Workshop come with the firmware installed. See Flash the frame to set their Wi-Fi.

4. Add the frame

• Hosted: the frame shows a six-letter code. In the Frames section, click ⋯, then Pair a frame, and enter the code.
• On your own server: click Add next to the new frame at the top of the Frames section.

See Add a frame.

5. Hang it

1. Put the frame on the wall in portrait orientation.
2. Connect USB-C power.

The frame shows a picture the next time your detector identifies a bird. To show one now, open Tools under the preview, type a species under Manual override, and click Show.

If the frame doesn't show a picture, see Troubleshooting.