LockUnlock

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"]}'