NanoLeaf Sunlight Simulator

NanoLeaf Sunlight Simulator by Quicksilver Industries LTD. is an experimental, local-first controller for Nanoleaf lighting. It combines direct device controls with a weather-aware automation engine that makes indoor panels follow the daylight that would arrive through a real window.

The application can run from the command line or as a browser dashboard. Its primary deployment target is a Raspberry Pi on the same LAN as the Nanoleaf device.

[!IMPORTANT] This is an independent, experimental third-party project. It is not affiliated with, sponsored, endorsed, authorized, or supported by Nanoleaf Canada Ltd. Before pairing or controlling a device, read the official Nanoleaf support instructions for your exact model and review Nanoleaf's hardware warranty terms. Incorrect or unsupported changes can cause unexpected operation, make a device temporarily or permanently inoperable, damage hardware, and may affect or void warranty coverage. Use this software at your own risk.

Dashboard preview

The dashboard brings the current daylight simulation, device state, manual controls, and diagnostics into one LAN-accessible interface. See the dashboard gallery for the automation and device-control views. Published screenshots use sanitized example values.

What it does

• Controls power, brightness, color, color temperature, and saved effects.
• Computes the sun's elevation and azimuth for a configured location.
• Adjusts brightness for the window's compass orientation.
• Uses blue-hour, golden-hour, daylight, and nighttime lighting profiles.
• Modulates the result using current cloud cover and weather from Open-Meteo.
• Applies smooth, one-minute transitions to the Nanoleaf device.
• Automatically resumes the correct state after a device disconnect.
• Pauses automation for one hour when a person makes a direct dashboard change.
• Prevents two simulator processes on the same host from controlling the lights.
• Exposes a responsive LAN dashboard with a live house, location, orientation, weather, and simulated-light visualization.

Requirements

• Python 3.10 or newer
• A Nanoleaf device on the same local network
• Internet access for live weather (optional)
• Linux with systemd for the documented Raspberry Pi service deployment

Quick start

Create a virtual environment and install the published package:

python3 -m venv venv
venv/bin/python -m pip install --upgrade pip
venv/bin/python -m pip install nanoleaf-ctl

For development from a source checkout, replace the final command with venv/bin/python -m pip install -e ".[dev]" from the repository root.

Find and pair with the Nanoleaf:

venv/bin/nanoleaf-ctl discover
venv/bin/nanoleaf-ctl pair <device-ip>

Immediately before running pair, follow Nanoleaf's current, model-specific instructions to open the device's third-party or local-API pairing window. Do not assume one button sequence or hold duration applies to every model. Start with Nanoleaf's official pairing guidance and support site. Pairing stores the device IP and token in ~/.config/nanoleaf-ctl/config.json with owner-only permissions. See Device safety and third-party notice before proceeding.

Start the dashboard:

venv/bin/nanoleaf-ctl web --port 5000

Then open http://<server-name-or-ip>:5000/ from another device on the LAN. The web process automatically starts the sunlight automation using the defaults in nanoleaf_ctl/sunlight.py.

Common commands

nanoleaf-ctl info
nanoleaf-ctl on
nanoleaf-ctl off
nanoleaf-ctl brightness 60
nanoleaf-ctl color "#ffd29b"
nanoleaf-ctl color-temp 4000
nanoleaf-ctl effects
nanoleaf-ctl effect "Northern Lights"
nanoleaf-ctl sunlight --preview
nanoleaf-ctl sunlight --lat 34.13 --lon -84.34 --facing southwest

Run nanoleaf-ctl <command> --help for the complete arguments accepted by a command.

Raspberry Pi service

The included nanoleaf.service uses a generic dedicated service account:

• user: nanoleaf
• checkout: /opt/nanoleaf
• virtual environment: /opt/nanoleaf/venv
• private state: /var/lib/nanoleaf
• dashboard: port 5000

Replace OWNER in the clone URL with the repository owner. If the deployment account or paths differ, edit the unit before installing it. See Installation and deployment for the complete, verified procedure.

Documentation

Important security note

The dashboard and HTTP API do not authenticate users. They are intended only for a trusted home LAN. Do not expose port 5000 directly to the public internet. The Nanoleaf token is equivalent to a device password; never paste the config file or an unredacted device URL into an issue or chat.

Tests

venv/bin/python -m pytest -q

Brand policy

The MIT License covers the software, but it does not grant permission to brand forks, modified versions, products, or services as Quicksilver Industries or Quicksilver Industries LTD., or to imply endorsement or affiliation. Factual references to the project's origin are permitted. See Brand and trademark policy.

License

MIT. See LICENSE.