@350d/homebridge-http-lock NPM

Homebridge HTTP Lock

Modern Homebridge plugin that transforms any HTTP-enabled device into a smart lock for Apple HomeKit. Perfect for IoT devices, web-controlled relays, and custom automation systems.

Key Features

HTTP Protocol Support: Works with any device accepting HTTP requests
Multiple HTTP Methods: GET, POST, PUT, PATCH support for maximum compatibility
Secure Authentication: Built-in HTTP Basic Authentication
Flexible Headers & Payloads: Complete control over request formatting
Smart Auto-Lock: Configurable automatic re-locking functionality
State Synchronization: Reset lock status without triggering actions
Robust Error Handling: Comprehensive logging and error management
Future-Proof: Full compatibility with Homebridge 1.9+ and 2.0+

System Requirements

Homebridge: Version 1.6.0 or newer (including 2.0.0-beta)
Node.js: 18.20.4+, 20.15.1+, or 22+
iOS/macOS: HomeKit-enabled device with iOS 13.0+

Installation Guide

Install through Homebridge UI or command line:

npm install -g @350d/homebridge-http-lock

Configuration Examples

Add the accessory configuration to your Homebridge config.json:

Simple Setup (GET Requests)

{
  "accessories": [
    {
      "accessory": "HTTPLock",
      "name": "Front Door Lock",
      "openURL": "http://192.168.1.100/relay/0?turn=on",
      "closeURL": "http://192.168.1.100/relay/0?turn=off"
    }
  ]
}

Advanced Setup (POST with Authentication)

{
  "accessories": [
    {
      "accessory": "HTTPLock",
      "name": "Smart Lock",
      "http_method": "POST",
      "timeout": 10,
      "username": "admin",
      "password": "password",
      "openURL": "https://your-device.local/api/unlock",
      "openHeader": {
        "Content-Type": "application/json",
        "X-API-Key": "your-api-key"
      },
      "openBody": {
        "action": "unlock",
        "device_id": "lock_01"
      },
      "closeURL": "https://your-device.local/api/lock",
      "closeHeader": {
        "Content-Type": "application/json",
        "X-API-Key": "your-api-key"
      },
      "closeBody": {
        "action": "lock",
        "device_id": "lock_01"
      },
      "autoLock": true,
      "autoLockDelay": 30
    }
  ]
}

State Reset Configuration

Ideal for devices that automatically return to locked state:

{
  "accessories": [
    {
      "accessory": "HTTPLock",
      "name": "Gate Lock",
      "openURL": "http://192.168.1.100/trigger",
      "resetLock": true,
      "resetLockTime": 5
    }
  ]
}

Configuration Reference

Essential Parameters

Parameter	Type	Description
`accessory`	string	Must be `HTTPLock`
`name`	string	Device name displayed in HomeKit

Note: Either openURL or closeURL (or both) must be configured.

HTTP Endpoints & Actions

Parameter	Type	Default	Description
`openURL`	string	-	HTTP endpoint for unlock operation
`closeURL`	string	-	HTTP endpoint for lock operation
`openHeader`	object	`{}`	Custom headers for unlock requests
`closeHeader`	object	`{}`	Custom headers for lock requests
`openBody`	string/object	`""`	Request payload for unlock operation
`closeBody`	string/object	`""`	Request payload for lock operation

Network & Authentication

Parameter	Type	Default	Description
`http_method`	string	`GET`	HTTP method (`GET`, `POST`, `PUT`, `PATCH`)
`timeout`	number	`5`	Request timeout in seconds
`username`	string	-	HTTP Basic Auth username
`password`	string	-	HTTP Basic Auth password

Automation Features

Parameter	Type	Default	Description
`autoLock`	boolean	`false`	Enable automatic re-locking after unlock
`autoLockDelay`	number	`5`	Delay before auto-lock in seconds
`resetLock`	boolean	`false`	Reset state to locked without HTTP call
`resetLockTime`	number	`5`	Delay before state reset in seconds

Important: autoLock and resetLock are mutually exclusive. autoLock triggers the closeURL, while resetLock only updates HomeKit state.

Device Identification

Parameter	Type	Default	Description
`manufacturer`	string	`350d`	Device manufacturer name
`model`	string	Plugin name	Device model identifier
`serial`	string	Plugin version	Device serial number
`firmware`	string	Plugin version	Firmware version string

Real-World Examples

Shelly 1 Relay Control

{
  "accessory": "HTTPLock",
  "name": "Garage Door",
  "openURL": "http://192.168.1.50/relay/0?turn=on",
  "closeURL": "http://192.168.1.50/relay/0?turn=off",
  "resetLock": true,
  "resetLockTime": 3
}

ESP8266/ESP32 Integration

{
  "accessory": "HTTPLock",
  "name": "Garden Gate",
  "http_method": "POST",
  "openURL": "http://esp-gate.local/api/control",
  "openHeader": {
    "Content-Type": "application/json"
  },
  "openBody": {
    "command": "open",
    "duration": 1000
  },
  "resetLock": true,
  "resetLockTime": 5
}

Cloud API Integration

{
  "accessory": "HTTPLock",
  "name": "Office Door",
  "http_method": "POST",
  "timeout": 15,
  "openURL": "https://api.smartlock.com/v1/locks/12345/unlock",
  "closeURL": "https://api.smartlock.com/v1/locks/12345/lock",
  "openHeader": {
    "Authorization": "Bearer your-token-here",
    "Content-Type": "application/json"
  },
  "closeHeader": {
    "Authorization": "Bearer your-token-here",
    "Content-Type": "application/json"
  },
  "autoLock": true,
  "autoLockDelay": 60
}

Troubleshooting Guide

Common Issues & Solutions

Device shows "No Response" in HomeKit

Verify device URL is accessible from Homebridge server
Check network connectivity and firewall configuration
Increase timeout value for slower responding devices

HTTP Authentication Failures (401/403)

Confirm username/password credentials are correct
Verify API key or token requirements in headers
Ensure device supports HTTP Basic Authentication

Lock state not updating properly

Review Homebridge logs for detailed error messages
Confirm URL endpoints return HTTP success codes (200-299)
Test URLs manually using curl or web browser

Auto-lock feature not functioning

Verify closeURL is configured when using autoLock
Check autoLockDelay timing configuration
Monitor logs for auto-lock execution messages

Debug Configuration

Enable detailed logging in Homebridge:

{
  "platforms": [],
  "accessories": [...],
  "log": {
    "method": "systemd",
    "level": "debug"
  }
}

Manual Testing

Test device endpoints manually:

# Simple GET request
curl -v "http://your-device/unlock"

# POST request with authentication
curl -v -X POST \
  -H "Content-Type: application/json" \
  -u "username:password" \
  -d '{"action":"unlock"}' \
  "https://your-device/api/control"