A Home Assistant custom integration for controlling scent and aroma diffusers via Bluetooth or WiFi.
Supports devices using the Aroma-Link and Aroma Buddy apps.

• Bluetooth (BLE) - Fully local control, no cloud account needed, all features including fan control
• WiFi / Cloud - Control via Aroma-Link cloud API, works from anywhere, no Bluetooth required
• Connect-on-Demand - BLE connects only when sending commands, frees the adapter for other devices
• Automatic Time Sync - Device clock synced on every connection
• Schedule Management - Set spray schedules via dashboard or automations
• Multiple Devices - Add as many diffusers as you want

Most waterless cold-air nebulizing scent/aroma diffusers that use the Aroma-Link or Aroma Buddy apps should work. These are sold under various brand names on Amazon and AliExpress.

Have a working device not listed here? Please open an issue to let us know!

1. Click the button above, or in Home Assistant go to HACS > Integrations > three dots > Custom repositories
2. Add https://github.com/mr-sparks/scent-assistant as Integration
3. Search for Scent Assistant and click Download
4. Restart Home Assistant

1. Download the custom_components/scent_assistant folder from this repository
2. Copy it to your Home Assistant config/custom_components/ directory
3. Restart Home Assistant

⚠️ Manual installation will not provide automatic update notifications. HACS is recommended.

Click the button above to start setup, or follow the steps below.

Fully local, no account required. Supports all features including fan control.

1. Go to Settings > Devices & Services > Add Integration
2. Search for Scent Assistant
3. Select Bluetooth
4. Your diffuser should appear in the device list
5. Select it and you're done

Note: Make sure no other device (phone, tablet) is connected to the diffuser via Bluetooth. BLE only allows one connection at a time.

Control your diffuser via the Aroma-Link cloud service. No Bluetooth required.

1. Go to Settings > Devices & Services > Add Integration
2. Search for Scent Assistant
3. Select WiFi / Cloud
4. Enter your Aroma-Link account credentials
5. Select your device from the list

Note: Requires an Aroma-Link account and internet connection. Fan control is only available via Bluetooth.

Set a complete spray schedule for specific days. Useful for automations.

service: scent_assistant.set_schedule
data:
  days:
    - mon
    - wed
    - fri
  start_time: "08:00"
  end_time: "20:00"
  work_seconds: 15
  pause_seconds: 60

automation:
  - alias: "Scent on when home"
    trigger:
      - platform: state
        entity_id: person.your_name
        to: "home"
    action:
      - service: switch.turn_on
        entity_id: switch.scent_diffuser_power

automation:
  - alias: "Weekday scent schedule"
    trigger:
      - platform: time
        at: "00:00"
    condition:
      - condition: time
        weekday: [mon, tue, wed, thu, fri]
    action:
      - service: scent_assistant.set_schedule
        data:
          days: [mon, tue, wed, thu, fri]
          start_time: "07:00"
          end_time: "18:00"
          work_seconds: 10
          pause_seconds: 120

  - alias: "Weekend scent schedule"
    trigger:
      - platform: time
        at: "00:00"
    condition:
      - condition: time
        weekday: [sat, sun]
    action:
      - service: scent_assistant.set_schedule
        data:
          days: [sat, sun]
          start_time: "09:00"
          end_time: "22:00"
          work_seconds: 15
          pause_seconds: 60

automation:
  - alias: "Scent off at night"
    trigger:
      - platform: time
        at: "23:00"
    action:
      - service: switch.turn_off
        entity_id: switch.scent_diffuser_power

• Make sure no other device is connected to the diffuser via Bluetooth (close the app on your phone)
• Try power-cycling the diffuser
• If your HA device is too far away, consider using an ESPHome Bluetooth Proxy

• Check the HA logs for BLE connection errors
• Try reloading the integration: Settings > Devices & Services > Scent Assistant > three dots > Reload
• Power-cycle the diffuser

Fan control is only available via Bluetooth. If you set up the device via Cloud/WiFi, the fan switch will not appear. This is a limitation of the Aroma-Link cloud API.

The integration uses connect-on-demand: it briefly connects, sends the command, then disconnects after 10 seconds. If your HA host is too far from the diffuser, consider:

• An ESPHome Bluetooth Proxy (ESP32, ~$5)
• A USB Bluetooth dongle closer to the diffuser

This integration was built by reverse engineering the BLE protocols of both device types. For full protocol documentation, see PROTOCOL.md.

Contributions are welcome! If you have a diffuser that uses the Aroma-Link or Aroma Buddy app and can help test, please open an issue.

MIT