The LockUnlock trait enables devices to control locking mechanisms. This trait is primarily used for smart door locks, cabinet locks, and other security devices that can be electronically locked or unlocked.

Supported Attributes

The LockUnlock trait does not define any specific attributes in the current implementation. The trait relies on the basic device capabilities and state reporting.

Supported Commands

1. `LockUnlock`

Controls the lock state of the device.

Parameters

{
  lock: boolean  // Required: true to lock, false to unlock
}

Parameter Validation

lock: Required boolean value
true: Engages the lock mechanism
false: Disengages the lock mechanism

Usage Examples

Basic Lock Control

Lock the Door

{
  "sn": "SMART_LOCK_SERIAL",
  "iotDevs": ["lock_mechanism"],
  "iotCmds": [
    {
      "command": "LockUnlock",
      "params": {
        "lock": true
      }
    }
  ]
}

Unlock the Door

{
  "sn": "SMART_LOCK_SERIAL",
  "iotDevs": ["lock_mechanism"],
  "iotCmds": [
    {
      "command": "LockUnlock",
      "params": {
        "lock": false
      }
    }
  ]
}

Multiple Lock Control

Lock Multiple Doors Simultaneously

{
  "sn": "MULTI_LOCK_CONTROLLER",
  "iotDevs": ["front_door", "back_door", "garage_door"],
  "iotCmds": [
    {
      "command": "LockUnlock",
      "params": {
        "lock": true
      }
    }
  ]
}

Unlock Specific Door

{
  "sn": "MULTI_LOCK_CONTROLLER",
  "iotDevs": ["front_door"],
  "iotCmds": [
    {
      "command": "LockUnlock",
      "params": {
        "lock": false
      }
    }
  ]
}

Security Scenarios

Emergency Unlock All Doors

{
  "sn": "SECURITY_SYSTEM_SERIAL",
  "iotDevs": ["all_locks"],
  "iotCmds": [
    {
      "command": "LockUnlock",
      "params": {
        "lock": false
      }
    }
  ]
}

Secure Building (Lock All)

{
  "sn": "BUILDING_CONTROLLER",
  "iotDevs": ["entrance", "office_doors", "storage"],
  "iotCmds": [
    {
      "command": "LockUnlock",
      "params": {
        "lock": true
      }
    }
  ]
}

Scheduled Lock Operations

Auto-Lock at Night

{
  "sn": "SMART_LOCK_SERIAL",
  "iotDevs": ["lock_mechanism"],
  "iotCmds": [
    {
      "command": "TimerStart",
      "params": {
        "timerTimeSec": 3600,
        "scheduledCommands": [
          {
            "command": "LockUnlock",
            "params": {
              "lock": true
            }
          }
        ]
      }
    }
  ]
}

Combined with Other Systems

Lock Door and Turn Off Lights

{
  "sn": "HOME_AUTOMATION_HUB",
  "iotDevs": ["security_system"],
  "iotCmds": [
    {
      "command": "LockUnlock",
      "params": {
        "lock": true
      }
    },
    {
      "command": "ActivateScene",
      "params": {
        "scene": "away_mode"
      }
    }
  ]
}

Device Types Using LockUnlock Trait

Residential Locks

Smart door locks
Deadbolts with electronic control
Keypad entry locks
Bluetooth/WiFi enabled locks

Commercial Security

Office door locks
Access control systems
Magnetic locks
Electric strike locks

Specialized Locks

Cabinet locks
Drawer locks
Safe locks
Locker systems

Automotive

Smart garage door locks
Gate locks
Vehicle door locks
Charging port locks

Lock Types and Mechanisms

Electronic Deadbolt

{
  "traits": ["LockUnlock"],
  "deviceType": "electronic_deadbolt",
  "features": ["battery_powered", "manual_override"]
}

Magnetic Lock

{
  "traits": ["LockUnlock"],
  "deviceType": "magnetic_lock",
  "features": ["fail_safe", "high_security"]
}

Smart Lock with Keypad

{
  "traits": ["LockUnlock"],
  "deviceType": "keypad_lock",
  "features": ["multiple_codes", "temporary_access"]
}

Integrated Security System

{
  "traits": ["LockUnlock", "SensorState", "StatusReport"],
  "deviceType": "security_lock",
  "features": ["door_sensor", "tamper_detection", "alarm_integration"]
}

Security Considerations

Access Control

Implement proper authentication before unlock commands
Log all lock/unlock operations with timestamps
Monitor failed unlock attempts
Use secure communication protocols

Fail-Safe vs Fail-Secure

Fail-Safe: Unlocks when power is lost (fire safety)
Fail-Secure: Remains locked when power is lost (security)
Choose appropriate behavior based on application

Battery Management

Monitor battery levels for battery-powered locks
Implement low battery warnings
Provide backup power or manual override options

Best Practices

1. Security First

Always verify user authorization before unlock operations
Implement audit logging for all lock operations
Use encrypted communication channels
Regular security updates and patches

2. Reliability

Test lock mechanisms regularly
Monitor battery levels and device health
Implement backup access methods
Plan for power outages and network failures

3. User Experience

Provide clear feedback on lock status
Implement reasonable timeouts for operations
Support multiple access methods (app, keypad, key)
Clear error messages and troubleshooting guidance

4. Integration

Coordinate with security systems and alarms
Integrate with home automation scenes
Support scheduling and automation rules
Consider emergency access requirements

5. Maintenance

Regular cleaning and lubrication of mechanical parts
Battery replacement schedules
Firmware updates and security patches
Periodic testing of all access methods

Related Traits

The LockUnlock trait is often combined with:

SensorState: For door position and tamper detection
StatusReport: For battery level and health monitoring
Timer: For scheduled lock/unlock operations
Scene: For security mode configurations
TwoFactorAck: For additional security verification

State Reporting

Devices with LockUnlock trait typically report:

isLocked: Current lock state (boolean)
isJammed: Whether lock mechanism is jammed
batteryLevel: Battery charge level (if battery powered)
doorOpen: Door position (if door sensor present)
tamperDetected: Tamper detection status
lastLockTime: Timestamp of last lock operation
lastUnlockTime: Timestamp of last unlock operation
online: Device connectivity status

Query current lock state:

curl -X POST "https://api.ultroncloud.com/usr/v5/GetGroupDeviceStates" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Ultron-Cloud-Appid: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{"groupId": "YOUR_LOCATION_ID", "snList": ["SN1", "SN2"]}'