OctoPrint-Fanlight

An OctoPrint plugin that controls an external fan/light controller board over a serial connection, directly from the OctoPrint web interface. It adds a tab with sliders for Fan and Light (4 intensity levels each: 0 = off, 1, 2, 3 = max), and automatically switches the fan on/off based on hotend temperature and print state.

How it works

On OctoPrint startup, the plugin opens the serial port you configure in Settings, fixed at 115200 baud.
Moving a slider sends one ASCII byte to the controller:
- Fan levels 0-3 → '0', '1', '2', '3'
- Light levels 0-3 → 'a', 'b', 'c', 'd'
Slider positions are not persisted across OctoPrint restarts. On every startup the plugin forces the fan off and the light to full brightness. Reopening the tab or reloading the page while OctoPrint keeps running still shows the current (in-memory) levels.

Automatic fan control

The plugin listens to OctoPrint's live temperature stream and print events:

If the hotend temperature rises above a configurable threshold (default 50 °C), the fan is automatically switched to a configurable level (default level 3 / High) — regardless of whether a print is running.
The fan is switched back to off only once both of the following are true:
1. A print has finished (completed, failed, or was cancelled), and
2. The hotend temperature has dropped back to/below the threshold.
This means the fan is intentionally left running through the cool-down period after a print completes, and only turns off once the hotend is cool again.
Automatic control can be turned off entirely in Settings (Automatically control the fan based on hotend temperature). While enabled, moving the fan slider manually still works immediately, but the automation may override it the next time its own conditions trigger.
The current printer state, hotend temperature, and automatic on/off status are shown live in the Fan & Light Control tab (refreshed every 5 seconds, and immediately when the tab is opened).

Installation

Install directly from the folder:
```
pip install /path/to/OctoPrint-Fanlight
```
Or via the OctoPrint web interface: **Settings > Plugin Manager > Get More

...from URL/ZIP** and point it at the zip file.
Restart OctoPrint.
Go to Settings > Fan & Light Controller and set:
- The serial port your controller is connected to (e.g. /dev/ttyUSB0, /dev/ttyACM0, or COM3 on Windows).
- Whether automatic fan control is enabled.
- The hotend temperature threshold (°C).
- The fan level to apply automatically while the hotend is above that threshold.
Open the new Fan & Light Control tab in the main OctoPrint interface to use the sliders and see live status.

Notes

Serial port permissions: on Linux, the user running OctoPrint needs to be in the dialout group (or equivalent) to access the serial port.
Port conflicts: if your controller enumerates as the same port as your printer, double check port in the settings so the plugin doesn't try to open the printer's own connection.
Reconnect logic: if a write fails, the plugin drops its serial handle and will attempt to reopen the port on the next command.
Temperature source: automatic control watches the first hotend (tool0). If your printer has multiple tools/hotends and you'd like a different one (or the highest of several) to drive the fan, that's a small change in _handle_hotend_temperature / on_printer_add_temperature.

File overview

OctoPrint-Fanlight/
├── setup.py
├── README.md
└── octoprint_fanlight/
    ├── __init__.py                       # plugin logic, serial I/O, API, automation
    ├── templates/
    │   ├── fanlight_tab.jinja2           # sliders + live status
    │   └── fanlight_settings.jinja2      # serial port + automation config
    └── static/
        ├── js/fanlight.js                # knockout view model
        └── css/fanlight.css