2.13.1 • Published 2d ago

@350d/homebridge-seam

Licence

MIT

Version

2.13.1

Deps

Size

87 kB

Vulns

Weekly

Stars

Summary Dependency Versions

Homebridge Seam

A Homebridge plugin for smart locks via Seam.co API. Control your August, Yale, Schlage, Kwikset, and 100+ other smart lock brands through HomeKit using Seam's universal API.

Features

Lock/Unlock Control - Control your smart locks directly from HomeKit
Battery Monitoring - Track battery levels with low battery alerts and 1-hour caching
Door Sensor - Monitor door open/closed status (if supported by device)
Real-time Updates - Automatic webhook management with instant state synchronization
Secure Webhooks - Svix signature verification with Seam-provided secrets
Lightweight - Written in pure JavaScript with zero external dependencies
Simple Setup - Easy configuration through Homebridge UI
Auto Webhook Management - Webhooks are created/deleted automatically
Real Device Data - Shows actual manufacturer, model, and serial number in HomeKit
Race Condition Protection - Prevents multiple simultaneous lock commands

Requirements

Node.js 18.20.4, 20.15.1, 22, or 24
Homebridge 1.6.0 or 2.0
Active Seam.co account with API key
Smart locks already connected to Seam.co

Installation

Via Homebridge UI (Recommended)

Search for "Seam" in the Homebridge UI plugin search
Click Install
Configure the plugin (see Configuration section)

Manual Installation

npm install -g homebridge-seam

Getting Started with Seam.co

Before using this plugin, you need to:

Create an account at Seam Console
Connect your smart lock(s) to Seam through their Connect Webview
Get your API key from the Seam Console
Note down your device IDs

For detailed instructions, visit Seam Documentation

Configuration

Via Homebridge UI

The easiest way to configure the plugin is through the Homebridge UI:

Navigate to the plugin settings
Enter your Seam API key
Add your device(s) with their Device IDs
Optionally configure webhooks and polling settings
Save and restart Homebridge

Manual Configuration

Add the following to your Homebridge config.json:

{
  "platforms": [
    {
      "platform": "SeamLock",
      "name": "Seam Lock",
      "apiKey": "seam_****_YOUR_API_KEY",
      "devices": [
        {
          "deviceId": "device_****_YOUR_DEVICE_ID",
          "name": "Front Door"
        },
        {
          "deviceId": "device_****_ANOTHER_DEVICE_ID",
          "name": "Back Door"
        }
      ],
      "polling": {
        "interval": 60
      },
      "webhooks": {
        "enabled": true,
        "url": "https://your-domain.com",
        "port": 8080
      },
      "debug": false
    }
  ]
}

Configuration Options

Option	Type	Required	Default	Description
`apiKey`	string	Yes	-	Your Seam.co API key
`devices`	array	Yes	-	Array of device configurations
`devices[].deviceId`	string	Yes	-	Device ID from Seam.co
`devices[].name`	string	No	Device name	Custom name for the lock
`polling.interval`	number	No	60	How often to poll for state updates (in seconds)
`webhooks.enabled`	boolean	No	false	Enable webhook server
`webhooks.url`	string	No	-	Base URL for webhook endpoint (HTTPS recommended)
`webhooks.port`	number	No	8080	Port for webhook server (local testing)
`debug`	boolean	No	false	Enable debug logging

Note: webhooks.path and webhooks.secret are auto-generated and managed by the plugin.

Webhook Setup (Optional)

Webhooks provide real-time state updates without constant polling. The plugin automatically manages webhook creation and deletion.

Production Setup with HTTPS

For production use, set up HTTPS webhooks using stunnel:

1. Install stunnel and certbot

sudo apt install stunnel4 certbot

2. Get SSL certificate

# Open port 80 on your router and forward it to homebridge port 80
# Stop Homebridge if needed (if your have it on port 80)
sudo certbot certonly --standalone -d your-domain.com

3. Configure stunnel

Create /etc/stunnel/homebridge.conf:

pid = /var/run/stunnel-homebridge.pid
[homebridge]
accept = 443
connect = 127.0.0.1:8080
cert = /etc/letsencrypt/live/your-domain.com/fullchain.pem
key = /etc/letsencrypt/live/your-domain.com/privkey.pem

4. Start stunnel

sudo systemctl enable stunnel4
sudo systemctl restart stunnel4

5. Configure plugin

Set webhook URL to https://your-domain.com in plugin configuration.

Webhook Features

Automatic Management - Webhooks are created/deleted automatically
Secure Paths - Each webhook gets a unique random UUID path
Svix Verification - Webhook secrets from Seam API with mandatory signature checks
Persistent Configuration - Webhook settings survive plugin updates

Note: Without webhooks, the plugin uses polling (default: every 60 seconds) to check lock state.

Advanced Features

Automatic Webhook Management

The plugin automatically handles webhook lifecycle:

Creation - Webhooks are created automatically when enabled
Deletion - Webhooks are deleted when disabled
Persistence - Webhook settings survive plugin updates
Security - Each webhook gets a unique random UUID path

Battery Caching

Battery level is cached for 1 hour to reduce API calls:

Efficient - Reduces unnecessary API requests
Accurate - Fresh data when needed
Configurable - Cache timeout can be adjusted

Race Condition Protection

Prevents multiple simultaneous lock commands:

Command Queue - Commands are queued and executed sequentially
Timeout Protection - Commands timeout after 15 seconds
State Locking - Prevents polling interference during commands

Real Device Information

Shows actual device data in HomeKit:

Manufacturer - Real manufacturer name (e.g., "August", "Yale")
Model - Actual model name from device
Serial Number - Real serial number from device
Firmware - Device firmware version

Supported Devices

This plugin supports any smart lock that works with Seam.co, including:

Popular Brands

August - All generations (August Smart Lock Pro, August Smart Lock 4th Gen, etc.)
Yale - All Assure Lock models (Yale Assure Lock SL, Yale Assure Lock 2, etc.)
Schlage - Encode series (Schlage Encode, Schlage Encode Plus, etc.)
Kwikset - Halo series (Kwikset Halo, Kwikset Halo Touch, etc.)

Additional Brands

Lockly - Secure Plus, Vision Elite, and other models
Nuki - Smart Lock 3.0, Smart Lock 2.0, and accessories
Salto - Various electronic lock models
Minut - Smart lock solutions
Tedee - Smart lock systems
And 100+ more brands!

For the complete list of supported devices, visit Seam Supported Devices

Note: This plugin works with any device that's compatible with Seam.co's universal API, regardless of the manufacturer.

HomeKit Features

Each lock will appear in HomeKit with:

Lock Mechanism - Lock/unlock control with current state
Battery Service - Battery level and low battery indicator with 1-hour caching
Accessory Information - Real device data (manufacturer, model, serial number, firmware)
Race Condition Protection - Prevents multiple simultaneous commands
Real-time Updates - Instant state synchronization via webhooks