homebridge-aroma-link

Homebridge plugin for Aroma-Link Smart Scent Air Machine. This plugin integrates your Aroma-Link diffuser with HomeKit through Homebridge, allowing you to control your scent system from the Home app and Siri.

Features

• 🌸 Multiple Service Types: Expose your Aroma-Link device as Fan, Switch, or Outlet services
• 🔐 Secure Authentication: Uses MD5-hashed passwords and session tokens
• 🔄 Automatic Discovery: Automatically discovers all Aroma-Link devices on your account
• 📱 HomeKit Integration: Full HomeKit compatibility with Siri voice control
• ⚙️ Configurable: Customize polling intervals and service types
• 🐛 Debug Mode: Comprehensive logging for troubleshooting

Prerequisites

• Aroma-Link Smart Scent Air Machine with WiFi connectivity
• Aroma-Link account (same credentials used in the mobile app)
• Homebridge installed and configured
• Node.js 14.0.0 or higher

Installation

Method 1: Homebridge UI (Recommended)

1. Open Homebridge UI
2. Go to the "Plugins" tab
3. Search for "homebridge-aroma-link"
4. Click "Install"
5. Configure the plugin using the UI

Method 2: Manual Installation

1. Install homebridge: npm install -g homebridge
2. Install this plugin: npm install -g homebridge-aroma-link
3. Add the platform to your config.json (see Configuration section)

Configuration

Homebridge UI Configuration

When using Homebridge UI, you can configure the plugin through the interface:

• Platform Name: Name for the platform in Homebridge
• Username: Your Aroma-Link account username
• Password: Your Aroma-Link account password (will be MD5 hashed)
• Polling Interval: How often to check device status (10-300 seconds)
• Enable Fan Service: Expose device as a Fan service for intensity control
• Enable Switch Service: Expose device as a Switch service for simple on/off
• Enable Outlet Service: Expose device as an Outlet service
• Debug Mode: Enable detailed logging

Manual Configuration

Add the following to your config.json:

{
  "platforms": [
    {
      "platform": "AromaLink",
      "name": "Aroma-Link",
      "username": "your-username",
      "password": "your-password",
      "pollingInterval": 30,
      "enableFanService": true,
      "enableSwitchService": true,
      "enableOutletService": false,
      "debug": false
    }
  ]
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | name | string | "Aroma-Link" | Platform name in Homebridge | | username | string | Required | Aroma-Link account username | | password | string | Required | Aroma-Link account password | | pollingInterval | number | 30 | Polling interval in seconds (10-300) | | enableFanService | boolean | true | Enable Fan service for intensity control | | enableSwitchService | boolean | true | Enable Switch service for on/off | | enableOutletService | boolean | false | Enable Outlet service | | debug | boolean | false | Enable debug logging |

Usage

HomeKit Integration

Once configured, your Aroma-Link devices will appear in the Home app:

• Fan Service: Control on/off and intensity (rotation speed)
• Switch Service: Simple on/off control
• Outlet Service: On/off control with outlet semantics

Siri Voice Control

You can use Siri to control your devices:

• "Hey Siri, turn on the Aroma-Link"
• "Hey Siri, set the Aroma-Link to 50%"
• "Hey Siri, turn off the scent diffuser"

Automation

Create automations in the Home app:

• Turn on when arriving home
• Turn off when leaving
• Schedule based on time of day
• Trigger based on other HomeKit devices

API Reference

This plugin uses the Aroma-Link API endpoints:

• Authentication: POST /v2/app/token
• Device Discovery: GET /v1/app/device/listAll/{accountId}
• Device Control: POST /v1/app/data/newSwitch

For more details about the API, see the Home Assistant integration guide.

Troubleshooting

Common Issues

1. Authentication Failed

   • Verify your username and password are correct
   • Check that your Aroma-Link account is active
   • Ensure your device is connected to WiFi

2. No Devices Found

   • Make sure your Aroma-Link device is online
   • Check that the device is properly registered in your account
   • Enable debug mode to see detailed logs

3. Device Not Responding

   • Check your internet connection
   • Verify the Aroma-Link servers are accessible
   • Try restarting Homebridge

Debug Mode

Enable debug mode in the configuration to see detailed logs:

{
  "platform": "AromaLink",
  "debug": true
}

This will show:

• API request/response details
• Device discovery process
• State changes and polling information

Development

Building from Source

1. Clone this repository:

   git clone https://github.com/yourusername/homebridge-aroma-link.git
   cd homebridge-aroma-link

2. Install dependencies:

   npm install

3. Create a symlink for development:

   npm link

4. Link to homebridge:

   npm link homebridge-aroma-link

5. Start homebridge:

   homebridge

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

ISC

Acknowledgments

• Based on the Hubitat Aroma-Link integration by Adrian Caramaliu
• Inspired by the Home Assistant automation guide
• Built for the Homebridge community

Support

• GitHub Issues
• Homebridge Discord
• Aroma-Link Support