Homebridge IOTAS V2

Homebridge plugin for IOTAS Smart Home

This Homebridge plugin exposes IOTAS smart home devices to Apple's HomeKit.

IOTAS is a smart apartment platform commonly found in multifamily residential buildings. This plugin allows you to control your IOTAS-connected devices through HomeKit, Siri, and the Home app.

Supported Devices

| Device Type | HomeKit Service | Features | | ------------------- | --------------- | -------------------------------- | | Lights | Lightbulb | On/Off, Brightness | | Switches | Switch | On/Off | | Outlets | Switch | On/Off | | Door Locks | Lock Mechanism | Lock/Unlock | | Thermostats | Thermostat | Current/Target Temperature, Mode | | Battery Devices | Battery | Battery Level, Charging State |

Known Limitations

• Door Lock Status: The lock status polling from the IOTAS API can become desynced if you use the physical keypad or if the door auto-locks. HomeKit may show "Locking..." even when the door is already locked. This is an IOTAS API limitation also observed in their first-party app.

Prerequisites

• A working Homebridge installation
• An IOTAS account with valid credentials
• Node.js 20.18.0 or later

Installation

Via Homebridge Config UI X (Recommended)

1. Search for homebridge-iotas-v2 in the Plugins tab
2. Click Install
3. Configure the plugin in the Settings

Via Command Line

npm install -g homebridge-iotas-v2

Configuration

Add the following to your Homebridge config.json:

{
  "platforms": [
    {
      "platform": "homebridge-iotas-v2",
      "name": "IOTAS",
      "username": "[email protected]",
      "password": "your-password",
      "unit": "Unit Name"
    }
  ]
}

| Option | Required | Description | | ---------- | -------- | ---------------------------------------- | | platform | Yes | Must be homebridge-iotas-v2 | | name | Yes | Display name for the platform | | username | Yes | Your IOTAS account email | | password | Yes | Your IOTAS account password | | unit | No | Unit name (defaults to first unit found) |

Troubleshooting

Debug Mode

Run Homebridge with debug logging enabled:

homebridge -D

This will show detailed logs including API requests and device discovery.

Common Issues

1. No devices showing up: Verify your IOTAS credentials are correct and that you can log into the IOTAS app.

2. Wrong unit: If you have access to multiple units, specify the unit name in your config.

3. Devices not responding: The IOTAS API may be temporarily unavailable. Check your internet connection and try restarting Homebridge.

Getting Help

• Check existing issues on GitHub
• Open a new issue with debug logs
• Join the Homebridge Discord community

Development

# Clone the repository
git clone https://github.com/mezaugusto/homebridge-iotas.git
cd homebridge-iotas

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Link for local development
npm link
homebridge -D

Commit Messages

This project uses Conventional Commits with release-please for automated releases. Your commit messages determine what's included in release PRs:

| Prefix | Included | Example | | ------------------ | -------- | ---------------------------------- | | fix: | Yes | fix: handle empty serial numbers | | feat: | Yes | feat: add humidity sensor support| | feat!: / fix!: | Yes | feat!: drop Node 18 support | | chore:, docs:, ci:, refactor: | No | chore: update dependencies |

Credits

• Forked from SanTechIT/homebridge-iotas-test
• Originally based on work by stevesample and kpsuperplane
• Built with the Homebridge Plugin Template

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.