HaWake — Home Assistant Setup

Install the HACS integration

Via HACS (recommended)

In Home Assistant, go to HACS → Integrations → ⋮ → Custom repositories
Add https://github.com/domoretechnet/hawake-hacs and select Integration as the category
Find HaWake Alarm in the HACS store and click Download
Restart Home Assistant

Manual install

Copy custom_components/hawake/ into your HA config/custom_components/ directory
Restart Home Assistant

ℹ️ HACS must be installed in your Home Assistant instance. If you haven't set it up yet, visit hacs.xyz for installation instructions.

Set up your MQTT broker

Create a dedicated MQTT user for the HaWake app and restrict it to only the topics it needs. This keeps the app isolated from the rest of your broker.

Step 2a — Create a dedicated user

Open Settings → Add-ons → Mosquitto broker → Configuration and add a login under the logins key:

Mosquitto broker config

logins:
  - username: hawake
    password: "your_secure_password"
customize:
  active: true
  folder: mosquitto

Save and restart the Mosquitto add-on after making this change.

Step 2b — Create the ACL file

With customize.active: true set above, Mosquitto loads any .conf files in /share/mosquitto/. Create /share/mosquitto/hawake_acl.conf using the File Editor add-on or SSH:

/share/mosquitto/hawake_acl.conf

# HaWake iOS app — restrict to HaWake topics only

user hawake
topic readwrite hawake/#

This grants the hawake user read/write access to every topic under hawake/. Restart the Mosquitto add-on again to apply the ACL.

Direction	Topics covered
App → Broker (publish)	`hawake/{device}/sensor/…` · `hawake/{device}/alarm/…` · `hawake/{device}/availability` · `hawake/{device}/arm/state`
App ← Broker (subscribe)	`hawake/{device}/command/…` · `hawake/{device}/alarm/…/command/…` · `hawake/{device}/arm/command`

💡 Custom prefix? If you use a different topic prefix in the app (e.g. myhome), replace hawake/# with myhome/# in the ACL file.

ℹ️ The HA MQTT integration uses a separate system account with broader broker access. You only need to configure credentials for the iOS app user.

Connect the HaWake app

In the HaWake iOS app, go to Settings → MQTT Settings and enter your broker details:

Field	Value
Host	Your Home Assistant IP address or hostname
Port	`1883` (plain) or `8883` (TLS)
Username	`hawake`
Password	The password you set in Step 2a
Topic Prefix	`hawake` (default)
Device Name	`iPhone` (default — change to identify multiple phones)

🛠 Use the MQTT Payload Builder to generate and test payloads for any command before wiring up automations.

Add the integration in Home Assistant

Go to Settings → Devices & Services → Add Integration
Search for HaWake Alarm and select it
Enter the Device Name and MQTT Topic Prefix — these must exactly match what is set in the HaWake app

ℹ️ Defaults: Device Name = iPhone · Topic Prefix = hawake. You can add multiple devices by adding one integration entry per phone.

What you get

Once connected, the integration creates a main dashboard device and one sub-device per alarm — each packed with entities you can use in automations, dashboards, and scripts.

📊

Sensors

Alarm state, name, fire time, snooze count, app version, sleep sound volume, and more.

🔘

Buttons

Dismiss, snooze, skip, unskip, kill snoozed — on the dashboard device and per-alarm.

🔁

Switches

Master arm toggle, per-alarm enable/disable, alert vibrate, and alert media loop.

🔊

Media Player

Play audio or TTS directly to the phone via play_media and media_announce.

🚨

Notify

Send a full-screen alert to the phone from any HA automation using the notify service.

⏰

Per-Alarm Devices

Each alarm gets its own HA device with full control — time, days, sound, snooze, and more.

📖 See the reference sections below for the full entity list, services, example automations, and MQTT topic details.

📊

Entities & devices

Dashboard sensors

These sensors appear on the main HaWake dashboard device in Home Assistant.

Sensor	Description
Alarm State	`idle` / `ringing` / `snoozed` / `dismissed`
Alarm Name	Name of the currently ringing or next upcoming alarm
Alarm Mission	Mission type required to dismiss (`shake`, `math`, `ha`, `none`)
Alarm Fire Time	Scheduled fire time of the active or next alarm
Alarm Snooze Fire Time	When a snoozed alarm will re-fire
Alarm Sound	Sound ID playing for the active alarm
Alarm Volume	Volume % for the active alarm
Alarm Vibrate	Whether vibration is enabled
Alarm Fade In	Whether fade-in is active
Alarm Notes	Notes attached to the active alarm
Alarm ID	MQTT index of the active alarm
Alarm Snooze Count	Number of times the current alarm has been snoozed
Snoozes Remaining	Snoozes left before alarm is force-dismissed
Alarm Count	Number of active (enabled) alarms
App Version	HaWake app version string
Broker Connection	MQTT connection state reported by the app
Alert Volume	Volume used for HA-triggered alert alarms (%)
Alert Sound	Default sound for HA alert alarms
Alert Vibrate	Whether HA alert alarms vibrate
Alert Loop Media	Whether media audio loops during HA alerts
Alert Loop Delay	Seconds between media audio loops
Quick Alarm	Active quick alarm state
Quick Alarm Fire Time	When the quick alarm fires
Quick Alarm Label	Label of the quick alarm
Quick Alarm Count	Number of active quick alarms
Sleep Sound Volume	Current sleep sounds volume (%)

Binary sensor

Sensor	Description
App Online	`on` when the iOS app is connected to the broker

Per-alarm sensors

For each alarm you create in the app, a dedicated HA device is created containing:

Name · Enabled · State · Fire Time · Snooze Fire Time · Days · Mission · Sound · Snoozes · Volume · Vibrate · Fade In · Notes · Sort Order · Commands · Swipe Left/Right Commands

Buttons

Dashboard buttons act on the currently active alarm:

Button	Action
Dismiss Alarm	Dismiss the ringing or snoozed alarm
Snooze Alarm	Snooze the ringing alarm
Skip Alarm	Skip the next upcoming fire for the active alarm
Unskip Alarm	Remove the skip flag from the next alarm
Delete Next Alarm	Delete the next alarm in the queue
Kill Snoozed Alarm	Immediately end a snoozed alarm session
Sleep Sound Stop / Pause / Resume	Control sleep sounds playback

Per-alarm buttons appear on each alarm's device: Dismiss · Snooze · Skip · Unskip · Kill Snoozed · Delete

Switches

Switch	Description
Arm	Master arm/disarm toggle (HA is source of truth)
Alarm N — Enabled	Enable or disable a specific alarm
Alert Vibrate	Toggle vibration for HA alert alarms
Alert Loop Media	Toggle media looping for HA alert alarms

Media player

Exposes a media player entity for playing audio or TTS to the phone. Supports play_media, media_announce, and volume_set.

Play TTS via media player

service: media_player.play_media
target:
  entity_id: media_player.hawake_iphone
data:
  media_content_id: media-source://tts/cloud?message=Good+morning
  media_content_type: music

Notify

Send a full-screen alert to the phone using the standard HA notify service:

Send a full-screen alert

service: notify.hawake_iphone
data:
  title: "Door Alert"
  message: "Front door opened"
  data:
    sound: "Perimeter_Breach"
    volume: 0.8
    media_url: "http://your-ha.local:8123/local/doorbell.mp3"

⚙️

Services

hawake.update_alarm

Modify an alarm by index or name. All fields except device_name are optional — only the fields you include will be changed.

hawake.update_alarm

service: hawake.update_alarm
data:
  device_name: iPhone        # optional if only one device
  name: "Work Alarm"         # target by name (or use index)
  time: "07:30"
  enabled: true
  days: [1, 2, 3, 4, 5]     # 0=Sunday … 6=Saturday
  sound: "Alarm_Clock"
  volume: 0.8
  snooze_duration: 9
  max_snooze_count: 3
  notes: "Team meeting at 9am"

hawake.trigger_alert

Show a full-screen alert alarm on the phone.

hawake.trigger_alert

service: hawake.trigger_alert
data:
  device_name: iPhone
  title: "Motion Detected"
  message: "Front camera triggered"
  sound: "Perimeter_Breach"
  volume: 0.9
  media_url: "http://ha.local:8123/local/alert.mp3"

hawake.dismiss

Dismiss the currently ringing or snoozed alarm.

hawake.dismiss

service: hawake.dismiss
data:
  device_name: iPhone

hawake.snooze

Snooze the currently ringing alarm.

hawake.snooze

service: hawake.snooze
data:
  device_name: iPhone

hawake.skip

Skip the next fire of the next upcoming alarm.

hawake.skip

service: hawake.skip
data:
  device_name: iPhone

🤖

Example automations

Re-enable a work alarm on Sunday evening

automation.yaml

automation:
  alias: "Re-enable work alarm on Sunday"
  trigger:
    - platform: time
      at: "20:00:00"
  condition:
    - condition: time
      weekday: [sun]
  action:
    - service: hawake.update_alarm
      data:
        name: "Work Alarm"
        enabled: true

Alert phone when front door opens at night

automation.yaml

automation:
  alias: "Front door night alert"
  trigger:
    - platform: state
      entity_id: binary_sensor.front_door
      to: "on"
  condition:
    - condition: time
      after: "22:00:00"
      before: "06:00:00"
  action:
    - service: hawake.trigger_alert
      data:
        title: "Front Door"
        message: "Front door opened"
        sound: "Perimeter_Breach"
        volume: 1.0

Auto-snooze when leaving the bedroom

automation.yaml

automation:
  alias: "Auto snooze when leaving bedroom"
  trigger:
    - platform: state
      entity_id: sensor.hawake_iphone_alarm_state
      to: "ringing"
  action:
    - delay: "00:00:30"
    - condition: state
      entity_id: binary_sensor.bedroom_presence
      state: "off"
    - service: hawake.snooze
      data:
        device_name: iPhone

📡

MQTT topic structure

All topics follow the pattern {prefix}/{device}/…. With default settings, prefix is hawake and device is iphone.

Direction	Topic pattern	Description
App → HA	`hawake/iphone/sensor/{key}`	Dashboard sensor values
App → HA	`hawake/iphone/alarm/{n}/{key}`	Per-alarm sensor values
App → HA	`hawake/iphone/availability`	App online/offline
App → HA	`hawake/iphone/arm/state`	Arm state
HA → App	`hawake/iphone/command/{cmd}`	Dashboard commands
HA → App	`hawake/iphone/alarm/{n}/command/{cmd}`	Per-alarm commands
HA → App	`hawake/iphone/arm/command`	Arm command

🛠 Use the MQTT Payload Builder to interactively construct and copy payloads for any of these topics.

Connect HaWake to Home Assistant.

Install the HACS integration

Set up your MQTT broker

Connect the HaWake app

Add the integration in Home Assistant

What you get

Sensors

Buttons

Switches

Media Player

Notify

Per-Alarm Devices

Entities & devices

Dashboard sensors

Binary sensor

Per-alarm sensors

Buttons

Switches

Media player

Notify

Services

hawake.update_alarm

hawake.trigger_alert

hawake.dismiss

hawake.snooze

hawake.skip

Example automations

Re-enable a work alarm on Sunday evening

Alert phone when front door opens at night

Auto-snooze when leaving the bedroom

MQTT topic structure