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"

Migration from Previous Versions

1. Update Dependencies: Remove old plugin versions and install v2.0+
2. Node.js Upgrade: Update to Node.js 18+ if running older versions
3. Configuration Compatibility: All existing configurations remain compatible
4. Homebridge Version: Update to 1.6.0+ for optimal compatibility

Contributing to Development

1. Fork the project repository
2. Create a feature development branch
3. Implement your changes with proper testing
4. Add documentation for new features
5. Submit a pull request for review

Legal Information

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

Support Resources

• Issue Reporting: GitHub Issues
• Community Support: Homebridge Discord
• Discussion Forum: r/homebridge

Version History

v2.0.0

• Breaking Change: Requires Node.js 18+
• Breaking Change: Requires Homebridge 1.6.0+
• Full Homebridge 2.0 compatibility implementation
• Migrated from deprecated request library to axios
• Enhanced error handling and detailed logging system
• Improved security and performance optimizations
• Advanced debug logging capabilities
• Comprehensive configuration validation

v1.0.0

• Initial plugin release
• Core HTTP lock functionality
• Basic auto-lock and state reset features