homebridge-tekmar

A Homebridge plugin for Tekmar tN4 WiFi thermostats (561/562/563/564). Control your Tekmar radiant floor heating thermostat through Apple HomeKit via the Watts Home cloud API.

Features

• Current Temperature — Room, floor, and outdoor sensor readings
• Target Temperature — Set your heating setpoint from the Home app or Siri
• Mode Control — Off, Heat, and Auto (scheduled program) modes
• Automatic Polling — Keeps HomeKit in sync with your thermostat state
• Easy Configuration — Set up through Homebridge Config UI X
• No Runtime Dependencies — Uses Node.js native fetch, no extra packages needed
• Child Bridge Support — Run as an isolated child bridge for stability

Supported Hardware

| Model | Name | Type | |-------|------|------| | 561 | tN4 Smart Thermostat | WiFi radiant floor heating | | 562 | tN4 Smart Thermostat | WiFi radiant floor heating | | 563 | tN4 Smart Thermostat | WiFi radiant floor heating | | 564 | tN4 Smart Thermostat | WiFi radiant floor heating |

These thermostats are controlled via the Watts Home mobile app (iOS / Android). You must have a Watts Home account with your thermostat(s) configured before using this plugin.

Installation

Option 1: Via Homebridge Config UI X (Recommended)

1. Search for homebridge-tekmar in the Homebridge Config UI X plugins tab
2. Click Install
3. Configure with your Watts Home account credentials

Option 2: Via npm

npm install -g homebridge-tekmar

Configuration

Configure the plugin through the Homebridge Config UI X interface, or manually edit your config.json:

{
  "platforms": [
    {
      "platform": "TekmarThermostat",
      "name": "Tekmar Thermostat",
      "username": "[email protected]",
      "password": "your-password"
    }
  ]
}

Configuration Options

| Option | Default | Description | |--------|---------|-------------| | username | required | Your Watts Home app email address | | password | required | Your Watts Home app password | | pollingInterval | 60 | Polling interval in seconds (10-300) | | temperatureUnit | fahrenheit | Display unit: fahrenheit or celsius |

How It Works

1. Authenticates with the Watts Home cloud API (Azure AD B2C OAuth2)
2. Discovers all Tekmar thermostats across your locations
3. Exposes each thermostat as a HomeKit Thermostat accessory
4. Polls the API at a configurable interval to keep state in sync
5. SET commands (temperature, mode) are sent immediately to the API

HomeKit Mode Mapping

The Tekmar 561 is a heat-only thermostat. HomeKit modes are mapped as:

| HomeKit Mode | Tekmar Behavior | |-------------|-----------------| | Off | Thermostat off | | Heat | Manual heating to target temperature | | Auto | Scheduled program mode enabled |

Note: Cool mode is not available — the Tekmar tN4 series does not support cooling.

Supported Features

• Set and read target temperature
• Read current room temperature
• Switch between Off / Heat / Auto modes
• Current heating state (actively heating or idle)
• Temperature display unit preference
• Multiple thermostats across multiple locations

Known Limitations

• Cloud API only — Requires internet connectivity (no local control)
• Heat only — No cooling support (hardware limitation)
• No humidity sensor — The thermostat does not report humidity
• Floor/outdoor temps — Floor and outdoor sensor readings are fetched but not yet exposed as separate HomeKit sensors

Development

Local Development

# Clone the repository
git clone https://github.com/apumapho/homebridge-tekmar.git
cd homebridge-tekmar

# Install dependencies
npm install

# Build
npm run build

# Link for local testing
npm link

# Run Homebridge in debug mode
homebridge -D

Standalone API Test

WATTS_USERNAME="[email protected]" WATTS_PASSWORD="yourpass" npx tsx test-auth.ts

Troubleshooting

Thermostat not appearing in HomeKit

1. Check Homebridge logs for authentication errors
2. Verify your Watts Home credentials are correct
3. Ensure your thermostat is set up in the Watts Home app
4. Try restarting Homebridge

"Not Responding" in Home app

• Check your internet connection
• Verify the Watts Home cloud service is operational
• Increase pollingInterval if you're hitting rate limits

Authentication failures

• Ensure your email and password match what you use in the Watts Home app
• Check if your account has been locked (too many failed attempts)
• The plugin uses the same authentication flow as the mobile app

About Tekmar / Watts

Tekmar is a Watts brand specializing in radiant heating controls. The tN4 WiFi thermostat series connects to the Watts Home cloud platform for remote control. This plugin uses the Watts Home cloud API to integrate with HomeKit.

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

• Thanks to the Homebridge team for the excellent platform
• Built with Claude Code

Support

• Report Issues
• Homebridge Discord
• Homebridge Wiki