Quickstart

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

If you have a ready-made frame, see Set up your frame instead.

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.

Featherframe Cloud: you need an invitation. See Featherframe Cloud.

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 your Featherframe webapp, in Chrome or Edge, click ⋯ in the Frames list, then USB firmware update.
3. Choose your kit. On a self-hosted server, click Open the flasher.
4. Click Connect, and choose your frame's port.
5. Click Install, then enter your Wi-Fi details.

4. Add the frame

• Featherframe Cloud: the frame shows a six-letter code. In the Frames list, click ⋯, then Pair a frame, and enter the code.
• Self-hosted: the frame shows a six-letter code. Connect it to your server, then click Add next to the new frame at the top of the Frames list.

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.

Next: Your frame.