Homebridge Appartme Plugin

A Homebridge plugin for integrating Appartme building management systems with Apple HomeKit. This plugin allows you to control lights, switches, thermostats, water valves, and monitor sensors from your Appartme Main Module through HomeKit.

Features

• Lighting Control: Turn lights on/off
• Switch Control: Control power sockets and additional channels
• Climate Control: Control thermostat with comfort/eco modes
• Water Valve Control: Open/close water valves
• Sensor Monitoring: Monitor temperature, voltage, current, and power consumption

Prerequisites

• Appartme Main Module (legacy hardware not supported)
• Appartme account with devices linked
• OAuth Client ID and Client Secret (request from Appartme OAuth Credentials Request Form)
• Homebridge installed and configured

Installation

Via Homebridge Config UI X (Recommended)

1. Open Homebridge Config UI X
2. Go to the "Plugins" tab
3. Search for "homebridge-appartme"
4. Click "Install"

Manual Installation

npm install -g homebridge-appartme

Configuration

Using Homebridge Config UI X

1. Go to the "Plugins" tab in Homebridge Config UI X
2. Find "Homebridge Appartme Plugin" and click "Settings"
3. Enter your OAuth credentials:
   • OAuth Client ID: Your Appartme OAuth Client ID
   • OAuth Client Secret: Your Appartme OAuth Client Secret
   • Update Interval: How often to poll for updates (30-300 seconds, default: 60)

Manual Configuration

Add the following to your Homebridge config.json:

{
  "platforms": [
    {
      "platform": "AppartmePlatform",
      "name": "Appartme",
      "username": "[email protected]",
      "password": "your-appartme-password",
      "clientId": "your-oauth-client-id",
      "clientSecret": "your-oauth-client-secret",
      "redirectUri": "http://localhost",
      "updateInterval": 60
    }
  ]
}

Configuration Options

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | username | string | Yes | - | Your Appartme account email address | | password | string | Yes | - | Your Appartme account password | | clientId | string | Yes | - | Your Appartme OAuth Client ID | | clientSecret | string | Yes | - | Your Appartme OAuth Client Secret | | redirectUri | string | No | http://localhost | OAuth redirect URI | | updateInterval | number | No | 60 | Update interval in seconds (30-300) |

Supported Devices

The plugin automatically discovers and creates HomeKit accessories for:

Lights

• Service: Lightbulb
• Controls: On/Off
• Property: lighting

Switches

• Service: Switch
• Controls: On/Off
• Properties: sockets, fifth_channel

Thermostat

• Service: Thermostat
• Controls: Temperature setting, heating mode
• Properties: thermostat_mode, comfort_temperature, eco_temperature, current_temperature
• Modes: Comfort and Eco preset modes

Water Valve

• Service: Switch (representing valve state)
• Controls: Open/Close
• Property: water

Sensors

• Temperature: Current room temperature
• Power Monitoring: Voltage, current, and power for each phase
• Properties: current_temperature, phase_1_current, phase_2_current, phase_3_current, etc.

Getting OAuth Credentials

1. Visit the Appartme OAuth Credentials Request Form
2. Fill out the required information
3. Wait for approval and receive your Client ID and Client Secret
4. Use these credentials in your Homebridge configuration

Troubleshooting

Plugin Not Loading

• Ensure Homebridge is running the latest version
• Check that your config.json is valid JSON
• Verify your OAuth credentials are correct

Devices Not Appearing

• Confirm your Main Module is online and connected to your Appartme account
• Check the Homebridge logs for authentication errors
• Ensure your OAuth credentials have the necessary permissions

Connection Issues

• Verify your internet connection
• Check if the Appartme API is accessible
• Try increasing the update interval if you're experiencing rate limiting

Legacy Hardware

This plugin only works with Appartme Main Modules. Legacy hardware (Connect, Relay, Sensor) is not supported. Contact Appartme Support to upgrade your system.

API Rate Limits

The plugin respects Appartme's API rate limits by:

• Using a configurable update interval (minimum 30 seconds)
• Implementing proper error handling and retry logic
• Caching device states to minimize API calls

Development

Building from Source

git clone https://github.com/yourusername/homebridge-appartme.git
cd homebridge-appartme
npm install
npm run build

Running in Development

npm run watch

Testing the Plugin

For testing and development, this repository includes a complete Docker-based testing environment:

macOS Users (Recommended)

# Navigate to the plugin directory
cd homebridge-appartme

# Start the test environment with macOS networking
./start-test-macos.sh

# Follow the on-screen instructions to add to HomeKit
# PIN: 031-45-154

Linux Users

# Navigate to the plugin directory
cd homebridge-appartme

# Start the test environment  
./start-test.sh

# Add the bridge to HomeKit using PIN: 031-45-154

Troubleshooting

If you encounter network issues on macOS (HomeKit discovery not working):

./troubleshoot-network.sh

See TESTING.md for detailed testing instructions and troubleshooting.

Contributing

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

Support

• Plugin Issues: GitHub Issues
• Appartme Support: [email protected]
• Homebridge Support: Homebridge Discord

License

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

Acknowledgments

• Based on the Appartme Home Assistant Custom Integration
• Built with the Homebridge Plugin Template
• Thanks to the Appartme team for providing API access

Changelog

v1.0.0

• Initial release
• Support for lights, switches, thermostat, water valve, and sensors
• OAuth authentication
• Configurable update intervals
• Full HomeKit integration