## Door Lock DDK
This document constitutes a hardware and software technical specification for a Door Lock to integrate and interoperate with the Comcast platforms. Door Locks are a key part of the Comcast security and home control product offering.
The purpose of this document is to provide Comcast Partners with the essential information necessary to supply Door Locks that work efficiently and reliably with Comcast platforms.
### Comcast System Architecture
Please refer to the [Comcast Platform Overviews](/xh/kbase/comcast-platform-overviews) page for more information on the Comcast platforms and how this device will interact with the system.
### Use Cases
The following are a few of the use cases for Door Locks operating within the Comcast system. Note that these do not represent the entire set of use cases.
#### Use Case: Manage access to home/business
The primary use case for door locks in the Comcast system is to enable users to manage:
- Who can unlock the door (e.g., inhabitants, guests, babysitter, lawn care provider, cable installer, pool maintenance provider)
- When authorized users can unlock the door (e.g., all the time, on weekends, ad hoc)
- Which doors they can unlock (e.g., front door, back door, office, garage, pool house)
Users will operate the lock remotely and locally, and consumers are increasingly downsizing the size of their wallets and key chains, so the door lock may have a key, keycard reader, and/or keypad.
#### Use Case: Notify when a user accesses or if things aren't as they should be
Door locks are a critical component in any home automation or security system. Both expected and unexpected behavior or issues with door locks require immediate notification to the user so that he can take action, if necessary. Door locks and the Comcast platform need to be able to alert users when a particular user accesses the door lock, the door lock fails to engage as expected, the door has been left open, or a user enters an incorrect access code multiple times.
#### Use Case: Notify when batteries are low and ensure fail-safe operation
The vast majority of home/small business doors do not have mains powered electrical wiring available. For this reason, Comcast and its customers require battery-operated door locks for nearly all deployments. Batteries are a critical system failure opportunity, so battery-powered door locks must alert the Comcast system when battery levels approach depletion to ensure adequate time to change the batteries. They must also ensure fail-safe operation should the batteries deplete or communications be lost with the Comcast system, so the lock may need to locally store, refresh, and update changes in access permissions on a frequent basis.
### Requirements and Conformance
The requirements encompass functional and non-functional hardware, firmware, application, performance, security, and operations, maintenance, and logistics requirements. An explanation of how Comcast captures and organizes requirements can be found in the [Comcast DDK Requirements Framework](/xh/kbase/comcast-platform-overviews/device-development-kits-and-supporting-documentation). Requirements can be found in the Requirements section along with notes and columns for Partners to state their conformance.
Some device types have Basic and Premium versions. These are meant to highlight areas for Partners to differentiate and distinguish themselves competitors.
Partners are requested to note their product's conformance with Comcast's requirements in the appropriate column of the Requirements worksheet and return to Comcast. Please also provide any notes or descriptive text in the Partner Comments column.
Requirements can be one of five types:
**Required (M)**: Conformance is mandatory in order to meet Comcast conformance.
**Optional (O)**: Conformance is optional in order to meet Comcast conformance. Some Comcast customers may require optional functionality. Optional functional requirements are also used to provide design recommendations and guidance.
**Conditionally Mandatory (CM)**: Conformance is mandatory depending on the type of product and its capabilities. For example, a battery-powered product will conditionally be required to support certain battery performance metrics and indicate and report battery status. Depending on the technology (e.g., ZigBee, Z-Wave, Wi-Fi) used, there will be conditional requirements specified to perform certain functionality. CM requirements should be interpreted as, "If \<conditional statement = TRUE\>, then \<the remaining stated functionality shall be supported\>."
**Not Applicable (NA)**:Conformance is not required at this time but may signal future product requirements direction. It may also mean a requirement will never apply based on the fundamental device functionality or technology (e.g., ZigBee, Z-Wave).
**Not Supported (NS)**: Conformance is not required, is optional under a given specification (e.g., ZigBee HA, Comcast Certified API), but Comcast does not support the use of the feature at this time. Partners are free to implement this requirement, but they will not be able to advertise or claim the functionality is enabled within the Comcast ecosystem.
**Future Support (FS)**: Partner should be aware that this requirement may become optional or mandatory in the future. These requirements are provided as an indication of roadmap features Partners may wish to consider in their development.
The Implementation Guidelines section below provide additional explanation and guidance of required functionality that may be difficult to describe in the Requirements Conformance table.
#### Door Lock Requirements
[Comcast - Door Lock Requirements - v1.3.5 - 181112](/media/file/dvp/2019/03/Comcast---Door-Lock-Requirements---v1.3.5---1801112-1.xlsx)
### Implementation Guidelines
The Requirements document will sometimes make reference to implementation guidelines or the Specification. The Implementation Guidelines section provides additional detail and explanation of functionality that is difficult to capture in a spreadsheet.
A device that does not have a network should search for a network that is open for joining. This should begin on power up with no network or after being defaulted. A device must scan all valid Zigbee channels when associating.
### Manual Defaulting
All devices in the Comcast ecosystem SHALL support a hardware and over-the-air (OTA) method to reset to factory defaults. The OTA method is defined by the application (e.g., Z-Wave, ZigBee, Comcast Certified) and is defined in [Over-the-Air Defaulting](#over-the-air-defaulting). The hardware method is up to the Partner to determine as long as it meets the [Door Lock Requirements](#door-lock-requirements). Comcast suggests the following method be employed:
This method assumes the device has implemented an air gap switch. Protocol for resetting to factory defaults:
1. Move the air gap switch to the OFF position (i.e., power down the device).
2. While pressing and holding the TOGGLE or LEVEL UP button for the device, move the air gap switch to the ON position.
3. Wait for the LED indicator on the device to illuminate.
4. Release the TOGGLE or LEVEL UP button.
The device should power cycle and reset itself to factory default settings, remove all network settings, network credentials, bindings, and other user configured information.
### Over-the-Air Defaulting
For ZigBee devices, the process for OTA defaulting shall be as follows:
1. CPE sends a Reset to Factory Default command to the device. By definition in [(/xh/kbase/comcast-platform-overviews/device-development-kits-and-supporting-documentation/ecosystem-ddks/thermostat-ddk)], this command resets the device and clears all settings, including bindings, except for network commissioning settings.
2. CPE sends a Leave Network command to the device.
At this point, the device is in a factory default state.
### Network Rejoin Backoff Algorithm
When a device cannot talk to its parent, it should perform a rejoin to find a new parent. Not being able to talk to your parent is indicated by not receiving a MAC layer acknowledge on a message sent to the parent. There are a number of reasons that a device could "lose" its parent in a ZigBee network. Many of the reasons are very short in duration while others can last indefinitely. For instance, a firmware upgrade of the Comcast CPE in the home will end with a CPE reboot, causing the ZigBee network to be down for a short period of time. Devices that have the CPE as their parent will not receive MAC layer ACKs during that time. Devices that are joined to other AC mains-powered routing devices (e.g., lighting modules, mains powered repeaters, etc.) will experience issues if the parent device is unplugged, deleted from the network, or simply moved to another room in the house. Channel and network key changes will cause sleepy devices to miss the notification of the change and will thus cause the inability to talk to their parent. Long-term issues could be caused by power outages in the home or removal or failure of the CPE.
#### AC Mains-Powered ZigBee End Devices
For AC mains powered end devices that have lost their parent, they SHOULD attempt to rejoin at least once every 60 seconds.
#### Battery-Powered ZigBee End Devices
For a device primarily powered by a battery, there needs to be a balance between responsiveness of the device on the network and its battery life. The short term issues mentioned above can be resolved with a quick rejoin while the long term issues will drain the device's battery quickly if care is not taken with the backoff algorithm.
There are numerous options for backoff algorithms, and different algorithms work better for different devices. An event-based (e.g., user-initiated action) algorithm may work well for door/window sensors but may cause excessive battery usage for a motion sensor that is tripping on a regular basis and may not provide enough responsiveness for a thermostat or door lock or smoke sensor that rarely has an event.
There is not a single algorithm that will be optimal for all devices, but the implementation guidelines presented here should be incorporated into the Partner's backoff algorithm implementation, which must be documented with each device submission for Comcast Developer Program Certification.
1. The initial rejoin attempt should be a secure rejoin on the current channel. The initial rejoin should be done within 2 seconds of the MAC layer ACK failure.
2. The second rejoin attempt should be a secure rejoin across all channels. The second rejoin should be done within 5 seconds of the failure of the first rejoin.
3. Subsequent rejoins should be unsecure rejoins across all channels and should be done after 1 minute, 2 minutes, 4 minutes, 8 minutes, 16 minutes, and 30 minutes.
4. After this initial rejoin backoff, a device without a parent should never go longer than 30 minutes without attempting to rejoin the network.
- This only applies for a device attempting to find its parent after losing connectivity, NOT as a general requirement.
5. Event based rejoins should be implemented when it makes sense for the device type.
- This is especially desirable for devices that have direct user interaction.
6. If the device's primary power source is a battery, the battery life must be at least 60 days in the absence of a parent.
### Battery Measurement Guidelines
Accurate battery measurement is a key feature of the Comcast ecosystem. Comcast customers require the ability to be notified when a device's battery level is low well in advance of depletion. In some cases, Comcast customers may schedule a truck roll to visit the customer premises to replace batteries and check up on the CPE and devices.
To ensure consistent and meaningful battery level information being reported to the CPE, devices SHALL implement the following battery measurement guidelines:
1. Battery voltage measurement SHALL be performed at the moment of peak current draw.
1. This may vary depending on the device but typically occurs at transmit or when performing mechanical behavior (e.g., operating relays on a thermostat, actuating the deadbolt on a door lock).
2. Manufacturers SHALL determine the moment of peak current draw at which to measure battery voltage.
2. The battery voltage measurement reported to the Comcast CPE SHALL be the average of the last 16 measurements.
1. This smoothes the natural variation of measurements due to temperature and other operational variance.
3. Only when the battery voltage measurement average reaches the manufacturer-defined battery voltage threshold levels shall the appropriate alarm or attribute report be updated and reported to the Comcast CPE.
4. Devices SHALL not clear battery alarms or update threshold status attributes unless the battery has been replaced.
1. Upon device reboot after battery change, device SHALL measure battery voltage during network rejoin transmission in order to determine that the battery voltage level is above any battery voltage reporting threshold
2. A hysteresis mechanism SHALL be employed that requires the voltage level to increase by a sufficient amount to prevent temperature-related fluctuations in the voltage measurement due from causing the alarm or attribute report to repeatedly toggle at the margin of the voltage threshold.
### Battery Status and Alarms
The battery level of a Door Lock that is powered by batteries is a critical part of the manageability of the device for service providers. On a new or fully charged battery, the expected battery life of the Door Lock prior to functional failure shall be 2 years.
For devices with single use batteries, the device shall periodically report the battery voltage measurement to the Comcast CPE. Upon reaching one of the factory-programmed battery voltage thresholds corresponding with 60-, 30-, 7-day, or "last gasp" battery level, the device shall report this threshold being reached to the Comcast CPE. Only upon installation of fresh batteries SHALL the device clear these threshold alarms. Also, upon installation of new batteries after the battery alarm state has indicated that the batteries were low, the device SHALL send a battery alarm state report indicating that the batteries are no longer low.
For devices with rechargeable batteries, the device shall periodically report battery state to the Comcast CPE each 10% reduction in remaining life from initial installation of the batteries to 10% remaining life (e.g., 100%, 90%, 80%, …, 30%, 20%, 10%). The device shall periodically report battery state to the Comcast CPE each 1% reduction in remaining life from 10% to end of charge (e.g., 10%, 9%, …, 2%, 1%) or as configured to report by the Comcast CPE.
ZigBee devices shall use the Power Configuration cluster and the new battery voltage thresholds and battery alarm state added in HA v1.2. Devices are not required to implement the Alarm cluster mechanism for reporting battery voltage thresholds. Table 1 below provides ZigBee behavior guidelines for reporting battery alarms.
**Table 1 – Zigbee Battery Voltage Reporting Guidelines**
| **Remaining Battery Life** | **Voltage Threshold** | **Alarm Code (optional)** | **Notes** |
| --- | --- | --- | --- |
| 60 days | BatteryVoltageThreshold3 | 0x13 | When the remaining battery life is 60 days of operation, the device shall update the BatteryAlarmStatus attribute. |
| 30 days | BatteryVoltageThreshold2 | 0x12 | When the remaining battery life is 30 days of operation, the device shall update the BatteryAlarmStatus attribute. |
| 7 days | BatteryVoltageThreshold1 | 0x11 | When the remaining battery life is 7 days of operation, the device shall update the BatteryAlarmStatus attribute. |
| Unable to operate (i.e., "last gasp") | BatteryVoltageMinThreshold | 0x10 | When the remaining is life is insufficient to ensure reliable operation of the radio or device, the device shall update the BatteryAlarmStatus attribute. |
### Single Firmware Image for Devices with Multiple Processors
All Partners are required to provide a single firmware image when updating their product via the Comcast system. This requirement exists to help Comcast and its customers manage the update process across hundreds to thousands of devices. Icontrol recommends the following method for updating firmware:
1. Each time a OTA client receives a Query Next Image command, it downloads the full OTA header and the individual headers for each sub-processor image.
2. OTA client interprets the individual headers and determines based on its factory-programmed order for updating processors which processor requires updating depending on the file versions included in the header.
3. OTA client begins downloading the first image.
4. OTA client applies the first image and reboots from the second boot partition on that processor.
5. The OTA client does NOT revise its File Version until after it has completed firmware update for all processors.
6. OTA client sends a Query Next Image Request command and receives the appropriate response from the Comcast CPE.
7. OTA client determines once again which processors need updating.
8. OTA client begins downloading update from the location specified in the individual headers.
9. OTA client repeates steps 4 to 8 until all processors have completed updating.
### ZigBee RF Performance Specification
All ZigBee devices in the Comcast ecosystem must undergo RF performance testing to ensure adequate performance in the field and enable Comcast customers to compare products from manufacturers using a standardized metric.
- Comcast ZigBee RF Performance Specification ([link](/xh/kbase/comcast-platform-overviews/device-development-kits-and-supporting-documentation/comcast-zigbee-rf-performance-specification))
For door locks with SKUs in multiple finishes (e.g., brass, nickel, aluminum, bronze), the finish with the worst RF performance SHALL be submitted for RF testing. This is done to ensure that the reported RF performance is conservative from the Comcast customer's perspective. Comcast will work with Developers to determine which finish has the worst RF properties
Additionally, all door lock DUT samples for RF testing SHALL be submitted mounted on a stand provided by Comcast to ensure consistent test conditions and minimize any effects on performance from the use of different stands and materials.
For more information, see [Device Samples for RF Testing](/xh/kbase/comcast-platform-overviews/device-development-kits-and-supporting-documentation/zigbee-device-development-guide).
### Test Plans
Partners are required to test their device prior to submitting to Comcast. In addition to any Z-Wave or ZigBee Alliance test plans, Comcast -certified Door Locks must pass the following test plans:
- Comcast Generic ZigBee Device Unit Test Plan ([link](/xh/kbase/comcast-platform-overviews/device-development-kits-and-supporting-documentation/ecosystem-ddks/zigbee-devices-additional-test-plans/generic-zigbee-device-unit-test-plan))
- Comcast Generic ZigBee Device Integration Test Plan ([link](/xh/kbase/comcast-platform-overviews/device-development-kits-and-supporting-documentation/ecosystem-ddks/zigbee-devices-additional-test-plans/generic-zigbee-device-integration-test-plan))
- ZigBee Door Lock Integration Test Plan ([link](/xh/kbase/comcast-platform-overviews/device-development-kits-and-supporting-documentation/ecosystem-ddks/door-lock-ddk/door-lock-test-plan))
Partners should follow the instructions that come with their Comcast Development Kit in order to conduct this testing, or they may elect to use a third party test harness (e.g., from an Comcast Certified Partner Test Lab).
1. "ZigBee Cluster Library Specification." ZigBee Alliance. Document 07-5123, revision 03. 26 April 2010.
2. "ZigBee Home Automation Public Application Profile v1.2." ZigBee Alliance. Document 05-3520, revision 29. 6 June 2013.