Ws2mqtt

ws2mqtt - WiSafe2 to MQTT gateway

ws2mqtt is an inofficial gateway to connect WiSafe2 smoke, heat and CO detectors to your smart home.

The gateway consists of an ESP32 module that handles Wifi and MQTT communication and integrates with Home Assistant through MQTT auto discovery. It is connected to an Arduino that acts as an SPI/UART converter. The Arduino talks to an official WiSafe2 module that is connected to your smoke detector network.

Disclaimer

This project is not related to or endorsed by the manufacturer of WiSafe2 devices. It is an unofficial hobby project.

:warning: DO NOT USE THIS PROJECT FOR SAFETY-CRITICAL PURPOSES! :warning:

This is a hobby project after all, so do not rely on it for your personal safety or the saftey of others. Always assume that it will not work in a case of emergency, and plan your emergency procedures accordingly. As the license states in more detail, I won't be liable for any damages incurred by this project.

Pictures

Supported devices

Tested:

• ST-630-DE(P) Smoke detector
• HT-630-EUT Heat detector

Not tested, but should be working:

• WST-630 Smoke alarm
• W2-CO-10X CO alarm
• FP1720W2-R Smoke alarm
• FP2620W2-R Smoke alarm

Features

• Smoke / heat detector states:
  • Smoke / heat detected
  • Battery state
  • Radio module battery state
  • Device attached to base
• Test button detection
• Combined test button / detection event (see Tips & troubleshooting)
• Test all devices from Home Assistant

TODO:

• Test single device from Home Assistant
• Logging via MQTT
• ESP32 over-the-air updates

Additional Hardware required

• ESP32-DevKitC V4
• Arduino Pro Mini, or chinese clone
• WiSafe2 module
• A 868 MHz antenna, e.g. stripped from a defective detector. Alternatively, an 8.8 cm long wire
• Custom PCB (see PCB folder). Alternatively, lots of breadboard wires (see schematic)

Setup

• Setup Arduino
  • Mount Arduino to PCB
  • Flash Arduino firmware (see Firmware-Atmega folder) via programmer
• Setup ESP32
  • Mount ESP32 to PCB
  • Configure your secrets in Firmware-ESP/include/credentials.h (see example)
  • Flash ESP32 firmware (see Firmware-ESP folder) via USB
• Power board via ESP32 USB connector
• Setup WiSafe2 module
  • Mount WiSafe2 module to PCB
  • Join WiSafe2 network
    • Push button on module for 5 seconds
    • Module LED should light up
    • Within 5 seconds, push test button on a different detector
    • Module LED should blink multiple times as a confirmation
• Mount ESP32, Arduino and WiSafe2 module on PCB
• Configure Home Assistant
  • The gateway and all detectors should be visible in the "Devices" tab
  • Create an automation that listens for the alarm event emitted by the gateway, see below

Tips & troubleshooting

• The recommended way to react to smoke detection and test events in Home Assistant is to listen to the alarm event emitted by the ws2mqtt Bridge device. This event is fired when any of the connected detectors detects smoke, or when any of the detectors' test buttons is pressed. This way you can test your emergency scenes and automations by pressing a detector's test button.

• The "smoke detected" sensor shows an unknown state

  This is actually a deficiency of the WiSafe2 protocol. As far as I know, there is no way to query a device for the current smoke / heat detector state. Additionally, a "smoke detected" message is only sent once to other detectors, and not repeated later. So if you start the gateway while a "smoke detected" event is ongoing, there is no way for the gateway to know about that event. I decided to err on the side of caution and show the state of devices as "unknown".

• The "battery" sensor, "docked" sensor etc. show an unknown state

  To conserve battery power, the gateway does not actively query the state of these diagnostic sensors. The sensor state is only updated on change. The easiest way to force an update is to remove a detector from its base, wait a bit, and re-mount the device. This should update not only the "docked" sensor, but also the battery ones.

• What is the programming language you used, and why is it not perfect C?

  C is not my mother tongue, so it's nearly certain that there are race conditions, buffer overflows or bad C programming practices in the code. Feel free to file an issue to point things out, or even better file a pull request.

License

See LICENSE.

Final notes

Shout out to C19HOP and his WiSafe2-to-HomeAssistant-Bridge, for helping in reversing the protocol, and for giving me the motivation to finish this project I've been working on for the last months.