README.md

prometheus_dyson

Prometheus client for DysonLink fans (e.g; Pure Hot+Cool and Pure Cool).

This code supports Dyson Pure Cool and Pure Hot+Cool fans. This supports both the V1 model (reports VOC and Dust) and the V2 models (those that report PM2.5, PM10, NOx, and VOC). Other Dyson fans may work out of the box or with minor modifications.

Updating instructions for 0.2.0

Due to changes in Dyson's Cloud API, automatic device detection based on your Dyson login/password no longer works reliably.

This means you need to take a one-time manual step to upgrade. The upside to this is that it removes the runtime dependency on the Dyson API, because it will cache the device information locally.

The manual step is to run this command and follow the prompts:

% /opt/prometheus-dyson/bin/main --create_device_cache

Build

% bazel build :main

If you'd like a Debian package:

% bazel build :main-deb

Without Bazel

Tip: a Python virtual environment is a very useful tool for keeping dependencies local to the project (rather than system-wide or in your home directory). This is optional and not required.

You'll need these dependencies:

% pip install libdyson
% pip install prometheus_client

Metrics

Environmental

Name	Type	Availability	Description
dyson_humidity_percent	gauge	all	relative humidity percentage
dyson_temperature_celsius	gauge	all	ambient temperature in celsius
dyson_volatile_organic_compounds_units	gauge	all	volatile organic compounds (range 0-10)
dyson_dust_units	gauge	V1 fans only	dust level (range 0-10)
dyson_pm25_units	gauge	V2 fans only	PM2.5 units (µg/m^3 ?)
dyson_pm10_units	gauge	V2 fans only	PM10 units (µg/m^3 ?)
dyson_nitrogen_oxide_units	gauge	V2 fans only	Nitrogen Oxide (NOx) levels (range 0-10)

Operational

Name	Type	Availability	Description
dyson_fan_mode	enum	all	AUTO, FAN, OFF (what the fan is set to)
dyson_fan_power	enum	all	ON if the fan is powered on, OFF otherwise
dyson_auto_mode	enum	all	ON if the fan is in auto mode, OFF otherwise
dyson_fan_state	enum	all	FAN, OFF (what the fan is actually doing)
dyson_fan_speed_units	gauge	all	0-10 (or -1 if on AUTO)
dyson_oscillation_mode	enum	all	ON if the fan in oscillation mode, OFF otherwise
dyson_oscillation_state	enum	all	ON, OFF, IDLE. ON means the fan is currently oscillating, IDLE means the fan is in auto mode and the fan is paused
dyson_oscillation_angle_low_degrees	gauge	V2 fans only	low angle of oscillation in degrees
dyson_oscillation_angle_high_degrees	gauge	V2 fans only	high angle of oscillation in degrees
dyson_night_mode	enum	all	ON if the fan is in night mode, OFF otherwise
dyson_night_mode_speed	gauge	V2 fans only	maximum speed of the fan in night mode
dyson_heat_mode	enum	all heating fans	HEAT, OFF (OFF means "in cooling mode")
dyson_heat_state	enum	all heating fans	only HEAT, OFF (what the fan is actually doing)
dyson_heat_target_celsius	gauge	all heating fans	target temperature (celsius)
dyson_focus_mode	enum	V1 heating only	ON if the fan is providing a focused stream, OFF otherwise
dyson_quality_target_units	gauge	V1 fans only	air quality target (1, 3, 5?)
dyson_filter_life_seconds	gauge	V1 fans only	seconds of filter life remaining
dyson_carbon_filter_life_percent	gauge	V2 fans only	percent remaining of the carbon filter
dyson_hepa_filter_life_percent	gauge	V2 fans only	percent remaining of the HEPA filter
dyson_continuous_monitoring_mode	gauge	V2 fans only	continuous monitoring of air quality (ON, OFF)

Usage

Configuration

This script reads config.ini (or another file, specified with --config) for your DysonLink login credentials.

Device Configuration

Devices must be specifically listed in your config.ini. You can create this automatically by running the binary with --create_device_cache and following the prompts. A device entry looks like this:

[XX1-ZZ-ABC1234A]
active = true
name = My Fan
serial = XX1-ZZ-ABC1234A
version = 21.04.03
localcredentials = a_random_looking_string==
autoupdate = True
newversionavailable = True
producttype = 455

Manual IP Overrides

By default, fans are auto-detected with Zeroconf. It is possible to provide manual IP overrides in the configuraton however in the Hosts section.

[Hosts]
XX1-ZZ-ABC1234A = 10.10.100.55

Args

% ./prometheus_dyson.py --help
usage: ./prometheus_dyson.py [-h] [--port PORT] [--config CONFIG] [--create_device_cache] [--log_level LOG_LEVEL]

optional arguments:
  -h, --help            show this help message and exit
  --port PORT           HTTP server port
  --config CONFIG       Configuration file (INI file)
  --create_device_cache
                        Performs a one-time login to Dyson's cloud service to identify your devices. This produces
                        a config snippet to add to your config, which will be used to connect to your device. Use
                        this when you first use this program and when you add or remove devices.
  --log_level LOG_LEVEL
                        Logging level (DEBUG, INFO, WARNING, ERROR)

Scrape Frequency

Environmental metrics are updated at approximately 30 second intervals. Fan state changes (e.g; FAN -> HEAT) are published ~immediately on change.

Dashboard

I've provided a sample Grafana dashboard in grafana.json.