This project allows controlling various Dream Maker fans through MQTT. The implementation is rather simple and just bridges between MQTT and the Dream Maker JSON protocol. The fan must be disconnected from the cloud for this.
Supported fans:
- Dream Maker Smart Fan DM-FAN01
- Dream Maker Smart Fan DM-FAN02-W (battery-powered version)
Warning: This is just a proof-of-concept which has been created within a few hours. Don't expect anything fancy: neither in functionality nor in style! 😄
dmiot2mqtt will provide the same interface (with a subset of features) that the official Dream Maker cloud server offers. This way the fans will "think" that they are talking to their usual Chinese control servers. No software modifications on the fan are required.
For this to work you need to have control over your local DNS. You need to alter the DNS record for cloud1.dm-maker.com to return the IP address of the machine running dmiot2mqtt.
This is what you need in order to get started:
- Control over your local DNS (e.g. through your router or through Pi Hole)
- Python 3.9 (or later) with aiomqtt (Version 2.2 or later)
- A MQTT broker
- Ideally an always-on machine which will run dmiot2mqtt (e.g. a Raspberry Pi)
- A static IP adress for your Dream Maker Smart Fan (IP will be used in MQTT topic), unless you use
topic_id = device_id(see below) - Recommended: Any Linux machine with a Bluetooth 4.0+ dongle for provisioning the fan without the Dream Maker app (one-time only)
- Pick a machine which will host
dmiot2mqtt.py. It's recommended to create a new Python venv and runpip3 install -r requirements.txtinside. - Create a DNS record which points
cloud1.dm-maker.comto the machine runningdmiot2mqtt.py. - Adjust the config file
dmiot2mqtt.iniaccording to your needs. - Run the service through
python3 dmiot2mqtt.py -c /path/to/dmiot2mqtt.ini. - If your fan is still unprovisioned, use the
provision.pyscript from this repository to push your WiFi information to the fan. - Wait until your fan connects to the service.
- Create a systemd unit file for dmiot2mqtt.py according to your needs.
Instead of steps 1, 4 and 7 above you can run the bridge as a container. Images for amd64, arm64 and armv7 (e.g. a Raspberry Pi) are published to ghcr.io/lukaszkusgithub/dmiot2mqtt for every version tag.
Put your dmiot2mqtt.ini next to docker-compose.yml and run:
docker compose up -d
The container reads its config from /config/dmiot2mqtt.ini and listens on port 31270, which must be reachable from the fans under the address that cloud1.dm-maker.com resolves to.
Inside the container localhost is the container itself, so set server to the broker's real address.
Without init: true (or docker run --init) the bridge runs as process 1 and ignores the stop signal, so docker stop takes 10 seconds.
Options in dmiot2mqtt.ini:
| section | option | default | explanation |
|---|---|---|---|
mqtt |
server |
localhost |
MQTT broker hostname |
mqtt |
port |
1883 |
MQTT broker port. With use_ssl = 1 this is usually 8883 |
mqtt |
base_topic |
dmiot2mqtt |
Prefix of all topics |
mqtt |
user, password |
none | Broker credentials |
mqtt |
use_ssl |
0 |
Connect to the broker over TLS, verifying its certificate against the system CAs |
mqtt |
retain |
0 |
Publish the fan state as retained message, so Home Assistant knows it right after a restart |
mqtt |
topic_id |
ip |
Identify a fan in the topic by ip or by device_id. See the note below |
mqtt |
discovery |
1 |
Announce each fan to Home Assistant through MQTT discovery, see Home Assistant integration |
mqtt |
discovery_prefix |
homeassistant |
Discovery prefix of the Home Assistant MQTT integration |
bridge |
read_timeout |
90 |
Seconds without any data before a fan connection is treated as dead, 0 or less disables it. The 10-second heartbeat in doc/protocol.md is not verified for every model: if a fan (e.g. the battery-powered DM-FAN02-W) is dropped every read_timeout seconds, raise the value |
With topic_id = device_id the fan does not need a static IP. This only works for fans that were provisioned through the official Dream Maker app and cloud: they keep the unique device id they got there. Fans provisioned through provision.py and this bridge all get the same all-zero device id; for those the bridge falls back to the IP address and logs a warning.
Topics per fan (<id> is the fan's IP address, or its device id with topic_id = device_id):
dmiot2mqtt/<id>: full fan state as JSONdmiot2mqtt/<id>/command: commands, one JSON object per message, e.g.{"power": 1}dmiot2mqtt/<id>/availability:online/offline, retained, also set as MQTT last willdmiot2mqtt/<id>/diagnostics: WiFi signal and firmware versions from the fan's heartbeat as JSON, retained, e.g.{"signal": 94, "rf_version": "v3.1.6", ...}. A change of the firmware versions is published at once, a change of the signal alone at most every 5 minutes.
The bridge keeps the fan connection open while the broker is unavailable and reconnects after 5 seconds, doubling the delay up to 60 seconds. The last state received in the meantime is published after the reconnect.
Each fan gets a fixed MQTT client id, dmiot2mqtt- followed by its topic with / replaced by -.
Two bridge instances connected to the same broker therefore need different base_topic values.
When a fan reconnects (e.g. after losing WiFi) while its old connection is still open, the old connection is closed.
Two different fans behind one IP address (NAT) share a topic unless topic_id = device_id is used. If they report different device ids, the bridge keeps both connections and logs an error, but with topic_id = ip commands then reach both fans; use topic_id = device_id or give them different IP addresses. Fans provisioned through provision.py and this bridge all report the same all-zero device id and cannot be told apart at all, so behind one IP address they replace each other's connection over and over; they need different IP addresses.
A connection without any data for read_timeout seconds is treated as dead; the fans send a heartbeat every 10 seconds.
The tests start a local mosquitto broker and talk to the bridge through a simulated fan:
pip3 install -r requirements-dev.txt
python3 -m pytest tests
Tests that need the broker are skipped when mosquitto is not installed.
With discovery = 1 (the default) and the Home Assistant MQTT integration connected to the same broker, every fan shows up in Home Assistant on its own, as a device of the MQTT integration. Its entities:
| entity | type | field |
|---|---|---|
| the fan itself | fan |
power, speed, roll_enable (oscillation), mode (preset direct, natural, smart) |
| Oscillation angle | select |
roll_angle |
| Off timer | number, 0 to 480 minutes |
power_delay |
| LED indicators, Button sounds, Child lock | switch |
light, sound, child_lock |
| Temperature, Humidity | sensor |
temperature, humidity |
| WiFi signal | diagnostic sensor, firmware versions as attributes |
signal on the diagnostics topic |
The discovery messages are retained and published again whenever the bridge connects to the broker. When Home Assistant reports on homeassistant/status (with your discovery_prefix) that it has started, the bridge publishes them again together with the last fan state, so Home Assistant knows the state even without retain = 1.
Temperature and humidity come with the fan's state update. doc/protocol.md describes that update after a change of the fan's status; how often a fan sends one when only the temperature changes is not documented, so the sensors may stay empty until the first change or command.
Setting the speed to 0 turns the fan off. The fan accepts one field per command, so turning it on at a given speed takes two commands; Home Assistant sends them one after the other.
If you added the fan manually with the YAML config below before, remove that config or set discovery = 0, otherwise every entity appears twice.
With topic_id = ip a fan that gets a new IP address appears as a new device; delete the old one in Home Assistant.
Without discovery you can integrate the fan manually. You can use this config as an example, just adjust the MQTT topic names according to your fan's IP address:
mqtt:
fan:
- name: "DreamMaker Fan"
unique_id: "mqtt_fan_dmfan01"
availability_topic: "dmiot2mqtt/192.168.100.5/availability"
command_topic: "dmiot2mqtt/192.168.100.5/command"
command_template: '{ "power": {{ value }} }'
oscillation_command_topic: "dmiot2mqtt/192.168.100.5/command"
oscillation_command_template: '{ "roll_enable": {{ value }}}'
oscillation_state_topic: "dmiot2mqtt/192.168.100.5"
oscillation_value_template: "{{ value_json.roll_enable }}"
state_topic: "dmiot2mqtt/192.168.100.5"
state_value_template: "{{ value_json.power }}"
payload_on: "1"
payload_off: "0"
payload_oscillation_on: "1"
payload_oscillation_off: "0"
percentage_command_topic: "dmiot2mqtt/192.168.100.5/command"
percentage_command_template: '{ "speed": {{value}} }'
percentage_state_topic: "dmiot2mqtt/192.168.100.5"
percentage_value_template: "{{ value_json.speed }}"
json_attributes_topic: "dmiot2mqtt/192.168.100.5"
preset_modes:
- direct
- natural
- smart
preset_mode_command_template: '{% if value == "natural" %}{"mode":1}{% elif value == "smart" %}{"mode":2}{% else %}{ "mode":0}{% endif %}'
preset_mode_command_topic: "dmiot2mqtt/192.168.100.5/command"
preset_mode_state_topic: "dmiot2mqtt/192.168.100.5"
preset_mode_value_template: '{% if value_json.mode == 1 %}natural{% elif value_json.mode == 2 %}smart{% else %}direct{% endif %}'
select:
- command_topic: "dmiot2mqtt/192.168.100.5/command"
command_template: '{ "roll_angle": {{value|int}} }'
name: "DreamMaker Fan Angle"
options:
- "30"
- "60"
- "90"
- "120"
- "140"
state_topic: "dmiot2mqtt/192.168.100.5"
value_template: "{{ value_json.roll_angle }}"
unique_id: mqtt_fan_dmfan01_angle