Door Lock

Overview

This sample demonstrates the usage of the Matter application layer to build a door lock device. A door lock is a device that ensures the security of doors and can be operated manually or remotely.

This device works as a Matter accessory device, meaning it can be paired and controlled remotely over a Matter network built on top of a low-power 802.15.4 Thread network.

The sample uses buttons and a controller to change the state of the door lock, and LEDs to show the state of these changes.

Door Lock Credentials

Door lock credentials can be used to control remote access to the door lock. This sample supports PIN (Personal Identification Number) code credentials, which can be verified via input from a keypad or wirelessly. These credentials are stored in flash and persist after a device reboot.

This sample supports multiple door lock users and credentials, which can be configured through the AppConfig.h file located at matter/connectedhomeip/examples/<app_name>/realtek_bee/main/include.

  • CONFIG_LOCK_NUM_USERS：Maximum number of users supported by the door lock

  • CONFIG_LOCK_NUM_CREDENTIALS：Maximum number of credentials in total

  • CONFIG_LOCK_NUM_CREDENTIALS_PER_USER： Maximum number of credentials that can be assigned to one user

Requirements

The sample supports the following development kits:

Supported Development Kits

Hardware platforms

Board name

RTL8777G HDK

RTL8777G EVB

Prepare Matter Environment

To set up the Matter environment, follow the steps listed in Development Setup.

Prepare CHIP Tool

The CHIP Tool (chip-tool) is a Matter controller implementation that allows commissioning a Matter device into the network and communicating with it using Matter messages, which may encode Data Model actions, such as cluster commands. The tool also provides other utilities specific to Matter, such as parsing the setup payload or performing discovery actions.

To build the target, follow the steps listed on the CHIP Tool.

Configurations

Sample Configurations

Our example samples all have default configurations. If wanting to modify the sample configuration, change CHIPProjectConfig.h under the path matter/connectedhomeip/examples/<app_name>/realtek_bee/main/include, where app_name refers to the name of the application, for example, lighting-app.

See APP Config for more information about configuration items.

Factory Data Configurations

The factory data is disabled by default for the evb board. To use factory data, follow the section Enable Factory Data Support and Factory Data Generation in Factory Data.

Building and Downloading

Building

Navigate to the specified directory and build door-lock app.

$ cd beeSDK/subsys/matter/samples
$ rm -r build/
$ ./build.py rtl8777g lock

Downloading

After a successful compilation, the app bin matter-cli-mtd_bank0_MP_dev_*.bin will be generated in the directory build/bank0/bin.

To download app bin into EVB board, follow the steps listed on the Downloading in Quick Start. If the factory data is enabled, also refer to Program Factory Data in Factory Data.

Then press reset button on EVB board and it will start running.

Experimental Verification

After programming the sample to your EVB board, complete the steps in the following sections.

Preparation Phase

  1. Connect the kit to the computer using a USB cable.

  2. Open a serial port connection to the kit using a terminal emulator (for example, Tera Term).

  3. If the device was not erased during the programming, press and hold SW2 for more than 6.5 seconds until the factory reset takes place.

  4. Press RST to start the Bluetooth LE advertising.

  5. Commission the device to the Matter network. See Commissioning the Device for more information. During the commissioning process, write down the value for the lock node ID for later use (<lock_node_ID>).

Testing Phase

Manual Control

  1. Observe that LED 0 is turned on, which indicates the door lock is closed. The device defaults to a locked state.

  2. Press SW1 to unlock the door; when the lock is opening, LED 0 will blink. After about two seconds, LED 0 turns off, and the lock has been opened.

  3. Press SW1 again to lock the door. LED 0 will blink, then stay steadily lit, and the lock has been closed.

Testing Remote Access with PIN Code Credential

  1. The door lock defaults to a locked state, and LED 0 is steadily lit.

  2. Add a new user.

    $ ./chip-tool doorlock set-user OperationType UserIndex UserName UserUniqueID UserStatus UserType CredentialRule <lock_node_ID> <endpoint_id>

    • <light_bulb_node_ID>：Obtained from previous step

    • <endpoint_id>：ID of the endpoint with Door Lock cluster implemented

    For example:

    $ ./chip-tool doorlock set-user 0 1 xxx 6452 1 0 0 1 1  --timedInteractionTimeoutMs 1000

    The command adds a user with index 1, named xxx, with a UniqueID of 6452. The new user’s UserStatus is set to 1, and both UserType and CredentialRule are set to 0.

  3. Add the PIN code credential to the xxx user:

    $ ./chip-tool doorlock set-credential OperationType Credential CredentialData UserIndex UserStatus UserType <lock_node_ID> <endpoint_id>

    For example:

    $ ./chip-tool doorlock set-credential 0 '{ "credentialType" : 1 , "credentialIndex" : 1 }' 123456 1 null null 1 1 --timedInteractionTimeoutMs 1000

    This command adds a credential with both type and index set to 1. The CredentialData is 123456, and it is associated with a user index of 1. Both UserStatus and UserType are set to null.

  4. Unlock the door lock using the PIN code added in step 3.

    $ ./chip-tool doorlock unlock-door 1 1 --timedInteractionTimeoutMs 1000 --PINCode 123456

  5. The LED 0 is flashed and then turned off, and the lock is opened.