🐦 Fugleramme: An 1800s-Style E-Ink Bird Observer

Fugleramme is a specialized e-ink display system designed for the Raspberry Pi. It utilizes local AI to listen for bird calls in real-time and transforms those detections into a beautiful, curated gallery of 19th-century natural history illustrations.

The window is a bit dirty because squirrels keep raiding the bird feeder.

⚠️ Development Note: This project is currently in its early stages. You may encounter the occasional bug or unpolished feature, but more updates are on the way.

You can view a live instance running from a kitchen window in Bergen, Norway, at fugleramme.arnegiacomo.dev.

---

⚙️ How It Works

The system operates as a pipeline where audio is converted into visual art.

1. Detection: BirdNET-Go monitors audio via a microphone and identifies the species.
2. Processing: Fugleramme polls the API, finds the corresponding historical illustration, and arranges the birds on a textured digital page.
3. Rendering: The display updates only when the bird composition changes.
4. Management: An admin panel allows for configuration and automated updates.

Pro Tip: While an e-ink panel is recommended for the aesthetic, it isn't mandatory. You can run the project in web-only mode via HDMI or any network-connected device.

---

🛠️ Hardware Specifications

To build this, the author used the following setup:

For a comprehensive list of parts and alternatives, visit the Hardware Docs.

---

🎨 The Artistry

The core appeal of Fugleramme is its use of public-domain natural history plates.

• Curation: Over 800 hand-cut illustrations covering 400+ species.
• Authenticity: No AI-generated art is used (though some AI was used for retouching).
• Logic: Birds are placed based on their physical size. The layout follows a rough mathematical heuristic where the visual scale $S$ is proportional to the body mass $M$: $\text{Scale} \propto \sqrt{M}$ Larger birds are generally positioned toward the center of the page.
• Coverage: Currently optimized for the British Isles, Germany, and Scandinavia. North American and broader European sets are currently in development.

---

🚀 Installation & Deployment

💻 Local Development

If you are developing locally, use uv for environment management:

uv sync 
# Start a mock detector on port :8090
uv run fugleramme-fake-detector 
# Start the service on port :8080 with hot-reload
uv run fugleramme-dev 

🍓 Raspberry Pi Setup

Run the following command directly on your Pi:

curl -fsSL https://raw.githubusercontent.com/arnegiacomo/fugleramme/main/install.sh | bash

The installer will:

• Ask for BirdNET-Go location and port settings.
• Clone the repository.
• Install dependencies.
• Configure the frame as a systemd service.

🐳 Docker Deployment

Run the frame as a container:

docker run -d -p 8080:8080 -v fugleramme:/data \
  -e FUGLERAMME_DETECTOR_URL=http://birdnet.local:8080 \
  ghcr.io/arnegiacomo/fugleramme

• Kiosk: :8080
• Admin: :8080/admin
• Persistence: /data

---

📚 Inspiration & Ecosystem

Fugleramme was inspired by a WWF poster by Axel Thorenfeldt, the "live-frame" concept from AvianVisitors, and the detection capabilities of BirdNET-Go.

Similar Projects (No shared code/art):

• AvianVisitors: BirdNET-Pi with AI/photo cutouts.
• inky-bird-frame: Field-journal style on Inky panels.
• HABirdDashboard: Home Assistant collage cards.
• belkins-birdnet: Kachō-e style AI illustrations.

---

🤝 Contributing & Legal

Contributions regarding bug fixes, documentation, and new artwork are highly encouraged!

How to engage:

1. Bugs? $\rightarrow$ File a bug report.
2. Questions/Ideas? $\rightarrow$ Check the FAQ, then use Discussions.
3. Fixes/Art? $\rightarrow$ Open a Pull Request (PR) directly.

Licensing

Detection: BirdNET-Go is licensed under CC BY-NC-SA 4.0 (Non-commercial). The model is provided by the Cornell Lab of Ornithology and Chemnitz University of Technology, with taxonomy from eBird.org.

Artwork: Each style folder contains specific terms; manifests link back to the original plates. General license: MIT for code, CC BY-SA 4.0 for art.