Merge pull request #575 from openweave/feature/weave-tlv-schemas

Weave TLV Schema documentation and source

Author: Jay Logue

doc/specs/weave-tlv-schema.pdf

@@ -0,0 +1,130 @@
+/*
+ *
+ *    Copyright (c) 2020 Google LLC.
+ *    All rights reserved.
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+
+/**
+ *    @file
+ *      Schema definition for the Weave Device Description profile.
+ */
+
+namespace weave.profiles {
+
+/** Weave Device Description Profile
+ */
+device-description => PROFILE [id common:0x000E]
+{
+    // ---- Message Types ----
+
+    identify-request    => MESSAGE [id 1]
+    identify-response   => MESSAGE [id 2] CONTAINING device-descriptor
+
+
+    // ---- Data Types ----
+
+    /** Structure containing information describing a Weave device. 
+     */
+    device-descriptor [*:1] => STRUCTURE [extensible, tag-order] 
+    {
+        includes product-fields,
+        includes feature-fields,
+
+        
+        manufacturing-date [3,opt]        : encoded-date,       /**< Calendar date of manufacture in encoded form. */
+
+        serial-number [4]                 : STRING [len 1..32], /**< Device serial number. */
+
+        primary-15-4-mac-address [5,opt]  : BYTE STRING [len 8],/**< MAC address for device's primary 802.15.4 interface. */
+
+        primary-wifi-mac-address [6,opt]  : BYTE STRING [len 6],/**< MAC address for device's primary WiFi interface. */
+
+        wifi-essid [7,opt]                : STRING [len 1..32], /**< ESSID for device's WiFi rendezvous network.
+                                                                 *  @note: This field is mutually exclusive with the
+                                                                 *  wifi-essid-suffix field. */
+
+        pairing-code [8,opt]              : STRING [len 1..16], /**< The pairing code for the device.
+                                                                 *  @note @b IMPORTANT: For security reasons, the PairingCode
+                                                                 *  field should *never* be sent over the network. It is
+                                                                 *  present in a device-descriptor structure so that is can
+                                                                 *  encoded in a data label (e.g. QR-code) that is physically
+                                                                 *  associated with the device.
+                                                                 */
+        
+        software-version [9,opt]          : STRING [len 1..32], /**< Version of software on the device. */
+        
+        
+        device-id [10,opt]                : UNSIGNED INTEGER [range 64bits],
+                                                                /**< Weave device ID. */
+        
+        fabric-id [11,opt]                : UNSIGNED INTEGER [range 64bits], 
+                                                                /**< ID of Weave fabric to which the device belongs. */
+
+        
+        pairing-compat-major-ver [12,opt] : UNSIGNED INTEGER [range 1..0xFFFF],
+                                                                /**< Pairing software compatibility major version. */
+        
+        pairing-compat-minor-ver [13,opt] : UNSIGNED INTEGER [range 1..0xFFFF],
+                                                                /**< Pairing software compatibility minor version. */
+
+        wifi-essid-suffix [14,opt]        : STRING [len 1..32], /**< ESSID suffix for device's WiFi rendezvous network.
+                                                                 *  @note: This field is mutually exclusive with the
+                                                                 *  wifi-essid field.
+                                                                 */
+    }
+    
+    /** Common fields containing product information for a device.
+     */
+    product-fields => FIELD GROUP
+    {
+        vendor-id [0]                     : UNSIGNED INTEGER [range 1..0xFFFE],
+                                                                /**< Code identifying the product vendor. */
+
+        product-id [1]                    : UNSIGNED INTEGER [range 1..0xFFFE],
+                                                                /**< Code identifying the product. */
+
+        product-revision [2,opt]          : UNSIGNED INTEGER [range 1..0xFFFF],
+                                                                /**< Code identifying the product revision. */
+    }
+
+    /** Fields describing features supported by the device.
+     */
+    feature-fields => FIELD GROUP
+    {
+        
+        home-alarm-link-capable [100,opt] : BOOLEAN,            /**< Indicates a Nest Protect that supports connection to a home alarm panel. */
+
+        line-powered [101,opt]            : BOOLEAN             /**< Indicates a device that requires line power. */
+    }
+
+    /** A calendar date, encoded as an integer.
+     *
+     * Date values are encoded according to the following formula:
+     *
+     *    encoded-date = (year - 2000) +
+     *                   ((month - 1) * 100) +
+     *                   (day * 12 * 100)
+     *
+     * Date values are limited to the years 2001 through 2099.
+     *
+     * Month values must be between 1 and 12.
+     *
+     * If provided, day values must be between 1 and 31.  Alternatively, a day value
+     * of 0 can be used to encode a date without a day-of-month (e.g. 2020/05). 
+     */
+    encoded-date => UNSIGNED INTEGER [range 16bits]
+}
+
+} // namespace weave.profiles