Door Lock#

The Z-Wave certified Door Lock application shows a lock implementation. It supports user codes to open a door and thereby eliminate the need for traditional keys. It is possible to both lock and unlock the door remotely through the Z-Wave protocol.

The Door Lock application is based on:



Role Type	Listening Sleeping End device (LSS / FLiRS)
Supporting Device Type	Actuator
Device Type	Lock
Generic Type	Entry Control
Specific Type	Door Lock
Requested security keys	S0 and S2_ACCESS The Door Lock features depend on the security level

The application will only work when securely added to a network by a controller supporting security. The controller MUST support security S2_Access_Control or S0 in order to be able to control the door lock.

Not implemented Door lock functionality:

Timed Operation mode
Door Lock condition
Inside Door Handle State
Functionality handling Lock timeout
Target mode
Auto-Relock, Hold And Release, Block to Block, and Twist Assist

Supported Command Classes#

The Door Lock application implements mandatory and some optional command classes. The table below lists the supported Command Classes, their version, and their required Security class, if any.


Command Class	Version	Required Security Class
Association	2	S0 or Access Control
Association Group Info	3	S0 or Access Control
Basic	2	S0 or Access Control
Battery	1	S0 or Access Control
Device Reset Locally	1	S0 or Access Control
Door Lock	4	S0 or Access Control
Firmware Update Meta Data	5	S0 or Access Control
Indicator	3	S0 or Access Control
Manufacturer Specific	2	S0 or Access Control
Multi-Channel Association	3	S0 or Access Control
Powerlevel	1	S0 or Access Control
Security 0	1	None
Security 2	1	None
Supervision	1	None
Transport Service	2	None
User Code	1	S0 or Access Control
User Credential*	1	S0 or Access Control
Version	3	S0 or Access Control
Z-Wave Plus Info	2	None

*: The User Credential Command Class is only available on specific boards. See the section User Credential Command Class.

User Credential Command Class#

The User Credential Command Class is enabled by default on the following boards:

BRD2705A
BRD4400B
BRD4400C
BRD4401B
BRD4401C

Support for this command class can be disabled if the User Code Command Class is sufficient, by disabling the User Credential Command Class component.

To enable this command class on other boards, due to flash memory constraints, it is recommended to first disable the Z-Wave CLI Common component before enabling the User Credential Command Class component.

The default credentials are created when the inclusion process finishes.

If the User Code Command Class is enabled:
- User Code 1 is created with a value of 3494.
If the User Credential Command Class is enabled:
- A Programming User with the unique identifier 1, called "Admin" is created.
- A PIN Code associated with user 1 is created with a value of 3494.

To operate the door bolt with the default credentials, the end device must first be included in a Z-Wave network.

Basic Command Class mapping#

The Basic Command Class is mapped according to the table below.


Basic Command	Mapped Command
Basic Set (Value)	Door Lock Operation Set (Door Lock Mode)
Basic Report (Current Value = 0x00)	Door Lock Operation Report (Door Lock Mode = 0x00)
Basic Report (Current Value = 0xFF)	Door Lock Operation Set (Door Lock Mode)

Association Groups#

The table below shows the available association groups, including supported command classes for Z-Wave and Z-Wave Long Range respectively.


ID	Name	Node Count	Description
1	Lifeline	X	Supports the following command classes: Device Reset Locally: triggered upon reset. Battery: Triggered upon low battery. Door Lock: Triggered upon a change in door lock configuration. Door Lock: Triggered upon a change in door lock operation. Indicator Report: Triggered when LED0 changes state. User Code: Triggered when a user code record is modified. User Credential*: Triggered when a Duress User enters a Credential.

X: For Z-Wave node count is equal to 5 and for Z-Wave Long Range it is 1.\ *: The User Credential Command Class is only available on specific boards. See the section User Credential Command Class.

Usage of Buttons and LED Status#

We are differentiating four different types of button presses. The following types are the same for the BTN0 and BTN1 on the WSTK board. The duration values can be configured under the config directory in app_button_press_config.h file in each generated application/project.

Please note external wakeup is not supported on button 1 in case of brd2603a and brd2603b.


Press Type	Duration
Short Press	0 - 400 ms
Medium Press	401 - 1500 ms
Long Press	1501 - 5000 ms
Very Long Press	Every press longer than Long Press


Button	Action	Description
RST	Press	Resets the firmware of an application (like losing power). All volatile memory will be cleared.
BTN0	Short Press	Simulates entering a PIN Code on a keypad via the User Credential API. The entered PIN Code is hard-coded with the value of 3494. A valid Credential entry (i.e., button press) toggles the Door Lock Mode between Secured and Unsecured, with a delay of 2 seconds, to simulate timed hardware operation. If Credential data for User UID 1, Slot 1 is changed to something other than the default PIN Code, the Door Lock Mode can no longer be toggled by pressing this button.
Medium Press	Sends Battery Report
Long Press	Changes the outside door handle mode to active if it was inactive and vice versa.
BTN1	Short Press	Enter "learn mode" (sending node info frame) to add/remove the device. Removing the device from a network will reset it.
Very Long Press	Perform a reset to factory default operation of the device, and a Device Reset Locally Notification Command is sent via Lifeline.


LED	Functionality	Description
LED0	Indicator:	Blinks with 1 Hz when learn mode is active. Used for Indicator Command Class.
LED1	Bolt:	Led off -> bolt unlocked Led on -> bolt locked

Firmware Update#

This section will describe backward compatibility when upgrading the Door Lock application from one SDK to a newer version.

CLI Support#

In case CLI support is needed pelase install zw_cli_common component to the project. Please note the zw_cli_common component will modify the power consumption in case of sleeping applications. Like door lock keypad, sensor pir or multilevel sensor. CLI cannot work with sleep mode, after a reset the application stays awake until the user issues the enable_sleeping command. From that point CLI won't work and sleep mode will be reached until the next reset.


Command	Arguments	Description
set_learn_mode		Toggling the learn mode functionality. In case the learn mode started, but inclusion does not happen, learn mode will automatically stop after about 30 seconds
factory_reset	-	Executing factory reset
get_dsk	-	Printing out the generated DSK of the device
get_region	-	Printing out the set region of the application
battery_report	-	Sending a battery report
enter_user_code	Your current user code. It must be between 4 and 10 digits.	Entering a minimum 4 digit long user code
set_new_user_code	Your new user code. It must be between 4 and 10 digits.	Setting a new user code wich's lenght must be between 4 and 10 digits
set_doorhandle_state	State of the door handle as string. Possible values are deactivate and activate	Updating the doorhandle state to locked or unlocked
sleeping	[string] "enable" or "disable"	Enable or disable sleeping. After pushing the reset button (or resetting with commander) the device will be awake for a given amount of time if the CLI component is added to the project. During this time the user can prevent the sleeping. For more information check the `zw_cli_sleeping` component.
get_doorhandle_state	-	Shows the state of the door handle. Can be "pressed" or "released"
get_doorbolt_state	-	Shows the state of the door bolt. Can be "unlocked" or "locked"
get_doorlatch_state	-	Shows the state of the door latch. Can be "closed" or "open"

User Credential Related CLI commands#

The following commands exist only if User Credential Command class is available. See the section User Credential Command Class.


Command	Arguments	Description
u3c_add_user	[string] Name of the user	This command will create a new user in U3C database. The user's UUID will be autogenerated.
u3c_add_credential	[uint16] Associated User UID [string] Type of the new credential. Can be "pin" or "password" [uint16] Slot number of the new credential [string] Credential data. E.g. 3494	This command will create a new credential and assign it to an existing user.
u3c_modify_user	[uint16] User UID to modify [string] Attribute to modify. Can be "type", "name" or "active" [string] New value of the attribute	This command modifies an attribute of an existing user
u3c_modify_credential	[string] Type of the credential. Can be "pin" or "password" [uint16] Slot of the credential [string] Attribute to change. Can be "data", "uuid" or "slot" [string] New value of the attribute	This command modifies an existing credential.
u3c_delete_user	[uint16] User UID of an existing user to delete	This command deletes an existing user and all of the assigned credentials.
u3c_delete_credential	[string] Type of the credential. Can be "pin" or "password" [uint16] Slot of the credential	This command deletes an existing credential from the database.
u3c_get_user	[uint16] User UID of an existing user	This command prints the information of an existing user.
u3c_get_credential	[string] Type of the credential. Can be "pin" or "password" [uint16] Slot of the credential	This command prints the information of an existing credential.
u3c_enter_credential	[string] Type of the credential. Can be "pin" or "password" [string] Credential data	This command enters an existing credential and validates it.
u3c_credential_learn_start	[uint16] Learn target UUID [string] Type of the credential. Can be "pin" or "password" [uint16] Learn target slot	Initiates the Credential Learn process locally.
u3c_credential_learn	[string] Credential data. E.g. 3494	Enter credential data for User Credental Learn process