Add unbolt support to door lock cluster

examples/all-clusters-app/all-clusters-common/all-clusters-app.matter

@@ -2820,6 +2820,10 @@ server cluster DoorLock = 257 {
     nullable CredentialStruct credential = 0;
   }
 
+  request struct UnboltDoorRequest {
+    optional OCTET_STRING PINCode = 0;
+  }
+
   response struct GetUserResponse = 28 {
     INT16U userIndex = 0;
     nullable CHAR_STRING userName = 1;
@@ -2861,6 +2865,7 @@ server cluster DoorLock = 257 {
   timed command access(invoke: administer) SetCredential(SetCredentialRequest): SetCredentialResponse = 34;
   command access(invoke: administer) GetCredentialStatus(GetCredentialStatusRequest): GetCredentialStatusResponse = 36;
   timed command access(invoke: administer) ClearCredential(ClearCredentialRequest): DefaultSuccess = 38;
+  timed command UnboltDoor(UnboltDoorRequest): DefaultSuccess = 39;
 }
 
 /** Provides an interface for controlling and adjusting automatic window coverings. */
@@ -5175,7 +5180,7 @@ endpoint 1 {
     ram      attribute wrongCodeEntryLimit default = 3;
     ram      attribute userCodeTemporaryDisableTime default = 10;
     ram      attribute requirePINforRemoteOperation default = 0;
-    ram      attribute featureMap default = 0xD13;
+    ram      attribute featureMap default = 0x1D13;
     ram      attribute clusterRevision default = 6;
   }
 

examples/all-clusters-app/all-clusters-common/all-clusters-app.zap

@@ -13147,6 +13147,14 @@
               "source": "client",
               "incoming": 1,
               "outgoing": 0
+            },
+            {
+              "name": "UnboltDoor",
+              "code": 39,
+              "mfgCode": null,
+              "source": "client",
+              "incoming": 1,
+              "outgoing": 0
             }
           ],
           "attributes": [
@@ -13836,7 +13844,7 @@
               "storageOption": "RAM",
               "singleton": 0,
               "bounded": 0,
-              "defaultValue": "0xD13",
+              "defaultValue": "0x1D13",
               "reportable": 1,
               "minInterval": 1,
               "maxInterval": 65534,

examples/lock-app/cc13x2x7_26x2x7/src/LockManager.cpp

@@ -638,6 +638,8 @@ const char * LockManager::lockStateToString(DlLockState lockState) const
         return "Locked";
     case DlLockState::kUnlocked:
         return "Unlocked";
+    case DlLockState::kUnlatched:
+        return "Unlatched";
     case DlLockState::kUnknownEnumValue:
         break;
     default:

examples/lock-app/lock-common/include/LockEndpoint.h

@@ -66,6 +66,7 @@ class LockEndpoint
 
     bool Lock(const Optional<chip::ByteSpan> & pin, OperationErrorEnum & err, OperationSourceEnum opSource);
     bool Unlock(const Optional<chip::ByteSpan> & pin, OperationErrorEnum & err, OperationSourceEnum opSource);
+    bool Unbolt(const Optional<chip::ByteSpan> & pin, OperationErrorEnum & err, OperationSourceEnum opSource);
 
     bool GetUser(uint16_t userIndex, EmberAfPluginDoorLockUserInfo & user) const;
     bool SetUser(uint16_t userIndex, chip::FabricIndex creator, chip::FabricIndex modifier, const chip::CharSpan & userName,

examples/lock-app/lock-common/include/LockManager.h

@@ -39,6 +39,8 @@ class LockManager
               OperationSourceEnum opSource);
     bool Unlock(chip::EndpointId endpointId, const Optional<chip::ByteSpan> & pin, OperationErrorEnum & err,
                 OperationSourceEnum opSource);
+    bool Unbolt(chip::EndpointId endpointId, const Optional<chip::ByteSpan> & pin, OperationErrorEnum & err,
+                OperationSourceEnum opSource);
 
     bool GetUser(chip::EndpointId endpointId, uint16_t userIndex, EmberAfPluginDoorLockUserInfo & user);
     bool SetUser(chip::EndpointId endpointId, uint16_t userIndex, chip::FabricIndex creator, chip::FabricIndex modifier,

examples/lock-app/lock-common/lock-app.matter

@@ -2152,6 +2152,10 @@ server cluster DoorLock = 257 {
     nullable CredentialStruct credential = 0;
   }
 
+  request struct UnboltDoorRequest {
+    optional OCTET_STRING PINCode = 0;
+  }
+
   response struct GetWeekDayScheduleResponse = 12 {
     INT8U weekDayIndex = 0;
     INT16U userIndex = 1;
@@ -2224,6 +2228,7 @@ server cluster DoorLock = 257 {
   timed command access(invoke: administer) SetCredential(SetCredentialRequest): SetCredentialResponse = 34;
   command access(invoke: administer) GetCredentialStatus(GetCredentialStatusRequest): GetCredentialStatusResponse = 36;
   timed command access(invoke: administer) ClearCredential(ClearCredentialRequest): DefaultSuccess = 38;
+  timed command UnboltDoor(UnboltDoorRequest): DefaultSuccess = 39;
 }
 
 endpoint 0 {
@@ -2593,7 +2598,7 @@ endpoint 1 {
     ram      attribute wrongCodeEntryLimit default = 3;
     ram      attribute userCodeTemporaryDisableTime default = 10;
     ram      attribute requirePINforRemoteOperation default = 0;
-    ram      attribute featureMap default = 0xDB3;
+    ram      attribute featureMap default = 0x1DB3;
     ram      attribute clusterRevision default = 6;
   }
 }

examples/lock-app/lock-common/lock-app.zap

@@ -7023,6 +7023,14 @@
               "source": "client",
               "incoming": 1,
               "outgoing": 0
+            },
+            {
+              "name": "UnboltDoor",
+              "code": 39,
+              "mfgCode": null,
+              "source": "client",
+              "incoming": 1,
+              "outgoing": 0
             }
           ],
           "attributes": [
@@ -7736,7 +7744,7 @@
               "storageOption": "RAM",
               "singleton": 0,
               "bounded": 0,
-              "defaultValue": "0xDB3",
+              "defaultValue": "0x1DB3",
               "reportable": 1,
               "minInterval": 1,
               "maxInterval": 65534,

examples/lock-app/lock-common/src/LockEndpoint.cpp

@@ -28,6 +28,17 @@ bool LockEndpoint::Lock(const Optional<chip::ByteSpan> & pin, OperationErrorEnum
 }
 
 bool LockEndpoint::Unlock(const Optional<chip::ByteSpan> & pin, OperationErrorEnum & err, OperationSourceEnum opSource)
+{
+    if (DoorLockServer::Instance().SupportsUnbolt(mEndpointId))
+    {
+        // If Unbolt is supported Unlock is supposed to pull the latch
+        setLockState(DlLockState::kUnlatched, pin, err, opSource);
+    }
+
+    return setLockState(DlLockState::kUnlocked, pin, err, opSource);
+}
+
+bool LockEndpoint::Unbolt(const Optional<chip::ByteSpan> & pin, OperationErrorEnum & err, OperationSourceEnum opSource)
 {
     return setLockState(DlLockState::kUnlocked, pin, err, opSource);
 }

examples/lock-app/lock-common/src/LockManager.cpp

@@ -158,6 +158,18 @@ bool LockManager::Unlock(chip::EndpointId endpointId, const Optional<chip::ByteS
     return lockEndpoint->Unlock(pin, err, opSource);
 }
 
+bool LockManager::Unbolt(chip::EndpointId endpointId, const Optional<chip::ByteSpan> & pin, OperationErrorEnum & err,
+                         OperationSourceEnum opSource)
+{
+    auto lockEndpoint = getEndpoint(endpointId);
+    if (nullptr == lockEndpoint)
+    {
+        ChipLogError(Zcl, "Unable to unbolt the door - endpoint does not exist or not initialized [endpointId=%d]", endpointId);
+        return false;
+    }
+    return lockEndpoint->Unbolt(pin, err, opSource);
+}
+
 bool LockManager::GetUser(chip::EndpointId endpointId, uint16_t userIndex, EmberAfPluginDoorLockUserInfo & user)
 {
     auto lockEndpoint = getEndpoint(endpointId);

examples/lock-app/lock-common/src/ZCLDoorLockCallbacks.cpp

@@ -40,6 +40,12 @@ bool emberAfPluginDoorLockOnDoorUnlockCommand(chip::EndpointId endpointId, const
     return LockManager::Instance().Unlock(endpointId, pinCode, err, OperationSourceEnum::kRemote);
 }
 
+bool emberAfPluginDoorLockOnDoorUnboltCommand(chip::EndpointId endpointId, const Optional<ByteSpan> & pinCode,
+                                              OperationErrorEnum & err)
+{
+    return LockManager::Instance().Unbolt(endpointId, pinCode, err, OperationSourceEnum::kRemote);
+}
+
 bool emberAfPluginDoorLockGetUser(chip::EndpointId endpointId, uint16_t userIndex, EmberAfPluginDoorLockUserInfo & user)
 {
     return LockManager::Instance().GetUser(endpointId, userIndex, user);

src/app/clusters/door-lock-server/door-lock-server-callback.cpp

@@ -58,6 +58,13 @@ emberAfPluginDoorLockOnDoorUnlockCommand(chip::EndpointId endpointId, const Opti
     return false;
 }
 
+bool __attribute__((weak))
+emberAfPluginDoorLockOnDoorUnboltCommand(chip::EndpointId endpointId, const Optional<ByteSpan> & pinCode, OperationErrorEnum & err)
+{
+    err = OperationErrorEnum::kUnspecified;
+    return false;
+}
+
 void __attribute__((weak)) emberAfPluginDoorLockOnAutoRelock(chip::EndpointId endpointId) {}
 
 // =============================================================================

src/app/clusters/door-lock-server/door-lock-server.cpp

@@ -114,7 +114,9 @@ bool DoorLockServer::SetLockState(chip::EndpointId endpointId, DlLockState newLo
     // DlLockState::kNotFullyLocked has no appropriate event to send. Also it is unclear whether
     // it should schedule auto-relocking. So skip it here. Check for supported states explicitly
     // to handle possible enum extending in future.
-    VerifyOrReturnError(DlLockState::kLocked == newLockState || DlLockState::kUnlocked == newLockState, success);
+    VerifyOrReturnError(DlLockState::kLocked == newLockState || DlLockState::kUnlocked == newLockState ||
+                            DlLockState::kUnlatched == newLockState,
+                        success);
 
     // Send LockOperation event
     auto opType = (DlLockState::kLocked == newLockState) ? LockOperationTypeEnum::kLock : LockOperationTypeEnum::kUnlock;
@@ -3563,6 +3565,28 @@ bool emberAfDoorLockClusterUnlockWithTimeoutCallback(
     return true;
 }
 
+bool emberAfDoorLockClusterUnboltDoorCallback(
+    chip::app::CommandHandler * commandObj, const chip::app::ConcreteCommandPath & commandPath,
+    const chip::app::Clusters::DoorLock::Commands::UnboltDoor::DecodableType & commandData)
+{
+    emberAfDoorLockClusterPrintln("Received command: UnboltDoor");
+
+    if (DoorLockServer::Instance().HandleRemoteLockOperation(commandObj, commandPath, LockOperationTypeEnum::kUnlock,
+                                                             emberAfPluginDoorLockOnDoorUnboltCommand, commandData.PINCode))
+    {
+        // appclusters.pdf 5.3.3.25:
+        // The number of seconds to wait after unlocking a lock before it automatically locks again. 0=disabled. If set, unlock
+        // operations from any source will be timed. For one time unlock with timeout use the specific command.
+        uint32_t autoRelockTime = 0;
+
+        VerifyOrReturnError(DoorLockServer::Instance().GetAutoRelockTime(commandPath.mEndpointId, autoRelockTime), true);
+        VerifyOrReturnError(0 != autoRelockTime, true);
+        DoorLockServer::Instance().ScheduleAutoRelock(commandPath.mEndpointId, autoRelockTime);
+    }
+
+    return true;
+}
+
 bool emberAfDoorLockClusterSetUserCallback(chip::app::CommandHandler * commandObj,
                                            const chip::app::ConcreteCommandPath & commandPath,
                                            const chip::app::Clusters::DoorLock::Commands::SetUser::DecodableType & commandData)

src/app/clusters/door-lock-server/door-lock-server.h

@@ -185,6 +185,8 @@ class DoorLockServer
         return GetFeatures(endpointId).Has(Feature::kUser) && SupportsAnyCredential(endpointId);
     }
 
+    inline bool SupportsUnbolt(chip::EndpointId endpointId) { return GetFeatures(endpointId).Has(Feature::kUnbolt); }
+
     bool OnFabricRemoved(chip::EndpointId endpointId, chip::FabricIndex fabricIndex);
 
     static void DoorLockOnAutoRelockCallback(chip::System::Layer *, void * callbackContext);
@@ -490,6 +492,10 @@ class DoorLockServer
         chip::app::CommandHandler * commandObj, const chip::app::ConcreteCommandPath & commandPath,
         const chip::app::Clusters::DoorLock::Commands::UnlockWithTimeout::DecodableType & commandData);
 
+    friend bool emberAfDoorLockClusterUnboltDoorCallback(
+        chip::app::CommandHandler * commandObj, const chip::app::ConcreteCommandPath & commandPath,
+        const chip::app::Clusters::DoorLock::Commands::UnboltDoor::DecodableType & commandData);
+
     friend bool emberAfDoorLockClusterSetHolidayScheduleCallback(
         chip::app::CommandHandler * commandObj, const chip::app::ConcreteCommandPath & commandPath,
         const chip::app::Clusters::DoorLock::Commands::SetHolidaySchedule::DecodableType & commandData);
@@ -910,6 +916,19 @@ bool emberAfPluginDoorLockOnDoorLockCommand(chip::EndpointId endpointId, const O
 bool emberAfPluginDoorLockOnDoorUnlockCommand(chip::EndpointId endpointId, const Optional<chip::ByteSpan> & pinCode,
                                               OperationErrorEnum & err);
 
+/**
+ * @brief User handler for UnboltDoor command (server)
+ *
+ * @param   endpointId      endpoint for which UnboltDoor command is called
+ * @param   pinCode         PIN code (optional)
+ * @param   err             error code if door unbolting failed (set only if retval==false)
+ *
+ * @retval true on success
+ * @retval false if error happenned (err should be set to appropriate error code)
+ */
+bool emberAfPluginDoorLockOnDoorUnboltCommand(chip::EndpointId endpointId, const Optional<chip::ByteSpan> & pinCode,
+                                              OperationErrorEnum & err);
+
 /**
  * @brief This callback is called when the AutoRelock timer is expired.
  *

src/app/tests/suites/DL_LockUnlock.yaml

@@ -49,6 +49,38 @@ tests:
       response:
           value: 1
 
+    - label: "Verify that lock state attribute value is set to Locked"
+      command: "readAttribute"
+      attribute: "LockState"
+      response:
+          value: 1
+
+    - label: "Try to unbolt the door without PIN"
+      command: "UnboltDoor"
+      timedInteractionTimeoutMs: 10000
+
+    - label: "Verify that lock state attribute value is set to Unlocked"
+      command: "readAttribute"
+      attribute: "LockState"
+      response:
+          value: 2
+
+    - label: "Try to lock the door without a PIN"
+      command: "LockDoor"
+      timedInteractionTimeoutMs: 10000
+
+    - label: "Verify that lock state attribute value is set to Locked"
+      command: "readAttribute"
+      attribute: "LockState"
+      response:
+          value: 1
+
+    - label: "Verify that lock state attribute value is set to Locked"
+      command: "readAttribute"
+      attribute: "LockState"
+      response:
+          value: 1
+
     - label: "Create new lock/unlock user"
       command: "SetUser"
       timedInteractionTimeoutMs: 10000
@@ -149,6 +181,22 @@ tests:
                           "UserIndex": null,
                           "Credentials": null,
                       }
+          - values:
+                - value:
+                      {
+                          "LockOperationType": 1,
+                          "OperationSource": 7,
+                          "UserIndex": null,
+                          "Credentials": null,
+                      }
+          - values:
+                - value:
+                      {
+                          "LockOperationType": 0,
+                          "OperationSource": 7,
+                          "UserIndex": null,
+                          "Credentials": null,
+                      }
           - values:
                 - value:
                       {