@350d/homebridge-http-lock
Version:
Modern Homebridge plugin for controlling HTTP-enabled lock mechanisms via Apple HomeKit. Supports various HTTP methods, custom authentication, automatic locking, and flexible device integration for smart home automation.
311 lines (248 loc) • 8.86 kB
Markdown
[](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)
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.
- **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+
- **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:
```bash
npm install -g @350d/homebridge-http-lock
```
## Configuration Examples
Add the accessory configuration to your Homebridge `config.json`:
### Simple Setup (GET Requests)
```json
{
"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"
}
]
}
```
```json
{
"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
}
]
}
```
Ideal for devices that automatically return to locked state:
```json
{
"accessories": [
{
"accessory": "HTTPLock",
"name": "Gate Lock",
"openURL": "http://192.168.1.100/trigger",
"resetLock": true,
"resetLockTime": 5
}
]
}
```
| 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.
| 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 |
| 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
```json
{
"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
}
```
```json
{
"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
}
```
```json
{
"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
}
```
**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:
```json
{
"platforms": [],
"accessories": [...],
"log": {
"method": "systemd",
"level": "debug"
}
}
```
Test device endpoints manually:
```bash
curl -v "http://your-device/unlock"
curl -v -X POST \
-H "Content-Type: application/json" \
-u "username:password" \
-d '{"action":"unlock"}' \
"https://your-device/api/control"
```
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
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
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for complete details.
- **Issue Reporting**: [GitHub Issues](https://github.com/350d/homebridge-http-lock/issues)
- **Community Support**: [Homebridge Discord](https://discord.gg/homebridge)
- **Discussion Forum**: [r/homebridge](https://reddit.com/r/homebridge)
- **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
- Initial plugin release
- Core HTTP lock functionality
- Basic auto-lock and state reset features