🌀 What is FanBridge?

FanBridge is a lightweight Docker service that connects your Unraid server’s drive temperatures to an external microcontroller (Arduino / RP2040).

The microcontroller generates Intel-spec PWM signals to control 4-pin fans, while FanBridge handles all the logic, UI, and integration.

Designed to run unprivileged on Unraid with simple device mappings — no need for --privileged.

---

✨ Features

• Drive → PWM mapping with custom fan curves, overrides, and exclusions

• Web UI with tabs for Drives, Config, Serial Tools, and Logs

• USB serial integration (auto-detects /dev/serial/by-id)

• Commands supported: PING, STATUS, VERSION, TEST, PWM set (0–100%)

• Secure UI with login/password, CSRF protection, and rate limiting

• Logging system with filters, in-UI view, and download option

• Prometheus metrics available at /metrics

• Unraid aware: parses disks.ini for temperature data

---

📦 Installation (Unraid)

1. Install via Community Applications or add manually:

   Repository: ghcr.io/robro92/fanbridge:latest

2. Map your device(s):

   • Preferred: /dev/serial/by-id/usb-...

   • Alternative: /dev/ttyACM0 or /dev/ttyUSB0

     Add via template: Device → Add Device → pick your microcontroller

3. Map Unraid’s disks.ini:

   • Host: /var/local/emhttp/disks.ini

   • Container: /unraid/disks.ini (Read-only)

4. Optional environment variables:

   • FANBRIDGE_SERIAL_PORT=/dev/serial/by-id/usb-...

   • FANBRIDGE_SERIAL_BAUD=115200

   • FANBRIDGE_SECURE_COOKIES=1 (enable if reverse proxy w/ HTTPS)

5. Apply and start the container.

6. Access WebUI → http://[Unraid-IP]:8080/

   • First run will prompt you to create an admin user.

---

🔧 Configuration

• Drives Tab → view temperatures, spin status, toggle exclusions

• Config Tab → set fan curves, apply thresholds, enable auto-apply

• Serial Tab → PING / STATUS / VERSION tools + PWM slider

• Logs Tab → live logs, filters, clear + download

---

🔐 Security

• Password-protected UI

• CSRF protection on POST endpoints

• Security headers + Content Security Policy

• Runs unprivileged (no need for --privileged)

---

📈 Metrics

Basic Prometheus endpoint at /metrics includes:

• fanbridge_http_requests_total{method,code}

• fanbridge_serial_commands_total{kind,status}

• fanbridge_serial_open_failures_total

---

🛠 Troubleshooting

• “Operation not permitted” on /dev/ttyACM0

  → Make sure you added the device, not bind-mounted the path.

• Serial not found

  → Map /dev/serial/by-id read-only and use that path.

• Logs empty

  → Use download function (live buffer only stores recent entries).

---

💬 Support & Feedback

Use this thread for support, questions, and feature requests.

Please include logs (/api/logs/download) and container config if reporting an issue.

Edited September 12, 2025Sep 12 by RoBro92

This seems pretty cool but I can't seem to figure out which microcontrollers are going to work with it without plugging one in and installing it. Any chance you could provide a list of supported hardware and some suggestion as to how the fans are intended to be wired?

12 hours ago, ailstyn said:

This seems pretty cool but I can't seem to figure out which microcontrollers are going to work with it without plugging one in and installing it. Any chance you could provide a list of supported hardware and some suggestion as to how the fans are intended to be wired?

Hi Thank you for your post, apologies this support forum is pretty sparce all info is available on the Github for the projet. I am planning to build a dedicated custom PCB for this but for now you can cobble it together with a few resistors, a BJT transistor and a cheap fan hub.

It is designed to work with a rp2040 microcontroller it has been working flawlessly for me for many months. I'd appreciate if you could try it out and let me know how you get on with it.

https://github.com/RoBro92/fanbridge

I'll order a couple pieces and give it a shot but I've got a couple questions. It looks like on the wiring diagram that each pin goes to one fan, you tie tach to ground, and let the board supply power from the SATA cable? How do you assign pins to fans then?