diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..6fef247 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +# Store the Z-Wave specification source PDFs in Git LFS. +# Scoped to the sources folder so unrelated *.pdf handling is unaffected. +docs/specs/sources/*.pdf filter=lfs diff=lfs merge=lfs -text diff --git a/AGENTS.md b/AGENTS.md index bdfe5f5..9764f3a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -143,6 +143,11 @@ Response structs that contain variable-length collections use count + indexer me ## Protocol References +Local Markdown copies of the key specs live in [`docs/specs/`](docs/specs/README.md) — prefer these for quick lookups: +- `zwave-host-api-specification/` — Serial API frame format, handshake, initialization, commands +- `command-class-specification/` — Command Class message formats, field definitions, versions +- `zwave-500-series-programmers-guide/` — 500-series programmer's guide + The official Z-Wave specification package can be downloaded from the [Z-Wave Alliance](https://z-wavealliance.org/development-resources-overview/specification-for-developers/). The two most relevant specs are: - **Z-Wave Host API Specification** — Serial API frame format, handshake, initialization, command definitions (replaces the old INS12350 document) - **Z-Wave Application Specification** — Command Class message formats, versioning, required fields diff --git a/README.md b/README.md index efca5e0..d063dbc 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,10 @@ var binarySwitch = driver.Controller.Nodes[2].GetCommandClass +# 1 Abbreviations + +| | Abbreviation | | | Explanation | | +| --- | --- | --- | --- | --- | --- | +| AMR | | | Automatic Meter Reading | | | +| API | | | Application Programming Interface | | | +| ASCII | | | American Standard Code for Information Interchange. An ASCII code is the numerical representation of a character. | | | +| AV | | | Audio/Video | | | +| DHCP | | | Dynamic Host Configuration Protocol. | | | +| DNS | | | Dynamic Host Service | | | +| DST | | | Daylight Savings Time | | | +| HRV | | | Heat Recovery Ventilation | | | +| ID | | | Identifier | | | +| IP | | | Internet Protocol | | | +| IPV4 | | | Internet Protocol version 4 | | | +| IPV6 | | | Internet Protocol version 6 | | | +| LF | | | Linefeed character. | | | +| LSB | | | Less Significant Bit | | | +| MSB | | | Most Significant Bit | | | +| NIF | | | Node Information Frame | | | +| PIR | | | Pyroelectric Infrared | | | +| SUC | | | Static Update Controller | | | +| TZO | | | Time Zone Offset | | | +| Unicode | | | Unicode is a standard for encoding of characters. For more information, visit http://www.unicode.org/ | | | +| UTC | | | Universal Time (sometimes also called “Zulu Time”) was called Greenwich Mean Time (GMT) before 1972 | | | +| WMC | | | Windows Vista Media Center and Media Center 2005 remote controls | | | +| Z/IP | | | Z-Wave for IP | | | diff --git a/docs/specs/command-class-specification/02-introduction/02.01-precedence-of-definitions.md b/docs/specs/command-class-specification/02-introduction/02.01-precedence-of-definitions.md new file mode 100644 index 0000000..da0a3d5 --- /dev/null +++ b/docs/specs/command-class-specification/02-introduction/02.01-precedence-of-definitions.md @@ -0,0 +1,10 @@ + +# 2.1 Precedence of definitions + +Device Class, Device Type and Command Class Specifications approved as final version during the Device Class, Device Type and Command Class Open Review process have precedence over this document until integrated into this document. diff --git a/docs/specs/command-class-specification/02-introduction/02.02-terms-used-in-this-document.md b/docs/specs/command-class-specification/02-introduction/02.02-terms-used-in-this-document.md new file mode 100644 index 0000000..6c25e48 --- /dev/null +++ b/docs/specs/command-class-specification/02-introduction/02.02-terms-used-in-this-document.md @@ -0,0 +1,24 @@ + +# 2.2 Terms used in this document + +The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", ["MAY", and "OPTIONAL" in this document MUST be interpreted as described in IETF RFC 2119 [6].](../04-command-class-definitions/04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +[Statements containing the IETF RFC 2119 [6] key words are at times marked with unique requirement](../04-command-class-definitions/04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) numbers in the margin. The requirements numbers have the following syntax: CC:xxxx.xx.xx.xx.xxx with each x being an hexadecimal digit. + +This document defines functionality as deprecated or obsoleted. + +The term "obsolete" means that the functionality MUST NOT be supported in new implementations applying for certification. + +A controller SHOULD provide controlling capabilities of the actual functionality for backwards compatibility with legacy devices. + +The term "deprecated" also indicates an obsolete definition, but it permits new implementations applying for certification. + +Thus, the term “deprecated” means that the functionality SHOULD NOT be supported in new implementations applying for certification. Often, another substitute functionality is REQUIRED if the deprecated functionality is implemented. + +A controller SHOULD provide controlling capabilities of the actual functionality for backwards compatibility with legacy devices. diff --git a/docs/specs/command-class-specification/02-introduction/index.md b/docs/specs/command-class-specification/02-introduction/index.md new file mode 100644 index 0000000..b1eabfe --- /dev/null +++ b/docs/specs/command-class-specification/02-introduction/index.md @@ -0,0 +1,21 @@ + +# 2 Introduction + +Commands classes are divided in four categories: + + Application Command Classes  [Management Command Classes [15]](../04-command-class-definitions/04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command)  [Transport-Encapsulation Command Classes [14]](../04-command-class-definitions/04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command)  [Network-Protocol Command Classes [16]](../04-command-class-definitions/04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +[The list of defined Command Classes with their associated category is available in [13].](../04-command-class-definitions/04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +This document describes the Command Classes designed for Application specific purposes. + +## Contents + +- [2.1 Precedence of definitions](02.01-precedence-of-definitions.md) +- [2.2 Terms used in this document](02.02-terms-used-in-this-document.md) diff --git a/docs/specs/command-class-specification/03-command-class-overview/03.01-overview.md b/docs/specs/command-class-specification/03-command-class-overview/03.01-overview.md new file mode 100644 index 0000000..848aede --- /dev/null +++ b/docs/specs/command-class-specification/03-command-class-overview/03.01-overview.md @@ -0,0 +1,10 @@ + +# 3.1 Overview + +[The Device Class specification [1] and Z-Wave Plus Device Type [10] specification indicate combinations](../04-command-class-definitions/04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) of command classes which MUST be supported for a particular product class or type. diff --git a/docs/specs/command-class-specification/03-command-class-overview/03.02-command-class-format.md b/docs/specs/command-class-specification/03-command-class-overview/03.02-command-class-format.md new file mode 100644 index 0000000..20b53e3 --- /dev/null +++ b/docs/specs/command-class-specification/03-command-class-overview/03.02-command-class-format.md @@ -0,0 +1,77 @@ + +# 3.2 Command class format + +## 3.2.1 Frame format + +All commands classes have a common header consisting of a Command Class identifier and a Command identifier. Each command can have from zero to N bytes of command data. The bit numbering starts at zero for the least significant bit. LSB is denoted as ‘Bit 0’ and MSB is denoted as ‘Bit 7 throughout the document. + +LSB and MSB notations are also used for multi bytes fields, indicating which byte is the most significant. + +[Figure 1 and Figure 2 below show the generic command frame for the two possible formats:](03.02-command-class-format.md#321-frame-format) + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class (0x20..0xEE) | | | | | | | | | | | | | | | | | | | | | | | | +| Command | | | | | | | | | | | | | | | | | | | | | | | | +| Command Data 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Command Data N | | | | | | | | | | | | | | | | | | | | | | | | + +Figure 1, Generic command format + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class MSB (0xF1..0xFF) | | | | | | | | | | | | | | | | | | | | | | | | +| Command Class LSB (0x00..0xFF) | | | | | | | | | | | | | | | | | | | | | | | | +| Command | | | | | | | | | | | | | | | | | | | | | | | | +| Command Data 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Command Data N | | | | | | | | | | | | | | | | | | | | | | | | + +Figure 2, Generic extended command format + +### 3.2.1.1 Command class + +[The Command Class identifier range is shown in Table 1.](03.02-command-class-format.md#3211-command-class) + +Table 1, Command Class identifier range + +| | Command Class | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | No Operation. Used by Z-Wave Protocol. MAY be used by the application. | | | +| 0x01..0x1F | | | Reserved for the Z-Wave protocol | | | +| 0x20..0xEE | | | Application Command Classes | | | +| 0xEF | | | Support/Control Mark | | | +| 0xF0 | | | Non interoperable | | | +| 0xF100 | | | Security Mark | | | +| 0xF101..0xFFFF | | | Extended Application Command Classes (2 byte-long Command Class identifier) | | | + +A Command Class can contain up to 255 different Commands. If the Command Class field is in the range 0xF1..0xFF, the Command Class identifier is therefore 2 bytes long. This allows for future extensions of the Command Classes and provides the possibility of having more than 4000 Command Classes. + +### 3.2.1.2 Command + +The command field contains the specific command indicating a node how to parse and interpret the command data. The command field length is always 1 byte. + +### 3.2.1.3 Command data (N bytes) + +The command data field contains data related to the command. The description for the command data is defined in each individual command. + +Simple commands, such as Get commands, usually contain no command data. Other commands, such as Set or Report commands can contain several bytes of command data. + +## 3.2.2 Command class versioning + +All command classes have a version number. The following rules apply to avoid interoperability issues when introducing the same Command Class with different versions: + + A node MUST NOT discard a frame based on the length field. A receiving node MUST use the Command Class identifier and the Command identifier to interpret the application frame. This enables a device, which supports version 1 of a Command Class to interpret the version 1 part of a received version 2 of the command. + + All implementations of a Command Class version higher than 1 MUST initialize all parameters associated with the version higher than 1. Thereby a node implementing the version 2 of a Command Class can interpret a version 1 received Command. + + A device supporting a Command Class having a version higher than 1 MUST support the [Version Command Class [15] to be able to identify the supported version. If a node does not](../04-command-class-definitions/04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) support the Version Command Class at its highest security level, it can be assumed that all Command Classes version are equal to 1. + + It is allowed to certify nodes supporting an older version of a Command Class despite a newer version exists as long as the generic/specific device specification does not require a specific version implemented. diff --git a/docs/specs/command-class-specification/03-command-class-overview/03.03-controlled-and-supported-command-classes.md b/docs/specs/command-class-specification/03-command-class-overview/03.03-controlled-and-supported-command-classes.md new file mode 100644 index 0000000..d1f1924 --- /dev/null +++ b/docs/specs/command-class-specification/03-command-class-overview/03.03-controlled-and-supported-command-classes.md @@ -0,0 +1,16 @@ + +# 3.3 Controlled and Supported Command Classes + +A node can support and/or control a given Command Class. + +If a Command Class is supported: The node implements all the Command Class functionalities and can be set and read back by other nodes. When a Command Class is supported, it is REQUIRED to implement the whole Command Class. + +If a Command Class is controlled: The node implements the ability to interview, read and/or set other nodes supporting the Command Class. Nodes controlling Command Classes MAY use only a subset of the Commands within a Command Class (for example only Set commands). Even if using a Command Class partially for control, the use MUST comply with the Command Class requirements. + +For example, a Set Command sent to Association Group destinations is a form of Command Class control. diff --git a/docs/specs/command-class-specification/03-command-class-overview/03.04-node-information-frame.md b/docs/specs/command-class-specification/03-command-class-overview/03.04-node-information-frame.md new file mode 100644 index 0000000..24b40a4 --- /dev/null +++ b/docs/specs/command-class-specification/03-command-class-overview/03.04-node-information-frame.md @@ -0,0 +1,134 @@ + +# 3.4 Node Information Frame + +The Node Information Frame (NIF) is used to inform other devices about the node capabilities. The NIF contains a structure with a protocol specific part that is handled by the Z-Wave protocol and an application specific part that is filled in by the application. The protocol specific part consists of a bit telling if the node is a continuously listening device, the Basic Device Class the node is based on etc. The application specific part consists of the Generic and Specific Device Class and the Command Classes that are supported and/or controlled by the node. + +[Generic and Specific Device Class are defined in [1] for legacy Z-Wave nodes or in [10] for Z-Wave Plus](../04-command-class-definitions/04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) nodes. + +A NIF will be sent to the controller when a node is to be included in the network, excluded from the network or upon request. [Table 2 shows the NIF structure.](03.04-node-information-frame.md#34-node-information-frame) + +Table 2, Node Information Frame Format + +| | Byte descriptor \ bit number | | | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Capability | | | Liste- ning | | | Z-Wave Protocol Specific Part | | | | | | | | | | | | | | | | | | | | | +| Security | | | Opt. Func. | | | Z-Wave Protocol Specific Part | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | Z-Wave Protocol Specific Part | | | | | | | | | | | | | | | | | | | | | | | | +| Basic *) | | | Basic Device Class (Z-Wave Protocol Specific Part) | | | | | | | | | | | | | | | | | | | | | | | | +| Generic | | | Generic Device Class | | | | | | | | | | | | | | | | | | | | | | | | +| Specific | | | Specific Device Class | | | | | | | | | | | | | | | | | | | | | | | | +| NodeInfo[0] | | | Command Class 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | … | | | | | | | | | | | | | | | | | | | | | | | | +| NodeInfo[n-1] | | | Command Class N | | | | | | | | | | | | | | | | | | | | | | | | + +*) The “Basic” field is only included when the NIF is sent by a controller + +The Z-Wave Protocol in a controller saves all the Node Information except the supported and controlled Command Classes when a node is included in the network. The reserved field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +## 3.4.1 Z-Wave Protocol Specific Part + +The protocol specific part of the NIF is handled by the Z-Wave protocol. This information is automatically inserted in the packet by the protocol layer when transferring data using the API. + +Basic Device Class + +The Basic Device Class field contains an identifier that identifies what Basic Device Class this node is based on and is set by the Z-Wave protocol. A detailed description of all available Basic Device Classes [is given in [1] for Z-Wave devices and [10] for Z-Wave Plus devices. The Z-Wave Plus devices have an](../04-command-class-definitions/04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) additional parameter Role Type defining device role in the network. The Role Type parameter is [announced via the Z-Wave Plus Info Command Class [15].](../04-command-class-definitions/04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +This field is only included when the NIF frame is sent by a controller. A slave MUST omit this field. Refer [to [9] for controller and slave definition.](../04-command-class-definitions/04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +## 3.4.2 Application Specific Part + +The application specific part of the NIF is handled by the application. The information must be in accordance with the defined classes to obtain interoperability. + +Listening Flag + +The Listening flag is used to indicate that the node is always listening if set to 1. An always listening node must be powered continuously and reside on a fixed position in the installation. An always listening node is included in the routing table to assist as repeater in the network. The routing table is static during normal operation. In case the Listening flag is set to 0, the node is non-listening. This is typically used for battery operated nodes being asleep when the protocol is idle to prolong battery lifetime. A battery operated node is not included in the routing table and is not used as a router in the network. In some instances the node’s position in the network is still determined, and stored by the protocol. + +Optional Functionality Flag + +The Optional Functionality flag is used to indicate that this node supports other command classes than the mandatory for the selected generic/specific device class and that a controlling node needs to look at the supported command classes to fully control this device. + +Generic Device Class + +The Generic Device Class field contains an identifier that identifies what Generic Device Class this node is part of and must be set by the application. For a detailed description of all available Generic Device [Classes, refer to [1] for Z-Wave devices and [10] for Z-Wave Plus devices.](../04-command-class-definitions/04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +Specific Device Class + +The Specific Device Class field specifies what Specific Device Class this application is part of and must [be set by the application. For a detailed description of all available Specific Device Classes, refer to [1] for Z-Wave devices and [10] for Z-Wave Plus devices.](../04-command-class-definitions/04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +Command Class + +The Command Class field is used to advertise Command Classes implemented by the node. The field MUST NOT be longer than 35 bytes. + +The field MUST advertise the list of Command Classes that the node supports. + +The field MAY advertise the list of Command Classes that the node can control in other nodes. If present, the list of controlling Command Classes MUST be prepended by the COMMAND_CLASS_MARK Command Class identifier. It is NOT RECOMMENDED to advertise controlled Command Classes. + +It has been found that legacy controllers MAY read as little as 6 lines from this list. For backwards [compatibility, the list SHOULD advertise supported command classes in the order indicated in Table 3 :](03.04-node-information-frame.md#342-application-specific-part) + +Table 3, NIF :: Command Class advertising priorities + +| | Priority | | | Command Class | | +| --- | --- | --- | --- | --- | --- | +| 1 (First line) | | | COMMAND CLASS ZWAVEPLUS INFO _ _ _ Applies only to Z-Wave Plus products | | | +| 2 (if supported) | | | COMMAND CLASS SWITCH MULTILEVEL or _ _ _ COMMAND CLASS SWITCH BINARY _ _ _ | | | +| 3 (if supported) | | | COMMAND CLASS SWITCH ALL _ _ _ | | | +| 4 (if supported) | | | COMMAND CLASS ASSOCIATION _ _ | | | +| 5 | | | All other command classes | | | + +[Table 4 shows the Command Class list structure of the Node Information frame:](03.04-node-information-frame.md#342-application-specific-part) Table 4, NIF::Command Class list structure + +| Description | | | | Command Class list field content | | | | | | | | | | | | | | | | | | | | | | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| | | | | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| Non-secure Supported Command Classes | | | Command Class 1 *) | | | | | | | | | | | | | | | | | | | | | | | | +| | | | … | | | | | | | | | | | | | | | | | | | | | | | | +| | | | Command Class M *) | | | | | | | | | | | | | | | | | | | | | | | | +| | Support/Control Mark | | | 0xEF | | | | | | | | | | | | | | | | | | | | | | | +| Non-secure Controlled Command Classes | | | Command Class 1 *) | | | | | | | | | | | | | | | | | | | | | | | | +| | | | … | | | | | | | | | | | | | | | | | | | | | | | | +| | | | Command Class K *) | | | | | | | | | | | | | | | | | | | | | | | | + + *) Command classes may be extended spanning two bytes for one command class + +The Command Class list MAY start or finish with the identifier COMMAND_CLASS_MARK. + +## 3.4.3 NIF and Multi Channel/Security Command Classes + +The NIF MUST represent command classes supported without Multi Channel or Security encapsulation [[14].](../04-command-class-definitions/04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +After inclusion in a Z-Wave network, the NIF represents the node’s Command Class capabilities when using no Security and no Multi Channel encapsulation. + +Multi Channel Root Devices advertise their capabilities via the NIF, but they advertise the Command Class capabilities of their End Points via the Multi Channel Command Class. + +Security bootstrapped nodes advertise their capabilities using security encapsulation via the Security 0 or Security 2 Command Class. + +The Command Class list advertised in the NIF may vary depending on the inclusion state and S0/S2 bootstrapping state of the node. + +A node supporting security (S0 and/or S2) MUST advertise command classes in the NIF according to [Table 5.](03.04-node-information-frame.md#343-nif-and-multi-channelsecurity-command-classes) Table 5, NIF content depending on inclusion and security bootstrapping + +| | Network inclusion | | | Security bootstrapping | | | Command Classes advertised in the NIF | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Not included in a network | | | N/A | | | At least all Command Classes that MUST always be non-securely supported. All supported Command Classes MAY be advertised | | | +| Included in a network | | | No security supported by the included node | | | All supported Command Classes | | | +| Included in a network | | | Before the node times out waiting for Security bootstrapping | | | At least all Command Classes that MUST always be non-securely supported. All supported Command Classes MAY be advertised | | | +| Included in a network | | | Timed out waiting for Security Bootstrapping (i.e. the process never started) | | | The same Command Class list as when security bootstrapping is successful but no key was granted1 | | | +| Included in a network | | | Security bootstrapping failed. (i.e. the process started but did not complete without error) | | | All Command Classes that MUST always be non-securely supported Command Classes that are supported when no key is granted MAY be added or removed from the list.1 | | | +| Included in a network | | | Bootstrapped with S0/S2 | | | All Command Classes that MUST always be non-securely supported only. (i.e. Command Classes supported even if not using S0/S2 encapsulation). | | | + +[Refer to each individual Device Type [10] for the list of Command Classes supported when no security key is granted](../04-command-class-definitions/04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) 1 + +Command Classes advertised as supported in the NIF after S0/S2 bootstrapping MUST also be supported at higher security levels unless encapsulated outside security. + +## 3.4.4 Command Class specific NIF rules + +A given Command Class MAY have additional requirement with respects to the NIF, Multi Channel Capability Report or S0/S2 Commands Supported Report. + +For example, the Basic Command Class is never advertised in the NIF or the Z-Wave Plus Info is always in the NIF if supported. + +In this case, requirements are listed in each individual Command Class definition, in the compatibility considerations section. diff --git a/docs/specs/command-class-specification/03-command-class-overview/03.05-multicast-and-broadcast-commands.md b/docs/specs/command-class-specification/03-command-class-overview/03.05-multicast-and-broadcast-commands.md new file mode 100644 index 0000000..764cd43 --- /dev/null +++ b/docs/specs/command-class-specification/03-command-class-overview/03.05-multicast-and-broadcast-commands.md @@ -0,0 +1,14 @@ + +# 3.5 Multicast and broadcast commands + +A node MAY send a command to several destinations using a Multicast or Broadcast frame. This is allowed only if the actual command does not require the responding node to return a response. + +Unless specified otherwise for a particular command:  Commands requiring another command to be returned in response by a receiving node MUST NOT be issued via multicast addressing in a Z-Wave network  A receiving node MUST NOT return a response if a command is received via multicast addressing. + +The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. diff --git a/docs/specs/command-class-specification/03-command-class-overview/03.06-actuator-control.md b/docs/specs/command-class-specification/03-command-class-overview/03.06-actuator-control.md new file mode 100644 index 0000000..b26e396 --- /dev/null +++ b/docs/specs/command-class-specification/03-command-class-overview/03.06-actuator-control.md @@ -0,0 +1,47 @@ + +# 3.6 Actuator Control + +An actuator device may support one or more actuator command classes. This section presents terminology and conventions applying to all actuator command classes. + +The actuator control group comprises the following command classes: + + Barrier Operator Command Class  Basic Command Class  Binary Switch Command Class  Color Switch Command Class  Door Lock Command Class  Multilevel Switch Command Class  Sound Switch Command Class  Window Covering Command Class + +## 3.6.1 Terminology + +Actuators may be controlled in two possible manners. + +A position actuator responds to a position control command, which specifies a target value and optionally a duration for the transition from the current value to the target value. The value may be binary or multilevel. State control commands may be encoded as special multilevel position control values, e.g. 0xFF for “On” and 0x00 for “Off”. The most recent (non-zero) target value is restored in response to the “On” state control command. + +A motion actuator responds to start/stop commands. A motion control command specifies a direction, optionally a start value, and a transition rate. + +## 3.6.2 Reporting values + +A position control command may be used to initiate a transition to a new target value. A position report advertises the current value of the device hardware, optionally the target value and the remaining transition duration. If the transition is initiated by a motion control command, the reported target value is the min or max value and the duration is the time needed to reach the target value at the actual transition rate. A controlling device should not assume that the position value advertised in a Report is identical to a value previously issued with a position control command when a transition has ended. + +A controlling node MAY want to receive application-level acknowledgements after issuing actuating commands. It is the responsibility and choice of the controlling node whether or not to ensure that a actuating command has been successfully executed. If doing so, it is RECOMMENDED to use the [Supervision Command Class [14] or MAY read back the node’s state at a later time with a Get](../04-command-class-definitions/04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) Command. A supporting node receiving an actuating Command SHOULD NOT return a Report Command advertising its status or level unless specified in the Command Class specification. + +## 3.6.3 Command values vs. hardware values + +A device may implement fewer hardware levels than supported by a position control Command Class. The hardware levels should be distributed uniformly over the entire range. The mapping of command values to hardware levels must be monotonous, i.e. a higher value MUST be mapped to either the same [or a higher hardware level. An example is found in Table 6.](03.06-actuator-control.md#363-command-values-vs-hardware-values) + +[Table 6, Mapping command values to hardware levels (example)](03.06-actuator-control.md#363-command-values-vs-hardware-values) + +| | Multilevel Value | | | Hardware level | | | State | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0 | | | 0 | | | Off | | | +| 1..33 | | | 33% | | | On | | | +| 34..66 | | | 66% | | | On | | | +| 67..99 | | | 100% | | | On | | | + +## 3.6.4 Supporting multiple actuator Command Classes + +Several actuator Command Classes MAY co-exist in a node or Multi Channel End Point. For example, a node MAY support both Window Covering Command Class and Multilevel Switch Command Class. + +In this case, the two actuator Command Classes SHOULD actuate the same resource. If a node implements several actuating resources, e.g. a LED and a power switch, it is RECOMMENDED to use Multi Channel End Points for each individual resource. diff --git a/docs/specs/command-class-specification/03-command-class-overview/03.07-common-fields-and-encoding.md b/docs/specs/command-class-specification/03-command-class-overview/03.07-common-fields-and-encoding.md new file mode 100644 index 0000000..f5f8a25 --- /dev/null +++ b/docs/specs/command-class-specification/03-command-class-overview/03.07-common-fields-and-encoding.md @@ -0,0 +1,136 @@ + +# 3.7 Common fields and encoding + +## 3.7.1 Reserved and Res fields + +Fields named ‘Reserved’ or ‘Res’ MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +## 3.7.2 Reserved values and reserved bits + +Values of fields in commands that are marked as “reserved” or “res” MUST NOT be used by devices sending commands and MUST be ignored by devices receiving commands. + +Bits in commands that are marked as “reserved” or “res” MUST be set to 0 by devices sending commands and MUST be ignored by devices receiving commands. + +Undefined values for a given parameter MUST be treated as “reserved”. Reserved values MUST NOT be used by a sending node and MUST be ignored by a receiving node. + +## 3.7.3 Duration encoding + +Some actuator command classes allow controlling nodes to specify a duration for reaching the target [value. The duration encoding is shown in Table 7.](03.07-common-fields-and-encoding.md#373-duration-encoding) + +Table 7, Actuator Command Class Duration Set encoding + +| | Value | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Instantly | | | +| 0x01..0x7F | | | 1 second (0x01) to 127 seconds (0x7F) in 1 second resolution. | | | +| 0x80..0xFE | | | 1 minute (0x80) to 127 minutes (0xFE) in 1 minute resolution. | | | +| 0xFF | | | Factory default duration. | | | + +A node supporting an actuator Command Class may advertise the duration left to reach the target value [advertised in a report. The duration encoding is shown in Table 8.](03.07-common-fields-and-encoding.md#373-duration-encoding) + +Table 8, Actuator Command Class Duration Report encoding + +| | Value | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | 0 seconds. Already at the Target Value. | | | +| 0x01..0x7F | | | 1 second (0x01) to 127 seconds (0x7F) in 1 second resolution. | | | +| 0x80..0xFD | | | 1 minute (0x80) to 126 minutes (0xFD) in 1 minute resolution. | | | +| 0xFE | | | Unknown duration | | | +| 0xFF | | | Reserved | | | + +## 3.7.4 Unsigned encoding + +Unless specified otherwise in a field description, the field encoding is using unsigned representation. [Examples for different field sizes are given in Table 9](03.07-common-fields-and-encoding.md#374-unsigned-encoding) + +[Table 9, Default unsigned encoding examples](03.07-common-fields-and-encoding.md#374-unsigned-encoding) + +| Value (hex) | Unsigned 8 bit representation (decimal) | | +| --- | --- | --- | +| 0x00 | 0 | | +| 0x01 | 1 | | +| 0x02 | 2 | | +| 0x7F | 127 | | +| 0x80 | 128 | | +| 0xFE | 254 | | +| 0xFF | 255 | | + +| Value (hex) | | Unsigned 16 bit | | +| --- | --- | --- | --- | +| | | representation | | +| | | (decimal) | | +| 0x0000 | 0 | | | +| 0x0001 | 1 | | | +| 0x0002 | 2 | | | +| 0x7FFF | 32767 | | | +| 0x8000 | 32768 | | | +| 0xFFFE | 65534 | | | +| 0xFFFF | 65535 | | | + +| Value (hex) | | Unsigned 32 bit | | +| --- | --- | --- | --- | +| | | representation | | +| | | (decimal) | | +| 0x00000000 | 0 | | | +| 0x00000001 | 1 | | | +| 0x00000002 | 2 | | | +| 0x7FFFFFFF | 2147483647 | | | +| 0x80000000 | 2147483648 | | | +| 0xFFFFFFFE | 4294967294 | | | +| 0xFFFFFFFF | 4294967295 | | | + +## 3.7.5 Signed encoding + +Some fields use the signed encoding representation.Signed encoding is using the two’s complement [representation. Fields using signed encoding MUST comply with Table 10.](03.07-common-fields-and-encoding.md#375-signed-encoding) + +Table 10, Signed field encoding (two’s complement representation) + +| Value (hex) | Signed 8 bit representation (decimal) | | +| --- | --- | --- | +| 0x7F | 127 | | +| 0x02 | 2 | | +| 0x01 | 1 | | +| 0x00 | 0 | | +| 0xFF | -1 | | +| 0xFE | -2 | | +| 0x80 | -128 | | + +| Value (hex) | | Signed 16 bit | | +| --- | --- | --- | --- | +| | | representation | | +| | | (decimal) | | +| 0x7FFF | 32767 | | | +| 0x0002 | 2 | | | +| 0x0001 | 1 | | | +| 0x0000 | 0 | | | +| 0xFFFF | -1 | | | +| 0xFFFE | -2 | | | +| 0x8000 | -32768 | | | + +| Value (hex) | | Signed 32 bit | | +| --- | --- | --- | --- | +| | | representation | | +| | | (decimal) | | +| 0x7FFFFFFF | 2147483647 | | | +| 0x00000002 | 2 | | | +| 0x00000001 | 1 | | | +| 0x00000000 | 0 | | | +| 0xFFFFFFFF | -1 | | | +| 0xFFFFFFFE | -2 | | | +| 0x80000000 | -2147483648 | | | + +## 3.7.6 Fields values and version + +New Command Class versions may define new possible values for a field introduced previously. In that case, a version column is added to the value table. A supporting node MUST support the values associated its version and previous versions and MUST NOT support values associated to future [versions. An example is given in Table 11.](03.07-common-fields-and-encoding.md#376-fields-values-and-version) Table 11, Field values and Command Class version (example) + +| | Value | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | Value introduced in version 1, valid and mandatory in all versions | | | 1 | | | +| 0x01 | | | Value introduced in version 2, valid and mandatory in version 2 and newer Version 1 MUST consider this value as reserved | | | 2 | | | +| 0x02 | | | Value introduced in version 2, valid and mandatory in version 2 and newer Version 1 MUST consider this value as reserved | | | 2 | | | +| 0xFF | | | Value introduced in version 3, valid and mandatory in version 3 and newer Version 1 and 2 MUST consider this value as reserved | | | 3 | | | diff --git a/docs/specs/command-class-specification/03-command-class-overview/index.md b/docs/specs/command-class-specification/03-command-class-overview/index.md new file mode 100644 index 0000000..ce2d82a --- /dev/null +++ b/docs/specs/command-class-specification/03-command-class-overview/index.md @@ -0,0 +1,20 @@ + +# 3 Command Class Overview + +The following sections present a general Command Class overview and their associated rules. The requirements and recommendations apply to all Command Classes. + +## Contents + +- [3.1 Overview](03.01-overview.md) +- [3.2 Command class format](03.02-command-class-format.md) +- [3.3 Controlled and Supported Command Classes](03.03-controlled-and-supported-command-classes.md) +- [3.4 Node Information Frame](03.04-node-information-frame.md) +- [3.5 Multicast and broadcast commands](03.05-multicast-and-broadcast-commands.md) +- [3.6 Actuator Control](03.06-actuator-control.md) +- [3.7 Common fields and encoding](03.07-common-fields-and-encoding.md) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.01-alarm-command-class-version-1-deprecated.md b/docs/specs/command-class-specification/04-command-class-definitions/04.01-alarm-command-class-version-1-deprecated.md new file mode 100644 index 0000000..20f6b99 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.01-alarm-command-class-version-1-deprecated.md @@ -0,0 +1,55 @@ + +# 4.1 Alarm Command Class, version 1 [DEPRECATED] + +THIS COMMAND CLASS VERSION HAS BEEN DEPRECATED + +A device MAY implement this Command Class version, but it is RECOMMENDED that new implementations comply with Notification Command Class, version 8 + +The Alarm Command Class allows applications to report alarm or service conditions. Since these parameters are not standardized across devices the alarms/service parameters MUST be described in the user manual (or an installer manual). + +## 4.1.1 Interoperability considerations + +The Alarm Command Class has been superseded by the Notification Command Class. Refer to most recent version of Notification Command Class. + +## 4.1.2 Alarm Get Command + +This command is used to get the value of an alarm. + +The Alarm Report Command MUST be returned in response to this command if the alarm type is supported. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ALARM _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ALARM GET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Alarm Type | | | | | | | | | | | | | | | | | | | | | | | | + +Alarm Type (8 bits) + +The Alarm Type field specifies which alarm is being requested. The alarm types are specific for each application. + +## 4.1.3 Alarm Report Command + +This command is used to report the type and level of an alarm. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ALARM _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ALARM REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Alarm Type | | | | | | | | | | | | | | | | | | | | | | | | +| Alarm Level | | | | | | | | | | | | | | | | | | | | | | | | + +Alarm Type (8 bits) + +Refer to explanation under the Alarm Get Command. + +Alarm Level (8 bits) + +The alarm level is application specific. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.01-all-switch-command-class-version-1-obsoleted.md b/docs/specs/command-class-specification/04-command-class-definitions/04.01-all-switch-command-class-version-1-obsoleted.md new file mode 100644 index 0000000..d961f27 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.01-all-switch-command-class-version-1-obsoleted.md @@ -0,0 +1,81 @@ + +# 4.1 All Switch Command Class, version 1 [OBSOLETED] + +THIS COMMAND CLASS HAS BEEN OBSOLETED + +New implementations MUST NOT support this Command Class. Controlling nodes MUST use S2 Multicast mechanism in order to achieve the All On and All Off functionality + +The All Switch Command Class is used to switch all devices on or off. Devices may be excluded/included from the all on/all off functionality. The application determines which devices there are included in the all on/all off functionality as default. + +## 4.1.1 All Switch Set Command + +This command is used to instruct a device if it is included or excluded from the all on/all off functionality. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH ALL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH ALL SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Mode | | | | | | | | | | | | | | | | | | | | | | | | + +Mode (8 bits) + +The mode field used to set the all on/all off functionality of the device. + +| | Mode | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Indicate that the switch is excluded from the all on/all off functionality. | | | +| 0x01 | | | Indicate that the switch is excluded from the all on functionality but not all off. | | | +| 0x02 | | | Indicate that the switch is excluded from the all off functionality but not all on. | | | +| 0x03..0xFE | | | Reserved | | | +| 0xFF | | | Indicates that the switch is included in the all on/all off functionality. | | | + +## 4.1.2 All Switch Get Command + +This command is used to ask a device if it is included or excluded from the all on/all off functionality. + +The All Switch Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH ALL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH ALL GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.1.3 All Switch Report Command + +This command is used to report if the device is included or excluded from the all on/all off functionality. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH ALL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH ALL REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Mode | | | | | | | | | | | | | | | | | | | | | | | | + +Mode (8 bits) + +Refer to the All Switch Set Command. + +## 4.1.4 All Switch On Command + +This command is used to inform a switch that it SHOULD be turned on. A receiving device MUST NOT react to this command if the actual operation has been prohibited via the Switch All Set command. Like the Basic Set On command, this command MUST cause the device to restore the most recent (non-zero) level. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH ALL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH ALL ON _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.1.5 All Switch Off Command + +This command is used to inform a switch that it SHOULD be turned off. A receiving device MUST NOT react to this command if the actual operation has been prohibited via the Switch All Set command. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH ALL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH ALL OFF _ _ | | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.02-alarm-command-class-version-2-deprecated.md b/docs/specs/command-class-specification/04-command-class-definitions/04.02-alarm-command-class-version-2-deprecated.md new file mode 100644 index 0000000..81f3cee --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.02-alarm-command-class-version-2-deprecated.md @@ -0,0 +1,169 @@ + +# 4.2 Alarm Command Class, version 2 [DEPRECATED] + +THIS COMMAND CLASS VERSION HAS BEEN DEPRECATED + +A device MAY implement this Command Class version, but it is RECOMMENDED that new implementations comply with Notification Command Class, version 8 + +The Alarm Command Class is intended for Z-Wave enabled devices capable of reporting alarm reports. + +Version 2 of the Alarm Command Class is improved with the following functionalities: + + Alarm Types defined by the Z-Wave Alliance  Interview process of supported Alarm Types + +The commands not described in this version remain unchanged from Alarm Command Class, version 1. + +## 4.2.1 Interoperability considerations + +[The interoperability considerations from version 1 also apply for this version. Refer to 4.1.1.](04.01-alarm-command-class-version-1-deprecated.md#411-interoperability-considerations) + +## 4.2.2 Alarm Set Command + +This command is used to set the activity of the Z-Wave Alarm Type and Status. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ALARM _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ALARM SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Z-Wave Alarm Type | | | | | | | | | | | | | | | | | | | | | | | | +| Z-Wave Alarm Status | | | | | | | | | | | | | | | | | | | | | | | | + +Z-Wave Alarm Type (8 bits) + +[Refer to 4.1.3 Alarm Report Command](04.01-alarm-command-class-version-1-deprecated.md#413-alarm-report-command) Z-Wave Alarm Status (8 bits) + +This field is used to set the state of the Alarm Type. The value 0x00 will deactivate the alarm and 0xFF will activate the alarm i.e. unsolicited Alarm Report Command will be transmitted to the node(s) defined in the Node field(s) when triggered by an event. Any other value is reserved for future use. + +Note: The factory default state MUST be described in the product manual. All Z-Wave enabled devices MUST be able to operate based on factory default settings i.e. an end-user MUST NOT be forced to set- up the states of the device in order to operate. The factory default state of the Z-Wave Alarm Status CC:0071.02.06.12.001 SHOULD be enabled. + +Products that do not allow deactivation of a specific Alarm Type, MUST respond to a Alarm Configuration Set deactivating the Alarm Type in question by returning an Application Rejected Request Command of the Application Status Command Class. + +## 4.2.3 Alarm Get Command + +The Alarm Get Command is used to request the alarm state for a specific alarm type announced as supported through the Alarm Type Supported Report Command. + +The Alarm Report Command MUST be returned in response to this command if the alarm type is supported. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ALARM _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ALARM GET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Alarm Type | | | | | | | | | | | | | | | | | | | | | | | | +| Z-Wave Alarm Type | | | | | | | | | | | | | | | | | | | | | | | | + +Alarm Type (8 bits) + +This field refers to the Alarm Type of Alarm Command Class (Version 1) i.e. the application specific Alarm Type which is not defined by the Z-Wave Alliance. If the ‘V1 Alarm’ field is set to ‘0’ as reported via the Alarm Type Supported Report Command, this field MUST be set to ‘0’ when requesting the report. + +Z-Wave Alarm Type (8 bits) + +The Z-Wave Alarm Type field MUST contain the Alarm Type identifier described in Alarm Report Command. This parameter refers to the Alarm Types defined by the Z-Wave Alliance. + +A node receiving a non-supported Z-Wave Alarm Type MUST ignore the command. A controlling node SHOULD interview the device for supported Alarm Types by means of Alarm Type Supported Get Command prior to Alarm Get. + +## 4.2.4 Alarm Report Command + +This command is used by the application to report the alarm state. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ALARM _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ALARM REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Alarm Type | | | | | | | | | | | | | | | | | | | | | | | | +| Alarm Level | | | | | | | | | | | | | | | | | | | | | | | | +| Zensor Net Source Node ID | | | | | | | | | | | | | | | | | | | | | | | | +| Z-Wave Alarm Status | | | | | | | | | | | | | | | | | | | | | | | | +| Z-Wave Alarm Type | | | | | | | | | | | | | | | | | | | | | | | | +| Z-Wave Alarm Event | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Event Parameters | | | | | | | | | | | | | | | | | | | | | | | | +| Event Parameter 1 | | | | | | | | | | | | | | | | | | | | | | | | +| ... | | | | | | | | | | | | | | | | | | | | | | | | +| Event Parameter N | | | | | | | | | | | | | | | | | | | | | | | | + +Alarm Type (8 bits) + +[Refer to 4.1.3 Alarm Report Command](04.01-alarm-command-class-version-1-deprecated.md#413-alarm-report-command) + +Alarm Level (8 bits) + +[Refer to 4.1.3 Alarm Report Command](04.01-alarm-command-class-version-1-deprecated.md#413-alarm-report-command) + +Zensor Net Source Node ID (8 bits) + +Specify the Zensor Net Source Node ID, which detected the alarm condition. In Zensor Net it is not possible to determine the Source Node ID due to the broadcast forwarded frame is without this information on protocol level. If the device is not based on Zensor Net this field MUST be set to ‘0’. + +Z-Wave Alarm Status (8 bits) + +[Refer to 4.2.2 Alarm Set Command](04.02-alarm-command-class-version-2-deprecated.md#422-alarm-set-command) + +Number of Event Parameters (8 bits) + +Indicates the Number of Event Parameters fields used in bytes. Z-Wave Alarm Type (8 bits), Z-Wave Alarm Event (8 bits) and Event Parameters (N Byte) + +[[18] specifies the Alarm Types and its subordinate parameters defined by the Z-Wave Alliance. The fields](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) that do not contain any definition of the Z-Wave Alarm Type MUST be set to ‘0’ in the Alarm Report Command. + +The device MUST advertise support of the Command Class which is included for the specific Alarm Type. Example: for Smoke Alarm, Smoke Detected the Node Naming and Location Command Class MUST be advertised as supported in the Node Information Frame. + +Alarm Type = 0xFF is used by the Alarm Get Command to retrieve the first alarm detection from the list of pending alarms. + +Example: a device supports the Z-Wave Alarm Types: Smoke, CO and Heat. The Heat Alarm is active 2 e.g. overheat has been detected. When the device receives Alarm Get, Z-Wave Alarm Type (0xFF), it must return Alarm Report, Z-Wave Alarm Type (0x04), Z-Wave Alarm Event (0x01/0x02) and the accompanied parameters. + +## 4.2.5 Alarm Type Supported Get Command + +This command is used to request the supported alarm types. + +The Alarm Type Supported Report Command MUST be returned in response to an Alarm Type Supported Get command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ALARM _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ALARM TYPE SUPPORTED GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.2.6 Alarm Type Supported Report Command + +This command is used to advertise the supported alarm types in the application. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ALARM _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ALARM TYPE SUPPORTED REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| V1 Alarm | | | Reserved | | | | | | Number of Bit Masks | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| ... | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | | + +V1 Alarm (1 bit) + +0 = the device implements only Notification CC V2 (or newer) Notification Type(s). 1 = the device implements Notification CC V2 Notification Types as well as proprietary Alarm CC V1 Alarm Types and Alarm Levels. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Number of Bit Masks (5 bits) + +Indicates the Number of Bit Masks fields used in bytes. + +Bit Mask (N Bytes) + +The Bit Mask fields describe the supported Z-Wave Alarm Types by the device. + + Bit 0 in Bit Mask 1 is not allocated to any Z-Wave Alarm Type and MUST therefore be set to zero.  Bit 1 in Bit Mask 1 indicates if Z-Wave Alarm Type = 1 (Smoke) is supported.  Bit 2 in Bit Mask 1 indicates if Z-Wave Alarm Type = 2 (CO) is supported.  Bit 3 in Bit Mask 1 indicates if Z-Wave Alarm Type = 3 (CO) is supported 2  … + +If the Z-Wave Alarm Type is supported the corresponding bit MUST be set to 1. If the Z-Wave Alarm Type is not supported the corresponding bit MUST be set to 0. + +Z-Wave Alarm Type = 0xFF (Return first Alarm on supported list) MUST NOT be advertised in the Bit Masks. + +The number of Bit Mask fields MUST match the value advertised in the Number of Bit Masks field. + +Note that the mapping of bit 1 to Alarm Type =1 differs from the support mapping used by the Multilevel Sensor Command Class. The Multilevel Sensor Command Class maps bit 0 to Sensor Type = 1. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.02-anti-theft-command-class-version-1-obsoleted.md b/docs/specs/command-class-specification/04-command-class-definitions/04.02-anti-theft-command-class-version-1-obsoleted.md new file mode 100644 index 0000000..e3ee0ca --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.02-anti-theft-command-class-version-1-obsoleted.md @@ -0,0 +1,16 @@ + +# 4.2 Anti-theft Command Class, version 1 [OBSOLETED] + +THIS COMMAND CLASS VERSION HAS BEEN OBSOLETED + +New implementations MUST use the Anti-theft Command Class Version 2. + +The Anti-theft Command Class is used to disable a subset of supported/controlled command classes in a device if the device is being excluded and re-included into a Z-Wave network again. This command class is typically used when installing a Z-Wave device in a public location such as a hotel room or conference center. The command class allows the user to lock the device to the actual Z-Wave network and to render it useless if it is removed from the local network without being unlocked. Another application would be to protect service provider owned products from leaving the service providers network before they are paid for. + +Version 2 limits the Magic Code and Anti-theft Hint maximum bytes to 10. This makes it possible to embed Anti-theft Command Class Version 2 in one Security Command Class and thereby avoid splitting it. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.03-alarm-sensor-command-class-version-1-deprecated.md b/docs/specs/command-class-specification/04-command-class-definitions/04.03-alarm-sensor-command-class-version-1-deprecated.md new file mode 100644 index 0000000..14936bf --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.03-alarm-sensor-command-class-version-1-deprecated.md @@ -0,0 +1,110 @@ + +# 4.3 Alarm Sensor Command Class, version 1 [DEPRECATED] + +THIS COMMAND CLASS HAS BEEN DEPRECATED + +A device MAY implement this command class, but it is RECOMMENDED that new implementations use the Notification Command Class. If implementing this Command Class, it is RECOMMENDED that the Notification Command Class is also implemented. + +The Alarm Sensor Command Class is used to realize Sensor Alarms. + +## 4.3.1 Alarm Sensor Get Command + +This command is used to request the status of a sensor. + +The Alarm Sensor Report Command MUST be returned in response to this command if the sensor type is supported. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR ALARM _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR ALARM GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Type | | | | | | | | | | | | | | | | | | | | | | | | + +Sensor Type (8 bits) + +[Sensor Type specifies what type of sensor this command originates from. Refer to Table 12. The sensor](04.03-alarm-sensor-command-class-version-1-deprecated.md#431-alarm-sensor-get-command) type value 0xFF returns the first found supported sensor type in the bit mask (starting from bit 0 in Bit Mask 1) by the Alarm Sensor Supported Report. Table 12, Alarm Sensor Get::Sensor Type encoding + +| | Value | | | Sensor Type | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | General Purpose Alarm | | | +| 0x01 | | | Smoke Alarm | | | +| 0x02 | | | CO Alarm | | | +| 0x03 | | | CO Alarm 2 | | | +| 0x04 | | | Heat Alarm | | | +| 0x05 | | | Water Leak Alarm | | | +| 0xFF | | | Return first Alarm on supported list | | | + +## 4.3.2 Alarm Sensor Report Command + +This command is used to advertise the alarm state. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR ALARM _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR ALARM REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Source Node ID | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Type | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor State | | | | | | | | | | | | | | | | | | | | | | | | +| Seconds 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Seconds 2 (LSB) | | | | | | | | | | | | | | | | | | | | | | | | + +Source Node ID (8 bits) + +Specify the source node ID, which detected the alarm condition. In a Zensor Net is it not possible to determine the source node ID because the frame is broadcast forwarded without this information on protocol level. + +Sensor Type (8 bits) + +[Refer to 4.3.1 Alarm Sensor Get Command.](04.03-alarm-sensor-command-class-version-1-deprecated.md#431-alarm-sensor-get-command) The Sensor Type 0xFF MUST NOT be advertised in this command. + +Sensor State (8 bits) + +The Sensor State parameter returns the current alarm state. The value 0x00 indicates no alarm and 0xFF indicates alarm. Furthermore it can return values from 0x01 to 0x64 to indicate severity of the alarm in percentage. + +The values 0x65…0xFE are reserved and MUST be ignored by receiving nodes. Seconds (16 bits) + +The field Seconds indicates time the remote alarm must be active since last received report. The value 0x0000 indicates that the time field MUST be ignored. + +## 4.3.3 Alarm Sensor Supported Get Command + +This command is used to request the supported sensor types from the device. + +The Alarm Sensor Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR ALARM _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR ALARM SUPPORTED GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.3.4 Alarm Sensor Supported Report Command + +This command is used to report the supported sensor types from the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR ALARM _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR ALARM SUPPORTED REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Bit Masks | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | | + +Number of Bit Masks (8 bits) + +Indicates the Number of Bit Masks fields used in bytes. Bit Mask (N Bytes) + +The Bit Mask fields describe the supported sensor types by the device. + + Bit 0 in Bit Mask 1 indicates if Sensor Type = 0 (General Alarm) is supported.  Bit 1 in Bit Mask 1 indicates if Sensor Type = 1 (Smoke Alarm) is supported.  … + +The sensor type is supported if the bit is 1 and the opposite if 0. It is only necessary to send the Bit Mask fields from 1 and up to the one indicating the last supported sensor type. The number of Bit Mask fields transmitted MUST be determined from the length field in the frame. + +Note that the mapping of bit 1 to Sensor Type =1 differs from the support mapping used by the Multilevel Sensor Command Class. The Multilevel Sensor Command Class maps bit 0 to Sensor Type = 1. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.03-anti-theft-command-class-version-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.03-anti-theft-command-class-version-2.md new file mode 100644 index 0000000..2ce5a80 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.03-anti-theft-command-class-version-2.md @@ -0,0 +1,176 @@ + +# 4.3 Anti-theft Command Class, version 2 + +The Anti-theft Command Class MUST NOT be supported unless the Device Class or Device Type implemented by the device explicitly allows for support of the Anti-theft Command Class. + +The Anti-theft Command Class is intended for devices operating in public locations such as hotel rooms or a conference center. The purpose of the Anti-theft Command Class is to render a device useless if it is removed from its actual network without being unlocked by the owner or a service provider. + +The Anti-theft Command Class is used to disable all command classes related to the actual application functionality of a device if is it excluded and later included in another network. It does not matter if the device implements a single resource addressed via the Root Device or a collection of resources addressed via individual Multi Channel End Points Enabling anti-theft protection in a device MUST NOT change any operation with respect to supported/controlled command classes as long as the device stays in the actual network. + +If a locked device is excluded, it MUST enter the protected state. When in the protected state, the node information frame (NIF) MUST NOT advertise support of the protected command classes.The NIF MUST however continue advertising support of the Anti-theft Command Class and all other non-application specific command classes; just as when the device operates in its home network. The device MUST NOT respond to application commands while in the protected state. A device in protected state MUST NOT leave its protected state if it is re-included into its home network. Another Anti-Theft Set command MUST be used to either disable locking or to clear the protected state. + +The following non-device specific command classes must not be protected by the anti-theft functionality (i.e. will always be available in the device regardless of protection state): + + Manufacturer Specific Command Class  Version Command Class  Anti-theft Command Class  Security Command Class (optional) Security encapsulated command classes are allowed to be protected. In that case they must be removed from the Security Commands Supported Report Command when in the protected state in a foreign network. + +The protection state may be updated by sending the set command with the correct magic code to the device at any time and in any network. When the protection state is updated the device must return to normal operation, regardless of whether the update is to disable or re-enable protection. However, it is not possible to update protection state when device is excluded because it must be able to receive a command. + +The Anti-theft protection state must be preserved in the following situations: + + Exclusion of a network  Reset to factory default  OTA update of firmware + +If secure device, supports Anti-theft Command Class, Security Command Class needs to be supported regardless of anti-theft protection state. A security enabled device MUST be able to join any secure Z- Wave network regardless of its anti-theft protection state. It is RECOMMENDED for a device that supports anti-theft protection to have physical mark that indicates that this device is capable of being locked. It is further RECOMMENDED that the device is capable of signaling via a LED or other means if the device refuses inclusion in a network because the device is locked to another network. Finally, the user guide and installation manual MUST advertise support of anti-theft protection. + +## 4.3.1 Anti-theft Set Command + +This command is used to enable/disable anti-theft protection in a device already included into a Z-Wave Network by sending a magic code to device in question. The same magic code MUST be used to disable anti-theft protection again. A new magic code may be used the next time to enable anti-theft protection in the device, but only if protection is disabled at the time. A new device MUST have anti-theft protection disabled. Enabling anti-theft protection in an already-enabled device restores it to normal operation if it is in reduced functionality mode, but otherwise has no effect. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ANTITHEFT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ANTITHEFT SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Enable | | | Number of Magic Code bytes | | | | | | | | | | | | | | | | | | | | | +| Magic Code 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Magic Code N | | | | | | | | | | | | | | | | | | | | | | | | +| Manufacturer ID MSB | | | | | | | | | | | | | | | | | | | | | | | | +| Manufacturer ID LSB | | | | | | | | | | | | | | | | | | | | | | | | +| Anti-theft Hint Number Bytes | | | | | | | | | | | | | | | | | | | | | | | | +| Anti-theft Hint Byte 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Anti-theft Hint Byte N | | | | | | | | | | | | | | | | | | | | | | | | + +Enable (1 bit) + +The value MAY be 0 (Attempt to disable anti-theft protection in device) or 1 (Attempt to enable or re- enable anti-theft protection in device). It is not necessary to first disable an exclude device having protection enable; it can be re-enabled directly in a new network by using correct magic code again. + +Number of Magic Code bytes (7 bits) + +Indicates the Number of Magic Code fields N used in bytes. Maximum number of Magic Code fields MUST NOT exceed 10 bytes. + +Magic Code (N bytes) + +The Magic Code fields hold the code to enable/disable the Z-Wave device in question. Manufacturer ID (2 bytes) + +The Manufacturer ID of the company’s product having a central role in the application requiring anti-theft protection enabled. Device should report 0xFFFF if anti-theft protection is disabled. + +[Manufacturer identifiers can be found in [12].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +Number of Anti-theft Hint bytes (8 bits) + +Indicates the Number of Anti-theft Hint fields N used in bytes. If length is 0 no Hint provided. Maximum number of Anti-theft Hint fields MUST NOT exceed 10 bytes. + +Anti-theft Hint Byte (N bytes) + +Anti-theft Hint Bytes that may be used as an identifier or key value for retrieving the Magic Code. The exact format and meaning of these Bytes is specific to the product or service that enabled anti-theft protection on the device, as identified by the Manufacturer ID above. If it is necessary to render the Hint Bytes for display, each byte should be interpreted as an unsigned integer value and represented in hexadecimal. + +## 4.3.2 Anti-theft Get Command + +This command is used to get an Anti-theft Report Command showing status of the Z-Wave device in question. + +The Anti-theft Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ANTITHEFT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ANTITHEFT GET _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.3.3 Anti-theft Report Command + +This command is used to report status of the Z-Wave device in question. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ANTITHEFT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ANTITHEFT REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Anti-theft Protection Status | | | | | | | | | | | | | | | | | | | | | | | | +| Manufacturer ID MSB | | | | | | | | | | | | | | | | | | | | | | | | +| Manufacturer ID LSB | | | | | | | | | | | | | | | | | | | | | | | | +| Anti-theft Hint Number Bytes | | | | | | | | | | | | | | | | | | | | | | | | +| Anti-theft Hint Byte 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Anti-theft Hint Byte N | | | | | | | | | | | | | | | | | | | | | | | | + +Anti-theft Protection Status (8 bits) + +Anti-theft Protection Status specifies the actual status of Z-Wave device in question. Refer to the table below with respect to defined status values. + +| | Value | | | Anti-theft Protection Status | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Reserved. | | | +| 0x01 | | | Anti-Theft Protection is currently DISABLED, and the Z-Wave Device is fully functional. | | | +| 0x02 | | | Anti-Theft Protection is currently ENABLED, and the Z-Wave Device is fully functional. | | | +| 0x03 | | | Anti-Theft Protection is currently ENABLED, and the Z-Wave Device is NOT fully functional (i.e., the Device was excluded from a network without disabling protection, and an ANTITHEFT SET command with the correct Magic Code has not yet been received in _ the current network). | | | +| 0x04..0xFF | | | Reserved | | | + +Manufacturer ID (2 bytes) + +The Manufacturer ID of the company’s product having a central role in the application requiring anti-theft protection enabled. Device should report 0xFFFF if anti-theft protection is disabled. + +Number of Anti-theft Hint bytes (8 bits) + +Indicates the Number of Anti-theft Hint fields N used in bytes. If length is 0 no Hint provided. Maximum number of Anti-theft Hint fields MUST NOT exceed 10 bytes. + +Anti-theft Hint Byte (N bytes) + +Anti-theft Hint Bytes. See the Anti-Theft Set Command for more details. + +## 4.3.4 Examples + +Following examples are for reference only. + +### 4.3.4.1 Example of a non-secure Thermostat + +Below is shown an example of the Node Information Frame (NIF) content for a non-secure thermostat. The first NIF shows a device having anti-theft protection disabled. The device may never been included into a network or reside in a network or excluded from a network: + +| | Disabled anti-theft protection | | +| --- | --- | --- | +| Manufacturer Specific Command Class | | | +| Version Command Class | | | +| Anti-theft Command Class | | | +| Thermostat Operating State Command Class | | | +| Thermostat Mode Command Class | | | +| Association Command Class | | | +| Battery Command Class | | | + +The second NIF shows a device having anti-theft protection enabled. The device may be excluded from network in which it was originally anti-theft protection enabled or re-included into a network. This also applies in case device is re-included into the network, which device originally was anti-theft protection enabled: + +| | Enabled anti-theft protection | | +| --- | --- | --- | +| Manufacturer Specific Command Class | | | +| Version Command Class | | | +| Anti-theft Command Class | | | + +### 4.3.4.2 Example of a security enabled Thermostat + +Below is shown an example of the Node Information Frame (NIF) content for a security enabled thermostat. The first NIF shows a device having anti-theft protection disabled. The device may never been included into a network or reside in a network or excluded from a network: + +| | Disabled anti-theft protection | | +| --- | --- | --- | +| Manufacturer Specific Command Class | | | +| Version Command Class | | | +| Security Command Class | | | + +Finally, the Security Commands Supported Report Command reports support of the following command classes:  Anti-theft Command Class  Thermostat Operating State Command Class  Thermostat Mode Command Class  Association Command Class  Battery Command Class + +The second NIF shows a device having anti-theft protection enabled. The device may be excluded from network in which it was originally anti-theft protection enabled or re-included into a network. This also applies in case device is re-included into the network, which device originally was anti-theft protection enabled. The NIF is unchanged because all application oriented command classes are security encapsulated except the default command classes: + +| | Enabled anti-theft protection | | +| --- | --- | --- | +| Manufacturer Specific Command Class | | | +| Version Command Class | | | +| Security Command Class | | | + +Finally, the Security Commands Supported Report Command reports support of at least the Anti-theft Command Class to be able to disable anti-theft protection: + + Anti-theft Command Class + +The Anti-theft Command Class is supported securely making malicious attempts to enable anti-theft protection very difficult. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.04-alarm-silence-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.04-alarm-silence-command-class-version-1.md new file mode 100644 index 0000000..169c80c --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.04-alarm-silence-command-class-version-1.md @@ -0,0 +1,51 @@ + +# 4.4 Alarm Silence Command Class, version 1 + +The Alarm Silence Command Class may be used to temporarily disable the sounding of the alarm but still keep the alarm operating. + +## 4.4.1 Alarm Silence Set Command + +This command is used to remotely silence the sensor alarm. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SILENCE ALARM _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR ALARM SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Mode | | | | | | | | | | | | | | | | | | | | | | | | +| Seconds 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Seconds 2 (LSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Bit Masks | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | | + +Mode (8 bits) + +Mode specifies the different options to silence sensor alarms. Modes are defined by the Z-Wave Alliance. + +| | Value | | | Mode | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Disable sounding of all sensor alarms independent of bit mask | | | +| 0x01 | | | Disable sounding of all sensor alarms independent of bit mask which have received the alarm via the Sensor Alarm Report command | | | +| 0x02 | | | Disable sounding of all sensor alarms according to bit mask | | | +| 0x03 | | | Disable sounding of all sensor alarms according to bit mask which have received the alarm via the Alarm Sensor Report Command | | | + +Seconds (16 bits) + +The field Seconds indicates the duration sounding of the alarm must be disable but still keep the alarm operating. If silence is engaged, the alarm will come back on when the duration expires unless the originating sensor clears the alarm. The value 0x0000 indicates that the time field MUST be ignored. Number of Bit Masks (8 bits) + +Indicates the Number of Bit Masks fields used in bytes. + +Bit Mask (N Bytes) + +The Bit Mask fields describe the sensor types to disable sounding from. + + Bit 0 in Bit Mask 1 indicates if Sensor Type = 0 (General Alarm) is disabled.  Bit 1 in Bit Mask 1 indicates if Sensor Type = 1 (Smoke Alarm) is disabled.  … + +If the sensor type is disabled the bit MUST be set to 1. If the sensor type is not disabled the bit MUST be set to 0. It is only necessary to send the Bit Mask fields from 1 and up to the one indicating the last sensor type to be disabled. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.04-barrier-operator-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.04-barrier-operator-command-class-version-1.md new file mode 100644 index 0000000..5edad3f --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.04-barrier-operator-command-class-version-1.md @@ -0,0 +1,210 @@ + +# 4.4 Barrier Operator Command Class, version 1 + +The Barrier Operator Command Class is used to control and query the status of motorized barriers. + +## 4.4.1 Compatibility considerations + +A supporting node MAY ignore a Barrier Operator Command if the requested operation violates operational limitations or safety regulations. + +### 4.4.1.1 Node Information Frame (NIF) + +The Barrier Operator Command Class MUST be supported only using secure communication (S0 and/or S2 Command Class). + +A supporting node MUST NOT advertise the Barrier Operator Command Class in its NIF after network inclusion. + +### 4.4.1.2 Command Class dependencies + +A node supporting the Barrier Operator Command Class MUST support the Notification Command Class, version 4 or newer. + +## 4.4.2 Barrier Operator Set Command + +This command is used to initiate an unattended change in state of the barrier. + +A supporting node MAY ignore this command if the requested operation violates operational limitations or safety regulations. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS BARRIER OPERATOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = BARRIER OPERATOR SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Target Value | | | | | | | | | | | | | | | | | | | | | | | | + +Target Value (8 bits) + +This field MUST specify the intended state of the device. [The encoding of this field MUST be according to Table 13.](04.04-barrier-operator-command-class-version-1.md#442-barrier-operator-set-command) + +Table 13, Barrier Set::Target Value + +| | Target Value | | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | CLOSE | | Initiate unattended close | | | 1 | | | +| 0xFF | | OPEN | | Initiate unattended open | | | 1 | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +![Figure 3, Barrier Set, state transitions](assets/img-f94675db5a.png) + +A receiving node MUST comply with the allowed state changes and triggering commands specified in [Figure 3. Any state/command pair not specified in Figure 3 MUST NOT cause any action.](04.04-barrier-operator-command-class-version-1.md#442-barrier-operator-set-command) + +The receiving node SHOULD respond to OPEN and CLOSE commands. However, the receiving node MUST NOT respond to OPEN or CLOSE commands if any safety issue is detected. The receiving node MUST NOT respond to the CLOSE command unless it is in the “Open” state. + +### 4.4.2.1 Error Handling + +The device MUST stop if any safety issue is detected. + +If the requested operation is overruled by a safety mechanism, the device MUST notify the requester via a Notification Report with the Notification {Access Control::Barrier unable to perform requested operation due to UL requirements}. + +If the requested operation is prohibited by the specific device class, e.g. SPECIFIC_TYPE_SECURE_BARRIER_OPEN_ONLY or SPECIFIC_TYPE_SECURE_BARRIER_CLOSE_ONLY, the device MUST notify the requester by issuing CC:0066.01.01.11.009 an Application Rejected Request Command. The Application Rejected Request Command is a member of the Application Status Command Class. + +## 4.4.3 Barrier Operator Get Command + +This command is used to request the current state of a barrier operator device. + +[The Barrier Operator Report Command MUST be returned in response to this command.](04.04-barrier-operator-command-class-version-1.md#444-barrier-operator-report-command) + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS BARRIER OPERATOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = BARRIER OPERATOR GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.4.4 Barrier Operator Report Command + +This command is used to advertise the status of the barrier operator device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS BARRIER OPERATOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = BARRIER OPERATOR REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| State | | | | | | | | | | | | | | | | | | | | | | | | + +State (8 bits) + +This field MUST advertise the current state of the device. [The encoding of this field MUST be according to Table 14.](04.04-barrier-operator-command-class-version-1.md#444-barrier-operator-report-command) + +Table 14, Barrier Report::State + +| Value | State | | Requirement | | Description | Version | +| --- | --- | --- | --- | --- | --- | --- | +| | | | level | | | | +| 0x00 | Closed | REQUIRED | | | The barrier is in the Closed position | 1 | +| 0x01..0x63 | Stopped at exact Position | RECOMMENDED | | | 0x01 = 1% (Near Closed) 0x63 = 99% (Near Open) | 1 | +| 0xFC | Closing | REQUIRED | | | The barrier is closing. The current position is unknown. | 1 | +| 0xFD | Stopped | REQUIRED | | | The barrier is stopped. The current position is unknown. | 1 | +| 0xFE | Opening | REQUIRED | | | The barrier is opening. The current position is unknown. | 1 | +| 0xFF | Open | REQUIRED | | | The barrier is in the Open position | 1 | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +## 4.4.5 Barrier Operator Get Signaling Capabilities Supported Command + +This command is used to query a device for available subsystems which may be controlled via Z-Wave. + +[The Barrier Operator Report Signaling Capabilities Supported Command MUST be returned in response](04.04-barrier-operator-command-class-version-1.md#446-barrier-operator-report-signaling-capabilities-supported-command) to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS BARRIER OPERATOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = BARRIER OPERATOR SIGNAL SUPPORTED GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.4.6 Barrier Operator Report Signaling Capabilities Supported Command + +This command returns a bit mask of signaling subsystem(s) supported by the sending node. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS BARRIER OPERATOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = BARRIER OPERATOR SIGNAL SUPPORTED REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| …. | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | | + +Bit Mask (N bytes) + +This field is used to advertise the event signaling capabilities supported by the sending node. It MUST be treated as a bitmask. + +1. Bit 0 in Bit Mask 1 indicates if subsystem type 0x01 is supported 2. Bit 1 in Bit Mask 1 indicates if subsystem type 0x02 is supported 3. … + +If the subsystem type is supported, the corresponding bit MUST be set to 1. If the subsystem type is not supported, the corresponding bit MUST be set to 0. + +[For the complete list of subsystem types, refer to Table 15.](04.04-barrier-operator-command-class-version-1.md#447-barrier-operator-event-signal-set-command) + +The length of this field depends on the number of subsystems supported by the sending node. The length of this field MUST be in the range 1..32 bytes. A sending node MUST limit the length of this field to represent only those subsystems supported and MUST NOT extend the length of the Bit Mask to pad the packet with 0x00. + +## 4.4.7 Barrier Operator Event Signal Set Command + +This command is used to turn on or off an event signaling subsystem that is supported by the device. + +A supporting node MAY ignore this command if the requested operation violates safety regulartions. + +UL requirements MUST take precedence over any Set command sent to a subsystem. It is up to the discretion of the device to accept or reject the requested action. If the requested action is rejected, the node MUST notify the requester via the Notification Command Class Report with the Notification {Access Control::Barrier unable to perform requested operation due to UL requirements}. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS BARRIER OPERATOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = BARRIER OPERATOR SIGNAL SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Subsystem Type | | | | | | | | | | | | | | | | | | | | | | | | +| Subsystem State | | | | | | | | | | | | | | | | | | | | | | | | + +Subsystem Type (8 bits) + +This field is used to indicate which subsystem type MUST be set at the receiving node. This field MUST [comply with Table 15.](04.04-barrier-operator-command-class-version-1.md#447-barrier-operator-event-signal-set-command) + +Table 15, Barrier Operator Event signal::Subsystem types encoding + +| | Subsystem Type | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | NOT SUPPORTED - reserved | | | 1 | | | +| 0x01 | | | The Barrier Device has an Audible Notification subsystem controllable via Z-Wave (For example: Siren) | | | 1 | | | +| 0x02 | | | The Barrier Device has an Visual Notification subsystem controllable via Z-Wave (For example: Flashing Light) | | | 1 | | | +| 0x03.. 0xFF | | | reserved | | | 1 | | | + +Subsystem State (8 bits) + +This field is used to indicate the state that the specified subsystem MUST assume at the receiving node. [This field MUST comply with Table 16.](04.04-barrier-operator-command-class-version-1.md#447-barrier-operator-event-signal-set-command) + +Table 16, Barrier Operator Event Signal::Subsystem states encoding + +| | Subsystem State | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | Subsystem OFF | | | 1 | | | +| … | | | reserved | | | 1 | | | +| 0xFF | | | Subsystem ON | | | 1 | | | + +## 4.4.8 Barrier Operator Event Signaling Get Command + +This command is used to request the state of a signaling subsystem to a supporting node. + +The Barrier Operator Event Signaling Report Command MUST be returned in response to this command if the specified type is supported. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS BARRIER OPERATOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = BARRIER OPERATOR SIGNAL GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Subsystem Type | | | | | | | | | | | | | | | | | | | | | | | | + +[For fields’ description, refer to 4.4.7 Barrier Operator Event Signal Set Command.](04.04-barrier-operator-command-class-version-1.md#447-barrier-operator-event-signal-set-command) + +## 4.4.9 Barrier Operator Event Signaling Report + +This command is used to indicate the state of a notification subsystem of a Barrier Device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS BARRIER OPERATOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = BARRIER OPERATOR SIGNAL REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Subsystem Type | | | | | | | | | | | | | | | | | | | | | | | | +| Subsystem State | | | | | | | | | | | | | | | | | | | | | | | | + +[For fields’ description, refer to 4.4.7 Barrier Operator Event Signal Set Command](04.04-barrier-operator-command-class-version-1.md#447-barrier-operator-event-signal-set-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.05-basic-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.05-basic-command-class-version-1.md new file mode 100644 index 0000000..dfdb0d9 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.05-basic-command-class-version-1.md @@ -0,0 +1,93 @@ + +# 4.5 Basic Command Class, version 1 + +The Basic Command Class allows a controlling device to operate the primary functionality of a supporting device without any further knowledge. + +The Basic Command Class ensures a basic interoperability if no other command class is shared by two devices. + +[The Basic Command Class is an actuator control command class. Refer to 3.6.](../03-command-class-overview/03.06-actuator-control.md#36-actuator-control) + +## 4.5.1 Compatibility considerations + +A specific device may not be able to support all Basic CC commands or parameter levels. For instance, a relay can only open fully in response to any non-zero value. + +Any device SHOULD support the Basic Command Class. + +A device MUST implement mappings from the Basic Command Class to specific commands according to the advertised generic and specific device class of the Node Info frame. Mappings defined by a Specific Device Class have precedence over the Generic Device Class. + +For Z-Wave Plus devices, the Basic Command Class MUST be mapped according to the actual Z-Wave [Plus Device Type. For further information, refer to [10].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +The following sections only present frame formats. For details on the mapping to other command [classes, refer to [1] and [10].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +### 4.5.1.1 Node Information Frame (NIF) + +The Basic Command Class MUST NOT be advertised in the Node Information Frame. The Basic Command Class MUST NOT be advertised in the Security Commands Supported Report (S0 as well as S2) + +A securely included node MAY support the Basic Command Class at the highest security level but it MUST NOT support the Basic Command Class at any lower security level or non-securely. + +## 4.5.2 Basic Set Command + +This command is used to set a value in a supporting device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS BASIC _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = BASIC SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Value | | | | | | | | | | | | | | | | | | | | | | | | + +Value (8 bits) + +A supporting device SHOULD support all parameter values in the range {0x00..0x63, 0xFF}. A controlling device MUST NOT assume that a receiving device reacts to this command. + +A receiving device MUST interpret Basic Set parameter values according to the requirements of the [Device Class implemented by the device. Refer to [1] and [10].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +## 4.5.3 Basic Get Command + +This command is used to request the status of a supporting device. + +The Basic Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS BASIC _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = BASIC GET _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.5.4 Basic Report Command + +This command is used to advertise the status of the primary functionality of the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS BASIC _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = BASIC REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Value | | | | | | | | | | | | | | | | | | | | | | | | + +Value (8 bits) + +The Value field SHOULD advertise the current value of the device hardware; also while in transition to a new target value. + +[For details on the mapping of values, refer to [1] and [10].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +A controlling device MUST NOT assume that the Value is identical to a value previously specified in a Set command; not even when a transition has ended. + +[A receiving device MUST interpret the Value field according to Table 17.](04.05-basic-command-class-version-1.md#454-basic-report-command) + +Table 17, Basic Report :: Value + +| | Value | | | Level | | | State | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0 (0x00) | | | 0% | | | Off | | | +| 1..99 (0x01..0x63) | | | 1..100% | | | On | | | +| … | | | Reserved | | | Reserved | | | +| 254 (0xFE) | | | Unknown | | | Unknown | | | +| 255 (0xFF) | | | 100% | | | On | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.06-basic-command-class-version-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.06-basic-command-class-version-2.md new file mode 100644 index 0000000..e03128a --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.06-basic-command-class-version-2.md @@ -0,0 +1,56 @@ + +# 4.6 Basic Command Class, version 2 + +The Basic Command Class allows a controlling device to operate the primary functionality of another device without any further knowledge. + +The Basic Command Class ensures a basic interoperability if no other Command Class is shared by two devices. + +[The Basic Command Class is an actuator control command class. Refer to 3.6.](../03-command-class-overview/03.06-actuator-control.md#36-actuator-control) + +## 4.6.1 Compatibility considerations + +A device supporting Basic Command Class, version 2 MUST support Basic Command Class, version 1. Commands not described in this version remain unchanged from version 1. + +Version 2 adds the distinction between the Current Value and the Target State of the device. Version 2 elevates the requirement level so that the Current Value field of the Basic Report command MUST advertise the current value of the device hardware; also while in transition to a new target value. + +[The compatibility considerations from version 1 also apply to this version. Refer to 4.5.1.](04.05-basic-command-class-version-1.md#451-compatibility-considerations) + +## 4.6.2 Basic Report Command + +This command is used to advertise the status of the primary functionality of the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS BASIC _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = BASIC REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Current Value | | | | | | | | | | | | | | | | | | | | | | | | +| Target Value | | | | | | | | | | | | | | | | | | | | | | | | +| Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Current Value (8 bits) + +The Current Value field MUST advertise the current value of the device hardware; also while in transition to a new target value. + +The advertised values may vary depending on the device class implemented by the supporting device. A [controlling device MUST interpret the value according to Table 17.For details on the mapping of values,](04.05-basic-command-class-version-1.md#454-basic-report-command) [refer to [1] and [10].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +The Current Value SHOULD be identical to the Target Value when a transition has ended. Target Value (8 bits) + +The Target Value field MUST advertise the target value of an ongoing transition or the most recent transition. + +The advertised values may vary depending on the device class implemented by the supporting device. A [controlling device MUST interpret the value according to Table 17.](04.05-basic-command-class-version-1.md#454-basic-report-command) + +[For details on the mapping of values, refer to [1] and [10].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +If queried after receiving a Set command, the Target Value field MUST advertise the target value specified in the Set command. The Target Value MAY change at a later time due to local control or a “Stop” motion control command. + +If the device is in a motion controlled transition, the Target Value field MUST advertise the min or max [value (depending on the direction) according to the command class mappings defined in [1] and [10].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +Duration (8 bits) + +The Duration field SHOULD advertise the time needed to reach the Target Value at the actual transition [rate. The encoding of the Duration field MUST be according to Table 8.](../03-command-class-overview/03.07-common-fields-and-encoding.md#373-duration-encoding) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.07-basic-tariff-information-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.07-basic-tariff-information-command-class-version-1.md new file mode 100644 index 0000000..d57d0e5 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.07-basic-tariff-information-command-class-version-1.md @@ -0,0 +1,94 @@ + +# 4.7 Basic Tariff Information Command Class, version 1 + +This Basic Tariff Information Command Class for use with a single element or dual element meter, and for use with import (electricity received from grid) rates only. The command class is kept as simple as possible without any pricing information. + +This command class supports a GET and REPORT. + +No Set command is supported, as it is not appropriate to set any of the parameters through Z-Wave. + +## 4.7.1 Basic Tariff Information Get Command + +This command is used to request current tariff information from the meter. + +The Basic Tariff Information Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS BASIC TARIFF INFO _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = BASIC TARIFF INFO GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.7.2 Basic Tariff Information Report Command + +This command returns information on the number of import rates supported, and current import rate information. Application can send unsolicited Basic Tariff Report commands or requested by the Basic Tariff Get Information command. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS BASIC TARIFF INFO _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = BASIC TARIFF INFO REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Dual | | | Reserved | | | | | | | | | Total No. Import Rates | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | E1 – Current Rate in Use | | | | | | | | | | | | +| E1 - Rate Consumption Register – MSB | | | | | | | | | | | | | | | | | | | | | | | | +| E1 - Rate Consumption Register | | | | | | | | | | | | | | | | | | | | | | | | +| E1 - Rate Consumption Register | | | | | | | | | | | | | | | | | | | | | | | | +| E1 - Rate Consumption Register – LSB | | | | | | | | | | | | | | | | | | | | | | | | +| E1 – Time for Next Rate – Hours | | | | | | | | | | | | | | | | | | | | | | | | +| E1 – Time for Next Rate – Minutes | | | | | | | | | | | | | | | | | | | | | | | | +| E1 – Time for Next Rate – Seconds | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | E2 – Current Rate in Use | | | | | | | | | | | | +| E2 - Rate Consumption Register – MSB | | | | | | | | | | | | | | | | | | | | | | | | +| E2 - Rate Consumption Register | | | | | | | | | | | | | | | | | | | | | | | | +| E2 - Rate Consumption Register | | | | | | | | | | | | | | | | | | | | | | | | +| E2 - Rate Consumption Register – LSB | | | | | | | | | | | | | | | | | | | | | | | | + +Dual (1 bit) + +Single Element = 0, Two Elements = 1. + +If single element the E2 fields are skipped in the frame. E1 – Time for Next Rate – Seconds will be the last byte of the message and the number of data bytes will be 9. + +If two elements the E2 fields are present and the number of data bytes will be 14. + +Total Number of Import Rates Supported (7 bits) + +Field specifies the number of import rates E1 (and E2) supported by the meter. Range of legal decimal values are 1…8. No units used. The decimal values 0 and 9…15 are reserved and MUST be ignored by receiving devices. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. E1 – Current Rate in Use (8 bits) + +Field specifies the current rate in use. Range of legal decimal values are 1…8. No units used. The decimal values 0 and 9…15 are reserved and MUST be ignored by receiving devices. + +E1 – Rate Consumption Register (32 bits) + +The meter has a 32-bit consumption register, for the energy used in each rate. This register is the rate consumption register for the current rate in use now on element 1. Units are in Wh. + +E1 – Time for Next Rate – Hours (8 bits) + +Field specifies the hour value of the time that the rate is due to change on element 1. Range of legal decimal values are 0…23, or 255. The values 24…254 are reserved and MUST be ignored by receiving devices. + +E1 – Time for Next Rate – Minutes (8 bits) + +Field specifies the minute value of the time that the rate is due to change on element 1. Range of legal decimal values are 0…59, or 255. The decimal values 60…254 are reserved and MUST be ignored by receiving devices. + +E1 – Time for Next Rate – Seconds (8 bits) + +Field specifies the second value of the time that the rate is due to change on element 1. Range of legal decimal values are 0…59, or 255. The decimal values 60…254 are reserved and MUST be ignored by receiving devices. + +NOTE: 255 in each field of the Time to Next Rate specifies no switching time is in use, which is appropriate for single rate meters. 255 is only a legal value if used in all three Time to Next Rate fields. + +E2 – Current Rate in Use (8 bits) + +Field specifies the current rate in use on element 2. Range of legal decimal values are 1…8. No units used. The decimal values 0 and 9…15 are reserved and MUST be ignored by receiving devices. + +E2 – Rate Consumption Register (32 bits) + +The meter has a 32-bit consumption register, for the energy used in each rate. This register is the rate consumption register for the current rate in use now on element 2. Units are in Wh. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.08-basic-window-covering-command-class-version-1-obsoleted.md b/docs/specs/command-class-specification/04-command-class-definitions/04.08-basic-window-covering-command-class-version-1-obsoleted.md new file mode 100644 index 0000000..fe602d2 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.08-basic-window-covering-command-class-version-1-obsoleted.md @@ -0,0 +1,43 @@ + +# 4.8 Basic Window Covering Command Class, version 1 [OBSOLETED] + +THIS COMMAND CLASS HAS BEEN OBSOLETED + +New implementations MUST NOT support this command class. + +New window covering device implementations SHOULD support the Window Covering Command Class. + +This section contains Commands that may be used to control a Basic Window Covering Command Class. + +## 4.8.1 Basic Window Covering Start Level Change Command + +This command is used to start moving drapes, shades, blinds in a given direction. The speed of the movement is implementation specific. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS BASIC WINDOW COVERING _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = BASIC WINDOW COVERING START LEVEL CHANGE _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | Open/ Close | | | Reserved | | | | | | | | | | | | | | | | | | + +Open/Close (1 bit) + +If the Open/Close bit is set to 0 the window covering SHOULD open. If field is set to 1 the window covering SHOULD close. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +## 4.8.2 Basic Window Covering Stop Level Change Command + +This command is used to stop moving drapes, shades, blinds in a given direction. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS BASIC WINDOW COVERING _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = BASIC WINDOW COVERING STOP LEVEL CHANGE _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.09-binary-sensor-command-class-version-1-deprecated.md b/docs/specs/command-class-specification/04-command-class-definitions/04.09-binary-sensor-command-class-version-1-deprecated.md new file mode 100644 index 0000000..88255ca --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.09-binary-sensor-command-class-version-1-deprecated.md @@ -0,0 +1,41 @@ + +# 4.9 Binary Sensor Command Class, version 1 [DEPRECATED] + +THIS COMMAND CLASS HAS BEEN DEPRECATED + +A device MAY implement this command class, but it is RECOMMENDED that new implementations use the Notification Command Class. If implementing this command class, it is RECOMMENDED that the Notification Command Class is also implemented. + +The Binary Sensor Command Class is used to realize binary sensors, such as movement sensors. + +## 4.9.1 Binary Sensor Get Command + +This command is used to request the status of a sensor. + +The Binary Sensor Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR BINARY _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR BINARY GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.9.2 Binary Sensor Report Command + +This command is used to advertise a sensor value. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR BINARY _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR BINARY REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Value | | | | | | | | | | | | | | | | | | | | | | | | + +Sensor Value (8 bits) + +If the Sensor Value is 0x00 indicates that the sensor is idle and 0xFF indicates that the sensor has detected an event. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.10-binary-sensor-command-class-version-2-deprecated.md b/docs/specs/command-class-specification/04-command-class-definitions/04.10-binary-sensor-command-class-version-2-deprecated.md new file mode 100644 index 0000000..18b8b02 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.10-binary-sensor-command-class-version-2-deprecated.md @@ -0,0 +1,105 @@ + +# 4.10 Binary Sensor Command Class, version 2 [DEPRECATED] + +THIS COMMAND CLASS HAS BEEN DEPRECATED + +A device MAY implement this command class, but it is RECOMMENDED that new implementations use the Notification Command Class. If implementing this command class, it is RECOMMENDED that the Notification Command Class is also implemented. + +The Binary Sensor Command Class is used to realize binary sensors, such as movement sensors and door/window sensors. Version 2 of this command class is extended with the following functionalities: + + A “get-supported” mechanism for the controlling device to interview the binary sensor for its supported sensor types + + A list of defined sensor types capable of reporting a binary value + +NOTE: A binary sensor is defined as a sensor unit capable of providing a binary value in the report i.e. that an event was “triggered” or “not triggered” and not other intermediate values. For sensor units providing multiple values the Multilevel Sensor Command Class is more suitable. The Binary Sensor Command Class can further advance through implementation of the Notification Command Class to communicate details about the event. + +## 4.10.1 Binary Sensor Get Command + +This command is used to request the status of the specific sensor device. + +The Binary Sensor Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR BINARY _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR BINARY GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Type | | | | | | | | | | | | | | | | | | | | | | | | + +Sensor Type (8 bits) + +[Sensor Type specifies what type of sensor this command originates from. Refer to Table 18. The sensor](04.10-binary-sensor-command-class-version-2-deprecated.md#4101-binary-sensor-get-command) type value 0xFF returns the first found supported sensor type in the bit mask (starting from bit 0 in Bit Mask 1) by the Binary Sensor Supported Report. + +Table 18, Binary Sensor Get::Sensor Type encoding + +| | Value | | | Sensor Type | | +| --- | --- | --- | --- | --- | --- | +| | 0x00 | | | Reserved | | +| 0x01 | | | General purpose | | | +| 0x02 | | | Smoke | | | +| 0x03 | | | CO | | | +| 0x04 | | | CO 2 | | | +| 0x05 | | | Heat | | | +| 0x06 | | | Water | | | +| 0x07 | | | Freeze | | | +| 0x08 | | | Tamper | | | +| 0x09 | | | Aux | | | +| 0x0A | | | Door/Window | | | +| 0x0B | | | Tilt | | | +| 0x0C | | | Motion | | | +| 0x0D | | | Glass Break | | | +| | 0x0E..0xFE | | | Reserved | | +| 0xFF | | | Return 1st Sensor Type on supported list | | | + +## 4.10.2 Binary Sensor Report Command + +This command is used to advertise a sensor value. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR BINARY _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR BINARY REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Value | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Type | | | | | | | | | | | | | | | | | | | | | | | | + +Sensor Value (8 bits) + +Sensor Value = 0x00 indicates that the sensor is idle and 0xFF indicates that the sensor has detected an event. + +## 4.10.3 Binary Sensor Get Supported Sensor Command + +This command is used to request the supported sensor types from the binary sensor device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR BINARY _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR BINARY SUPPORTED GET SENSOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.10.4 Binary Sensor Supported Sensor Report Command + +This command must be sent as requested by a received Binary Sensor Get Supported Sensor Command. This command indicates the supported sensor types of the binary sensor device in a bit mask format and MUST NOT be transmitted unsolicited. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR BINARY _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR BINARY SUPPORTED SENSOR REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | | + +Bit Mask (N bytes) + +The Bit Mask fields describe the supported sensor types by the binary sensor device and refer to the Sensor Type table of Binary Sensor Report command. + + Bit 0 in Bit Mask 1 is not allocated to any Sensor Type and must therefore be set to zero.  Bit 1 in Bit Mask 1 indicates if Sensor Type = 1 (General Purpose) is supported.  Bit 2 in Bit Mask 1 indicates if Sensor Type = 2 (Smoke) is supported.  Bit 3 in Bit Mask 1 indicates if Sensor Type = 3 (CO) is supported  … + +If the Sensor Type is supported the bit MUST be set to 1. If the Sensor Type is not supported the bit MUST be set to 0. Sensor Type = 0xFF (Return 1st Sensor Type on supported list) cannot be indicated by the Bit Masks. + +Note: It is only necessary to transmit Bit Mask 1 and up to the Bit Mask N indicating the last supported sensor type. The number of Bit Mask fields transmitted MUST be determined from the length field in the frame. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.100-thermostat-setback-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.100-thermostat-setback-command-class-version-1.md new file mode 100644 index 0000000..dbdadcf --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.100-thermostat-setback-command-class-version-1.md @@ -0,0 +1,84 @@ + +# 4.100 Thermostat Setback Command Class, version 1 + +The Thermostat Setback Command Class is used to change the current state of a non-schedule setback thermostat. + +## 4.100.1 Thermostat Setback Set Command + +This command is used to set the state of the thermostat. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT SETBACK _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT SETBACK SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | Setback Type | | | | | | +| Setback State | | | | | | | | | | | | | | | | | | | | | | | | + +Setback Type (2 bits) + +[The setback type field MUST comply with Table 133](04.100-thermostat-setback-command-class-version-1.md#41001-thermostat-setback-set-command) + +Table 133, Thermostat Setback Set::Setback Type encoding + +| | Value | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 0x01 0x02 0x03 | | | No override Temporary override Permanent override Reserved | | | + +Note: The temporary override provides an opportunity to implement a timer or equivalent in the device. A temporary override will, if a timer is implemented, be terminated by the timer. If no timer is implemented the temporary override MUST act as permanent override. If the temporary override is implemented it MUST be documented in the user’s manual. + +Setback State (8 bits) + +[The Setback State MUST comply with Table 134](04.100-thermostat-setback-command-class-version-1.md#41001-thermostat-setback-set-command) Table 134, Thermostat Setback Set::Setback State encoding + +| | Setback State | | | | | Description | +| --- | --- | --- | --- | --- | --- | --- | +| | Hexadecimal | | | Decimal | | | +| 0x80 … 0xFF 0x00 0x01 … 0x78 | | | -128 … -1 0 1 … 120 | | | The setback in 1/10 degrees (Kelvin) Example: 0 = 0 degrees setback 1 = 0.1 degrees is added to the setpoint 2 = 0.2 degrees is added to the setpoint -1 = 0.1 degrees is subtracted from the setpoint -2 = 0.2 degrees is subtracted from the setpoint | +| 0x79 | | | 121 | | | Frost Protection | +| 0x7A | | | 122 | | | Energy Saving Mode | +| 0x7B – 0x7E | | | 123 – 126 | | | Reserved | +| 0x7F | | | 127 | | | Unused State | + +Reserved values MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +When converting between Celsius and Fahrenheit proper rounding MUST be applied with at least two decimals in the internal calculations of a device to avoid rounding errors. + +Note: The implementation of Energy Saving Mode is manufacturer specific, and MUST be documented in the User’s Manual. If the device is set to an unreachable state, the device SHOULD assume the closest possible state. + +## 4.100.2 Thermostat Setback Get Command + +This command is used to request the current state of the thermostat. + +The Thermostat Setback Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT SETBACK _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT SETBACK GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.100.3 Thermostat Setback Report Command + +This command is used to report the current state of the thermostat. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT SETBACK _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT SETBACK REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | Setback Type | | | | | | +| Setback State | | | | | | | | | | | | | | | | | | | | | | | | + +Setback Type (2 bits) + +Refer to description under the Thermostat Setback Set Command + +Setback State (8 bits) + +Refer to description under the Thermostat Setback Set Command. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.101-thermostat-setpoint-command-class-version-1-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.101-thermostat-setpoint-command-class-version-1-2.md new file mode 100644 index 0000000..47cdd98 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.101-thermostat-setpoint-command-class-version-1-2.md @@ -0,0 +1,151 @@ + +# 4.101 Thermostat Setpoint Command Class, version 1-2 + +The Thermostat Setpoint Command Class is used for setpoint handling. Version 2 extends the available number of setpoint types. + +## 4.101.1 Interoperability Considerations + +It has been found that early implementations of this Command Class specification apply two non- interoperable interpretations of the bit mask advertising the support for specific Setpoint Types. + +As a consequence, one may find thermostat products and controller products in the marketplace which [implement either of the two bit mask interpretations found in Table 135. The notation x.y indicates Bit](04.102-thermostat-setpoint-command-class-version-3.md#41021-interoperability-considerations) Mask byte x, bit y. + +Implementations of Thermostat Setpoint Command Class, version 1-2 SHOULD comply with Interpretation A. + +It is RECOMMENDED that a controlling node determines supported Setpoint Types by sending one Thermostat Setpoint Get Command at a time while incrementing the requested Setpoint Type. If the same Setpoint Type is advertised in the resulting Thermostat Setpoint Report Command, the controlling node MAY conclude that the actual Setpoint Type is supported. If the Setpoint Type 0x00 (type N/A) is advertised in the resulting Thermostat Setpoint Report Command, the controlling node MUST conclude that the actual Setpoint Type is not supported. + +## 4.101.2 Thermostat Setpoint Set Command + +This command is used to specify the target value for the specified Setpoint Type. + +It is RECOMMENDED that all combinations of precision, scale and size parameters are supported. The Thermostat Setpoint Set command MUST support the same format of precision, scale and size parameters as can be returned in the Thermostat Setpoint Report command. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT SETPOINT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT SETPOINT SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Setpoint Type | | | | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | | | | +| Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| .. | | | | | | | | | | | | | | | | | | | | | | | | +| Value N | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Setpoint Type (4 bits) + +[This field specifies the Setpoint to be set in the thermostat. The value MUST comply with Table 136.](04.102-thermostat-setpoint-command-class-version-3.md#41022-thermostat-setpoint-set-command) Precision (3 bits) + +This field specifies the precision of the setpoint value. The value MUST indicate the number of decimals. As an example, the decimal value 1025 with precision 2 must be interpreted as 10.25. + +Scale (2 bits) + +[This field specifies the temperature scale used. The field MUST be encoded according to Table 137..](04.102-thermostat-setpoint-command-class-version-3.md#41022-thermostat-setpoint-set-command) + +Size (3 bits) + +This field specifies the number of bytes used for the Value field. The value of this field MUST comply [with Table 138.](04.102-thermostat-setpoint-command-class-version-3.md#41022-thermostat-setpoint-set-command) + +Value (N bytes) + +This field carries the actual setpoint value. The size of the field MUST comply with the size advertised by the Size field. + +[The field MUST carry a signed value. The binary encoding of the signed value MUST comply with Table 10. The field Value 1 MUST be the most significant byte.](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) + +## 4.101.3 Thermostat Setpoint Get Command + +This command is used to query the value of a specified setpoint type. + +The Thermostat Setpoint Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT SETPOINT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT SETPOINT GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Setpoint Type | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Setpoint Type (4 bits) + +Refer to description under the Thermostat Setpoint Set Command. + +If a request for a supported Setpoint Type value is received, the same value MUST be returned in the Thermostat Setpoint Report Command. + +If a request for a unsupported Setpoint Type value is received, the value 0x00 (N/A) MUST be returned in the Thermostat Setpoint Report Command. + +## 4.101.4 Thermostat Setpoint Report Command + +This command is used to advertise the value a setpoint type. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT SETPOINT _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT SETPOINT REPORT _ _ | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Setpoint Type | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | +| Value 1 | | | | | | | | | | | | | | | | | | | | | +| .. | | | | | | | | | | | | | | | | | | | | | +| Value N | | | | | | | | | | | | | | | | | | | | | + +Refer to Thermostat Setpoint Set command for fields not described below. + +Setpoint Type (4 bits) + +This field specifies the actual Setpoint advertised by the sending node. The value MUST comply with [Table 136.](04.102-thermostat-setpoint-command-class-version-3.md#41022-thermostat-setpoint-set-command) + +If this field is set to 0x00 (N/A), it is RECOMMENDED to set the Size field to 1 and the Value field to 0. + +## 4.101.5 Thermostat Setpoint Supported Get Command + +This command is used to query the supported setpoint types. + +The Thermostat Setpoint Supported Report Command MUST be returned in response to this command. + +[This command is known to cause interoperability issues. Refer to section 4.101.1.](04.101-thermostat-setpoint-command-class-version-1-2.md#41011-interoperability-considerations) + +A controlling device SHOULD NOT rely on the information returned in the Thermostat Setpoint Supported Report Command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT SETPOINT _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT SETPOINT SUPPORTED GET _ _ _ | | | | | | | | | | | | | | | | | | | | | + +## 4.101.6 Thermostat Setpoint Supported Report Command + +This command is used to advertise the supported setpoint types. + +[This command is known to cause interoperability issues. Refer to section 4.101.1.](04.101-thermostat-setpoint-command-class-version-1-2.md#41011-interoperability-considerations) + +A controlling device SHOULD NOT rely on the information returned in the Thermostat Setpoint Supported Report Command. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT SETPOINT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT SETPOINT SUPPORTED REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | | + +Bit Mask (N bytes) + +[The Bit Mask field advertises the supported Setpoint Types. Refer to section 4.101.1 for details on the](04.101-thermostat-setpoint-command-class-version-1-2.md#41011-interoperability-considerations) encoding of the Bit Mask field. + +If the Setpoint Type is supported the corresponding bit MUST be set to 1. If the Setpoint Type is not supported the corresponding bit MUST be set to 0. + +A node SHOULD send only the Bit Mask fields from 1 and up to the one indicating the last supported Setpoint Type. + +The number of Bit Mask fields MUST be determined from the length field of the frame. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.102-thermostat-setpoint-command-class-version-3.md b/docs/specs/command-class-specification/04-command-class-definitions/04.102-thermostat-setpoint-command-class-version-3.md new file mode 100644 index 0000000..1fb78c1 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.102-thermostat-setpoint-command-class-version-3.md @@ -0,0 +1,260 @@ + +# 4.102 Thermostat Setpoint Command Class, version 3 + +The Thermostat Setpoint Command Class, version 3 is an extension to support control and status monitoring functions of air-conditioning devices in order to cover functions found in typical air- conditioning products. The new features comprise: + + Discovery of the precision and size supported by the device  Discovery of the upper and lower limits of the specific setpoint type  New Thermostat Setpoint Types: Away Cooling, Full Power. + +## 4.102.1 Interoperability Considerations + +It has been found that early implementations of this Command Class specification apply two non- interoperable interpretations of the bit mask advertising the support for specific Setpoint Types. + +As a consequence, one may find thermostat products and controller products in the marketplace which [implement either of the two bit mask interpretations found in Table 135. The notation x.y indicates Bit](04.102-thermostat-setpoint-command-class-version-3.md#41021-interoperability-considerations) Mask byte x, bit y. Table 135, Thermostat Setpoint Types Bit Mask encoding + +| | Support Bit Mask, | | | Support Bit Mask, | | | Setpoint Type | | Description | | | Version | | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| | Interpretation A | | | Interpretation B | | | Identifier | | | | | | | | +| | 1.0 | | | 1.0 | | | 0x00 | | | N/A | | | - | | +| | 1.1 | | 1.1 | | | 0x01 | | | Heating | | | 1 | | | +| | 1.2 | | 1.2 | | | 0x02 | | | Cooling | | | 1 | | | +| | | | | 1.3 | | | 0x03 | | | N/A | | | - | | +| | | | | 1.4 | | | 0x04 | | | N/A | | | - | | +| | | | | 1.5 | | | 0x05 | | | N/A | | | - | | +| | | | | 1.6 | | | 0x06 | | | N/A | | | - | | +| | 1.3 | | 1.7 | | | 0x07 | | | Furnace | | | 1 | | | +| | 1.4 | | 2.0 | | | 0x08 | | | Dry Air | | | 1 | | | +| | 1.5 | | 2.1 | | | 0x09 | | | Moist Air | | | 1 | | | +| 1.6 | 1.6 | | 2.2 | | | 0x0A | | | Auto changeover | | | 1 | | | +| 1.7 | | | 2.3 | | | 0x0B | | | Energy Save Heating | | | 2 | | | +| 2.0 | | | 2.4 | | | 0x0C | | | Energy Save Cooling | | | 2 | | | +| 2.1 | | | 2.5 | | | 0x0D | | | Away Heating | | | 2 | | | +| 2.2 | | | 2.6 | | | 0x0E | | | Away Cooling | | | 3 | | | +| | 2.3 | | 2.7 | | | 0x0F | | | Full Power | | | 3 | | | + +All other bits are reserved and MUST be set to zero by a sending node. Reserved bits MUST be ignored by a receiving node. + +Implementations of Thermostat Setpoint Command Class, version 3 MUST comply with Interpretation A. + +It is RECOMMENDED that a controlling node determines supported Setpoint Types by sending one Thermostat Setpoint Get Command at a time while incrementing the requested Setpoint Type. If the same Setpoint Type is advertised in the resulting Thermostat Setpoint Report Command, the controlling node MAY conclude that the actual Setpoint Type is supported. If the Setpoint Type 0x00 (type N/A) is advertised in the resulting Thermostat Setpoint Report Command, the controlling node MUST conclude that the actual Setpoint Type is not supported. + +## 4.102.2 Thermostat Setpoint Set Command + +This command is used to specify the target value for the specified Setpoint Type. + +It is RECOMMENDED that all combinations of precision, scale and size parameters are supported. The Thermostat Setpoint Set command MUST support the same format of precision, scale and size parameters as can be returned in the Thermostat Setpoint Report command. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT SETPOINT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT SETPOINT SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Setpoint Type | | | | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | | | | +| Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| .. | | | | | | | | | | | | | | | | | | | | | | | | +| Value N | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Setpoint Type (4 bits) + +This field specifies the setpoint to be set in the thermostat. + +[The value MUST comply with Table 136.](04.102-thermostat-setpoint-command-class-version-3.md#41022-thermostat-setpoint-set-command) Table 136, Thermostat Setpoint Set::Setpoint Types + +| Setpoint Type | Description | | CC | | +| --- | --- | --- | --- | --- | +| | | | Version | | +| 0x00 | N/A | - | | | +| 0x01 | Heating | 1 | | | +| 0x02 | Cooling | 1 | | | +| 0x03 | N/A | - | | | +| 0x04 | N/A | - | | | +| 0x05 | N/A | - | | | +| 0x06 | N/A | - | | | +| 0x07 | Furnace | 1 | | | +| 0x08 | Dry Air | 1 | | | +| 0x09 | Moist Air | 1 | | | +| 0x0A | Auto Changeover | 1 | | | +| 0x0B | Energy Save Heating | 2 | | | +| 0x0C | Energy Save Cooling | 2 | | | +| 0x0D | Away Heating | 2 | | | +| 0x0E | Away Cooling | 3 | | | +| 0x0F | Full Power | 3 | | | + +Values marked as not applicable (N/A) MUST be ignored by a receiving node. + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Precision (3 bits) + +This field specifies the precision of the setpoint value. The value MUST indicate the number of decimals. As an example, the decimal value 1025 with precision 2 must be interpreted as 10.25. + +Scale (2 bits) + +[This field specifies the temperature scale used. The field MUST be encoded according to Table 137.](04.102-thermostat-setpoint-command-class-version-3.md#41022-thermostat-setpoint-set-command) + +Table 137, Thermostat Setpoint Set::Scale encoding + +| | Scale | Scale used in Value field | | +| --- | --- | --- | --- | +| 0 | | Celcius | | +| 1 | | Fahrenheit | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. Size (3 bits) + +This field specifies the number of bytes used for the Value field. The value of this field MUST comply [with Table 138.](04.102-thermostat-setpoint-command-class-version-3.md#41022-thermostat-setpoint-set-command) + +Table 138, Thermostat Setpoint Set::Size encoding + +| | Size | | | Size of Value field | | +| --- | --- | --- | --- | --- | --- | +| 1 | | | 8 bit | | | +| 2 | | | 16 bit | | | +| 4 | | | 32 bit | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Value (N bytes) + +This field carries the actual setpoint value. The size of the field MUST comply with the size advertised by the Size field. + +[The field MUST carry a signed value. The binary encoding of the signed value MUST comply with Table 10. The field Value 1 MUST be the most significant byte.](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) + +## 4.102.3 Thermostat Setpoint Get Command + +This command is used to query the value of a specified setpoint type. + +The Thermostat Setpoint Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT SETPOINT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT SETPOINT GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Setpoint Type | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Setpoint Type (4 bits) + +Refer to description under the Thermostat Setpoint Set Command. + +If a supported Setpoint Type value is received, the same value MUST be returned in the Thermostat Setpoint Report Command. + +If an unsupported Setpoint Type value is received, the value 0x00 (N/A) MUST be returned in the Thermostat Setpoint Report Command. + +## 4.102.4 Thermostat Setpoint Report Command + +This command is used to advertise the value of a setpoint type. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT SETPOINT _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT SETPOINT REPORT _ _ | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Setpoint Type | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | +| Value 1 | | | | | | | | | | | | | | | | | | | | | +| .. | | | | | | | | | | | | | | | | | | | | | +| Value N | | | | | | | | | | | | | | | | | | | | | + +Refer to Thermostat Setpoint Set command for parameter/field descriptions. + +## 4.102.5 Thermostat Setpoint Supported Get Command + +This command is used to query the supported setpoint types. + +The Thermostat Setpoint Supported Report Command MUST be returned in response to this command. + +[This command is known to cause interoperability issues. Refer to section 4.102.1.](04.102-thermostat-setpoint-command-class-version-3.md#41021-interoperability-considerations) + +A controlling device SHOULD NOT rely on the information returned in the Thermostat Setpoint Supported Report Command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT SETPOINT _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT SETPOINT SUPPORTED GET _ _ _ | | | | | | | | | | | | | | | | | | | | | + +## 4.102.6 Thermostat Setpoint Supported Report Command + +This command is used to advertise the supported setpoint types. + +[This command is known to cause interoperability issues. Refer to section 4.102.1.](04.102-thermostat-setpoint-command-class-version-3.md#41021-interoperability-considerations) + +A controlling device SHOULD NOT rely on the information returned in the Thermostat Setpoint Supported Report Command. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT SETPOINT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT SETPOINT SUPPORTED REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | | + +Bit Mask (N bytes) + +The Bit Mask field advertises the supported Setpoint Types. + +[Refer to section 4.102.1 for details on the encoding of the Bit Mask field.](04.102-thermostat-setpoint-command-class-version-3.md#41021-interoperability-considerations) + +If the Setpoint Type is supported, the corresponding bit MUST be set to 1. If the Setpoint Type is not supported the corresponding bit MUST be set to 0. + +A node SHOULD send only the Bit Mask fields from 1 and up to the one indicating the last supported mode. + +The number of Bit Mask fields MUST be determined from the length field of the frame. + +## 4.102.7 Thermostat Setpoint Capabilities Get Command + +This command is used query the minimum and maximum setpoint values for the specified Setpoint Type. + +The Thermostat Setpoint Capabilities Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT SETPOINT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT SETPOINT CAPABILITIES GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Setpoint Type | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. Setpoint Type (4 bits) + +Refer to description under the Thermostat Setpoint Set Command. + +If a supported Setpoint Type value is received, the same value MUST be returned in the Thermostat Setpoint Capabilities Report Command. + +If an unsupported Setpoint Type value is received, the value 0x00 (N/A) MUST be returned in the Thermostat Setpoint Report Command. + +## 4.102.8 Thermostat Setpoint Capabilities Report Command + +This command is used to advertise the minimum and maximum values for the advertised Setpoint Type. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT SETPOINT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT SETPOINT CAPABILITIES REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Setpoint Type | | | | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | | | | +| Min Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| .. | | | | | | | | | | | | | | | | | | | | | | | | +| Min Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | | | | +| Max Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| .. | | | | | | | | | | | | | | | | | | | | | | | | +| Max Value N | | | | | | | | | | | | | | | | | | | | | | | | + +Refer to Thermostat Setpoint Set command for field descriptions. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.103-time-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.103-time-command-class-version-1.md new file mode 100644 index 0000000..cf19142 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.103-time-command-class-version-1.md @@ -0,0 +1,115 @@ + +# 4.103 Time Command Class, version 1 + +The Time Command Class, version1 is used to read date and time from a supporting node in a Z-Wave network. + +## 4.103.1 Compatibility considerations + +Notice that the former Time Command Class version 1 (Revision 4 of this document) is discontinued and replaced by a new one. + +### 4.103.1.1 Node Information Frame (NIF) + +A supporting node MUST always advertise the Time Command Class in its NIF, regardless of the security bootstrapping outcome. + +This allows other nodes bootstrapped on any security level to request the current time from a supporting node. + +## 4.103.2 Interoperability considerations + +Nodes supporting this Command Class are time servers for other nodes in a Z-Wave network. Other nodes can learn the current date and time by querying nodes supporting this Command Class. + +For nodes based on a slave Role Type, it is RECOMMENDED to support a dedicated Association Group which issues the Time Get Command and/or the Date Get Command. Controlling nodes SHOULD automatically associate such association groups to a node supporting the Time Command Class. + +## 4.103.3 Time Get Command + +This command is used to request the current time from a supporting node. + +[The Time Report Command MUST be returned in response to this command.](04.103-time-command-class-version-1.md#41034-time-report-command) + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TIME _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = TIME GET _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.103.4 Time Report Command + +This command is used to report the current time. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TIME _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = TIME REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| RTC failure | | | Reserved | | | | | | Hour Local Time | | | | | | | | | | | | | | | +| Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | + +RTC failure (1 bit) + +Many RTC chips have a stop bit indicating if the oscillator has been stopped. The RTC failure bit MUST be set to 1 in order to indicate to the receiving node that the RTC has been stopped and that the advertised time might be inaccurate. + +If the sending node does not support this feature or if the oscillator has not been stopped, it MUST set this field to 0. If the receiving node does not support this feature, it MUST ignore this field. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Hour Local Time (8 bits) + +This field is used to indicate the number of complete hours that have passed since midnight in local time. This field MUST be in the range 0..23. + +Minute Local Time (8 bits) + +This field is used to indicate the number of complete minutes that have passed since the start of the hour in local time. This field MUST be in the range 0..59. + +Second Local Time (8 bits) + +This field is used to indicate the number of complete seconds that have passed since the start of the minute in local time. This field MUST be in the range 0..59. + +Note: the time synchronization between nodes may vary by a few seconds due to delays introduced by the wireless communication. + +## 4.103.5 Date Get Command + +This command is used to request the current date adjusted according to the local time zone and Daylight Saving Time from a supporting node. + +[The Date Report Command MUST be returned in response to this command.](04.103-time-command-class-version-1.md#41036-date-report-command) + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TIME _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DATE GET _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.103.6 Date Report Command + +This command is used to advertise the current date adjusted according to the local time zone and Daylight Saving Time. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TIME _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DATE REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Month | | | | | | | | | | | | | | | | | | | | | | | | +| Day | | | | | | | | | | | | | | | | | | | | | | | | + +Year (16 bits) + +This field MUST specify the current year using the Gregorian calendar. The first byte (Year 1) MUST be the most significant byte. + +For example, Year1= 0x07 and Year2 =0xD7 MUST indicate year 2007 + +Month (8 bits) + +This field MUST specify the current month of the year. This field MUST be in the range 1..12 (representing respectively January...December). + +Day (8 bits) + +This field MUST specify current the day of the month. This field MUST be in the range 1..31. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.104-time-command-class-version-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.104-time-command-class-version-2.md new file mode 100644 index 0000000..a5eb0c6 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.104-time-command-class-version-2.md @@ -0,0 +1,131 @@ + +# 4.104 Time Command Class, version 2 + +The Time Command Class, version 2 is used to read date and time from a supporting node in a Z-Wave network. + +## 4.104.1 Compatibility considerations + +The Time Command Class, version 2 is backwards compatible with the Time Command Class, version 1. + +The Time Command Class, version 2 enables reading and setting Time Zone Offset and Daylight Saving Time parameters. The data formats are based on the International Standard ISO 8601. + +Commands not described in this version MUST remain unchanged from version 1. + +### 4.104.1.1 Node Information Frame (NIF) + +A supporting node MUST always advertise the Time Command Class in its NIF, regardless of the security bootstrapping outcome. + +This allows other nodes bootstrapped on any security level to request the current time from a supporting node. + +## 4.104.2 Interoperability considerations + +Nodes supporting this Command Class are time servers for other nodes in a Z-Wave network. Other nodes can learn the current date and time by querying nodes supporting this Command Class. + +For nodes based on a slave Role Type, it is RECOMMENDED to support a dedicated Association Group which issues the Time Get Command, the Date Get Command and/or the Time Offset Get Command. Controlling nodes SHOULD automatically associate such association groups to a node supporting the Time Command Class, version 2. + +The purpose of this Command Class is to read the current date and time information from supporting nodes. Hence, supporting nodes MAY ignore the Time Offset Set Command introduced in version 2 if they rely on another source to retrieve the Time Zone Offset and Daylight Saving Time information. + +## 4.104.3 Time Offset Get Command + +This command is used to request the Time Zone Offset (TZO) and Daylight Savings Time (DST) parameters from a supporting node. + +[The Time Offset Report Command MUST be returned in response to this command.](04.104-time-command-class-version-2.md#41045-time-offset-report-command) + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TIME _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = TIME OFFSET GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.104.4 Time Offset Set Command + +This command is used to set Time Zone Offset (TZO) and Daylight Savings Time (DST) at the supporting node. + +This command MAY be ignored by a supporting node if it relies on another source to retrieve the TZO/DST information. This command SHOULD be ignored if it is not received at the highest granted security level. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TIME _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = TIME OFFSET SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sign TZO | | | Hour TZO | | | | | | | | | | | | | | | | | | | | | +| Minute TZO | | | | | | | | | | | | | | | | | | | | | | | | +| Sign Offset DST | | | Minute Offset DST | | | | | | | | | | | | | | | | | | | | | +| Month Start DST | | | | | | | | | | | | | | | | | | | | | | | | +| Day Start DST | | | | | | | | | | | | | | | | | | | | | | | | +| Hour Start DST | | | | | | | | | | | | | | | | | | | | | | | | +| Month End DST | | | | | | | | | | | | | | | | | | | | | | | | +| Day End DST | | | | | | | | | | | | | | | | | | | | | | | | +| Hour End DST | | | | | | | | | | | | | | | | | | | | | | | | + +Sign TZO (1 bit) + +This field is used to indicate the sign (plus or minus) to apply to the Hour TZO and Minute TZO fields. + +The value 0 MUST indicate the Plus sign (positive offset from UTC) The value 1 MUST indicate the Minus sign (negative offset from UTC) + +Hour TZO (7 bits) + +This field is used to indicate the number of hours that the originating time zone deviates from UTC. This field SHOULD be in the range 0..14. + +Minute TZO (7 bits) + +This field is used to indicate the number of minutes that the originating time zone deviates UTC. This field MUST be in the range 0..59. + +Sign Offset DST (1 bit) + +This field is used to indicate the sign (plus or minus) for the Minute Offset DST field to apply to the current time while in the Daylight Saving Time. + +The value 0 MUST indicate the Plus sign (positive offset from current time), The value 1 MUST indicate the Minus sign (negative offset from current time). + +Minute Offset DST (7 bits) + +This field MUST indicate the number of minutes by which the current time is to be adjusted when Daylight Saving Time starts. + +Month Start DST (8 bits) + +This field MUST indicate the month of the year when Daylight Saving Time starts. This field MUST be in the range 1..12 (representing respectively January...December). + +Day Start DST (8 bits) + +This field MUST indicate the day of the month when Daylight Saving Time starts. This field MUST be in the range 1..31. + +Hour Start DST (8 bits) + +This field MUST indicate the hour of the day when Daylight Saving Time starts. This field MUST be in the range 0..23. + +Month End DST (8 bits) + +This field MUST indicate the month of the year when Daylight Saving Time ends. This field MUST be in the range 1..12 (representing respectively January...December). + +Day End DST (8 bits) + +This field MUST indicate the day of the month when Daylight Saving Time ends. This field MUST be in the range 1..31 Hour End DST (8 bits) + +This field MUST indicate the hour of the day when Daylight Saving Time ends. This field MUST be in the range 0..23. + +## 4.104.5 Time Offset Report Command + +This command is used to advertise the Time Zone Offset (TZO) and Daylight Savings Time (DST) parameters. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TIME _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = TIME OFFSET REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sign TZO | | | Hour TZO | | | | | | | | | | | | | | | | | | | | | +| Minute TZO | | | | | | | | | | | | | | | | | | | | | | | | +| Sign Offset DST | | | Minute Offset DST | | | | | | | | | | | | | | | | | | | | | +| Month Start DST | | | | | | | | | | | | | | | | | | | | | | | | +| Day Start DST | | | | | | | | | | | | | | | | | | | | | | | | +| Hour Start DST | | | | | | | | | | | | | | | | | | | | | | | | +| Month End DST | | | | | | | | | | | | | | | | | | | | | | | | +| Day End DST | | | | | | | | | | | | | | | | | | | | | | | | +| Hour End DST | | | | | | | | | | | | | | | | | | | | | | | | + +[For fields’ description, refer to 4.104.4 Time Offset Set Command. A sending node MUST comply with fields’ description from 4.104.4 Time Offset Set Command.](04.104-time-command-class-version-2.md#41044-time-offset-set-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.105-time-parameters-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.105-time-parameters-command-class-version-1.md new file mode 100644 index 0000000..f708241 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.105-time-parameters-command-class-version-1.md @@ -0,0 +1,81 @@ + +# 4.105 Time Parameters Command Class, version 1 + +The Time Parameters Command Class is used to set date and time in a device hosting this facility. In case the clock is updated via an external source such as SAT, internet, Rugby/Frankfurt source, omit this command class. Time zone offset and daylight savings may be set in the Time Command Class if necessary. The data formats are based on the International Standard ISO 8601. + +## 4.105.1 Time Parameters Set Command + +This command is used to set current date and time in Universal Time (UTC). Be aware that the communication overhead may be significant in case routing is necessary. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TIME PARAMETERS _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = TIME PARAMETERS SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Month | | | | | | | | | | | | | | | | | | | | | | | | +| Day | | | | | | | | | | | | | | | | | | | | | | | | +| Hour UTC | | | | | | | | | | | | | | | | | | | | | | | | +| Minute UTC | | | | | | | | | | | | | | | | | | | | | | | | +| Second UTC | | | | | | | | | | | | | | | | | | | | | | | | + +Year (16 bits) + +Specify the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. + +Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December). + +Day (8 bits) + +Specify the day of the month between 01 and 31. + +Hour UTC (8 bits) + +Specify the number of complete hours that have passed since midnight (00..23) in UTC. + +Minute UTC (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00..59) in UTC. Minutes are measured in Universal Time (UTC). + +Second UTC (8 bits) + +Specify the number of complete seconds since the start of the minute (00..59) in UTC. Seconds are measured in Universal Time (UTC). + +## 4.105.2 Time Parameters Get Command + +This command is used to request date and time parameters. + +The Time Parameters Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TIME PARAMETERS _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = TIME PARAMETERS GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.105.3 Time Parameters Report Command + +This command is used to advertise date and time. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TIME PARAMETERS _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = TIME PARAMETERS REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Month | | | | | | | | | | | | | | | | | | | | | | | | +| Day | | | | | | | | | | | | | | | | | | | | | | | | +| Hour UTC | | | | | | | | | | | | | | | | | | | | | | | | +| Minute UTC | | | | | | | | | | | | | | | | | | | | | | | | +| Second UTC | | | | | | | | | | | | | | | | | | | | | | | | + +Refer to description under the Time Parameters Set Command. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.106-user-code-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.106-user-code-command-class-version-1.md new file mode 100644 index 0000000..3337d2b --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.106-user-code-command-class-version-1.md @@ -0,0 +1,134 @@ + +# 4.106 User Code Command Class, version 1 + +The User Code Command Class is used to manage User Codes in access control systems. + +## 4.106.1 Interoperability considerations + +A node supporting the Door Lock Command Class SHOULD reflect user code inputs in the door lock status when relevant. (e.g. when the door becomes unlocked by a User Code input, the Door Lock Mode is also updated to unlocked) + +This Command Class can be used in conjunction with Schedule Entry Lock Command Class in order to schedule access for users. + +A node receiving a User Code Get Command MUST advertise what User Code is set in the User Code Report Command. It has been found that some version 1 nodes wrongfully report obfuscated User Codes in the User Code Report (e.g. ‘******’). A controlling node SHOULD understand that a code has been set correctly but cannot be read back with such nodes. + +## 4.106.2 User Code Set Command + +This command is used to set a User Code at the receiving node. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS USER CODE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = USER CODE SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| User Identifier | | | | | | | | | | | | | | | | | | | | | | | | +| User ID Status | | | | | | | | | | | | | | | | | | | | | | | | +| User Code 1 | | | | | | | | | | | | | | | | | | | | | | | | +| ... | | | | | | | | | | | | | | | | | | | | | | | | +| User Code N | | | | | | | | | | | | | | | | | | | | | | | | + +User Identifier (8 bits) + +This field is used to specify the actual User Identifier. + +The implemented User Identifier values MUST be in a sequence starting from 1, i.e. a node supporting 10 User Identifiers MUST accept values in the range 1..10. + +A receiving node MAY ignore this field if it only supports one User Code. + +The value 0 MUST indicate that the receiving node MUST set the User Code and User Status for all available users. The value 0 SHOULD be used only with User ID Status set to 0x00. + +[If a non-existing User Identifier (higher than the advertised supported users number in the Users Number Report Command) is specified in this command, a receiving node MUST ignore the command](04.106-user-code-command-class-version-1.md#41066-users-number-report-command) User ID Status (8 bits) + +[The User ID Status field indicates the status of the User Identifier. This field MUST comply with Table 139.](04.106-user-code-command-class-version-1.md#41062-user-code-set-command) The User ID Status 0xFE SHOULD NOT be used in this command. + +Table 139, User Code Set::User ID Status encoding + +| | Value | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Available (not set) | | | +| 0x01 | | | Occupied | | | +| 0x02 | | | Reserved by administrator | | | +| 0xFE | | | Status not available | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +User Code (N bytes) + +This field is used to advertise the User Code to be set for the User Identifier. + +The length of this field MUST be between 4 and 10 bytes. The field’s length MUST be determined using the length of the frame. + +Each byte in this field MUST be a digit encoded with ASCII representation (from 0x30 to 0x39). A node receiving an invalid User Code MUST ignore the command. + +The User Code field MUST be set to 0x00000000 (4 bytes) when User ID Status is equal to 0x00. + +## 4.106.3 User Code Get Command + +This command is used to request the User Code of a specific User Identifier. + +[The User Code Report Command MUST be returned in response to this command.](04.106-user-code-command-class-version-1.md#41064-user-code-report-command) + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS USER CODE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = USER CODE GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| User Identifier | | | | | | | | | | | | | | | | | | | | | | | | + +User Identifier (8 bits) + +This field is used to specify the requested User Identifier. + +The value 0 MUST NOT be specified in the User Code Get Command. + +[If the specified User Identifier is not supported, a responding node SHOULD return a User Code Report Command with the User ID Status set to 0xFE “Status not available”.](04.106-user-code-command-class-version-1.md#41064-user-code-report-command) + +## 4.106.4 User Code Report Command + +This command is used to advertise a User Code and its current status. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS USER CODE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = USER CODE REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| User Identifier | | | | | | | | | | | | | | | | | | | | | | | | +| User ID Status | | | | | | | | | | | | | | | | | | | | | | | | +| User Code 1 | | | | | | | | | | | | | | | | | | | | | | | | +| ... | | | | | | | | | | | | | | | | | | | | | | | | +| User Code N | | | | | | | | | | | | | | | | | | | | | | | | + +[For fields’ description, refer to 4.106.2 User Code Set Command.](04.106-user-code-command-class-version-1.md#41062-user-code-set-command) + +## 4.106.5 Users Number Get Command + +This command is used to request the number of user codes supported by the receiving node. + +[The Users Number Report Command MUST be returned in response to this command.](04.106-user-code-command-class-version-1.md#41066-users-number-report-command) + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS USER CODE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = USERS NUMBER GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.106.6 Users Number Report Command + +This command is used to report the number of User Codes supported by the sending node. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS USER CODE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = USERS NUMBER REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Supported Users | | | | | | | | | | | | | | | | | | | | | | | | + +Supported Users (8 bits) + +This field is used to advertise the number of supported User Codes. + +This field MUST be set to the total amount of supported User Codes. The value ‘0’ MUST indicate that no User Code is supported by the node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.107-window-covering-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.107-window-covering-command-class-version-1.md new file mode 100644 index 0000000..2ad8535 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.107-window-covering-command-class-version-1.md @@ -0,0 +1,381 @@ + +# 4.107 Window Covering Command Class, version 1 + +The Window Covering Command Class is used to control window covering devices. + +[The Window Covering Command Class is an actuator control command class. Refer to 3.6.](../03-command-class-overview/03.06-actuator-control.md#36-actuator-control) + +## 4.107.1 Terminology + +A window covering device may be closed or open. The term closed represents the lowest light throughput, while open represents the highest light throughput. + +A window covering device may provide one or more properties such as up/down movement combined with for example slats angle control. + +Each of the available properties is advertised. A window covering device may offer precise control of the position of a property or it may offer a more limited movement control, where it is possible to start and stop movement in one of two directions but where the target position cannot be specified. + +If a window covering parameter is marked as position unknown, this indicates that the actual property can only be controlled via start and stop of movement. + +[The parameters controlling edges are identified as outlined in Table 140.](04.107-window-covering-command-class-version-1.md#41071-terminology) + +Table 140, Identification of edges + +| | Edge | | Description | Usage examples | +| --- | --- | --- | --- | --- | +| | Title | | | | +| out left _ | | | Outbound edge towards the left | | +| out right _ | | | Outbound edge towards the right | | +| in left _ | | | Inbound edge towards the left | | +| in right _ | | | Inbound edge towards the right | | +| in right left _ _ | | | Inbound edges controlled horizontally as one | | + +![figure p578](assets/img-fbc9bfea32.png) + +![figure p578](assets/img-91ca87aebd.png) + +![figure p578](assets/img-95385a795f.png) + +![figure p578](assets/img-234b052b98.png) + +![figure p578](assets/img-0d25374112.png) + +| | Edge | | Description | Usage examples | +| --- | --- | --- | --- | --- | +| | Title | | | | +| out bottom _ | | | Outbound edge towards the bottom | | +| out top _ | | | Outbound edge towards the top | | +| in bottom _ | | | Inbound edge towards the bottom | | +| in top _ | | | Inbound edge towards the top | | +| in top bottom _ _ | | | Inbound edges controlled vertically as one | | + +![figure p579](assets/img-f8baa4593b.png) + +![figure p579](assets/img-b897b5e07d.png) + +![figure p579](assets/img-ec65ec745a.png) + +![figure p579](assets/img-f5af822b72.png) + +![figure p579](assets/img-762e99613e.png) + +## 4.107.2 Compatibility considerations + +This Command Class replaces the following command classes: + + Basic Window Covering Command Class [OBSOLETED]  Move To Position Window Covering Command Class [OBSOLETED] + +### 4.107.2.1 Motor Control Device Class support + +A device supporting this command class SHOULD comply with the Motor Control Specific Device Class [B or C [1] for backwards compatibility with existing window covering control applications.](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +### 4.107.2.2 Multilevel Switch Command Class support + +A device supporting the Window Covering Command Class, Version 1 MUST support the Multilevel Switch Command Class, version 3 or newer. + +With the exception for slats angle control, the following mapping MUST apply: + +The Multilevel Switch value 0x00 MUST represent the least light, i.e. covering fully closed. The Multilevel Switch value 0x63 MUST represent the most light, i.e. covering fully opened. + +For slats angle control, the following mapping MUST apply: + +The Multilevel Switch value 0x00 MUST represent slats closed to the one side. The Multilevel Switch value 0x32 MUST represent slats open. The Multilevel Switch value 0x63 MUST represent slats closed to the other side. + +The purpose of supporting the Multilevel Switch Command Class is to allow a general purpose remote control to control window covering devices even though that remote control does not implement the Window Covering Command Class. By mapping the Multilevel Switch value 0 to the closed position, a multicasted or broadcasted Multilevel Switch Command that turns off light sources will also cause window coverings to close, thus reducing light from the outside. + +An implementation MAY allow the Multilevel Switch Command Class to control multiple features like up/down control as well as slats angle control. For instance, the Start Level Change command may start changing the slats angle towards the extreme angle and when reaching that extreme angle, it may start moving up or down. This way, multiple functions can be controlled from a general purpose remote control, although with less convenience than if a dedicated window covering remote control is used. + +### 4.107.2.3 Basic Command Class support + +A device supporting the Window Covering Command Class, version 1 MUST support the Basic Command Class, version 2 or newer. + +[The Basic Command Class MUST be mapped according to the actual Device Class, refer to [1].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +## 4.107.3 Window Covering Parameters + +Each distinct property of a window covering device is accessed via a dedicated parameter. + +Two variants are defined for many parameters: One allows full position control, including movement control. The other variant is limited to movement control. + +If a device implements full position control of a property, it MUST NOT implement the parameter limited to movement control. + +The term “Closed” represents the lowest light throughput, while “Open” represents the highest light throughput of the window covering. + +Table 141, Window Covering Parameter IDs + +| | Parm | | Description | | Value | | Encoding | +| --- | --- | --- | --- | --- | --- | --- | --- | +| | ID | | | | range | | | +| Outbound horizontal control | | | | | | | | +| 0 | | | out left: Outbound edge towards the left _ Right/Left movement (Position unknown) | NA | | | Level Change Up = Opening Level Change Down = Closing | +| 1 | | | out left: Outbound edge towards the left _ Right/Left position Parm 0 MUST NOT be supported | 0x00 – 0x63 | | | 0x00 = Closed 0x63 = Open | +| 2 | | | out right: Outbound edge towards the right _ Right/Left movement (Position unknown) | NA | | | Level Change Up = Opening Level Change Down = Closing | +| 3 | | | out right: Outbound edge towards the right _ Right/Left position Parm 2 MUST NOT be supported | 0x00 – 0x63 | | | 0x00 = Closed 0x63 = Open | + +| | Parm | | Description | | Value | | Encoding | +| --- | --- | --- | --- | --- | --- | --- | --- | +| | ID | | | | range | | | +| Inbound horizontal control | | | | | | | | +| 4 | | | in left: Inbound edge towards the left _ Right/Left movement (Position unknown) | NA | | | Level Change Down = Closing Level Change Up = Opening | +| 5 | | | in left: Inbound edge towards the left _ Right/Left position Parm 4 MUST NOT be supported | 0x00 – 0x63 | | | 0x00 = Closed 0x63 = Open | +| 6 | | | in right: Inbound edge towards the right _ Right/Left movement (Position unknown) | NA | | | Level Change Down = Closing Level Change Up = Opening | +| 7 | | | in right: Inbound edge towards the right _ Right/Left position Parm 0x18 MUST NOT be supported | 0x00 – 0x63 | | | 0x00 = Closed 0x63 = Open | +| 8 | | | in right left: _ _ Inbound edges controlled horizontally as one Right/Left movement (Position unknown) | NA | | | Level Change Down = Closing Level Change Up = Opening | +| 9 | | | in right left: _ _ Inbound edges controlled horizontally as one Right/Left position Parm 8 MUST NOT be supported | 0x00 – 0x63 | | | 0x00 = Closed 0x63 = Open | +| Angle control of vertical slats | | | | | | | | +| 10 | | | Vertical slats angle Right/Left movement (Position unknown) | NA | | | Level Change Down = Closing; to the right inside Level Change Up = Closing; to the left inside (Open is passed midway between the two closing positions) | +| 11 | | | Vertical slats angle Right/Left position Parm 10 MUST NOT be supported | 0x00 – 0x63 | | | 0x00 = Closed; to the right inside 0x32 = Open 0x63 = Closed; to the left inside | +| Outbound vertical control | | | | | | | | +| 12 | | | out bottom: Outbound edge towards the bottom _ Up/Down movement (Position unknown) | NA | | | Level Change Down = Closing Level Change Up = Opening | +| 13 | | | out bottom: Outbound edge towards the bottom _ Up/Down position Parm 12 MUST NOT be supported | 0x00 – 0x63 | | | 0x00 = Closed 0x63 = Open | + +| | Parm | | Description | | Value | | Encoding | +| --- | --- | --- | --- | --- | --- | --- | --- | +| | ID | | | | range | | | +| 14 | | | out top: Outbound edge towards the top _ Up/Down movement (Position unknown) | NA | | | Level Change Down = Closing Level Change Up = Opening | +| 15 | | | out top: Outbound edge towards the top _ Up/Down position Parm 14 MUST NOT be supported | 0x00 – 0x63 | | | 0x00 = Closed 0x63 = Open | +| Inbound vertical control | | | | | | | | +| 16 | | | in bottom: Inbound edge towards the bottom _ Up/Down movement (Position unknown) | NA | | | Level Change Down = Closing Level Change Up = Opening | +| 17 | | | in bottom: Inbound edge towards the bottom _ Up/Down position Parm 16 MUST NOT be supported | 0x00 – 0x63 | | | 0x00 = Closed 0x63 = Open | +| 18 | | | in top: Inbound edge towards the top _ Up/Down movement (Position unknown) | NA | | | Level Change Down = Closing Level Change Up = Opening | +| 19 | | | in top: Inbound edge towards the top _ Up/Down position Parm 18 MUST NOT be supported | 0x00 – 0x63 | | | 0x00 = Closed 0x63 = Open | +| 20 | | | in top bottom: _ _ Inbound edges controlled vertically as one Up/Down movement (Position unknown) | NA | | | Level Change Down = Closing Level Change Up = Opening | +| 21 | | | in top bottom: _ _ Inbound edges controlled vertically as one Up/Down position Parm 20 MUST NOT be supported | 0x00 – 0x63 | | | 0x00 = Closed 0x63 = Open | +| Angle control of horizontal slats | | | | | | | | +| 22 | | | Horizontal slats angle Up/Down movement (Position unknown) | NA | | | Level Change Down = Closing; up inside Level Change Up = Closing; down inside (Open is passed midway between the two closing positions) | +| 23 | | | Horizontal slats angle Up/Down position Parm 22 MUST NOT be supported | 0x00 – 0x63 | | | 0x00 = Closed; up inside 0x32 = Open 0x63 = Closed; down inside | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. A device MAY implement up to 100 hardware levels (including 0) for a given parameter. If a device implements less than 100 hardware levels, the hardware levels MUST be distributed uniformly over the entire range. The mapping of parameter values to hardware levels MUST be monotonous, i.e. a higher value MUST [be mapped to either the same or a higher hardware level. An example is found in Table 142.](04.107-window-covering-command-class-version-1.md#41073-window-covering-parameters) + +Table 142, Parameter value mapping to a limited number of hardware levels (example) + +| | Horizontal Slats Angle | | | Hardware level | | +| --- | --- | --- | --- | --- | --- | +| 0x00..0x13 | | | 100% Up inside | | | +| 0x14..0x27 | | | 50% Up inside | | | +| 0x28..0x3B | | | Open | | | +| 0x3C..0x4F | | | 50% Down inside | | | +| 0x50..0x63 | | | 100% Down inside | | | + +## 4.107.4 Window Covering Supported Get Command + +This command is used to request the supported properties of a device. + +[The Window Covering Supported Report Command MUST be returned in response to this command.](04.107-window-covering-command-class-version-1.md#41075-window-covering-supported-report-command) + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS WINDOW COVERING _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = WINDOW COVERING SUPPORTED GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.107.5 Window Covering Supported Report Command + +This command is used to advertise the supported properties of a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS WINDOW COVERING _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = WINDOW COVERING SUPPORTED REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Number of Parameter Mask bytes | | | | | | | | | | | | +| Parameter Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Mask N | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Number of Parameter Mask bytes (4 bits) + +The Number of Parameter Masks field MUST advertise the number of bytes carrying the Covering Parameter Mask field. + +The value MUST be in the range 1..15. + +Parameter Mask (N Bytes) + +The Parameter Mask field MUST advertise the Parameters supported by the device. + +The length of this field MUST be advertised by the Number of Parameter Masks field. + + Bit 0 in Bit Mask 1 indicates if Parameter ID 0 is supported  Bit 1 in Bit Mask 1 indicates if Parameter ID 1 is supported  … + +[For the definition of Parameter IDs, refer to Table 141.](04.107-window-covering-command-class-version-1.md#41073-window-covering-parameters) + +## 4.107.6 Window Covering Get Command + +This command is used to request the status of a specified Covering Parameter. + +The Window Covering Report command MUST be returned in response to this command. + +This command SHOULD NOT be used for parameters marked as (position unknown). A receiving node returning a Window Covering Report command for a parameter marked as (position unknown) MUST return the value 0x00 in the Current Value and Target Value fields while the Duration field value MUST be 0xFE. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS WINDOW COVERING _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = WINDOW COVERING GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter ID | | | | | | | | | | | | | | | | | | | | | | | | + +Parameter ID (8 bits) + +This field MUST specify the Parameter for which the status is requested. [For the definition of Parameter IDs, refer to Table 141.](04.107-window-covering-command-class-version-1.md#41073-window-covering-parameters) + +## 4.107.7 Window Covering Report Command + +This command is used to advertise the status of a Parameter. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS WINDOW COVERING _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = WINDOW COVERING REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter ID | | | | | | | | | | | | | | | | | | | | | | | | +| Current Value | | | | | | | | | | | | | | | | | | | | | | | | +| Target Value | | | | | | | | | | | | | | | | | | | | | | | | +| Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Parameter ID (8 bits) + +This field MUST advertise the Parameter covered by this report. [For the definition of Parameter IDs, refer to Table 141.](04.107-window-covering-command-class-version-1.md#41073-window-covering-parameters) + +Current Value (8 bits) + +The Current Value field MUST advertise the current value of the Parameter identified by the Parameter ID field. + +The Current Value SHOULD be identical to the Target Value when a transition has ended. + +[For the definition of valid parameter values, refer to Table 141.](04.107-window-covering-command-class-version-1.md#41073-window-covering-parameters) + +Target Value (8 bits) + +The Target Value field MUST advertise the target value of an ongoing transition or the most recent transition for the advertised Parameter ID. + +If a transition is initiated in an interactive fashion via a local user interface or via a Start Level Change command, the advertised Target Value MUST be 0x00 or 0x63, depending on the direction. + +[For the definition of valid parameter values, refer to Table 141.](04.107-window-covering-command-class-version-1.md#41073-window-covering-parameters) + +Duration (8 bits) + +The Duration field SHOULD advertise the time needed to reach the Target Value at the actual transition [rate. The encoding of the Duration field MUST be according to Table 8.](../03-command-class-overview/03.07-common-fields-and-encoding.md#373-duration-encoding) + +The Duration is defined as the interval from start of the transition until the Target Value is reached. + +## 4.107.8 Window Covering Set Command + +This command is used to control one or more parameters in a window covering device. + +A node receiving this command MUST ignore parameters marked as (position unknown). [Refer to Table 141.](04.107-window-covering-command-class-version-1.md#41073-window-covering-parameters) + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS WINDOW COVERING _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = WINDOW COVERING SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Parameter Count | | | | | | | | | | | | | | | +| | Parameter ID 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Value 1 | | | | | | | | | | | | | | | | | | | | | | | +| ... | | | | | | | | | | | | | | | | | | | | | | | | +| | Parameter ID N | | | | | | | | | | | | | | | | | | | | | | | +| | Value N | | | | | | | | | | | | | | | | | | | | | | | +| Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Parameter Count (5 bits) + +This field MUST specify the number of (Parameter ID, Value) datasets contained in the Window Covering Set command. + +Parameter ID (N bytes) + +This field MUST specify the Parameter to receive a new value. [For the definition of Parameter IDs, refer to Table 141.](04.107-window-covering-command-class-version-1.md#41073-window-covering-parameters) + +Value (N bytes) + +This field MUST specify the value of the Parameter identified by the Parameter ID field. [For the definition of valid parameter ID values, refer to Table 141.](04.107-window-covering-command-class-version-1.md#41073-window-covering-parameters) + +Duration (8 bits) + +The Duration field MUST specify the time that the transition should take from the current value to the new target value. A supporting device SHOULD respect the specified Duration value. + +[The encoding of the Duration field MUST be according to Table 7.](../03-command-class-overview/03.07-common-fields-and-encoding.md#373-duration-encoding) + +## 4.107.9 Window Covering Start Level Change Command + +This command is used to initiate a transition of one parameter to a new level. + +A receiving node MUST initiate the transition to a new value for the specified Parameter ID. + +A node receiving this command MUST accept all parameter IDs supported by the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS WINDOW COVERING _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = WINDOW COVERING START LEVEL CHANGE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Res | | | Up/ Down | | | Res | | | | | | | | | | | | | | | | | | +| Parameter ID | | | | | | | | | | | | | | | | | | | | | | | | +| Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Up/Down (1 bit) + +This field MUST specify the direction of the level change. + +If the Up/Down bit is set to 0 the level change MUST be increasing. If the Up/Down bit is set to 1 the level change MUST be decreasing. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Parameter ID (8 bits) + +This field MUST specify the Parameter to start a transition. [For the definition of Parameter IDs, refer to Table 141.](04.107-window-covering-command-class-version-1.md#41073-window-covering-parameters) + +Duration (8 bits) + +The level change rate MUST be calculated to match a level change from the minimum value to the maximum value during the time specified by the Duration field. A supporting device SHOULD respect the specified Duration value. + +[The encoding of the Duration field MUST be according to Table 7.](../03-command-class-overview/03.07-common-fields-and-encoding.md#373-duration-encoding) + +## 4.107.10 Window Covering Stop Level Change Command + +This command is used to stop an ongoing transition. + +A receiving node MUST stop the transition if the specified Parameter ID is currently in transition to a new value. A receiving node MUST NOT stop ongoing transitions for other Parameter IDs than the one specified. + +A node receiving this command MUST accept all parameter IDs supported by the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS WINDOW COVERING _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = WINDOW COVERING STOP LEVEL CHANGE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter ID | | | | | | | | | | | | | | | | | | | | | | | | + +Parameter ID (8 bits) + +This field MUST specify the parameter to stop a transition. [For the definition of Parameter IDs, refer to Table 141.](04.107-window-covering-command-class-version-1.md#41073-window-covering-parameters) APPENDIX A ASCII CODES + +The standard ASCII table defines 128 character codes (from 0 to 127), of which, the first 32 are control codes (non-printable), and the remaining 96 character codes are printable characters. The table below shows the hexadecimal values of the ASCII character codes, e.g. the ASCII code for the capital letter “A” is equal to 0x41: + +Table 143, The standard ASCII Table + +![figure p590](assets/img-bda7a771b4.jpeg) + +In addition to the 128 standard ASCII codes (the ones listed above ranging from 0 to 127), most systems have another 128 extra codes which form what is known as extended ASCII (with ranges from 128 to 255). The OEM Extended ASCII character set is included in all PC-compatible computers as the default character set when the system boots before loading any operating system and under MS-DOS. It includes some foreign signs, some marked characters and also pieces to draw simple panels. The table below shows the hexadecimal values of the OEM Extended ASCII character codes, e.g. the ASCII code for the capital letter “Æ” is equal to 0x92: Table 144, OEM Extended ASCII Table + +![figure p591](assets/img-031d09cc57.jpeg) + +Below are listed codes for players, radios etc. as an alternative to the OEM Extended ASCII codes. Undefined values MUST be ignored. + +Table 145, Players Table + +![figure p591](assets/img-9fde74cbd0.jpeg) + +REFERENCES + +[1] Sigma Designs, SDS10242, Software Design Spec., Z-Wave Device Class Specification. [2] Sigma Designs, SDS12657, Z-Wave Command Class Specification A-M. [3] Sigma Designs, SDS12652, Z-Wave Command Class Specification N-Z. [4] IETF RFC 4861, Neighbor Discovery for IP version 6 (IPv6), [http://tools.ietf.org/pdf/rfc4861.pdf](http://tools.ietf.org/pdf/rfc4861.pdf) [5] IETF RFC 3122, Extensions to IPv6 Neighbor Discovery for Inverse Discovery Specification, [http://tools.ietf.org/pdf/rfc3122.pdf](http://tools.ietf.org/pdf/rfc3122.pdf) [6] IETF RFC 2119, Key words for use in RFCs to Indicate Requirement Levels, [http://tools.ietf.org/pdf/rfc2119.pdf](http://tools.ietf.org/pdf/rfc2119.pdf) [7] IETF RFC 2460, Internet Protocol, Version 6 (IPv6) Specification, [http://tools.ietf.org/pdf/rfc2460.pdf](http://tools.ietf.org/pdf/rfc2460.pdf) [8] IETF RFC 4291, IP Version6 Addressing Architecture, [http://tools.ietf.org/pdf/rfc4291.pdf](http://tools.ietf.org/pdf/rfc4291.pdf) [9] Sigma Designs, SDS11846, Z-Wave Plus Role Types Specification. [10] Sigma Designs, SDS11847, Z-Wave Plus Device Types Specification. [11] Graphical UI elements, [http://en.wikipedia.org/wiki/Graphical_user_interface_elements](http://en.wikipedia.org/wiki/Graphical_user_interface_elements) [12] Sigma Designs, SDS13425. Z-Wave Plus Assigned Manufacturer IDs. [13] Sigma Designs, SDS13548, List of defined Z-Wave Command Classes [14] Sigma Designs, SDS13783, Z-Wave Transport-Encapsulation Command Class Specification [15] Sigma Designs, SDS13782, Z-Wave Management Command Class Specification [16] Sigma Designs, SDS13784, Z-Wave Network-Protocol Command Class Specification [17] Sigma Designs, SDS13812, Multilevel Sensor Command Class, list of assigned Multilevel Sensor types and scales [18] Sigma Designs, SDS13713, Notification Command Class, list of assigned Notifications [19] Sigma Designs, SDS13907, Simple AV Command Class, list of assigned AV Control codes diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.11-binary-switch-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.11-binary-switch-command-class-version-1.md new file mode 100644 index 0000000..20b8872 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.11-binary-switch-command-class-version-1.md @@ -0,0 +1,77 @@ + +# 4.11 Binary Switch Command Class, version 1 + +The Binary Switch Command Class is used to control the On/Off state of supporting nodes. [The Binary Switch Command Class is an actuator control Command Class. Refer to 3.6.](../03-command-class-overview/03.06-actuator-control.md#36-actuator-control) + +## 4.11.1 Binary Switch Set Command + +This command is used to set the On/Off state at the receiving node. A receiving node MAY apply a non-zero duration to the transition from one value to a new value. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH BINARY _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH BINARY SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Value | | | | | | | | | | | | | | | | | | | | | | | | + +Value (8 bits) + +This field is used to specify the On/Off state that the receiving node MUST assume. This field MUST be [encoded according to Table 19.](04.11-binary-switch-command-class-version-1.md#4111-binary-switch-set-command) + +Table 19, Binary Switch Set :: Value + +| | Value | | | Level | | | State | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 0 (0x00) | | | 0% | | | Off | | +| 1..99 (0x01..0x63) | | | 100% | | | On | | +| 255 (0xFF) | | | 100% | | | On | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +The above value mapping of the Binary Switch Command Class Value allows a controlling node to control a mixed group of Binary Switch and Multilevel Switch supporting nodes via Basic Set commands. Nodes supporting the Binary Switch Command Class turn On or Off while nodes supporting the Multilevel Switch Command Class are set at the specified value level. + +## 4.11.2 Binary Switch Get Command + +This command is used to request the current On/Off state from a node. + +The Binary Switch Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH BINARY _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH BINARY GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.11.3 Binary Switch Report Command + +This command is used to advertise the current On/Off state at the sending node. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH BINARY _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH BINARY REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Value | | | | | | | | | | | | | | | | | | | | | | | | + +Value (8 bits) + +This field is used to advertise the current On/Off state at the sending node. This field MUST be encoded [according to Table 20](04.11-binary-switch-command-class-version-1.md#4113-binary-switch-report-command) + +Table 20, Binary Switch Report :: Value + +| | Value | | | Level | | | State | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0 (0x00) | | | 0% | | | Off | | | +| 254 (0xFE) | | | Unknown | | | Unknown | | | +| 255 (0xFF) | | | 100% | | | On | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +This field SHOULD advertise the current value of the node’s hardware; also while in transition to a new value. + +A controlling node MUST NOT assume that this field’s value is identical to the value previously issued with a Binary Switch Set Command. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.12-binary-switch-command-class-version-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.12-binary-switch-command-class-version-2.md new file mode 100644 index 0000000..be5c38d --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.12-binary-switch-command-class-version-2.md @@ -0,0 +1,65 @@ + +# 4.12 Binary Switch Command Class, version 2 + +The Binary Switch Command Class is used to control the On/Off state of supporting nodes. [The Binary Switch Command Class is an actuator control Command Class. Refer to 3.6.](../03-command-class-overview/03.06-actuator-control.md#36-actuator-control) + +## 4.12.1 Compatibility considerations + +A node supporting Binary Switch Command Class, version 2 MUST support the Binary Switch Command Class, version 1. + +Commands not described in this version MUST remain unchanged from version 1. + +Version 2 adds duration and target value control and reporting. + +## 4.12.2 Binary Switch Set Command + +This command is used to set the binary state at the receiving node. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH BINARY _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH BINARY SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Target Value | | | | | | | | | | | | | | | | | | | | | | | | +| Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Target Value (8 bits) + +This field is used to specify the On/Off state that the receiving node MUST assume. This field MUST be [encoded according to Table 19.](04.11-binary-switch-command-class-version-1.md#4111-binary-switch-set-command) + +Duration (8 bits) + +This field is used to specify the duration that the transition from the current value to the Target Value SHOULD take. A supporting node SHOULD respect the specified duration value. + +[The encoding of the Duration value MUST be according to Table 7.](../03-command-class-overview/03.07-common-fields-and-encoding.md#373-duration-encoding) + +## 4.12.3 Binary Switch Report Command + +This command is used to advertise the current On/Off state at the sending node. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH BINARY _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH BINARY REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Current Value | | | | | | | | | | | | | | | | | | | | | | | | +| Target Value | | | | | | | | | | | | | | | | | | | | | | | | +| Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Current Value (8 bits) + +This field is used to advertise the current On/Off state at the sending node. This field MUST be encoded [according to Table 20](04.11-binary-switch-command-class-version-1.md#4113-binary-switch-report-command) + +The advertised Current Value MUST NOT be updated to the Target Value before the hardware actuator has actually reached the Target Value. + +Target Value (8 bits) + +This field MUST advertise the target value of an ongoing transition or the most recent transition. [This field MUST be encoded according to Table 20.](04.11-binary-switch-command-class-version-1.md#4113-binary-switch-report-command) + +Duration (8 bits) + +The duration field SHOULD advertise the duration of a transition from the Current Value to the Target Value. [The encoding of the Duration field MUST be according to Table 8.](../03-command-class-overview/03.07-common-fields-and-encoding.md#373-duration-encoding) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.13-binary-toggle-switch-command-class-version-1-obsoleted.md b/docs/specs/command-class-specification/04-command-class-definitions/04.13-binary-toggle-switch-command-class-version-1-obsoleted.md new file mode 100644 index 0000000..b11e14a --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.13-binary-toggle-switch-command-class-version-1-obsoleted.md @@ -0,0 +1,50 @@ + +# 4.13 Binary Toggle Switch Command Class, version 1 [OBSOLETED] + +THIS COMMAND CLASS HAS BEEN OBSOLETED + +A node MUST NOT implement this Command Class. New implementations MUST use the Binary Switch Command Class. + +The Binary Toggle Switch Command Class is used for toggle-style control of binary actuator devices. + +## 4.13.1 Binary Toggle Switch Set Command + +This command is used to toggle a device e.g. from on to off and from off to on. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH TOGGLE BINARY _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH TOGGLE BINARY SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.13.2 Binary Toggle Switch Get Command + +This command is used to request the state of the load controlled by the device. + +The Binary Toggle Switch Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH TOGGLE BINARY _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH TOGGLE BINARY GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.13.3 Binary Toggle Switch Report Command + +This command is used to advertise the value of a toggle switch. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH TOGGLE BINARY _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH TOGGLE BINARY REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Value | | | | | | | | | | | | | | | | | | | | | | | | + +Value (8 bits) + +The value MAY be 0x00 (off) or 0xFF (on). diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.14-climate-control-schedule-command-class-version-1-deprecated.md b/docs/specs/command-class-specification/04-command-class-definitions/04.14-climate-control-schedule-command-class-version-1-deprecated.md new file mode 100644 index 0000000..7128beb --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.14-climate-control-schedule-command-class-version-1-deprecated.md @@ -0,0 +1,234 @@ + +# 4.14 Climate Control Schedule Command Class, version 1 [DEPRECATED] + +THIS COMMAND CLASS HAS BEEN DEPRECATED + +A device MAY implement this command class, but it is RECOMMENDED that new implementations use the Schedule Command Class. If implementing this command class, it is RECOMMENDED that the Schedule Command Class is also implemented. + +The Climate Control Schedule Command Class allows devices to exchange schedules and overrides, which specify when to perform a setback on the setpoint. + +Note: The setpoint is the temperature a device will try to maintain. The setback is a deviation from the setpoint. When a setback is in use the device will apply the setback to the setpoint, resulting in a different temperature. When using schedules and overrides it is possible to define several setbacks occurring at specific times. + +Schedules are exchanged using the Schedule Commands. Overrides of schedules are exchanged using the Schedule Override Commands. Detection of updated schedules is done using the Schedule Changed Commands. + +The Climate Control Schedule uses the Schedule State type to define each setback. The Schedule State type has the following format: + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Schedule State | | | | | | | | | | | | | | | | | | | | | | | | + +Schedule State (8 bits) + +The values are as follows: + +| | Schedule State | | | | | Description | +| --- | --- | --- | --- | --- | --- | --- | +| | Hexadecimal | | | Decimal | | | +| 0x80 … 0xFF 0x00 0x01 … 0x78 | | | -128 … -1 0 1 … 120 | | | The setback in 1/10 degrees (Kelvin) Example: 0 = 0 degrees setback 1 = 0.1 degrees is added to the setpoint 2 = 0.2 degrees is added to the setpoint -1 = 0.1 degrees is subtracted from the setpoint -2 = 0.2 degrees is subtracted from the setpoint | +| 0x79 | | | 121 | | | Frost Protection | +| 0x7A | | | 122 | | | Energy Saving Mode | +| 0x7B – 0x7E | | | 123 – 126 | | | Reserved | +| 0x7F | | | 127 | | | Unused State | + +When converting between Celsius and Fahrenheit proper rounding MUST be applied with at least two decimals in the internal calculations of a device to avoid rounding errors. + +When displaying converted Fahrenheit values it is RECOMMENDED that the displayed value is rounded to nearest quarter of a degree. + +## 4.14.1 Schedule Set Command + +This command is used to set the climate control schedule in a device for a specific weekday. A climate control schedule defines when to use a setback on the setpoint in a device. A schedule can hold a maximum of 9 switchpoints. A switchpoint defines one setback from the current setpoint. + +The entire list of switchpoints in the Command MUST be ordered by time, ascending from 00:00 towards 23:59. Switchpoints which have a Schedule State set to “Unused” MUST be placed last. Duplicates MUST NOT be allowed for Switchpoints which have a Schedule State different from “Unused”. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CLIMATE CONTROL SCHEDULE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | Weekday | | | | | | | | | +| | Switchpoint 0 Byte 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Switchpoint 0 Byte 2 | | | | | | | | | | | | | | | | | | | | | | | +| | Switchpoint 0 Byte 3 | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Switchpoint 8 Byte 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Switchpoint 8 Byte 2 | | | | | | | | | | | | | | | | | | | | | | | +| | Switchpoint 8 Byte 3 | | | | | | | | | | | | | | | | | | | | | | | + +Weekday (3 bits) + +[This field MUST be encoded according to Table 21.](04.14-climate-control-schedule-command-class-version-1-deprecated.md#4141-schedule-set-command) + +Table 21, Climate Control Schedule Set::Weekday encoding + +| | Value | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 | | | Reserved Monday Tuesday Wednesday Thursday Friday Saturday Sunday | | | + +Switchpoint (9*24 bits) + +| | 7 | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Reserved | | | | | | | Hour | | | | | | | | | | | | | | | +| Reserved | | | | Minute | | | | | | | | | | | | | | | | | | +| Schedule State | | | | | | | | | | | | | | | | | | | | | | + +Hour (5 bits) + +This field is used to specify the hour of the of the actual switchpoint. This field MUST be in the range 0..23. + +Minute (6 bits) + +This field is used to specifiy the minute of the actual switchpoint. This field MUST be in the range 0..59. + +Schedule State (8 bits) + +[Schedule State uses the Schedule State type format, see section 4.14. If Schedule State has the value](04.14-climate-control-schedule-command-class-version-1-deprecated.md#414-climate-control-schedule-command-class-version-1-deprecated) of “Unused”, the Hour and Minute field MUST be ignored. Once a Schedule State of “Unused” is encountered, the parsing of switchpoints must stop. + +## 4.14.2 Schedule Get Command + +This command is used to request the climate control schedule in a device for a specific weekday. + +The Schedule Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CLIMATE CONTROL SCHEDULE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE GET _ | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | Weekday | | | | | | | | | + +[For fields’ description, refer to 4.14.1 Schedule Set Command](04.14-climate-control-schedule-command-class-version-1-deprecated.md#4141-schedule-set-command) + +## 4.14.3 Schedule Report Command + +This command is used to report the climate control schedule in a device for a specific weekday. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CLIMATE CONTROL SCHEDULE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | Weekday | | | | | | | | | +| | Switchpoint 0 Byte 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Switchpoint 0 Byte 2 | | | | | | | | | | | | | | | | | | | | | | | +| | Switchpoint 0 Byte 3 | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Switchpoint 8 Byte 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Switchpoint 8 Byte 2 | | | | | | | | | | | | | | | | | | | | | | | +| | Switchpoint 8 Byte 3 | | | | | | | | | | | | | | | | | | | | | | | + +[For fields’ description, refer to 4.14.1 Schedule Set Command](04.14-climate-control-schedule-command-class-version-1-deprecated.md#4141-schedule-set-command) + +## 4.14.4 Schedule Changed Get Command + +This command is used to check if the climate control schedule has changed. + +The Schedule Changed Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CLIMATE CONTROL SCHEDULE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE CHANGED GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.14.5 Schedule Changed Report Command + +This command is used to report if the climate control schedule has changed. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CLIMATE CONTROL SCHEDULE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE CHANGED REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| ChangeCounter | | | | | | | | | | | | | | | | | | | | | | | | + +ChangeCounter (8 bits) + +The ChangeCounter is a timestamp for a climate control schedule and it is kept in devices which exchange climate control schedules. + +One device holds a climate control schedule and other devices uses this climate control schedule. Whenever the climate control schedule changes, the device MUST update its ChangeCounter, and the other devices MUST regularly use the Schedule Changed Get Command on the device which holds the Climate Control Schedule to see if the ChangeCounter is different from last time – indicating a change in a climate control schedule. + +The possible values are: + +| | Value | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | The climate control schedule change mechanism is temporarily disabled by the override function. | | | +| 0x01..0xFF | | | The climate control schedule change mechanism is enabled. ChangeCounter is incremented by one every time climate control schedule changes. When ChangeCounter eventually reach 0xFF, the next increment MUST rollover to 0x01. | | | + +When a device is fresh and has no climate control schedule it MUST retrieve a climate control schedule using the Schedule Get Command and it MUST also use the Schedule Changed Get to get the first copy of the current ChangeCounter, thus avoiding getting the climate control schedule initially twice. + +When a device is awake after sleep mode it SHOULD use this Command to detect if the schedule has been changed. + +## 4.14.6 Schedule Override Set Command + +This command is used to set the override in a device. + +The purpose of an override is to inform a device to ignore its current climate control schedule and assume the setting provided by the Override Type and Override State fields. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CLIMATE CONTROL SCHEDULE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE OVERRIDE SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | Override Type | | | | | | +| Override State | | | | | | | | | | | | | | | | | | | | | | | | + +Override Type (2 bits) + +[This field MUST be encoded according to Table 22.](04.14-climate-control-schedule-command-class-version-1-deprecated.md#4146-schedule-override-set-command) + +Table 22, Climate Control Schedule Override Set::Override Type encoding + +| | Value | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 0x01 0x02 0x03 | | | No override Temporary override Permanent override Reserved | | | + +Note: The difference between a temporary and a permanent override is that a temporary override only overrides the current switchpoint in the climate control schedule. + +Both temporary and permanent overrides MAY be cancelled in the device, which receives the SCHEDULE_OVERRIDE_SET. This cancellation MUST be notified in an unsolicited SCHEDULE_OVERRIDE_REPORT as specified in the following sequence diagram: + +Controller Thermostat + +Figure 4, Sequence diagram for cancellation of a Schedule Override Set + +Override State (8 bits) + +[The Override State uses the Schedule State type format, see section 4.14](04.14-climate-control-schedule-command-class-version-1-deprecated.md#414-climate-control-schedule-command-class-version-1-deprecated) + +## 4.14.7 Schedule Override Get Command + +This command is used to request the override, currently in use in a device. + +The Schedule Override Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CLIMATE CONTROL SCHEDULE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE OVERRIDE GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.14.8 Schedule Override Report Command + +The Schedule Override Report Command is used to report the override, currently in use in a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CLIMATE CONTROL SCHEDULE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE OVERRIDE REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | Override Type | | | | | | +| Override State | | | | | | | | | | | | | | | | | | | | | | | | + +Override Type (2 bits) + +[This field MUST be encoded according to Table 22.](04.14-climate-control-schedule-command-class-version-1-deprecated.md#4146-schedule-override-set-command) + +Both temporary and permanent overrides MAY be cancelled in the device, which receives the SCHEDULE_OVERRIDE_SET. This cancellation MUST be notified in an unsolicited [SCHEDULE_OVERRIDE_REPORT as shown on figure in section 4.14.6](04.14-climate-control-schedule-command-class-version-1-deprecated.md#4146-schedule-override-set-command) + +Override State (8 bits) + +[The Override State uses the Schedule State type format, see section 4.14](04.14-climate-control-schedule-command-class-version-1-deprecated.md#414-climate-control-schedule-command-class-version-1-deprecated) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.15-central-scene-command-class-version-1-obsoleted.md b/docs/specs/command-class-specification/04-command-class-definitions/04.15-central-scene-command-class-version-1-obsoleted.md new file mode 100644 index 0000000..76f8351 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.15-central-scene-command-class-version-1-obsoleted.md @@ -0,0 +1,105 @@ + +# 4.15 Central Scene Command Class, version 1 [OBSOLETED] + +THIS COMMAND CLASS HAS BEEN OBSOLETED + +New implementations MUST support the Central Scene Command Class, version 3 or newer. + +The Central Scene Command Class is used to communicate central scene activations to a central controller using the lifeline concept. The central scene controller only need to configure lifeline association in relevant nodes before the home control application can take action in the central scene controller. The typical application contains up to 10-15 selected nodes creating a nice “out of the box” experience with minimum effort by the customer. A scene is typically activated via a push button on the device in question. + +The Central Scene Command Class can instruct the central scene controller to perform the relevant [actions as shown on Figure 5.](04.15-central-scene-command-class-version-1-obsoleted.md#415-central-scene-command-class-version-1-obsoleted) + +![Figure 5, Centralized feedback and control](assets/img-6ceb291c6e.png) + +Multiple sending nodes MAY advertise the same Scene number. Therefore, a receiving node MUST interpret the advertised Scene number in combination with the source NodeID of the sending node. + +For instance, {Node A, Scene 1} may trigger changes to another scene than {Node B, Scene 1} in the receiving node + +Notice that this configuration has a single point of failure in case the central scene controller is broken. The likelihood to experience the “popcorn effect” is increased because the central scene controller may be located far from the push button activated and therefore out of direct range with respect to devices to control. + +To compensate for single point of failure in case the central scene controller is broken the devices could do fallback to alternative association groups to control devices directly. These association groups are activated only if the device does not receive acknowledge from configured lifeline. This will ensure some basic level of light control in the house until the central scene controller is restored. Alternatively, a backup central scene controller could be added to the system to take over in case the first one fails. + +## 4.15.1 Central Scene Supported Get Command + +This command is used to request the maximum number of scenes that this device supports. + +The Central Scene Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CENTRAL SCENE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CENTRAL SCENE SUPPORTED GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.15.2 Central Scene Supported Report Command + +This command is used to report the maximum number of scenes that the requested device supports. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CENTRAL SCENE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CENTRAL SCENE SUPPORTED REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Supported Scenes | | | | | | | | | | | | | | | | | | | | | | | | + +Supported Scenes (8 bits) + +This field indicates the maximum number of scenes supported by the requested device. + +This field MUST advertise the number of available scenes. Scenes MUST be numbered in the range 1..[Supported Scenes]. + +A device MAY implement virtual buttons via two-button presses, touch screen swipes or other means. Virtual buttons MUST be numbered after physical push buttons or graphical button objects. + +The advertised number of Supported Scenes MUST cover physical push buttons, graphical button objects as well as virtual buttons. Therefore, the advertised number of Supported Scenes MAY be larger than the number of physical push buttons or graphical button objects. + +## 4.15.3 Central Scene Notification Command + +This command is used to report activated scene on device in question including how notification must be interpreted. + +In case a lifeline is configured in group #1 using Association Command Class, the device must use this lifeline for transmitting the Central Scene Notification Command. It is allowed to define other association groups handling Central Scene Notification Command and setup rules between the groups. However, lifeline has precedence over other groups handling Central Scene Notification Command in case lifeline is defined. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CENTRAL SCENE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CENTRAL SCENE NOTIFICATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sequence Number | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | Key Attributes | | | | | | | | | +| Scene Number | | | | | | | | | | | | | | | | | | | | | | | | + +Sequence Number (8 bits) + +The sequence number MUST be incremented each time a Central Scene Notification Command is issued. The receiving device uses the sequence number to ignore duplicates. + +Key Attributes (3 bits) + +[The key Attributes field specifies the state of the key. The field MUST be encoded according to Table 23](04.15-central-scene-command-class-version-1-obsoleted.md#4153-central-scene-notification-command) + +Table 23, Central Scene Notification :: Key Attributes + +| | Key Attribute | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Key Pressed | | | +| 0x01 | | | Key Released | | | +| 0x02 | | | Key Held Down | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +[Notifications carrying these Key Attributes MUST comply with Figure 6.](04.15-central-scene-command-class-version-1-obsoleted.md#4153-central-scene-notification-command) + +![Figure 6, Central Scene version 1 button press decoding and timer management](assets/img-1f27ee63d2.png) + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Scene Number (8 bits) + +The advertised number of Supported Scenes MUST cover physical push buttons, graphical button objects as well as virtual buttons. Therefore, the advertised number of Supported Scenes MAY be larger than the number of physical push buttons or graphical button objects. + +![Figure 7, Scene number mapping to button layout](assets/img-f586b8bafd.png) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.16-central-scene-command-class-version-2-obsoleted.md b/docs/specs/command-class-specification/04-command-class-definitions/04.16-central-scene-command-class-version-2-obsoleted.md new file mode 100644 index 0000000..4b4a625 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.16-central-scene-command-class-version-2-obsoleted.md @@ -0,0 +1,113 @@ + +# 4.16 Central Scene Command Class, version 2 [OBSOLETED] + +THIS COMMAND CLASS HAS BEEN OBSOLETED + +New implementations MUST support the Central Scene Command Class, version 3 or newer. + +The Central Scene Command Class is used to communicate central scene activations to a central controller using the lifeline concept. + +## 4.16.1 Compatibility considerations + +Central Scene Command Class version 2 is extended on the following areas: + + The Central Scene Supported Report Command is updated to advertise Key Attributes support for each scene.  Additional Key Attributes are defined. + +Commands and paragraphs not mentioned in this version remain unchanged from version 1. + +## 4.16.2 Central Scene Supported Report Command + +This command is used to report the maximum number of supported scenes and the Key Attributes supported for each scene. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CENTRAL SCENE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CENTRAL SCENE SUPPORTED REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Supported Scenes | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | Number of Bit Mask Bytes | | | | | | Identical | | | +| | Supported Key Attributes for Scene 1 – Byte 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Supported Key Attributes for Scene 1 – Byte N | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Supported Key Attributes for Scene M – Byte 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Supported Key Attributes for Scene M – Byte N | | | | | | | | | | | | | | | | | | | | | | | + +Fields not described below remain unchanged from version 1. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. Number of Bit Mask Bytes (2 bits) + +This field advertises the size of each “Supported Key Attributes” field measured in bytes. The value MUST be in the range 1..3. + +Identical (1 bit) + +This field indicates if all scenes are supporting the same Key Attributes: + +The value 1 MUST indicate that all scenes support the same set of Key Attributes. In this case, the field “Supported Key Attributes for Scene 1” MUST advertise the supported Key Attributes for all scenes + +The value 0 MUST indicate that scenes support different Key Attributes. In this case, Supported Key Attributes MUST be advertised for each individual scene. + +Supported Key Attributes (N bytes) + +This Bit Mask field advertises the attributes supported by the corresponding scene. The field MUST be [encoded according to Table 24.](04.16-central-scene-command-class-version-2-obsoleted.md#4162-central-scene-supported-report-command) + +Table 24: Central Scene Supported Report::Supported Key Attributes + +| | Byte:Bit | | | Supported Key Attributes | | +| --- | --- | --- | --- | --- | --- | +| 1:0 | | | Key Pressed 1 time | | | +| 1:1 | | | Key Released. | | | +| 1:2 | | | Key Held Down. | | | +| 1:3 | | | Key Pressed 2 times | | | +| 1:4 | | | Key Pressed 3 times | | | +| 1:5 | | | Key Pressed 4 times | | | +| 1:6 | | | Key Pressed 5 times | | | +| 1:7 | | | Reserved | | | + +If the Key Released attribute is supported, the Key Held Down attribute MUST also be supported. If the Key Held Down attribute is supported, the Key Released attribute MUST also be supported. + +## 4.16.3 Central Scene Notification Command + +This command is used to advertise one or more key events. + +If the device implements Z-Wave Plus Lifeline support is implemented, the device MUST send the Central Scene Notification Command to the actual Lifeline targets. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CENTRAL SCENE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Command = CENTRAL SCENE NOTIFICATION _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Sequence Number | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | Key Attributes | | | | | | | | +| Scene Number | | | | | | | | | | | | | | | | | | | | | | | + +Fields not described below remain unchanged from version 1. + +Key Attributes (3 bits) + +This field advertises one or more events detected by the key. The field MUST be encoded according to [Table 25](04.16-central-scene-command-class-version-2-obsoleted.md#4163-central-scene-notification-command) + +Table 25: Central Scene Notification::Key Attributes + +| | Key Attribute | | | Description | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | Key Pressed 1 time | | 1 | | | +| 0x01 | | | Key Released | | 1 | | | +| 0x02 | | | Key Held Down | | 1 | | | +| 0x03 | | | Key Pressed 2 times | | 2 | | | +| 0x04 | | | Key Pressed 3 times | | 2 | | | +| 0x05 | | | Key Pressed 4 times | | 2 | | | +| 0x06 | | | Key Pressed 5 times | | 2 | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +[Notification carrying these Key Attributes MUST comply with Figure 8.](04.16-central-scene-command-class-version-2-obsoleted.md#4163-central-scene-notification-command) + +![Figure 8, Central Scene button press decoding and timer management](assets/img-73381c079f.png) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.17-central-scene-command-class-version-3.md b/docs/specs/command-class-specification/04-command-class-definitions/04.17-central-scene-command-class-version-3.md new file mode 100644 index 0000000..efa5f89 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.17-central-scene-command-class-version-3.md @@ -0,0 +1,158 @@ + +# 4.17 Central Scene Command Class, version 3 + +The Central Scene Command Class, version 3 extends version 2 by adding a new mode for the transmission of Key Held Down notifications. This allows a node to send Key Held Down refreshes at a low rate for the duration of the key held down. + +The purpose of this new feature is to provide improved compatibility with FLiRS beaming and network routing. + +Central Scene Command Class, version 3 introduces three new commands to allow a controller to query and configure node capabilities. + + [Central Scene Configuration Set Command](04.17-central-scene-command-class-version-3.md#4172-central-scene-configuration-set-command)  [Central Scene Configuration Get Command](04.17-central-scene-command-class-version-3.md#4173-central-scene-configuration-get-command)  [Central Scene Configuration Report Command](04.17-central-scene-command-class-version-3.md#4174-central-scene-configuration-report-command) + +Central Scene Command Class, version 3 extends the following commands for a scene launching node to advertise its optional capabilities. + + [Central Scene Supported Report Command](04.17-central-scene-command-class-version-3.md#4176-central-scene-supported-report-command)  [Central Scene Notification Command](04.17-central-scene-command-class-version-3.md#4177-central-scene-notification-command) + +## 4.17.1 Compatibility considerations + +A scene controller SHOULD NOT try to detect multiple key presses from the reception of successive key press notifications in any single or multiple key attribute combination. FLiRS beaming, collisions or routing may add delays between messages and render the timing between notifications unreliable. + +Version 1 and version 2 required to send Key Held Down notifications commands every 200ms. It has been found that this requirement cannot be observed when the network is using FLiRS beaming or routing. Further, issuing the 200ms refreshes also degrades general network reliability and availability. + +Version 3 introduces the Slow Refresh Capability, which allows a node to send refreshes every [55 seconds instead of 200ms. For details about the Slow Refresh capability, refer to 4.17.7.](04.17-central-scene-command-class-version-3.md#4177-central-scene-notification-command) + +In order to ensure a functioning network, the Slow Refresh capability MUST be enabled by default after inclusion. + +When creating associations from a version 3 node, the node creating the association SHOULD enable the Slow Refresh capability in the node if the association destination does also support Central Scene Command Class, version 3. When using the version 3 Slow Refresh capability, the controller relies on the reception of a Key Up notification instead of the Key Held Down refreshes. The new mode still sends refreshes at a low rate, for the controller to detect if a node failed after sending a Held Down Key notification. This means that a version 2 controlling node may time out when receiving Key Held Down Notifications from a version 3 node. + +However, it has been found that there exist nodes supporting version 1 or version 2 which do not send Central Scene Notification refreshes every 200ms when the Key Held Down notification is issued. + +A controller SHOULD apply an adaptive approach based on the reception of the Key Released Notification. Initially, the controller SHOULD time out if not receiving any Key Held Down Notification refresh after 400ms and consider this to be a Key Up Notification. If, however, the controller subsequently receives a Key Released Notification, the controller SHOULD consider the sending node to be operating with the Slow Refresh capability enabled. + +### 4.17.1.1 Multi Channel considerations + +Multi Channel End Points SHOULD NOT support the Central Scene Command Class. + +## 4.17.2 Central Scene Configuration Set Command + +This command is used to configure the use of optional node capabilities for scene notifications. + +| | 7 | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CENTRAL SCENE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Command = CENTRAL SCENE CONFIGURATION SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Slow Refresh | | Reserved | | | | | | | | | | | | | | | | | | | | | + +Slow Refresh (1 bit) + +This flag is used to configure the use of the Slow Refresh capability. + +The value 1 MUST indicate that the scene launching node MUST use Slow Refresh. The value 0 MUST indicate that the scene launching node MUST NOT use Slow Refresh. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +## 4.17.3 Central Scene Configuration Get Command + +This command is used to query the configuration of optional node capabilities for scene notifications. + +The Central Scene Configuration Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CENTRAL SCENE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Command = CENTRAL SCENE CONFIGURATION GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | + +## 4.17.4 Central Scene Configuration Report Command + +This command is used to advertise the configuration of optional node capabilities for scene notifications. + +| | 7 | 6 | 5 | 4 | 3 | 2 | 1 | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CENTRAL SCENE _ _ _ | | | | | | | | | | | +| Command = CENTRAL SCENE CONFIGURATION REPORT _ _ _ | | | | | | | | | | | +| Slow Refresh | | Reserved | | | | | | | | | + +Slow Refresh (1 bit) + +This flag is used to advertise the use of the Slow Refresh capability. + +The value 1 MUST indicate that the scene launching node MUST use Slow Refresh. The value 0 MUST indicate that the scene launching node MUST NOT use Slow Refresh capability. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +## 4.17.5 Central Scene Supported Get Command + +This command is used to request the maximum number of scenes that this device supports. + +The Central Scene Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | 6 | 5 | 4 | 3 | 2 | 1 | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CENTRAL SCENE _ _ _ | | | | | | | | | | | +| Command = CENTRAL SCENE SUPPORTED GET _ _ _ | | | | | | | | | | | + +## 4.17.6 Central Scene Supported Report Command + +This command is used to report the maximum number of supported scenes and the Key Attributes supported for each scene. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CENTRAL SCENE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CENTRAL SCENE SUPPORTED REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Supported Scenes | | | | | | | | | | | | | | | | | | | | | | | | +| Slow Refresh Support | | | Reserved | | | | | | | | | | | | Number of Bit Mask Bytes | | | | | | Identical | | | +| | Supported Key Attributes for Scene 1 – Byte 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Supported Key Attributes for Scene 1 – Byte N | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Supported Key Attributes for Scene M – Byte 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Supported Key Attributes for Scene M – Byte N | | | | | | | | | | | | | | | | | | | | | | | + +All fields not described below are the same as in version 2. + +Slow Refresh Support (1 bit) + +This field indicates whether the node supports the Slow Refresh capability. + +The value 1 MUST indicate that the node supports the Slow Refresh capability. The value 0 MUST indicate that the node does not support the Slow Refresh capability. + +## 4.17.7 Central Scene Notification Command + +This command is used to advertise a key event. + +If the device implements Z-Wave Plus Lifeline support, the device MUST send the Central Scene Notification Command to the actual Lifeline targets. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CENTRAL SCENE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CENTRAL SCENE NOTIFICATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sequence Number | | | | | | | | | | | | | | | | | | | | | | | | +| Slow Refresh | | | Reserved | | | | | | | | | | | | Key Attribute | | | | | | | | | +| Scene Number | | | | | | | | | | | | | | | | | | | | | | | | + +All fields not described below are the same as in version 2. Slow Refresh (1 bit) + +This flag is used to advertise if the node is sending Key Held Down notifications at a slow rate. A sending node MUST always set this field according to the configured mode. A receiving node MUST ignore this field if the command is not carrying the Key Held Down key attribute. + +If the Slow Refresh field is 0: + + A new Key Held Down notification MUST be sent every 200ms until the key is released.  The Sequence Number field MUST be updated at each notification transmission.  If not receiving a new Key Held Down notification within 400ms, a controlling node SHOULD use [an adaptive timeout approach as described in 4.17.1.](04.17-central-scene-command-class-version-3.md#4171-compatibility-considerations) + +If the Slow Refresh field is 1: + + A new Key Held Down notification MUST be sent every 55 seconds until the key is released.  The Sequence Number field MUST be updated at each notification refresh.  If not receiving a new Key Held Down notification within 60 seconds after the most recent Key Held Down notification, a receiving node MUST respond as if it received a Key Release notification. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.18-clock-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.18-clock-command-class-version-1.md new file mode 100644 index 0000000..eacfb5c --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.18-clock-command-class-version-1.md @@ -0,0 +1,82 @@ + +# 4.18 Clock Command Class, version 1 + +The Clock Command Class is used to implement a simple clock functionality. + +## 4.18.1 Interoperability considerations + +A controlling node SHOULD configure the current time and weekday in a supporting node during node commissioning. + +It has been found that some version 1 nodes issue Clock Get Command to controllers in order to learn the current time and use the returned Clock Report Command as a Clock Set Command. A supporting node SHOULD NOT learn the current time with a Clock Get Command. + +A node SHOULD control the Time Command Class to read the current time from supporting nodes (time servers) or support the Clock Command Class and wait to be set the current time by a controlling node. + +A Z-Wave Plus node SHOULD issue a Clock Report Command via the Lifeline Association Group if they suspect to have inaccurate time and/or weekdays (e.g. after battery removal). A controlling node SHOULD compare the received time and weekday with its current time and set the time again at the supporting node if a deviation is observed (e.g. different weekday or more than a minute difference) + +## 4.18.2 Clock Set Command + +This command is used to set the current time in a supporting node. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CLOCK _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CLOCK SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Weekday | | | | | | | | | Hour | | | | | | | | | | | | | | | +| Minute | | | | | | | | | | | | | | | | | | | | | | | | + +Weekday (3 bits) + +This field is used to indicate the current weekday that the receiving node MUST assume. [This field MUST comply with Table 26](04.18-clock-command-class-version-1.md#4182-clock-set-command) Table 26, Clock Set Command::Weekday encoding + +| | Value | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Unused/unknown This value may be specified if the weekday is not used or not known | | | +| 0x01 | | | Monday | | | +| 0x02 | | | Tuesday | | | +| 0x03 | | | Wednesday | | | +| 0x04 | | | Thursday | | | +| 0x05 | | | Friday | | | +| 0x06 | | | Saturday | | | +| 0x07 | | | Sunday | | | + +Hour (5 bits) + +This field is used to indicate the hour of the current time that the receiving node MUST assume. This field MUST be in the range 0..23. + +Minute (8 bits) + +This field is used to indicate the minute of the current time that the receiving node MUST assume. This field MUST be in the range 0..59. + +A sending node knowing the current time with seconds precision SHOULD round its current time to the nearest minute when sending this command. + +## 4.18.3 Clock Get Command + +This command is used to request the current time set at a supporting node. + +[The Clock Report Command MUST be returned in response to this command.](04.18-clock-command-class-version-1.md#4184-clock-report-command) + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CLOCK _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CLOCK GET _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.18.4 Clock Report Command + +This command is used to advertise the current time set at the sending node. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CLOCK _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CLOCK REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Weekday | | | | | | | | | Hour | | | | | | | | | | | | | | | +| Minute | | | | | | | | | | | | | | | | | | | | | | | | + +[For fields’ description, refer to 4.18.2 Clock Set Command. A sending node MUST comply with fields’ description from 4.18.2 Clock Set Command](04.18-clock-command-class-version-1.md#4182-clock-set-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.19-color-switch-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.19-color-switch-command-class-version-1.md new file mode 100644 index 0000000..b9160d3 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.19-color-switch-command-class-version-1.md @@ -0,0 +1,218 @@ + +# 4.19 Color Switch Command Class, version 1 + +The Color Switch Command Class is used to control color capable devices. + +The Color Switch Command Class manipulates the color components of a device. Each color component is scaled by the brightness level previously set by a Multilevel Switch Set, Binary Switch Set or Basic Set Command. + +[The Color Switch Command Class is an actuator control command class. Refer to 3.6.](../03-command-class-overview/03.06-actuator-control.md#36-actuator-control) + +## 4.19.1 Compatibility considerations + +The Color Switch Command Class, version 1 was previously named the Color Control Command Class, version 1. The Color Switch Command Class, version 1 is binary compatible with the Color Control Command Class, version 1. + +### 4.19.1.1 Command Class dependencies + +Nodes supporting the Color Switch Command Class, version 1 MUST support one of the following command classes in order to control the color brightness: + + Multilevel Switch Command Class, version 2  Binary Switch Command Cass, version 2. + +## 4.19.2 Interoperability considerations + +The Color Switch Command Class MUST be treated as a separate Command Class. Basic and Binary/Multilevel Switch Command Class commands MUST NOT affect color component levels controlled by the Color Switch Command Class. The Color Switch Command Class commands MUST NOT affect the brightness level controlled by Basic or Binary/Multilevel Switch Command Classes. + +If the brightness level is requested via a Basic Get or Binary/Multilevel Switch Get command, the reported value MUST reflect the brightness level previously set via Basic or Multilevel Switch commands. If a color component is requested via the Color Switch Get command, the reported value MUST reflect the color component level previously set via Color Switch commands. + +An implementation MUST scale color component levels by the brightness level . Thus, to achieve a resulting light level of 100% for a given color component, the color component level must be set to 100% (via the Color Switch Command Class) and the brightness level must be set to 100% (via Basic or Multilevel Switch Command Class). + +A controlling device SHOULD specify the highest possible color component levels of a given color tone to achieve the highest light yield when scaled by the brightness level. The controlling device MAY however limit color component levels to achieve the same brightness for blended color tones as for pure colors. For this reason, a supporting device MUST NOT normalize color components manipulated by the Color Switch Command Class. Likewise, a supporting device implementing indexed colors should reduce its internal color component levels for blended colors to achieve the same brightness for all color tones. + +## 4.19.3 Color Switch Supported Get Command + +This command is used to request the supported color components of a device. + +The Color Switch Supported Report command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH COLOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH COLOR SUPPORTED GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.19.4 Color Switch Supported Report Command + +This command is used to report the supported color components of a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH COLOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH COLOR SUPPORTED REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Color Component Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Color Component Mask 2 | | | | | | | | | | | | | | | | | | | | | | | | + +Color Component Mask (variable length) + +The Color Component Mask field MUST advertise the color components supported by the device. + + Bit 0 in Bit Mask 1 indicates if color component 0 is supported  Bit 1 in Bit Mask 1 indicates if color component 1 is supported  … + +[For the definition of Color Component IDs, refer to section 4.19.7.](04.19-color-switch-command-class-version-1.md#4197-color-switch-set-command) + +## 4.19.5 Color Switch Get Command + +This command is used to request the status of a specified color component. + +The Color Switch Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH COLOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH COLOR GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Color Component ID | | | | | | | | | | | | | | | | | | | | | | | | + +Color Component ID (8 bits) + +This field MUST specify the color component for which the status is requested. + +[For the definition of Color Component IDs, refer to section 4.19.7.](04.19-color-switch-command-class-version-1.md#4197-color-switch-set-command) + +## 4.19.6 Color Switch Report Command + +This command is used to advertise the status of a color component. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH COLOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH COLOR REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Color Component ID | | | | | | | | | | | | | | | | | | | | | | | | +| Value | | | | | | | | | | | | | | | | | | | | | | | | + +Color Component ID (8 bits) + +This field MUST advertise the color component covered by this report. + +[For the definition of Color Component IDs, refer to section 4.19.7.](04.19-color-switch-command-class-version-1.md#4197-color-switch-set-command) + +Value (8 bits) + +The Value field MUST advertise the value of the color component identified by the Color Component ID. + +The Value field SHOULD advertise the current value of the device hardware; also while in transition to a new target value. + +A controlling device MUST NOT assume that the Value is identical to a value previously issued with a Set command; not even when a transition has ended. + +## 4.19.7 Color Switch Set Command + +This command is used to control one or more color components in a device. + +[Color component levels MUST be scaled by the brightness level. Refer to 4.19.2.](04.19-color-switch-command-class-version-1.md#4192-interoperability-considerations) + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH COLOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH COLOR SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Color Component Count | | | | | | | | | | | | | | | +| | Color Component ID 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Value 1 | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Color Component ID N | | | | | | | | | | | | | | | | | | | | | | | +| | Value N | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Color Component Count (5 bits) + +This field MUST specify the number of (Color Component ID, Value) datasets contained in the Color Switch Set command. + +Color Component ID (8 bits) + +[This field MUST specify the color component to receive a new value. Refer to Table 27.](04.19-color-switch-command-class-version-1.md#4197-color-switch-set-command) + +Table 27, Color Switch Component IDs + +| | Component ID | | | Label | | | Value | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0 | | | Warm White | | | 0x00 – 0xFF: 0 – 100% | | | +| 1 | | | Cold White | | | 0x00: - 0xFF: 0 – 100% | | | +| 2 | | | Red | | | 0x00 – 0xFF: 0 – 100% | | | +| 3 | | | Green | | | 0x00 – 0xFF: 0 – 100% | | | +| 4 | | | Blue | | | 0x00 – 0xFF: 0 – 100% | | | +| 5 | | | Amber (for 6ch Color mixing) | | | 0x00 – 0xFF: 0 – 100% | | | +| 6 | | | Cyan (for 6ch Color mixing) | | | 0x00 – 0xFF: 0 – 100% | | | +| 7 | | | Purple (for 6ch Color mixing) | | | 0x00 – 0xFF: 0 – 100% | | | +| 8 | | | Indexed Color | | | 0x00 – 0xFF: Color Index 0-255 | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. Value (8 bits) + +This field MUST specify the value of the color component identified by the Color Component ID field. + +Unlike other actuator control command classes, the Value used by the Color Switch Command Class spans the entire range from 0x00 to 0xFF. Thus, except for the Indexed Color, the value 0x00 MUST represent 0% and 0xFF MUST represent 100% of the actual color component. + +## 4.19.8 Color Switch Start Level Change Command + +This command is used to initiate a transition of one color component to a new level. + +A receiving device MUST initiate the transition to a new value for the specified Color Component ID. + +The device MAY apply a non-zero duration to the transition from one value to a new value. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH COLOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH COLOR START LEVEL CHANGE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | Up/ Down | | | Ignore Start Level | | | Reserved | | | | | | | | | | | | | | | +| Color Component ID | | | | | | | | | | | | | | | | | | | | | | | | +| Start Level | | | | | | | | | | | | | | | | | | | | | | | | + +Up/Down (1 bit) + +This field MUST specify the direction of the level change. + +If the Up/Down bit is set to 0 the level change MUST be increasing. If the Up/Down bit is set to 1 the level change MUST be decreasing. + +Ignore Start Level (1 bit) + +A receiving device SHOULD respect the Start Level if the Ignore Start Level bit is 0. A receiving device MUST ignore the Start Level if the Ignore Start Level bit is 1. + +A controlling device SHOULD set the Ignore Start Level bit to 1. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Color Component ID (8 bits) + +This field MUST specify the color component to start a transition. + +[For the definition of Color Component IDs, refer to section 4.19.7.](04.19-color-switch-command-class-version-1.md#4197-color-switch-set-command) Start Level (8 bits) + +The Start Level field MUST specify the initial value of the level change. + +## 4.19.9 Color Switch Stop Level Change Command + +[This command is used to stop an ongoing transition initiated by a Color Switch Start Level Change Command.](04.19-color-switch-command-class-version-1.md#4198-color-switch-start-level-change-command) + +A receiving device MUST stop the transition if the specified Color Component ID is currently in transition to a new value. A receiving device MUST NOT stop ongoing transitions for other Color Component IDs than the one specified. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH COLOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH COLOR STOP LEVEL CHANGE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Color Component ID | | | | | | | | | | | | | | | | | | | | | | | | + +Color Component ID (8 bits) + +This field MUST specify the color component to stop a transition. + +[For the definition of Color Component IDs, refer to section 4.19.7.](04.19-color-switch-command-class-version-1.md#4197-color-switch-set-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.20-color-switch-command-class-version-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.20-color-switch-command-class-version-2.md new file mode 100644 index 0000000..9827b21 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.20-color-switch-command-class-version-2.md @@ -0,0 +1,76 @@ + +# 4.20 Color Switch Command Class, version 2 + +The Color Switch Command Class, version 2 is used to control color capable devices. + +[The Color Switch Command Class is an actuator control command class. Refer to 3.6.](../03-command-class-overview/03.06-actuator-control.md#36-actuator-control) + +## 4.20.1 Compatibility considerations + +A device supporting Color Switch Command Class, version 2 MUST support Color Switch Command Class, version 1. + +Version 2 adds a duration parameter to the Color Switch Set Command. + +Commands not described in this version remain unchanged from version 1. + +### 4.20.1.1 Command Class dependencies + +Nodes supporting the Color Switch Command Class, version 2 MUST support one of the following command classes in order to control the color brightness: + + Multilevel Switch Command Class, version 2  Binary Switch Command Cass, version 2. + +## 4.20.2 Interoperability considerations + +[Refer to 4.19.2.](04.19-color-switch-command-class-version-1.md#4192-interoperability-considerations) + +## 4.20.3 Color Switch Set Command + +This command is used to control one or more color components in a device. + +[Color component levels MUST be scaled by the brightness level. Refer to 4.19.2.](04.19-color-switch-command-class-version-1.md#4192-interoperability-considerations) + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH COLOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH COLOR SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Color Component Count | | | | | | | | | | | | | | | +| | Color Component ID 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Value 1 | | | | | | | | | | | | | | | | | | | | | | | +| ... | | | | | | | | | | | | | | | | | | | | | | | | +| | Color Component ID N | | | | | | | | | | | | | | | | | | | | | | | +| | Value N | | | | | | | | | | | | | | | | | | | | | | | +| Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Color Component Count (5 bits) + +This field MUST specify the number of (Color Component ID, Value) datasets contained in the Color Switch Set command. + +Color Component ID (8 bits) + +This field MUST specify the color component to receive a new value. + +[For the definition of Color Component IDs, refer to section 4.19.7.](04.19-color-switch-command-class-version-1.md#4197-color-switch-set-command) + +Value (8 bits) + +This field MUST specify the value of the color component identified by the Component ID field. + +[Refer to section Table 27.](04.19-color-switch-command-class-version-1.md#4197-color-switch-set-command) + +Duration (8 bits) + +The Duration field MUST specify the time that the transition should take from the current value to the new target value. A supporting device SHOULD respect the specified Duration value. + +[The encoding of the Duration field MUST be according to Table 7.](../03-command-class-overview/03.07-common-fields-and-encoding.md#373-duration-encoding) + +The factory default duration SHOULD be the same as the duration used for the Color Switch Set command, version 1. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.21-color-switch-command-class-version-3.md b/docs/specs/command-class-specification/04-command-class-definitions/04.21-color-switch-command-class-version-3.md new file mode 100644 index 0000000..b2f86cb --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.21-color-switch-command-class-version-3.md @@ -0,0 +1,114 @@ + +# 4.21 Color Switch Command Class, version 3 + +The Color Switch Command Class is used to control color capable devices. + +The Color Switch Command Class manipulates the color components of a device. Each color component is scaled by the brightness level previously set by a Multilevel Switch Set or Basic Set command. + +[The Color Switch Command Class is an actuator control command class. Refer to 3.6.](../03-command-class-overview/03.06-actuator-control.md#36-actuator-control) + +## 4.21.1 Compatibility considerations + +A node supporting Color Switch Command Class, version 3 MUST support the Color Switch Command Class, version 2. + +Version 3 adds duration and target value reporting to the Color Switch Report Command and adds duration control to the Color Switch Start Level Change Command. + +Commands not described in this version remain unchanged from version 2. + +A node receiving a version 1 Color Switch Set command MAY apply a factory default duration to the transition. + +### 4.21.1.1 Command Class dependencies + +Nodes supporting the Color Switch Command Class, version 3 MUST support one of the following Command Classes in order to control the color brightness: + + Multilevel Switch Command Class, version 4  Binary Switch Command Cass, version 2. + +## 4.21.2 Interoperability considerations + +[Refer to 4.19.2](04.19-color-switch-command-class-version-1.md#4192-interoperability-considerations) + +## 4.21.3 Color Switch Report Command + +This command is used to advertise the status of a color component. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH COLOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH COLOR REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Color Component ID | | | | | | | | | | | | | | | | | | | | | | | | +| Current Value | | | | | | | | | | | | | | | | | | | | | | | | +| Target Value | | | | | | | | | | | | | | | | | | | | | | | | +| Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Color Component ID (8 bits) + +This field MUST advertise the color component covered by this report. + +Current Value (8 bits) + +The Current Value field MUST advertise the current value of the color component identified by the Color Component ID. + +Refer to the Color Switch Set command for valid values. + +The Current Value SHOULD be identical to the Target Value when a transition has ended. + +Target Value (8 bits) + +The Target Value field MUST advertise the target value of an ongoing transition or the most recent transition for the advertised Color Component ID. + +Refer to the Color Switch Set command for valid values. + +If a transition is initiated in an interactive fashion via a local user interface or via a Start Level Change command, the advertised Target Value MUST be 0x00 or 0xFF, depending on the direction. + +The Current Value SHOULD be identical to the Target Value when a transition has ended. + +Duration (8 bits) + +The Duration field SHOULD advertise the time needed to reach the Target Value at the actual transition [rate. The encoding of the Duration field MUST be according to Table 8.](../03-command-class-overview/03.07-common-fields-and-encoding.md#373-duration-encoding) + +## 4.21.4 Color Switch Start Level Change Command + +This command is used to initiate a transition of one color component to a new value. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH COLOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH COLOR START LEVEL CHANGE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Res | | | Up/ Down | | | Ignore Start Level | | | Reserved | | | | | | | | | | | | | | | +| Color Component ID | | | | | | | | | | | | | | | | | | | | | | | | +| Start Level | | | | | | | | | | | | | | | | | | | | | | | | +| Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Up/Down (1 bit) + +This field MUST specify the direction of the level change. + +If the Up/Down bit is set to 0 the level change MUST be increasing. If the Up/Down bit is set to 1 the level change MUST be decreasing. Ignore Start Level (1 bit) + +A receiving device SHOULD respect the Start Level if the Ignore Start Level bit is 0. A receiving device MUST ignore the Start Level if the Ignore Start Level bit is 1. + +A controlling device SHOULD set the Ignore Start Level bit to 1. + +Res + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Color Component ID (8 bits) + +Refer to Color Switch Set command. + +Start Level (8 bits) + +The Start Level field MUST specify the initial value of the level change. + +Duration (8 bits) + +The level change rate MUST be calculated to match a level change from 0x00 to 0xFF during the time specified by the Duration field. A supporting device SHOULD respect the specified Duration value. + +[For encoding of the Duration value, refer to the Color Switch Set Command.](04.20-color-switch-command-class-version-2.md#4203-color-switch-set-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.22-configuration-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.22-configuration-command-class-version-1.md new file mode 100644 index 0000000..6ab6243 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.22-configuration-command-class-version-1.md @@ -0,0 +1,118 @@ + +# 4.22 Configuration Command Class, version 1 + +The Configuration Command Class allows product specific configuration parameters to be changed. One example could be the default dimming rate of a light dimmer. + +Configuration parameters MUST be specified in the product documentation. Configuration parameters accessed via this command class MUST NOT replace similar commands provided by other existing Command Classes. + +A device MUST be able to operate with default factory configuration parameter values. + +It is RECOMMENDED that configuration parameters can be manipulated via a local user interface. It is RECOMMENDED that default factory configuration parameter values can be restored via a local user interface. + +## 4.22.1 Compatibility considerations + +### 4.22.1.1 “Default” flag + +Earlier text revisions of the Configuration Command Class, versions 1-3 presented conflicting interpretations of the default field. Controllers should be aware that nodes with version 3 or less MAY reset all configuration parameters to default when receiving a Configuration Set or Configuration Bulk Set Command with the Default bit set to 1. + +A controller SHOULD probe a node in order to discover what behavior it implements. The following steps are RECOMMENDED: + + If the device is version 1- 2, scan the node for available configuration parameters. Else discover the available parameters thanks to the Configuration Properties Get Command.  Determine how the default bit works if the node implements 2 or more parameters + +Step 1: + + One at a time, issue a Configuration Set for a parameter number, and check whether the value can be read back. Try each parameter for 1, 2 and 4 bytes sizes.  Store the discovered parameter list for future use. + +Step 2: + + Choose 2 parameters and issue a Configuration Set with the default bit set to 1 for each parameter.  Read back both parameters value with a Configuration Get.  Try to modify both parameters to non-default values (it is recommended to try the default value ± 1)  Send a Configuration Set for one of parameters with the default bit set to 1.  Read back both parameters and check whether one or both returned to the default value + +## 4.22.2 Configuration Set Command + +The Configuration Set Command is used to set the value of a configuration parameter. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONFIGURATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CONFIGURATION SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number | | | | | | | | | | | | | | | | | | | | | | | | +| Default | | | Reserved | | | | | | | | | | | | Size | | | | | | | | | +| Configuration Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Configuration Value N | | | | | | | | | | | | | | | | | | | | | | | | + +Parameter Number (8 bits) + +This field is used to specify the actual configuration parameter. Parameter Numbers MAY be product specific. Parameter Numbers SHOULD be assigned in a sequence starting from 1. + +Default (1 bit) + +This field is used to specify if the default value is to be restored for the specified configuration parameter. + +The value 1 MUST indicate that default factory settings must be restored for the specified Parameter Number. In this case, the Configuration Value field MUST be ignored and the receiving node MUST reset the specified parameter and SHOULD NOT reset any other parameters. + +The value 0 MUST indicate that the specified Parameter Number must assume the value specified by the Configuration Value field. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Size (3 bits) + +This field is used to specify the size of the actual parameter. The advertised size of a given parameter CC:0070.01.04.11.005 [MUST always be the same. The value of this field MUST comply with Table 28.](04.22-configuration-command-class-version-1.md#4222-configuration-set-command) + +Table 28, Configuration Set::Size encoding + +| | Size | | | Size of Value field | | +| --- | --- | --- | --- | --- | --- | +| 1 | | | 8 bit | | | +| 2 | | | 16 bit | | | +| 4 | | | 32 bit | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. Configuration Value (N bytes) + +This field carries the value to be assigned. The size of the field MUST comply with the size advertised by the Size field. + +[The field MUST carry a signed value. The binary encoding of the signed value MUST comply with Table 10. The field Value 1 MUST be the most significant byte.](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) + +## 4.22.3 Configuration Get Command + +This command is used to query the value of a configuration parameter. + +The Configuration Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONFIGURATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CONFIGURATION GET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number | | | | | | | | | | | | | | | | | | | | | | | | + +Parameter Number (8 bits) + +This field is used to specify the requested configuration parameter. Parameter Numbers MAY be product specific. Parameter Numbers SHOULD be assigned in a sequence starting from 1. + +A node receiving this command for an unsupported parameter SHOULD return a Report advertising the value of the first available parameter in the node. + +## 4.22.4 Configuration Report Command + +This command is used to advertise the actual value of the advertised parameter. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONFIGURATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CONFIGURATION REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | Size | | | | | | | | | +| Configuration Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| .. | | | | | | | | | | | | | | | | | | | | | | | | +| Configuration Value N | | | | | | | | | | | | | | | | | | | | | | | | + +Refer to the Configuration Set Command for parameter details. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.23-configuration-command-class-version-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.23-configuration-command-class-version-2.md new file mode 100644 index 0000000..e3952a4 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.23-configuration-command-class-version-2.md @@ -0,0 +1,237 @@ + +# 4.23 Configuration Command Class, version 2 + +The Configuration Command Class allows product specific configuration parameters to be changed. One example could be the default dimming rate of a light dimmer. + +Configuration parameters MUST be specified in the product documentation. Configuration parameters accessed via this command class MUST NOT replace similar commands provided by other existing Command Classes. + +A device MUST be able to operate with default factory configuration parameter values. + +It is RECOMMENDED that configuration parameters can be manipulated via a local user interface. It is RECOMMENDED that default factory configuration parameter values can be restored via a local user interface. + +## 4.23.1 Compatibility considerations + +Configuration Command Class, version 2 extends the addressing space to 65.535 product specific configuration parameters. Further, Configuration Command Class, version 2 makes it possible to set multiple configuration parameters with one Command. + +A device supporting Configuration Command Class, version 2 MUST support Configuration Command Class, version 1. + +### 4.23.1.1 “Default” flag + +[Refer to 4.22.1.1](04.22-configuration-command-class-version-1.md#42211-default-flag) + +## 4.23.2 Interoperability considerations + +Configuration Command Class, version 2 is backwards compatible with Configuration Command Class, version 1. + +Configuration Command Class, version 2 does not extend any existing commands of Configuration Command Class, version 1. The 255 parameters that can be addressed by the Configuration Set Command MUST be identical to the first 255 parameters that can be addressed by the (version 2) Configuration Bulk Set Command. + +## 4.23.3 Configuration Set Command + +This command is used to set the value of a configuration parameter. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONFIGURATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CONFIGURATION SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number | | | | | | | | | | | | | | | | | | | | | | | | +| Default | | | Reserved | | | | | | | | | | | | Size | | | | | | | | | +| Configuration Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Configuration Value N | | | | | | | | | | | | | | | | | | | | | | | | + +Parameter Number (8 bits) + +This field is used to specify the actual configuration parameter. Parameter Numbers MAY be product specific. Parameter Numbers SHOULD be assigned in a sequence starting from 1. + +Default (1 bit) + +This field is used to specify if the default value is to be restored for the specified configuration parameter. + +The value 1 MUST indicate that default factory settings must be restored for the specified Parameter Number. In this case, the Configuration Value field MUST be ignored and the receiving node MUST reset the specified parameter and SHOULD NOT reset any other parameters. + +The value 0 MUST indicate that the specified Parameter Number must assume the value specified by the Configuration Value field. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Size (3 bits) + +This field is used to specify the size of the actual parameter. The advertised size of a given parameter [MUST always be the same. The value of this field MUST comply with Table 28.](04.22-configuration-command-class-version-1.md#4222-configuration-set-command) + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Configuration Value (N bytes) + +This field carries the value to be assigned. The size of the field MUST comply with the size advertised by the Size field. + +[The field MUST carry a signed value. The binary encoding of the signed value MUST comply with Table 10. The field Value 1 MUST be the most significant byte.](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) + +## 4.23.4 Configuration Bulk Set Command + +This command is used to set the value of one or more configuration parameters. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONFIGURATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CONFIGURATION BULK SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Offset 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Offset 2 (LSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Parameters | | | | | | | | | | | | | | | | | | | | | | | | +| Default | | | Hand- shake | | | Reserved | | | | | | | | | Size | | | | | | | | | +| | Parameter 1 – Configuration Value 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Parameter 1 – Configuration Value N (LSB) | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Parameter M – Configuration Value 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Parameter M – Configuration Value N (LSB) | | | | | | | | | | | | | | | | | | | | | | | + +Parameter Offset (16 bits) + +This field is used to specify the first parameter in a range of one or more parameters. The first byte CC:0070.02.07.11.001 MUST carry the most significant byte of the 16 bit value. + +Number of Parameters (8 bits) + +This field is used to specify the number (M) of configuration parameters contained in this command. + +The value of this field MUST be in the range 1..255. + +The advertised parameters MUST be in a consecutive range. For example, Parameter Offset set to 4 and Number of Parameters set to 3 MUST represent parameters number 4, 5 and 6. + +A receiving node MUST ignore values for non-existing parameters + +Default (1 bit) + +This field is used to specify if the default value is to be restored for the specified configuration parameters. + +The value 1 MUST indicate that default factory settings must be restored for the Parameter Numbers defined by the Parameter Offset and Number of Parameters fields. In this case, the Configuration Value field MUST be ignored and the receiving node MUST reset the specified parameters and SHOULD NOT CC:0070.02.07.11.004 reset any other parameters. The value 0 MUST indicate that the specified Parameter Numbers must assume the value specified by the Configuration Value field. + +Handshake (1 bit) + +This field is used to indicate if a Configuration Bulk Report Command is to be returned when the specified configuration parameters have been stored in non-volatile memory. + +If the Handshake bit is set to 1, a Configuration Bulk Report Command MUST be returned. The command MUST echo all parameters found in this Configuration Bulk Set Command. A node returning a Configuration Bulk Report Command with the Handshake bit set MUST be ready to receive another Configuration Bulk Set Command. If the Handshake bit is set, an originating node MUST wait for the Configuration Bulk Report Command for at least one second. If not receiving a report, the originating node SHOULD assume that the operation failed and resend the same Configuration Bulk Set Command one more time. + +If the Handshake bit is set to 0, a receiving node MUST NOT return a Configuration Bulk Report in response. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Size (3 bits) + +This field is used to specify the size of the actual parameters. The advertised size of a given parameter [MUST always be the same. The value of this field MUST comply with Table 28.](04.22-configuration-command-class-version-1.md#4222-configuration-set-command) + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Parameter – Configuration Value (M*N bytes) + +These fields carry the values to be assigned. Each field MUST have the same size. The size of each field MUST comply with the size advertised by the Size field. + +[The field MUST carry a signed value. The binary encoding of the signed value MUST comply with Table 10. The Value 1 field MUST be the most significant byte.](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) + +## 4.23.5 Configuration Bulk Get Command + +This command is used to query the value of one or more configuration parameters. + +The Configuration Bulk Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONFIGURATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CONFIGURATION BULK GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Offset 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Offset 2 (LSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Parameters | | | | | | | | | | | | | | | | | | | | | | | | + +Parameter Offset (16 bits) + +This field is used to specify the first parameter in a range of one or more parameters. The first byte MUST carry the most significant byte of the 16 bit value. + +Parameter Numbers SHOULD be assigned in a sequence starting from 1. + +Number of Parameters (8 bits) + +This field is used to specify the number of requested configuration parameters. + +The value of this field MUST be in the range 1..255. + +The advertised parameters MUST be in a consecutive range. For example, Parameter Offset set to 4 and Number of Parameters set to 3 MUST represent parameters number 4, 5 and 6. + +## 4.23.6 Configuration Bulk Report Command + +This command is used to advertise the actual value of one or more advertised parameters. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONFIGURATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CONFIGURATION BULK REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Offset 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Offset 2 (LSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Parameters | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to follow | | | | | | | | | | | | | | | | | | | | | | | | +| Default | | | Hand- shake | | | Reserved | | | | | | | | | Size | | | | | | | | | +| | Parameter 1 – Configuration Value 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Parameter 1 – Configuration Value N (LSB) | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Parameter M – Configuration Value 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Parameter M – Configuration Value N (LSB) | | | | | | | | | | | | | | | | | | | | | | | + +Parameter Offset (16 bits) + +This field is used to advertise the first parameter in a range of one or more parameters. The first byte MUST carry the most significant byte of the 16 bit value. CC:0070.02.09.11.001 + +Number of Parameters (8 bits) + +This field is used to advertise the number (M) of configuration parameters contained in this command. + +The value of this field MUST be in the range 1..255. + +The advertised parameters MUST be in a consecutive range. For example, Parameter Offset set to 4 and Number of Parameters set to 3 MUST represent parameters number 4, 5 and 6, regardless of whether they exist at the sending node. + +Reports to follow (8 bits) + +This field MUST be used to advertise the number of reports left before all requested configuration parameters values have been transferred. + +The value 0 MUST indicate that this is the last report. + +If the Handshake field is 1 , this field MUST be set to 0. + +The value of this field MUST be in the range 0..255. Default (1 bit) + +This field MUST be used to advertise if all advertised configuration parameters have the factory default value. + +The value 1 MUST indicate that all advertised configuration parameters have the factory default value. The value 0 MUST indicate that one or more of the advertised configuration parameters do not have the factory default value. + +Handshake (1 bit) + +This field is used to indicate if this report is returned in response to a Configuration Bulk Set Command. + +The value 1 MUST indicate that all configuration parameters have been stored in non-volatile memory and that the sending node is ready to receive another Configuration Bulk Set Command. Except for the Reports to Follow field, all other fields MUST echo the values received in the Configuration Bulk Set Command. The Reports to Follow field MUST be 0. + +The value 0 MUST indicate that this report is returned in response to a Configuration Bulk Get Command. + +Size (3 bits) + +This field is used to advertise the size of the actual parameter. The advertised size of a given parameter CC:0070.02.09.11.00E [MUST always be the same. The value of this field MUST comply with Table 28.](04.22-configuration-command-class-version-1.md#4222-configuration-set-command) + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Parameter – Configuration Value (M*N bytes) + +These fields carry the values advertised by the Parameter Offset and Number of Parameters fields. Each field MUST have the same size. The size of each field MUST comply with the size advertised by the Size field. + +[The field MUST carry a signed value. The binary encoding of the signed value MUST comply with Table 10. The Value 1 field MUST be the most significant byte.](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) + +A sending node SHOULD set this field to 0 for non-existing parameters. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.24-configuration-command-class-version-3.md b/docs/specs/command-class-specification/04-command-class-definitions/04.24-configuration-command-class-version-3.md new file mode 100644 index 0000000..32aadce --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.24-configuration-command-class-version-3.md @@ -0,0 +1,316 @@ + +# 4.24 Configuration Command Class, version 3 + +The Configuration Command Class, version 3 allows product specific configuration parameters to be changed. Examples include the default dimming rate of a light dimmer and the endpoints of a window covering device. + +Configuration parameters accessed via this command class MUST NOT replace similar commands provided by other existing application Command Classes. Configuration parameter documentation MUST be provided in the product documentation. Configuration parameter documentation SHOULD be provided via Z-Wave via this command class CC:0070.03.00.12.001 version. + +A device MUST be able to operate with default factory configuration parameter values. + +It is RECOMMENDED that configuration parameters can be manipulated via a local user interface. It is RECOMMENDED that default factory configuration parameter values can be restored via a local user interface. + +## 4.24.1 Compatibility considerations + +The following additions are made to the Configuration Command Class, version 3: + + [Configuration Name Get Command](04.24-configuration-command-class-version-3.md#4243-configuration-name-get-command)  [Configuration Name Report Command](04.24-configuration-command-class-version-3.md#4244-configuration-name-report-command)  [Configuration Info Get Command](04.24-configuration-command-class-version-3.md#4245-configuration-info-get-command)  [Configuration Info Report Command](04.24-configuration-command-class-version-3.md#4246-configuration-info-report-command)  [Configuration Properties Get Command](04.24-configuration-command-class-version-3.md#4247-configuration-properties-get-command)  [Configuration Properties Report Command](04.24-configuration-command-class-version-3.md#4248-configuration-properties-report-command) + +The purpose of the above commands is to allow a manufacturer to advertise information relating to the use of a specific configuration parameter directly from the configuration interface. The advertised information should be the same as can be found in the printed documentation. + +It should be emphasized that, just like versions 1 and 2, the Configuration Command Class, version 3 is intended only for access to product specific configuration parameters. The access to parameter information is only meant to facilitate access via Z-Wave to information which can also be found in the printed documentation. + +Configuration Command Class versions 1 and 2 explicitly require that the binary value of all configuration parameters are represented as signed values encoded as binary 2's complement. + +Configuration Command Class v3 allows for bit field, signed integer or unsigned integer representations of each individual parameter. + +A device supporting the Configuration Command Class v3 MUST respond to a Configuration Properties Get command. If a Configuration Properties Report command is not returned in response to a Configuration Properties Get command, a controlling device MUST treat the parameter value as a signed integer. + +Configuration Command Class version 2 extended the possible parameter range from 1..255 to 1..65535. The first 255 parameters of the two ranges are identical. Parameters in the range 1..255 can be addressed using either the Bulk Set/Get Commands or Set/Get Commands while parameters in the range 256..65535 can only be addressed using the Bulk Set/Get Commands. + +### 4.24.1.1 “Default” flag + +[Refer to 4.22.1.1.](04.22-configuration-command-class-version-1.md#42211-default-flag) + +### 4.24.1.2 Configuration Properties Report + +Earlier text revisions of the Configuration Command Class, version 3 did not explicitly specify that the “Min Value”, “Max Value” and “Default Value” fields MUST be omitted if the advertised size is 0 in the [Configuration Properties Report Command.](04.24-configuration-command-class-version-3.md#4248-configuration-properties-report-command) + +Controlling nodes SHOULD be aware that some legacy nodes supporting version 3 could by error include the “Min Value”, “Max Value” and “Default Value” fields and set them to 0x00 with an arbitrary size. If a controlling node receives a Report in which the “Next Parameter Number” field seems to be set to 0x0000 when requesting parameter number 0, the controlling node SHOULD inspect the last 2 bytes of the command frame in order to find out what is the Next Parameter Number. + +## 4.24.2 Interoperability considerations + +It is RECOMMENDED that the name and information stored in a supporting device are in English. + +It is RECOMMENDED that the last line of the information field presents an Internet URL which points to updated information for the actual configuration parameter as well as other language variants. + +## 4.24.3 Configuration Name Get Command + +This command is used to request the name of a configuration parameter. + +The Configuration Name Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONFIGURATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CONFIGURATION NAME GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number 2 (LSB) | | | | | | | | | | | | | | | | | | | | | | | | + +Parameter Number (16 bits) + +This field is used to specify the requested configuration parameter. + +The first byte MUST carry the most significant byte of the 16 bit value. + +## 4.24.4 Configuration Name Report Command + +This command is used to advertise the name of a parameter. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONFIGURATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CONFIGURATION NAME REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number 2 (LSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to follow | | | | | | | | | | | | | | | | | | | | | | | | +| Name 1 | | | | | | | | | | | | | | | | | | | | | | | | +| .. | | | | | | | | | | | | | | | | | | | | | | | | +| Name N | | | | | | | | | | | | | | | | | | | | | | | | + +Parameter Number (16 bits) + +This field is used to advertise the actual configuration parameter. + +The first byte MUST carry the most significant byte of the 16 bit value. + +If a non-existing parameter is specified in a Configuration Name Get Command, a receiving node MAY return a zero-length Name field in the Configuration Name Report Command. The receiving node SHOULD however return an error message e.g. “Unassigned parameter”. CC:0070.03.0B.12.001 + +Parameter numbers above 255 can only be addressed using the Bulk Set/Get Commands. Parameter numbers in the range 1..255 can be addressed using either the Bulk Set/Get Commands or the Set/Get Commands. + +Reports to follow (8 bits) + +This field is used to advertise the number of reports left before all parts of the command have been transferred. + +The value 0 MUST indicate that this is the last report. + +Name (N bytes) + +This field is used to advertise the name of the parameter. It is RECOMMENDED that the Name field advertises the name found in the documentation. + +The field MUST carry a byte string with no zero termination. The Name field MAY span multiple reports. The number of Name bytes transmitted MUST be determined from the length field in the frame. + +Bytes MUST be encoded in UTF-8 format. + +It is RECOMMENDED that the name stored in a supporting device is in English. + +## 4.24.5 Configuration Info Get Command + +This command is used to request usage information for a configuration parameter. + +The Configuration Info Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONFIGURATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CONFIGURATION INFO GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number 2 (LSB) | | | | | | | | | | | | | | | | | | | | | | | | + +Parameter Number (16 bits) + +This field is used to specify the requested configuration parameter. + +The first byte MUST carry the most significant byte of the 16 bit value. + +## 4.24.6 Configuration Info Report Command + +This command is used to advertise usage information for a configuration parameter. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONFIGURATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CONFIGURATION INFO REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number 2 (LSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to follow | | | | | | | | | | | | | | | | | | | | | | | | +| Info 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Info N | | | | | | | | | | | | | | | | | | | | | | | | + +Parameter Number (16 bits) + +This field is used to advertise the actual configuration parameter. + +The first byte MUST carry the most significant byte of the 16 bit value. + +If a non-existing parameter is specified in a Configuration Info Get Command, a receiving node MAY return a zero-length Info field in the Configuration Info Report Command. The receiving node SHOULD however return an error message, e.g. “Unassigned parameter”. + +Parameter numbers above 255 can only be addressed using the Bulk Set/Get Commands. Parameter numbers in the range 1..255 can be addressed using either the Bulk Set/Get Commands or the Set/Get Commands + +Reports to follow (8 bits) + +This field is used to advertise the number of reports left before all parts of the command have been transferred. + +The value 0 MUST indicate that this is the last report. + +Info (N bytes) + +This field is used to advertise the detailed information available for the parameter. It is RECOMMENDED that the Info field carries all information found in the documentation. + +The field MUST carry a byte string with no zero termination. The number of Info bytes transmitted MUST be determined from the length field in the frame. The Info field MAY span multiple reports. The number of Info bytes MAY be zero. + +Bytes MUST be encoded in UTF-8 format. + +It is RECOMMENDED that the information stored in a supporting device is in English. + +It is RECOMMENDED that the last line of the information field presents an Internet URL which points to updated information for the actual configuration parameter as well as other language variants. + +## 4.24.7 Configuration Properties Get Command + +This command is used to request the properties of a configuration parameter. + +The Configuration Properties Report Command MUST be returned in response to this command. + +If a Configuration Properties Report command is not returned in response to a Configuration Properties Get command, a controlling device MUST treat the parameter value as a signed integer. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONFIGURATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CONFIGURATION PROPERTIES GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number 2 (LSB) | | | | | | | | | | | | | | | | | | | | | | | | + +Parameter Number (16 bits) + +This field is used to specify the requested configuration parameter. + +The first byte MUST carry the most significant byte of the 16 bit value. + +If a non-existing parameter is specified in this command, a receiving node MUST advertise zero values in the Format and Size fields. The Next Parameter Number field MUST advertise the next available configuration parameter. + +It is RECOMMENDED that a controlling device initiates probing of supported configuration parameters by issuing this command for parameter number 0. If a Size field value of zero is returned, a controlling device SHOULD issue a Configuration Properties Get Command for the parameter advertised in the Next Parameter Number field. + +## 4.24.8 Configuration Properties Report Command + +This command is used to advertise the properties of a configuration parameter. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONFIGURATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CONFIGURATION PROPERTIES REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number 2 (LSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | Format | | | | | | | | | Size | | | | | | | | | +| Min Value 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| .. | | | | | | | | | | | | | | | | | | | | | | | | +| Min Value N (LSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Max Value 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| .. | | | | | | | | | | | | | | | | | | | | | | | | +| Max Value N (LSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Default Value 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| .. | | | | | | | | | | | | | | | | | | | | | | | | +| Default Value N (LSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Next Parameter Number 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Next Parameter Number 2 (LSB) | | | | | | | | | | | | | | | | | | | | | | | | + +Parameter Number (16 bits) + +This field is used to advertise the actual configuration parameter. + +The first byte MUST carry the most significant byte of the 16 bit value. + +If this field advertises a non-existing parameter , a receiving node MUST advertise zero values in the Format and Size fields. The Next Parameter Number field MUST advertise the next available configuration parameter. + +Parameter numbers above 255 can only be addressed using the Bulk Set/Get Commands. Parameter numbers in the range 1..255 can be addressed using either the Bulk Set/Get Commands or the Set/Get Commands. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Format (3 bits) + +This field is used to advertise the format of the parameter. + +[The value of this field MUST comply with Table 29.](04.24-configuration-command-class-version-3.md#4248-configuration-properties-report-command) Table 29, Configuration Properties Report :: Format encoding + +| | Value | | | Parameter format and presentation | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Signed Integer | | | +| 0x01 | | | Unsigned Integer | | | +| 0x02 | | | Enumerated (Radio buttons) | | | +| 0x03 | | | Bit field (Checkboxes) | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +If the parameter format is “Unsigned integer”, normal binary integer encoding MUST be used. + +[If the parameter format is “Signed integer”, the binary encoding MUST comply with Table 10.](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) + +If the parameter format is “Enumerated”, the parameter MUST be treated as an unsigned integer. [A graphical configuration tool SHOULD present this parameter as a series of radio buttons [11].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +If the parameter format is “Bit field” the parameter MUST be treated as a bit field where each individual bit can be set or reset. [A graphical configuration tool SHOULD present this parameter as a series of checkboxes [11].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +Size (3 bits) + +This field is used to advertise the size of the actual parameter. + +The advertised size MUST also apply to the fields “Min Value”, “Max Value”, “Default Value” carried in this command. + +[The value of this field MUST comply with Table 30.](04.24-configuration-command-class-version-3.md#4248-configuration-properties-report-command) + +Table 30, Configuration Properties Report :: Size encoding + +| | Size | | | Size of parameter | | +| --- | --- | --- | --- | --- | --- | +| 0 | | | 0 bit (Unassigned parameter, Value fields omitted) | | | +| 1 | | | 8 bit | | | +| 2 | | | 16 bit | | | +| 4 | | | 32 bit | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Min Value (N bytes) + +This field MUST advertise the minimum value that the actual parameter can assume. + +If the parameter is “Bit field”, this field MUST be set to 0. + +The size of the field MUST comply with the size advertised by the Size field. This field MUST be omitted if the Size field is set to 0. + +The sign encoding MUST comply with the mode advertised by the Signed field. Max Value (N bytes) + +This field MUST advertise the maximum value that the actual parameter can assume. + +If the parameter is “Bit field”, each individual supported bit MUST be set to ‘1’, while each un-supported bit of MUST be set to ‘0’. A graphical configuration tool SHOULD NOT present checkboxes for un-supported bits. + +The size of the field MUST comply with the size advertised by the Size field. This field MUST be omitted if the Size field is set to 0. + +The sign encoding MUST comply with the mode advertised by the Signed field. + +Default Value (N bytes) + +This field MUST advertise the default value of the actual parameter. + +The size of the field MUST comply with the size advertised by the Size field. This field MUST be omitted if the Size field is set to 0. + +The sign encoding MUST comply with the mode advertised by the Signed field. + +Next Parameter Number (16 bits) + +Configuration parameter identifiers may be assigned in a non-sequential order. + +This field MUST advertise the next available configuration parameter. The value 0x0000 MUST indicate that this is the last available configuration parameter. + +The first byte MUST carry the most significant byte of the 16 bit value. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.25-configuration-command-class-version-4.md b/docs/specs/command-class-specification/04-command-class-definitions/04.25-configuration-command-class-version-4.md new file mode 100644 index 0000000..6c6c2e9 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.25-configuration-command-class-version-4.md @@ -0,0 +1,205 @@ + +# 4.25 Configuration Command Class, version 4 + +The Configuration Command Class, version 4 introduces the support of read-only parameters, parameters requiring network re-inclusion and advanced parameters as well as allows optional support for Bulk Commands. + +A read-only parameter can be accessed with Get commands but cannot be modified with Set Commands. A parameter requiring re-inclusion is typically a parameter altering the node capabilities, which requires performing the inclusion again in order to have the controller to learn about the node capabilities once more. A parameter may be advertised as "advanced" to indicate to the controlling application that the actual parameter is intended only for advanced use, e.g. calibration. + +The following commands are modified in version 4: + + [Configuration Set Command](04.25-configuration-command-class-version-4.md#4252-configuration-set-command)  [Configuration Bulk Set Command](04.25-configuration-command-class-version-4.md#4253-configuration-bulk-set-command)  [Configuration Properties Report Command](04.25-configuration-command-class-version-4.md#4254-configuration-properties-report-command) + +The following new command is introduced: + + [Configuration Default Reset Command](04.25-configuration-command-class-version-4.md#4255-configuration-default-reset-command) + +All commands not mentioned in this version remain unchanged from previous versions. + +## 4.25.1 Compatibility considerations + +Configuration Command Class, version 4 is backwards compatible with the previous versions of Configuration Command Class. + +A device supporting Configuration Command Class, version 4 MUST support Configuration Command Class, version 3. + +### 4.25.1.1 “Default” flag + +[Refer to 4.22.1.1](04.22-configuration-command-class-version-1.md#42211-default-flag) + +From version 4 and onwards, a node MUST NOT reset all Configuration Parameters when receiving a Set or Bulk Set Command with the default flag set to 1. + +### 4.25.1.2 Configuration Properties Report + +[Refer to 4.24.1.2.](04.24-configuration-command-class-version-3.md#42412-configuration-properties-report) + +The recommendation given in version 3 does not apply to version 4 supporting nodes as new fields are [appended at the end of the Configuration Properties Report Command in version 4.](04.24-configuration-command-class-version-3.md#4248-configuration-properties-report-command) + +### 4.25.1.3 “Re-inclusion required” flag + +Configuration parameters modifying a node’s NIF and/or (non-dynamic) Multi Channel End Point capabilities MUST be advertised as “Re-inclusion required”. + +When such a parameter is modified, the node MUST NOT advertise the new NIF and/or (non dynamic) Multi Channel End Point capabilities before being excluded from its current network. + +### 4.25.1.4 “Advanced” flag + +The difference between normal and advanced parameters lies on the controlling node side. + +A parameter MAY be advertised as "advanced" in order to simplify the configuration of a node by normally not showing such a parameter to the end user. Advanced parameters SHOULD be presented to the user only when an [Advanced] option is selected in the controller user interface. + +### 4.25.1.5 Parameters value and network inclusion/exclusion + +From version 4 and onwards, a node MUST NOT modify or reset any configuration parameter when being included or excluded of a Z-Wave network. + +A node MUST reset all its configuration parameters if either: + + It is manually reset to factory default  [It receives a Configuration Default Reset Command.](04.25-configuration-command-class-version-4.md#4255-configuration-default-reset-command) + +A node MUST NOT reset all its configuration parameters in any other case. + +### 4.25.1.6 Bulk commands support + +A node supporting Configuration Command Class, version 4 MAY elect to ignore the following Commands: + + Configuration Bulk Set Command  Configuration Bulk Get Command  Configuration Bulk Report Command. + +If it is the case, the node MUST: + + Return an Application Rejected Request Command when receiving one of the ignored commands (if received without Supervision encapsulation).  Advertise that it ignores the Bulk Commands in the Configuration Properties Report. + +If Bulk Commands are supported, they MUST be supported for all parameters. If Bulk Commands are ignored, they MUST be ignored for all parameters. + +## 4.25.2 Configuration Set Command + +This command is used to set the value of a configuration parameter. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONFIGURATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CONFIGURATION SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number | | | | | | | | | | | | | | | | | | | | | | | | +| Default | | | Reserved | | | | | | | | | | | | Size | | | | | | | | | +| Configuration Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Configuration Value N | | | | | | | | | | | | | | | | | | | | | | | | + +A receiving node MUST ignore this command if the specified parameter is advertised as a Read-only parameter. + +All fields not specified below are unchanged from version 2 Configuration Set Command. + +Default (1 bit) + +This field is used to specify if the default value is to be restored for the specified configuration parameter. + +The value 1 MUST indicate that default factory settings must be restored for the specified Parameter Number. In this case, the Configuration value field MUST be ignored and any other parameters MUST NOT be reset by a receiving node. + +The value 0 MUST indicate that the specified Parameter Number MUST assume the value specified by the Configuration Value field. + +Configuration Value (N bytes) + +This field carries the value to be assigned. The size of the field MUST comply with the size advertised by the Size field. + +The configuration value MUST be encoded according to the Format field advertised in the Configuration Properties Report Command for the parameter number. + +## 4.25.3 Configuration Bulk Set Command + +This command is used to set the value of one or more configuration parameters. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONFIGURATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CONFIGURATION BULK SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Offset 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Offset 2 (LSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Parameters | | | | | | | | | | | | | | | | | | | | | | | | +| Default | | | Hand- shake | | | Reserved | | | | | | | | | Size | | | | | | | | | +| | Parameter 1 – Configuration Value 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Parameter 1 – Configuration Value N (LSB) | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Parameter M – Configuration Value 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Parameter M – Configuration Value N (LSB) | | | | | | | | | | | | | | | | | | | | | | | + +A receiving node MUST ignore this command for parameters that are advertised as Read-only parameters. + +All fields not specified below are unchanged from version 2 Configuration Bulk Set Command. + +Default (1 bit) + +This field is used to specify if the default value is to be restored for the specified configuration parameters. + +The value 1 MUST indicate that default factory settings must be restored for all the Parameter Numbers defined by the Parameter Offset and Number of Parameters fields. In this case, the Configuration Value field MUST be ignored and any other parameters MUST NOT be reset by a receiving node. + +The value 0 MUST indicate that the specified Parameter Numbers MUST assume the value specified by the Configuration Value field. + +Parameter –Configuration Value (M*N bytes) + +These fields carry the parameter values to be assigned. Each parameter value field MUST have the same size. The size of each field MUST comply with the size advertised by the Size field. + +The values MUST be encoded according to the Format field advertised in the Configuration Properties Report Command for each parameter number. + +## 4.25.4 Configuration Properties Report Command + +This command is used to advertise the properties of a configuration parameter. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONFIGURATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CONFIGURATION PROPERTIES REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number 2 (LSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Re-inclusion required | | | Read- only | | | Format | | | | | | | | | Size | | | | | | | | | +| Min Value 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| .. | | | | | | | | | | | | | | | | | | | | | | | | +| Min Value N (LSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Max Value 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| .. | | | | | | | | | | | | | | | | | | | | | | | | +| Max Value N (LSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Default Value 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| .. | | | | | | | | | | | | | | | | | | | | | | | | +| Default Value N (LSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Next Parameter Number 1 (MSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Next Parameter Number 2 (LSB) | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | No Bulk support | | | Advanced | | | + +All fields not specified below are unchanged from version 3 Configuration Properties Report Command. + +Read-only (1 bit) + +This field is used to indicate if the parameter is read-only. + +The value 1 MUST indicate that the advertised parameter is read-only. The value 0 MUST indicate that the advertised parameter is not read-only. + +Re-inclusion required (1 bit) + +This field is used to indicate if the advertised parameter requires the node to be re-included in the network before the parameter value change takes effect. + +The value 1 MUST indicate that the advertised parameter requires re-inclusion after being changed. The value 0 MUST indicate that the advertised parameter does not require re-inclusion after being changed. Advanced (1 bit) + +This field is used to indicate if the advertised parameter is to be presented in the “Advanced” parameter section in the controller GUI. + +The value 1 MUST indicate that the advertised parameter is an Advanced parameter. The value 0 MUST indicate that the advertised parameter is not an Advanced parameter. + +No Bulk support (1 bit) + +This field is used to advertise if the sending node supports Bulk Commands. + +The value 1 MUST indicate that the Bulk Commands will be ignored by the sending node. The value 0 MUST indicate that the Bulk Commands are supported by the sending node + +A sending node MUST always advertise the same value in this field, regardless of the parameter number. + +## 4.25.5 Configuration Default Reset Command + +This command is used to reset all configuration parameters to their default value. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONFIGURATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CONFIGURATION DEFAULT RESET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +A node receiving this command MUST reset all its Configuration Parameters to their default value. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.26-controller-replication-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.26-controller-replication-command-class-version-1.md new file mode 100644 index 0000000..1953b07 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.26-controller-replication-command-class-version-1.md @@ -0,0 +1,115 @@ + +# 4.26 Controller Replication Command Class, version 1 + +The Controller Replication Command Class is used to copy scene and group data to another controlling node. The Command Class may be used in conjunction with a controller shift or when including a new controller to the network. It is OPTIONAL to use this command class during a controller shift or when including a new controller to the network. + +## 4.26.1 Transfer Group Command + +This command is used to replicate mappings between Group ID and Node ID. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONTROLLER REPLICATION _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CTRL REPLICATION TRANSFER GROUP _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sequence Number | | | | | | | | | | | | | | | | | | | | | | | | +| Group ID | | | | | | | | | | | | | | | | | | | | | | | | +| Node ID | | | | | | | | | | | | | | | | | | | | | | | | + +Sequence Number (8 bits) + +Sequence Number of this particular command. + +Group ID (8 bits) + +Group ID of the group that the node is member of. + +Node ID (8 bits) + +Node ID of slave device. + +## 4.26.2 Transfer Group Name Command + +This command is used to replicate group names. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONTROLLER REPLICATION _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CTRL REPLICATION TRANSFER GROUP NAME _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sequence Number | | | | | | | | | | | | | | | | | | | | | | | | +| Group ID | | | | | | | | | | | | | | | | | | | | | | | | +| Group Name 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Group Name N | | | | | | | | | | | | | | | | | | | | | | | | + +Sequence Number (8 bits) + +Sequence Number of this particular command. + +Group ID (8 bits) + +Group ID associated with a specific group. + +Group Name (N bytes) + +The Group Name fields contain the assign group name in ASCII characters. + +## 4.26.3 Transfer Scene Command + +This command is used to replicate mappings between Scene ID and Node ID. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONTROLLER REPLICATION _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CTRL REPLICATION TRANSFER SCENE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sequence Number | | | | | | | | | | | | | | | | | | | | | | | | +| Scene ID | | | | | | | | | | | | | | | | | | | | | | | | +| Node ID | | | | | | | | | | | | | | | | | | | | | | | | +| Level | | | | | | | | | | | | | | | | | | | | | | | | + +Sequence Number (8 bits) + +Sequence Number of this particular command. + +Scene ID (8 bits) + +The scene ID is the parameter used to link together the different devices that takes part of a scene. + +Node ID (8 bits) + +The Node ID for a device that is part of the scene. + +Level (8 bits) + +The level is the parameter used for the specified scene. + +## 4.26.4 Transfer Scene Name Command + +This command is used to replicate scene names. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS CONTROLLER REPLICATION _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CTRL REPLICATION TRANSFER SCENE NAME _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sequence Number | | | | | | | | | | | | | | | | | | | | | | | | +| Scene ID | | | | | | | | | | | | | | | | | | | | | | | | +| Scene Name 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Scene Name N | | | | | | | | | | | | | | | | | | | | | | | | + +Sequence Number (8 bits) + +Sequence Number of this particular command. + +Scene ID (8 bits) + +Scene ID associated with a specific scene. + +Scene Name (N bytes) + +The Scene Name fields contain the assign scene name in ASCII characters. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.27-demand-control-plan-configuration-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.27-demand-control-plan-configuration-command-class-version-1.md new file mode 100644 index 0000000..a68bf2b --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.27-demand-control-plan-configuration-command-class-version-1.md @@ -0,0 +1,252 @@ + +# 4.27 Demand Control Plan Configuration Command Class, version 1 + +The Demand Control Plan Configuration Command Class allows Utility Suppliers to issue and manage a list of Demand Control Plan (DCP) events to the end consumer. + +The DCP Configuration commands are separated for the DCP monitoring commands in the Demand Control Plan Monitor Command Class, allowing the classes to be optionally supported at different security levels. (E.g. DCP monitoring commands could be supported using non-secure communication, while enabling strict secure-only communication for the DCP Configuration Command Class). Refer to the Security and Security 2 command classes for more details. + +A DCP event contains information regarding criticality, products involved, requested reduction, time duration and if a certain rate (identified by a Demand Control Plan Rate ID, refer to the Rate Table Configuration Command Class) is associated with the event. When a DCP event is outdated, it is removed from the list. It is the utility supplier responsibility to prevent overflow of the list by query the number of free positions in the list before submitting a new DCP event to the list. Each DCP event is uniquely identified by a timestamp issued the Utility Supplier. + +A DCP event may also include information, which enables devices not supporting this class to use in the Demand Control Plan through the Start & Stop Association Group functionality. The installer, the end user or Utility Supplier (remote management) configures the Association groups. During the configuration process the devices are selected and the association entries are created. These associations can additionally be configured with the specific Z-Wave commands (through the Association Command Configuration Command Class). If no Z-Wave commands are specified in the Associations groups, it is the responsibility of the device to issue the relevant commands based on Utility Supplier specific algorithms. + +## 4.27.1 DCP List Supported Get Command + +This command is used to request the total size of the DCP list along with the number of free entries in the list. + +The DCP List Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DCP CONFIG _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DCP LIST SUPPORTED GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.27.2 DCP List Supported Report Command + +This command is used to provide the total size of the DCP list along with the number of free entries in the list. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DCP CONFIG _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DCP LIST SUPPORTED REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| DCP List Size | | | | | | | | | | | | | | | | | | | | | | | | +| Free DCP List entries | | | | | | | | | | | | | | | | | | | | | | | | + +DCP List Size (8 bits) + +This value specifies the DCP list size. 0x00 is reserved + +Free DCP List entries (8 bits) + +This value specifics the number of free entries for new DCP events. The value 0x00 specifies a full list. + +## 4.27.3 DCP List Set Command + +This command is used to place a new DCP event in the DCP list. Each DCP event is time stamped for future reference. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DCP CONFIG _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DCP LIST SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Month | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Day | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| DCP Rate ID | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | Number of DC | | | | | | +| | Generic Device Class 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Specific Device Class 1 | | | | | | | | | | | | | | | | | | | | | | | +| …. | | | | | | | | | | | | | | | | | | | | | | | | +| | Generic Device Class N | | | | | | | | | | | | | | | | | | | | | | | +| | Specific Device Class N | | | | | | | | | | | | | | | | | | | | | | | +| Start Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Start Month | | | | | | | | | | | | | | | | | | | | | | | | +| Start Day | | | | | | | | | | | | | | | | | | | | | | | | +| Start Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Start Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Start Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Hour Time | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Minute Time | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Second Time | | | | | | | | | | | | | | | | | | | | | | | | +| Event Priority | | | | | | | | | | | | | | | | | | | | | | | | +| Load shedding | | | | | | | | | | | | | | | | | | | | | | | | +| Start Association Group | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Association Group | | | | | | | | | | | | | | | | | | | | | | | | +| Randomization interval | | | | | | | | | | | | | | | | | | | | | | | | + +Timestamp -Year (16 bits) + +Specify the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. + +Timestamp -Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December). + +Timestamp -Day (8 bits) + +Specify the day of the month between 01 and 31. + +Timestamp -Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00-23) in local time. + +Timestamp -Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00-59) in local time. + +Timestamp -Second Local Time (8 bits) + +Specify the number of complete seconds since the start of the minute (00-59) in local time. The value 60 used to keep UTC from wandering away is not supported. + +DCP Rate ID (8 bits) + +Specify if a specific rate is applicable when participating in the DCP event. If an entry in the Rata table contains a matching DCP Rate ID this rate will be active for the duration of the event regardless of other parameters in the rate is not met. + +DCP Rate ID usage Example + +Prior to the DCP events a given rate table is configured defining when rates are active during a day. The Table contains two entries with DCP Rate IDs allowing the Utility Supplier to activate the rates outside of the time defined in the Table when a DCP event is placed in the DCP list with the corresponding DCP rate ID. + +Prior to Jul14 2008 two DCP events are placed in the List by the Utility Supplier, which changes the Rate profile of Jul14 compared to an ‘standard’ day. + +| 4 | 2 | 5 | 1 | 3 | 4 | +| --- | --- | --- | --- | --- | --- | + +| | | | | | | | | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | 5 | 5 | 1 | 2 | 1 | 3 | 4 | + +Randomization interval (8 bits) + +Specify the randomization interval in units of seconds, which must be applied as an offset to the start and stopping of the events as requested in the DCP event. + +E.g. A value of 0x10 specifies that every device should randomly select a start and stop time offset between 0 and 16 seconds. This offset SHOULD be applied to the start and duration fields in the DCP event. + +Number of DC (2 bits) + +Specify the number of Generic/Specific Device Classes, which are requested to participate in the DCP event + +Generic Device Class (8bits) + +[Specify the Generic Device Class identifier. Refer to [1] and [10].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +Specific Device Class (8 bits) + +[Specify the Specific Device Class identifier. Refer to [1] and [10].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +Start Year (16 bits) + +Specify the year in the usual Gregorian calendar for the start of the event. The first byte (Year 1) is the most significant byte. + +Start Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December) for the start of the event. + +Start Day (8 bits) + +Specify the day of the month for the start of the event between 01 and 31. + +Start Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00-23) in local time for the start of the event. + +Start Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00-59) in local time for the start of the event. + +Start Second Local Time (8 bits) + +Specify the number of complete seconds since the start of the minute (00-59) in local time. The value 60 used to keep UTC from wandering away is not supported. Duration Hour Time (8 bits) + +Specify the number of complete hours of the event. + +Duration Minute Time (8 bits) + +Specify the number of complete minutes of the event. + +Duration Second Time (8 bits) + +Specify the number of complete seconds of the event. + +Event Priority (8 bits) + +The parameter specifies the priority of the DCP event. The High priority is used by the utility Supplier to mandate device participation and lower priorities are used by devices to voluntary to participate in the event and to which degree. + +| | Event Priority | | | Description | | | Device participation | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | Reserved | | | Voluntary | | | +| 0x01 | | | V1 - Green Energy | | | Voluntary | | | +| 0x02 | | | V2 | | | Voluntary | | | +| 0x03 | | | V3 | | | Voluntary | | | +| 0x04 | | | V4 | | | Voluntary | | | +| 0x05 | | | V5 | | | Voluntary | | | +| 0x06 | | | V6 | | | Voluntary | | | +| 0x07 | | | V7 | | | Voluntary | | | +| 0x08 | | | M1 - Emergency | | | Mandatory | | | +| 0x09 | | | M2 | | | Mandatory | | | +| 0x0A | | | M3 | | | Mandatory | | | +| 0x0B | | | M4 | | | Mandatory | | | +| 0x0C | | | Utility defined | | | Utility defined | | | +| 0x0D | | | Utility defined | | | Utility defined | | | +| 0x0E | | | Utility defined | | | Utility defined | | | +| 0x0F | | | Utility defined | | | Utility defined | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Load shedding (8 bits) + +Specify the load shedding in percentage of average consumption requested for the event. This load shedding will be applied to the devices with the device classes specified in the command. + +This field MUST be in the range 0x01..0x64, which represents values in the range 1%..100%. All other values are reserved. Reserved values MUST NOT be used by a sending node and MUST be ignored by a receiving node. Start Association group (8 bits) + +Specify which association group (see the Association Command Class) should be activated when the event is started. The value 0x00 specifies no group should be activated. + +If the device also supports the Association Command Configuration Command Class it possible to dynamically and remotely (from the Energy Supplier or others) to specify precisely which current and future Z-Wave commands should be send to which Z-Wave nodes. + +The configuration of the Start Association group is done either manually by the installer or automatically when the device detect other relevant devices + +Stop Association group (8 bits) + +Specify which association group (see the Association Command Class) should be activated when the event is stopped. The value 0x00 specifies no group should be activated. + +The configuration of the Stop Association group is done either manually by the installer or automatically when the device detect other relevant devices + +Start Associating group and Stop Associating Group usage example + +A small energy control system consisting of a device supporting the DCP command class and 3 z-wave devices which can participate in the application. NodeId 1: Setback Thermostat device, NodeId 8: Simple Thermostat device, NodeId 5: Multilevel Power Switch device. + +Through the use of the Association Command Class and the Association Command Configuration Command Class the following Associations has been established in the device. + +Group 1 Node1, Thermostat_Setback_SetPpermanent override,energy saving mode) o Node8, Thermostat_Setpoint_Set(Heating setpoint#1, 19,5 C) Node5, Multilevel_Switch:Set (Dimlevel =0x20) + +Group 2 o Node1, Thermostat_Setback_Set(No override,Setback = 0 C) o Node8, Thermostat_Setpoint_Set(Heating setpoint#1, 21,5 C) Node5, Multilevel_Switch:Set (Dimlevel =0x40) + +A DCP event can now specifically invoke Group1 when starting the event and invoking group2 when stopping the event by specifying Start Association Group=0x01 and Stop Association Group=0x02. + +## 4.27.4 DCP List Remove + +This command is used to remove a DCP event from the DCP list. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DCP CONFIG _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DCP LIST REMOVE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Month | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Day | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | + +[Refer to DCP List report command class (section 4.28.2) for description of fields](04.28-demand-control-plan-monitor-command-class-version-1.md#4282-dcp-list-report-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.28-demand-control-plan-monitor-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.28-demand-control-plan-monitor-command-class-version-1.md new file mode 100644 index 0000000..bb8abf7 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.28-demand-control-plan-monitor-command-class-version-1.md @@ -0,0 +1,124 @@ + +# 4.28 Demand Control Plan Monitor Command Class, version 1 + +The Demand Control Plan Monitor Command Class allows devices to monitor the list of Demand Control Plan (DCP). A DCP event contains information regarding criticality, products involved, requested reduction, time duration and if a certain rate (identified by a Demand Control Plan Rate ID, refer to the Rate Table Configuration Command Class) is associated with the event. When a DCP event is outdated, it is removed from the list. Each DCP event is uniquely identified by a timestamp issued the Utility Supplier. + +## 4.28.1 DCP List Get Command + +This command is used to request the pending DCP event in a device. + +The DCP List Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DCP MONITOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DCP LIST GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.28.2 DCP List Report Command + +This command reports the pending DCP event in a device. If more than one DCP event is pending – the reports will be submitted in chronically order as to when the events was placed on the list. Newest entry will be reported first. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DCP MONITOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DCP LIST REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Month | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Day | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| DCP ID | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | Number of DC | | | | | | +| | Generic Device Class 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Specific Device Class 1 | | | | | | | | | | | | | | | | | | | | | | | +| …. | | | | | | | | | | | | | | | | | | | | | | | | +| | Generic Device Class N | | | | | | | | | | | | | | | | | | | | | | | +| | Specific Device Class N | | | | | | | | | | | | | | | | | | | | | | | +| Start Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Start Month | | | | | | | | | | | | | | | | | | | | | | | | +| Start Day | | | | | | | | | | | | | | | | | | | | | | | | +| Start Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Start Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Start Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Hour Time | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Minute Time | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Second Time | | | | | | | | | | | | | | | | | | | | | | | | +| Event Priority | | | | | | | | | | | | | | | | | | | | | | | | +| Load shedding | | | | | | | | | | | | | | | | | | | | | | | | +| Start Association Group | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Association Group | | | | | | | | | | | | | | | | | | | | | | | | +| Randomization interval | | | | | | | | | | | | | | | | | | | | | | | | + +Reports to Follow (8 bits) + +This value indicates how many report frames there are left, the value 0xFF means that the number of reports have not been calculated yet or that there is more than 255 reports to follow. + +[Refer to DCP List Set command class (section 4.27.3) for detailed description of the fields.](04.27-demand-control-plan-configuration-command-class-version-1.md#4273-dcp-list-set-command) + +## 4.28.3 DCP Event Status Get + +This command is used to query the status of a specific DCP event in the DCP list. + +The DCP Event Status Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DCP MONITOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DCP EVENT STATUS GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Month | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Day | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | + +[Refer to DCP List Set command class (section 4.27.3) for detailed description of the fields.](04.27-demand-control-plan-configuration-command-class-version-1.md#4273-dcp-list-set-command) + +## 4.28.4 DCP Event Status Report + +This command is used to provide the status of a specific DCP event in the DCP list. + +| | 7 | | | 6 | | | 5 | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DCP MONITOR _ _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Command = DCP EVENT STATUS GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Year 1 | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Year 2 | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Month | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Day | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp -Second Local Time | | | | | | | | | | | | | | | | | | | | | | | +| Event status | | | | | | | | | | | | | | | | | | | | | | | + +[Refer to DCP List report command class (section 4.28.2) for description of fields](04.28-demand-control-plan-monitor-command-class-version-1.md#4282-dcp-list-report-command) + +Event Status (8 bits) + +The field contains the status of the event. + +Table 31, DCP Event Status Report::Event Status encoding + +| Event status | | | Description | | +| --- | --- | --- | --- | --- | +| 0x01 | | Event Started | | | +| 0x02 | | Event Completed | | | +| 0x03 | | Event Rejected by the user | | | +| 0x04 | | Event not Applicable | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.29-door-lock-command-class-version-1-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.29-door-lock-command-class-version-1-2.md new file mode 100644 index 0000000..d313cb1 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.29-door-lock-command-class-version-1-2.md @@ -0,0 +1,277 @@ + +# 4.29 Door Lock Command Class, version 1-2 + +The Door Lock Command Class is used to operate and configure a door lock device. + +[The Door Lock Command Class is an actuator control command class. Refer to 3.6.](../03-command-class-overview/03.06-actuator-control.md#36-actuator-control) + +## 4.29.1 Compatibility considerations + +A device supporting Door Lock CC, Version 2 MUST support Door Lock CC, version 1. + +The Door Lock Command Class, version 2 adds the “unknown” state to the Door Lock Operation Report Command. + +A supporting node MAY implement a subset of the features represented by the Door Lock Mode, Door Handles Mode and Door Condition fields which are provided by the commands of this Command Class. + +## 4.29.2 Door Lock Operation Set Command + +This command is used to set the operation mode of a supporting door lock device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DOOR LOCK _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DOOR LOCK OPERATION SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Door Lock Mode | | | | | | | | | | | | | | | | | | | | | | | | + +Door Lock Mode (8 bits) + +The Door Lock Mode field is used to specify the operation mode of the door lock device. + +[The encoding of this field MUST be according to Table 32.](04.29-door-lock-command-class-version-1-2.md#4292-door-lock-operation-set-command) + +Table 32, Door Lock Operation Set :: Mode + +| | Mode | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | Door Unsecured 1) | | | 1 | | | +| 0x01 | | | Door Unsecured with timeout 2) | | | 1 | | | +| 0x10 | | | Door Unsecured for inside Door Handles 1) | | | 1 | | | +| 0x11 | | | Door Unsecured for inside Door Handles with timeout 2) | | | 1 | | | +| 0x20 | | | Door Unsecured for outside Door Handles 1) | | | 1 | | | +| 0x21 | | | Door Unsecured for outside Door Handles with timeout 2) | | | 1 | | | +| 0xFF | | | Door Secured | | | 1 | | | + +1) Constant mode. Door will be unsecured until set to secured mode by another command. 2) Timeout mode. Fallback to secured mode after timeout has expired. All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +A controlling node MUST NOT specify modes using timeout-based fall back if the Operation Type of the supporting device is set to Constant operation (set by Door Lock Configuration Set). A supporting node MUST ignore modes using timeout-based fall back if Operation Type is set to Constant operation. A supporting node MUST apply the constant modes without any timeout even if it is set to Timed Operation Type. + +[A supporting node MAY implement a subset of the Door Lock Modes defined by Table 32.](04.29-door-lock-command-class-version-1-2.md#4292-door-lock-operation-set-command) A supporting node MUST accept the Door Lock Mode values 0x00 and 0xFF. + +## 4.29.3 Door Lock Operation Get Command + +This command is used to request the status of a door lock device. + +The Door Lock Operation Report command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DOOR LOCK _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DOOR LOCK OPERATION GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.29.4 Door Lock Operation Report Command + +This command is used to advertise the status of a door lock device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DOOR LOCK _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DOOR LOCK OPERATION REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Door Lock Mode | | | | | | | | | | | | | | | | | | | | | | | | +| Outside Door Handles Mode | | | | | | | | | | | | Inside Door Handles Mode | | | | | | | | | | | | +| Door Condition | | | | | | | | | | | | | | | | | | | | | | | | +| Lock Timeout Minutes | | | | | | | | | | | | | | | | | | | | | | | | +| Lock Timeout Seconds | | | | | | | | | | | | | | | | | | | | | | | | + +Door Lock Mode (8 bits) + +The Door Lock Mode field MUST advertise the mode of the door lock device. + +[The encoding of this field MUST be according to Table 33.](04.29-door-lock-command-class-version-1-2.md#4294-door-lock-operation-report-command) + +[Table 33, Door Lock Operation Report :: Door Lock Mode](04.29-door-lock-command-class-version-1-2.md#4294-door-lock-operation-report-command) + +| | Mode | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | Door Unsecured 1) | | | 1 | | | +| 0x01 | | | Door Unsecured with timeout 2) | | | 1 | | | +| 0x10 | | | Door Unsecured for inside Door Handles 1) | | | 1 | | | +| 0x11 | | | Door Unsecured for inside Door Handles with timeout 2) | | | 1 | | | +| 0x20 | | | Door Unsecured for outside Door Handles 1) | | | 1 | | | +| 0x21 | | | Door Unsecured for outside Door Handles with timeout 2) | | | 1 | | | +| 0xFE | | | Door/Lock State Unknown 3) | | | 2 | | | +| 0xFF | | | Door Secured | | | 1 | | | + +1) Constant mode. Door will be unsecured until set back to secured mode by command 2) Timeout mode. Fallback to secured mode after timeout has expired 3) Bolt is not fully retracted/engaged + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +A supporing node MAY advertise a subset of the available Door Lock Mode values. A controlling node MUST accept all Door Lock Mode values. + +The Door Lock Mode field SHOULD advertise the current value of the device hardware; also while in transition to a new target value. + +Outside Door Handles Mode (4 bits) + +This field MUST advertise the status of each individual outside door handle. + +[The encoding of the Outside Door Handles Mode bitmask field MUST be according to Table 34 and Table 35.](04.29-door-lock-command-class-version-1-2.md#4294-door-lock-operation-report-command) + +Table 34, Door Handles Mode bitmask + +| | Bit 3 | | | Bit 2 | | | Bit 1 | | | Bit 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| | Handle 4 | | | Handle 3 | | | Handle 2 | | | Handle 1 | | + +Table 35, Door Handles Mode bit encoding + +| | Bit value | | | Description | | +| --- | --- | --- | --- | --- | --- | +| | ‘0’ | | | Disabled | | +| | ‘1’ | | | Enabled | | + +The value ‘0’ MUST signify that the actual handle cannot open the door locally. The value ‘1’ MUST signify that the actual handle can open the door locally. + +A supporting node MAY advertise just a subset of the available Door Handles Mode values. A controlling node MUST accept all Door Handles Mode values. + +Inside Door Handles Mode (4 bits) + +This field MUST advertise the status of each individual inside door handle. + +[The encoding of the Inside Door Handles Mode bitmask field MUST be according to Table 34 and Table 35.](04.29-door-lock-command-class-version-1-2.md#4294-door-lock-operation-report-command) + +A supporting node MAY advertise just a subset of the available Door Handles Mode values. A controlling node MUST accept all Door Handles Mode values. + +Door Condition (8 bits) + +The Door Condition field MUST advertise the status of the door lock components. + +[The encoding of the Door Condition bitmask field MUST be according to Table 36.](04.29-door-lock-command-class-version-1-2.md#4294-door-lock-operation-report-command) + +Table 36, Door Condition bitmask + +| | | | | Bit 7..3 | | | Bit 2 | | | Bit 1 | | | Bit 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| | bit = ‘0’ | | | Reserved | | | Latch Open | | | Bolt Locked | | | Door Open | | +| | bit = ‘1’ | | | Reserved | | | Latch Closed | | | Bolt Unlocked | | | Door Closed | | + +All other bits are reserved and MUST be set to zero by a sending node. Reserved bits MUST be ignored by a receiving node. + +A supporting node MAY advertise just a subset of the available Door Condition values. A controlling node MUST accept all Door Condition values. Lock Timeout Minutes (8 bits) + +This field MUST advertise the remaining time before the door lock will automatically be locked again. + +[The encoding of the Lock Timeout Minutes field MUST be according to Table 37. The time the supporting](04.29-door-lock-command-class-version-1-2.md#4294-door-lock-operation-report-command) node stays unlocked MUST be determined by combining the Lock Timeout Minutes and Lock Timeout Seconds fields. + +Table 37, Door Lock Operation Report :: Lock Timeout Minutes + +| | Value | | | Operation | | +| --- | --- | --- | --- | --- | --- | +| 0x00..0xFC | | | Unlocked 0 .. 253 minutes (Operation Type = Timed Operation) | | | +| 0xFE | | | No unlocked period (Operation Type = Constant Operation) | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +A supporting node MAY advertise just a subset of the available Lock Timeout values. A controlling node MUST accept all Lock Timeout values. + +Lock Timeout Seconds (8 bits) + +This field MUST advertise the remaining time before the door lock will automatically be locked again. + +[The encoding of the Lock Timeout Seconds field MUST be according to Table 38. The time to stay](04.29-door-lock-command-class-version-1-2.md#4294-door-lock-operation-report-command) unlocked MUST be determined by combining the Lock Timeout Minutes and Lock Timeout Seconds fields. + +Table 38, Door Lock Operation Report :: Lock Timeout Seconds + +| | Value | | | Operation | | +| --- | --- | --- | --- | --- | --- | +| 0..59 (0x00..0x3B) | | | Unlocked 0 .. 59 seconds (Operation Type = Timed Operation) | | | +| 254 (0xFE) | | | No unlocked period (Operation Type = Constant Operation) | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +A supporting node MAY advertise just a subset of the available Lock Timeout values. A controlling de MUST accept all Lock Timeout values. + +## 4.29.5 Door Lock Configuration Set Command + +This command is used to set the configuration of a supporting door lock device. + +A door lock device MUST be able to operate with the factory default settings. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DOOR LOCK _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DOOR LOCK CONFIGURATION SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Operation Type | | | | | | | | | | | | | | | | | | | | | | | | +| Outside Door Handles Mode | | | | | | | | | | | | Inside Door Handles Mode | | | | | | | | | | | | +| Lock Timeout Minutes | | | | | | | | | | | | | | | | | | | | | | | | +| Lock Timeout Seconds | | | | | | | | | | | | | | | | | | | | | | | | + +Operation Type (1 byte) + +[The Operation Type field MUST be set according to Table 39. When timed operation is specified, the](04.29-door-lock-command-class-version-1-2.md#4295-door-lock-configuration-set-command) Lock Timeout Minutes and Lock Timeout Seconds fields MUST be set to valid values. + +Table 39, Door Lock Operation Type + +| Operation Type | Description | | Valid Lock | | +| --- | --- | --- | --- | --- | +| | | | Timeout values | | +| 0x01 | Constant operation | Minutes = 0xFE Seconds= 0xFE | | | +| 0x02 | Timed operation | Minutes = 0x00..0xFD Seconds= 0x00..0x3B | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +A supporting node MAY accept just a subset of the available Operation Type values. A supporting node MUST accept the Operation Type value 0x01. + +Outside Door Handles Mode (4 bits) + +This field is used to advertise the status of each individual outside door handle. + +[The encoding of the Outside Door Handles Mode bitmask field MUST be according to Table 34 and Table 35.](04.29-door-lock-command-class-version-1-2.md#4294-door-lock-operation-report-command) + +A supporting node MAY ignore the Door Handles Mode value. + +Inside Door Handles Mode (4 bits) + +This field MUST advertise the status of each individual inside door handle. + +[The encoding of the Inside Door Handles Mode bitmask field MUST be according to Table 34 and Table 35.](04.29-door-lock-command-class-version-1-2.md#4294-door-lock-operation-report-command) A supporting node MAY ignore the Door Handles Mode value. + +Lock Timeout Minutes (1 byte) + +This field MUST specify the time that a door lock must wait before automatically being locked again. + +[The encoding of the Lock Timeout Minutes field MUST be according to Table 37. The time to stay](04.29-door-lock-command-class-version-1-2.md#4294-door-lock-operation-report-command) unlocked MUST be determined by combining the Lock Timeout Minutes and Lock Timeout Seconds fields. + +A supporting node MAY ignore the Lock Timeout values if it implements only the Operation Type = 0x01 (Constant operation). + +Lock Timeout Seconds (1 byte) + +This field MUST specify the time that a door lock must wait before automatically being locked again. + +[The encoding of the Lock Timeout Seconds field MUST be according to Table 38. The time to stay](04.29-door-lock-command-class-version-1-2.md#4294-door-lock-operation-report-command) unlocked MUST be determined by combining the Lock Timeout Minutes and Lock Timeout Seconds fields. + +A supporting node MAY ignore the Lock Timeout values if it implements only the Operation Type = 0x01 (Constant operation). + +## 4.29.6 Door Lock Configuration Get Command + +This command is used to request the configuration parameters of a door lock device. + +The Door Lock Configuration Report command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DOOR LOCK _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DOOR LOCK CONFIGURATION GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.29.7 Door Lock Configuration Report Command + +This command is used to advertise the configuration parameters of a door lock device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DOOR LOCK _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DOOR LOCK CONFIGURATION REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Operation Type | | | | | | | | | | | | | | | | | | | | | | | | +| Outside Door Handles Mode | | | | | | | | | | | | Inside Door Handles Mode | | | | | | | | | | | | +| Lock Timeout Minutes | | | | | | | | | | | | | | | | | | | | | | | | +| Lock Timeout Seconds | | | | | | | | | | | | | | | | | | | | | | | | + +[For fields’ description, refer to 4.29.5 Door Lock Configuration Set Command.](04.29-door-lock-command-class-version-1-2.md#4295-door-lock-configuration-set-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.30-door-lock-command-class-version-3.md b/docs/specs/command-class-specification/04-command-class-definitions/04.30-door-lock-command-class-version-3.md new file mode 100644 index 0000000..cb55631 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.30-door-lock-command-class-version-3.md @@ -0,0 +1,54 @@ + +# 4.30 Door Lock Command Class, version 3 + +The Door Lock Command Class is used to operate and configure a door lock device. + +[The Door Lock Command Class is an actuator control command class. Refer to 3.6.](../03-command-class-overview/03.06-actuator-control.md#36-actuator-control) + +Commands and fields not described in version 3 remain unchanged from version 2. + +## 4.30.1 Compatibility considerations + +A node supporting the Door Lock Command Class, version 3 MUST support the Door Lock Command Class, version 2. + +Version 3 adds duration and target value reporting to the Door Lock Operation Report Command. + +## 4.30.2 Door Lock Operation Report Command + +This command is used to advertise the status of a door lock device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DOOR LOCK _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DOOR LOCK OPERATION REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Current Door Lock Mode | | | | | | | | | | | | | | | | | | | | | | | | +| Outside Door Handles Mode | | | | | | | | | | | | Inside Door Handles Mode | | | | | | | | | | | | +| Door Condition | | | | | | | | | | | | | | | | | | | | | | | | +| Lock Timeout Minutes | | | | | | | | | | | | | | | | | | | | | | | | +| Lock Timeout Seconds | | | | | | | | | | | | | | | | | | | | | | | | +| Target Door Lock Mode | | | | | | | | | | | | | | | | | | | | | | | | +| Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Fields not described below remain unchanged from previous versions. + +Current Door Lock Mode (8 bits) + +The Current Door Lock Mode field MUST advertise the current mode of the door lock device. + +[The encoding of this field MUST be according to Table 33.](04.29-door-lock-command-class-version-1-2.md#4294-door-lock-operation-report-command) + +An Operation Set Command may be used to initiate a transition to a new target mode. The device may be queried for its current mode while in transition to a new mode. The response to an Operation Get SHOULD be the current mode of the device hardware, e.g. Door/Lock State Unknown. (applies to Version 2 and newer). Target Door Lock Mode (8 bits) + +The Target Door Lock Mode field MUST advertise the target mode of an ongoing transition or the most recent transition. + +[The encoding of this field MUST be according to Table 33.](04.29-door-lock-command-class-version-1-2.md#4294-door-lock-operation-report-command) + +Duration (8 bits) + +The Duration field SHOULD advertise the remaining time before the target mode is reached. [The encoding of this field MUST be according to Table 8.](../03-command-class-overview/03.07-common-fields-and-encoding.md#373-duration-encoding) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.31-door-lock-logging-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.31-door-lock-logging-command-class-version-1.md new file mode 100644 index 0000000..1bff0ac --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.31-door-lock-logging-command-class-version-1.md @@ -0,0 +1,171 @@ + +# 4.31 Door Lock Logging Command Class, version 1 + +This Door Lock Logging Command Class provides an audit trail in an access control application. Each time an event takes place at the door lock, the system logs the user's ID, date, time etc. + +## 4.31.1 Door Lock Logging Records Supported Get Command + +This command is used to request the number of records that the audit trail supports. + +The Door Lock Logging Records Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DOOR LOCK LOGGING _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DOOR LOCK LOGGING RECORDS SUPPORTED GET _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.31.2 Door Lock Logging Records Supported Report Command + +This command is used to report the maximum number of reports the audit trail supports. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DOOR LOCK LOGGING _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = DOOR LOCK LOGGING RECORDS SUPPORTED REPORT _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Max records stored | | | | | | | | | | | | | | | | | | | | | | | | + +Max records stored (8 bits) + +The number of records the audit trail supports stored in a queue. + +## 4.31.3 Door Lock Logging Record Get Command + +This command is used to request the audit trail. + +The Door Lock Logging Record Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DOOR LOCK LOGGING _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = RECORD GET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Record number | | | | | | | | | | | | | | | | | | | | | | | | + +Record number (8 bits) + +The Record number field indicates the record to be requested. + +A value 0 – Max records stored is acceptable with a value of 0 being the most recent entry. When requesting with a value of 0, the report will contain the record number so the latest record is known. + +## 4.31.4 Door Lock Logging Record Report Command + +This command returns records from the audit trail. + +To provide flexibility the user associated with the record may be identified by one of two methods: the user identifier or the user code. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS DOOR LOCK LOGGING _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = RECORD REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Record number | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp - Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp - Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp – Month | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp – Day | | | | | | | | | | | | | | | | | | | | | | | | +| Record status | | | | | | | | | Timestamp - Hour Local Time | | | | | | | | | | | | | | | +| Timestamp - Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Timestamp - Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Event Type | | | | | | | | | | | | | | | | | | | | | | | | +| User Identifier | | | | | | | | | | | | | | | | | | | | | | | | +| User Code Length | | | | | | | | | | | | | | | | | | | | | | | | +| USER CODE 1 _ | | | | | | | | | | | | | | | | | | | | | | | | +| .. | | | | | | | | | | | | | | | | | | | | | | | | +| USER CODE N _ | | | | | | | | | | | | | | | | | | | | | | | | + +Record number (8 bits) + +Record number requested (1- 255). + +Timestamp - Year (16 bits) + +Specify the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. + +Timestamp - Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December). + +Timestamp - Day (8 bits) + +Specify the day of the month between 01 and 31. Record status (3-bits) + +The Record Status field is used to indicate if legal data is stored in the record. + +| | Record State | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0 | | | Requested record is empty. | | | +| 1 | | | Requested record holds legal data. | | | + +Timestamp - Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00-23) in local time. + +Timestamp - Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00-59) in local time. + +Timestamp - Second Local Time (8 bits) + +Specify the number of complete seconds since the start of the minute (00-59) in local time. The value 60 used to keep UTC from wandering away is not supported. + +Note: If RTC (Real Time Clock) all values in Time Stamp record SHOULD be set to 0. Most recent Record MUST be stored under Record Number 1. + +User Identifier (8 bits) + +The User Identifier is used to recognize the user identity. A valid User Identifier MUST be a value starting from 1 to the maximum number of users supported by the device; refer to the User Code Command Class. A User Identifier of 0 is acceptable when the record does not need to identify a user or if the User Code is provided in this report. + +User Code Length (8 bits) + +The User Code Length field indicates the number of bytes used to hold the User Code. A length of 0 is acceptable when the record does not need to identify a User Code or when the User Identifier field is non-zero. + +USER_CODE (N bytes) + +These fields contain the user code. Minimum code length is 4 and maximum 10 ASCII digits. For further details about the user code, refer to the User Code Command Class. Event Type (8 bits) + +[This field MUST be encoded according to Table 40.](04.31-door-lock-logging-command-class-version-1.md#4314-door-lock-logging-record-report-command) + +Table 40, Door Lock Logging Record Report::Event Type encoding + +| | Event type | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 1 | | | Lock Command: Keypad access code verified lock command | | | +| 2 | | | Unlock Command: Keypad access code verified unlock command | | | +| 3 | | | Lock Command: Keypad lock button pressed | | | +| 4 | | | Unlock command: Keypad unlock button pressed | | | +| 5 | | | Lock Command: Keypad access code out of schedule | | | +| 6 | | | Unlock Command: Keypad access code out of schedule | | | +| 7 | | | Keypad illegal access code entered | | | +| 8 | | | Key or latch operation locked (manual) | | | +| 9 | | | Key or latch operation unlocked (manual) | | | +| 10 | | | Auto lock operation | | | +| 11 | | | Auto unlock operation | | | +| 12 | | | Lock Command: Z-Wave access code verified | | | +| 13 | | | Unlock Command: Z-Wave access code verified | | | +| 14 | | | Lock Command: Z-Wave (no code) | | | +| 15 | | | Unlock Command: Z-Wave (no code) | | | +| 16 | | | Lock Command: Z-Wave access code out of schedule | | | +| 17 | | | Unlock Command Z-Wave access code out of schedule | | | +| 18 | | | Z-Wave illegal access code entered | | | +| 19 | | | Key or latch operation locked (manual) | | | +| 20 | | | Key or latch operation unlocked (manual) | | | +| 21 | | | Lock secured | | | +| 22 | | | Lock unsecured | | | +| 23 | | | User code added | | | +| 24 | | | User code deleted | | | +| 25 | | | All user codes deleted | | | +| 26 | | | Master code changed | | | +| 27 | | | User code changed | | | +| 28 | | | Lock reset | | | +| 29 | | | Configuration changed | | | +| 30 | | | Low battery | | | +| 31 | | | New Battery installed | | | + +Not all events types are supported and it is up to manufacturer to decide which ones are to be supported. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.32-energy-production-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.32-energy-production-command-class-version-1.md new file mode 100644 index 0000000..31feb22 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.32-energy-production-command-class-version-1.md @@ -0,0 +1,79 @@ + +# 4.32 Energy Production Command Class, version 1 + +The Energy Production Command Class is used to retrieve various production data from the device. + +## 4.32.1 Energy Production Get Command + +This command is used to request various production data from the device. + +The Energy Production Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ENERGY PRODUCTION _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ENERGY PRODUCTION GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number | | | | | | | | | | | | | | | | | | | | | | | | + +Parameter Number (8 bits) + +The parameter number specifies the kind of production data to retrieve. Currently the following parameter numbers are defined: + +| | Parameter Number | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Instant energy production | | | +| 0x01 | | | Total energy production | | | +| 0x02 | | | Energy production today | | | +| 0x03 | | | Total production time | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +## 4.32.2 Energy Production Report Command + +This command is used to retrieve various production data from the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ENERGY PRODUCTION _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ENERGY PRODUCTION REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Number | | | | | | | | | | | | | | | | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | | | | +| Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Value N | | | | | | | | | | | | | | | | | | | | | | | | + +Parameter Number (8 bits) + +Refer to description under the Energy Production Get Command. + +Precision (3 bits) + +The precision field describes what the precision of the value is. The number indicates the number of decimals. The decimal value 1025 with precision 2 is therefore equal to 10.25. + +Scale (2 bits) + +The Scale field indicates the scale used for the specified parameter number: + +| | Parameter Number | | | Scale | | | Description | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | 0x00 | | | W | | | +| 0x01 | | | 0x00 | | | Wh | | | +| 0x02 | | | 0x00 | | | Wh | | | +| 0x03 | | | 0x00 | | | Seconds | | | +| | | | 0x01 | | | Hours | | | + +Size (3 bits) + +The size field indicates the number of bytes used for the value. This field can take values from 1 (001b), 2 (010b) or 4 (100b). + +Value (N bytes) + +[The value is MUST be treated as a signed field (Table 10). The field MAY be 1, 2 or 4 bytes in size. The](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) first byte is the most significant byte. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.33-entry-control-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.33-entry-control-command-class-version-1.md new file mode 100644 index 0000000..5dbbf79 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.33-entry-control-command-class-version-1.md @@ -0,0 +1,356 @@ + +# 4.33 Entry Control Command Class, version 1 + +The Entry Control Command Class defines a method for advertising user input to a central Entry Control application and for the discovery of capabilities. User input may be button presses, RFID tags or other means. + +It is RECOMMENDED that this command class is only supported via secure communication. This recommendation may be raised to a stronger requirement at the Device Class or Device Type level. + +The Entry Control Command Class provides the following commands: + + Key Supported Get/Report – Used by the controller to request which ASCII keys are present on the Entry Control device.  Event Supported Get/Report – Used by the controller to request which Event Types are supported by the Entry Control device.  Configuration Set/Get/Report – Used by the controller to configure the Entry Control device  Notification Command – Used by the Entry Control device to notify the controller of inputs. + +## 4.33.1 Interoperability Considerations + +It is RECOMMENDED that an Entry Control input device that implements the Entry Control Command Class also implements the Indicator Command Class, version 2. + +If implementing the Indicator Command Class, version 2, it is RECOMMENDED that all indicator resources are addressable via the Indicator Command Class, version 2. The input device MAY implement local control of indicator resources. If the Indicator Command Class, version 2 is supported, the first received Indicator Set command MUST disable all local control of indicator resources – except for interface feedback functionality like a short beep on each button press. + +Transmissions may fail due to central control application fault or due to RF jamming. It is RECOMMENDED that an Entry Control input device provides local user feedback if the transmission of notifications to the central control application fails. + +If the device only features light indicators, it is RECOMMENDED that all light flashes at 2Hz for at least 5 seconds to indicate transmission error. + +If the device features a buzzer, it is RECOMMENDED that the buzzer generates sound pulses at a rate of 2Hz for at least 5 seconds to indicate transmission error. + +If implementing the indicator Command Class, version 2, in devices based on Role Type RSS (using Wakeup Command Class), the control of indicators must be synchronized with the Wakeup Notification. The controller must therefore wait for the Wakeup Notification, before it can control the indictors. The device implementing the indicator Command Class must therefore send the Wakeup Notification after sending the Entry Control Notification Command, in case the device expects to be controlled. + +## 4.33.2 Security Considerations + +An attacker could theoretically determine the length of manually entered user credentials even if they are transmitted via encryption. It is therefore MANDATORY to add padding bytes to ASCII strings so that all transferred ASCII strings are structured as one or more blocks of 16 characters. The ASCII code 0xFF MUST be reserved for padding purposes and it MUST NOT be used for any other purposes. + +## 4.33.3 Handling user supplied data + +The Entry Control device must cache the user input before sending the full entry in one Notification Frame. A user input MUST therefore have a termination, which MAY be determined by: + + The Key Cache Size is exceeded  The Key Cache Timeout is exceeded  A Command Button is pressed  User data is received by other means, e.g. from an RFID tag + +Key Cached Size: + +The Key Cached Size is configured to specify the number of user inputs before the Notification Frame is sent. After sending the Notification Frame the cache must be cleared and subsequent user inputs MUST be considered a new entry. + +The Key Cached Size May be configured to 1, in which case a Notification Frame is send for each user input. + +It is RECOMMENDED to have a default Key Cached Size of 4, in which case the Notification Frame will be send after 4 entries. + +Key Timeout: + +The Key Timeout is configured to specify the maximum time between user inputs. If the time between user inputs exceeds the Timeout, the cached user inputs will be send in a Notification Frame. After sending the Notification Frame the cache must be cleared and subsequent user inputs MUST be considered a new entry. + +Based on Command Button: + +A user input may be terminated by the user pressing on of the Command Buttons like ENTER or ARM_ALL. The cached entry will be sent in a Notification Frame immediately after the user presses the Command Button. After sending the Notification Frame the cache must be cleared and subsequent user inputs MUST be considered a new entry. + +Based on RFID: + +When presenting an RFID tag, the ID will be read from the tag, and this terminates the user input. So the cached ID ‘s from the RFID tag data can immediately be sent in a Notification Frame. After sending the Notification Frame the cache must be cleared and subsequent user inputs MUST be considered a new entry. + +Presenting an RFID tag may also terminate an ongoing user input. For instance, a user may enter four characters and subsequently present an RFID tag. In that case, the four entries must first be sent in one Notification Frame, and subsequently the ID ‘s from the RFID tag data is sent in a second Notification Frame. + +## 4.33.4 Handling Incorrect Entry + +A user may do an incorrect entry e.g. the credential is 1234 but the user enters 1734. In this case the terminal may provide a “delete” option, to allow the user to fix or re-enter the credential. If a “delete” option is not provided, the invalid code must first be send, followed by a new (correct) entry. + +The terminal must not assume that the receiving controller does error handling like 1+7+Delete+2+3+4 = 1234. + +## 4.33.5 Entry Control Notification Command + +This command is used to advertise user input. + +Depending on the Event Type, this command MAY carry manually entered user credentials. + +| | 7 | | | 6 | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ENTRY CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | +| Command = ENTRY CONTROL NOTIFICATION _ _ | | | | | | | | | | | | | | | | | | | | | | +| Sequence Number | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | Data Type | | | | | | +| Event Type | | | | | | | | | | | | | | | | | | | | | | +| Event Data Length | | | | | | | | | | | | | | | | | | | | | | +| Event Data 1 (optional) | | | | | | | | | | | | | | | | | | | | | | +| ... | | | | | | | | | | | | | | | | | | | | | | +| Event Data N (optional) | | | | | | | | | | | | | | | | | | | | | | + +Sequence Number (8 bit) + +The sequence number MUST be incremented each time a new command of this type is issued. + +The value MUST be in the range 0..255. The initial value MAY be any value in the range 0..255. A receiving device MUST use the Sequence Number to detect and ignore duplicates. + +Reserved + +This field MUST be set to 0 by a sending device and MUST be ignored by a receiving device. + +Data Type (2 bits) + +This field is used to advertise the type of data (if any) that is appended to this command. + +Table 41, Entry Control Notification :: Event Data Type + +| | Data Type | | Description | | +| --- | --- | --- | --- | --- | +| 0x00 | | NA | No data included | | +| 0x01 | | RAW | 1 to 32 bytes of arbitrary binary data | | +| 0x02 | | ASCII | 1 to 32 ASCII encoded characters. ASCII codes MUST be in the value range 0x00- 0xF7. The string MUST be padded with the value 0xFF to fit 16 byte blocks when sent in a notification. | | +| 0x03 | | MD5 | 16 byte binary data encoded as a MD5 hash value. | | + +All other values are reserved and MUST NOT be used by a sending device. Reserved values MUST be ignored by a receiving device. Event Type (4 bit) + +This field is used to advertise the actual Event Type. + +[The field MUST be encoded according to section 4.33.13](04.33-entry-control-command-class-version-1.md#43313-event-types) + +Event Data Length (8 bit) + +This field MUST advertise the length of the Event Data field in bytes. + +The value MUST be in the range 0..32. If no data bytes are included, this field MUST be set to 0. + +Event Data (n bytes) + +This field is used to carry data related to the event, e.g. received from an RFID tag. + +The length of this field MUST comply with the length advertised by the Event Data Length field. The format of this field MUST comply with the data format advertised by the Data Type field. + +## 4.33.6 Entry Control Key Supported Get Command + +This command is used to query the keys that a device implements for entry of user credentials. + +The Entry Control Key Supported Report command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ENTRY CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ENTRY CONTROL KEY SUPPORTED GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.33.7 Entry Control Key Supported Report Command + +This command is used to advertise the keys that a device implements for entry of user credentials. + +A management interface may determine the available keys for credential entry from this command. The range of available Command Keys may be determined via the Entry Control Event Supported Report Command. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ENTRY CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ENTRY CONTROL KEY SUPPORTED REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Key Supported Bit Mask Length | | | | | | | | | | | | | | | | | | | | | | | | +| Key Supported Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Key Supported Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | | + +Key Supported Bit Mask Length + +This field is used to advertise the number of Key Supported Bit Mask Bytes to follow. + +Only the Key Supported Bit Mask bytes until the last supported ASCII key SHOULD be included. + +Key Supported Bit Mask (Variable length) + +This field is used to advertise the keys that a device implements for entry of user credentials. + +The Key Supported Bit Mask field MUST advertise ASCII codes that represent the supported keys. + + Bit 0 in Bit Mask 1 indicates that the supporting device may issue ASCII code 0  Bit 1 in Bit Mask 1 indicates that the supporting device may issue ASCII code 1  … + + Bit 7 in Bit Mask 16 indicates that the supporting device may issue ASCII code 127 + +## 4.33.8 Entry Control Event Supported Get Command + +This command is used to request the supported Events of a device. + +The Entry Control Event Supported Report command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ENTRY CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ENTRY CONTROL EVENT SUPPORTED GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.33.9 Entry Control Event Supported Report Command + +This command is used to advertise the supported Event Types. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ENTRY CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ENTRY CONTROL EVENT SUPPORTED REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | Data Type Supported Bit Mask Length | | | | | | +| Data Type Supported Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Data Type Supported Bit Mask M | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Event Supported Bit Mask Length | | | | | | | | | | | | | | | +| Event Type Supported Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Event Type Supported Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | | +| Key Cached Size supported Minimum | | | | | | | | | | | | | | | | | | | | | | | | +| Key Cached Size supported Maximum | | | | | | | | | | | | | | | | | | | | | | | | +| Key Cached Timeout supported Minimum | | | | | | | | | | | | | | | | | | | | | | | | +| Key Cached Timeout supported Maximum | | | | | | | | | | | | | | | | | | | | | | | | + +Data Type Supported Bit Mask Length (2 bits) + +This field is used to advertise the number of Data Type Supported Bit Mask Bytes to follow. + +Reserved + +This field MUST be set to 0 by a sending device and MUST be ignored by a receiving device. + +Data Type Supported Bit Mask (Variable length) + +This field is used to advertise the supported Data Types. + + Bit 0 in Bit Mask 1 indicates if Data Type 0 is supported  Bit 1 in Bit Mask 1 indicates if Data Type 1 is supported  … + +[For the definition of Data Type IDs, refer to Table 41.](04.33-entry-control-command-class-version-1.md#4335-entry-control-notification-command) Event Type Supported Bit Mask Length (1 byte) + +This field is used to advertise the number of Event Type Supported Bit Mask Bytes to follow. + +Event Type Supported Bit Mask (variable length) + +This field is used to advertise the supported Event Type. + + Bit 0 in Bit Mask 1 indicates if Event Type 0 is supported  Bit 1 in Bit Mask 1 indicates if Event Type 1 is supported  … + +[For the definition of Event Type IDs, refer to Table 42.](04.33-entry-control-command-class-version-1.md#43313-event-types) + +Key Cached Size Supported Minimum + +The minimum configurable number of key entries before the CACHED_KEYS notification is sent. [Refer to 4.33.10](04.33-entry-control-command-class-version-1.md#43310-entry-control-configuration-set-command) + +Key Cached Size Supported Maximum + +The maximum configurable number of key entries before the CACHED_KEYS notification is sent. [Refer to 4.33.10](04.33-entry-control-command-class-version-1.md#43310-entry-control-configuration-set-command) + +Key Cached Timeout Supported Minimum + +The minimum configurable timeout before the CACHED_KEYS notification is sent. [Refer to 4.33.10](04.33-entry-control-command-class-version-1.md#43310-entry-control-configuration-set-command) + +Key Cached Timeout Supported Maximum + +The maximum configurable timeout before the CACHED_KEYS notification is sent. [Refer to 4.33.10](04.33-entry-control-command-class-version-1.md#43310-entry-control-configuration-set-command) + +## 4.33.10 Entry Control Configuration Set Command + +This command is used to configure Event Type specific parameters. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ENTRY CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ENTRY CONTROL CONFIGURATION SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Key Cache Size | | | | | | | | | | | | | | | | | | | | | | | | +| Key Cache Timeout | | | | | | | | | | | | | | | | | | | | | | | | + +Key Cache Size (1 byte) + +This field specifies the number of characters the key cache MUST store before sending data to the central control application. Data MUST be sent when the number of characters in the cache matches or exceeds the value of this field. + +The value MUST be in the range 1..32. The default value of this field SHOULD be 4. + +In deployments where characters are entered first and a command button is pressed subsequently, it is RECOMMENDED that this field is set to 32 and that the Key Cache Timeout is set to 2 seconds. + +Key Cache Timeout (1 byte) + +This field specifies the number of seconds the key cache MUST wait for additional characters before sending data to the central control application. Data MUST be sent if a Key Cache Timeout occurs. + +The Key Cache Timeout MUST be measured from the most recent reception of a character. + +The value SHOULD be in the range 1..10 seconds. The default value SHOULD be 2 seconds. + +## 4.33.11 Entry Control Configuration Get Command + +This command is used to request the operational mode of a device. + +The Entry Control Configuration Report command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ENTRY CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ENTRY CONTROL CONFIGURATION GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.33.12 Entry Control Configuration Report Command + +This command is used to advertise the current operational mode of a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS ENTRY CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = ENTRY CONTROL CONFIGURATION REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Key Cache Size | | | | | | | | | | | | | | | | | | | | | | | | +| Key Cache Timeout | | | | | | | | | | | | | | | | | | | | | | | | + +Key Cache Size (1 byte) + +[Refer to 4.33.10 Entry Control Configuration Set Command.](04.33-entry-control-command-class-version-1.md#43310-entry-control-configuration-set-command) + +Key Cache Timeout (1 byte) + +[Refer to 4.33.10 Entry Control Configuration Set Command.](04.33-entry-control-command-class-version-1.md#43310-entry-control-configuration-set-command) + +## 4.33.13 Event Types + +[The Event Types MUST be encoded according to Table 42.](04.33-entry-control-command-class-version-1.md#43313-event-types) + +Table 42, Event Type and Event identifiers + +| Event Type | | | | Recommended | | | Event Data | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| | | | | Button Label | | | (optional) | | +| 0x00 | CACHING | | - | | | - | | | +| 0x01 | CACHED KEYS _ | | - | | | ASCII bytes | | | +| 0x02 | ENTER | | Enter | | | ASCII bytes | | | +| 0x03 | DISARM ALL _ | | Disarm | | | ASCII bytes | | | +| 0x04 | ARM ALL _ | | Arm | | | ASCII bytes | | | +| 0x05 | ARM AWAY _ | | Away | | | ASCII bytes | | | +| 0x06 | ARM HOME _ | | Home | | | ASCII bytes | | | +| 0x07 | EXIT DELAY _ | | Arm Delay _ | | | ASCII bytes | | | +| 0x08 | ARM 1 _ | | Arm zone 1 | | | ASCII bytes | | | +| 0x09 | ARM 2 _ | | Arm zone 2 | | | ASCII bytes | | | +| 0x0A | ARM 3 _ | | Arm zone 3 | | | ASCII bytes | | | +| 0x0B | ARM 4 _ | | Arm zone 4 | | | ASCII bytes | | | +| 0x0C | ARM 5 _ | | Arm zone 5 | | | ASCII bytes | | | +| 0x0D | ARM 6 _ | | Arm zone 6 | | | ASCII bytes | | | +| 0x0E | RFID | | - | | | As advertised by the Data Type field | | | +| 0x0F | BELL | |  | | | - | | | +| 0x10 | FIRE | | Fire | | | - | | | +| 0x11 | POLICE | | Police | | | - | | | +| 0x12 | ALERT PANIC _ | | | | | - | | | +| 0x13 | ALERT MEDICAL _ | | | | | - | | | +| 0x14 | GATE OPEN _ | | Open, Up. ’O’ or similar | | | ASCII bytes | | | +| 0x15 | GATE CLOSE _ | | Close, Down, ’C’ or similar | | | ASCII bytes | | | +| 0x16 | LOCK | | | | | ASCII bytes | | | +| 0x17 | UNLOCK | | | | | ASCII bytes | | | +| 0x18 | TEST | | Test | | | ASCII bytes | | | +| 0x19 | CANCEL | | Cancel | | | ASCII bytes | | | + +All other values are reserved and MUST NOT be used by a sending device. Reserved values MUST be ignored by a receiving device. + +Event Type CACHING + +The CACHING Event Type is used to indicate to the central controller that the user has started entering credentials, and that caching is initiated. This allows the central controller to change the indications on the Entry Control device through the indicator Command Class, or to change the status of the central controller user interface. + +If Key Cached Size it set to 1, the CACHING event notification MUST NOT be sent. Instead each individual credential byte MUST be sent in its own CACHED_KEYS event notification. + +Event Type CACHED_KEYS + +The CACHED_KEYS Event Type is used to send user inputs in a Notification Frame. The CACHED_KEYS is sent when the user input is terminated by one of the following reasons: + + The Key Cache Size is exceeded  The Key Cache Timeout is exceeded  A command button is pressed  User data is received by other means, e.g. from an RFID tag diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.34-geographic-location-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.34-geographic-location-command-class-version-1.md new file mode 100644 index 0000000..059348c --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.34-geographic-location-command-class-version-1.md @@ -0,0 +1,59 @@ + +# 4.34 Geographic Location Command Class, version 1 + +The Geographic Location Command Class is used to read latitude and longitude from another device. The latitude and longitude may also be set according to the geographic location in question. Date and geographic location may be used to calculate sunrise and sunset for e.g. automatic lighting control. + +## 4.34.1 Geographic Location Set Command + +This command is used to set latitude and longitude. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS GEOGRAPHIC LOCATION _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = GEOGRAPHIC LOCATION SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Longitude Degrees | | | | | | | | | | | | | | | | | | | | | | | | +| Long. Sign | | | Longitude Minutes | | | | | | | | | | | | | | | | | | | | | +| Latitude Degrees | | | | | | | | | | | | | | | | | | | | | | | | +| Lat. Sign | | | Latitude Minutes | | | | | | | | | | | | | | | | | | | | | + +Longitude (16 bits) + +The longitude determines one's location on the earth's surface, East or West of the Greenwich Meridian. The Greenwich Meridian is located at the Greenwich observatory, in Greenwich, England to be the geographic point for where East and West meet. Therefore, Greenwich Meridian is indicated as 0° longitude. Longitude values for points East of the Meridian are always positive, while points West of the Meridian are always negative. Valid ranges are for degrees (from -180 to 180) and minutes (0-59). Other values will be interpreted as 0. + +Latitude (16 bits) + +The latitude determines one's location on the earth's surface, North or South of the Equator. Latitude is measured between -90° South, and +90° North of the Equator point (0°). Valid ranges are for degrees (from -90 to 90) and minutes (0-59). Other values will be interpreted as 0. + +## 4.34.2 Geographic Location Get Command + +This command is used to request latitude and longitude from a device. + +The Geographic Location Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS GEOGRAPHIC LOCATION _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = GEOGRAPHIC LOCATION GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.34.3 Geographic Location Report Command + +This command returns latitude and longitude from a device in a Z-Wave network. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS GEOGRAPHIC LOCATION _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = GEOGRAPHIC LOCATION REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Longitude Degrees | | | | | | | | | | | | | | | | | | | | | | | | +| Long. Sign | | | Longitude Minutes | | | | | | | | | | | | | | | | | | | | | +| Latitude Degrees | | | | | | | | | | | | | | | | | | | | | | | | +| Lat. Sign | | | Latitude Minutes | | | | | | | | | | | | | | | | | | | | | + +Refer to description under the Geographic Location Set Command. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.35-hrv-status-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.35-hrv-status-command-class-version-1.md new file mode 100644 index 0000000..4a6d318 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.35-hrv-status-command-class-version-1.md @@ -0,0 +1,118 @@ + +# 4.35 HRV Status Command Class, version 1 + +The residential Heat Recovery Ventilation (HRV) Status Command Class is used to read out a number of parameters in the ventilation system. + +## 4.35.1 HRV Status Get Command + +This command is used to request specific parameters from the ventilation system. + +The HRV Status Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HRV STATUS _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HRV STATUS GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Status Parameter | | | | | | | | | | | | | | | | | | | | | | | | + +Status Parameter (8 bits) + +The status parameter used to indicate which status parameter that is requested. + +| | Value | | | Status Parameter | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Outdoor Air temperature | | | +| 0x01 | | | Supply Air (to room) temperature | | | +| 0x02 | | | Exhaust Air (from room) temperature | | | +| 0x03 | | | Discharge Air temperature | | | +| 0x04 | | | Room temperature | | | +| 0x05 | | | Relative Humidity in room | | | +| 0x06 | | | Remaining filter life | | | + +## 4.35.2 HRV Status Report Command + +This command is used to report a specific status parameter in response to a HRV Status Get. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HRV STATUS _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HRV STATUS REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Status Parameter | | | | | | | | | | | | | | | | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | | | | +| Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| …. | | | | | | | | | | | | | | | | | | | | | | | | +| Value N | | | | | | | | | | | | | | | | | | | | | | | | + +Status Parameter (8 bits) + +[The status parameter used to indicate which status parameter that is reported. Refer to 4.35.1 HRV Status Get for possible values.](04.35-hrv-status-command-class-version-1.md#4351-hrv-status-get-command) + +Precision (3 bits) + +The precision field describes what the precision of the setpoint value is. The number indicates the number of decimals. The decimal value 1025 with precision 2 is therefore equal to 10.25. + +Scale (2 bits) + +The scale field indicates the scale used the list of possible scales are given below: + +| | Status Parameter | | | Scale | | | Value | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Outdoor Air temperature | | | Celsius (C) | | | 0 | | | +| | | | Fahrenheit (F) | | | 1 | | | +| Supply Air (to room) temperature | | | Celsius (C) | | | 0 | | | +| | | | Fahrenheit (F) | | | 1 | | | +| Exhaust Air (from room) temperature | | | Celsius (C) | | | 0 | | | +| | | | Fahrenheit (F) | | | 1 | | | +| Discharge Air temperature | | | Celsius (C) | | | 0 | | | +| | | | Fahrenheit (F) | | | 1 | | | +| Room temperature | | | Celsius (C) | | | 0 | | | +| | | | Fahrenheit (F) | | | 1 | | | +| Relative Humidity in room | | | Percentage (%) | | | 0 | | | +| Remaining filter life | | | Percentage (%) | | | 0 | | | + +Size (3 bits) + +The size field indicates the number of bytes used for the sensor value. This field can take values from 1 (001b), 2 (010b) or 4 (100b). + +Value (N bytes) + +[The value MUST be treated as a signed field (Table 10). The value MAY be 1, 2 or 4 bytes in size. This](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) first byte is the most significant byte. + +## 4.35.3 HRV Status Supported Get Command + +This command is used to request a bitmap of the supported status parameters. + +The HRV Status Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HRV STATUS _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HRV STATUS SUPPORTED GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.35.4 HRV Status Supported Report Command + +This command is used to report a bitmap indicating the supported status parameters. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HRV STATUS _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HRV STATUS SUPPORTED REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | | + +Bit Mask (N bytes) + +The Bit Mask fields describe the supported status parameters from the ventilation system. Bit 0 in the Bit Mask 1 field used to indicate if the status parameter “Outdoor Air Temperature” is supported, 0 indicating not supported and 1 indicating supported. Bit 1 in the Bit Mask 1 field used to indicate if the status parameter “Supply Air Temperature” is supported and so forth. All available status parameters are given [in Section 4.35.1 HRV Status Get.](04.35-hrv-status-command-class-version-1.md#4351-hrv-status-get-command) + +It is only necessary to send the Bit Mask fields 1 and up to the one indicating the last support status parameter. The number of Bit Mask fields transmitted MUST be determined from the length field in the frame. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.36-hrv-control-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.36-hrv-control-command-class-version-1.md new file mode 100644 index 0000000..496e243 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.36-hrv-control-command-class-version-1.md @@ -0,0 +1,212 @@ + +# 4.36 HRV Control Command Class, version 1 + +The Heat Recovery Ventilation (HRV) Control Command Class is introducing control of Heat Recovery Ventilation systems via the Z-Wave interface. + +## 4.36.1 HRV Mode Set + +This command is used to set the desired mode in the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HRV CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HRV CONTROL MODE SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Mode | | | | | | | | | | | | | | | + +Mode (5 bits) + +The mode identifier MAY be set to the following values: + +| | Mode | | | Name | | | Description | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0 | | | Off | | | The HRV system is in the off state, frost protection can occur. | | | +| 1 | | | Demand / Automatic | | | The HRV system is controlled based on sensor input. | | | +| 2 | | | Schedule | | | The HRV system is controlled based on predefined input from the factory and/or user/installer. | | | +| 3 | | | Energy Savings Mode | | | The HRV system will be put into a reduced heat / ventilation mode. | | | +| 4 | | | Manual | | | The HRV system is in manual mode. The command HRV Manual Control Set may be used to manually control the device. | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +## 4.36.2 HRV Mode Get Command + +This command is used to request the current mode from the device. + +The HRV Mode Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HRV CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HRV CONTROL MODE GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.36.3 HRV Mode Report Command + +The HRV Mode Report Command is used to report the mode from the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HRV CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HRV CONTROL MODE REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Mode | | | | | | | | | | | | | | | + +Mode (8 bits) + +Refer to description under the HRV Mode Set command. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +## 4.36.4 HRV Bypass Set Command + +This command is used to set the bypass mode when the ventilation system is set to manual mode. If the system is not in manual mode while receiving this command it MUST be ignored. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HRV CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HRV CONTROL BYPASS SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Bypass | | | | | | | | | | | | | | | | | | | | | | | | + +Bypass (8 bits) + +The value MAY be 0x00 (close) or 0xFF (open). + +Furthermore, the field MAY carry a percentage value between 1 to 99 (0x01 - 0x63). If the ventilation system supports modulated bypass, the percentage value will represent the aperture of the bypass. If the system does not support the full range of aperture steps, the values SHOULD be mapped linearly over the entire scale. + +If ventilation system does support modulated bypass the values from 1 to 99 MUST be interpreted as fully open. + +The value 254 (0xFE) MAY be used to set the bypass into automatic mode. + +## 4.36.5 HRV Bypass Get Command + +This command is used to request the current bypass setting. + +The HRV Bypass Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HRV CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HRV CONTROL BYPASS GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.36.6 HRV Bypass Report Command + +This command is used to report the current bypass parameters. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HRV CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HRV CONTROL BYPASS REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Bypass | | | | | | | | | | | | | | | | | | | | | | | | + +Bypass (8 bits) + +[See description in 4.36.4 HRV Bypass Set.](04.36-hrv-control-command-class-version-1.md#4364-hrv-bypass-set-command) + +## 4.36.7 HRV Ventilation Rate Set Command + +This command is used to set the ventilation rate when the ventilation system is set to manual mode. If the system is not in manual mode while receiving this command it MUST be ignored. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HRV CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HRV CONTROL VENTILATION RATE SET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Ventilation Rate | | | | | | | | | | | | | | | | | | | | | | | | + +Ventilation Rate (8 bits) + +The value MAY be 0x00 (off) or 0xFF (on). + +The field MAY carry a percentage value between 1 to 99 (0x01 - 0x63). A ventilation system MAY map the values 1..99 to less than 99 steps. + +## 4.36.8 HRV Ventilation Rate Get Command + +This command is used to request the current ventilation rate setting. + +The HRV Ventilation Rate Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HRV CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HRV CONTROL VENTILATION RATE GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.36.9 HRV Ventilation Rate Report Command + +This command is used to report the current ventilation rate setting. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HRV CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HRV CONTROL VENTILATION RATE REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Ventilation Rate | | | | | | | | | | | | | | | | | | | | | | | | + +Ventilation Rate (8 bits) + +[See description under Section 4.36.7 HRV Ventilation Rate Set.](04.36-hrv-control-command-class-version-1.md#4367-hrv-ventilation-rate-set-command) + +## 4.36.10 HRV Mode Supported Get Command + +This command is used to request the supported modes from the device. + +The HRV Mode Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HRV CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Command = HRV CONTROL MODE SUPPORTED GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | + +## 4.36.11 HRV Mode Supported Report Command + +This command is used to report the supported modes from the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HRV CONTROL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Command = HRV CONTROL MODE SUPPORTED REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | Manual Control Supported | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Manual Control Supported (3 bits) + +The manual control supported bits describes the supported manual control modes of the ventilation system. The mode is supported if the bit is 1. If the bit is 0, the mode is not supported. + +The bits are mapped to the following controls: + +| Bit | | | Name | | +| --- | --- | --- | --- | --- | +| 0 | | Bypass Open / Close | | | +| 1 | | Bypass Auto | | | +| 2 | | Modulated Bypass | | | +| 3 | | Ventilation Rate | | | + +E.g. a ventilation system supporting only open and close would report Manual Control Supported = 0x01. Bit Mask (N bytes) + +The Bit Mask fields describe the supported modes by the device. + + Bit 0 in Bit Mask 1 field indicates if Mode = 0 (Off) is supported.  Bit 1 in Bit Mask 1 field indicates if Mode = 1 (Demand / Automatic) is supported.  … + +If the Mode is supported the bit MUST be set to 1. If the Mode is not supported the bit MUST be set to 0. It is only necessary to send the Bit Mask fields from 1 and up to the one indicating the last supported mode. The number of Bit Mask fields transmitted MUST be determined from the length field in the frame. + +[All available modes are given in Section 4.36.1 HRV Mode Set.](04.36-hrv-control-command-class-version-1.md#4361-hrv-mode-set) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.37-humidity-control-mode-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.37-humidity-control-mode-command-class-version-1.md new file mode 100644 index 0000000..d8e7ce0 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.37-humidity-control-mode-command-class-version-1.md @@ -0,0 +1,110 @@ + +# 4.37 Humidity Control Mode Command Class, version 1 + +The Humidity Control Mode Command Class is used to control a humidity control device. + +## 4.37.1 Humidity Control Mode Set Command + +This command is used to set the humidity control mode in the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HUMIDITY CONTROL MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HUMIDITY CONTROL MODE SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Mode | | | | | | | | | | | | + +Reserved + +The reserved field is for future use. Reserved bits MUST be set to zero by a sending node. Reserved bits MUST be ignored by a receiving node. + +Mode (4 bits) + +[The encoding of the humidity control mode field MUST be according to Table 43.](04.37-humidity-control-mode-command-class-version-1.md#4371-humidity-control-mode-set-command) + +Table 43, Mode + +| | Mode | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0 | | | Off – Humidity control system is off. | | | 1 | | | +| 1 | | | Humidify – The system will attempt to raise humidity to the humidifier setpoint. | | | 1 | | | +| 2 | | | De-humidify – The system will attempt to lower the humidity to the de- humidifier setpoint. | | | 1 | | | + +All other values are reserved. Reserved values MUST NOT be used by a sending node and MUST be ignored by a receiving node. + +## 4.37.2 Humidity Control Mode Get Command + +This command is used to request the supported humidity control modes from the device. + +The Humidity Control Mode Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HUMIDITY CONTROL MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HUMIDITY CONTROL MODE GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +Humidity Control Mode Report Command 4.37.3 + +This command is used to report the humidity control mode from the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HUMIDITY CONTROL MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HUMIDITY CONTROL MODE REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Mode | | | | | | | | | | | | + +Reserved + +The reserved field is for future use. Reserved bits MUST be set to zero by a sending node. Reserved bits MUST be ignored by a receiving node. + +Mode (4 bits) + +Refer to the description under the Humidity Control Mode Set Command. + +## 4.37.4 Humidity Control Mode Supported Get Command + +This command is used to request the supported modes from the device. + +The Humidity Control Mode Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HUMIDITY CONTROL MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Command = HUMIDITY CONTROL MODE SUPPORTED GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | + +## 4.37.5 Humidity Control Mode Supported Report Command + +This command is used to report the supported humidity control modes from the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HUMIDITY CONTROL MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Command = HUMIDITY CONTROL MODE SUPPORTED REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | + +Bit Mask (N bytes) + +The Bit Mask fields MUST advertise the supported humidity control modes by the device. The encoding [of the Size field MUST be according to Table 44.](04.37-humidity-control-mode-command-class-version-1.md#4375-humidity-control-mode-supported-report-command) + +Table 44, Supported Humidity Control Mode + +| | Field | | Bit | | | Support for Control Mode | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Bit Mask 1 | | | 0 | | Reserved | | | 1 | | | +| Bit Mask 1 | | | 1 | | 1 (Humidifier) | | | 1 | | | +| Bit Mask 1 | | | 2 | | 2 (De-humidifer) | | | 1 | | | + +All Bit Mask fields and bits not specified above are reserved. Reserved bits MUST be set to zero by a sending node. Reserved bits MUST be ignored by a receiving node. + +For each individual bit, The value ‘0’ MUST signify that the actual Mode is not supported. The value ‘1’ MUST signify that the actual Mode is supported. A sending node MAY omit trailing Bit Mask fields if they are not needed. The number of Bit Mask fields MUST be determined from the length field in the frame. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.38-humidity-control-operating-state-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.38-humidity-control-operating-state-command-class-version-1.md new file mode 100644 index 0000000..4285f8f --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.38-humidity-control-operating-state-command-class-version-1.md @@ -0,0 +1,51 @@ + +# 4.38 Humidity Control Operating State Command Class, version 1 + +The Humidity Control Operating State Command Class is used to obtain the operating state of the humidity control device. + +## 4.38.1 Humidity Control Operating State Get Command + +This command is used to request the operating state of the humidity control device. + +The Humidity Control Operating State Report Command MUST be returned in response to thiscommand. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HUMIDITY CONTROL OPERATING STATE _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HUMIDITY CONTROL OPERATING STATE GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.38.2 Humidity Control Operating State Report Command + +This command is used to report the operating state of the humidity control device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HUMIDITY CONTROL OPERATING STATE _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HUMIDITY CONTROL OPERATING STATE REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Operating State | | | | | | | | | | | | + +Reserved + +The reserved field is for future use. Reserved bits MUST be set to zero by a sending node. Reserved bits MUST be ignored by a receiving node. + +Operating State (4 bits) + +The Operating State field MUST advertise the current operating state. + +[The encoding of the Operating State field MUST be according to Table 45.](04.38-humidity-control-operating-state-command-class-version-1.md#4382-humidity-control-operating-state-report-command) Table 45, Operating State + +| | Operating State | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0 | | | Idle | | | 1 | | | +| 1 | | | Humidifying | | | 1 | | | +| 2 | | | De-humidifying | | | 1 | | | + +All other values are reserved. Reserved values MUST NOT be used by a sending node and MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.39-humidity-control-setpoint-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.39-humidity-control-setpoint-command-class-version-1.md new file mode 100644 index 0000000..25a46ec --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.39-humidity-control-setpoint-command-class-version-1.md @@ -0,0 +1,237 @@ + +# 4.39 Humidity Control Setpoint Command Class, version 1 + +The Humidity Control Setpoint Command Class is used for humidity control setpoint handling. + +## 4.39.1 Humidity Control Setpoint Set Command + +This command is used to set the humidity control setpoint in the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HUMIDITY CONTROL SETPOINT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HUMIDITY CONTROL SETPOINT SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Setpoint Type | | | | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | | | | +| Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Value N | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +The reserved field is for future use. Reserved bits MUST be set to zero by a sending node. Reserved bits MUST be ignored by a receiving node. + +Setpoint Type (4 bits) + +The Setpoint Type field MUST specify the humidity control setpoint to be set in the humidity control [device. The encoding of the Setpoint Type field MUST be according to Table 46.](04.39-humidity-control-setpoint-command-class-version-1.md#4391-humidity-control-setpoint-set-command) + +Table 46, Setpoint Type + +| | Setpoint Type | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 1 | | | Humidifier | | | 1 | | | +| 2 | | | De-humidifier | | | 1 | | | + +All other values are reserved. Reserved values MUST NOT be used by a sending node and MUST be ignored by a receiving node. + +Precision (3 bits) + +The precision field MUST specify the precision of the setpoint value. The number indicates the number of decimals. As an example, the decimal value 1025 with precision two (2) is equal to 10.25. Scale (2 bits) + +The Scale field MUST specify the humidity scale used. The encoding of the Scale field MUST be [according to Table 47.](04.39-humidity-control-setpoint-command-class-version-1.md#4391-humidity-control-setpoint-set-command) + +Table 47, Scale values + +| | Scale | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0 | | | Percentage value | | | 1 | | | +| 1 | | | Absolute humidity (g/m3) | | | 1 | | | + +All other values are reserved. Reserved values MUST NOT be used by a sending node and MUST be ignored by a receiving node. + +Size (3 bits) + +The Size field MUST specify the number of bytes used for the Value field. The encoding of the Size field [MUST be according to Table 48.](04.39-humidity-control-setpoint-command-class-version-1.md#4391-humidity-control-setpoint-set-command) + +Table 48, Size values + +| | Size | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 1 | | | Value field is 1 byte long | | | 1 | | | +| 2 | | | Value field is 2 bytes long | | | 1 | | | +| 4 | | | Value field is 4 bytes long | | | 1 | | | + +All other values are reserved. Reserved values MUST NOT be used by a sending node and MUST be ignored by a receiving node. + +Value (N bytes) + +The value is a signed field. The field MAY be one, two, or four bytes in size as specified by the Size field. Value 1 is the most significant byte. + +## 4.39.2 Humidity Control Setpoint Get Command + +This command is used to request the given humidity control setpoint type in a device. + +The Humidity Control Setpoint Report MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HUMIDITY CONTROL SETPOINT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HUMIDITY CONTROL SETPOINT GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Setpoint Type | | | | | | | | | | | | + +Reserved + +The reserved field is for future use. Reserved bits MUST be set to zero by a sending node. Reserved bits MUST be ignored by a receiving node. + +Setpoint Type (4 bits) + +Refer to the description under the Humidity Control Setpoint Set Command. + +## 4.39.3 Humidity Control Setpoint Report Command + +This command is used to report the value of the humidity control setpoint type in the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HUMIDITY CONTROL SETPOINT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HUMIDITY CONTROL SETPOINT REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Setpoint Type | | | | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | | | | +| Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Value N | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +The reserved field is for future use. Reserved bits MUST be set to zero by a sending node. Reserved bits MUST be ignored by a receiving node. + +[For fields’ description, refer to 4.39.1 Humidity Control Setpoint Set Command](04.39-humidity-control-setpoint-command-class-version-1.md#4391-humidity-control-setpoint-set-command) + +## 4.39.4 Humidity Control Setpoint Supported Get Command + +This command is used to request the humidity control setpoint types supported by the device. + +The Humidity Control Setpoint Supported Report Command MUST be returned in response to a this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HUMIDITY CONTROL SETPOINT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HUMIDITY CONTROL SETPOINT SUPPORTED GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.39.5 Humidity Control Setpoint Supported Report Command + +This command is used to report the humidity control setpoint types supported by the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HUMIDITY CONTROL SETPOINT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HUMIDITY CONTROL SETPOINT SUPPORTED REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | | + +Bit Mask (N bytes) + +The Bit Mask fields MUST advertise the humidity control setpoint types supported by the device.The [encoding of the Size field MUST be according to Table 49.](04.39-humidity-control-setpoint-command-class-version-1.md#4395-humidity-control-setpoint-supported-report-command) + +Table 49, Humidity Control Setpoint Supported Report values + +| | Field | | | Bit | | | Support for Setpoint Type | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Bit Mask 1 | | | 0 | | | Reserved | | | 1 | | | +| Bit Mask 1 | | | 1 | | | 1 (Humidifier) | | | 1 | | | +| Bit Mask 1 | | | 2 | | | 2 (De-humidifer) | | | 1 | | | + +All Bit Mask fields and bits not specified above are reserved. Reserved bits MUST be set to zero by a sending node. Reserved bits MUST be ignored by a receiving node. For each individual bit, The value ‘0’ MUST signify that the actual Setpoint Type is not supported. The value ‘1’ MUST signify that the actual Setpoint Type is supported. + +A sending node MAY omit trailing Bit Mask fields if they are not needed. The number of Bit Mask fields MUST be determined from the length field in the frame. + +## 4.39.6 Humidity Control Setpoint Scale Supported Get Command + +This command is used to retrieve the supported scales of the humidity control setpoints in the device. + +The Humidity Control Scale Supported Report Command MUST be returned in response to this command. + +| | 7 | 6 | | | 5 | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HUMIDITY CONTROL SETPOINT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = HUMIDITY CONTROL SETPOINT SCALE SUPPORTED GET _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Setpoint Type | | | | | | | | | | | | + +Reserved + +The reserved field is for future use. Reserved bits MUST be set to zero by a sending node. Reserved bits MUST be ignored by a receiving node. + +Setpoint Type (4 bits) + +Refer to the description under the Humidity Control Setpoint Set Command. + +## 4.39.7 Humidity Control Setpoint Scale Supported Report Command + +This command indicates the supported scales of the humidity control setpoint in a bit mask format. + +| | 7 | 6 | | | 5 | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HUMIDITY CONTROL SETPOINT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = HUMIDITY CONTROL SETPOINT SCALE SUPPORTED REPORT _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Scale Bit Mask | | | | | | | | | | | | + +Reserved + +The reserved field is for future use. Reserved bits MUST be set to zero by a sending node. Reserved bits MUST be ignored by a receiving node. + +Scale Bit Mask (4 bits) + +Refer to the description under the Humidity Control Setpoint Set Command. + +## 4.39.8 Humidity Control Setpoint Capabilities Get Command + +This command is used to request the minimum and maximum setpoint values for a given humidity control Setpoint Type. + +The Humidity Control Setpoint Capabilities Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HUMIDITY CONTROL SETPOINT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HUMIDITY CONTROL SETPOINT CAPABILITIES GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Setpoint Type | | | | | | | | | | | | + +Reserved + +The reserved field is for future use. Reserved bits MUST be set to zero by a sending node. Reserved bits MUST be ignored by a receiving node. + +Setpoint Type (4 bits) + +Refer to the description under the Humidity Control Setpoint Set Command. + +## 4.39.9 Humidity Control Setpoint Capabilities Report Command + +This command is used to report the minimum and maximum values of the requested humidity control setpoint type. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS HUMIDITY CONTROL SETPOINT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = HUMIDITY CONTROL SETPOINT CAPABILITIES REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Setpoint Type | | | | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | | | | +| Minimum Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Minimum Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | | | | +| Maximum Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Maximum Value N | | | | | | | | | | | | | | | | | | | | | | | | + +Refer to the description under the Humidity Control Setpoint Set Command for other parameter/field descriptions. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.40-indicator-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.40-indicator-command-class-version-1.md new file mode 100644 index 0000000..705f932 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.40-indicator-command-class-version-1.md @@ -0,0 +1,53 @@ + +# 4.40 Indicator Command Class, version 1 + +The Indicator Command Class is used to show the actual state, level etc. on a supporting node. + +## 4.40.1 Indicator Set Command + +This command is used to enable or disable an indicator. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS INDICATOR _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = INDICATOR SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Value | | | | | | | | | | | | | | | | | | | | | | | | + +Value (8 bits) + +The value MAY be 0x00 (off/disable) or 0xFF (on/enable). + +The field MAY carry values from 1 to 99. In case the indicator does not have the capability to show the range from 1 to 99, the values 1 to 99 MUST be presented as (on/enable). + +## 4.40.2 Indicator Get Command + +This command is used to request the state of an indicator. + +The Indicator Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS INDICATOR _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = INDICATOR GET _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.40.3 Indicator Report Command + +This command is used to advertise the state of an indicator. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS INDICATOR _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = INDICATOR REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Value | | | | | | | | | | | | | | | | | | | | | | | | + +Value (8 bits) + +Refer to description under the Indicator Set Command. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.41-indicator-command-class-version-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.41-indicator-command-class-version-2.md new file mode 100644 index 0000000..b73ef55 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.41-indicator-command-class-version-2.md @@ -0,0 +1,298 @@ + +# 4.41 Indicator Command Class, version 2 + +The Indicator Command Class, version 2 is used to manipulate indicator resources in a supporting node. An indicator may be an LED, an LCD display or a buzzer. + +One example of use is a central entry control application that uses the indicators of an entry control keypad device to advertise system status information. + +If the Indicator Command Class is implemented in a devices based on Role Type RSS (using Wake Up Command Class), the control of indicators must be synchronized with the Wake Up Notification. The controller must therefore wait for the Wake Up Notification, before it can control the indicators. The device implementing the indicator Command Class must therefore send the Wake Up Notification in case it expects to be controlled. + +## 4.41.1 Compatibility Considerations + +A supporting device MAY use its indicator resources for local status reporting until the first Indicator Set command is received. After receiving an Indicator Set command, the supporting device MUST NOT use its indicator resources for local status reporting until it has been reset to default or re-included in the network. An exception to this MAY be interface feedback functionality like a short beep on each button press. Likewise, transmission failure to the central controller MAY be advertised via the use of local indications. As an example, an entry control keypad device may feature an LCD backlight. If the backlight is advertised as an indicator resource, a central control application also has to control the backlight of the keypad, e.g. in response to local user activity and to temporarily draw attention to all keypads when an alarm is enabled. + +The Indicator Command Class, version 1 provides a single unspecified indicator resource. + +The Indicator Command Class, version 2 supports multiple indicator resources. Each indicator resource may implement a number of properties such as on/off and color. + +The Indicator Command Class, version 2 renames the Value field of version 1 to “Indicator 0 Value”. The Indicator 0 Value field properties are unspecified as in version 1. + +A supporting version 2 device MUST ignore the Indicator 0 Value of the Indicator Set command if other Value fields are specified. A supporting version 2 device MUST map the Indicator 0 Value of the Indicator Set command to a supported indicator if no other fields are specified. + +Since the Indicator 0 Value field is always present in Indicator Set commands, a controlling device MUST send the correct value in every Indicator Set command. A controlling version 2 device MUST ignore the Indicator 0 Value of the Indicator Report command if other Value fields are specified. A controlling version 2 device MUST interpret the Indicator 0 Value of the Indicator Report command the same way as in the Indicator Set command. + +## 4.41.2 Service Discovery Considerations + +A control application may discover available indicators and their properties via the Indicator Supported Report Command. Color properties allow the application to discover the color of actual indicators. A single indicator, e.g. ARMED_NOT_ARMED, may provide two colors; red and green. + +Likewise, a control application may detect the availability of indicator resources using LCD, e-paper or similar technologies to implement an indicator resource that keeps its state when the device goes to sleep. The device may advertise the property “Low_power” to indicate this. + +## 4.41.3 Indicator Set Command + +This command is used to manipulate one or more indicator resources of a supporting device. + +A supporting device MAY use its indicator resources for local status reporting until the first Indicator Set command is received. After receiving an Indicator Set command, the supporting device MUST NOT use its indicator resources for local status reporting until it has been reset to default or re-included in the network. An exception to this MAY be interface feedback functionality like a short beep on each button press. Likewise, transmission failure to the central controller MAY be advertised via the use of local indications. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS INDICATOR _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = INDICATOR SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Indicator 0 Value (Indicator ID 0 = 0x00, Property ID 0 = 0x01) | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Indicator Object Count | | | | | | | | | | | | | | | +| | Indicator ID 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Property ID 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Value 1 | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Indicator ID N | | | | | | | | | | | | | | | | | | | | | | | +| | Property ID N | | | | | | | | | | | | | | | | | | | | | | | +| | Value N | | | | | | | | | | | | | | | | | | | | | | | + +Indicator 0 Value (1 byte) + +This field provides backwards compatibility with devices implementing the Indicator Command Class, version 1. + +A receiving device MUST ignore this field if other indicator resources are specified. A receiving device MUST map this value to a supported indicator resource if no other fields are specified. + +[Refer to the compatibility considerations found in 4.41.1.](04.41-indicator-command-class-version-2.md#4411-compatibility-considerations) Reserved + +This field MUST be set to 0 by a sending device and MUST be ignored by a receiving device. + +Indicator Object Count (1 byte) + +This field is used to advertise the number of indicator objects carried in the actual command. An indicator object MUST comprise an Indicator ID, Property ID and Value field. There MAY be several indicator objects carrying the same Indicator ID but different Property IDs, e.g. Color and Blink pattern. + +A receiving device MUST ignore an indicator object if an unsupported Indicator ID or Property ID is specified. The receiving device MUST continue parsing the command if more fields follow the ignored indicator object. + +Indicator ID n (1 byte) + +This field is used to identify the actual indicator resource. + +There MAY be several indicator objects carrying the same Indicator ID but different Property IDs, e.g. Color and Blink pattern. + +Property ID n (1 byte) + +This field is used to identify the specific property of the indicator resource identified by the Indicator ID. + +There MAY be several indicator objects carrying the same Indicator ID but different Property IDs, e.g. Color and Blink pattern. + +Value n (1 byte) + +This field is used to specify the value to assign to the specific property identified by the Indicator ID and the Property ID fields. + +### 4.41.3.1 Indicator IDs + +[The identifiers used in Indicator ID fields MUST comply with the definitions found in Table 50.](04.41-indicator-command-class-version-2.md#44131-indicator-ids) + +Table 50, Indicator CC :: Indicator IDs + +| | Indicator | | Description | Appearance and use | +| --- | --- | --- | --- | --- | +| | ID | | | | +| 0x00 | | | NA | Not Applicable. MUST NOT be used for other purposes than service discovery and rejecting invalid requests. | +| 0x01 | | | ARMED | Use to indicate that alarm is armed (RECOMMENDED color: Red) | +| 0x02 | | | NOT ARMED _ | Use to indicate that alarm is disarmed (RECOMMENDED color: Green) | +| 0x03 | | | READY | Use to indicate that device is ready (RECOMMENDED color: Green) | +| 0x04 | | | FAULT | Use to indicate a general error (RECOMMENDED color: Red) | +| 0x05 | | | BUSY | Use to indicate that device is temporarily busy (RECOMMENDED color: Yellow) | +| 0x06 | | | ENTER ID _ | Use to signal that device is waiting for ID (RECOMMENDED color: Yellow) | +| 0x07 | | | ENTER PIN _ | Use to signal that device is waiting for PIN code (RECOMMENDED color: Yellow) | +| 0x08 | | | OK | Use to indicate OK e.g. the entered code is accepted (RECOMMENDED color: Green) | +| 0x09 | | | NOT OK _ | Use to indicate NOT OK e.g. the entered code is NOT accepted (RECOMMENDED color: Red) | +| … | | | | | +| 0x20 | | | ZONE1 ARMED _ | Use to indicate that alarm zone 1 is armed (RECOMMENDED color: Red) | +| 0x21 | | | ZONE2 ARMED _ | Use to indicate that alarm zone 2 is armed (RECOMMENDED color: Red) | +| 0x22 | | | ZONE3 ARMED _ | Use to indicate that alarm zone 3 is armed (RECOMMENDED color: Red) | +| 0x23 | | | ZONE4 ARMED _ | Use to indicate that alarm zone 4 is armed (RECOMMENDED color: Red) | +| 0x24 | | | ZONE5 ARMED _ | Use to indicate that alarm zone 5 is armed (RECOMMENDED color: Red) | +| 0x25 | | | ZONE6 ARMED _ | Use to indicate that alarm zone 6 is armed (RECOMMENDED color: Red) | +| … | | | | | +| 0x30 | | | LCD BACKLIGHT _ | Use to turn on LCD backlight, e.g. to shortly draw attention when alarm is activated from another entry control keypad. | +| … | | | | | +| 0x40 | | | BUTTON BACKLIGHT _ _ LETTERS | Use to indicate that buttons are ready for user input | + +| | Indicator | | Description | Appearance and use | +| --- | --- | --- | --- | --- | +| | ID | | | | +| 0x41 | | | BUTTON BACKLIGHT _ _ DIGITS | Use to indicate that buttons are ready for user input | +| 0x42 | | | BUTTON BACKLIGHT _ _ COMMAND | Use to indicate that buttons are ready for user input | +| 0x43 | | | BUTTON1 INDICATION _ | Use to draw attention to button 1 (RECOMMENDED for button backlight or LED next to button) | +| 0x44 | | | BUTTON2 INDICATION _ | Use to draw attention to button 2 (RECOMMENDED for button backlight or LED next to button) | +| 0x45 | | | BUTTON3 INDICATION _ | Use to draw attention to button 3 (RECOMMENDED for button backlight or LED next to button) | +| 0x46 | | | BUTTON4 INDICATION _ | Use to draw attention to button 4 (RECOMMENDED for button backlight or LED next to button) | +| 0x47 | | | BUTTON5 INDICATION _ | Use to draw attention to button 5 (RECOMMENDED for button backlight or LED next to button) | +| 0x48 | | | BUTTON6 INDICATION _ | Use to draw attention to button 6 (RECOMMENDED for button backlight or LED next to button) | +| 0x49 | | | BUTTON7 INDICATION _ | Use to draw attention to button 7 (RECOMMENDED for button backlight or LED next to button) | +| 0x4A | | | BUTTON8 INDICATION _ | Use to draw attention to button 8 (RECOMMENDED for button backlight or LED next to button) | +| 0x4B | | | BUTTON9 INDICATION _ | Use to draw attention to button 9 (RECOMMENDED for button backlight or LED next to button) | +| 0x4C | | | BUTTON10 INDICATION _ | Use to draw attention to button 10 (RECOMMENDED for button backlight or LED next to button) | +| 0x4D | | | BUTTON11 INDICATION _ | Use to draw attention to button 11 (RECOMMENDED for button backlight or LED next to button) | +| 0x4E | | | BUTTON12 INDICATION _ | Use to draw attention to button 12 (RECOMMENDED for button backlight or LED next to button) | +| … | | | | | +| 0xF0 | | | Buzzer | Use to draw attention or provide user feedback | +| | | | | | + +All other values are reserved and MUST NOT be used by a sending device. Reserved values MUST be ignored by a receiving device. + +### 4.41.3.2 Property IDs + +[The identifiers used in Property ID fields MUST comply with the definitions found in Table 51.](04.41-indicator-command-class-version-2.md#44132-property-ids) + +Table 51, Indicator CC :: Property IDs + +| | Value | | | General Description | | | Specific use | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x01 | | | Multilevel | | | Light level, sound level 0x00 = OFF 0x01 – 0x63 = Lowest non-zero level - 100% 0xFF = Restore most recent (non-zero) level. | | | +| 0x02 | | | Binary | | | Turn indication On or Off 0x00 = OFF 0x01 – 0x63, 0xFF = ON | | | +| 0x03 | | | On Off Period _ _ | | | The Period in seconds of one ON/OFF period 0x00 – 0xFF = 0 - 25,5 sec | | | +| 0x04 | | | On Off Cycles _ _ | | | Number of On Off Period to run _ _ 0x00 – 0xFE = 0 – 254 times 0xFF = Run until stopped by On Off _ | | | +| … | | | | | | | | | +| 0x10 | | | Low power - _ | | | ADVERTISE ONLY: This property MAY be used to advertise that the indicator can continue working in sleep mode. The indicator may use LCD, e-paper or similar technologies to achieve this. If this property is not advertised, the indicator MUST be switch Off doing power down. The indicator MUST keep the Off state at next wakeup. | | | + +All other values are reserved and MUST NOT be used by a sending device. Reserved values MUST be ignored by a receiving device. + +If the On_Off_Period property is specified, the On_Off_Cycles property MUST also be specified. A receiving device MUST apply an On_Off_Cycles property value of 5 times if the On_Off_Period property is specified and the On_Off_Cycles property is not specified. + +If the On_Off_Cycles property is specified, the On_Off_Period property MUST also be specified. A receiving device MUST apply an On_Off_Period property value of 1 second if the On_Off_Cycles property is specified and the On_Off_Period property is not specified. + +The Multilevel and Binary properties can be used anytime to stop an alternating period configured the On_Off_Period and On_Off_Cycles properties. + +Properties marked as “ADVERTISE ONLY” MUST be treated as unsupported by the Indicator Set and Indicator Get Commands. + +## 4.41.4 Indicator Get Command + +This command is used to request the state of an indicator. + +The Indicator Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS INDICATOR _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = INDICATOR GET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Indicator ID | | | | | | | | | | | | | | | | | | | | | | | | + +Indicator ID n (1 byte) + +This field is used to specify the actual indicator resource. + +If an unsupported Indicator ID is specified, a receiving device MUST advertise an indicator object with all fields set to zero in the Indicator Report Command that is returned in response to this command. + +## 4.41.5 Indicator Report Command + +This command is used to advertise the state of an indicator resource. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS INDICATOR _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = INDICATOR REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Indicator 0 Value (Indicator ID 0 = 0x00, Property ID 0 = 0x01) | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Indicator Object Count | | | | | | | | | | | | | | | +| | Indicator ID 1 | | | | | | | | | | | | | | | | | | | | | | | +| | PropertyID 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Value 1 | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Indicator ID N | | | | | | | | | | | | | | | | | | | | | | | +| | PropertyID N | | | | | | | | | | | | | | | | | | | | | | | +| | Value N | | | | | | | | | | | | | | | | | | | | | | | + +This field provides backwards compatibility with devices implementing the Indicator Command Class, [version 1. Refer to section 4.41.1 for details.](04.41-indicator-command-class-version-2.md#4411-compatibility-considerations) + +A controlling version 2 device MUST ignore the Indicator 0 Value field if other values are advertised. Indicator 0 Value (1 byte) + +Refer to the Indicator Set Command. + +[Refer to the compatibility considerations found in 4.41.1.](04.41-indicator-command-class-version-2.md#4411-compatibility-considerations) + +Reserved + +This field MUST be set to 0 by a sending device and MUST be ignored by a receiving device. + +Indicator Object Count (1 byte) + +This field is used to advertise the number of indicator objects carried in this command. An indicator object MUST comprise an Indicator ID, Property ID and Value field. Only one Indicator may be advertised at a time. Therefore, all indicator objects MUST carry the same Indicator ID while Property IDs MUST be different, e.g. Color and Blink pattern. This format is compatible w. the Indicator Set Command. + +Indicator ID (1 byte) + +This field is used to identify the actual indicator resource. + +All indicator objects MUST carry the same Indicator ID. + +Property ID n (1 byte) + +Refer to the Indicator Set Command. + +Value n (1 byte) + +Refer to the Indicator Set Command. + +## 4.41.6 Indicator Supported Get Command + +This command is used to request the supported properties of an indicator. + +The Indicator Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS INDICATOR _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = INDICATOR SUPPORTED GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Indicator ID | | | | | | | | | | | | | | | | | | | | | | | | + +Indicator ID (1 byte) + +This field is used to specify the actual indicator resource. A sending device SHOULD set this field to zero to discover supporting Indicator IDs. A device receiving an Indicator ID value of zero MUST advertise the first supported Indicator ID in the Indicator Supported Report Command that is returned in response to this command. + +A device receiving a non-zero Indicator ID that is not supported MUST advertise the value zero in all fields of the Indicator Supported Report Command. + +## 4.41.7 Indicator Supported Report Command + +This command is used to advertise the supported properties for a given indicator. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS INDICATOR _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = INDICATOR SUPPORTED REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Indicator ID | | | | | | | | | | | | | | | | | | | | | | | | +| Next Indicator ID | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Property Supported Bit Mask Length | | | | | | | | | | | | | | | +| Property Supported Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| ... | | | | | | | | | | | | | | | | | | | | | | | | +| Property Supported Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | | + +Indicator ID (1 byte) + +This field is used to advertise the actual indicator resource. + +Reserved + +This field MUST be set to 0 by a sending device and MUST be ignored by a receiving device. + +Next Indicator ID (1 byte) + +This field is used to advertise if more Indicator IDs are supported. + +If a sending device supports additional Indicator IDs, this field MUST advertise the next supported Indicator ID. If the sending device supports only one Indicator ID, or if this command carries the last supported Indicator ID, this field MUST advertise the value 0. + +A receiving device SHOULD continue requesting supported Indicator IDs via the Indicator Supported Get Command until this field advertises the value zero. + +Property Supported Bit Mask Length (5 bits) + +This field is used to advertise the length of the Property Supported Bit Mask field in bytes. + +The value MUST be in the range 0..32. Property Supported Bit Mask (variable length) + +The Property Supported Bit Mask is used to advertise the properties supported by the actual Indicator ID. + + Bit 0 in Bit Mask 1 is not allocated to any property and MUST be set to zero.  Bit 1 in Bit Mask 1 indicates if Property ID = 1 (Multilevel) is supported.  Bit 2 in Bit Mask 1 indicates if Property ID = 2 (On/Off) is supported.  … + +If the Property ID is supported, the corresponding bit MUST be set to 1. If the Property ID is not supported the corresponding bit MUST be set to 0. + +Note that this Command Class maps bit 1 to Property ID=1. Some Command Classes map bit 0 to the first property diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.01-terminology.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.01-terminology.md new file mode 100644 index 0000000..67053c5 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.01-terminology.md @@ -0,0 +1,26 @@ + +# 4.42.1 Terminology + +In an irrigation system, a zone valve is turned on to allow a certain group of sprinklers to water an area (or zone) for a specified duration. The terms zone valve and valve are used synonymously, whereas a master valve is always identified as such. + +A valve that is on or open lets the water run through the valve. A valve that is off or closed blocks the water from running through the valve. + +A master valve allows water to flow to a set of zone valves, and must be turned on before water flows to the zone valves. In version 1 of this Command Class, there is only one master valve in an irrigation system. + +A valve is identified with a ValveID. The master valve and zone valves have their own ID pools, each starting with 1. + +In some cases a master valve switch may drive a pump relay rather than an actual irrigation valve. In this case, there may be a configurable delay between the master valve (or pump) being turned on and the rest of the zone valves being turned on. When a given zone is turned on, a master valve (if present) should automatically turn on. The master valve should also automatically turn off after a device specific duration of zone valve inactivity. + +A valve can be physically connected or disconnected. Attach points where valves can be connected always keep the same valve ID. A disconnected valve cannot be operated and the water does not run through a disconnected valve. + +In an irrigation system, a scheduled run or run is when a set of zone valves are open and closed sequentially, one after another. Each zone valve will be turned on for a specified duration and once complete, that valve will be turned off and the next zone valve will be turned on. In a (scheduled) run, each zone valve has its own specified run duration, which is unique to that zone valve and that specific [(scheduled) run. At the end of a scheduled run, the Irrigation System Shutoff Command can also be used](04.42.21-irrigation-system-shutoff-command.md#44221-irrigation-system-shutoff-command) to turn everything off. + +A master valve remains on/open for the entire duration of any run, so that all zone valves will be able to provide water to their associated sprinklers. + +A valve table is a list of zone valves and their corresponding run durations. A valve table can be created, configured and stored in an irrigation device. The valve table can subsequently be executed (or run) using a single command. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.02-compatibility-considerations.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.02-compatibility-considerations.md new file mode 100644 index 0000000..25c0b79 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.02-compatibility-considerations.md @@ -0,0 +1,12 @@ + +# 4.42.2 Compatibility considerations + +## 4.42.2.1 Multi Channel considerations + +Multi Channel End Points SHOULD NOT support the Irrigation Command Class. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.03-interoperability-considerations.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.03-interoperability-considerations.md new file mode 100644 index 0000000..f7f3180 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.03-interoperability-considerations.md @@ -0,0 +1,34 @@ + +# 4.42.3 Interoperability considerations + +A node supporting the Irrigation Command Class SHOULD be implemented as a Multi Channel Device with the master valve and each zone valve implemented as a separate Multi Channel End Point. + +The Root Device SHOULD support the following Command Classes: + + Irrigation Command Class  Schedule Command Class + +Each End Point SHOULD support the following Command Class: + + Binary Switch Command Class. + +A node supporting optional sensors SHOULD implement each sensor as a separate Multi Channel End Point. + +The Notification Command Class, version 7 or newer can be used for reporting Irrigation events/states, using the Irrigation Notification Type. + +Scheduling can be done using the Schedule Command Class. If supported, the Schedule Command Class SHOULD support alternating days and odd/even date processing. + +Some supporting nodes MAY support having only 1 zone valve open at a time. A controlling node SHOULD be aware that opening a zone valve may cause another currently open zone valve to close. + +## 4.42.3.1 Controlling methods + +A system integrator should be aware that if an irrigation control device is controlled using both End Point Binary Switch Command Class and Root Device Irrigation Command Class at the same time, this may cause unpredictable behavior. This applies whether commands are issued instantly or scheduled. It is RECOMMENDED that an irrigation controlling system is managed either via direct End Point control or via the Irrigation Command Class. + +An irrigation device can be driven directly from a Z-Wave controlling node, turning on the master valve and sequentially turning on each zone valve for a specified duration. + +The controlling node can also use the concept of a valve table to turn on a set of valves sequentially. A [valve table allows a single command, the Irrigation Valve Table Run Command, to trigger a run. The](04.42.20-irrigation-valve-table-run-command.md#44220-irrigation-valve-table-run-command) [controlling node must first create the valve tables, using the Irrigation Valve Table Set Command. The](04.42.17-irrigation-valve-table-set-command.md#44217-irrigation-valve-table-set-command) [run can triggered by sending the Irrigation Valve Table Run Command at the desired time. The irrigation](04.42.20-irrigation-valve-table-run-command.md#44220-irrigation-valve-table-run-command) device will sequentially run the valves in each of the specified valve tables for their associated runtimes. Depending on the irrigation system, the controlling node may need to turn on the master valve manually [using the Irrigation Valve Run Command.](04.42.16-irrigation-valve-run-command.md#44216-irrigation-valve-run-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.04-irrigation-system-info-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.04-irrigation-system-info-get-command.md new file mode 100644 index 0000000..beec399 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.04-irrigation-system-info-get-command.md @@ -0,0 +1,19 @@ + +# 4.42.4 Irrigation System Info Get Command + +This command is used to request a receiving node about its irrigation system information. + +[The Irrigation System Info Report Command MUST be returned in response to this command.](04.42.05-irrigation-system-info-report-command.md#4425-irrigation-system-info-report-command) + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION SYSTEM INFO GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.05-irrigation-system-info-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.05-irrigation-system-info-report-command.md new file mode 100644 index 0000000..e1c4682 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.05-irrigation-system-info-report-command.md @@ -0,0 +1,45 @@ + +# 4.42.5 Irrigation System Info Report Command + +This command is used to advertise irrigation system information. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION SYSTEM INFO REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | | | | Master Valve | | | +| Total Number of Valves | | | | | | | | | | | | | | | | | | | | | | | | +| Total Number of Valve Tables | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Valve Table Max Size | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Master Valve (1 bit) + +This field is used to indicate if a master valve is supported by the sending node. + +The value 1 MUST indicate that the sending node supports a master valve. The value 0 MUST indicate that the sending node does not support a master valve. + +Total Number of Valves (8 bits) + +This field is used to advertise the total number of zone valves supported by the device + +The implemented Valve ID values MUST be in a sequence starting from 1, i.e. a node supporting 10 valves MUST accept Valve ID values in the range 1..10. Total Number of Valve Tables (8 bits) + +This field is used to advertise the total number of valve tables that can be created/stored in the device. + +The implemented Valve Table ID MUST be in a sequence starting from 1, i.e. a node supporting 10 valve tables MUST accept Valve Table ID values in the range 1..10. + +Valve Table Max Size (4 bits) + +This field is used to advertise the maximum number of entries per valve table supported by the sending node. + +The value MUST be in the range 1..15. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.06-irrigation-system-status-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.06-irrigation-system-status-get-command.md new file mode 100644 index 0000000..90ab660 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.06-irrigation-system-status-get-command.md @@ -0,0 +1,19 @@ + +# 4.42.6 Irrigation System Status Get Command + +This command is used to request a receiving node about its irrigation system status. + +The Irrigation System Status Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION SYSTEM STATUS GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.07-irrigation-system-status-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.07-irrigation-system-status-report-command.md new file mode 100644 index 0000000..ac3b635 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.07-irrigation-system-status-report-command.md @@ -0,0 +1,136 @@ + +# 4.42.7 Irrigation System Status Report Command + +This command is used to advertise irrigation system status. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION SYSTEM STATUS REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| System Voltage | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Status | | | | | | | | | | | | | | | | | | | | | | | | +| Flow Precision | | | | | | | | | Flow Scale=l/h | | | | | | Flow Size | | | | | | | | | +| Flow Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Flow Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Pressure Precision | | | | | | | | | Pressure Scale=kPa | | | | | | Pressure Size | | | | | | | | | +| Pressure Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Pressure Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Shutoff Duration | | | | | | | | | | | | | | | | | | | | | | | | +| System Error Status | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | | | | Master Valve | | | +| Valve ID | | | | | | | | | | | | | | | | | | | | | | | | + +System Voltage (8 bits) + +This field advertises the voltage level applied at the sending node. + +The advertised value MUST be expressed in Volt. This field does not indicate the voltage type (AC or DC). + +If the node does not have a voltage sensor measuring the voltage, this field MUST be set to 0. + +Sensor Status (8 bits) + +This field is used to advertise if optional sensors are currently reporting values or detecting events at the sending node. + +[This field MUST be treated as a bit mask and MUST comply with Table 52.](04.42.07-irrigation-system-status-report-command.md#4427-irrigation-system-status-report-command) Table 52, Irrigation System Status Report::Sensor Status encoding + +| | Bit | | | Sensor Status | | +| --- | --- | --- | --- | --- | --- | +| 0 | | | Flow Sensor currently active If this bit is set to 1, the Flow Value field value MUST advertise a valid sensor reading. | | | +| 1 | | | Pressure Sensor currently active If this bit is set to 1, the Pressure Value field value MUST advertise a valid sensor reading. | | | +| 2 | | | Rain Sensor attached and active If a rain sensor is currently attached to the device and detecting rain, this bit MUST be set to 1. | | | +| 3 | | | Moisture Sensor attached and active If a moisture sensor is currently attached to the device and detecting moisture, this bit MUST be set to 1. | | | +| 4..7 | | | Reserved | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Flow Precision (3 bits) + +This field MUST indicate how many decimals are contained in the “Flow Value” field value. For example, if the “Flow Value” field is set to 1025 and the “Flow Precision” field is set to 2, the Flow Value MUST be interpreted as 10.25. + +If the Sensor Status field’s bit 0 is set to 0, this field MUST be set to 0. + +Flow Scale (2 bits) + +This field MUST indicate which unit is used for the “Flow Value” field. This field MUST be set to 0. + +The value 0 MUST indicate that the unit is l/h (liter/hour) + +Flow Size (3 bits) + +This field is used to advertise the length in bytes of the “Flow Value” field. This field MUST be set to 1, 2 or 4. All other values are reserved and MUST NOT be used by a sending node. + +If the Sensor Status field’s bit 0 is set to 0, this field MUST be set to 1. + +Flow Value (N bytes) + +This field is used to advertise the Flow value measured by the flow sensor. + +The length of this field in byte MUST comply with the value advertised in the Flow Size field. + +If the Sensor Status field’s bit 0 is set to 0, this field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. Pressure Precision (3 bits) + +This field MUST indicate how many decimals are contained in the “Pressure Value” field value. For example, if the “Pressure Value” field is set to 1025 and the “Pressure Precision” field is set to 2, the Pressure Value MUST be interpreted as 10.25. + +If the Sensor Status field’s bit 1 is set to 0, this field MUST be set to 0. + +Pressure Scale (2 bits) + +This field MUST indicate which unit is used for the “Pressure Value” field. This field MUST be set to 0. + +The value 0 MUST indicate that the unit is kPa (kilopascal) + +Pressure Size (3 bits) + +This field is used to advertise the length in bytes of the “Pressure Value” field. This field MUST be set to 1, 2 or 4. All other values are reserved and MUST NOT be used by a sending node. + +If the Sensor Status field’s bit 1 is set to 0, this field MUST be set to 1. + +Pressure Value (N bytes) + +This field is used to advertise the Pressure value measured by the pressure sensor. + +The length of this field in bytes MUST comply with the value advertised in the Pressure Size field. + +If the Sensor Status field’s bit 1 is set to 0, this field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Shutoff Duration (8 bits) + +This field is used to indicate how many hours are left in the “shut off” mode. + +[For description, refer to 4.42.21 Irrigation System Shutoff Command.](04.42.21-irrigation-system-shutoff-command.md#44221-irrigation-system-shutoff-command) + +System Error Status (8 bits) + +This field is used to advertise if any system error is being active at the sending node. [This field MUST be treated as a bit mask and MUST comply with Table 53.](04.42.07-irrigation-system-status-report-command.md#4427-irrigation-system-status-report-command) Table 53, System Status Report::System Error Status encoding + +| | Bit | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0 | | | The device has not been programmed | | | +| 1 | | | The device has experienced an emergency shutdown. | | | +| 2 | | | The device’s pressure high threshold has been triggered. | | | +| 3 | | | The device’s pressure low threshold has been triggered. | | | +| 4 | | | A valve or the master valve is reporting error. Valves can be individually checked using the Irrigation Valve Info Get Command | | | +| 5..7 | | | Reserved | | | + +In some cases, errors are no longer active. Any inactive errors (except valve errors) can be cleared by [sending an Irrigation System Config Set Command. Refer to the Irrigation Valve Info Report Command](04.42.08-irrigation-system-config-set-command.md#4428-irrigation-system-config-set-command) for more details on valve specific errors. + +Master Valve (1 bit) + +This field is used to indicate if a master valve is currently open or closed. + +The value 1 MUST indicate that the master valve is On / Open. The value 0 MUST indicate that the master valve is Off / Closed. + +Valve ID (8 bits) + +This field is used to indicate the Valve ID of the first open zone valve currently On / Open. + +If no zone valve is On / Open, this field MUST be set to 0. Else, this field MUST be to a value in the range 1..{Total number of supported zone valves} by a sending node diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.08-irrigation-system-config-set-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.08-irrigation-system-config-set-command.md new file mode 100644 index 0000000..bf5e792 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.08-irrigation-system-config-set-command.md @@ -0,0 +1,68 @@ + +# 4.42.8 Irrigation System Config Set Command + +This command allows the irrigation system to be configured accordingly. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION SYSTEM CONFIG SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Master Valve Delay | | | | | | | | | | | | | | | | | | | | | | | | +| High Pressure Threshold Precision | | | | | | | | | High Pressure Threshold Scale=kPa | | | | | | High Pressure Threshold Size | | | | | | | | | +| High Pressure Threshold Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| High Pressure Threshold Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Low Pressure Threshold Precision | | | | | | | | | Low Pressure Threshold Scale=kPa | | | | | | Low Pressure Threshold Size | | | | | | | | | +| Low Pressure Threshold Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Low Pressure Threshold Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Polarity | | | | | | | | | | | | | | | | | | | | | | | | + +Master Valve Delay (8 bits) + +This field is used to configure a delay in seconds between turning on the master valve and turning on any “zone” valve. + +This field MUST ignored by a receiving node if it does not implement a master valve. + +The value MUST be expressed in seconds and the value 0 MUST indicate that no delay is applied when turning master and zone valves on. + +Pressure High Threshold + +These fields are used to configure the pressure high threshold at the receiving node. + +A receiving node having no support for pressure sensor MAY ignore this field. + +[If the receiving node supports a Pressure Sensor, the node MUST issue an Irrigation System Status Report Command with the System Error Status indicating high pressure when the pressure crosses](04.42.07-irrigation-system-status-report-command.md#4427-irrigation-system-status-report-command) above this threshold. + +The format of the Pressure High Threshold fields MUST comply with the format used by the Multilevel Sensor Command Class and MUST be expressed in kPa. Pressure Low Threshold + +These fields are used to configure the pressure low threshold at the receiving node. + +A receiving node having no support for pressure sensor MAY ignore this field. + +[If the receiving node supports a Pressure Sensor, the node MUST issue an Irrigation System Status Report Command with the System Error Status indicating low pressure when the pressure crosses below](04.42.07-irrigation-system-status-report-command.md#4427-irrigation-system-status-report-command) this threshold. + +The format of the Pressure Low Threshold fields MUST comply with the format used by the Multilevel Sensor Command Class and MUST be expressed in kPa. + +Sensor Polarity (8 bits) + +This field is used to configure optional sensors’ polarity at the receiving node. + +[This field MUST be treated as a bit mask and MUST comply with Table 54. This field MUST be ignored if](04.42.08-irrigation-system-config-set-command.md#4428-irrigation-system-config-set-command) the ‘valid’ bit (bit 7) is set to 0. + +Table 54, Irrigation System Config Set::Sensor Polarity encoding + +| | Bit | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0 | | | Rain Sensor Polarity (0 LOW, 1 HIGH) A receiving node having no support for rain sensor MAY ignore this field. | | | +| 1 | | | Moisture Sensor Polarity (0 LOW, 1 HIGH) A receiving node having no support for moisture sensor MAY ignore this field | | | +| 2..6 | | | Reserved | | | +| 7 | | | Valid This bit MUST be set to 1 to indicate that the other bits in the bitmask contain valid data. | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.09-irrigation-system-config-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.09-irrigation-system-config-get-command.md new file mode 100644 index 0000000..ac59940 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.09-irrigation-system-config-get-command.md @@ -0,0 +1,19 @@ + +# 4.42.9 Irrigation System Config Get Command + +This command is used to request a receiving node about its current irrigation system configuration. + +[The Irrigation System Config Report Command MUST be returned in response to this command.](04.42.10-irrigation-system-config-report-command.md#44210-irrigation-system-config-report-command) + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION SYSTEM CONFIG GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.10-irrigation-system-config-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.10-irrigation-system-config-report-command.md new file mode 100644 index 0000000..0ffbb31 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.10-irrigation-system-config-report-command.md @@ -0,0 +1,27 @@ + +# 4.42.10 Irrigation System Config Report Command + +This command is used to advertise the current irrigation system configuration. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION SYSTEM CONFIG REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Master Valve Delay | | | | | | | | | | | | | | | | | | | | | | | | +| High Pressure Threshold Precision | | | | | | | | | High Pressure Threshold Scale=kPa | | | | | | High Pressure Threshold Size | | | | | | | | | +| High Pressure Threshold Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| High Pressure Threshold Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Low Pressure Threshold Precision | | | | | | | | | Low Pressure Threshold Scale=kPa | | | | | | Low Pressure Threshold Size | | | | | | | | | +| Low Pressure Threshold Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Low Pressure Threshold Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Polarity | | | | | | | | | | | | | | | | | | | | | | | | + +[For fields’ description, refer to 4.42.8 Irrigation System Config Set Command. A sending node MUST comply with field descriptions in 4.42.8 Irrigation System Config Set Command.](04.42.08-irrigation-system-config-set-command.md#4428-irrigation-system-config-set-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.11-irrigation-valve-info-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.11-irrigation-valve-info-get-command.md new file mode 100644 index 0000000..4323390 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.11-irrigation-valve-info-get-command.md @@ -0,0 +1,39 @@ + +# 4.42.11 Irrigation Valve Info Get Command + +This command is used to request general information about the specified valve. + +The Irrigation Valve Info Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION VALVE INFO GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | | | | Master Valve | | | +| Valve ID | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Master Valve (1 bit) + +This field is used to indicate whether the sending node requests the information of the master valve or of a zone valve. + +The value 1 MUST indicate that the sending node requests the master valve information. The value 0 MUST indicate that the sending node requests information related to the zone valve corresponding to Valve ID field. + +Valve ID (8 bits) + +This field is used to indicate the Valve ID if the sending node requests the information about a zone valve. + +This field MUST be set to a Valve ID supported by the receiving node. A node receiving this command for an unsupported zone valve ID SHOULD return a report for the first supported zone valve. + +If the Master Valve field is set to 1, this field MUST be set to 1. Other values MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.12-irrigation-valve-info-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.12-irrigation-valve-info-report-command.md new file mode 100644 index 0000000..584b040 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.12-irrigation-valve-info-report-command.md @@ -0,0 +1,55 @@ + +# 4.42.12 Irrigation Valve Info Report Command + +This command is used to advertise general information about a given valve. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION VALVE INFO REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | Conn- ected | | | Master Valve | | | +| Valve ID | | | | | | | | | | | | | | | | | | | | | | | | +| Nominal Current | | | | | | | | | | | | | | | | | | | | | | | | +| Valve Error Status | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Master Valve (1 bit) + +This field is used to indicate whether the sending node advertises the information of the master valve or of a zone valve. + +The value 1 MUST indicate that the sending node advertises the master valve information. The value 0 MUST indicate that the sending node advertises information related to the zone valve corresponding to Valve ID field. + +Connected (1 bit) + +This field indicates if the actual valve is currently connected to the node or not. + +The value 0 MUST indicate that the valve is disconnected from the node. The value 1 MUST indicate that the valve is connected to the node. + +Valve ID (8 bits) + +This field is used to indicate the Valve ID if the sending node requests the information about a zone valve. + +This field MUST be set to a Valve ID supported by the receiving node. + +If the Master Valve field is set to 1, this field MUST be set to 1. Other values MUST be ignored by a receiving node. + +Nominal Current (8 bits) + +This field is used to advertise the valve’s nominal electric current when the valve is On / Open. + +This field MUST be expressed as a multiple of 10mA. E.g. the value 23 represents 230 mA. This field MUST be set to 0 if the Connected field is set to 0. This field MUST advertise the last measured current (measured when the valve was on) when the valve is Off / Closed. Valve Error Status (8 bits) + +This bit mask provides valve error status fields. The field MUST be encoded according the following: + + Bit 0 indicates short circuit has been detected.  Bit 1 indicates current high threshold has been detected.  Bit 2 indicates current low threshold has been detected.  Bit 3 indicates maximum flow has been detected (zone valves only).  Bit 4 indicates flow high threshold has been detected (zone valves only).  Bit 5 indicates flow low threshold has been detected (zone valves only).  Bits 6-7 are reserved. + +Any inactive errors can be cleared by sending an Irrigation Valve Config Set Command. Also, if the valve is turned on again, any inactive errors should be cleared as the valve is turned on. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.13-irrigation-valve-config-set-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.13-irrigation-valve-config-set-command.md new file mode 100644 index 0000000..5a2fec7 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.13-irrigation-valve-config-set-command.md @@ -0,0 +1,108 @@ + +# 4.42.13 Irrigation Valve Config Set Command + +This command allows an irrigation valve to be configured accordingly. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION VALVE CONFIG SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | | | | Master Valve | | | +| Valve ID | | | | | | | | | | | | | | | | | | | | | | | | +| Nominal Current High Threshold | | | | | | | | | | | | | | | | | | | | | | | | +| Nominal Current Low Threshold | | | | | | | | | | | | | | | | | | | | | | | | +| Maximum Flow Precision | | | | | | | | | Maximum Flow Scale=l/h | | | | | | Maximum Flow Size | | | | | | | | | +| Maximum Flow Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Maximum Flow Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Flow High Threshold Precision | | | | | | | | | Flow High Threshold Scale=l/h | | | | | | Flow High Threshold Size | | | | | | | | | +| Flow High Threshold Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Flow High Threshold Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Flow Low Threshold Precision | | | | | | | | | Flow Low Threshold Scale=l/h | | | | | | Flow Low Threshold Size | | | | | | | | | +| Flow Low Threshold Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Flow Low Threshold Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Usage | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Master Valve (1 bit) + +This field is used to indicate whether the valve to configure is the master valve or a zone valve. + +The value 1 MUST indicate that the valve to configure is the master valve. The value 0 MUST indicate that the valve to configure is the zone valve corresponding to Valve ID field. Valve ID (8 bits) + +This field is used to indicate the Valve ID to configure. + +This field MUST be set to a Valve ID supported by the receiving node. + +If the Master Valve field is set to 1, this field MUST be set to 1. Other values MUST be ignored by a receiving node. + +Nominal Current High Threshold (8 bits) + +This field is used to configure the nominal current high threshold for the actual valve. + +[The receiving node MUST issue an Irrigation System Status Report Command with the System Error](04.42.07-irrigation-system-status-report-command.md#4427-irrigation-system-status-report-command) Status indicating that a valve is reporting errors when the current crosses above this threshold. + +This field MUST be expressed as a multiple of 10mA. E.g. the value 23 represents 230 mA. + +Nominal Current Low Threshold (8 bits) + +This field is used to configure the nominal current low threshold for the actual valve at the receiving node. + +[The receiving node MUST issue an Irrigation System Status Report Command with the System Error](04.42.07-irrigation-system-status-report-command.md#4427-irrigation-system-status-report-command) Status indicating that a valve is reporting errors when the current crosses below this threshold. + +This field MUST be expressed as a multiple of 10mA. E.g. the value 23 represents 230 mA. + +Maximum Flow + +These fields are used to configure the maximum allowed water flow for the specified valve. + +These fields MUST be ignored if the Master Valve field is set to 1. A receiving node having no support for flow sensor MAY ignore these fields. + +[If the receiving node supports a flow sensor, the node MUST issue an Irrigation System Status Report Command with the System Error Status indicating that a valve is reporting errors when the water flow](04.42.07-irrigation-system-status-report-command.md#4427-irrigation-system-status-report-command) crosses above this threshold. + +This field MUST be expressed in l/h (liter/hour). + +Flow High Threshold + +These fields are used to configure the flow high threshold for the specified valve. + +These fields MUST be ignored if the Master Valve field is set to 1. A receiving node having no support for flow sensor MAY ignore these fields. + +[If the receiving node supports a flow sensor, the node MUST issue an Irrigation System Status Report Command with the System Error Status indicating that a valve is reporting errors when the water flow](04.42.07-irrigation-system-status-report-command.md#4427-irrigation-system-status-report-command) crosses above this threshold. + +The format of the Flow High Threshold fields MUST comply with the format used by the Multilevel Sensor Command Class and MUST be expressed in l/h (liter/hour). Flow Low Threshold + +These fields are used to configure the flow low threshold for the specified valve. + +These fields MUST be ignored if the Master Valve field is set to 1. A receiving node having no support for flow sensor MAY ignore these fields. + +[If the receiving node supports a flow sensor, the node MUST issue an Irrigation System Status Report Command with the System Error Status indicating that a valve is reporting errors when the water flow](04.42.07-irrigation-system-status-report-command.md#4427-irrigation-system-status-report-command) crosses below this threshold. + +The format of the Flow Low Threshold fields MUST comply with the format used by the Multilevel Sensor Command Class and MUST be expressed in l/h (liter/hour). + +Sensor Usage (8 bits) + +This field is used to configure if the actual valve must turn off / close when the specified sensors are active. + +This field MUST be ignored if the Master Valve field is set to 1. [This field MUST be treated as a bit mask and MUST comply with Table 55.](04.42.13-irrigation-valve-config-set-command.md#44213-irrigation-valve-config-set-command) + +Table 55, Irrigation Valve Config Set::Sensor Usage encoding + +| | Bit | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0 | | | Use Rain Sensor The valve MUST turn off / close if rain is detected A receiving node having no support for rain sensor MAY ignore this field. | | | +| 1 | | | Use Moisture Sensor The valve MUST turn off / close if moisture is detected A receiving node having no support for moisture sensor MAY ignore this field. | | | +| 2..7 | | | Reserved | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.14-irrigation-valve-config-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.14-irrigation-valve-config-get-command.md new file mode 100644 index 0000000..29ef5bd --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.14-irrigation-valve-config-get-command.md @@ -0,0 +1,39 @@ + +# 4.42.14 Irrigation Valve Config Get Command + +This command is used to request the current configuration of an irrigation valve. + +The Irrigation Valve Config Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION VALVE CONFIG GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | | | | Master Valve | | | +| Valve ID | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Master Valve (1 bit) + +This field is used to indicate whether the sending node requests the configuration of the master valve or of a zone valve. + +The value 1 MUST indicate that the sending node requests the master valve configuration. The value 0 MUST indicate that the sending node requests the configuration related to the zone valve corresponding to Valve ID field. + +Valve ID (8 bits) + +This field is used to indicate the Valve ID if the sending node requests the information about a zone valve. + +This field MUST be set to a Valve ID supported by the receiving node. A node receiving this command for an unsupported zone valve ID SHOULD return a report for the first supported zone valve. + +If the Master Valve field is set to 1, this field MUST be set to 1. Other values MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.15-irrigation-valve-config-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.15-irrigation-valve-config-report-command.md new file mode 100644 index 0000000..75e9040 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.15-irrigation-valve-config-report-command.md @@ -0,0 +1,34 @@ + +# 4.42.15 Irrigation Valve Config Report Command + +This command is used to advertise the configuration of a valve. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION VALVE CONFIG REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | | | | Master Valve | | | +| Valve ID | | | | | | | | | | | | | | | | | | | | | | | | +| Nominal Current High Threshold | | | | | | | | | | | | | | | | | | | | | | | | +| Nominal Current Low Threshold | | | | | | | | | | | | | | | | | | | | | | | | +| Maximum Flow Precision | | | | | | | | | Maximum Flow Scale=l/h | | | | | | Maximum Flow Size | | | | | | | | | +| Maximum Flow Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Maximum Flow Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Flow High Threshold Precision | | | | | | | | | Flow High Threshold Scale=l/h | | | | | | Flow High Threshold Size | | | | | | | | | +| Flow High Threshold Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Flow High Threshold Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Flow Low Threshold Precision | | | | | | | | | Flow Low Threshold Scale=l/h | | | | | | Flow Low Threshold Size | | | | | | | | | +| Flow Low Threshold Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Flow Low Threshold Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Usage | | | | | | | | | | | | | | | | | | | | | | | | + +[For fields’ description, refer to 4.42.13 Irrigation Valve Config Set Command. A sending node MUST comply with field descriptions in 4.42.13 Irrigation Valve Config Set Command.](04.42.13-irrigation-valve-config-set-command.md#44213-irrigation-valve-config-set-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.16-irrigation-valve-run-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.16-irrigation-valve-run-command.md new file mode 100644 index 0000000..055c2d0 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.16-irrigation-valve-run-command.md @@ -0,0 +1,43 @@ + +# 4.42.16 Irrigation Valve Run Command + +The Irrigation Valve Run Command will run the specified valve for a specified duration. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION VALVE RUN _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | | | | Master Valve | | | +| Valve ID | | | | | | | | | | | | | | | | | | | | | | | | +| Duration MSB | | | | | | | | | | | | | | | | | | | | | | | | +| Duration LSB | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Master Valve (1 bit) + +This field is used to indicate if the specified valve is the master valve or a zone valve. + +The value 1 MUST indicate that the specified valve is the master valve. The value 0 MUST indicate that the specified valve is the zone valve corresponding to Valve ID field. + +Valve ID (8 bits) + +This field is used to specify the actual Valve ID. + +This field MUST be set to a Valve ID supported by the receiving node. + +If the Master Valve field is set to 1, this field MUST be set to 1. Other values MUST be ignored by a receiving node. + +Duration (16 bits) + +This field is used to specify the duration of the run in seconds. + +The value 0 MUST indicate that the valve MUST be turned off / Closed immediately. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.17-irrigation-valve-table-set-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.17-irrigation-valve-table-set-command.md new file mode 100644 index 0000000..3c5bfbe --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.17-irrigation-valve-table-set-command.md @@ -0,0 +1,39 @@ + +# 4.42.17 Irrigation Valve Table Set Command + +This command is used to set a valve table with a list of valves and durations. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION VALVE TABLE SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Valve Table ID | | | | | | | | | | | | | | | | | | | | | | | | +| | Valve ID 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Duration MSB 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Duration LSB 1 | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Valve ID N | | | | | | | | | | | | | | | | | | | | | | | +| | Duration MSB N | | | | | | | | | | | | | | | | | | | | | | | +| | Duration LSB N | | | | | | | | | | | | | | | | | | | | | | | + +Valve Table ID (8 bits) + +This field is used to specify the valve table ID. + +This field MUST be set to a Valve Table ID supported by the receiving node. + +Valve ID and Duration (N * 3 bytes) + +These fields are used to specify valve IDs and their associated run duration. + +A sending node MUST NOT specify more Valve IDs than the “Valve Table Max Size” advertised by a [receiving node in the Irrigation System Info Report Command](04.42.05-irrigation-system-info-report-command.md#4425-irrigation-system-info-report-command) + +The duration MUST be expressed in seconds. + +This field MAY be omitted in order to erase/empty the specified valve table. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.18-irrigation-valve-table-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.18-irrigation-valve-table-get-command.md new file mode 100644 index 0000000..8bf2ecd --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.18-irrigation-valve-table-get-command.md @@ -0,0 +1,26 @@ + +# 4.42.18 Irrigation Valve Table Get Command + +This command is used to request the contents of the specified Valve Table ID. + +The Irrigation Valve Table Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION VALVE TABLE GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Valve Table ID | | | | | | | | | | | | | | | | | | | | | | | | + +Valve Table ID (8 bits) + +This field is used to specify the valve table ID. + +Valves tables MUST be identified sequentially from 1 to the total number available on the device. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.19-irrigation-valve-table-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.19-irrigation-valve-table-report-command.md new file mode 100644 index 0000000..d220d0b --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.19-irrigation-valve-table-report-command.md @@ -0,0 +1,25 @@ + +# 4.42.19 Irrigation Valve Table Report Command + +This command provides the contents of the specified Valve Table ID. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION VALVE TABLE REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Valve Table ID | | | | | | | | | | | | | | | | | | | | | | | | +| | Valve ID 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Duration MSB 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Duration LSB 1 | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Valve ID N | | | | | | | | | | | | | | | | | | | | | | | +| | Duration MSB N | | | | | | | | | | | | | | | | | | | | | | | +| | Duration LSB N | | | | | | | | | | | | | | | | | | | | | | | + +[For fields’ description, refer to 4.42.17 Irrigation Valve Table Set Command. A sending node MUST comply with field descriptions in 4.42.17 Irrigation Valve Table Set Command.](04.42.17-irrigation-valve-table-set-command.md#44217-irrigation-valve-table-set-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.20-irrigation-valve-table-run-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.20-irrigation-valve-table-run-command.md new file mode 100644 index 0000000..836de66 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.20-irrigation-valve-table-run-command.md @@ -0,0 +1,24 @@ + +# 4.42.20 Irrigation Valve Table Run Command + +This command is used to run the specified valve tables sequentially. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION VALVE TABLE RUN _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Valve Table ID 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Valve Table ID N | | | | | | | | | | | | | | | | | | | | | | | | + +Valve Table ID (N bytes) + +This field is used to specify the list of Valve Tables to run sequentially. + +A receiving node MUST run the indicated Valve Table ID starting by the entry 1. These fields contain a variable list of valve table IDs that will be run sequentially in the order they are listed. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.21-irrigation-system-shutoff-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.21-irrigation-system-shutoff-command.md new file mode 100644 index 0000000..9c138f9 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/04.42.21-irrigation-system-shutoff-command.md @@ -0,0 +1,34 @@ + +# 4.42.21 Irrigation System Shutoff Command + +This command is used to prevent any irrigation activity triggered by the Schedule CC for a specified duration. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS IRRIGATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = IRRIGATION SYSTEM SHUTOFF _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Duration (8 bits) + +This field is used to indicate the duration of the system shutoff. + +Values in the range 1..254 MUST indicate how many hours the irrigation system MUST stay shut off after reception of this command. While active, the shutoff duration MUST prevent all enabled schedules (including the back-up schedule) from running. After the shutoff duration is over, any enabled schedule MUST run as configured. + +The value 0 MUST indicate to turn off any running valve (including the master valve) as well as cancel any active Irrigation Valve Table Run or Schedule. Any subsequent schedule MUST run as configured. + +The value 255 MUST indicate that the irrigation system MUST stay permanently shut off until the node receives one of the following commands: + + [Irrigation System Shutoff Command with a Duration different than 255.](04.42.21-irrigation-system-shutoff-command.md#44221-irrigation-system-shutoff-command)  [Irrigation Valve Run Command](04.42.16-irrigation-valve-run-command.md#44216-irrigation-valve-run-command)  [Irrigation Valve Table Run Command](04.42.20-irrigation-valve-table-run-command.md#44220-irrigation-valve-table-run-command) + +When permanently shut off, the node MUST NOT run any schedule + +[A receiving node MUST cancel the current shutoff and advertise a shutoff duration of 0 in the Irrigation System Status Report Command after receiving one of the following commands:](04.42.07-irrigation-system-status-report-command.md#4427-irrigation-system-status-report-command) + + [Irrigation Valve Run Command](04.42.16-irrigation-valve-run-command.md#44216-irrigation-valve-run-command)  [Irrigation Valve Table Run Command](04.42.20-irrigation-valve-table-run-command.md#44220-irrigation-valve-table-run-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/index.md b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/index.md new file mode 100644 index 0000000..0507df4 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.42-irrigation-command-class-version-1/index.md @@ -0,0 +1,34 @@ + +# 4.42 Irrigation Command Class, version 1 + +The Irrigation Command Class provides commands to manage irrigation systems. + +## Contents + +- [4.42.1 Terminology](04.42.01-terminology.md) +- [4.42.2 Compatibility considerations](04.42.02-compatibility-considerations.md) +- [4.42.3 Interoperability considerations](04.42.03-interoperability-considerations.md) +- [4.42.4 Irrigation System Info Get Command](04.42.04-irrigation-system-info-get-command.md) +- [4.42.5 Irrigation System Info Report Command](04.42.05-irrigation-system-info-report-command.md) +- [4.42.6 Irrigation System Status Get Command](04.42.06-irrigation-system-status-get-command.md) +- [4.42.7 Irrigation System Status Report Command](04.42.07-irrigation-system-status-report-command.md) +- [4.42.8 Irrigation System Config Set Command](04.42.08-irrigation-system-config-set-command.md) +- [4.42.9 Irrigation System Config Get Command](04.42.09-irrigation-system-config-get-command.md) +- [4.42.10 Irrigation System Config Report Command](04.42.10-irrigation-system-config-report-command.md) +- [4.42.11 Irrigation Valve Info Get Command](04.42.11-irrigation-valve-info-get-command.md) +- [4.42.12 Irrigation Valve Info Report Command](04.42.12-irrigation-valve-info-report-command.md) +- [4.42.13 Irrigation Valve Config Set Command](04.42.13-irrigation-valve-config-set-command.md) +- [4.42.14 Irrigation Valve Config Get Command](04.42.14-irrigation-valve-config-get-command.md) +- [4.42.15 Irrigation Valve Config Report Command](04.42.15-irrigation-valve-config-report-command.md) +- [4.42.16 Irrigation Valve Run Command](04.42.16-irrigation-valve-run-command.md) +- [4.42.17 Irrigation Valve Table Set Command](04.42.17-irrigation-valve-table-set-command.md) +- [4.42.18 Irrigation Valve Table Get Command](04.42.18-irrigation-valve-table-get-command.md) +- [4.42.19 Irrigation Valve Table Report Command](04.42.19-irrigation-valve-table-report-command.md) +- [4.42.20 Irrigation Valve Table Run Command](04.42.20-irrigation-valve-table-run-command.md) +- [4.42.21 Irrigation System Shutoff Command](04.42.21-irrigation-system-shutoff-command.md) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.43-language-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.43-language-command-class-version-1.md new file mode 100644 index 0000000..2d9e8ef --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.43-language-command-class-version-1.md @@ -0,0 +1,81 @@ + +# 4.43 Language Command Class, version 1 + +The Language Command Class is used to specify the language settings on a device. + +## 4.43.1 Language Set Command + +This command is used to set the language at the receiving node. The receiving node SHOULD use the default language in case the received language is not supported. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS LANGUAGE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = LANGUAGE SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Language 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Language 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Language 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Country 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Country 2 | | | | | | | | | | | | | | | | | | | | | | | | + +Language (24 bits) + +The code definition of the languages may be found in ISO 639-2:1998 ‘Codes for the representation of names of languages – Part 2: Alpha-3 code’. In the table below are some examples of the alpha-3 codes listed: + +| | Language | | | Language 1 | | | Language 2 | | | Language 3 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| English | | | e | | | n | | | g | | | +| Flemish; Dutch | | | d | | | u | | | t | | | +| French | | | f | | | r | | | e | | | +| German | | | g | | | e | | | r | | | +| Italian | | | i | | | t | | | a | | | +| Polish | | | p | | | o | | | l | | | +| Russian | | | r | | | u | | | s | | | +| Walloon | | | w | | | l | | | n | | | + +Country (16 bits) + +The code definition of the countries may be found in ISO 3166-1 ‘Country Codes: Alpha-2 codes’. The use of the country field is OPTIONAL and only defined in case it is necessary for distinguishing geographical variants. The number of data fields transmitted MUST be determined from the length field in the frame. In the table below are some examples of the alpha-2 codes listed: + +| | Language | | | Country 1 | | | Country 2 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| Belgium | | | B | | | E | | +| Italy | | | I | | | T | | +| Netherlands | | | N | | | L | | +| Poland | | | P | | | L | | +| United Kingdom | | | G | | | B | | +| United States | | | U | | | S | | + +## 4.43.2 Language Get Command + +This command is used to request the current language setting in a device. + +The Language Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS LANGUAGE _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Command = LANGUAGE GET _ | | | | | | | | | | | | | | | | | | | | | | | + +## 4.43.3 Language Report Command + +This commandreturns the current language setting in a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS LANGUAGE _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Command = LANGUAGE REPORT _ | | | | | | | | | | | | | | | | | | | | | | | +| Language 1 | | | | | | | | | | | | | | | | | | | | | | | +| Language 2 | | | | | | | | | | | | | | | | | | | | | | | +| Language 3 | | | | | | | | | | | | | | | | | | | | | | | +| Country 1 | | | | | | | | | | | | | | | | | | | | | | | +| Country 2 | | | | | | | | | | | | | | | | | | | | | | | + +[For fields’ description, refer to 4.43.1 Language Set Command.](04.43-language-command-class-version-1.md#4431-language-set-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.44-lock-command-class-version-1-deprecated.md b/docs/specs/command-class-specification/04-command-class-definitions/04.44-lock-command-class-version-1-deprecated.md new file mode 100644 index 0000000..9b17053 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.44-lock-command-class-version-1-deprecated.md @@ -0,0 +1,55 @@ + +# 4.44 Lock Command Class, version 1 [DEPRECATED] + +THIS COMMAND CLASS HAS BEEN DEPRECATED + +A device MAY implement this command class, but it is RECOMMENDED that new implementations use the Door Lock Command Class. If implementing this command class, it is RECOMMENDED that the Door Lock Command Class is also implemented. + +The Lock Command Class is used to lock and unlock a “lock” type device, e.g. a door or window lock + +## 4.44.1 Lock Set Command + +This command is used to set the lock state in a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS LOCK _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = LOCK SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Lock State | | | | | | | | | | | | | | | | | | | | | | | | + +Lock State (8 bits) + +The lock state field used to set the lock state of the device. The value 0 indicates that the device is unlocked. The value 1 indicates that the device is locked. + +## 4.44.2 Lock Get Command + +This command is used to request the lock state from a device. + +The Lock Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS LOCK _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = LOCK GET _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.44.3 Lock Report Command + +This command is used to report the lock state of a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS LOCK _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = LOCK REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Lock State | | | | | | | | | | | | | | | | | | | | | | | | + +Lock State (8 bits) + +The Lock state field used to report the lock state of the device. The value 0 indicates that the device is unlocked. The value 1 indicates that the device is locked. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.45-manufacturer-proprietary-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.45-manufacturer-proprietary-command-class-version-1.md new file mode 100644 index 0000000..e349396 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.45-manufacturer-proprietary-command-class-version-1.md @@ -0,0 +1,39 @@ + +# 4.45 Manufacturer Proprietary Command Class, version 1 + +The Manufacturer Proprietary Command Class is used to transfer data between devices in the Z-Wave network. The data content MUST be vendor specific and MUST be non-value added with respect to the Home Automation application in general. An example could be data used to diagnose the hardware in a device. + +Note: Do not use the Manufacturer Proprietary Command Class without written approval from Sigma Designs. + +## 4.45.1 Manufacturer Proprietary Command + +Thiscommand is used to transfer proprietary commands between devices. The Command features a manufacturer specific identifier to allow the receiving device to check if this Command can be interpreted. The vendor is responsible for establishing a Command structure to differ between the set of Commands supported. + +In order not to congest the Z-Wave network, large data transfers MUST leave transmit opportunities for other nodes in the network. If sending a command longer than two frames, a node MUST implement a delay between every transmitted frame. The minimum required time delay and number of frames before a delay must be inserted depends on the actual bit rate. + + 40 kbit/s: At least 35 ms if sending more than 2 frames back-to-back  100 kbit/s: At least 15 ms if sending more than 2 frames back-to-back + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS MANUFACTURER PROPRIETARY _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Manufacturer ID 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Manufacturer ID 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Data 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Data N | | | | | | | | | | | | | | | | | | | | | | | | + +Manufacturer ID (16 bits) + +The Manufacturer ID is a unique ID identifying the manufacturer of the device. Manufacturer identifiers [can be found in [12].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +The first byte (Manufacturer ID 1) is the most significant byte. + +Data (N bytes) + +The data fields may be used for data transfer etc. The number of data fields transmitted MUST be determined from the length field in the frame. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.46-meter-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.46-meter-command-class-version-1.md new file mode 100644 index 0000000..ee9827c --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.46-meter-command-class-version-1.md @@ -0,0 +1,93 @@ + +# 4.46 Meter Command Class, version 1 + +The Meter Command Class defines the Commands necessary to read accumulated values in physical units from a water meter or metering device (gas, electric etc.) and thereby enabling automatic meter reading capabilities. + +Automatic meter reading (AMR), is the technology of automatically collecting data from water meter or energy metering devices and transferring that data to a central database for billing and/or analyzing. + +## 4.46.1 Terminology + +A meter is used to monitor a resource. The meter accumulates the resource flow over time. As an option, the meter may report not only the most recent accumulated reading but also the previous reading and the time that elapsed since then. A meter may also be able to report the current resource flow. This is known as the instant value. + +Meters may report two rate types. A utility installs production meters in its production facilities, while it installs consumption meters at consumer premises. The difference is the mapping of the physical flow direction to the forward direction of the meter: + + The accumulated value of a production meter grows when more resources are produced  The accumulated value of a production meter drops when more resources are consumed + + The accumulated value of a consumption meter grows when more resources are consumed  The accumulated value of a consumption meter drops when more resources are produced + +If a meter only supports one rate type, the meter may run backwards. If a meter runs backwards, the accumulated value may eventually become negative. While the production meter of a power generator rarely runs backwards, the consumption meter in a private household with solar panels runs backwards every time the solar panels deliver more than is consumed in the household. The actual reading of a one-rate type meter reflects the net accumulated value since the meter was installed with a factory default reading of zero. The accumulated value over an arbitrary interval may be calculated by subtracting a previous accumulated value from the current accumulated value. Normal arithmetic rules ensure that this also works in case of negative values. + +A production meter may be used as a consumption meter by applying a sign change to all production meter readings before using the values as consumption meter readings. + +A meter device may advertise that it implements two separate registers for the production and consumption, respectively. In that case, both of these meters are always running forward: Production makes the production meter run forward while consumption makes the consumption meter run forward. Two meter reports must be used to report the values of the respective meters. + +## 4.46.2 Meter Get Command + +The Meter Get Command is used to request the accumulated consumption in physical units from a metering device. + +The Meter Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER GET _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.46.3 Meter Report Command + +The Meter Report Command is used to advertise a meter reading. + +This command MUST NOT be transmitted using broadcast. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Meter Type | | | | | | | | | | | | | | | | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | | | | +| Meter Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Meter Value N | | | | | | | | | | | | | | | | | | | | | | | | + +Meter Type (8 bits) + +Meter Type specifies what type of metering device this Command originates from. This field MUST be [encoded according to Table 56.](04.46-meter-command-class-version-1.md#4463-meter-report-command) + +Table 56, Meter Report::Meter Type encoding + +| | Value | | | Meter Type | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x01 | | | Electric meter | | | 1 | | | +| 0x02 | | | Gas meter | | | 1 | | | +| 0x03 | | | Water meter | | | 1 | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. Precision (3 bits) + +The precision field describes what the precision of the value is. The number indicates the number of decimals. The decimal value 1025 with precision 2 is therefore equal to 10.25. + +The value of the precision field MUST be in the range 0..7. + +Scale (2 bits) + +The Scale field MUST advertise the unit used for this report. This field MUST be encoded according to [Table 65.](04.50-meter-command-class-version-5.md#4503-meter-report-command) + +Size (3 bits) + +The size field indicates the number of bytes that used for the meter value. This field can take values from 1 (001b), 2 (010b) or 4 (100b). + +Meter Value (N bytes) + +The Meter Value is a signed field. The field MAY be 1, 2 or 4 bytes in size. The first byte is the most significant byte. + +[The field MUST be encoded using signed representation and comply with Table 10.](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) + +The metering device receiving the Meter Report MUST always show the value even though the Metering Device Type and/or Scale are not supported + +A controlling node SHOULD implement the capability to update its list of Meter Type and Scales, so that new Meter Types and scales added in more recent versions are not presented as unknown. If a controlling node receives an unknown Meter Type or Scale, it SHOULD allow the user to assign a free- text description to that Meter reading diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.47-meter-command-class-version-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.47-meter-command-class-version-2.md new file mode 100644 index 0000000..765b89c --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.47-meter-command-class-version-2.md @@ -0,0 +1,246 @@ + +# 4.47 Meter Command Class, version 2 + +The Meter Command Class is intended for devices capable of reporting energy measurements in addition to any main functionality or features e.g. an appliance module reporting the current consumption of the connected load. This command class is not intended for residential utility sub-metering such as a water meter counting total consumption. + +Meter Command Class (version 2) is improved with the following functionalities: + + Commands to interview the device for supported Meter types  New field ‘Previous Meter Value’ added to the Meter Report to allow for easy calculation of consumption since previous measurement  Reset of accumulated consumption  Add capability to communicate current consumption (W)  ‘Scale’ entry for pulse meters along with W, kVAh and Cubic feet + +The commands not mentioned are the same as specified for Meter Command Class (Version 1). + +## 4.47.1 Meter Supported Get Command + +This command is used to request the supported scales in a sub meter. + +The Meter Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | 6 | | | 5 | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER _ _ | | | | | | | | | | | | | | | | | | | | +| Command = METER SUPPORTED GET _ _ | | | | | | | | | | | | | | | | | | | | + +## 4.47.2 Meter Supported Report Command + +This command is used to advertise supported scales in a sub meter. + +| | 7 | 6 | | | 5 | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER _ _ | | | | | | | | | | | | | | | | | | | | +| Command = METER SUPPORTED REPORT _ _ | | | | | | | | | | | | | | | | | | | | +| Meter Reset | | Reserved | | | | Meter Type | | | | | | | | | | | | | | +| Reserved | | | | | | | | Scale Supported | | | | | | | | | | | | + +Meter Reset (1 bit) + +The Meter Reset field set to “1” indicates support for the Meter Reset Command. + +Meter Type (5 bits) + +See Meter Type defined in Meter Report Command. + +Scale Supported (4 bits) + +This field MUST advertise the supported scales of the device. The field MUST be formatted and interpreted as a bitmask. The bit value ‘1’ MUST indicate support for the actual scale. The bit value ‘0’ MUST indicate that there is no support for the actual scale. + +The Scale Supported bitmask MUST be interpreted in combination with the Meter Type. + +Table 57, Meter Supported Report v2::Scale Supported encoding + +| | Meter Type | | | Scale | | | Scale Supported Bit position | | | Measurement mode | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Electric meter | | | kWh | | | Bit 0 | | | Accumulated | | | +| | | | kVAh | | | Bit 1 | | | Accumulated | | | +| | | | W | | | Bit 2 | | | Instant | | | +| | | | Pulse count | | | Bit 3 | | | Accumulated | | | +| Gas meter | | | Cubic meters | | | Bit 0 | | | Accumulated | | | +| | | | Cubic feet | | | Bit 1 | | | Accumulated | | | +| | | | Reserved | | | Bit 2 | | | n/a | | | +| | | | Pulse count | | | Bit 3 | | | Accumulated | | | +| Water meter | | | Cubic meters | | | Bit 0 | | | Accumulated | | | +| | | | Cubic feet | | | Bit 1 | | | Accumulated | | | +| | | | US gallons | | | Bit 2 | | | Accumulated | | | +| | | | Pulse count | | | Bit 3 | | | Accumulated | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +## 4.47.3 Meter Reset Command + +The Meter Reset Command is used to reset ALL accumulated values stored in the meter device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER RESET _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.47.4 Meter Get Command + +The Meter Get Command is used to request a device supported measurement in physical units from a metering device. + +The Meter Report Command MUST be returned in response to this command if the requested scale is supported. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER GET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Scale | | | | | | Reserved | | | | | | | | | + +Scale (2 bits) + +See description of Meter Report Command. + +If the Scale is not present (v1) or set to 0x00, a receiving node MUST return a Report using its default scale. A Meter Get Command containing a non-supported Scale MUST be ignored by a receiving device. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +### 4.47.4.1 Backwards compatibility + +When devices supporting Meter Command Class (Version 1) receives a Meter Get Command of Version 2 it MUST report its implemented scale. + +The manufacturer MUST define which scale is the default scale and it MUST be described in the product manual. + +## 4.47.5 Meter Report Command + +The Meter Report Command is used to advertise a meter reading. + +The Meter Report Command MUST NOT be transmitted using broadcast. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reser- ved | | | Rate Type | | | | | | Meter Type | | | | | | | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | | | | +| Meter Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Meter Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Delta Time 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Delta Time 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Previous Meter Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Previous Meter Value N | | | | | | | | | | | | | | | | | | | | | | | | + +Rate Type (2 bits) + +Rate Type specifies if it is import or export values to be read. Setting the Rate Type to Import on the Meter Report Command is an indication that the Meter Value is a consumed measurement. In contrary when the Rate Type is set to Export the indication of the Meter Value is a produced measurement. + +[This field MUST be encoded according to Table 58.](04.47-meter-command-class-version-2.md#4475-meter-report-command) + +Table 58, Meter Report::Rate Type encoding + +| | Value | | | Rate Type | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Reserved | | | +| 0x01 | | | Import (consumed) | | | +| 0x02 | | | Export (produced) | | | +| 0x03 | | | Reserved | | | + +Meter Type (5 bits) + +Meter Type specifies what type of metering device this command originates from. This field MUST be [encoded according to Table 56.](04.46-meter-command-class-version-1.md#4463-meter-report-command) Precision (3 bits) + +The Precision field describes what the precision of the value is. The number indicates the number of decimals. The decimal value 1025 with precision 1 MUST be interpreted as 102.5 and if precision is 3 the interpreted value is 1.025. + +Scale (2 bits) + +The Scale field field MUST advertise the unit used for this report. This field MUST be encoded according [to Table 65.](04.50-meter-command-class-version-5.md#4503-meter-report-command) + +Size (3 bits) + +The Size field MUST advertise the number of bytes that is used for the Meter Value. The value of the Size field MUST be in the range (1,2,4). All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Meter Value (N bytes) + +The Meter Value field is a signed field. The Meter Value field MUST have the size advertised by the Size field. The first byte is the most significant byte. + +[The field MUST be encoded using signed representation and comply with Table 10.](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) + +Delta Time (16 bits) + +The Delta Time field MUST advertise the elapsed time in seconds between the ‘Meter Value’ and the ‘Previous Meter Value’ measurements. Values MUST be in the range 0 to 65536 seconds. + +Table 59, Meter Report v2::Delta Time encoding + +| | Delta Time | | | Value | | +| --- | --- | --- | --- | --- | --- | +| No Previous Meter Value field included in the Meter Report | | | 0x0000 | | | +| 1 sec. between Meter Value and Previous Meter Value measurements | | | 0x0001 | | | +| … | | | … | | | +| 65534 sec. between Meter Value and Previous Meter Value measurements | | | 0xFFFE | | | +| Unknown time between Meter Value and Previous Meter Value measurements | | | 0xFFFF | | | + +If the Delta Time is 0, the Previous Meter Value field MUST be omitted. + +Previous Meter Value (N bytes) + +The Previous Meter Value MUST be omitted if the Delta Time field is set to the value 0. The Previous Meter Value MUST be included if the Delta Time field is set to a non-zero value. + +The Previous Meter Value field MUST have the same size and format as the Meter Value field. Refer to the description of the Meter Value field. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +### 4.47.5.1 Examples + +To retrieve accumulated power consumption from a device supporting Meter Command Class (Version 2), the Meter Get Command has to indicate what scale is requested. + +| | 7 | 6 | | | 5 | 4 | | | 3 | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x32 (COMMAND CLASS METER) _ _ | | | | | | | | | | | | | | | | | | | +| 0x01 (METER GET) _ | | | | | | | | | | | | | | | | | | | +| 0 | | | | | | 0 (kWh) | | | | | 0 | | | | | | | | + +As a response to the above Meter Get Command an example of accumulated power consumption can be reported with the below Meter Report indicating a current measurement of 12065.298 kWh and 10 minutes ago the previous measurement was 12060.678 kWh. + +| | 7 | 6 | | | 5 | 4 | | | 3 | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x32 (COMMAND CLASS METER) _ _ | | | | | | | | | | | | | | | | | | | +| 0x02 (METER REPORT) _ | | | | | | | | | | | | | | | | | | | +| 0 | | 2 (export) | | | | 0 (Electric meter) | | | | | | | | | | | | | +| 3 (3 decimals) | | | | | | 0 (kWh) | | | | 4 (4 bytes) | | | | | | | | | +| 0x00 (Meter Value 1) | | | | | | | | | | | | | | | | | | | +| 0xB8 (Meter Value 2) | | | | | | | | | | | | | | | | | | | +| 0x1A (Meter Value 3) | | | | | | | | | | | | | | | | | | | +| 0x12 (Meter Value 4) | | | | | | | | | | | | | | | | | | | +| 0x02 (Delta Time 1) | | | | | | | | | | | | | | | | | | | +| 0x58 (Delta Time 2) | | | | | | | | | | | | | | | | | | | +| 0x00 (Previous Meter Value 1) | | | | | | | | | | | | | | | | | | | +| 0xB8 (Previous Meter Value 2) | | | | | | | | | | | | | | | | | | | +| 0x08 (Previous Meter Value 3) | | | | | | | | | | | | | | | | | | | +| 0x06 (Previous Meter Value 4) | | | | | | | | | | | | | | | | | | | + +To retrieve instant power consumption from a device supporting Meter Command Class (Version 2), the Meter Get Command MUST indicate what scale is requested. + +| | 7 | 6 | | | 5 | 4 | | | 3 | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x32 (COMMAND CLASS METER) _ _ | | | | | | | | | | | | | | | | | | | +| 0x01 (METER GET) _ | | | | | | | | | | | | | | | | | | | +| 0 | | | | | | 2 (W) | | | | | 0 | | | | | | | | + +An example of instant power consumption can be reported with the below Meter Report indicating a current measurement of 39.99 W. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x32 (COMMAND CLASS METER) _ _ | | | | | | | | | | | | | | | | | | | | | | | +| 0x02 (METER REPORT) _ | | | | | | | | | | | | | | | | | | | | | | | +| 0 | | | 2 (export) | | | | | | 0 (Electric meter) | | | | | | | | | | | | | | +| 2 (2 decimals) | | | | | | | | | 2 (W) | | | | | | 2 (2 bytes) | | | | | | | | +| 0x0F (Meter Value 1) | | | | | | | | | | | | | | | | | | | | | | | +| 0x9F (Meter Value 2) | | | | | | | | | | | | | | | | | | | | | | | +| 0x00 (Delta Time 1) | | | | | | | | | | | | | | | | | | | | | | | +| 0x00 (Delta Time 2) | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.48-meter-command-class-version-3.md b/docs/specs/command-class-specification/04-command-class-definitions/04.48-meter-command-class-version-3.md new file mode 100644 index 0000000..d258268 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.48-meter-command-class-version-3.md @@ -0,0 +1,186 @@ + +# 4.48 Meter Command Class, version 3 + +The Meter Command Class is intended for Z-Wave enabled devices capable of reporting energy measurements in addition to any main functionality or features e.g. an appliance module reporting the current consumption of the connected load. This command class is not intended for residential utility sub- metering such as a water meter counting total consumption. + +Meter Command Class (Version 3) is improved with the following functionalities: + + ‘Scale’ entry has been enlarged to support 8 scales + +The commands not mentioned are the same as specified for Meter Command Class (Version 2). + +## 4.48.1 Meter Supported Report Command + +This command is used to advertise supported scales in a sub meter. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER SUPPORTED REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Meter Reset | | | Reserved | | | | | | Meter Type | | | | | | | | | | | | | | | +| Scale Supported | | | | | | | | | | | | | | | | | | | | | | | | + +Meter Reset (1 bit) + +The Meter Reset field set to “1” indicates support for the Meter Reset Command. + +Meter Type (5 bits) + +See Meter Type defined in Meter Report Command. Scale Supported (8 bits) + +This field is used to advertise the supported scales by the sending node. + +[The field MUST be treated as a bitmask and MUST be encoded according to Table 63.](04.50-meter-command-class-version-5.md#4502-meter-supported-report-command) + +The bit value ‘1’ MUST indicate support for the actual scale. The bit value ‘0’ MUST indicate that there is no support for the actual scale. + +The Scale Supported bitmask MUST be interpreted in combination with the Meter Type. + +## 4.48.2 Meter Get Command + +This command is used to request a device supported measurement in physical units from a metering device. + +The Meter Report Command MUST be returned in response to this command if the requested scale is supported. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER GET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | Scale | | | | | | | | | Reserved | | | | | | | | | + +Scale (3 bits) + +See description of Meter Report Command. + +If the Scale is not present (v1) or set to 0x00, a receiving node MUST return a Report using its default scale. + +A Meter Get Command containing a non-supported Scale MUST be ignored by a receiving device. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +### 4.48.2.1 Backwards compatibility + +The manufacturer MUST define which scale is the default scale and it MUST be described in the product manual. The default scale MUST be in the range 0..3 as Version 1 and 2 devices will not be able to interpret Scale values in the range 4..7. + +## 4.48.3 Meter Report Command + +This command is used to advertise a meter reading. + +The Meter Report Command MUST NOT be transmitted using broadcast. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Scale (2) | | | Rate Type | | | | | | Meter Type | | | | | | | | | | | | | | | +| Precision | | | | | | | | | Scale (1:0) | | | | | | Size | | | | | | | | | +| Meter Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Meter Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Delta Time 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Delta Time 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Previous Meter Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Previous Meter Value N | | | | | | | | | | | | | | | | | | | | | | | | + +Rate Type (2 bits) + +Rate Type specifies if it is import or export values to be read. Setting the Rate Type to Import on the Meter Report Command is an indication that the Meter Value is a consumed measurement. In contrary when the Rate Type is set to Export the indication of the Meter Value is a produced measurement. + +[This field MUST be encoded according to Table 58.](04.47-meter-command-class-version-2.md#4475-meter-report-command) + +Meter Type (5 bits) + +Meter Type specifies what type of metering device this command originates from. This field MUST be [encoded according to Table 56.](04.46-meter-command-class-version-1.md#4463-meter-report-command) + +Precision (3 bits) + +The Precision field describes what the precision of the value is. The number indicates the number of decimals. The decimal value 1025 with precision 1 MUST be interpreted as 102.5 and if precision is 3 the interpreted value is 1.025. + +The value of the precision field MUST be in the range 0..7. Scale (3 bits) + +The Scale field field MUST advertise the unit used for this report. The Scale field is composed of two sub-fields Scale (2) and Scale (1:0) which MUST be composed and interpreted as one unit. + +[This field MUST be encoded according to Table 65.](04.50-meter-command-class-version-5.md#4503-meter-report-command) + +Size (3 bits) + +The Size field MUST advertise the number of bytes that is used for the Meter Value. The value of the Size field MUST be in the range (1,2,4). All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Meter Value (N bytes) + +The Meter Value field is a signed field. The Meter Value field MUST have the size advertised by the Size field. The first byte MUST be the most significant byte. + +[The field MUST be encoded using signed representation and comply with Table 10.](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) + +Delta Time (16 bits) + +The Delta Time field MUST advertise the elapsed time in seconds between the ‘Meter Value’ and the ‘Previous Meter Value’ measurements. + +[This field MUST comply with Table 59.](04.47-meter-command-class-version-2.md#4475-meter-report-command) + +If the Delta Time is 0, the Previous Meter Value field MUST be omitted. + +Previous Meter Value (N bytes) + +The Previous Meter Value MUST be omitted if the Delta Time field is set to the value 0. The Previous Meter Value MUST be included if the Delta Time field is set to a non-zero value. + +The Previous Meter Value field MUST have the same size and format as the Meter Value field. Refer to the description of the Meter Value field. + +### 4.48.3.1 Examples of Meter Report Commands + +To retrieve Instant Voltage from a device supporting Meter Command Class (Version 3), the Meter Get Command has to indicate what scale is requested. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x32 (COMMAND CLASS METER) _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| 0x01 (METER GET) _ | | | | | | | | | | | | | | | | | | | | | | | | +| 0 | | | | | | 4 (V) | | | | | | | | | 0 | | | | | | | | | + +As a response to the above Meter Get Command an example of instant Voltage can be reported with the below Meter Report indicating a current measurement of 108.5 V and 10 minutes ago the previous measurement was 109.1V. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x32 (COMMAND CLASS METER) _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| 0x02 (METER REPORT) _ | | | | | | | | | | | | | | | | | | | | | | | | +| 1 (V) | | | 2 (export) | | | | | | 0 (Electric meter) | | | | | | | | | | | | | | | +| 1 (1 decimals) | | | | | | | | | 0 (V) | | | | | | 4 (4 bytes) | | | | | | | | | +| 0x00 (Meter Value 1) | | | | | | | | | | | | | | | | | | | | | | | | +| 0x00 (Meter Value 2) | | | | | | | | | | | | | | | | | | | | | | | | +| 0x04 (Meter Value 3) | | | | | | | | | | | | | | | | | | | | | | | | +| 0x3D (Meter Value 4) | | | | | | | | | | | | | | | | | | | | | | | | +| 0x02 (Delta Time 1) | | | | | | | | | | | | | | | | | | | | | | | | +| 0x58 (Delta Time 2) | | | | | | | | | | | | | | | | | | | | | | | | +| 0x00 (Previous Meter Value 1) | | | | | | | | | | | | | | | | | | | | | | | | +| 0x00 (Previous Meter Value 2) | | | | | | | | | | | | | | | | | | | | | | | | +| 0x04 (Previous Meter Value 3) | | | | | | | | | | | | | | | | | | | | | | | | +| 0x43 (Previous Meter Value 4) | | | | | | | | | | | | | | | | | | | | | | | | + +To retrieve instant power consumption from a device supporting Meter Command Class (Version 2), the Meter Get Command has to indicate what scale is requested. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x32 (COMMAND CLASS METER) _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| 0x01 (METER GET) _ | | | | | | | | | | | | | | | | | | | | | | | | +| 0 | | | | | | | | | 2 (W) | | | | | | 0 | | | | | | | | | + +An example of instant power consumption can be reported with the below Meter Report indicating a current measurement of 39.99 W. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x32 (COMMAND CLASS METER) _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| 0x02 (METER REPORT) _ | | | | | | | | | | | | | | | | | | | | | | | | +| 0 | | | 2 (export) | | | | | | 0 (Electric meter) | | | | | | | | | | | | | | | +| 2 (2 decimals) | | | | | | | | | 2 (W) | | | | | | 2 (2 bytes) | | | | | | | | | +| 0x0F (Meter Value 1) | | | | | | | | | | | | | | | | | | | | | | | | +| 0x9F (Meter Value 2) | | | | | | | | | | | | | | | | | | | | | | | | +| 0x00 (Delta Time 1) | | | | | | | | | | | | | | | | | | | | | | | | +| 0x00 (Delta Time 2) | | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.49-meter-command-class-version-4.md b/docs/specs/command-class-specification/04-command-class-definitions/04.49-meter-command-class-version-4.md new file mode 100644 index 0000000..444e05a --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.49-meter-command-class-version-4.md @@ -0,0 +1,216 @@ + +# 4.49 Meter Command Class, version 4 + +The Meter Command Class is intended for Z-Wave enabled devices capable of reporting energy measurements in addition to any main functionality or features e.g. an appliance module reporting the current consumption of the connected load. This command class is not intended for residential utility metering such as a water meter counting total consumption. + +Meter Command Class, Version 4 is improved with the following functionalities: + + The Rate Type is included in the Meter Supported Report and the Meter Get Command  Added support for Meter Scale Types kVar and kVarh + +The commands not mentioned are the same as specified for Meter Command Class, Version 3. + +## 4.49.1 Meter Supported Report Command + +This command is used to advertise supported capabilities of a sub meter. + +| | 7 | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER SUPPORTED REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Meter Reset | | | Rate Type | | | | | Meter Type | | | | | | | | | | | | | | | +| M.S.T | | | Scale Supported “Byte 1” | | | | | | | | | | | | | | | | | | | | +| Number of Scale Supported Bytes to Follow (Version 4 Extension) | | | | | | | | | | | | | | | | | | | | | | | +| Scale Supported 1 “Byte 2” | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | +| Scale Supported N “Byte N+1” | | | | | | | | | | | | | | | | | | | | | | | + +Meter Reset (1 bit) + +The Meter Reset field set to “1” indicates support for the Meter Reset Command. Rate Type (2 bits) + +Rate Type specifies if import and export consumption is supported. Import is an indication that the Meter Value is a consumed measurement and Export is an indication that the Meter Value is a produced measurement. + +[This field MUST be encoded according to Table 60.](04.49-meter-command-class-version-4.md#4491-meter-supported-report-command) + +Table 60, Meter Supported Report::Rate Type encoding + +| | Value | | | Rate Type | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | Reserved | | | 1 | | | +| 0x01 | | | Import only (consumed) | | | 1 | | | +| 0x02 | | | Export only (produced) | | | 1 | | | +| 0x03 | | | Both Import and Export | | | 4 | | | + +Meter Type (5 bits) + +See Meter Type defined in Meter Report Command. + +Scale Supported (7 bits) + +This field is used to advertise the supported scales by the sending node. + +[The field MUST be treated as a bitmask and MUST be encoded according to Table 63.](04.50-meter-command-class-version-5.md#4502-meter-supported-report-command) + +The bit value ‘1’ MUST indicate support for the actual scale. The bit value ‘0’ MUST indicate that there is no support for the actual scale. + +The Scale Supported bitmask MUST be interpreted in combination with the Meter Type. + +M.S.T. (More Scale Types) (1 bit) + +This bit MUST be set to ‘1’ when more than one Scale Supported byte is carried in the Meter Supported Report. In this case the Number of Scale Supported Bytes to Follow field MUST advertise the total number of Scale Supported Bytes. The bitmask of the following Scale Supported Bytes is described in the table of Scale Supported. + +The M.S.T bit MUST be set to ‘0’ if the Meter Supported Report only carries the Scale Supported “Byte 1” field. In this case the report MUST NOT include the “Number of Scale Supported Bytes to Follow” field or any “Scale Supported Bytes 1 – N” fields. + +Number of Scale Supported to Follow (8 bits) + +The number of Scale Supported Bytes to follow. Scale Supported (bytes 2..N+1) (N bytes) + +These fields MUST advertise the supported scales of the device not covered by byte 1. The fields MUST be formatted and interpreted as bitmasks. The bit value ‘1’ MUST indicate support for the actual scale. The bit value ‘0’ MUST indicate that there is no support for the actual scale. + +[The Scale Supported bitmask MUST be interpreted in combination with the Meter Type. Refer to to Table 63.](04.50-meter-command-class-version-5.md#4502-meter-supported-report-command) + +## 4.49.2 Meter Get Command + +This command is used to request a device supported measurement in physical units from a metering device. + +The Meter Report Command MUST be returned in response to this command if the requested scale and rate type are supported. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER GET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Type | | | | | | Scale | | | | | | | | | Reserved | | | | | | | | | +| Scale 2 | | | | | | | | | | | | | | | | | | | | | | | | + +Rate Type (2 bits) + +Rate Type specifies if it is import or export values to be requested. Import is an indication that the Meter Value is a consumed measurement and Export is an indication that the Meter Value is a produced measurement. If both Import and Export is needed, two Meter Get Commands must be send. + +Table 61, Meter Get v4::Rate Type encoding + +| | Value | | | Rate Type | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Reserved | | | +| 0x01 | | | Import (consumed) | | | +| 0x02 | | | Export (produced) | | | +| 0x03 | | | Not to be used | | | + +Reserved values MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +If the Rate Type is not present (v1-v3) or set to 0x00, a receiving node MUST return a Report using its default Rate Type. + +Scale (3 bits) + +See description of Meter Report Command. This field MUST specify the scale of the requested meter report. The Scale Value 7 MUST be used to indicate that the scale of the requested meter reading is advertised by the Scale 2 field. + +For valid Scale values, refer to the Meter Report Command V4. + +If the Scale is not present (v1) or set to 0x00, a receiving node MUST return a Report using its default scale. + +A Meter Get Command containing a non-supported Scale MUST be ignored by a receiving device. + +Scale 2 (8 bits) + +The Scale 2 field MUST be appended to the Meter Get Command if the Scale field is set to 7 (M.S.T). The Scale 2 field MUST NOT be appended to the Meter Get Command if the Scale field carries any other value than 7. + +For valid Scale 2 values, refer to the Meter Report Command V4. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +### 4.49.2.1 Backwards compatibility + +The manufacturer MUST define which scale and rate type are the default and it MUST be described in the product manual. The default scale MUST be in the range 0..3 as Version 1 and 2 devices will not be able to interpret Scale values in the range 4..7. + +## 4.49.3 Meter Report Command + +The Meter Report Command is used to advertise a meter reading. + +The Meter Report Command MUST NOT be transmitted using broadcast. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Scale (2) | | | Rate Type | | | | | | Meter Type | | | | | | | | | | | | | | | +| Precision | | | | | | | | | Scale (1:0) | | | | | | Size | | | | | | | | | +| Meter Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Meter Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Delta Time 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Delta Time 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Previous Meter Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Previous Meter Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Scale 2 | | | | | | | | | | | | | | | | | | | | | | | | + +Rate Type (2 bits) + +Rate Type specifies if it is import or export values to be read. Setting the Rate Type to Import on the Meter Report Command is an indication that the Meter Value is a consumed measurement. In contrary when the Rate Type is set to Export the indication of the Meter Value is a produced measurement. + +[This field MUST be encoded according to Table 58.](04.47-meter-command-class-version-2.md#4475-meter-report-command) + +Meter Type (5 bits) + +Meter Type specifies what type of metering device this command originates from. This field MUST be [encoded according to Table 56.](04.46-meter-command-class-version-1.md#4463-meter-report-command) + +Precision (3 bits) + +The Precision field describes what the precision of the value is. The number indicates the number of decimals. The decimal value 1025 with precision 1 must be interpreted as 102.5 and if precision is 3 the interpreted value is 1.025. + +The value of the precision field MUST be in the range 0..7. Scale (3 bits) + +The Scale field MUST advertise the unit used for this report. The Scale field is composed of two sub- fields Scale (2) and Scale (1:0) which MUST be composed and interpreted as one unit. + +[This field MUST be encoded according to Table 65.](04.50-meter-command-class-version-5.md#4503-meter-report-command) + +The Scale Value 7 MUST be used to indicate that the scale of the advertised meter reading is advertised through the Scale 2 field. + +Size (3 bits) + +The Size field MUST advertise the number of bytes that is used for the Meter Value. The value of the Size field MUST be in the range (1,2,4). All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Meter Value (N bytes) + +The Meter Value field is a signed field. The Meter Value field MUST have the size advertised by the Size field. The first byte is the most significant byte. + +[The field MUST be encoded using signed representation and comply with Table 10.](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) + +Delta Time (16 bits) + +The Delta Time field MUST advertise the elapsed time in seconds between the ‘Meter Value’ and the ‘Previous Meter Value’ measurements. + +[This field MUST comply with Table 59](04.47-meter-command-class-version-2.md#4475-meter-report-command) + +If the Delta Time is 0, the Previous Meter Value field MUST be omitted. + +Previous Meter Value (N bytes) + +The Previous Meter Value MUST be omitted if the Delta Time field is set to the value 0. The Previous Meter Value MUST be included if the Delta Time field is set to a non-zero value. + +The Previous Meter Value field MUST have the same size and format as the Meter Value field. Refer to the description of the Meter Value field. Scale 2 (8 bits) + +The Scale 2 field MUST be appended to the Meter Report Command if the Scale field is set to 7 (M.S.T). The Scale 2 field MUST NOT be appended to the Meter Report Command if the Scale field carries any other value than 7. + +[Table 62 shows valid Scale 2 values.](04.49-meter-command-class-version-4.md#4493-meter-report-command) + +Table 62, Meter Report v4::Scale 2 encoding + +| | Meter Type | | | Scale | | | Value | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Electric meter | | | kVar | | | 0x00 | | | +| | | | kVarh | | | 0x01 | | | +| | | | Reserved | | | 0x02 – 0xFF | | | +| Gas meter | | | Reserved | | | 0x00 – 0xFF | | | +| Water meter | | | Reserved | | | 0x00 – 0xFF | | | + +Reserved values MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.50-meter-command-class-version-5.md b/docs/specs/command-class-specification/04-command-class-definitions/04.50-meter-command-class-version-5.md new file mode 100644 index 0000000..2fa2a12 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.50-meter-command-class-version-5.md @@ -0,0 +1,146 @@ + +# 4.50 Meter Command Class, version 5 + +The Meter Command Class is intended for Z-Wave enabled devices capable of reporting cumulated energy measurements e.g. an appliance module reporting the current consumption of the connected load. + +This command class is not intended for residential utility metering such as a water meter counting total consumption. + +## 4.50.1 Compatibility considerations + +Meter Command Class, version 5 adds support for Heating and Cooling Meter types. + +The Meter Command Class, version 5 is backwards compatible with version 4. A node supporting the Meter Command Class, version 5 MUST also support Meter Command Class, version 4. + +Commands and fields not described in this version MUST remain unchanged from version 4. + +## 4.50.2 Meter Supported Report Command + +This command is used to advertise supported capabilities of a sub meter. + +| | 7 | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER SUPPORTED REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Meter Reset | | | Rate Type | | | | | Meter Type | | | | | | | | | | | | | | | +| M.S.T | | | Scale Supported “Byte 1” | | | | | | | | | | | | | | | | | | | | +| Number of Scale Supported Bytes to Follow (Version 4 Extension) | | | | | | | | | | | | | | | | | | | | | | | +| Scale Supported 1 “Byte 2” | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | +| Scale Supported N “Byte N+1” | | | | | | | | | | | | | | | | | | | | | | | + +All fields not described below remain unchanged from version 4. Scale Supported (7 bits) + +This field is used to advertise the supported scales by the sending node. + +[The field MUST be treated as a bitmask and MUST be encoded according to Table 63.](04.50-meter-command-class-version-5.md#4502-meter-supported-report-command) + +The bit value ‘1’ MUST indicate support for the actual scale. The bit value ‘0’ MUST indicate that there is no support for the actual scale. + +The Scale Supported bitmask MUST be interpreted in combination with the Meter Type. + +Table 63, Meter Supported Report::Scale Supported Bitmask encoding + +| | Meter | | Scale | | Scale Supported | | | Scale Supported | | | Measurement | | Version | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| | Type | | | | Byte number | | | Bit position | | | mode | | | +| Electric meter | | | kWh | Byte 1 | | | Bit 0 | | | Accumulated | | | 1 | +| | | | kVAh | Byte 1 | | | Bit 1 | | | Accumulated | | | 2 | +| | | | W | Byte 1 | | | Bit 2 | | | Instant | | | 2 | +| | | | Pulse count | Byte 1 | | | Bit 3 | | | Accumulated | | | 2 | +| | | | V | Byte 1 | | | Bit 4 | | | Instant | | | 3 | +| | | | A | Byte 1 | | | Bit 5 | | | Instant | | | 3 | +| | | | Power factor | Byte 1 | | | Bit 6 | | | Instant | | | 3 | +| | | | kVar | Byte 2 | | | Bit 0 | | | Instant | | | 4 | +| | | | kVarh | Byte 2 | | | Bit 1 | | | Accumulated | | | 4 | +| | | | Reserved | Byte 2 | | | Bit 2-7 | | | Reserved | | | - | +| Gas meter | | | Cubic meters | Byte 1 | | | Bit 0 | | | Accumulated | | | 1 | +| | | | Cubic feet | Byte 1 | | | Bit 1 | | | Accumulated | | | 2 | +| | | | Reserved | Byte 1 | | | Bit 2 | | | n/a | | | - | +| | | | Pulse count | Byte 1 | | | Bit 3 | | | Accumulated | | | 2 | +| | | | Reserved | Byte 1 | | | Bit 4-6 | | | Reserved | | | - | +| | | | Reserved | Byte 2 | | | Bit 0-7 | | | Reserved | | | - | +| Water meter | | | Cubic meters | Byte 1 | | | Bit 0 | | | Accumulated | | | 1 | +| | | | Cubic feet | Byte 1 | | | Bit 1 | | | Accumulated | | | 1 | +| | | | US gallons | Byte 1 | | | Bit 2 | | | Accumulated | | | 1 | +| | | | Pulse count | Byte 1 | | | Bit 3 | | | Accumulated | | | 2 | +| | | | Reserved | Byte 1 | | | Bit 4-6 | | | Reserved | | | - | +| | | | Reserved | Byte 2 | | | Bit 0-7 | | | Reserved | | | - | +| Heating meter | | | kWh | Byte 1 | | | Bit 0 | | | Accumlated | | | 5 | +| Cooling meter | | | kWh | Byte 1 | | | Bit 0 | | | Accumlated | | | 5 | + +## 4.50.3 Meter Report Command + +The Meter Report Command is used to advertise a meter reading. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Scale (2) | | | Rate Type | | | | | | Meter Type | | | | | | | | | | | | | | | +| Precision | | | | | | | | | Scale (1:0) | | | | | | Size | | | | | | | | | +| Meter Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Meter Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Delta Time 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Delta Time 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Previous Meter Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Previous Meter Value N | | | | | | | | | | | | | | | | | | | | | | | | +| Scale 2 | | | | | | | | | | | | | | | | | | | | | | | | + +Fields not described below remain unchanged from version 4. + +Meter Type (8 bits) + +Meter Type specifies what type of metering device this Command originates from. This field MUST be [encoded according to Table 64.](04.50-meter-command-class-version-5.md#4503-meter-report-command) + +Table 64, Meter Report v5::Meter Type encoding + +| | Value | | | Meter Type | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x01 | | | Electric meter | | | 1 | | | +| 0x02 | | | Gas meter | | | 1 | | | +| 0x03 | | | Water meter | | | 1 | | | +| 0x04 | | | Heating meter | | | 5 | | | +| 0x05 | | | Cooling meter | | | 5 | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. Scale (3 bits) + +The Scale field MUST advertise the unit used for this report. The Scale field is composed of two sub- fields Scale (2) and Scale (1:0) which MUST be composed and interpreted as one unit. + +[This field MUST be encoded according to Table 65.](04.50-meter-command-class-version-5.md#4503-meter-report-command) + +The Scale value 0x07 MUST be used to indicate that the scale of the advertised meter reading is advertised through the Scale 2 field. + +Table 65, Meter Report v5::Scale encoding + +| | Meter Type | | | Scale | | | Value | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Electric meter | | | kWh | | | 0x00 | | | 1 | | | +| | | | kVAh | | | 0x01 | | | 2 | | | +| | | | W | | | 0x02 | | | 2 | | | +| | | | Pulse count | | | 0x03 | | | 2 | | | +| | | | V | | | 0x04 | | | 3 | | | +| | | | A | | | 0x05 | | | 3 | | | +| | | | Power Factor | | | 0x06 | | | 3 | | | +| | | | M.S.T | | | 0x07 | | | 4 | | | +| Gas meter | | | Cubic meters | | | 0x00 | | | 1 | | | +| | | | Cubic feet | | | 0x01 | | | 2 | | | +| | | | Reserved | | | 0x02 | | | - | | | +| | | | Pulse count | | | 0x03 | | | 2 | | | +| | | | Reserved | | | 0x04- 0x06 | | | - | | | +| | | | M.S.T | | | 0x07 | | | 4 | | | +| Water meter | | | Cubic meters | | | 0x00 | | | 1 | | | +| | | | Cubic feet | | | 0x01 | | | 1 | | | +| | | | US gallons | | | 0x02 | | | 1 | | | +| | | | Pulse count | | | 0x03 | | | 2 | | | +| | | | Reserved | | | 0x04-0x06 | | | - | | | +| | | | M.S.T | | | 0x07 | | | 4 | | | +| Heating meter | | | kWh | | | 0x00 | | | 5 | | | +| Cooling meter | | | kWh | | | 0x00 | | | 5 | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.51-meter-table-configuration-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.51-meter-table-configuration-command-class-version-1.md new file mode 100644 index 0000000..d642622 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.51-meter-table-configuration-command-class-version-1.md @@ -0,0 +1,37 @@ + +# 4.51 Meter Table Configuration Command Class, version 1 + +The Meter Table Configuration Command Class defines the Commands necessary to configure the fundamental properties of the meter. + +The Meter Table configuration commands are separated from the Meter Table monitoring commands in the Meter Table Monitor Command Class, allowing the classes to be optionally supported at different Z- Wave security levels. (E.g. Meter table monitoring commands could be supported in any device, while enabling a strict and certificate based security solution for the Meter Table Configuration Command [class). Refer to [14] for more details about Z-Wave security.](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +## 4.51.1 Meter Table Point Adm Number Set Command + +This command is used to set the Meter Point Administration Number in the metering device. The Meter Point Administration Number is used to identify the customer. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL CONFIG _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL TABLE POINT ADM NO SET _ _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Number of Meter Point Adm Number Characters | | | | | | | | | | | | | | | +| Meter Point Adm Number Character 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Meter Point Adm Number Character N | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Number of Meter Point Adm Number Characters (5 bits) + +Number of characters in the meter point administration number(1…32). + +Meter Point Adm Number Character (N bytes) + +The Meter Point Adm Number character fields hold the string identifying the customer. The character presentation uses standard ASCII codes (values 128-255 are ignored). diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.01-meter-table-point-adm-number-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.01-meter-table-point-adm-number-get-command.md new file mode 100644 index 0000000..fef5d16 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.01-meter-table-point-adm-number-get-command.md @@ -0,0 +1,19 @@ + +# 4.52.1 Meter Table Point Adm. Number Get Command + +This command is used to request the Meter Point Administration Number to identify customer. + +The Meter Table Adm. Number Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL TABLE POINT ADM NO GET _ _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.02-meter-table-point-adm-number-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.02-meter-table-point-adm-number-report-command.md new file mode 100644 index 0000000..b5f43b1 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.02-meter-table-point-adm-number-report-command.md @@ -0,0 +1,21 @@ + +# 4.52.2 Meter Table Point Adm. Number Report Command + +This command reports parameters used for identification of customer and metering device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL TABLE POINT ADM NO REPORT _ _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Number of Meter Point Adm. Number Characters | | | | | | | | | | | | | | | +| Meter Point Adm. Number Character 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Meter Point Adm. Number Character N | | | | | | | | | | | | | | | | | | | | | | | | + +[Refer to description of fields under the Meter Table Point Adm. Number Set Command (section 4.51.1).](../04.51-meter-table-configuration-command-class-version-1.md#4511-meter-table-point-adm-number-set-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.03-meter-table-id-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.03-meter-table-id-get-command.md new file mode 100644 index 0000000..675ec7c --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.03-meter-table-id-get-command.md @@ -0,0 +1,19 @@ + +# 4.52.3 Meter Table ID Get Command + +This command is used to request the parameters used for identification of customer and metering device. + +The Meter Table ID Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL TABLE ID GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.04-meter-table-id-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.04-meter-table-id-report-command.md new file mode 100644 index 0000000..dbaf199 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.04-meter-table-id-report-command.md @@ -0,0 +1,31 @@ + +# 4.52.4 Meter Table ID Report Command + +This command reports parameters used for identification of customer and metering device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL TABLE ID REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Number of Meter ID Characters | | | | | | | | | | | | | | | +| Meter ID Character 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Meter ID Character N | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Number of Meter ID Characters (5 bits) + +Number of characters defining the meter ID (1..32). + +Meter ID Character (N bytes) + +The Meter ID character fields hold the string identifying the individual metering device. The character presentation uses standard ASCII codes (values 128-255 are ignored). In addition one can use the Manufacturer Specific Command Class in conjunction as product identification. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.05-meter-table-capability-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.05-meter-table-capability-get-command.md new file mode 100644 index 0000000..ed85ce9 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.05-meter-table-capability-get-command.md @@ -0,0 +1,19 @@ + +# 4.52.5 Meter Table Capability Get Command + +This command is used to request the capabilities of a metering device. + +The Meter Table Capability Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL TABLE CAPABILITY GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.06-meter-table-capability-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.06-meter-table-capability-report-command.md new file mode 100644 index 0000000..804b953 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.06-meter-table-capability-report-command.md @@ -0,0 +1,145 @@ + +# 4.52.6 Meter Table Capability Report Command + +This command is used to advertise meter table capabilities. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Type | | | | | | Meter Type | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Pay Meter | | | | | | | | | | | | +| Dataset Supported 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset Supported 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset Supported 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset History Supported 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset History Supported 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset History Supported 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Data History Supported 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Data History Supported 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Data History Supported 3 | | | | | | | | | | | | | | | | | | | | | | | | + +Rate Type (2 bits) + +[Rate Type specifies the type of parameters in the report. This field MUST be encoded according to Table 58.](../04.47-meter-command-class-version-2.md#4475-meter-report-command) + +Meter Type (6 bits) + +Meter Type specifies the type of metering device the command originates. This field MUST be encoded [according to Table 66.](04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Table 66: Meter Table capability Report::Meter Types encoding + +| | Value | | | Meter Type | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Reserved | | | +| 0x01 | | | Single-E electric meter | | | +| 0x02 | | | Gas meter | | | +| 0x03 | | | Water meter | | | +| 0x04 | | | Twin-E electric meter | | | +| 0x05 | | | 3P Single Direct electric meter | | | +| 0x06 | | | 3P Single ECT electric meter | | | +| 0x07 | | | 1 Phase Direct Electricity Meter | | | +| 0x08 | | | Heating meter | | | +| 0x09 | | | Cooling meter | | | +| 0x0A | | | Combined Heating and Cooling Meter | | | +| 0x0B | | | Electric Sub-Meter | | | +| 0x0C-0x3F | | | Reserved | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. Pay Meter (4 bits) + +Pay Meter specifies the way settling of account is done. Refer to the table below with respect to defined payment meters. + +Table 67, Meter Table Capability Report::Pay Meter encoding + +| Value | | | Pay Meter | | +| --- | --- | --- | --- | --- | +| 0x00 | | Reserved | | | +| 0x01 | | Creditmeter | | | +| 0x02 | | Prepayment meter | | | +| 0x03 | | Prepayment meter with debt recovery | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Dataset Supported / Dataset History Supported (24 bits / 24 bits) + +Dataset Supported specifies which parameters, are available to be requested from the metering device. [Dataset Supported MUST be encoded according to Table 68.](04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Dataset History Supported specifies the type of data/values, which may be requested through the Meter [Table Historical data Get command (see 4.52.14) from the metering device. Dataset History Supported](04.52.14-meter-table-historical-data-get-command.md#45214-meter-table-historical-data-get-command) [MUST be encoded according to Table 68.](04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Table 68, Meter Table Capability Report::Meter Dataset encoding + +| Meter Type | Byte # | Bit # | Description | +| --- | --- | --- | --- | +| Single-E electric meter Twin-E electric meter 3P Single Direct electric meter 3P Single ECT electric meter 1 Phase Direct Electricity Meter | Byte 1 | Bit 0 | Total Primary Active Energy (kWh) Energy delivered to the unit before transformation. | +| | Byte 1 | Bit 1 | Total Primary Reactive Energy (kvarh) Energy delivered to the unit before transformation. | +| | Byte 1 | Bit 2 | Total Secondary Active Energy (kWh) Consumed energy after transformation. | +| | Byte 1 | Bit 3 | Total Secondary Reactive Energy (kvarh) Consumed energy after transformation. | +| | Byte 1 | Bit 4 | Instantaneous Primary Active Power (kW) Current power consumption. | +| | Byte 1 | Bit 5 | Instantaneous Primary Reactive Power (kvar) Current power consumption. | +| | Byte 1 | Bit 6 | Primary Active Maximum Demand (kW) All time maximum active power demand. | +| | Byte 1 | Bit 7 | Primary Reactive Maximum Demand (kvar) All time maximum reactive power demand. | + +| Meter Type | Byte # | Bit # | Description | +| --- | --- | --- | --- | +| | Byte 2 | Bit 0 | Cumulative Primary Active Maximum Demand (kW) Accumulated power over period. | +| | Byte 2 | Bit 1 | Cumulative Primary Reactive Maximum Demand (kvar) Accumulated power over period. | +| | Byte 2 | Bit 2 | Voltage Phase 1 (V) Voltage measured on phase 1. | +| | Byte 2 | Bit 3 | Voltage Phase 2 (V) Voltage measured on phase 2. | +| | Byte 2 | Bit 4 | Voltage Phase 3 (V) Voltage measured on phase 3. | +| | Byte 2 | Bit 5 | Ampere Phase 1 (A) Amperes measured on phase 1. | +| | Byte 2 | Bit 6 | Ampere Phase 2 (A) Amperes measured on phase 2. | +| | Byte 2 | Bit 7 | Ampere Phase 3 (A) Amperes measured on phase 3. | +| | Byte 3 | Bit 0 | Pulse Input (Pulse Count) Pulse count on pulse input port of meter. | +| | Byte 3 | Bit 1 | Current Transformation Ratio (ratio) Transformation ratio between primary and secondary energy. | +| | Byte 3 | Bit 2 | Power Factor (%) Power factor contains the ratio of real power to total power, and is expressed as a percentage (%). | +| | Byte 3 | Bit 3-7 | Reserved Value reserved for future expansion. | +| Gas meter Water meter | Byte 1 | Bit 0 | Accumulated Volume (m3) Total accumulated volume. | +| | Byte 1 | Bit 1 | Current Flow (l/h, m3/h) Current flow value. | +| | Byte 1 | Bit 2 | Current Pressure (kPa) Current pressure value. | +| | Byte 1 | Bit 3 | Peak Flow (l/h, m3/h) Peak flow demand recorded. | +| | Byte 1 | Bit 4 | Hour Counter (Hours) Hours in operation. | +| | Byte 1 | Bit 5 | Input A (m3/h, kW, m3, kWh, MWh, Pulse Count) Value of input port A on the meter. | + +| Meter Type | Byte # | Bit # | Description | +| --- | --- | --- | --- | +| | Byte 1 | Bit 6 | Input B (m3/h, kW, m3, kWh, MWh, Pulse Count) Value of input port B on the meter. | +| | Byte 1 Byte 2 Byte 3 | Bit 7 Bit 0-7 Bit 0-7 | Reserved Value reserved for future expansion. | +| Heating meter Cooling meter | Byte 1 | Bit 0 | Heat Energy (kWh, MWh, GJ, GCal) Total accumulated energy used for heating. | +| | Byte 1 | Bit 1 | Cooling Energy (kWh, MWh, GJ, GCal) Total accumulated energy used for cooling. | +| | Byte 1 | Bit 2 | Volume 1 (m3, ton) Volume counter 1 – forward flow. | +| | Byte 1 | Bit 3 | Volume2 (m3, ton) Volume counter 2 – return flow. | +| | Byte 1 | Bit 4 | Temperature 1 (Forward) (Co, oF) Forward temperature. | +| | Byte 1 | Bit 5 | Temperature 2 (Return) (Co, oF) Return temperature. | +| | Byte 1 | Bit 6 | Temperature 3 (Co, oF) Temperature sensor 3. | +| | Byte 1 | Bit 7 | Actual Flow (Volume 1) (l/h, m3/h) Current flow on volume 1. | +| | Byte 2 | Bit 0 | Actual Flow (Volume 2) (l/h, m3/h) Current flow on volume 2. | +| | Byte 2 | Bit 1 | Actual Power (kW, MW) Current power. | +| | Byte 2 | Bit 2 | Peak Flow (l/h, m3/h) Peak flow recorded. | +| | Byte 2 | Bit 3 | Peak Power (kW, MW) Peak power recorded. | +| | Byte 2 | Bit 4 | Input A (m3/h, kW, m3, kWh, MWh, Pulse Count) Value of input port A on the meter. | +| | Byte 2 | Bit 5 | Input B (m3/h, kW, m3, kWh, MWh, Pulse Count) Value of input port B on the meter. | +| | Byte 2 | Bit 6 | Hour Counter (Hours) Hours in operation. | +| | Byte 2 Byte 3 | Bit 7 Bit 0-7 | Reserved Value reserved for future expansion. | +| Electric Sub-Meter | Byte 1 | Bit 0 | Accumulated (kWh) | + +| Meter Type | Byte # | Bit # | Description | +| --- | --- | --- | --- | +| | Byte 1 | Bit 1 | Accumulated (kVAh) | +| | Byte 1 | Bit 2 | Instant (W) | +| | Byte 1 | Bit 3 | Accumulated (Pulse Count) | +| | Byte 1 | Bit 4 | Instant (V) | +| | Byte 1 | Bit 5 | Instant (A) | +| | Byte 1 | Bit 6 | Power Factor (%) | +| | Byte 1 Byte 2 Byte 3 | Bit 7 Bit 0-7 Bit 0-7 | Reserved | + +Data History Supported (24 bits) + +Data History Supported specifies number of possible entries in the buffer holding the historical values. Historical data cannot be retrieved when Data History Supported is equal to 0. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.07-meter-table-status-supported-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.07-meter-table-status-supported-get-command.md new file mode 100644 index 0000000..8e5092c --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.07-meter-table-status-supported-get-command.md @@ -0,0 +1,19 @@ + +# 4.52.7 Meter Table Status Supported Get Command + +This command is used to request the supported operating status event parameters and logging depth of the metering device. + +The Meter Table Status Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL STATUS SUPPORTED GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.08-meter-table-status-supported-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.08-meter-table-status-supported-report-command.md new file mode 100644 index 0000000..5c5f50a --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.08-meter-table-status-supported-report-command.md @@ -0,0 +1,59 @@ + +# 4.52.8 Meter Table Status Supported Report Command + +This command is used to report the supported operation status and logging depth of these in the meter. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL STATUS SUPPORTED REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Supported Operating Status 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Supported Operating Status 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Supported Operating Status 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Status Event Log Depth | | | | | | | | | | | | | | | | | | | | | | | | + +Supported Operating Status (24 bits) + +This command parameter is defined in a bitmap format and holds values and combinations of the meters operating status. If no “Operating Status Event” is supported by the application all fields of this parameter MUST be set to ‘0’ as an indication of the meter is at “Normal/Idle” operating status. Supported Operating Status supports the following combinations of operating status: + +Table 69, Meter Table Status Supported Report::Supported Operating Status encoding + +| Operating Status | Bit Map | | Operating | | Description | +| --- | --- | --- | --- | --- | --- | +| | | | Status Event | | | +| | | | Identifier | | | +| 1 | Bit 0 | 0x00 | | | Disconnected The meter has been disconnected. | +| 1 | Bit 1 | 0x01 | | | Leak detection A leak has been detected. | +| 1 | Bit 2 | 0x02 | | | Power failure All phases / meter without power. | +| 1 | Bit 3 | 0x03 | | | Power failure – Phase 1 Power failure on phase 1 detected. | +| 1 | Bit 4 | 0x04 | | | Power failure – Phase 2 Power failure on phase 2 detected. | +| 1 | Bit 5 | 0x05 | | | Power failure – Phase 3 Power failure on phase 3 detected. | +| 1 | Bit 6 | 0x06 | | | Voltage Quality Voltage quality not within limits. | +| 1 | Bit 7 | 0x07 | | | Tamper detection Tamper switch has been activated. | +| 2 | Bit 0 | 0x08 | | | Magnetic tampering Magnetic tempering detected. | +| 2 | Bit 1 | 0x09 | | | Meter Clock Set The clock has been set in the meter. | +| 2 | Bit 2 | 0x0A | | | Meter Clock Adjusted The clock has been adjusted in the meter. | + +| Operating Status | Bit Map | | Operating | | Description | +| --- | --- | --- | --- | --- | --- | +| | | | Status Event | | | +| | | | Identifier | | | +| 2 | Bit 3 | 0x0B | | | Out of Credit The meter is out of credit. | +| 2 | Bit 4 | 0x0C | | | Emergency credit The meter is running on emergency credit. | +| 2 | Bit 5 | 0x0D | | | Transformer Ratio Changed “Current transformation ratio” in meter changed. | +| 2 | Bit 6 | 0x0E | | | Temperature Sensor 1 – Out of range Temperature Sensor 1 outside specifications. | +| 2 | Bit 7 | 0x0F | | | Temperature Sensor 2 – Out of range Temperature Sensor 2 outside specifications. | +| 3 | Bit 0 | 0x10 | | | Temperature Sensor 3 – Out of range Temperature Sensor 3 outside specifications. | +| 3 | Bit 1 | 0x11 | | | Burst Detection Heat Burst detected in the heating network causing potential flooding. | +| 3 | Bit 2 | 0x12 | | | Error – Check Meter Any other error condition not mentioned above. | +| 3 | Bit 4 – 7 | 0x13 – 0x1F | | | Reserved Values reserved for future expansion. | + +Status Event Log Depth (8 bits) + +The status event log depth indicates the supported depth of the event log. If the meter only supports reporting the current status the status event log depth MUST be set to 0. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.09-meter-table-status-depth-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.09-meter-table-status-depth-get-command.md new file mode 100644 index 0000000..5a7f856 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.09-meter-table-status-depth-get-command.md @@ -0,0 +1,24 @@ + +# 4.52.9 Meter Table Status Depth Get Command + +This command is used to request the current operating status of the metering device or to request a number of the latest status event from the logs. + +The Meter Table Status Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL STATUS DEPTH GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Status Event Log Depth | | | | | | | | | | | | | | | | | | | | | | | | + +Status Event Log Depth (8 bits) + +The status event log depth indicates the number of latest recorded events that should be returned in the corresponding report. If the log depth is set to 0 the meter will only return the current status; if the log depth is set to 0xFF the meter SHOULD return the entire status log. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.10-meter-table-status-date-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.10-meter-table-status-date-get-command.md new file mode 100644 index 0000000..83b2a07 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.10-meter-table-status-date-get-command.md @@ -0,0 +1,62 @@ + +# 4.52.10 Meter Table Status Date Get Command + +This command is used to request a number of status events recorded in a certain time interval. + +The Meter Table Status Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +If the meter does not support a status event log history it MUST return the current state of the meter (see [Meter Table Status Report Command).](04.52.11-meter-table-status-report-command.md#45211-meter-table-status-report-command) + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL STATUS DATE GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Maximum Reports | | | | | | | | | | | | | | | | | | | | | | | | +| Start - Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Start - Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Start - Month | | | | | | | | | | | | | | | | | | | | | | | | +| Start - Day | | | | | | | | | | | | | | | | | | | | | | | | +| Start - Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Start - Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Start - Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop - Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Stop - Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Stop - Month | | | | | | | | | | | | | | | | | | | | | | | | +| Stop - Day | | | | | | | | | | | | | | | | | | | | | | | | +| Stop - Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop - Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop - Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | + +Maximum Reports (8 bits) + +The maximum reports parameter is used to indicate the maximum number of reports to return based on the get. Reports are always returned with the most recently recorded log entry first. If set to 0x00 the meter will return all reports based on the request. Start/Stop - Year (16 bits) + +Specify the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. + +Start/Stop - Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December). + +Start/Stop - Day (8 bits) + +Specify the day of the month between 01 and 31. + +Start/Stop - Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00-23) in local time. + +Start/Stop - Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00-59) in local time. + +Start/Stop - Second Local Time (8 bits) + +Specify the number of complete seconds since the start of the minute (00-59) in local time. The value 60 used to keep UTC from wandering away is not supported. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.11-meter-table-status-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.11-meter-table-status-report-command.md new file mode 100644 index 0000000..adfc0d4 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.11-meter-table-status-report-command.md @@ -0,0 +1,74 @@ + +# 4.52.11 Meter Table Status Report Command + +This command is used to advertise the current status of the meter. + +| | 7 | | | 6 | | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL STATUS REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to follow | | | | | | | | | | | | | | | | | | | | | | | | | +| Current Operating Status 1 | | | | | | | | | | | | | | | | | | | | | | | | | +| Current Operating Status 2 | | | | | | | | | | | | | | | | | | | | | | | | | +| Current Operating Status 3 | | | | | | | | | | | | | | | | | | | | | | | | | +| Event 1 - Type | | | | | Reserved | | | | | Event 1 - Operating Status Event ID | | | | | | | | | | | | | | | +| Event 1 - Year 1 | | | | | | | | | | | | | | | | | | | | | | | | | +| Event 1 - Year 2 | | | | | | | | | | | | | | | | | | | | | | | | | +| Event 1 - Month | | | | | | | | | | | | | | | | | | | | | | | | | +| Event 1 - Day | | | | | | | | | | | | | | | | | | | | | | | | | +| Event 1 - Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | | +| Event 1 - Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | | +| Event 1 - Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | | +| Event N -Type | | | | | Reserved | | | | | Event N - Operating Status Event ID | | | | | | | | | | | | | | | +| Event N - Year 1 | | | | | | | | | | | | | | | | | | | | | | | | | +| Event N - Year 2 | | | | | | | | | | | | | | | | | | | | | | | | | +| Event N - Month | | | | | | | | | | | | | | | | | | | | | | | | | +| Event N - Day | | | | | | | | | | | | | | | | | | | | | | | | | +| Event N - Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | | +| Event N -Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | | +| Event N - Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | | + +Reports to follow (8 bits) + +This value indicates how many report frames there are left, the value 0xFF means that the number of reports have not been calculated yet or that there is more than 255 reports to follow. Current Operating Status (24 bits) + +This command parameter is defined in a bitmap format and holds values and combinations of the meters operating status. If no “Operating Status Event” has been registered for the period requested by the Meter Table Status Date Get Command, all fields of this parameter MUST be set to ‘0’ AND no “Event” parameters are to be included in the Meter Table Status Report Command i.e. the command parameters [ends after “Current Operating Status” . Refer to “Supported Operating Status” in section 4.52.8 for](04.52.08-meter-table-status-supported-report-command.md#4528-meter-table-status-supported-report-command) details. + +Event – Type (1 bit) + +The parameter reports type of event number n in the event log. The event type MAY be 0 (the meter entered the state described by the operating event status ID at the time reported), or 1 (the meter left the state described by the operating event status ID). + +Event – Operating Status Event ID (5 bits) + +The operating status event identifier of event number n in the event log. The identifiers available are [given in the table in section 4.52.8.](04.52.08-meter-table-status-supported-report-command.md#4528-meter-table-status-supported-report-command) + +Event - Year (16 bits) + +Specify the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. + +Event - Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December). + +Event - Day (8 bits) + +Specify the day of the month between 01 and 31. + +Event - Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00-23) in local time. + +Event - Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00-59) in local time. + +Event - Second Local Time (8 bits) + +Specify the number of complete seconds since the start of the minute (00-59) in local time. The value 60 used to keep UTC from wandering away is not supported. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.12-meter-table-current-data-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.12-meter-table-current-data-get-command.md new file mode 100644 index 0000000..1b13316 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.12-meter-table-current-data-get-command.md @@ -0,0 +1,26 @@ + +# 4.52.12 Meter Table Current Data Get Command + +This command is used to request a number of time stamped values (current) in physical units according to the dataset mask. + +The Meter Table Current Data Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL CURRENT DATA GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset Requested 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset Requested 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset Requested 3 | | | | | | | | | | | | | | | | | | | | | | | | + +Dataset Requested (24 bits) + +The Dataset Requested is used to indicate which parameters are requested from the meter. This field [MUST be encoded according to Table 68.](04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.13-meter-table-current-data-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.13-meter-table-current-data-report-command.md new file mode 100644 index 0000000..2614446 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.13-meter-table-current-data-report-command.md @@ -0,0 +1,135 @@ + +# 4.52.13 Meter Table Current Data Report Command + +This command is is used to report a number of time stamped values. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL CURRENT DATA REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | Rate Type | | | | | | +| Dataset 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Month | | | | | | | | | | | | | | | | | | | | | | | | +| Day | | | | | | | | | | | | | | | | | | | | | | | | +| Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| | Current Meter Precision 1 | | | | | | | | | Current Meter Scale 1 | | | | | | | | | | | | | | +| | Current Value 1,1 | | | | | | | | | | | | | | | | | | | | | | | +| | Current Value 1,2 | | | | | | | | | | | | | | | | | | | | | | | +| | Current Value 1,3 | | | | | | | | | | | | | | | | | | | | | | | +| | Current Value 1,4 | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Current Meter Precision N | | | | | | | | | Current Meter Scale N | | | | | | | | | | | | | | +| | Current Value N,1 | | | | | | | | | | | | | | | | | | | | | | | +| | Current Value N,2 | | | | | | | | | | | | | | | | | | | | | | | +| | Current Value N,3 | | | | | | | | | | | | | | | | | | | | | | | +| | Current Value N,4 | | | | | | | | | | | | | | | | | | | | | | | + +Reports to follow (8 bits) + +This value indicates how many report frames there are left, the value 0xFF means that the number of reports have not been calculated yet or that there is more than 255 reports to follow. Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Rate Type (2 bits) + +[Rate Type specifies the type of parameters in the report. This field MUST be encoded according to Table 58.](../04.47-meter-command-class-version-2.md#4475-meter-report-command) + +Dataset (24 bits) + +The dataset parameter indicates which data is included in the report. This field MUST be encoded [according to Table 68.](04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Year (16 bits) + +Specify the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. A year equal to 0x0000 indicates that an accumulated value is not determined yet. + +Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December). + +Day (8 bits) + +Specify the day of the month between 01 and 31. + +Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00-23) in local time. + +Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00-59) in local time. + +Second Local Time (8 bits) + +Specify the number of complete seconds since the start of the minute (00-59) in local time. The value 60 used to keep UTC from wandering away is not supported. + +Meter Precision (3 bits) + +The Meter Precision field describes what the precision of the value is. The number indicates the number of decimals. The decimal value 1025 with precision 2 is therefore equal to 10.25. Meter Scale (5 bits) + +The Meter Scale used to indicate the scale (unit) of the reported parameter. + +Table 70, Meter Table Current Data Report::Meter Scale encoding + +| | Meter Type | | | Meter Scale | | | Value | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Electric meter | | | kWh | | | 0x00 | | | +| | | | kVARh | | | 0x01 | | | +| | | | % | | | 0x02 | | | +| | | | Pulse count | | | 0x03 | | | +| | | | kVAR | | | 0x04 | | | +| | | | Voltage (V) | | | 0x05 | | | +| | | | Amperes (A) | | | 0x06 | | | +| | | | kW | | | 0x07 | | | +| | | | Ratio | | | 0x08 | | | +| | | | Reserved | | | 0x09- 0x1F | | | +| Gas and water meter | | | Cubic meter | | | 0x00 | | | +| | | | Cubic feet | | | 0x01 | | | +| | | | US gallon | | | 0x02 | | | +| | | | Pulse count | | | 0x03 | | | +| | | | IMP gallon | | | 0x04 | | | +| | | | Liter | | | 0x05 | | | +| | | | kPa | | | 0x06 | | | +| | | | Centum cubic feet | | | 0x07 | | | +| | | | Cubic meter per hour | | | 0x08 | | | +| | | | Liter per hour | | | 0x09 | | | +| | | | kWh | | | 0x0A | | | +| | | | MWh | | | 0x0B | | | +| | | | KW | | | 0x0C | | | +| | | | Hours | | | 0x0D | | | +| | | | Reserved | | | 0x0E-0x1F | | | +| Heating and Cooling Meter | | | Cubic meter (m3) | | | 0x00 | | | +| | | | Metric Ton (tonne) (t) | | | 0x01 | | | +| | | | Cubic meter per hour (m3/h) | | | 0x02 | | | +| | | | Liter per hour (l/h) | | | 0x03 | | | +| | | | kW | | | 0x04 | | | +| | | | MW | | | 0x05 | | | + +| | Meter Type | | | Meter Scale | | | Value | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| | | | kWh | | | 0x06 | | | +| | | | MWh | | | 0x07 | | | +| | | | Giga Joule (GJ) | | | 0x08 | | | +| | | | Giga Calorie (Gcal) | | | 0x09 | | | +| | | | Celsius (Co) | | | 0x0A | | | +| | | | Fahrenheit (oF) | | | 0x0B | | | +| | | | Hours | | | 0x0C | | | +| | | | Reserved | | | 0x0D-0x1F | | | + +Current Value (32 bits) + +The Current Value is a 32 bit signed field defined by dataset requested field. The first byte (Value 1) is [the most significant byte. Table 10 shows signed decimal values together with their hexadecimal](../../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) equivalents. + +NOTICE: The device receiving the Meter Table Current Data Report MUST show the value even though the scale is not supported. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.14-meter-table-historical-data-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.14-meter-table-historical-data-get-command.md new file mode 100644 index 0000000..a409418 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.14-meter-table-historical-data-get-command.md @@ -0,0 +1,69 @@ + +# 4.52.14 Meter Table Historical Data Get Command + +This command is used to request a number of time stamped values (historical) in physical units according to rate type, dataset mask and time interval. + +The Meter Table Historical Data Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL HISTORICAL DATA GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Maximum Reports | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Dataset Requested 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Dataset Requested 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Dataset Requested 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Start Month | | | | | | | | | | | | | | | | | | | | | | | | +| Start Day | | | | | | | | | | | | | | | | | | | | | | | | +| Start Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Start Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Start Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Month | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Day | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | + +Maximum Reports (8 bits) + +The maximum reports parameter is used to indicate the maximum number of reports to return based on the get. Reports are always returned with the most recently recorded value first. If set to 0x00 the meter will return all reports based on the request. + +Dataset History (24 bits) + +The Historical Dataset Requested parameter is use to indicate which parameters are requested from the [meter. This field MUST be encoded according to Table 68.](04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Start/Stop Year (16 bits) + +Specify the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. + +Start/Stop Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December). + +Start/Stop Day (8 bits) + +Specify the day of the month between 01 and 31. + +Start/Stop Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00-23) in local time. + +Start/Stop Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00-59) in local time. + +Start/Stop Second Local Time (8 bits) + +Specify the number of complete seconds since the start of the minute (00-59) in local time. The value 60 used to keep UTC from wandering away is not supported. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.15-meter-table-historical-data-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.15-meter-table-historical-data-report-command.md new file mode 100644 index 0000000..04d3b40 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/04.52.15-meter-table-historical-data-report-command.md @@ -0,0 +1,88 @@ + +# 4.52.15 Meter Table Historical Data Report Command + +This command is used to report a number of time stamped values. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL HISTORICAL DATA REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | Rate Type | | | | | | +| Dataset 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Month | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Day | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Precision 1 | | | | | | | | | Historical Scale 1 | | | | | | | | | | | | | | +| | Historical Value 1,1 | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value 1,2 | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value 1,3 | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value 1,4 | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Precision N | | | | | | | | | Historical Scale N | | | | | | | | | | | | | | +| | Historical Value N,1 | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value N,2 | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value N,3 | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value N,4 | | | | | | | | | | | | | | | | | | | | | | | + +Reports to Follow (8 bits) + +This value indicates how many report frames there are left, the value 0xFF means that the number of reports have not been calculated yet or that there is more than 255 reports to follow. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. Rate Type (2 bits) + +[Rate Type specifies the type of parameters in the report. This field MUST be encoded according to Table 58.](../04.47-meter-command-class-version-2.md#4475-meter-report-command) + +Dataset (24 bits) + +This command parameter is defined in a bitmap format and holds values and combinations of the meters dataset. If no historical data has been registered for the period requested by the Meter Table Historical Data Get Command, all fields of this parameter MUST be set to ‘0’ AND no “Historical” parameters are to be included in the Meter Table Historical Data Report Command i.e. the command parameters ends after [“Dataset”. This field MUST be encoded according to Table 68.](04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Historical Year (16 bits) + +Specify for the dataset the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. + +Historical Month (8 bits) + +Specify for the dataset the month of the year between 01 (January) and 12 (December). A year equal to 0x0000 indicates that an accumulated value is not determined yet. + +Historical Day (8 bits) + +Specify for the dataset the day of the month between 01 and 31. + +Historical Hour Local Time (8 bits) + +Specify for the dataset the number of complete hours that have passed since midnight (00-23) in local time. + +Historical Minute Local Time (8 bits) + +Specify for the dataset the number of complete minutes that have passed since the start of the hour (00- 59) in local time. + +Historical Second Local Time (8 bits) + +Specify for the dataset the number of complete seconds since the start of the minute (00-59) in local time. The value 60 used to keep UTC from wandering away is not supported. + +Historical Precision (3 bits) + +The Historical Precision field describes what the precision of the value is. The number indicates the number of decimals. The decimal value 1025 with precision 2 is therefore equal to 10.25. + +Historical Scale (5 bits) + +The Historical Scale used to indicate the scale (unit) of the reported parameter. The Historical Scale parameter is of the variable type Meter Scale [; refer to Section 4.52.13 for a definition of the variable.](04.52.13-meter-table-current-data-report-command.md#45213-meter-table-current-data-report-command) Historical Value + +The Historical Value is a 32 bit signed field defined by dataset requested field. The first byte (Value 1) is [the most significant byte. Table 10 shows signed decimal values together with their hexadecimal](../../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) equivalents. + +NOTICE: The device receiving the Meter Table Historical Data Report MUST always show the value even though the Scale is not supported. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/index.md b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/index.md new file mode 100644 index 0000000..5e8704d --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.52-meter-table-monitor-command-class-version-1/index.md @@ -0,0 +1,28 @@ + +# 4.52 Meter Table Monitor Command Class, version 1 + +The Meter Table Monitor Command Class defines the Commands necessary to read historical and accumulated values in physical units from a water meter or other metering device (gas, electric etc.) and thereby enabling automatic meter reading capabilities + +## Contents + +- [4.52.1 Meter Table Point Adm. Number Get Command](04.52.01-meter-table-point-adm-number-get-command.md) +- [4.52.2 Meter Table Point Adm. Number Report Command](04.52.02-meter-table-point-adm-number-report-command.md) +- [4.52.3 Meter Table ID Get Command](04.52.03-meter-table-id-get-command.md) +- [4.52.4 Meter Table ID Report Command](04.52.04-meter-table-id-report-command.md) +- [4.52.5 Meter Table Capability Get Command](04.52.05-meter-table-capability-get-command.md) +- [4.52.6 Meter Table Capability Report Command](04.52.06-meter-table-capability-report-command.md) +- [4.52.7 Meter Table Status Supported Get Command](04.52.07-meter-table-status-supported-get-command.md) +- [4.52.8 Meter Table Status Supported Report Command](04.52.08-meter-table-status-supported-report-command.md) +- [4.52.9 Meter Table Status Depth Get Command](04.52.09-meter-table-status-depth-get-command.md) +- [4.52.10 Meter Table Status Date Get Command](04.52.10-meter-table-status-date-get-command.md) +- [4.52.11 Meter Table Status Report Command](04.52.11-meter-table-status-report-command.md) +- [4.52.12 Meter Table Current Data Get Command](04.52.12-meter-table-current-data-get-command.md) +- [4.52.13 Meter Table Current Data Report Command](04.52.13-meter-table-current-data-report-command.md) +- [4.52.14 Meter Table Historical Data Get Command](04.52.14-meter-table-historical-data-get-command.md) +- [4.52.15 Meter Table Historical Data Report Command](04.52.15-meter-table-historical-data-report-command.md) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.01-meter-table-point-adm-number-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.01-meter-table-point-adm-number-get-command.md new file mode 100644 index 0000000..edaf954 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.01-meter-table-point-adm-number-get-command.md @@ -0,0 +1,19 @@ + +# 4.53.1 Meter Table Point Adm. Number Get Command + +This command is used to request the Meter Point Administration Number to identify customer. + +The Meter Table Point Adm. Number Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL TABLE POINT ADM NO GET _ _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.02-meter-table-point-adm-number-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.02-meter-table-point-adm-number-report-command.md new file mode 100644 index 0000000..0f16d5f --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.02-meter-table-point-adm-number-report-command.md @@ -0,0 +1,23 @@ + +# 4.53.2 Meter Table Point Adm. Number Report Command + +This command reports parameters used for identification of customer and metering device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL TABLE POINT ADM NO REPORT _ _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Number of Meter Point Adm. Number Characters | | | | | | | | | | | | | | | +| Meter Point Adm. Number Character 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Meter Point Adm. Number Character N | | | | | | | | | | | | | | | | | | | | | | | | + +Refer to description of fields under the Meter Table Point Adm. Number Set Command in Meter Table Configuration Command Class, version 1. + +If Meter Table Point Adm, Number is not Set using the Meter Table Point Adm, Number Set Command in Meter Table Configuration Command Class, version 1 the Reported Number of Meter Point Adm, Number must be 0x00 and no Meter Table Point Adm, Numbers must be reported. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.03-meter-table-id-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.03-meter-table-id-get-command.md new file mode 100644 index 0000000..6843290 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.03-meter-table-id-get-command.md @@ -0,0 +1,19 @@ + +# 4.53.3 Meter Table ID Get Command + +This command is used to request the parameters used for identification of customer and metering device. + +The Meter Table ID Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL TABLE ID GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.04-meter-table-id-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.04-meter-table-id-report-command.md new file mode 100644 index 0000000..d4bb7d4 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.04-meter-table-id-report-command.md @@ -0,0 +1,33 @@ + +# 4.53.4 Meter Table ID Report Command + +This command reports parameters used for identification of customer and metering device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL TABLE ID REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Number of Meter ID Characters | | | | | | | | | | | | | | | +| Meter ID Character 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Meter ID Character N | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Number of Meter ID Characters (5 bits) + +Number of characters defining the meter ID (1..32). + +Meter ID Character (N bytes) + +The Meter ID character fields hold the string identifying the individual metering device. The character presentation uses standard ASCII codes (values 128-255 are ignored). In addition one can use the Manufacturer Specific Command Class in conjunction as product identification. + +Note: If the Meter Table ID is not used Number of Meter ID Characters must be reported as 0x00 and no Meter ID Characters must be reported. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.05-meter-table-capability-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.05-meter-table-capability-get-command.md new file mode 100644 index 0000000..358b1b3 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.05-meter-table-capability-get-command.md @@ -0,0 +1,19 @@ + +# 4.53.5 Meter Table Capability Get Command + +This command is used to request the capabilities of a metering device. + +The Meter Table Capability Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL TABLE CAPABILITY GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.06-meter-table-capability-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.06-meter-table-capability-report-command.md new file mode 100644 index 0000000..e889791 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.06-meter-table-capability-report-command.md @@ -0,0 +1,60 @@ + +# 4.53.6 Meter Table Capability Report Command + +This command is used to advertise meter table capabilities. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Type | | | | | | Meter Type | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Pay Meter | | | | | | | | | | | | +| Dataset Supported 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset Supported 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset Supported 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset History Supported 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset History Supported 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset History Supported 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Data History Supported 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Data History Supported 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Data History Supported 3 | | | | | | | | | | | | | | | | | | | | | | | | + +Rate Type (2 bits) + +[Rate Type specifies the type of parameters in the report. This field MUST be encoded according to Table 58.](../04.47-meter-command-class-version-2.md#4475-meter-report-command) + +If the Meter Type is Submeter the Rate Type must be Import to indicate consumption. Meter Type (6 bits) + +Meter Type specifies the type of metering device the command originates. This field MUST be encoded [according to Table 66.](../04.52-meter-table-monitor-command-class-version-1/04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Pay Meter (4 bits) + +Pay Meter specifies the way settling of account is done. + +| | Value | | | Pay Meter | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Reserved | | | +| 0x01 | | | Creditmeter | | | +| 0x02 | | | Prepayment meter | | | +| 0x03 | | | Prepayment meter with debt recovery | | | +| 0x04-0x07 | | | Reserved | | | + +Dataset Supported / Dataset History Supported (24 bits / 24 bits) + +Dataset Supported specifies which parameters, are available to be requested from the metering device. [Dataset Supported MUST be encoded according to Table 68..](../04.52-meter-table-monitor-command-class-version-1/04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Dataset History Supported specifies the type of data/values, which may be requested through the Meter [Table Historical data Get command (see 4.53.14) from the metering device. Dataset History Supported](04.53.14-meter-table-historical-data-get-command.md#45314-meter-table-historical-data-get-command) [MUST be encoded according to Table 68.](../04.52-meter-table-monitor-command-class-version-1/04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Data History Supported (24 bits) + +Data History Supported specifies number of possible entries in the buffer holding the historical values. Historical data cannot be retrieved when Data History Supported is equal to 0. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.07-meter-table-status-supported-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.07-meter-table-status-supported-get-command.md new file mode 100644 index 0000000..cac7b0f --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.07-meter-table-status-supported-get-command.md @@ -0,0 +1,19 @@ + +# 4.53.7 Meter Table Status Supported Get Command + +This command is used to request the supported operating status event parameters and logging depth of the metering device. + +The Meter Table Status Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL STATUS SUPPORTED GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.08-meter-table-status-supported-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.08-meter-table-status-supported-report-command.md new file mode 100644 index 0000000..4922612 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.08-meter-table-status-supported-report-command.md @@ -0,0 +1,27 @@ + +# 4.53.8 Meter Table Status Supported Report Command + +This command is used to report the supported operation status’ and logging depth of these in the meter. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL STATUS SUPPORTED REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Supported Operating Status 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Supported Operating Status 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Supported Operating Status 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Status Event Log Depth | | | | | | | | | | | | | | | | | | | | | | | | + +Supported Operating Status (1–4 Bytes) + +This command parameter is defined in a bitmap format and holds values and combinations of the meters operating status. If no “Operating Status Event” is supported by the application all fields of this parameter must be set to ‘0’ as an indication of the meter is at “Normal/Idle” operating status. Supported Operating Status supports the following combinations of operating status: + +Status Event Log Depth (8 bits) + +The status event log depth indicates the supported depth of the event log. If the meter only supports reporting the current status the status event log depth must be set to 0. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.09-meter-table-status-depth-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.09-meter-table-status-depth-get-command.md new file mode 100644 index 0000000..1512bf8 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.09-meter-table-status-depth-get-command.md @@ -0,0 +1,24 @@ + +# 4.53.9 Meter Table Status Depth Get Command + +This command is used to request the current operating status of the metering device or to request a number of the latest status event from the logs. + +The Meter Table Status Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL STATUS DEPTH GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Status Event Log Depth | | | | | | | | | | | | | | | | | | | | | | | | + +Status Event Log Depth (8 bits) + +The status event log depth indicates the number of latest recorded events that should be returned in the corresponding report. If the log depth is set to 0 the meter will only return the current status; if the log depth is set to 0xFF the meter should return the entire status log. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.10-meter-table-status-date-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.10-meter-table-status-date-get-command.md new file mode 100644 index 0000000..95b8e96 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.10-meter-table-status-date-get-command.md @@ -0,0 +1,62 @@ + +# 4.53.10 Meter Table Status Date Get Command + +This command is used to request a number of status events recorded in a certain time interval. + +The Meter Table Status Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +If the meter does not support a status event log history it must return the current state of the meter (see [section 4.53.11)](04.53.11-meter-table-status-report-command.md#45311-meter-table-status-report-command) + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL STATUS DATE GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Maximum Reports | | | | | | | | | | | | | | | | | | | | | | | | +| Start - Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Start - Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Start - Month | | | | | | | | | | | | | | | | | | | | | | | | +| Start - Day | | | | | | | | | | | | | | | | | | | | | | | | +| Start - Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Start - Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Start - Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop - Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Stop - Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Stop - Month | | | | | | | | | | | | | | | | | | | | | | | | +| Stop - Day | | | | | | | | | | | | | | | | | | | | | | | | +| Stop - Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop - Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop - Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | + +Maximum Reports (8 bits) + +The maximum reports parameter is used to indicate the maximum number of reports to return based on the get. Reports are always returned with the most recently recorded log entry first. If set to 0x00 the meter will return all reports based on the request. + +Start / Stop - Year (16 bits) + +Specify the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. Start / Stop - Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December). + +Start / Stop - Day (8 bits) + +Specify the day of the month between 01 and 31. + +Start / Stop - Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00-23) in local time. + +Start / Stop - Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00-59) in local time. + +Start / Stop - Second Local Time (8 bits) + +Specify the number of complete seconds since the start of the minute (00-59) in local time. The value 60 used to keep UTC from wandering away is not supported. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.11-meter-table-status-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.11-meter-table-status-report-command.md new file mode 100644 index 0000000..fe218fa --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.11-meter-table-status-report-command.md @@ -0,0 +1,78 @@ + +# 4.53.11 Meter Table Status Report Command + +This command is used to advertise the current status of the meter. + +| | 7 | | | 6 | | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL STATUS REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to follow | | | | | | | | | | | | | | | | | | | | | | | | | +| Current Operating Status 1 | | | | | | | | | | | | | | | | | | | | | | | | | +| Current Operating Status 2 | | | | | | | | | | | | | | | | | | | | | | | | | +| Current Operating Status 3 | | | | | | | | | | | | | | | | | | | | | | | | | +| | Event 1 | | | | Reserved | | | | | Event 1 - Operating Status Event ID | | | | | | | | | | | | | | | +| | - Type | | | | | | | | | | | | | | | | | | | | | | | | +| | Event 1 - Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| | Event 1 - Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| | Event 1 - Month | | | | | | | | | | | | | | | | | | | | | | | | +| | Event 1 - Day | | | | | | | | | | | | | | | | | | | | | | | | +| | Event 1 - Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| | Event 1 - Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| | Event 1 - Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | | +| | Event n | | | | Reserved | | | | | Event n - Operating Status Event ID | | | | | | | | | | | | | | | +| | -Type | | | | | | | | | | | | | | | | | | | | | | | | +| | Event n - Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| | Event n - Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| | Event n - Month | | | | | | | | | | | | | | | | | | | | | | | | +| | Event n - Day | | | | | | | | | | | | | | | | | | | | | | | | +| | Event n - Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| | Event n -Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| | Event n - Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | + +Reports to follow (8 bits) + +This value indicates how many report frames there are left, the value 0xFF means that the number of reports have not been calculated yet or that there is more than 255 reports to follow. + +Current Operating Status (24 bits) + +This command parameter is defined in a bitmap format and holds values and combinations of the meters operating status. If no “Operating Status Event” has been registered for the period requested by the Meter Table Status Date Get Command, all fields of this parameter must be set to ‘0’ AND no “Event” parameters are to be included in the Meter Table Status Report Command i.e. the command parameters [ends after “Current Operating Status” . Refer to “Supported Operating Status” in section 4.52.8 for](../04.52-meter-table-monitor-command-class-version-1/04.52.08-meter-table-status-supported-report-command.md#4528-meter-table-status-supported-report-command) details. + +Event n – Type (1 bit) + +The parameter reports type of event number n in the event log. The event type MAY be 0 (the meter entered the state described by the operating event status ID at the time reported), or 1 (the meter left the state described by the operating event status ID). + +Event – Operating Status Event ID + +The operating status event identifier of event number n in the event log. The identifiers available are [given in the table in section 4.52.8.](../04.52-meter-table-monitor-command-class-version-1/04.52.08-meter-table-status-supported-report-command.md#4528-meter-table-status-supported-report-command) + +Event - Year (16 bits) + +Specify the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. + +Event - Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December). + +Event - Day (8 bits) + +Specify the day of the month between 01 and 31. + +Event - Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00-23) in local time. + +Event - Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00-59) in local time. + +Event - Second Local Time (8 bits) + +Specify the number of complete seconds since the start of the minute (00-59) in local time. The value 60 used to keep UTC from wandering away is not supported. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.12-meter-table-current-data-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.12-meter-table-current-data-get-command.md new file mode 100644 index 0000000..7faa2ce --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.12-meter-table-current-data-get-command.md @@ -0,0 +1,26 @@ + +# 4.53.12 Meter Table Current Data Get Command + +This command is used to request a number of time stamped values (current) in physical units according to the dataset mask. + +The Meter Table Current Data Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL CURRENT DATA GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset Requested 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset Requested 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset Requested 3 | | | | | | | | | | | | | | | | | | | | | | | | + +Dataset Requested (24 bits) + +The Dataset Requested is used to indicate which parameters are requested from the meter. This field [MUST be encoded according to Table 68.](../04.52-meter-table-monitor-command-class-version-1/04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.13-meter-table-current-data-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.13-meter-table-current-data-report-command.md new file mode 100644 index 0000000..acdce99 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.13-meter-table-current-data-report-command.md @@ -0,0 +1,96 @@ + +# 4.53.13 Meter Table Current Data Report Command + +This command is used to report a number of time stamped values. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL CURRENT DATA REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| Operating Status Indication | | | | Reserved | | | | | | | | | | | | | | Rate Type | | | | | | +| Dataset 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Month | | | | | | | | | | | | | | | | | | | | | | | | +| Day | | | | | | | | | | | | | | | | | | | | | | | | +| Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| | Current Meter Precision 1 | | | | | | | | | Current Meter Scale 1 | | | | | | | | | | | | | | +| | Current Value 1,1 | | | | | | | | | | | | | | | | | | | | | | | +| | Current Value 1,2 | | | | | | | | | | | | | | | | | | | | | | | +| | Current Value 1,3 | | | | | | | | | | | | | | | | | | | | | | | +| | Current Value 1,4 | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Current Meter Precision N | | | | | | | | | Current Meter Scale N | | | | | | | | | | | | | | +| | Current Value N,1 | | | | | | | | | | | | | | | | | | | | | | | +| | Current Value N,2 | | | | | | | | | | | | | | | | | | | | | | | +| | Current Value N,3 | | | | | | | | | | | | | | | | | | | | | | | +| | Current Value N,4 | | | | | | | | | | | | | | | | | | | | | | | + +Reports to follow (8 bits) + +This value indicates how many report frames there are left, the value 0xFF means that the number of reports have not been calculated yet or that there is more than 255 reports to follow. Operating Status Indication (1 bit) + +The Operating Status Indication bit is used to indicate that the reported meter data is measured while the meter is in a operating status different from Normal e.g. accuracy warning or clock not accurate. + +Setting the bit to 1 means that the meter is operating in a status different from Normal. Setting the bit to 0 means that the meter is operating in Normal mode. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Rate Type (2 bits) + +[Rate Type specifies the type of parameters in the report. This field MUST be encoded according to Table 58.](../04.47-meter-command-class-version-2.md#4475-meter-report-command) + +If the Meter Type is Submeter, the Rate Type MUST be set to Import to indicate consumption. + +Dataset (24 bits) + +The dataset parameter indicates which data is included in the report. This field MUST be encoded [according to Table 68.](../04.52-meter-table-monitor-command-class-version-1/04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Year (16 bits) + +Specify the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. A year equal to 0x0000 indicates that an accumulated value is not determined yet. + +Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December). + +Day (8 bits) + +Specify the day of the month between 01 and 31. + +Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00-23) in local time. + +Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00-59) in local time. + +Second Local Time (8 bits) + +Specify the number of complete seconds since the start of the minute (00-59) in local time. The value 60 used to keep UTC from wandering away is not supported. + +Meter Precision (3 bits) + +The Meter Precision field describes what the precision of the value is. The number indicates the number of decimals. The decimal value 1025 with precision 2 is therefore equal to 10.25. Meter Scale (5 bits) + +The Meter Scale used to indicate the scale (unit) of the reported parameter. Meter Scale variables; refer [to section 4.52.13 for a definition of the variable.](../04.52-meter-table-monitor-command-class-version-1/04.52.13-meter-table-current-data-report-command.md#45213-meter-table-current-data-report-command) + +Current Value (32 bits) + +The Current Value is a 32 bit signed field defined by dataset requested field. The first byte (Value 1) is [the most significant byte. Table 10 shows signed decimal values together with their hexadecimal](../../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) equivalents. + +NOTICE: The device receiving the Meter Table Current Data Report must always show the value even though the scale is not supported. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.14-meter-table-historical-data-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.14-meter-table-historical-data-get-command.md new file mode 100644 index 0000000..f97d6df --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.14-meter-table-historical-data-get-command.md @@ -0,0 +1,69 @@ + +# 4.53.14 Meter Table Historical Data Get Command + +This command is used to request a number of time stamped values (historical) in physical units according to rate type, dataset mask and time interval. + +The Meter Table Historical Data Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL HISTORICAL DATA GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Maximum Reports | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Dataset Requested 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Dataset Requested 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Dataset Requested 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Start Month | | | | | | | | | | | | | | | | | | | | | | | | +| Start Day | | | | | | | | | | | | | | | | | | | | | | | | +| Start Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Start Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Start Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Month | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Day | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | + +Maximum Reports (8 bits) + +The maximum reports parameter is used to indicate the maximum number of reports to return based on the get. Reports are always returned with the most recently recorded value first. If set to 0x00 the meter will return all reports based on the request. + +Dataset History (24 bits) + +The Historical Dataset Requested parameter is use to indicate which parameters are requested from the [meter. This field MUST be encoded according to Table 68.](../04.52-meter-table-monitor-command-class-version-1/04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Start/Stop Year (16 bits) + +Specify the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. + +Start/Stop Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December). + +Start/Stop Day (8 bits) + +Specify the day of the month between 01 and 31. + +Start/Stop Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00-23) in local time. + +Start/Stop Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00-59) in local time. + +Start/Stop Second Local Time (8 bits) + +Specify the number of complete seconds since the start of the minute (00-59) in local time. The value 60 used to keep UTC from wandering away is not supported. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.15-meter-table-historical-data-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.15-meter-table-historical-data-report-command.md new file mode 100644 index 0000000..fdfab76 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/04.53.15-meter-table-historical-data-report-command.md @@ -0,0 +1,96 @@ + +# 4.53.15 Meter Table Historical Data Report Command + +This command is used to report a number of time stamped values. + +| | 7 | | | 6 | | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL HISTORICAL DATA REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to Follow | | | | | | | | | | | | | | | | | | | | | | | | | +| Operating Status Indication | | | | | Reserved | | | | | | | | | | | | | | Rate Type | | | | | | +| Dataset 1 | | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset 2 | | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset 3 | | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Year 1 | | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Year 2 | | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Month | | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Day | | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | | +| Historical Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Precision 1 | | | | | | | | | | Historical Scale 1 | | | | | | | | | | | | | | +| | Historical Value 1,1 | | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value 1,2 | | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value 1,3 | | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value 1,4 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Precision N | | | | | | | | | | Historical Scale N | | | | | | | | | | | | | | +| | Historical Value N,1 | | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value N,2 | | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value N,3 | | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value N,4 | | | | | | | | | | | | | | | | | | | | | | | | + +Reports to Follow (8 bits) + +This value indicates how many report frames there are left, the value 0xFF means that the number of reports have not been calculated yet or that there is more than 255 reports to follow. Operating Status Indication (1 bit) + +The Operating Status Indication bit is used to indicate that the reported meter data is measured while the meter is in a operating status different from Normal e.g. accuracy warning or clock not accurate. + +Setting the bit to 1 means that the meter is operating in a status different from Normal. Setting the bit to 0 means that the meter is operating in Normal mode. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Rate Type (2 bits) + +[Rate Type specifies the type of parameters in the report. This field MUST be encoded according to Table 58.](../04.47-meter-command-class-version-2.md#4475-meter-report-command) + +If the Meter Type is Submeter, the Rate Type MUST be set to Import to indicate consumption. + +Dataset (24 bits) + +This command parameter is defined in a bitmap format and holds values and combinations of the meters dataset. If no historical data has been registered for the period requested by the Meter Table Historical Data Get Command, all fields of this parameter must be set to ‘0’ AND no “Historical” parameters are to be included in the Meter Table Historical Data Report Command i.e. the command parameters ends after [“Dataset”. Refer to Table 68.](../04.52-meter-table-monitor-command-class-version-1/04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Historical Year (16 bits) + +Specify for the dataset the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. + +Historical Month (8 bits) + +Specify for the dataset the month of the year between 01 (January) and 12 (December). A year equal to 0x0000 indicates that an accumulated value is not determined yet. + +Historical Day (8 bits) + +Specify for the dataset the day of the month between 01 and 31. + +Historical Hour Local Time (8 bits) + +Specify for the dataset the number of complete hours that have passed since midnight (00-23) in local time. + +Historical Minute Local Time (8 bits) + +Specify for the dataset the number of complete minutes that have passed since the start of the hour (00- 59) in local time. + +Historical Second Local Time (8 bits) + +Specify for the dataset the number of complete seconds since the start of the minute (00-59) in local time. The value 60 used to keep UTC from wandering away is not supported. Historical Precision (3 bits) + +The Historical Precision field describes what the precision of the value is. The number indicates the number of decimals. The decimal value 1025 with precision 2 is therefore equal to 10.25. + +Historical Scale (5 bits) + +The Historical Scale used to indicate the scale (unit) of the reported parameter. The Historical Scale parameter is of the variable type Meter Scale [; refer to Section 4.52.13 for a definition of the variable.](../04.52-meter-table-monitor-command-class-version-1/04.52.13-meter-table-current-data-report-command.md#45213-meter-table-current-data-report-command) + +Historical Value + +The Historical Value is a 32 bit signed field defined by dataset requested field. The first byte (Value 1) is [the most significant byte. Table 10 shows signed decimal values together with their hexadecimal](../../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) equivalents. + +NOTICE: The device receiving the Meter Table Historical Data Report must always show the value even though the Scale is not supported. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/index.md b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/index.md new file mode 100644 index 0000000..c3433b5 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.53-meter-table-monitor-command-class-version-2/index.md @@ -0,0 +1,28 @@ + +# 4.53 Meter Table Monitor Command Class, version 2 + +The Meter Table Monitor Command Class defines the Commands necessary to read historical and accumulated values in physical units from a water meter or other metering device (gas, electric etc.) or electric sub-metering device and thereby enabling automatic meter reading capabilities + +## Contents + +- [4.53.1 Meter Table Point Adm. Number Get Command](04.53.01-meter-table-point-adm-number-get-command.md) +- [4.53.2 Meter Table Point Adm. Number Report Command](04.53.02-meter-table-point-adm-number-report-command.md) +- [4.53.3 Meter Table ID Get Command](04.53.03-meter-table-id-get-command.md) +- [4.53.4 Meter Table ID Report Command](04.53.04-meter-table-id-report-command.md) +- [4.53.5 Meter Table Capability Get Command](04.53.05-meter-table-capability-get-command.md) +- [4.53.6 Meter Table Capability Report Command](04.53.06-meter-table-capability-report-command.md) +- [4.53.7 Meter Table Status Supported Get Command](04.53.07-meter-table-status-supported-get-command.md) +- [4.53.8 Meter Table Status Supported Report Command](04.53.08-meter-table-status-supported-report-command.md) +- [4.53.9 Meter Table Status Depth Get Command](04.53.09-meter-table-status-depth-get-command.md) +- [4.53.10 Meter Table Status Date Get Command](04.53.10-meter-table-status-date-get-command.md) +- [4.53.11 Meter Table Status Report Command](04.53.11-meter-table-status-report-command.md) +- [4.53.12 Meter Table Current Data Get Command](04.53.12-meter-table-current-data-get-command.md) +- [4.53.13 Meter Table Current Data Report Command](04.53.13-meter-table-current-data-report-command.md) +- [4.53.14 Meter Table Historical Data Get Command](04.53.14-meter-table-historical-data-get-command.md) +- [4.53.15 Meter Table Historical Data Report Command](04.53.15-meter-table-historical-data-report-command.md) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.54-meter-table-push-configuration-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.54-meter-table-push-configuration-command-class-version-1.md new file mode 100644 index 0000000..d608c26 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.54-meter-table-push-configuration-command-class-version-1.md @@ -0,0 +1,104 @@ + +# 4.54 Meter Table Push Configuration Command Class version 1 + +The Meter Table Push Configuration Command Class is used to configure the meter to send a Current Data Report at a given interval. The meter may be configured to return different data sets at different intervals using both the primary and secondary push commands. + +## 4.54.1 Meter Table Push Configuration Set Command + +This command is used to request the meter to send a Current Data Report at a given interval. The meter may be configured to return different data sets at different intervals using both the primary and secondary push commands. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL PUSH _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL PUSH CONFIGURATION SET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | P/S | | | Operating Status Push Mode | | | | | | | | | | | | +| Push Dataset 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Push Dataset 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Push Dataset 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Interval Months | | | | | | | | | | | | | | | | | | | | | | | | +| Interval Days | | | | | | | | | | | | | | | | | | | | | | | | +| Interval Hours | | | | | | | | | | | | | | | | | | | | | | | | +| Interval Minutes | | | | | | | | | | | | | | | | | | | | | | | | +| Push Node ID | | | | | | | | | | | | | | | | | | | | | | | | + +Operating Status Push Mode (4 bits) + +[This field is used to configure if the Meter Table Status Report Command (refer to 4.52.11) participates in](04.52-meter-table-monitor-command-class-version-1/04.52.11-meter-table-status-report-command.md#45211-meter-table-status-report-command) the Push Functionality + +| | Operating Status Push Mode Identifier | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Operating Status push disabled | | | +| 0x01 | | | Operating Status push based on Interval | | | +| 0x02 | | | Operating Status push based on Status Change | | | +| 0x03 | | | Operating Status push Based on Interval AND status change | | | +| 0x04-0x0F | | | Reserved | | | + +P/S (1 bit) + +| | P/S | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Primary push configuration | | | +| 0x01 | | | Secondary push configuration | | | + +Push Dataset (24 bits) + +The Push Dataset parameter is use to indicate which parameters are requested to be pushed from the [meter. This field MUST be encoded according to Table 68.](04.52-meter-table-monitor-command-class-version-1/04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Interval Months (8 bits) + +Specify the number of months between pushing the push dataset. + +Interval Day (8 bits) + +Specify the number of days between pushing the push dataset. + +Interval Hours (8 bits) + +Specify the number of hours between pushing the push dataset. + +Interval Minute (8 bits) + +Specify the number of minutes between pushing the push dataset. + +Push Node ID (8 bits) + +Specify the node ID of the node to receive push dataset in the given interval. + +## 4.54.2 Meter Table Push Configuration Get Command + +This command is used to request the meters push configuration + +The Meter Table Push Configuration Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL PUSH _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL PUSH CONFIGURATION GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.54.3 Meter Table Push Configuration Report Command + +This command is used report the current Push Configuration + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER TBL PUSH _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER TBL PUSH CONFIGURATION REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | P/S | | | Operating Status Push Mode | | | | | | | | | | | | +| Push Dataset 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Push Dataset 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Push Dataset 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Interval Months | | | | | | | | | | | | | | | | | | | | | | | | +| Interval Days | | | | | | | | | | | | | | | | | | | | | | | | +| Interval Hours | | | | | | | | | | | | | | | | | | | | | | | | +| Interval Minutes | | | | | | | | | | | | | | | | | | | | | | | | +| Push Node ID | | | | | | | | | | | | | | | | | | | | | | | | + +[Refer to Meter Table Push Configuration Set Command (section 4.54.1) for detailed description of the](04.54-meter-table-push-configuration-command-class-version-1.md#4541-meter-table-push-configuration-set-command) fields. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.55-move-to-position-window-covering-command-class-version-1-obsoleted.md b/docs/specs/command-class-specification/04-command-class-definitions/04.55-move-to-position-window-covering-command-class-version-1-obsoleted.md new file mode 100644 index 0000000..b036f1d --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.55-move-to-position-window-covering-command-class-version-1-obsoleted.md @@ -0,0 +1,74 @@ + +# 4.55 Move To Position Window Covering Command Class, version 1 [OBSOLETED] + +THIS COMMAND CLASS HAS BEEN OBSOLETED + +New implementations MUST NOT support this command class. + +Window covering device implementations SHOULD support the Window Covering Command Class. + +The Move To Position Window Covering Command Class is used to control the position of a window covering device. + +The Move To Position Window Covering Command Class is an actuator control command class. [Refer to 3.6.](../03-command-class-overview/03.06-actuator-control.md#36-actuator-control) + +## 4.55.1 Move To Position Set Command + +This command is used to instruct a window covering to move to a new position. + +| | 7 | | | 6 | | | 5 | | | 4 | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS MTP WINDOW COVERING _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | +| Command = MOVE TO POSITION SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | +| Value | | | | | | | | | | | | | | | | | | | | | | + +Value (8 bits) + +[The encoding of the Value field MUST be according to Table 71.](04.55-move-to-position-window-covering-command-class-version-1-obsoleted.md#4551-move-to-position-set-command) + +Table 71, Move To Position Set :: Value + +| | Value | Level | | | State | | +| --- | --- | --- | --- | --- | --- | --- | +| 0 (0x00) | | 0% | | Closed | | | +| 1..99 (0x01..0x63) | | Almost closed .. 100% Open | | Open | | | +| … | | reserved | | reserved | | | +| 255 (0xFF) | | 100% Open | | Open | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +## 4.55.2 Move To Position Get Command + +This command is used to request the status of a window covering device. + +The Move To Position Report command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS MTP WINDOW COVERING _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = MOVE TO POSITION GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.55.3 Move To Position Report Command + +This command is used to advertise the status of a window covering device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS MTP WINDOW COVERING _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = MOVE TO POSITION REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Value | | | | | | | | | | | | | | | | | | | | | | | | + +Value (8 bits) + +[The encoding of the Value field MUST be according to Table 71.](04.55-move-to-position-window-covering-command-class-version-1-obsoleted.md#4551-move-to-position-set-command) + +The Value field SHOULD advertise the current value of the device hardware; also while in transition to a new target value. + +A controlling device MUST NOT assume that the Value is identical to a value previously issued with a Set command when a transition has ended. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.56-multilevel-sensor-command-class-version-1-4.md b/docs/specs/command-class-specification/04-command-class-definitions/04.56-multilevel-sensor-command-class-version-1-4.md new file mode 100644 index 0000000..015937d --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.56-multilevel-sensor-command-class-version-1-4.md @@ -0,0 +1,69 @@ + +# 4.56 Multilevel Sensor Command Class, version 1-4 + +The Multilevel Sensor Command Class is used to advertise numerical sensor readings.. + +## 4.56.1 Multilevel Sensor Get Command + +This command is used to request the current reading from a multilevel sensor. + +The Multilevel Sensor Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR MULTILEVEL GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.56.2 Multilevel Sensor Report Command + +This command is used by a supporting node to advertise its current sensor reading for its supported sensor type. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR MULTILEVEL REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Type | | | | | | | | | | | | | | | | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | | | | +| Sensor Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Value N | | | | | | | | | | | | | | | | | | | | | | | | + +Sensor Type (8 bits) + +This field is used to specify the sensor type of the actual sensor reading. + +[This field MUST be set to a value defined in [17]. Values not defined in [17] are reserved and MUST NOT](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) be used. + +A node MUST support as a minimum the highest Multilevel Sensor Command Class version associated with the Scale and Type it supports. The minimum required version for each Scale and Type is specified [in [17].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) Precision (3 bits) + +This field is used to indicate how many decimal places are included the Sensor Value field. For example, the Sensor Value 1025 with precision 2 MUST be interpreted as equal to 10.25. + +Scale (2 bits) + +This field is used to indicate what scale is used for the actual sensor reading. + +[This field MUST be set to a value defined in [17]. Values not defined in [17] are reserved and MUST NOT](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) be used. + +A node MUST implement as a minimum the highest Multilevel Sensor Command Class version associated with the Scale and Type it supports. The minimum required version for each Scale and Type [is specified in [17].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +Size (3 bits) + +This field is used to indicate the length in bytes of the Sensor Value field. This field MUST be set to 1, 2 or 4. + +Sensor Value (N bytes) + +This field is used to advertise the value of the actual sensor reading. + +The length of this field in bytes MUST be according to the Size field value. The first byte MUST be the most significant byte. [This field MUST be encoded using signed representation and comply with Table 10.](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) + +A controlling node receiving this command MUST always show the sensor value as is even though the Sensor Type and/or Scale are unknown. + +A controlling node SHOULD implement the capability to update its list of Sensor Type and Scales, so [that new Sensor Types and Scales added in [17] are not presented as unknown. If a controlling node](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) receives an unknown Sensor Type or Scale, it SHOULD allow the user to assign a free-text description to the sensor reading. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.57-multilevel-sensor-command-class-version-5-11.md b/docs/specs/command-class-specification/04-command-class-definitions/04.57-multilevel-sensor-command-class-version-5-11.md new file mode 100644 index 0000000..1aa711f --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.57-multilevel-sensor-command-class-version-5-11.md @@ -0,0 +1,312 @@ + +# 4.57 Multilevel Sensor Command Class, Version 5-11 + +The Multilevel Sensor Command Class is used to advertise numerical sensor readings . + +## 4.57.1 Compatibility considerations + +A node supporting version 5 or newer may support several sensor types and advertise the readings for each of them. + +Version 5 of this command class is extended with the following functionality: + + A “get-supported” mechanism for the controlling device to interview the multilevel sensor for its supported sensor types and/or scales  Additional sensor type and scale fields to the Multilevel Sensor Get command to request for a specific sensor report  Additional sensor types and/or scales to the list of multilevel sensors + +Version 6 of this command class is extended with the following functionality: + + Additional sensor types + +Version 7 of this command class is extended with the following functionality: + + Additional sensor types + +Version 8 of this command class is extended with the following functionality: + + New Sensor Types and Scale Values for rotation and linear movement.  New Sensor Types and Scale Values for Smoke Density + +Multilevel Sensor Command Class, version 8 deprecates the Sensor Type “Angle Position”. + +Version 9 of this command class is extended with the following functionality: + + New Sensor Types and Scale Values for Water Flow and Water Pressure  New Sensor Types and Scale Values for RF Signal Strength + +Version 10 of this command class is extended with the following functionality: + + New Sensor Types and Scale Values for Particulate Matter 10 and Respiratory rate  New Scale Values for CO and VOC Sensors Types + +Version 11 of this command class is extended with the following functionality: + + New Sensor Types and Scale Values.  [Moved the list of assigned Sensor Types and Scale Values to an external registry [17].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command)  Deprecated the “General Purpose” Sensor Type + +### 4.57.1.1 Unknown Multilevel Sensor Types and Scales + +A controlling node SHOULD implement the capability to update its Multilevel sensor types and scales list, [so that new Types and Scales added in [17] are not presented as unknown. If a controlling node receives](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) an unknown Type or Scale, it SHOULD allow the user to assign a free-text description to that Type or Scale. + +## 4.57.2 Multilevel Sensor Get Supported Sensor Command + +This command is used to request the supported Sensor Types from a supporting node. + +The Multilevel Sensor Supported Sensor Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | 6 | | | 5 | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR MULTILEVEL SUPPORTED GET SENSOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | + +## 4.57.3 Multilevel Sensor Supported Sensor Report Command + +This command is used to advertise the supported Sensor Types by a supporting node. + +| | 7 | 6 | | | 5 | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR MULTILEVEL SUPPORTED SENSOR REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | + +Bit Mask (N bytes) + +This field is used to advertise the supported sensor types by sending node. + +This field MUST be treated as a bit mask and interpreted as follows: + + Bit 0 in Bit Mask 1 indicates if Sensor Type = Air Temperature (0x01) is supported  Bit 1 in Bit Mask 1 indicates if Sensor Type = General Purpose (0x02) is supported  Bit 2 in Bit Mask 1 indicates if Sensor Type = luminance (0x03) is supported  … + +[The list of Sensor Types is defined in [17].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +The value 1 MUST indicate that the corresponding Sensor Type is supported. The value 0 MUST indicate that the corresponding Sensor Type is not supported. + +It is only necessary to send the Bit Mask fields from 1 and up to the Bit Mask N indicating the last supported Sensor Type. The number of Bit Mask fields transmitted MUST be determined from the length field in the frame. + +Note that the mapping of bit 0 to Sensor Type = 1 differs from the support mapping used by the Notification Command Class. The Notification Command Class maps bit 1 to Notification Type =1. + +## 4.57.4 Multilevel Sensor Get Supported Scale Command + +This command is used to retrieve the supported scales of the specific sensor type from the Multilevel Sensor device. + +The Multilevel Sensor Supported Scale Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR MULTILEVEL SUPPORTED GET SCALE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Type | | | | | | | | | | | | | | | | | | | | | | | | + +Sensor Type (8 bits) + +This field is used to request a given sensor type. + +If the specified sensor type is not supported, a receiving node SHOULD return a response with the Scale Bit Mask set to 0. + +## 4.57.5 Multilevel Sensor Supported Scale Report Command + +This command is used to advertise the supported scales of a specified multilevel sensor type. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR MULTILEVEL SUPPORTED SCALE REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Type | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Scale Bit Mask | | | | | | | | | | | | + +Sensor Type (8 bits) + +This field is used to indicate the actual Sensor Type for which the supported scales are being advertised. + +Scale Bit Mask (4 bits) + +This field is used to advertise the supported scales for the actual sensor type. + +This field MUST be treated as a bit mask and interpreted as follow: + + Bit 0 indicates support for the first scale of the actual Sensor Type  Bit 1 indicates support for the second scale of the actual Sensor Type  … + +[The list of scales for a given sensor type is defined in [17].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +The value 1 MUST indicate that the corresponding scale is supported for the sensor type. The value 0 MUST indicate that the corresponding scale is not supported for the sensor type. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +## 4.57.6 Multilevel Sensor Get Command + +This command is used to request the current reading from a multilevel sensor. + +The Multilevel Sensor Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR MULTILEVEL GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Type | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Scale | | | | | | Reserved | | | | | | | | | + +Sensor Type (8 bits) + +This field is used to request a node to report a reading for the specified sensor type. + +If this field is unspecified or a receiving node does not support the specified Sensor Type, it MUST reply with a pre-defined default Sensor Type and Scale. + +Scale (2 bits) + +This field is used to request a node to report a reading with a particular scale for the actual Sensor Type. + +A node receiving a non-supported scale for the actual Sensor Type MUST reply with a supported scale within the Sensor type. + +A sending node MUST ensure that the receiver supports the requested Sensor Types and/or Scales using the Multilevel Sensor Get Supported Sensor/Scale commands. + +Reserved + +These fields MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +## 4.57.7 Multilevel Sensor Report Command + +This command is used to advertise a multilevel sensor reading. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR MULTILEVEL REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Type | | | | | | | | | | | | | | | | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | | | | +| Sensor Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Value N | | | | | | | | | | | | | | | | | | | | | | | | + +Sensor Type (8 bits) + +This field is used to specify the sensor type of the actual sensor reading. + +[This field MUST be set to a value defined in [17]. Values not defined in [17] are reserved and MUST NOT](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) be used. + +A node MUST support as a minimum the highest Multilevel Sensor Command Class version associated with the Scale and Type it supports. The minimum required version for each Scale and Type is specified [in [17].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +Precision (3 bits) + +This field is used to indicate how many decimal places are included the Sensor Value field. For example, the Sensor Value 1025 with precision 2 MUST be interpreted as equal to 10.25. + +Scale (2 bits) + +This field is used to indicate what scale is used for the actual sensor reading. + +[This field MUST be set to a value defined in [17]. Values not defined in [17] are reserved and MUST NOT](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) be used. + +A node MUST implement as a minimum the highest Multilevel Sensor Command Class version associated with the Scale and Type it supports. The minimum required version for each Scale and Type [is specified in [17].](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +Size (3 bits) + +This field is used to indicate the length in bytes of the Sensor Value field. This field MUST be set to 1, 2 or 4. Sensor Value (N bytes) + +This field is used to advertise the value of the actual sensor reading. + +The length of this field MUST be according to the Size field value. The first byte MUST be the most significant byte. [This field MUST be encoded using signed representation and comply with Table 10.](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) + +A controlling node receiving this command MUST always show the sensor value as is even though the Sensor Type and/or Scale are unknown. + +A controlling node SHOULD implement the capability to update its list of Sensor Type and Scales, so [that new Sensor Types and Scales added in [17] are not presented as unknown. If a controlling node](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) receives an unknown Sensor Type or Scale, it SHOULD allow the user to assign a free-text description to the sensor reading. + +### 4.57.7.1 Detailed description: Sensor Types for Movement and Rotation + +A device may report position, velocity (position change over time) or acceleration (velocity change over time). Position, velocity and acceleration may all refer to a linear scale following an axis or a polar scale circling an axis. Position may be reported in an absolute or relative fashion. + +[The 3D reference coordinate system outlined in Figure 9 MUST be used for reporting changes in the](04.57-multilevel-sensor-command-class-version-5-11.md#45771-detailed-description-sensor-types-for-movement-and-rotation) physical orientation. + +![Figure 9, 3D reference coordinate system](assets/img-7e17d638c6.png) + +Information relating to linear position, velocity and acceleration MUST refer to the zero position on a given axis. Thus a position change or a velocity MUST be positive if moving towards a larger position, measured from the zero position. + +Information relating to an angle or change in angle MUST use the right-hand rule. This means that if one (virtually) grabs around an axis with the right hand, with the thumb in the direction of the axis, the angle increases in the direction of the index finger. Table 72, Definition of position, velocity or acceleration + +| | Application | | Definition | | +| --- | --- | --- | --- | --- | +| Linear position, absolute | | | Position with reference to 0 (e.g. 1 meter) | | +| Linear position, relative | | | Position with reference to previous position (e.g. 1 meter) | | +| Linear velocity | | | Position change per time unit (e.g. 1 meter/second) | | +| Linear acceleration | | | Velocity change per time unit (e.g. 1 meter/second2) | | +| Polar position, absolute | | | Angle with reference to 0 (e.g. 45 degrees) | | +| Polar position, relative | | | Angle with reference to previous angle (e.g. 45 degrees) | | +| Polar velocity (rotation) | | | Angle change per time unit (e.g. 1 degree/second) | | +| Polar acceleration | | | Velocity change per time unit (e.g. 1 degree/second2) | | + +Depending on the number of axes supported by a given device, changes in the physical orientation are [mapped to one, two or three axes as outlined in Table 73.](04.57-multilevel-sensor-command-class-version-5-11.md#45771-detailed-description-sensor-types-for-movement-and-rotation) + +Table 73, Mapping of 1D, 2D and 3D movement and rotation + +| | Dimensions | | | Movement | | | Rotation | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 1 | | | Along X axis | | | Around X axis | | | +| 2 | | | Along X and Y axes | | | Around X and Y axes | | | +| 3 | | | Along X, Y and Z axes | | | Around X, Y and Z axes | | | + +A number of Sensor Types allow a device to report changes in the physical orientation. + +Table 74, Recommended Sensor Types for reporting movement and rotation + +| | Application | | Sensor Type | | | Intended usage | | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 1D Linear position, absolute | | Distance (v3) | | | Single axis measurement of position (m) | | | +| 1D Linear position, relative | | (no support) | | | Single axis measurement of position change (m) | | | +| 1D Linear velocity | | Velocity (v2) | | | Single axis measurement of velocity (m/s) | | | +| 1D Linear accelleration | | Acceleration, X (v8) | | | Single axis measurement of acceleration (m/s2) | | | +| 1D Polar position, absolute | | Direction (v2) | | | Single axis measurement of angle (degrees) | | | +| 1D Polar position, relative | | (no support) | | | Single axis measurement of angle change | | | +| 1D Polar velocity | | Rotation (v5) | | | Single axis measurement of velocity (RPM) | | | +| 1D Polar accelleration | | (no support) | | | Single axis measurement of acceleration (degree/s2) | | | + +| | Application | | | Sensor Type | | | Intended usage | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 2D Linear position, absolute | | | (no support) | | | Two axis measurement of position (m) | | | +| 2D Linear position, relative | | | (no support) | | | Two axis measurement of position change (m) | | | +| 2D Linear velocity | | | (no support) | | | Two axis measurement of velocity (m/s) | | | +| 2D Linear accelleration | | | Acceleration, X (v8), Acceleration, Y (v8) | | | Two axis measurement of acceleration (m/s2) | | | +| 2D Polar position, absolute | | | (no support) | | | Two axis measurement of angle (degrees from North) | | | +| 2D Polar position, relative | | | (no support) | | | Two axis measurement of angle change | | | +| 2D Polar velocity | | | (no support) | | | Two axis measurement of velocity (RPM) | | | +| 2D Polar accelleration | | | (no support) | | | Two axis measurement of acceleration (degree/s2) | | | +| 3D Linear position, absolute | | | (no support) | | | Three axis measurement of position (m) | | | +| 3D Linear position, relative | | | (no support) | | | Three axis measurement of position change (m) | | | +| 3D Linear velocity | | | (no support) | | | Three axis measurement of velocity (m/s) | | | +| 3D Linear accelleration | | | Acceleration, X (v8), Acceleration, Y (v8), Acceleration, Z (v8) | | | Three axis measurement of acceleration (m/s2) | | | +| 3D Polar position, absolute | | | (no support) | | | Three axis measurement of angle (degrees from North) | | | +| 3D Polar position, relative | | | (no support) | | | Three axis measurement of angle change | | | +| 3D Polar velocity | | | (no support) | | | Three axis measurement of velocity (RPM) | | | +| 3D Polar accelleration | | | (no support) | | | Three axis measurement of acceleration (degree/s2) | | | + +4.57.7.1.1 Sensor Type = Acceleration The sensor types “Acceleration, X”, “Acceleration, Y” and “Acceleration, Z” are used to advertise the acceleration of a device along the X, Y and Z axes, respectively. + +A one-dimensional device MUST report acceleration using the “Acceleration, X” type. + +A two-dimensional device MUST report acceleration using the “Acceleration, X” and “Acceleration, Y” types. + +2 2 The Scale used MUST be m/s. An Acceleration value reported with the Scale m/s may be converted by [a receiving node to a “g-force” level by using the formula outlined in Figure 10.](04.57-multilevel-sensor-command-class-version-5-11.md#45771-detailed-description-sensor-types-for-movement-and-rotation) + +2 1g = 9.81m/s + +(g represents the unit of Earth Gravity; NOT the weight unit “gram”) + +2 Figure 10, Converting from m/s to g-force + +### 4.57.7.2 Detailed description: Smoke Density + +[Figure 11 shows the principle of how a photoelectric smoke detector works. As shown the smoke sensor](04.57-multilevel-sensor-command-class-version-5-11.md#45772-detailed-description-smoke-density) uses the smoke to reflect the light onto a photo cell. So when no smoke is present, the light will not be reflected onto the photo cell. When smoke is present, the light will be reflected onto the photo cell. Dependent on the smoke density, more light will be reflected onto the photo cell. So by measuring the received light strength on the photo cell, it is possible to estimate the smoke density. + +It is not possible to determine an accurate unit for this, as it is estimated from the light strength on the photo cell. So the exact particle density of the smoke is not known. Also the light strength interval measured on the photo cell, may vary between sensors. So it is decided to report the smoke density in percent, where 0% is no smoke and 100% is the maximum received light strength on the photo cell. + +![Figure 11, Photoelectric smoke detector](assets/img-8ec64d3ea0.jpeg) + +### 4.57.7.3 Detailed description: RF Signal Strength + +The RF Signal Strength sensor type may report values using two different scales. While the dBm is a well-defined unit, the RSSI value represents a relative measurement where the internal sampling circuits and the actual sampling method is product specific. The RSSI value MUST be reported in the range 0..100, where the value 100 represents the highest power level that can be measured. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.58-multilevel-switch-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.58-multilevel-switch-command-class-version-1.md new file mode 100644 index 0000000..1a92c60 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.58-multilevel-switch-command-class-version-1.md @@ -0,0 +1,128 @@ + +# 4.58 Multilevel Switch Command Class, version 1 + +The Multilevel Switch Command Class is used to control devices with multilevel capability. + +[The Multilevel Switch Command Class is an actuator control command class. Refer to 3.6.](../03-command-class-overview/03.06-actuator-control.md#36-actuator-control) + +## 4.58.1 Multilevel Switch Set Command + +This command is used to set a multilevel value in a supporting device. + +The device MAY apply a non-zero duration to the transition from one value to a new value. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH MULTILEVEL SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Value | | | | | | | | | | | | | | | | | | | | | | | | + +Value (8 bits) + +[The encoding of the Value field MUST be according to Table 75.](04.58-multilevel-switch-command-class-version-1.md#4581-multilevel-switch-set-command) + +Table 75, Multilevel Switch Set :: Value + +| | Value | | | Level | | | State | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0 (0x00) | | | 0% | | | Off | | | +| 1..99 (0x01..0x63) | | | Lowest non-zero level .. 100% | | | On | | | +| … | | | Reserved | | | Reserved | | | +| 255 (0xFF) | | | Restore most recent (non-zero) level. | | | On | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +The above mapping of the Multilevel Switch Command Class Value to hardware levels allows a controlling device to control a mixed group of Binary Switch and Multilevel Switch devices via Basic Set commands. Devices implementing the Binary Switch CC turn On or Off while devices implementing the Multilevel Switch CC sets the specified level. + +The values 0x00 and 0xFF are special values which MUST be treated as state control commands indicating “Off” and “On”, respectively. A supporting device MUST restore the most recent (non-zero) value in response to the “On” state control command. + +A device MAY implement up to 100 hardware levels (including 0). If a device implements less than 100 hardware levels, the hardware levels SHOULD be distributed uniformly over the entire range. The mapping of command values to hardware levels MUST be monotonous, i.e. a higher value MUST be [mapped to either the same or a higher hardware level. Refer to 3.6.2.](../03-command-class-overview/03.06-actuator-control.md#362-reporting-values) + +## 4.58.2 Multilevel Switch Get Command + +This command is used to request the status of a multilevel device. + +The Multilevel Switch Report command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH MULTILEVEL GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.58.3 Multilevel Switch Report Command + +This commandis used to advertise the status of a multilevel device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH MULTILEVEL REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Value | | | | | | | | | | | | | | | | | | | | | | | | + +Value (8 bits) + +[The encoding of the Value field MUST be according to Table 76.](04.58-multilevel-switch-command-class-version-1.md#4583-multilevel-switch-report-command) + +Table 76, Multilevel Switch Report :: Value + +| | Value | | Hardware level | | | State | | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 0 (0x00) | | | 0% | | Off | | | +| 1..99 (0x01..0x63) | | | Lowest non-zero level .. 100% | | On | | | +| ... | | | Reserved | | On | | | +| 254 (0xFE) | | | Unknown | | Unknown | | | +| 255 (0xFF) | | | (100%) | | On [Deprecated] | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +The value 255 (0xFF) has been deprecated as it provides no information on the actual value in the device. A sending node MUST NOT use the value 255. A receiving node MUST interpret the value 255 as 100%. The Value field SHOULD advertise the current value of the device hardware; also while in transition to a new target value. + +A controlling device MUST NOT assume that the Value is identical to a value previously issued with a Set command when a transition has ended. + +## 4.58.4 Multilevel Switch Start Level Change Command + +This command is used to initiate a transition to a new level. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH MULTILEVEL START LEVEL CHANGE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | Up/ Down | | | Ignore Start Level | | | Reserved | | | | | | | | | | | | | | | +| Start Level | | | | | | | | | | | | | | | | | | | | | | | | + +Up/Down (1 bit) + +This field MUST specify the direction of the level change. + +If the Up/Down bit is set to 0 the level change MUST be increasing. If the Up/Down bit is set to 1 the level change MUST be decreasing. + +Ignore Start Level (1 bit) + +A receiving device SHOULD respect the start level if the Ignore Start Level bit is 0. A receiving device MUST ignore the start level if the Ignore Start Level bit is 1. + +A controlling device SHOULD set the Ignore Start Level bit to 1. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Start Level (8 bits) + +The Start Level field MUST specify the initial level of the level change. + +## 4.58.5 Multilevel Switch Stop Level Change Command + +This command is used to stop an ongoing transition. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH MULTILEVEL STOP LEVEL CHANGE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.59-multilevel-switch-command-class-version-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.59-multilevel-switch-command-class-version-2.md new file mode 100644 index 0000000..901123e --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.59-multilevel-switch-command-class-version-2.md @@ -0,0 +1,81 @@ + +# 4.59 Multilevel Switch Command Class, version 2 + +The Multilevel Switch Command Class is used to control devices with multilevel capability. + +[The Multilevel Switch Command Class is an actuator control command class. Refer to 3.6.](../03-command-class-overview/03.06-actuator-control.md#36-actuator-control) + +## 4.59.1 Compatibility considerations + +A device supporting Multilevel Switch CC, version 2 MUST support Multilevel Switch CC, version 1. + +Version 2 adds a “Duration” parameter to the Multilevel Switch Set and Multilevel Switch Start/Stop Level Change commands. + +Commands not described in Version 2 remain unchanged from Version 1. + +## 4.59.2 Multilevel Switch Set Command + +This command is used to set a multilevel value in a supporting device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH MULTILEVEL SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Value | | | | | | | | | | | | | | | | | | | | | | | | +| Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Value (8 bits) + +Refer to Multilevel Switch Set V1 command. + +Duration (8 bits) + +The Duration field MUST specify the time that the transition should take from the current value to the new target value. A supporting device SHOULD respect the specified Duration value. + +[The encoding of the Duration field MUST be according to Table 7.](../03-command-class-overview/03.07-common-fields-and-encoding.md#373-duration-encoding) + +The factory default duration SHOULD be the same as the duration used for the Multilevel Switch Set command, version 1. + +## 4.59.3 Multilevel Switch Start Level Change Command + +This command is used to initiate a transition to a new level. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH MULTILEVEL START LEVEL CHANGE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | Up/ Down | | | Ignore Start Level | | | Reserved | | | | | | | | | | | | | | | +| Start Level | | | | | | | | | | | | | | | | | | | | | | | | +| Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Up/Down (1 bit) + +This field MUST specify the direction of the level change. + +If the Up/Down bit is set to 0 the level change MUST be increasing. If the Up/Down bit is set to 1 the level change MUST be decreasing. + +Ignore Start Level (1 bit) + +A receiving device SHOULD respect the start level if the Ignore Start Level bit is 0. A receiving device MUST ignore the start level if the Ignore Start Level bit is 1. + +A controlling device SHOULD set the Ignore Start Level bit to 1. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Start Level (8 bits) + +The Start Level field MUST specify the initial level of the level change. + +Duration (8 bits) + +The dimming rate to use MUST be calculated to match a transition from 0 to 99 during the time specified by the Duration field. A supporting device SHOULD respect the specified Duration value. + +[For encoding of the duration value refer to section 4.59.2.](04.59-multilevel-switch-command-class-version-2.md#4592-multilevel-switch-set-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.60-multilevel-switch-command-class-version-3.md b/docs/specs/command-class-specification/04-command-class-definitions/04.60-multilevel-switch-command-class-version-3.md new file mode 100644 index 0000000..ed7dd5c --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.60-multilevel-switch-command-class-version-3.md @@ -0,0 +1,184 @@ + +# 4.60 Multilevel Switch Command Class, version 3 + +The Secondary Switch Type of the Multilevel Switch Command Class, version 3 has been DEPRECATED. + +The Primary Switch Type 0x00, indicating “Not supported”, of the Multilevel Switch Command Class, version 3 has been OBSOLETED. + +The implementation of Secondary Switch Type functionality is NOT RECOMMENDED. + +While the functionality related to the Secondary Switch Type of the Multilevel Switch Command Class, version 3 is deprecated, a supporting device claiming compliance with this version MUST implement support for the Multilevel Switch Supported Get Command. + +For backwards compatibility reasons, a device MAY implement Secondary Switch Type functionality. It is however RECOMMENDED that Multi Channel Command Class support is also implemented if a device provides multiple controllable resources in the same physical entity. + +The Multilevel Switch Command Class is used to control devices with multilevel capability. + +[The Multilevel Switch Command Class is an actuator control Command Class. Refer to 3.6.](../03-command-class-overview/03.06-actuator-control.md#36-actuator-control) + +Multilevel Switch CC, version 3 adds two-dimensional resource control capabilities to the Multilevel Switch Start/Stop Level Change commands and introduces two new commands for the discovery of those capabilities. + +The Secondary Switch Type is intended for devices providing two-dimensional control, e.g. Window blinds, where the Primary Switch Type is used for Up/Down control and the Secondary Switch Type is used for controlling the slat tilt angle. + +The Multilevel Switch Set, Get and Report commands MUST address the primary device functionality. The Multilevel Switch Start/Stop Level Change commands MUST manipulate the Primary Switch Type functionality based on the Up/Down parameter. + +The Multilevel Switch Start/Stop Level Change commands MUST manipulate the Secondary Switch Type functionality based on the Inc/Dec parameter. If the Secondary Switch Type is 0x00 (Undefined / Not supported), the Multilevel Switch Start/Stop Level Change (Inc/Dec) command parameter MUST be ignored. + +## 4.60.1 Compatibility considerations + +A device supporting Multilevel Switch CC, version 3 MUST support Multilevel Switch CC, version 2. + +A device supporting Multilevel Switch CC, version 3 MUST implement the Primary Switch type. + +Commands not described in Version 3 remain unchanged from Version 2. + +## 4.60.2 Multilevel Switch Supported Get Command + +This command is used to request the supported Switch Types of a supporting device. + +The Multilevel Switch Supported Report command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH MULTILEVEL SUPPORTED GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.60.3 Multilevel Switch Supported Report Command + +This command is used to advertise the supported Switch Types implemented by a supporting device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH MULTILEVEL SUPPORTED REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Primary Switch Type | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Secondary Switch Type | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Primary Switch Type (5 bits) + +The Primary Switch Type field MUST represent the primary device functionality. + +Primary Switch Type 0x00, indicating “Not supported”, has been OBSOLETED. + +Previous revisions of this specification allowed that a device may (theoretically) be implemented with no primary device functionality, i.e. Primary Switch Type 0x00, and specified that such a device should indicate this situation by returning Multilevel Switch Report commands carrying the value 0xFE. The value 0xFE is incompatible with Versions 1 and 2 of the Multilevel Switch Command Class and MUST NOT be used in a Multilevel Switch Report. + +[The Primary Switch Type MUST comply with Table 77.](04.60-multilevel-switch-command-class-version-3.md#4603-multilevel-switch-supported-report-command) A supporting device MUST implement the Primary Switch type. The Primary Switch Type SHOULD be 0x02 (Up/Down). The Primary Switch Type MUST NOT be 0x00 (Undefined). + +Table 77, Encoding of Primary and Secondary Switch Types + +| | Switch | | | 0x00 | | | 0x63/0xFF | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| | Type Value | | | (Direction/Endpoint A) | | | (Direction/Endpoint B) | | +| 0x00 | | | Undefined / Not supported (Secondary only) | | | | | | +| 0x01 | | | Off | | | On | | | +| 0x02 | | | Down | | | Up | | | +| 0x03 | | | Close | | | Open | | | +| 0x04 | | | Counter-Clockwise | | | Clockwise | | | +| 0x05 | | | Left | | | Right | | | +| 0x06 | | | Reverse | | | Forward | | | +| 0x07 | | | Pull | | | Push | | | +| 0x08-0x1F | | | Reserved | | | | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Secondary Switch Type (5 bits) + +The Secondary Switch Type field MUST represent the secondary device functionality. The Secondary [Switch Type MUST comply with Table 77.](04.60-multilevel-switch-command-class-version-3.md#4603-multilevel-switch-supported-report-command) + +A supporting device MAY implement the Secondary Switch type. + +## 4.60.4 Multilevel Switch Start Level Change Command + +This command is used to initiate a transition to a new level. + +The Multilevel Switch Command Class, version 3 adds a “Secondary Switch Inc/Dec” and a “Secondary Switch Step Size” field to this command to support motor controlled devices featuring two-dimensional motion. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH MULTILEVEL START LEVEL CHANGE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Primary Switch Up/Down | | | | | | Ignore Start Level | | | Secondary Switch Inc/Dec | | | | | | Reserved | | | | | | | | | +| Primary Switch Start Level | | | | | | | | | | | | | | | | | | | | | | | | +| Duration | | | | | | | | | | | | | | | | | | | | | | | | +| Secondary Switch Step Size | | | | | | | | | | | | | | | | | | | | | | | | + +Primary Switch Up/Down (2 bits) + +The Up/Down field MUST be used for manipulating the primary device functionality. + +[This field MUST be encoded according to Table 78.](04.60-multilevel-switch-command-class-version-3.md#4604-multilevel-switch-start-level-change-command) + +Table 78, Encoding of the Up/Down field + +| | Value | | | Description | | | Details | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | Up | | | Increase level for Primary Switch Type | | | +| 0x01 | | | Down | | | Decrease level for Primary Switch Type | | | +| 0x02 | | | Reserved | | | | | | +| 0x03 | | | No Up/Down motion | | | Maintain current level for Primary Switch Type | | | + +Ignore Start Level (1 bit) + +A receiving device SHOULD respect the start level if the Ignore Start Level bit is 0. A receiving device MUST ignore the start level if the Ignore Start Level bit is 1. + +Secondary Switch Inc/Dec (2 bits) + +The Inc/Dec field MUST be used for controlling the secondary device functionality. + +If the Secondary Switch Type is 0x00 (Undefined / Not supported), the Inc/Dec field MUST be ignored. This field MUST be encoded according to the table below. + +Table 79, Encoding of the Inc/Dec field + +| | Value | | | Description | | | Details | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | Increment | | | Increase level for Secondary Switch Type | | | +| 0x01 | | | Decrement | | | Decrease level for Secondary Switch Type | | | +| 0x02 | | | Reserved | | | | | | +| 0x03 | | | No Inc/Dec | | | Maintain current level for Secondary Switch Type | | | + +As this field defines the value “00” of two previously reserved bits as the code “Increment”, a supporting device implementing Multilevel Switch CC, version 3 MUST correctly identify the Multilevel Switch Start Level Change command to be version 3 (by the presence of the field) before interpreting the field. Failing to do so will cause a device to start incrementing the Secondary Switch Type in response to version 1 and version 2 variants of the Multilevel Switch Start Level Change command. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Primary Switch Start Level (8 bits) + +The Start Level field MUST be used for controlling the primary device functionality. + +Duration (8 bits) + +This field is unchanged from version 2. + +Secondary Switch Step Size (8 bits) + +The Step Size field MAY be used for controlling a secondary device functionality. If the Secondary Switch Type is 0x00 (Undefined / Not supported), the Step Size field MUST be ignored. If the Secondary Switch Type is not 0x00, the Step Size field MUST be used for controlling the secondary device functionality. + +If the Inc/Dec field is set to 3 (No Inc/Dec), the Step Size field MUST be set to 0. + +This field MUST carry a value in the range {0x00..0x63, 0xFF}. All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. A receiving device MUST accept any of the values in the above range. 0x01 MUST represent the lowest non-zero level and 0x63 MUST represent the highest level + +A device MAY implement 100 hardware levels (including 0). If a device implements less than 100 hardware levels, the mapping to hardware levels SHOULD be distributed equally over the entire range of 1..99 (0x01..0x63). The mapping of command values to hardware levels MUST be monotonous, i.e. a higher value MUST be mapped to either the same or a higher hardware level. + +[An implementation MUST interpret the combined Inc/Dec and Step Size fields as outlined in Table 80.](04.60-multilevel-switch-command-class-version-3.md#4604-multilevel-switch-start-level-change-command) Table 80, Interpretation of the Inc/Dec and Step Size fields + +| | (Secondary | | Inc/Dec | Step Size | Interpretation | +| --- | --- | --- | --- | --- | --- | +| | Switch Type) | | | | | +| (undefined) | | | (ignore) | (ignore) | Secondary Switch Type is undefined  ignore fields | +| 0x01..0x07 | | | No Inc/Dec | (ignore) | No Inc/Dec  Maintain current Secondary Switch level | +| 0x01..0x07 | | | Increment | x | Increase Secondary Switch level by x steps | +| 0x01..0x07 | | | Decrement | y | Decrease Secondary Switch level by y steps | + +The requested level change SHOULD take the time specified by the Duration field. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.61-multilevel-switch-command-class-version-4.md b/docs/specs/command-class-specification/04-command-class-definitions/04.61-multilevel-switch-command-class-version-4.md new file mode 100644 index 0000000..6085e3b --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.61-multilevel-switch-command-class-version-4.md @@ -0,0 +1,52 @@ + +# 4.61 Multilevel Switch Command Class, version 4 + +The Multilevel Switch Command Class is used to control devices with multilevel capability. + +[The Multilevel Switch Command Class is an actuator control Command Class. Refer to 3.6.](../03-command-class-overview/03.06-actuator-control.md#36-actuator-control) + +## 4.61.1 Compatibility considerations + +Version 4 adds reporting of target value and duration. + +A device supporting Multilevel Switch CC, Version 4 MUST support Multilevel Switch CC, Version 3. + +A device receiving a V1 Multilevel Set command MAY apply a factory default duration to the transition to a new value. + +## 4.61.2 Multilevel Switch Report Command + +This command is used to advertise the status of a multilevel device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH MULTILEVEL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH MULTILEVEL REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Current Value | | | | | | | | | | | | | | | | | | | | | | | | +| Target Value | | | | | | | | | | | | | | | | | | | | | | | | +| Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Current Value (8 bits) + +[The encoding of the Value field MUST be according to Table 76.](04.58-multilevel-switch-command-class-version-1.md#4583-multilevel-switch-report-command) + +The device may be queried for its current value while in transition to a new value. The response to a Get command SHOULD be the current value of the device hardware. + +A controlling device MUST NOT assume that the Value is identical to a value previously issued with a Set command when a transition has ended. + +Target Value (8 bits) + +The Target Value field MUST advertise the target value of an ongoing transition or the most recent transition. + +[The encoding of the Target Value field MUST be according to Table 76.](04.58-multilevel-switch-command-class-version-1.md#4583-multilevel-switch-report-command) + +If queried after receiving a Set command, the Target Value field MUST advertise the target value specified in the Set command. The Target Value may change at a later time due to local control or a Multilevel Switch Stop Level Change command. + +If the device is in a motion controlled transition, the Target Value field MUST advertise the value 0x00 or 0x63. Duration (8 bits) + +The Duration field SHOULD advertise the time needed to reach the Target Value at the actual transition [rate. The encoding of the Duration field MUST be according to Table 8.](../03-command-class-overview/03.07-common-fields-and-encoding.md#373-duration-encoding) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.62-multilevel-toggle-switch-command-class-version-1-deprecated.md b/docs/specs/command-class-specification/04-command-class-definitions/04.62-multilevel-toggle-switch-command-class-version-1-deprecated.md new file mode 100644 index 0000000..3a50721 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.62-multilevel-toggle-switch-command-class-version-1-deprecated.md @@ -0,0 +1,86 @@ + +# 4.62 Multilevel Toggle Switch Command Class, version 1 [DEPRECATED] + +THIS COMMAND CLASS HAS BEEN DEPRECATED + +A device MAY implement this command class, but it is RECOMMENDED that new implementations use the Multilevel Switch Command Class. If implementing this command class, it is RECOMMENDED that the Multilevel Switch Command Class is also implemented. + +The Multilevel Toggle Switch Command Class is used for multilevel toggle-style actuator devices. + +## 4.62.1 Multilevel Toggle Switch Set Command + +This command is used to set the level in a device that supports the multilevel switch functionality. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH TOGGLE MULTILEVEL _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH TOGGLE MULTILEVEL SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.62.2 Multilevel Toggle Switch Get Command + +This command is used to request the state of the load controlled by the device. + +The Multilevel Toggle Switch Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH TOGGLE MULTILEVEL _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH TOGGLE MULTILEVEL GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.62.3 Multilevel Toggle Switch Report Command + +This command is used to advertise the level of a toggle switch. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH TOGGLE MULTILEVEL _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH TOGGLE MULTILEVEL REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Value | | | | | | | | | | | | | | | | | | | | | | | | + +Value (8 bits) + +The value MAY be 0x00 (off/disable) or 0xFF (on/enable). The field MAY carry values from 1 to 99. + +## 4.62.4 Multilevel Toggle Switch Start Level Change Command + +This command is used to inform a multilevel toggle switch, that it should start changing the level. The speed that the switch increases or decreases the level with is implementation specific. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH TOGGLE MULTILEVEL _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH TOGGLE MULTILEVEL START LEVEL CHANGE _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Roll Over | | | Reser- ved | | | Ignore Start Level | | | Reserved | | | | | | | | | | | | | | | +| Start Level | | | | | | | | | | | | | | | | | | | | | | | | + +Roll Over (1 bit) + +If the Roll Over bit is set to 0, the switch SHOULD stop when reaching the max or min level. If the roll over bit is set to 1, the switch SHOULD continually increase and decrease the level until otherwise instructed. + +Ignore Start Level (1 bit) + +If the Ignore Start Level bit is set to 0 the switch SHOULD use the start level specified in the Command. If field is set to 1 the switch SHOULD start from the actual level in the device. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Start Level (8 bits) + +The Start Level field contains the initial level that the switch should assume when it start to change the level. + +## 4.62.5 Multilevel Toggle Switch Stop Level Change Command + +This command is used to inform a multilevel toggle switch, that it should stop changing the level. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SWITCH TOGGLE MULTILEVEL _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SWITCH TOGGLE MULTILEVEL STOP LEVEL CHANGE _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.01-terminology.md b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.01-terminology.md new file mode 100644 index 0000000..b95fc13 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.01-terminology.md @@ -0,0 +1,48 @@ + +# 4.63.1 Terminology + +Sensors may be designed for several purposes. A multilevel sensor advertises measurements or readings. A notification sensor sends event or state notifications. + +This Command Class is used for notification sensors. The Multilevel Sensor Command Class is used for multilevel sensors. + +Notifications are categorized into logical groups called Notification Types. A Notification is denoted with its type and event/state: {Notification Type::event/state}. A node may send Notifications from several Notification Types. + +An event only has a meaning in the moment it happens. An event does not indicate the value of a state [variable. An example is given in Figure 12](04.63.01-terminology.md#4631-terminology) + +![Figure 12, Event notifications inform only about instantaneous situations](assets/img-10ce66b311.png) + +A state variable may assume two or more states. Some state variables are returned to their idle state via a generic “State idle” Notification. + +For example, a controlling node receiving a {Smoke alarm::Smoke detected} Notification will consider that the state has not changed until it receives a {Smoke alarm::State idle(Smoke detected)} Notification. [An illustration is given in Figure 13.](04.63.01-terminology.md#4631-terminology) + +![Figure 13, Binary state variable with generic “State idle” Notification](assets/img-a5a0d9d7be.png) + +The “State idle” notification may also be used to return a multi-value state variable to its idle state. An [example is given in Figure 14.](04.63.01-terminology.md#4631-terminology) + +![Figure 14, Multi-value state variable with generic “State idle” Notification](assets/img-de17561660.png) + +[Some state variables use a specific Notification defined for each state change. Figure 15 shows an](04.63.01-terminology.md#4631-terminology) example of such a state variable. + +![Figure 15, Binary state variable with specific idle state Notification](assets/img-fb25e9706c.png) + +Some notifications are complemented with event/state parameters. For example, the {System::System software failure} Notification may be accompanied with the manufacturer’s failure/error codes as event parameters. + +Event/state parameters may also affect state variables and their states. For example, the Notification {Irrigation::Schedule started} takes a 1-byte parameter which identifies the Schedule ID that is started. In that case, each state variable is identified using the state parameters, thus creating a state variable array. + +[An illustration is given in Figure 16, where the same Notifications with different parameters advertise the](04.63.01-terminology.md#4631-terminology) state of different state variables. + +![Figure 16, State variable array defined by additional Event/State Parameters](assets/img-be382647c3.png) + +[A complete list of Notifications (including state variables, event parameters, etc.) is given in [18].](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +A notification node operates either in Push or in Pull mode. + +A Push node sends unsolicited Notifications. The transmission of unsolicited notifications may be disabled or enabled. When enabled, unsolicited Notifications are transmitted via an Association Group. It is not possible to subsequently retrieve Notifications issued by a Push node. + +A Pull sensor collects events and state changes in a queue of pending Notifications. Notifications are retrieved one by one from the Pull sensor queue via the Notification Get Command. The Pull sensor advertises that its queue is empty when all Notifications have been retrieved. A persistent Pull Notification is not removed from the Pull sensor queue until it is actively cleared by a controlling node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.02-compatibility-considerations.md b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.02-compatibility-considerations.md new file mode 100644 index 0000000..ccca022 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.02-compatibility-considerations.md @@ -0,0 +1,195 @@ + +# 4.63.2 Compatibility considerations + +## 4.63.2.1 Notifications and Command Class version + +New Notification Types and Notifications have been added to each new version of this Command Class. A node MUST implement as a minimum the Notification Command Class version associated with the [Notifications it sends. The minimum required version for each Notification is specified in [18].](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +## 4.63.2.2 Push mode requirements + +A node supporting the Notification Command Class SHOULD implement Push mode. + +A Push node MUST implement the Association Command Class. + +A Push node SHOULD advertise Association Groups through the Association Group Information (AGI) Command Class. + +A Z-Wave Plus Push node MUST: + + Provide all supported Notifications via the Lifeline Association group.  Advertise Association Groups through the Association Group Information (AGI) Command Class. + +## 4.63.2.3 Pull mode requirements + +Earlier text revisions presented inconsistencies and undefined behaviors for Pull nodes. Thus, existing Pull nodes may behave differently than expected by a controlling node. A node supporting the Notification Command Class SHOULD NOT implement Pull mode. CC:0071.03.00.22.003 + +A Pull node MAY reorder Notifications according to priority so that the first detected event is not the first to be reported. A Pull node SHOULD NOT reorder states of the same state variable in the event queue. For example, the “Program in progress” and “Program completed” Notifications SHOULD stay in the same order. + +A Pull node having its queue full SHOULD remove the oldest notification entry from the queue. + +Persistent notifications SHOULD carry a sequence number. + +## 4.63.2.4 Multi Channel considerations + +If several End Points within a Multi Channel device support the Notification Command Class, they MUST all operate in the same mode (i.e. either all End Points operate in Push mode or all End Points operate in Pull mode). + +4.63.2.4.1 Multi Channel Push nodes + +While End Points MAY send identical notifications via the Root Device Lifeline Group, the Root Device [MUST NOT send identical Notifications on behalf of multiple End Points. Illustrations are given in Figure](04.63.02-compatibility-considerations.md#46324-multi-channel-considerations) CC:0071.03.00.21.005 [17 and Figure 18.](04.63.02-compatibility-considerations.md#46324-multi-channel-considerations) + +![Figure 17, Multi Channel device aggregating Notifications (Lifeline group)](assets/img-db9abf0d3d.png) + +![Figure 18, Multi Channel device with End Point notification overlap (Lifeline group)](assets/img-2ed45acc64.png) + +A Multi Channel node with identical End Points issuing the same binary state notification with generic state idle Notification MAY be an exception and issue binary Notifications representing the state all End Points. If doing so, the Root Device MUST issue the active state notification if any of the End Points has the active binary state and MUST issue the event inactive Notification when all End Points are back to the “State idle”. + +![Figure 19, Notification representing all End Points for Binary State with generic State Idle notification](assets/img-c52ce0b218.png) + +Z-Wave Plus Multi Channel devices MUST send End Point Push notifications via the Root Device Lifeline Association Group (if notifications are not identical). + +A controlling node SHOULD create a Multi Channel Association to the Lifeline group of a supporting node. Thus Notifications will be sent Multi Channel encapsulated via the Root Device Lifeline group, allowing End Points to send identical Notifications. + +Individual End Point Notifications can be enabled/disabled by sending a Multi Channel encapsulated Notification Set Command to an End Point, even when End Point Notifications are actually sent via the Root Device Lifeline group. + +## 4.63.2.5 State idle + +Every Notification Type has the same generic Notification 0x00 “State idle”, (also known as “Event Inactive” in older specification text) which was introduced in version 4. The Notification allows the device to advertise that a state variable returned to its idle state. + +A Push sensor MAY send repeated state Notifications without sending any “State idle” Notification to indicate that a given state is still active. For instance, a smoke sensor can send a “Smoke Detected” Notification every five minutes to indicate that the state variable has not returned to idle (refer to [Figure 13).](04.63.01-terminology.md#4631-terminology) + +Notification Command Class, version 8 increases the requirement level for the use of the “State idle” [Notification from OPTIONAL to REQUIRED. Refer to 4.63.2.11.](04.63.02-compatibility-considerations.md#463211-version-8) + +A supporting node SHOULD NOT send a “State idle” notification for an event or for a state variable to [which state idle does not apply. Refer to [17] for state variables to which the “State idle” notification](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) applies + +## 4.63.2.6 Version 3 [DEPRECATED] + +The Notification Command Class version 3 is an extension of the Alarm Command Class version 2 and adds the following: + + [Additional Notifications (refer to [18])](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command)  Interview process includes Events (Event Supported Get / Event Supported Report)  Sequence field added for collection management of reports  The queue empty status (=0xFE) for Pull nodes. A Pull node can now advertise Notification Status = “no pending notifications” + +Commands not mentioned in this version are unchanged from Alarm Command Class version 1 and/or Alarm Command Class version 2. + +The CC identifier for Notification CC V3 is the same as the Alarm CC V1 and V2. However, the Notification Command Class is not fully backwards compatible with the Alarm Command Class, versions 1 and 2. Clarifications for ensuring backwards compatibility with version 1 and 2 are given in version 4 of this Command Class. + +An implementation supporting Alarm CC V1 fields MUST map proprietary alarm types and levels to a similar Notification Type and Notification CC V3 where possible. In addition, all Alarm CC V1 alarm types and levels MUST be described in the product manual. + +## 4.63.2.7 Version 4 [DEPRECATED] + +Version 4 of this Command Class introduces the following: + + [Additional Notifications (refer to [18])](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command)  Event/State = 0x00 (State idle) for a given Notification Type to indicate that all state variables of that Notification Type returned to idle  The Zensor Net Source Node ID field has been discontinued. It is now a reserved field.  Clarification to expected behavior in regards to: V1 and V2 Alarm Get Command handling o o Notification Status field description Notification Type = 0xFF, “Return first detected notification on supported list” o Event = 0xFE in Event Supported Report Command, which must not be advertised. o The support for state idle (event/state=0x00) cannot be advertised in the Event Supported Get Command and version 4 nodes will appear to use reserved values for version 3 controlling nodes. + +[A version 4 node MUST comply with the rules outlined in Table 81 and Table 82.](04.63.02-compatibility-considerations.md#46327-version-4-deprecated) + +[Table 81 outlines the required behavior when receiving an Alarm Get command, Version 1. Table 82 outlines the required behavior when receiving an Alarm Get command, Version 2.](04.63.02-compatibility-considerations.md#46327-version-4-deprecated) The version of an Alarm Get Command can be determined from the command length. + +Table 81, Required behavior when receiving Alarm Get, version 1 + +| | Received Command: V1, ALARM GET (Alarm Type = x) _ | | | | +| --- | --- | --- | --- | --- | +| | V1 Alarm Type | | Response | | +| | supported (x)? | | | | +| YES | | | V1, ALARM REPORT (Alarm Type = x, Alarm Level = level) _ | | +| NO | | | V1, ALARM REPORT (Alarm Type = 0x00, Alarm Level = 0x00) _ | | + +Table 82, Required behavior when receiving Alarm Get, version 2 + +| Received Command: V2, ALARM GET (Alarm Type = x, Z-Wave Alarm Type = y) _ | | | +| --- | --- | --- | +| Z-Wave Alarm Type supported (y)? | | Response | +| | V1 Alarm Type | | +| | supported (x)? | | +| | | | +| NO | NO | NO RESPONSE | +| NO | YES | V2, ALARM REPORT ( _ Alarm Type = x Alarm Level = level Reserved = 0x00 Z-Wave Alarm Status = 0x00 Z-Wave Alarm Type = 0x00 Z-Wave Alarm Event = 0x00 Number of Event Param = 0x00 ) | +| YES or y = 0xFF | YES/NO | Notifications newer than V2, idle states or empty queues MUST be represented with the unknown notification (Notification event/state field set to 0xFE). If no state is detected (push nodes) or no event/state queued (pull nodes), the Notification Type MUST be set to one of the supported Notification Type in response to a Get (Type = 0xFF) Push nodes: A supporting node MUST return the current states compatible with V2. Table 84 shows a Push node example returning responses to different V2 Alarm Get Commands. Pull nodes: A supporting node MUST return only V2 notifications from its queue when receiving a V2 Alarm Get Command. A supporting node MUST set the status to 0x00 and event to 0xFE when its queue is empty. Table 85 shows a Pull node example returning responses to different V2 Alarm Get Commands. | + +CC:0071.04.00.21.003 nodes), the Notification Type MUST be set to one of the supported + +[Table 84 and Table 85 show the responses of a node supporting Notification Types and Notifications described in Table 83:](04.63.02-compatibility-considerations.md#46327-version-4-deprecated) + +Table 83, V2 Alarm Get node capabilities example + +| Node capabilities | | +| --- | --- | +| Notifications Types | Notifications | +| 0x01: Smoke Alarm | 0x01: Smoke detected 0x03: Smoke alarm test 0x06: Alarm silenced | +| 0x03: CO2 Alarm | 0x01: Carbon dioxide detected | + +Table 84, Push node responses to V2 Alarm Get (example) + +| Received Get | | Current states at the receiving node | | | Returned response | | | +| --- | --- | --- | --- | --- | --- | --- | --- | +| V1 | Type | | | | | Status | | +| | | Smoke Alarm:: | Smoke Alarm:: | CO2 Alarm:: | | | Event/ | +| Alarm | | | | | Type | | | +| | | Sensor status | Alarm status | Sensor status | | | State | +| Type | | | | | | | | +| | | | | | | | | +| -* | 0x01 | Idle | Idle | - | 0x01 | 0x00 or 0xFF | 0xFE | +| - | 0x01 | Smoke detected (V2) | Idle | - | 0x01 | 0x00 or 0xFF | 0x01 | +| - | 0x01 | Smoke detected (V2) | Alarm silenced (V8) | - | 0x01 | 0x00 or 0xFF | 0x01 | +| - | 0x01 | Idle | Smoke alarm test (V3) | - | 0x01 | 0x00 or 0xFF | 0xFE | +| 0x00 | 0x02 | - | - | - | No Report | | | +| 0x01 | 0x02 | - | - | - | No Report, unless V1 alarm is supported. Refer to Table 82 | | | +| - | 0xFF | Idle | Idle | Idle | 0x01 or 0x03** | 0x00 or 0xFF | 0xFE | +| - | 0xFF | Smoke detected (V2) | Idle | Idle | 0x01 | 0x00 or 0xFF | 0x01 | +| - | 0xFF | Smoke detected (V2) | Alarm silenced (V8) | Idle | 0x01 | 0x00 or 0xFF | 0x01 | +| - | 0xFF | Idle | Smoke alarm test (V3) | Idle | 0x01 | 0x00 or 0xFF | 0xFE | +| - | 0xFF | Smoke detected (V2) | Idle | Carbon dioxide detected (V2) | 0x01 or 0x03** | 0x00 or 0xFF | 0x01 | + +*) The symbol ‘-’ indicates that the value has no impact on the V2 fields of the returned response **) It is up to the node to decide which Notification Type to report. Table 85, Pull node responses to V2 Alarm Get (example) + +| Received Get | | Before returning a report | Returned response | | | After returning a report | +| --- | --- | --- | --- | --- | --- | --- | +| V1 | Type | | | Status | | Node’s queue | +| | | | | | Event/ | | +| Alarm | | Node’s queue | Type | | | | +| | | | | | State | | +| Type | | | | | | | +| | | | | | | | +| -* | 0x01 | Empty | 0x01 | 0x00 | 0xFE | Empty | +| - | 0x01 | Carbon dioxide detected (V2) Smoke detected (V2) | 0x01 | 0x00 | 0x01 | Carbon dioxide detected (V2) | +| - | 0x01 | Alarm silenced (V8) Smoke detected (V2) | 0x01 | 0x00 | 0x01 | Alarm silenced (V8) | +| - | 0x01 | Alarm silenced (V8) | 0x01 | 0x00 | 0xFE | Alarm silenced (V8) | +| 0x00 | 0x02 | - | No Report | | | - | +| 0x01 | 0x02 | - | No Report, unless V1 alarm is supported. Refer to Table 82 | | | - | +| - | 0xFF | Empty | 0x01 or 0x03** | 0x00 | 0xFE | Empty | +| - | 0xFF | Carbon dioxide detected (V2) Smoke detected (V2) | 0x03 | 0x00 | 0x01 | Smoke detected (V2) | +| - | 0xFF | Alarm silenced (V8) | 0x01 | 0x00 | 0xFE | Alarm silenced (V8) | + +*) The symbol ‘-’ indicates that the value has no impact on the V2 fields of the returned response **) It is up to the node to decide which Notification Type to report. + +## 4.63.2.8 Version 5 [DEPRECATED] + +[Version 5 of this Command Class introduces additional Notifications (refer to [18]) and the event/state](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) parameters for the special purpose State idle 0x00, allowing to specify which state variable returned to idle. + +A version 4 controlling node will conclude that all state variables have returned to idle when a version 5 node advertises that a single state variable has returned to idle. + +## 4.63.2.9 Version 6 [DEPRECATED] + +[Version 6 of this Command Class introduces additional Notifications (refer to [18])](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +Version 6 clarifies how to use the ‘User Code Report’ Event Parameter. The User Code Report Command is used as Event Parameter for the Notification {Access Control::Keypad Lock/Unlock Operation} Command. + +[An example of Notification Event/State Parameter encapsulation is given in 4.63.6.1](04.63.06-notification-report-command.md#46361-event-state-parameter-encapsulation) + +## 4.63.2.10 Version 7 [DEPRECATED] + +[Version 7 of this Command Class introduces additional Notifications (refer to [18]).](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +## 4.63.2.11 Version 8 + +It is RECOMMENDED that new nodes support version 8 of this Command Class. + +Requirements for backwards compatibility with version 2 nodes introduced in version 4 have been found to be ambiguous and challenging to be observed correctly by newer nodes. Therefore, it is OPTIONAL [for a version 8 node to comply Table 81 and Table 82 when receiving a V2 Get Command.](04.63.02-compatibility-considerations.md#46327-version-4-deprecated) + +[Version 8 of this Command Class introduces additional Notifications (refer to [18]).](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +Version 8 increases the requirement level for the use of the “State idle” Notification from OPTIONAL to REQUIRED. + +Supporting nodes implementing version 8 or newer of the Notification Command Class MUST issue a “State idle” Notification when a state variable returns to idle. For instance, the {Smoke alarm::Smoke Detected} Notification MUST be followed by a {Smoke alarm::State idle(Smoke detected)} Notification [when the smoke is no longer detected by the sensor. (refer to Figure 13).](04.63.01-terminology.md#4631-terminology) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.03-interoperability-considerations.md b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.03-interoperability-considerations.md new file mode 100644 index 0000000..ee0d84e --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.03-interoperability-considerations.md @@ -0,0 +1,20 @@ + +# 4.63.3 Interoperability considerations + +## 4.63.3.1 Push nodes Basic control + +For Push nodes, it is RECOMMENDED to implement additional association groups for relevant Notifications, which issue a Basic Set Command. It allows configuring a device to control other nodes directly, e.g., turn on lights when motion is detected and turn off when there is no more motion. + +## 4.63.3.2 Event flood + +Certain sensors may trigger repeatedly within a short amount of time. It is RECOMMENDED to [implement timers to arbitrate the transmission of notifications. Illustrations are given in Figure 20 and Figure 21.](04.63.03-interoperability-considerations.md#46332-event-flood) + +![Figure 20, recommended timer mechanism for sending notifications (1)](assets/img-17ed9bdd33.png) + +![Figure 21, recommended timer mechanism for sending notifications (2)](assets/img-13ece31554.png) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.04-notification-set-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.04-notification-set-command.md new file mode 100644 index 0000000..32ffb03 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.04-notification-set-command.md @@ -0,0 +1,54 @@ + +# 4.63.4 Notification Set Command + +Push nodes: + +This command is used to enable or disable the unsolicited transmission of a specific Notification Type. + +Pull nodes: + +This command is used to clear a persistent Notification in the notification queue. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS NOTIFICATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = NOTIFICATION SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Notification Type | | | | | | | | | | | | | | | | | | | | | | | | +| Notification Status | | | | | | | | | | | | | | | | | | | | | | | | + +Notification Type (8 bits) + +[This field is used to specify a Notification Type. Assigned values are defined in [18].](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +A sending node MUST specify a Notification Type that is supported by a receiving node. + +A receiving node MUST ignore the command if this field is set to a non-supported Notification Type or if this field set to 0xFF. + +Notification Status (8 bits) + +Push nodes: + +This field is used to set the Status of a Notification Type. [This field MUST comply with Table 86.](04.63.04-notification-set-command.md#4634-notification-set-command) + +Table 86, Notification Set::Notification Status (push mode) + +| | Value | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | Unsolicited messages MUST be disabled for the specified Notification Type | | | 2 | | | +| 0xFF | | | Unsolicited messages MUST be enabled for the specified Notification Type | | | 2 | | | + +0x00 Unsolicited messages MUST be disabled for the specified Notification Type 2 CC:0071.03.06.11.004 + +CC:0071.03.06.11.005 0xFF Unsolicited messages MUST be enabled for the specified Notification Type 2 All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +A receiving node MAY deny the deactivation of a specific Notification Type. In that case, the receiving node MUST respond to this command with an Application Rejected Request Command. Thus, if a node can deny the deactivation of a Notification Type, the node MUST implement the Application Status CC. A sending node should be aware that a receiving node may return a response to the Set Command and thus SHOULD apply a back-off timer before sending a subsequent command. Pull nodes: + +A sending node MUST set this field to 0x00 to indicate that a persistent Notification for the specified Notification Type MUST be cleared in the receiving node’s queue. + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.05-notification-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.05-notification-get-command.md new file mode 100644 index 0000000..01d8865 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.05-notification-get-command.md @@ -0,0 +1,68 @@ + +# 4.63.5 Notification Get Command + +Push nodes: + +This command is used to request if the unsolicited transmission of a specific Notification Type is enabled. Some supporting nodes will also advertise a current state in response to this command. + +Pull nodes: + +This command is used to retrieve the next Notification from the receiving node’s queue. + +[The Notification Report Command MUST be returned in response to this command unless this command](04.63.06-notification-report-command.md#4636-notification-report-command) is to be ignored. Refer to the fields description. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS NOTIFICATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = NOTIFICATION GET _ | | | | | | | | | | | | | | | | | | | | | | | | +| V1 Alarm Type | | | | | | | | | | | | | | | | | | | | | | | | +| Notification Type | | | | | | | | | | | | | | | | | | | | | | | | +| Notification Event / State | | | | | | | | | | | | | | | | | | | | | | | | + +V1 Alarm Type (8 bits) + +The use of this field depends on the V1 Alarm field advertised in the Alarm Type Supported Report Command. + +A sending node MAY specify a V1 Alarm Type if the receiving node supports the actual alarm type. A sending node MUST specify the value 0x00 if the receiving node does not support V1 alarms. + +[The receiving node behavior SHOULD comply with Table 81 and Table 82.](04.63.02-compatibility-considerations.md#46327-version-4-deprecated) Notification Type (8 bits) + +[This field is used to specify a Notification Type. Assigned values are defined in [18].](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +This field MUST be set to a Notification Type that is supported by the receiving node or to 0xFF. A receiving node MUST ignore the command if this field is different than 0xFF and set to a non- supported Notification Type. + +Push nodes: + +The value 0xFF indicates to the receiving node that it MUST select a supported Notification Type and SHOULD advertise the current state of one of its state variables within the chosen Notification Type. CC:0071.03.04.12.002 + +A supported Notification Type value indicates that the receiving node MUST advertise the unsolicited transmission status for the requested Notification Type and MAY advertise the current state of one of its state variables within the Notification Type. + +Pull nodes: + +The value 0xFF indicates to the receiving node that it MUST retrieve the next Notification in its queue. + +A Notification Type value indicates to the receiving node that it SHOULD retrieve the next Notification in its Notification queue matching the specified Notification Type value. + +Notification Event / State (8 bits) + +This field is used to optionally specify a Notification Event/State within the Notification Type. Assigned [values are defined in [18]. This field allows receiving nodes to differentiate between V2 Alarm Get](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) Command and V3 or newer Notification Get Command. + +If the Notification Type is set to 0xFF, this field MUST be set to 0x00 by a sending node and SHOULD be ignored by a receiving node. + +Push nodes: + +A sending node MAY set this field to 0x00. A sending node MAY specify a value that is supported by the receiving node within the specified Notification Type. In this case, a receiving node:  MAY advertise a current state related to the indicated state  MAY return the same value in response to a supported Notification Event. + +A receiving node MUST return the “Unknown notification” value (0xFE) in response to a non- supported Notification Event. + +Pull nodes: + +This field SHOULD be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.06-notification-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.06-notification-report-command.md new file mode 100644 index 0000000..939f423 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.06-notification-report-command.md @@ -0,0 +1,157 @@ + +# 4.63.6 Notification Report Command + +Push nodes: + +This command is used for two purposes:  If this command is returned in response to a Notification Get Command, this command advertises if the unsolicited transmission of the advertised Notification Type is enabled and optionally advertises a currently active state.  If this command is sent unsolicited, it advertises an event or state Notification. + +The use of the command’s fields is the same in both cases. + +Pull nodes: + +This command is used by a sending node to return a Notification from its queue or indicate that its queue is empty. + +| | 7 | | | 6 | | | 5 | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS NOTIFICATION _ _ | | | | | | | | | | | | | | | | | | | | | | +| Command = NOTIFICATION REPORT _ | | | | | | | | | | | | | | | | | | | | | | +| V1 Alarm Type | | | | | | | | | | | | | | | | | | | | | | +| V1 Alarm Level | | | | | | | | | | | | | | | | | | | | | | +| | Reserved | | | | | | | | | | | | | | | | | | | | | +| | Notification Status | | | | | | | | | | | | | | | | | | | | | +| | Notification Type | | | | | | | | | | | | | | | | | | | | | +| | Notification Event / State | | | | | | | | | | | | | | | | | | | | | +| | Sequence | | | Reserved | | | | Event / State Parameters Length | | | | | | | | | | | | | | +| Event /State Parameter 1 (optional) | | | | | | | | | | | | | | | | | | | | | | +| ... | | | | | | | | | | | | | | | | | | | | | | +| Event / State Parameter N (optional) | | | | | | | | | | | | | | | | | | | | | | +| Sequence Number (optional) | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +V1 Alarm Type (8 bits) & V1 Alarm Level (8 bits) + +These fields carry the proprietary Alarm Type and Alarm Level fields originally introduced with Alarm Command Class, Version 1. V1 Alarm Type and V1 Alarm Level fields MUST be specified in the product manual. + +If the V1 Alarm Type is not supported, these fields MUST be set to 0x00. Notification Status (8 bits) + +Push nodes: + +This field is used to advertise the status of the Notification Type indicated in this command. [This field MUST comply with Table 87.](04.63.06-notification-report-command.md#4636-notification-report-command) + +[Table 87, Notification Report::Notification Status (push nodes)](04.63.06-notification-report-command.md#4636-notification-report-command) + +| | Value | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | Unsolicited transmissions are disabled for the specified Notification Type | | | 2 | | | +| 0xFF | | | Unsolicited transmissions are enabled for the specified Notification Type | | | 2 | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Pull nodes: + +This field is used to advertise the status of the sending node’s Notification queue. [This field MUST comply with Table 88](04.63.06-notification-report-command.md#4636-notification-report-command) + +Table 88, Notification Report::Notification Status (pull nodes) + +| | Value | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | This command carries a valid Notification returned from the queue. There may be more Notifications queued up. This Notification MAY be persistent. | | | 2 | | | +| 0xFE | | | This command does not carry any valid Notification and the event queue is empty | | | 3 | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Notification Type (8 bits) + +[This field is used to advertise the Notification Type. Assigned values are defined in [18].](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +A sending node MUST set this field to the Notification Type of the actual Notification. + +Notification Event / State (8 bits) + +This field is used to specify a Notification Event/State for the advertised Notification Type. Assigned [values are defined in [18].](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +A node advertising a Notification MUST set this field to the actual Notification event/state. + +Sequence (1 bit) + +This field is used to advertise the presence of the “Sequence Number” field. + +The value 0 MUST indicate that no “Sequence Number” field is appended after the “Event / State Parameter” field. The value 1 MUST indicate that a “Sequence Number” field is appended after the “Event / State Parameter” field. Event / State Parameters Length (5 bits) + +This field is used to advertise the length in bytes of the Event / State Parameters field. + +The value 0 MUST indicate that no Event / State Parameter field is appended after the Event Parameters Length field. Values in the range 1..31 MUST indicate the length of the Event / State Parameter field appended after the Event / State Parameters Length field. + +Event / State Parameter (N bytes) + +The Event / State Parameter field is used to specify associated parameters to a Notification. + +[Parameters for each Event/State Notification are defined in [18].](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +This field MAY carry an encapsulated command. In this case, the field MUST include the complete command structure, i.e. Command Class, Command and all mandatory command fields. + +If a node encapsulates a command in this field, the corresponding Command Class MUST be supported by the node and advertised in the Node Information Frame (NIF) or S0/S2 Supported Command Report. + +This field MUST be omitted if the “Event Parameter Length” field is set to 0. + +[4.63.6.1 provides an example of Event Parameter encapsulation.](04.63.06-notification-report-command.md#46361-event-state-parameter-encapsulation) + +Sequence Number (8 bits) + +This field is used to advertise a sequence number for the actual Notification. This command MAY carry a Sequence Number field. + +This field MUST be omitted if the Sequence flag is set to 0. + +The first sequence number for each distinct Notification MUST be 1. A sending node MUST increment the sequence number for a Notification each time it issues a Notification Report for that given Notification. + +The Sequence Number range MUST be in the range 0..255. The value after 255 MUST be 0. + +Example: + +1. Notification {Smoke Alarm::Smoke Detected}, …, Seq. Number = 254 2. Notification {Smoke Alarm::Smoke Detected}, …, Seq. Number = 255 3. Notification {Heat Alarm::Overheat Detected}, …, Seq. Number = 6 4. Notification {Smoke Alarm::Smoke Detected}, …, Seq. Number = 0 5. Etc. + +## 4.63.6.1 Event / State parameter encapsulation + +Event / State parameter encapsulation of commands MUST comprise the entire command, starting from the Command Class identifier. + +For example, a “User Code Report” is used as Event / State Parameter in a “Keypad Lock/Unlock Operation”. The “User Code Report” has the following format: + + Command Class = = 0x63 COMMAND_CLASS_USER_CODE  Command = = 0x03 USER_CODE_REPORT  User Identifier = 0x01  User ID Status = 0x01  User Code = 0x30, 0x30, 0x30, 0x30 + +The complete User Code Report therefore comprises the following Bytes: [0x63, 0x03, 0x01, 0x01, 0x30, 0x30, 0x30, 0x30]. + +[Another example with the Node naming and location Command class is given in Table 89.](04.63.06-notification-report-command.md#46361-event-state-parameter-encapsulation) + +Table 89, Notification Report::Event / State parameter encapsulation (example) + +| | Notification Report Command fields | | | | Value | | | Explanation | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 1 | | COMMAND CLASS NOTIFICATION _ _ | | 0x71 | | | Notification CC id | | | +| 2 | | NOTIFICATION REPORT _ | | 0x05 | | | Notification Report command id | | | +| 3 | | V1 Alarm Type | | 0x00 | | | Not implemented | | | +| 4 | | V1 Alarm Level | | 0x00 | | | Not implemented | | | +| 5 | | Reserved | | 0x00 | | | Reserved field | | | +| 6 | | Notification Status | | 0xFF | | | Unsolicited report is activated | | | +| 7 | | Notification Type | | 0x01 | | | Smoke Alarm | | | +| 8 | | Notification Event | | 0x01 | | | Smoke Detected | | | +| 9 | | Sequence Number / Event Parameters Length | | 0x1A | | | Sequence Number is appended / Event Parm Length = 10 | | | +| 10 | | Event Parm 1 | | 0x77 | | | Node Naming & Location CC id | | | +| 11 | | Event Parm 2 | | 0x06 | | | Node Location Report command id | | | +| 12 | | Event Parm 3 | | 0x00 | | | Cmd Parm: Char = ASCII | | | +| 13 | | Event Parm 4 | | 0x4B | | | Cmd Parm: Node Location Char 1 = K | | | +| 14 | | Event Parm 5 | | 0x49 | | | Cmd Parm: Node Location Char 2 = I | | | +| 15 | | Event Parm 6 | | 0x54 | | | Cmd Parm: Node Location Char 3 = T | | | +| 16 | | Event Parm 7 | | 0x43 | | | Cmd Parm: Node Location Char 4 = C | | | +| 17 | | Event Parm 8 | | 0x48 | | | Cmd Parm: Node Location Char 5 = H | | | +| 18 | | Event Parm 9 | | 0x45 | | | Cmd Parm: Node Location Char 6 = E | | | +| 19 | | Event Parm 10 | | 0x4E | | | Cmd Parm: Node Location Char 7 = N | | | +| 20 | | Sequence Number | | 0x0F | | | Sequence Number = 15 | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.07-notification-supported-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.07-notification-supported-get-command.md new file mode 100644 index 0000000..5015f00 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.07-notification-supported-get-command.md @@ -0,0 +1,19 @@ + +# 4.63.7 Notification Supported Get Command + +This command is used to request supported Notification Types. + +The Notification Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS NOTIFICATION _ _ | | | | | | | | | | | | | | | | | | | | | | +| Command = NOTIFICATION SUPPORTED GET _ _ | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.08-notification-supported-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.08-notification-supported-report-command.md new file mode 100644 index 0000000..696ff5d --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.08-notification-supported-report-command.md @@ -0,0 +1,39 @@ + +# 4.63.8 Notification Supported Report Command + +This command is used to advertise supported Notification Types. + +| | 7 | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS NOTIFICATION _ _ | | | | | | | | | | | | | | | | | | | | | | +| Command = NOTIFICATION SUPPORTED REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | +| | V1 Alarm | Reserved | | | | | Number of Bit Masks | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | +| ... | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | | + +V1 Alarm (1 bit) + +This field is used to indicate if the node implements proprietary Alarms from version 1. + +The value 0 MUST indicate that the device implements only Notification CC V2 or newer Notification Types. The value 1 MUST indicate that the device implements Notification CC V2 Notification Types as well as proprietary Alarm CC V1 Alarm Types and Alarm Levels. + +Number of Bit Masks (5 bits) + +This field MUST advertise the length in bytes of the Bit Mask field. The value MUST be in the range 1..31. Bit Mask (N bytes) + +The Bit Mask field describes the supported Notification Types by the node. The length of this field in bytes MUST match the value advertised in the Number of Bit Masks field. + + Bit 0 in Bit Mask 1 is not allocated to any Notification Type and MUST be set to zero.  Bit 1 in Bit Mask 1 indicates if Notification Type = Smoke Alarm (0x01) is supported.  Bit 2 in Bit Mask 1 indicates if Notification Type = CO Alarm (0x02) is supported.  Bit 3 in Bit Mask 1 indicates if Notification Type = CO Alarm (0x03) is supported 2  … + +[For Notification Types, refer to [18].](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +If the Notification Type is supported, the corresponding bit MUST be set to 1. If the Notification Type is not supported, the corresponding bit MUST be set to 0. + +The Notification Type values 0x00 and 0xFF are special-purpose values. Reserved values and special- purpose values MUST NOT be advertised in the Bit Mask field by a sending node and MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.09-event-supported-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.09-event-supported-get-command.md new file mode 100644 index 0000000..bfe811d --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.09-event-supported-get-command.md @@ -0,0 +1,26 @@ + +# 4.63.9 Event Supported Get Command + +This command is used to request the supported Notifications for a specified Notification Type. + +The Event Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS NOTIFICATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = EVENT SUPPORTED GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Notification Type | | | | | | | | | | | | | | | | | | | | | | | | + +Notification Type (8 bits) + +[For Notifications Types, refer to [18].](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +If a node receives an unsupported Notification Type or a special-purpose value, the receiving node [MUST respond with Event Supported Report Command with the Notification Type specified in the this](04.63.10-event-supported-report-command.md#46310-event-supported-report-command) command and the Number of Bit Masks field set to 0. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.10-event-supported-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.10-event-supported-report-command.md new file mode 100644 index 0000000..d03f285 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.10-event-supported-report-command.md @@ -0,0 +1,44 @@ + +# 4.63.10 Event Supported Report Command + +This command is used to advertise supported events/states for a specified Notification Type. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS NOTIFICATION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = EVENT SUPPORTED REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Notification Type | | | | | | | | | | | | | | | | | | | | | | | | +| | Reserved | | | | | | | | | Number of Bit Masks | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| ... | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | | + +Notification Type (8 bits) + +[For Notifications Types, refer to [18].](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +Number of Bit Masks (5 bits) + +This field is used to advertise the length (in bytes) of the Bit Mask field. + +The value MUST be in the range 0..31. The value 0 MUST indicate that the Notification Type is not supported. + +Bit Mask (N bytes) + +This field is used to advertise the supported Events/States for the actual advertised Notification Type. The length of this field (in bytes) MUST match the value advertised in the Number of Bit Masks field. This field MUST be omitted if the “Number of Bit Masks” field is set to 0. + +The bit value ‘1’ MUST indicate that the actual Event/State is supported. The bit value ‘0’ MUST indicate that the actual Event/State is not supported. + +Example: Notification Type = Heat Alarm (0x04): + + Bit 0 in Bit Mask 1 field is not allocated to any event and must therefore be set to zero.  Bit 1 in Bit Mask 1 field indicates support for Overheat detected (0x01).  Bit 2 in Bit Mask 1 field indicates support for Overheat, unknown loc. (0x02).  Bit 3 in Bit Mask 1 field indicates support for Rapid temp rise (0x03).  … + +[For Notification Types and their Events/States, refer to [18][17].](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +The Event/State values 0x00 and 0xFE are special-purpose values. Reserved values and special- purpose values MUST NOT be advertised in the Bit Mask field by a sending node and MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.11-controller-guidelines.md b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.11-controller-guidelines.md new file mode 100644 index 0000000..484f52c --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/04.63.11-controller-guidelines.md @@ -0,0 +1,114 @@ + +# 4.63.11 Controller guidelines + +This section presents guidelines for controlling legacy sensors nodes supporting the Notification Command Class, version 3-8. + +Alarm Command Class version 2 supporting nodes operate in Push mode only. The guidelines [presented in 4.63.11.6 Controlling Push Mode Sensors can also be used for controlling Alarm CC](04.63.11-controller-guidelines.md#463116-controlling-push-mode-sensors) version 2 supporting nodes. + +## 4.63.11.1 Sensor database + +The following sections present discovery methods for sensor properties, such as Push/Pull mode or the use of state idle notifications. Some sensor properties (e.g. configuration parameters, Association group properties, state variables dependencies) cannot always be discovered. + +A public database of known certified Notification sensors is available and can be consulted first before attempting to probe a supporting node. If the supporting node is present in the database, a controlling node SHOULD read the sensor properties from the database and skip any discovery. + +## 4.63.11.2 Push/Pull mode discovery + +A supporting node does not advertise whether it operates in Push or Pull mode. Therefore a controlling node SHOULD probe a supporting node in order to discover which mode it implements. The RECOMMENDED discovery steps for a controlling node are the following: + +If the supporting node does not support the Association Command Class, it may be concluded that the supporting node implements Pull Mode and discovery may be aborted. + +If the supporting node supports the AGI Command Class, probe the AGI table in the following way: + +1. Discover how many Association groups the supporting node (and its eventual End Points) implements by issuing an Association Supported Groupings Get Command. 2. For each association group, issue an Association Group Command List Get for the grouping identifier. Inspect the returned Association Group Command List Report and look for the following pair: {Command Class x = Command x =. COMMAND_CLASS_NOTIFICATION, NOTIFICATION_REPORT} If a match is found, conclude that the supporting node implements Push Mode and stop the discovery process. + +If no match is found at the end of the AGI test, conclude that the supporting node implements Pull Mode. [The AGI test is illustrated in Figure 22.](04.63.11-controller-guidelines.md#463112-pushpull-mode-discovery) + +![Figure 22, Push/Pull node discovery, AGI table probing](assets/img-0f5e748af7.png) + +If the supporting node does not support the AGI Command Class, proceed with the following Notification Command Class test: + +1. Discover the list of supported Notification Types by issuing a Notification Supported Get Command. 2. For each supported Notification Type, query the supported Events/States via the Event Supported Get Command. 3. Set the status of one of the Supported Notification Types at the target node using a Notification Set Command with the following values: a. Notification Type = (a supported type discovered in step 1) b. Notification Status = 0xFF 4. Issue a Notification Get Command with the following values: a. Notification Type = (Same as step 3.a). b. Notification Event = (a supported Event/State discovered in step 2). 5. The supporting node returns a Notification Report Command. a. If the Notification Status is 0xFF, the target node implements Push Mode b. If the Notification Status is 0xFE or 0x00, the target node implements Pull Mode c. If the target node did not return a report within 10 seconds, it implements Pull Mode + +[The Notification Command Class test is illustrated in Figure 23.](04.63.11-controller-guidelines.md#463112-pushpull-mode-discovery) + +![Figure 23, Push/Pull node discovery, Notification Command Class test](assets/img-5e2a35351b.png) + +## 4.63.11.3 Unknown Notifications + +A controlling node SHOULD implement the capability to update its Notifications list, so that new [Notifications added in [18] are not presented as unknown. If a controlling node receives an unknown](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) Notification, it SHOULD allow the user to assign a free-text description to that Notification. + +It is RECOMMENDED to treat an unknown Notification as its own state variable. + +## 4.63.11.4 State idle + +A controlling node receiving a “State idle” Notification for an event or state of which the “State idle” [Notification does not apply (e.g. the “heartbeat” event) SHOULD ignore the Notification. Refer to [18] for](../04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) state variables to which the “State idle” notification applies. + +It is not mandatory for nodes supporting Notification Command Class, version 7 or older to send a “State idle” Notification for returning a state variable to idle. Thus, there is a risk that a “State idle” is never sent. A controlling node SHOULD NOT use timeouts to consider a state variable to be idle for example 5 minutes after the last received Notification. It MAY allow the user to mark states variables as idle. + +## 4.63.11.5 Parameter encapsulation + +A node implementing version 5 or older MAY use the following parameter encapsulation format: (User ID, User Code Report Command) instead of (User Code Report Command). + +A controlling node SHOULD accept the User Code Report Event Parameter with a User ID byte prefixed at the beginning of the Notification Event Parameter for backwards compatibility. A controlling node can detect the beginning of the User Code Report by finding the following consecutive bytes: {byte x=, byte x+1 = }. COMMAND_CLASS_USER_CODE USER_CODE_REPORT + +## 4.63.11.6 Controlling Push Mode Sensors + +The following sections present guidelines for controlling Push sensors nodes. + +4.63.11.6.1 Notification Get Command This command MAY be used at the initial node interview or for checking if unsolicited transmissions are enabled for a specified Notification Type. This command cannot be used to query what state is currently active at the receiving node. + +Below are recommendations for what values controlling nodes should set in the fields of this command. + +Notification Type (8 bits) + +A controlling node SHOULD set this field to a Notification Type supported by the receiving node A controlling node SHOULD NOT set the Notification Type field to 0xFF. + +Earlier specification text mandated that Push nodes return an answer to Notification Get (Type=0xFF, Event/State=0x00), i.e. not specifying an actual event type, without clearly describing what the required response is. + +Notification Event / State (8 bits) + +A controlling node SHOULD set this field to 0x00. + +4.63.11.6.2 Enabling/disabling Notification Types [Push node notifications via the Association Groups can be enabled or disabled. Figure 24 shows an](04.63.11-controller-guidelines.md#463116-controlling-push-mode-sensors) example for enabling/disabling unsolicited messages for a Notification Type. + +[Figure 24 assumes that the controlling node is the Lifeline Association Group (or other Association](04.63.11-controller-guidelines.md#463116-controlling-push-mode-sensors) Group sending Notification Report) destination. + +![Figure 24, Enabling/Disabling events from a push node](assets/img-ac16ca2e4f.png) + +## 4.63.11.7 Controlling Pull Mode Sensors + +The following sections present guidelines for controlling Pull sensors nodes. + +4.63.11.7.1 Notification Get Command This command is used to retrieve the next Notification from the receiving node’s queue. Below are recommendations for what values controlling nodes should set in the fields of this command. + +Notification Type (8 bits) + +A sending node SHOULD set the Notification Type field to 0xFF. + +Earlier specification text suggested that Pull nodes must not ignore this command if the Notification Type is set to a supported type; rather than 0xFF. Therefore, Pull sensors MAY respond to a Notification Get for a supported Notification type by retrieving the next notification in the queue matching the specified Notification Type. + +Notification Event /State (8 bits) + +This field SHOULD be set to 0x00. A receiving node will have an unpredictable behavior if this field is set to a supported Event. + +4.63.11.7.2 Detecting and clearing persistent notifications. It is OPTIONAL for Pull nodes to specify a sequence number in notifications. + +A controlling node receiving twice the same Notification with identical sequence number SHOULD [consider the Notification as persistent. An example is given in Figure 25.](04.63.11-controller-guidelines.md#463117-controlling-pull-mode-sensors) + +![Figure 25, detecting and clearing persistent notifications, identical sequence numbers](assets/img-68e758a97d.png) + +Due to unclear specification text, sensors may issue persistent Notifications without a sequence number field or with a new sequence number every time. Therefore, a controlling node SHOULD consider an notification to be persistent if it receives the same Notification 5 times or more. An example is given in [Figure 26.](04.63.11-controller-guidelines.md#463117-controlling-pull-mode-sensors) + +![Figure 26, detecting and clearing persistent notifications with incremental sequence numbers](assets/img-0546536017.png) + +4.63.11.7.3 Status and queue empty A controlling node can stop issuing Notification Get Commands when receiving a Queue empty [notification (0xFE). Illustration is given in Figure 27.](04.63.11-controller-guidelines.md#463117-controlling-pull-mode-sensors) + +All fields following the Status field MAY be omitted in the Notification Report if it advertises a Status of 0xFE (queue empty). + +![Figure 27, Pull node event retrieval until receiving queue empty](assets/img-ec0eea3305.png) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/index.md b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/index.md new file mode 100644 index 0000000..dbaf7a9 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.63-notification-command-class-version-3-8/index.md @@ -0,0 +1,30 @@ + +# 4.63 Notification Command Class, version 3-8 + +THIS COMMAND CLASS VERSIONS 3-7 HAVE BEEN DEPRECATED + +A device MAY implement version 3 to 7, but it is RECOMMENDED that new implementations comply with Notification Command Class, version 8 + +The Notification Command Class is used to advertise events or states, such as movement detection, door open/close or system failure. The Notification Command Class supersedes the Alarm Command Class. + +[Controller designers should pay particular attention to sections 4.63.1 Terminology and](04.63.01-terminology.md#4631-terminology) [4.63.11 Controller guidelines.](04.63.11-controller-guidelines.md#46311-controller-guidelines) + +## Contents + +- [4.63.1 Terminology](04.63.01-terminology.md) +- [4.63.2 Compatibility considerations](04.63.02-compatibility-considerations.md) +- [4.63.3 Interoperability considerations](04.63.03-interoperability-considerations.md) +- [4.63.4 Notification Set Command](04.63.04-notification-set-command.md) +- [4.63.5 Notification Get Command](04.63.05-notification-get-command.md) +- [4.63.6 Notification Report Command](04.63.06-notification-report-command.md) +- [4.63.7 Notification Supported Get Command](04.63.07-notification-supported-get-command.md) +- [4.63.8 Notification Supported Report Command](04.63.08-notification-supported-report-command.md) +- [4.63.9 Event Supported Get Command](04.63.09-event-supported-get-command.md) +- [4.63.10 Event Supported Report Command](04.63.10-event-supported-report-command.md) +- [4.63.11 Controller guidelines](04.63.11-controller-guidelines.md) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.64-prepayment-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.64-prepayment-command-class-version-1.md new file mode 100644 index 0000000..5858210 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.64-prepayment-command-class-version-1.md @@ -0,0 +1,141 @@ + +# 4.64 Prepayment Command Class, version 1 + +The Prepayment Command Class defines the Commands necessary to implement a Z-Wave encapsulation of Prepayment data and to distribute prepayment information between devices + +## 4.64.1 Prepayment Balance Get Command + +This command is used to request the balance of the Prepayment. + +The Prepayment Balance Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PREPAYMENT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PREPAYMENT BALANCE GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Balance Type | | | | | | | Reserved | | | | | | | | | | | | | | | | | + +Balance Type (2 bits) + +The field specifies which balance type is requested in the response report. The available balance types [may be requested using the Prepayment Supported Get Command.](04.64-prepayment-command-class-version-1.md#4643-prepayment-supported-get-command) + +Table 90, Prepayment Balance Get::Balance Type encoding + +| | Value | | | Balance Type | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Utility Balance | | | +| 0x01 | | | Monetary Balance | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +## 4.64.2 Prepayment Balance Report Command + +This command is used to report the current balances. + +The report includes the following main elements: + + Balance  Debt  Emergency Credit + +The elements MAY be given in monetary values or in utility units depending on the Balance Type field. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PREPAYMENT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PREPAYMENT BALANCE REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Balance Type | | | | | | Meter type | | | | | | | | | | | | | | | | | | +| Balance Precision | | | | | | | | | Scale | | | | | | | | | | | | | | | +| Balance Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Balance Value 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Balance Value 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Balance Value 4 | | | | | | | | | | | | | | | | | | | | | | | | +| Debt Precision | | | | | | | | | Reserved | | | | | | | | | | | | | | | +| Debt 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Debt 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Debt 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Debt 4 | | | | | | | | | | | | | | | | | | | | | | | | +| Emer. Credit Precision | | | | | | | | | Reserved | | | | | | | | | | | | | | | +| Emer. Credit 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Emer. Credit 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Emer. Credit 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Emer. Credit 4 | | | | | | | | | | | | | | | | | | | | | | | | +| Currency 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Currency 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Currency 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Debt Recovery Percentage | | | | | | | | | | | | | | | | | | | | | | | | + +Balance Type (2 bits) + +The field specifies which type of balance is given in the report. + +[All available Balance Types may be found in the section 4.64.1 Prepayment Balance Get Command.](04.64-prepayment-command-class-version-1.md#4641-prepayment-balance-get-command) + +Meter Type (6 bits) + +Meter Type specifies the type of metering device the command originates. This field MUST be encoded [according to Table 66.](04.52-meter-table-monitor-command-class-version-1/04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Scale (5 bits) + +The Scale used to indicate the scale (unit) of the balance, debt and emergency credit value in the report. Scale field only used for a report of type “Utility Balance”, for other reports set the scale to 0x1F. The Scale parameter is of the variable type Meter Scale [; refer to 4.52.13 Meter Table Current Data Report](04.52-meter-table-monitor-command-class-version-1/04.52.13-meter-table-current-data-report-command.md#45213-meter-table-current-data-report-command) Command. Currency (3 bytes) + +This field advertises the currency code. Reports of the type “Monetary Balance” MUST advertise currency codes complying with ISO 4217. Other report types MUST advertise a currency code of “XXX”. + +Table 91, Prepayment Balance Report::Currency examples + +| | Currency Code | | | Currency 1 | | | Currency 2 | | | Currency 3 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Pound sterling (ISO 4217) | | | G | | | B | | | P | | | +| US Dollar (ISO 4217) | | | U | | | S | | | D | | | +| No Currency | | | X | | | X | | | X | | | + +Balance, Debt and Emergency Credit Precision (3 bits) + +The precision field describes what the precision of the value is. The number indicates the number of decimals. The decimal value 1025 with precision 2 is therefore equal to 10.25. + +Balance, Debt and Emergency Credit (32 bits) + +The Balance, Debt and Emergency Credit fields MUST be encoded as 32-bit signed integers. The first [byte MUST carry most significant byte. Table 10 shows signed decimal values together with their](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) hexadecimal equivalents. + +Debt Recovery Percentage (8 bits) + +The Debt Recovery Percentage indicates the percentage of the payment that is for debt recovery. This can take the value from 0 – 50%, the value is always given with a precision of 0 decimal places. The value 0xFF indicates that this field is unspecified. + +This field is only used for only used for a report of type “Monetary Balance”. For other reports this field MUST be set to 0xFF (unspecified). + +## 4.64.3 Prepayment Supported Get Command + +The Prepayment Supported Get Command is used to request type of Balance Reports that are available in the device. + +The Prepayment Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PREPAYMENT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PREPAYMENT SUPPORTED GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.64.4 Prepayment Supported Report Command + +The Prepayment Supported Report Command reports the types of Balance Reports that are available in the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PREPAYMENT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = Command = PREPAYMENT SUPPORTED REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Bit Mask Balance Types Supported | | | | | | | | | | | | + +Bit Mask - Balance Types Supported (8 bits) + +The Bit Mask - Balance Types Supported byte describes the type of Balance Reports that are available in the device. + +Bit 0 in Bit Mask is used to indicate if the Balance Report Type “Utility Balance” is supported, 0 indicating not supported and 1 indicating supported. Bit 1 in the Bit Mask is used to indicate if the Balance Report Type “Monetary Balance” is available in the device, 0 indicating not supported and 1 indicating supported. + +[All available Balance Types may be found in the section 4.64.1 Prepayment Balance Get Command.](04.64-prepayment-command-class-version-1.md#4641-prepayment-balance-get-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.65-prepayment-encapsulation-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.65-prepayment-encapsulation-command-class-version-1.md new file mode 100644 index 0000000..e11024a --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.65-prepayment-encapsulation-command-class-version-1.md @@ -0,0 +1,26 @@ + +# 4.65 Prepayment Encapsulation Command Class, version 1 + +The Prepayment Encapsulation Command Class is used to smartcard preinstalled security mechanisms. + +## 4.65.1 Prepayment Encapsulation Command + +This command is used to encapsulate Smart card related data communication (e.g. between a Card reader and Meter), allowing the smartcard preinstalled security mechanisms to be applied transparently to Z-Wave. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PREPAYMENT ENCAPSULATION _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = CMD ENCAPSULATION _ | | | | | | | | | | | | | | | | | | | | | | | | +| Data 1 | | | | | | | | | | | | | | | | | | | | | | | | +| ... | | | | | | | | | | | | | | | | | | | | | | | | +| Data N | | | | | | | | | | | | | | | | | | | | | | | | + +Data (N bytes) + +This field contains prepayment smart card data. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.66-proprietary-command-class-version-1-deprecated.md b/docs/specs/command-class-specification/04-command-class-definitions/04.66-proprietary-command-class-version-1-deprecated.md new file mode 100644 index 0000000..bd9e025 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.66-proprietary-command-class-version-1-deprecated.md @@ -0,0 +1,66 @@ + +# 4.66 Proprietary Command Class, version 1 [DEPRECATED] + +THIS COMMAND CLASS HAS BEEN DEPRECATED + +A device MAY implement this command class, but it is RECOMMENDED that new implementations use the Manufacturer Proprietary Command Class. If implementing this command class, it is RECOMMENDED that the Manufacturer Proprietary Command Class is also implemented. + +The Proprietary Command Class is used to transfer data between devices. The data content MUST be vendor specific and commands MUST NOT provide any value-add with respect to the Home Automation application in general. + +## 4.66.1 Proprietary Set Command + +This command is used to transfer data to a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PROPRIETARY _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PROPRIETARY SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Data 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Data N | | | | | | | | | | | | | | | | | | | | | | | | + +Data (N bytes) + +The data fields may be used to set various data in the device. The number of data fields transmitted MUST be determined from the length field in the frame. + +## 4.66.2 Proprietary Get Command + +This command is used to request data from a device. + +The Proprietary Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PROPRIETARY _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PROPRIETARY GET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Data 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Data N | | | | | | | | | | | | | | | | | | | | | | | | + +Data (N bytes) + +Refer to explanation under the Proprietary Set Command. + +## 4.66.3 Proprietary Report Command + +This command is used to retrieve various data from a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PROPRIETARY _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PROPRIETARY REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Data 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Data N | | | | | | | | | | | | | | | | | | | | | | | | + +Data (N bytes) + +Refer to explanation under the Proprietary Set Command. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.67-protection-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.67-protection-command-class-version-1.md new file mode 100644 index 0000000..761fd7e --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.67-protection-command-class-version-1.md @@ -0,0 +1,63 @@ + +# 4.67 Protection Command Class, version 1 + +The Protection Command Class version 1 used to protect a device against unintentional control by e.g. a child. + +## 4.67.1 Protection Set Command + +This command is used to set the protection state in a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PROTECTION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PROTECTION SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Protection State | | | | | | | | | | | | | | | | | | | | | | | | + +Protection State (8 bits) + +The Protection State field used to set the protection state of the device. + +Table 92, Protection Set::Protection State encoding + +| | Protection State | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Unprotected - The device is not protected, and may be operated normally via the user interface. | | | +| 0x01 | | | Protection by sequence - The device is protected by altering the way the device normally is operated into a more complicated sequence of actions, e.g. if a device normally is controlled by a single press of a button on the device it might be changed to require 3 rapid presses on a button to control it. | | | +| 0x02 | | | No operation possible - It is not possible at all to control a device directly via the user interface. | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Control via Z-Wave is always possible independently of the protection state. + +## 4.67.2 Protection Get Command + +This Command is used to request the protection state from a device. + +The Protection Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PROTECTION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PROTECTION GET _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.67.3 Protection Report Command + +This command is used to report the protection state of a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PROTECTION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PROTECTION REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Protection State | | | | | | | | | | | | | | | | | | | | | | | | + +Protection State (8 bits) + +Refer to explanation under Protection Get Command. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.68-protection-command-class-version-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.68-protection-command-class-version-2.md new file mode 100644 index 0000000..61d751e --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.68-protection-command-class-version-2.md @@ -0,0 +1,214 @@ + +# 4.68 Protection Command Class, version 2 + +The Protection Command Class version 2 is extended to specify whether a device may be controlled via RF Commands or not. When a video recorder is powered by an outlet that can be controlled by RF the user would like to prevent the video recorder from being turned off when it is recording her/his favorite show. In this case the Protection Command Class version 2 may be used to protect the outlet from being turned off by setting the outlet in “No RF Control” state. + +The following Commands have been added or changed in version 2. The Commands not mentioned remain unchanged. + +This Command Class is intended for convenience applications. The Command Class SHOULD NOT be used for safety critical applications. + +## 4.68.1 Protection Set Command + +This command is used to set the protection state in a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PROTECTION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PROTECTION SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Local Protection State | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | RF Protection State | | | | | | | | | | | | + +Local Protection State (4 bits) + +The Local Protection State field used to set the protection state of the device. + +Table 93, Protection Set::Local Protection State encoding + +| | Local Protection | | Description | +| --- | --- | --- | --- | +| | State | | | +| 0 | | | Unprotected - The device is not protected, and may be operated normally via the user interface. | +| 1 | | | Protection by sequence - The device is protected by altering the way the device normally is operated into a more complicated sequence of actions, e.g. if a device normally is controlled by a single press of a button on the device it might be changed to require 3 rapid presses on a button to control it. | +| 2 | | | No operation possible - It is not possible at all to control a device directly via the user interface. | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. Note: Local Protection can only protect a device from “normal operation”. This means only the operation that is intended by the application of the device. It is NOT allowed to protect the device from network functionalities. The device cannot be protected from being put into learn mode nor from sending out the NIF. + +RF Protection State (4 bits) The RF Protection State field used to set the RF protection state of the device. In the case where a device set into a RF Protection State which instructs the device not to answer to a “normal operation” Command, the device MUST return the Application Rejected Request Command (Status = 0) of the Application Status Command Class. Refer to the Application Status Command Class. + +Table 94, Protection Set::RF Protection State + +| | RF Protection | | Description | +| --- | --- | --- | --- | +| | State | | | +| 0 | | | Unprotected - The device MUST accept and respond to all RF Commands. | +| 1 | | | No RF control - all runtime Commands are ignored by the device. The device MUST still respond with status on requests. | +| 2 | | | No RF response at all. The device will not even reply to status requests. | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. Note: – It is only possible to un-protect the device with the Protection Set Command. It is not allowed ignore Protection Commands. If a device is excluded from the network, the protection states MUST be reset. + +## 4.68.2 Protection Report Command + +This command is used to report the protection state of a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PROTECTION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PROTECTION REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Local Protection State | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | RF Protection State | | | | | | | | | | | | + +[For field description, refer to 4.68.1 Protection Set Command.](04.68-protection-command-class-version-2.md#4681-protection-set-command) + +## 4.68.3 Protection Supported Get Command + +This command is used to query supported protection capabilities. + +The Protection Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PROTECTION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PROTECTION SUPPORTED GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.68.4 Protection Supported Report Command + +This command is used to advertise supported protection capabilities. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PROTECTION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PROTECTION SUPPORTED REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | Exclusive Control | | | Timeout | | | +| Local Protection State Byte 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Local Protection State Byte 2 | | | | | | | | | | | | | | | | | | | | | | | | +| RF Protection State Byte 1 | | | | | | | | | | | | | | | | | | | | | | | | +| RF Protection State Byte 2 | | | | | | | | | | | | | | | | | | | | | | | | + +Local Protection State Byte (2 bytes) + +[The list of all Local Protection States may be found in section 4.68.1. The two bytes MUST be interpreted](04.68-protection-command-class-version-2.md#4681-protection-set-command) as bit masks where byte 1 bit 0 represent Local Protection State 0, byte 1 bit 1 represent Protection State 1, byte 2 bit 0 represent Protection State 8 etc. + +RF Protection State Byte (2 bytes) + +[The list of all RF Protection States may be found in section 4.68.1. The two bytes MUST be interpreted](04.68-protection-command-class-version-2.md#4681-protection-set-command) as bit masks where byte 1 bit 0 represent RF Protection State 0, byte 1 bit 1 represent Protection State 1, byte 2 bit 0 represent Protection State 8 etc. + +Exclusive Control (1 bit) + +When this bit is set to 1 the device support Exclusive Control. When Exclusive Control is supported the device MUST support the Commands Protection Exclusive Control Set, Get and Report described below. + +Timeout (1 bit) + +When this bit is set to 1 the device supports a timeout for RF Protection State. When the timeout is supported the device MUST support the Commands Protection Timeout Set, Get and Report described below. + +## 4.68.5 Protection Exclusive Control + +The Protection Exclusive Control is an optional feature. The Commands in this chapter can only be implemented if the device supporting Protection Command Class version 2 announces support for Exclusive Control in the Protection Supported Report Command. + +### 4.68.5.1 Protection Exclusive Control Set Command + +This command is used to set the NodeID of a Z-Wave device that can override the protection state in a protected device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PROTECTION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PROTECTION EC SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| NodeID | | | | | | | | | | | | | | | | | | | | | | | | + +NodeID + +The NodeID that has exclusive control can override the RF protection state of the device and can control it regardless of the protection state. Commands from any other nodes in the network may be restricted by the RF protection state. In that case, the Application Rejected Request Command MUST be returned. + +All of the Protection Command Class commands will be accepted and processed regardless of whether or not a node has exclusive control. + +Factory default setting of the NodeID for exclusive control MUST be set to 0. To reset the exclusive control state in a device an Exclusive Control Set Command with NodeID 0 as parameter MUST be send to the device. + +### 4.68.5.2 Protection Exclusive Control Get Command + +This command is used to request a Protection Exclusive Control Report Command from the device. + +The Protection Exclusive Control Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PROTECTION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PROTECTION EC GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +### 4.68.5.3 Protection Exclusive Control Report Command + +This command is used to return the NodeID of a Z-Wave device that has exclusive control over this device in protection mode. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PROTECTION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PROTECTION EC REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| NodeID | | | | | | | | | | | | | | | | | | | | | | | | + +NodeID + +[See description under the Protection Exclusive Control Set Command section 4.68.5.1.](04.68-protection-command-class-version-2.md#46851-protection-exclusive-control-set-command) + +## 4.68.6 Protection Timeout + +The Protection Timeout is an optional feature. The Commands in this section MAY be implemented if the device supporting Protection Command Class version 2 announces support for Timeout in the Protection Supported Report Command. + +### 4.68.6.1 Protection Timeout Set Command + +This command is used to set the timeout for protection mode in a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PROTECTION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PROTECTION TIMEOUT SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Timeout | | | | | | | | | | | | | | | | | | | | | | | | + +Timeout + +The timeout describes the time that a device MUST remain in RF Protection mode. Factory default setting for the Timeout parameter MUST be 0x00. This field MUST be encoded according [to Table 95.](04.68-protection-command-class-version-2.md#46861-protection-timeout-set-command) + +Table 95, Protection Timeout Set::Timeout encoding + +| | Timeout | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | No timer is set. All “normal operation” Commands MUST be accepted. | | | +| 0x01-0x3C | | | Timeout is set from 1 second (0x01) to 60 seconds (0x3C) in 1-second resolution. | | | +| 0x41-0xFE | | | Timeout is set from 2 minutes (0x41) to 191 minutes (0xFE) in 1-minute resolution. | | | +| 0xFF | | | No Timeout – The Device will remain in RF Protection mode infinitely. | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +### 4.68.6.2 Protection Timeout Get Command + +This command is used to request a Protection Timeout Report Command from the device. + +The Protection Timeout Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PROTECTION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PROTECTION TIMEOUT GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +### 4.68.6.3 Protection Timeout Report Command + +This command is used to return the remaining time that a device will remain in protection mode. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS PROTECTION _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = PROTECTION TIMEOUT REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Timeout | | | | | | | | | | | | | | | | | | | | | | | | + +Timeout + +[This field indicates the remaining timeout set in the Node. It MUST be encoded as described in Table 95](04.68-protection-command-class-version-2.md#46861-protection-timeout-set-command) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.69-pulse-meter-command-class-version-1-deprecated.md b/docs/specs/command-class-specification/04-command-class-definitions/04.69-pulse-meter-command-class-version-1-deprecated.md new file mode 100644 index 0000000..94cee35 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.69-pulse-meter-command-class-version-1-deprecated.md @@ -0,0 +1,44 @@ + +# 4.69 Pulse Meter Command Class, version 1 [DEPRECATED] + +THIS COMMAND CLASS HAS BEEN DEPRECATED + +A device MAY implement this command class, but it is RECOMMENDED that new implementations use the Meter Command Class. If implementing this command class, it is RECOMMENDED that the Meter Command Class is also implemented. + +The Pulse Meter Command Class defines the Commands necessary to implement the pulse meter functionality. The Pulse Meter Command Class is intended for all kinds of meters that generate pulses, such as gas and water meters. + +## 4.69.1 Pulse Meter Get Command + +This command is used to request the number of pulses that has been counted. + +The Pulse Meter Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER PULSE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER PULSE GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.69.2 Pulse Meter Report Command + +This command is used to report the number of pulses detected. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS METER PULSE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = METER PULSE REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Pulse Count 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Pulse Count 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Pulse Count 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Pulse Count 4 | | | | | | | | | | | | | | | | | | | | | | | | + +Pulse Count (32 bits) + +The Pulse Count field contains the number of pulses generated by the meter. The first byte is the most significant byte. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.70-rate-table-configuration-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.70-rate-table-configuration-command-class-version-1.md new file mode 100644 index 0000000..0c31232 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.70-rate-table-configuration-command-class-version-1.md @@ -0,0 +1,150 @@ + +# 4.70 Rate Table Configuration Command Class, version 1 + +The Rate Table Configuration Command Class defines the parameter sets for a range of rates. + +The Rate Table configuration commands are separated for the Rate Table monitoring commands in the rate Table Monitor Command Class, allowing the classes to be optionally supported at different Z-Wave security levels. + +Every rate is described as a combination of time, maximum consumption, maximum demand and DCP Rate ID. + + Time: Time of day. E.g. 7.15am to 9.20am  Maximum Consumption: E.g. 200kWh. This allows the Utility Supplier to provide special rates for ‘utility conserving’ end users.  Maximum Demand: E.g. 4000W. This allows the Utility Supplier to provide special rates for end- users which manages to keep the ‘peak’ demand under ‘control’.  DCP Rate ID: E.g. DCP Rate ID = 16. This allows the Utility Supplier to provide special rates for end-users participating in DCP event with a specific DCP Rate ID. + +## 4.70.1 Rate Table Set Command + +This command adds a rate parameter set to a given rate parameter set identifier. + +| | 7 | | | 6 | | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS RATE TBL CONFIG _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | | +| Command = RATE TBL SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Parameter Set ID | | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | Rate Type | | | | | Number of Rate Char. | | | | | | | | | | | | | | | +| Rate Character 1 | | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Character N | | | | | | | | | | | | | | | | | | | | | | | | | +| Start Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | | +| Start Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Minute 1 | | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Minute 2 | | | | | | | | | | | | | | | | | | | | | | | | | + +The following part of the command is OPTIONAL depending on the parameters supported. Use the Rate Table Supported Get Command to obtain supported parameters beside the default above. A not supported parameter is not included into the command layout. + +| Consumption Precision 1 | Consumption Scale 1 | +| --- | --- | +| Min. Consumption Value 1 | | +| Min. Consumption Value 2 | | +| Min. Consumption Value 3 | | +| Min. Consumption Value 4 | | +| Max. Consumption Value 1 | | +| Max. Consumption Value 2 | | +| Max. Consumption Value 3 | | +| Max. Consumption Value 4 | | +| Max. Demand Precision 1 | Max. Demand Scale 1 | +| Max. Demand Value 1 | | +| Max. Demand Value 2 | | +| Max. Demand Value 3 | | +| Max. Demand Value 4 | | +| DCP Rate ID | | + +Rate Parameter Set ID (8 bits) + +The Rate Parameter Set ID indicates the requested parameter set. Rate Type (2 bits) + +[Rate Type specifies the type of parameters in the report. This field MUST be encoded according to Table 58.](04.47-meter-command-class-version-2.md#4475-meter-report-command) + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Number of Rate Characters (5 bits) + +Number of characters defining the rate text (1..32). + +Rate Character (N bytes) + +The Rate character fields hold the string identifying the rate parameter set. The character presentation uses standard ASCII codes (values in the range 128..255 MUST be ignored). + +Start Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00..23) in local time. + +Start Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00..59) in local time. + +Duration Minute (16 bits) + +Specify the duration in minutes (1..1440) since the start in local time. The value 1440 indicates that the parameter set applies the entire day. + +Consumption Precision (3 bits) + +The precision field describes what the precision of the value is. The number indicates the number of decimals. The decimal value 1025 with precision 2 is therefore equal to 10.25. + +Consumption Scale (5 bits) + +The Consumption Scale used to indicate the scale (unit) is applicable for the rate. The Consumption Scale parameter is of the variable type Meter Scale [; refer to 4.52.13 Meter Table Current Data Report](04.52-meter-table-monitor-command-class-version-1/04.52.13-meter-table-current-data-report-command.md#45213-meter-table-current-data-report-command) Command. Minimum / Maximum Consumption Value (4 * 8 bits) + +The Minimum / Maximum Consumption Value are a 32 bit unsigned field. The first byte is the most significant byte. + +The Minimum / Maximum Consumption Value are used in the Rate Table when Block Tariffs are used. Block tariffs assign blocks of energy at a set cost. The billing period is defined by the Utility Supplier. + +Example of Block Tariff based Rate Table: (Two Block tariff system) + +The first block from 0 kWh to 200 kWh is charged at 2 USD/kWh and all other units consumed over 200kWh will be charged at 2.5 USD/kWh + +Rate1: Min Consumption value = 0kWh, Max Consumption Value = 200kWh Rate2: Min Consumption value = 200kWh, Max Consumption Value = 2147483648kWh + +NOTE [: The actual charge is set using the Tariff Table Configuration Command Class, version 1.](04.89-tariff-table-configuration-command-class-version-1.md#489-tariff-table-configuration-command-class-version-1) + +NOTICE: The device receiving the Rate Table Report MUST show the value even though the Scale is not supported. + +Max. Demand Precision (3 bits) + +The Maximum Demand Precision field describes what the precision of the value is. The number indicates the number of decimals. The decimal value 1025 with precision 2 is therefore equal to 10.25. + +Max. Demand Scale (5 bits) + +The Maximum Demand Scale field describes what unit is applicable for the rate. The Maximum Demand Scale parameter is of the variable type Meter Scale [; refer to 4.52.13 Meter Table Current Data Report](04.52-meter-table-monitor-command-class-version-1/04.52.13-meter-table-current-data-report-command.md#45213-meter-table-current-data-report-command) Command. + +Max. Demand Value (4 * 8 bits) + +The Maximum Demand Value is a 32 bit unsigned field. The first byte is the most significant byte. + +The maximum demand value 0xFFFFFFFF is reserved and represents an unlimited maximum demand value. + +NOTICE: The device receiving the Rate Table Report MUST show the value even though the Scale is not supported. + +DCP Rate ID (8 bits) + +The DCP Rate ID addresses the Demand Control Plan parameters, which will overrule other parameter sets defined in the Rate Table Command Class. A DCP Rate ID equal to zero disables Demand Control Plan mapping. + +## 4.70.2 Rate Table Remove Command + +This command is used to remove rate parameter set(s). + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS RATE TBL CONFIG _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = RATE TBL REMOVE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | Rate Parameter Set IDs | | | | | | | | | | | | | | | | | | +| Rate Parameter Set ID 1 | | | | | | | | | | | | | | | | | | | | | | | | +| ... | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Parameter Set ID N | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Rate Parameter Set IDs (6 bits) + +The Rate Parameter Set IDs indicates the number of rate parameter set IDs in the command. + +Rate Parameter Set ID (N bytes) + +These fields contain a list of Rate Parameter Set ID’s that should be removed from the Rate Table. All Rate Parameter Set ID’s are cleared in case no Rate Parameter Set ID’s are supplied. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.71-rate-table-monitor-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.71-rate-table-monitor-command-class-version-1.md new file mode 100644 index 0000000..0fffaab --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.71-rate-table-monitor-command-class-version-1.md @@ -0,0 +1,396 @@ + +# 4.71 Rate Table Monitor Command Class, version 1 + +The Rate Table Monitor Command Class defines the parameter sets for a range of rates. + +## 4.71.1 Rate Table Supported Get Command + +This command is used to request the number of rates and parameter sets supported by the Rate Table Command Class. + +The Rate Table Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS RATE TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = RATE TBL SUPPORTED GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.71.2 Rate Table Supported Report Command + +This command is used to advertise the number of rates and parameter sets supported. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS RATE TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = Command = RATE TBL SUPPORTED REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Rates Supported | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Set Supported Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Parameter Set Supported Bit Mask 2 | | | | | | | | | | | | | | | | | | | | | | | | + +Rates Supported (8 bits) + +Number of rates supported (1..255). + +Parameter Set Supported Bit Mask 1, 2 (16 bits) + +The Bit Mask field describes the supported parameter set in addition to the default-supported parameter set. The default parameter set comprises of Rate Parameter Set ID, Rate text, Start time and Duration. + +It is possible to extend the default parameter set as follows: + +Table 96, Rate Table Supported Report::Parameter Set Supported Bit Mask encoding + +| | Parameter | | Bit Map | Description | +| --- | --- | --- | --- | --- | +| | Set | | | | +| | Supported | | | | +| 1 | | | Bit 0 | Reserved | +| 1 | | | Bit 1 | Supports Block tariffs if the bit is 1 and the opposite if 0. Block tariffs assign blocks of energy at a set cost, for example in a two block tariff the first block say from 0 kWh to 200 kWh is charged at X currency per unit(kWh) all other units consumed over 200kWh will be charged at Y currency per unit for the billing period. | +| 1 | | | Bit 2 | Supports Maximum demand tariffs if the bit is 1 and the opposite if 0. Maximum demand tariffs are based on the maximum load that is measured for example 20kw over an averaging period. The charge is based on the max load; hence a 30kW maximum demand would be more costly than a 20kW maximum demand. | +| 1 | | | Bit 3 | Supports Subscribed demand tariffs if the bit is 1 and the opposite if 0. This type of tariff is used in France and Italy primarily; the standing charge is calculated from the maximum load, for example 10A = 10 currency/month, 20A = 20 currency / month. | +| 1 | | | Bit 4 | Supports Demand Control Plan mapping (DCP ID) if the bit is 1 and the opposite if 0. | + +All other bits are reserved and MUST be set to zero by a sending node. Reserved bits MUST be ignored by a receiving node. + +## 4.71.3 Rate Table Get Command + +This command is used to request the rate parameter set for a given rate parameter set identifier. + +The Rate Table Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS RATE TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = RATE TBL GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Parameter Set ID | | | | | | | | | | | | | | | | | | | | | | | | + +Rate Parameter Set ID (8 bits) + +The Rate Parameter Set ID addresses the wanted parameter set. The rate parameter set identifier MUST be a sequence starting from 1 to Rates Supported. + +## 4.71.4 Rate Table Report Command + +This command reports rate parameter set for a given rate parameter set identifier. + +| | 7 | | | 6 | | | | 5 | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS RATE TBL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Command = RATE TBL REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | +| Rate Parameter Set ID | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | Rate Type | | | | Number of Rate Char. | | | | | | | | | | | | | | +| Rate Character 1 | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | +| Rate Character N | | | | | | | | | | | | | | | | | | | | | | | +| Start Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | +| Start Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | +| Duration Minute 1 | | | | | | | | | | | | | | | | | | | | | | | +| Duration Minute 2 | | | | | | | | | | | | | | | | | | | | | | | + +The following part of the command is OPTIONAL depending on the parameters supported. Use the Rate Table Supported Get Command to obtain supported parameters beside the default above. A not supported parameter is removed from the command layout. + +| Consumption Precision 1 | Consumption Scale 1 | +| --- | --- | +| Min. Consumption Value 1 | | +| Min. Consumption Value 2 | | +| Min. Consumption Value 3 | | +| Min. Consumption Value 4 | | +| Max. Consumption Value 1 | | +| Max. Consumption Value 2 | | +| Max. Consumption Value 3 | | +| Max. Consumption Value 4 | | +| Max. Demand Precision 1 | Max. Demand Scale 1 | +| Max. Demand Value 1 | | +| Max. Demand Value 2 | | +| Max. Demand Value 3 | | +| Max. Demand Value 4 | | +| DCP Rate ID | | + +[Refer to description of fields under the Rate Table Set Command (section 4.70.1).](04.70-rate-table-configuration-command-class-version-1.md#4701-rate-table-set-command) + +## 4.71.5 Rate Table Active Rate Get Command + +This command is used to retrieve the rate currently active in the meter. + +The Rate Table Active Rate Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS RATE TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = RATE TBL ACTIVE RATE GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.71.6 Rate Table Active Rate Report Command + +This command is used to advertise the rate parameter set ID of the rate currently active in the meter. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS RATE TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = RATE TBL ACTIVE RATE REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Parameter Set ID | | | | | | | | | | | | | | | | | | | | | | | | + +Rate Parameter Set ID (8 bits) + +The Rate Parameter Set ID of the rate currently active in the meter. + +## 4.71.7 Rate Table Current Data Get Command + +This command is used to request a number of time stamped values (current) in physical units according to the dataset mask. + +The Rate Table Current Data Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS RATE TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = RATE TBL CURRENT DATA GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Parameter Set ID | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset Requested 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset Requested 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset Requested 3 | | | | | | | | | | | | | | | | | | | | | | | | + +Rate Parameter Set ID (8 bits) + +The Rate Parameter Set ID addresses the wanted parameter set. The rate parameter set identifier MUST be a sequence starting from 1 to Rates Supported. + +Dataset Requested (24 bits) + +The dataset requested parameter indicates which data is requested by the command. This field MUST [be encoded according to Table 68.](04.52-meter-table-monitor-command-class-version-1/04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +## 4.71.8 Rate Table Current Data Report Command + +This command is used to report a number of time stamped values (current) in physical units in the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS RATE TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = RATE TBL CURRENT DATA REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Parameter Set ID | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Month | | | | | | | | | | | | | | | | | | | | | | | | +| Day | | | | | | | | | | | | | | | | | | | | | | | | +| Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Current Precision 1 | | | | | | | | | Current Scale 1 | | | | | | | | | | | | | | | +| Current Value 1,1 | | | | | | | | | | | | | | | | | | | | | | | | +| Current Value 1,2 | | | | | | | | | | | | | | | | | | | | | | | | +| Current Value 1,3 | | | | | | | | | | | | | | | | | | | | | | | | +| Current Value 1,4 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Current Precision N | | | | | | | | | Current Scale N | | | | | | | | | | | | | | | +| Current Value N,1 | | | | | | | | | | | | | | | | | | | | | | | | +| Current Value N,2 | | | | | | | | | | | | | | | | | | | | | | | | +| Current Value N,3 | | | | | | | | | | | | | | | | | | | | | | | | +| Current Value N,4 | | | | | | | | | | | | | | | | | | | | | | | | + +Reports to Follow (8 bits) + +This value indicates how many report frames there are left, the value 0xFF means that the number of reports have not been calculated yet or that there is more than 255 reports to follow. + +Rate Parameter Set ID (8 bits) + +The Rate Parameter Set ID addresses the wanted parameter set. The rate parameter set identifier MUST be a sequence starting from 1 to Rates Supported. Dataset (24 bits) + +The dataset parameter indicates which data is included in the report. This field MUST be encoded [according to Table 68.](04.52-meter-table-monitor-command-class-version-1/04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Year (16 bits) + +Specify the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. + +Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December). A year equal to 0x0000 indicates that a accumulated value is not determined yet. + +Day (8 bits) + +Specify the day of the month between 01 and 31. + +Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00..23) in local time. + +Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00..59) in local time. + +Second Local Time (8 bits) + +Specify the number of complete seconds since the start of the minute (00..59) in local time. The value 60 used to keep UTC from wandering away is not supported. + +Precision (N * 3 bits) + +The precision field describes what the precision of the value is. The number indicates the number of decimals. The decimal value 1025 with precision 2 is therefore equal to 10.25. + +Current Scale (N*5 bits) + +The Current Scale is used to indicate the scale (unit) of the following value. This field MUST be encoded [according to Table 68.](04.52-meter-table-monitor-command-class-version-1/04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Current Value (N * 32 bits) + +The Current Value advertises a value corresponding to the Dataset Requested field of the Get Command. The field MUST be encoded as a 32-bit signed integer. The first byte (Value 1) MUST carry [most significant byte. Table 10 shows signed decimal values together with their hexadecimal equivalents.](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) + +NOTICE: The device receiving the Rate Table Current Data Report MUST show the value even though the Scale is not supported. + +## 4.71.9 Rate Table Historical Data Get Command + +This command is used to request a number of time stamped values (historical) in physical units according to rate type, dataset mask and time interval. + +The Rate Table Historical Data Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS RATE TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = RATE TBL HISTORICAL DATA GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Maximum Reports | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Parameter Set ID | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset Requested 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset Requested 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset Requested 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Start Month | | | | | | | | | | | | | | | | | | | | | | | | +| Start Day | | | | | | | | | | | | | | | | | | | | | | | | +| Start Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Start Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Start Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Month | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Day | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | + +Maximum Reports (8 bits) + +The maximum reports parameter is used to indicate the maximum number of reports to return based on the get. Reports are always returned with the most recently recorded value first. If set to 0x00 the meter will return all reports based on the request. + +Rate Parameter Set ID (8 bits) + +The Rate Parameter Set ID addresses the wanted parameter set. The rate parameter set identifier MUST be a sequence starting from 1 to Rates Supported. + +Dataset Requested (24 bits) + +The dataset requested parameters indicate data requested. This field MUST be encoded according to [Table 68.](04.52-meter-table-monitor-command-class-version-1/04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Start/Stop Year (16 bits) + +Specify the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. + +Start/Stop Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December). A year equal to 0x0000 indicates that an accumulated value is not determined yet. + +Start/Stop Day (8 bits) + +Specify the day of the month between 01 and 31. + +Start/Stop Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00..23) in local time. + +Start/Stop Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00..59) in local time. + +Start/Stop Second Local Time (8 bits) + +Specify the number of complete seconds since the start of the minute (00..59) in local time. The value 60 used to keep UTC from wandering away is not supported. + +## 4.71.10 Rate Table Historical Data Report Command + +This command is used to report a number of time stamped values (historical) in physical units in the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS RATE TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = RATE TBL HISTORICAL DATA REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Parameter Set ID | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Dataset 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Month | | | | | | | | | | | | | | | | | | | | | | | | +| Day | | | | | | | | | | | | | | | | | | | | | | | | +| Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Precision 1 | | | | | | | | | Historical Scale 1 | | | | | | | | | | | | | | +| | Historical Value 1,1 | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value 1,2 | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value 1,3 | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value 1,4 | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Precision N | | | | | | | | | Historical Scale N | | | | | | | | | | | | | | +| | Historical Value N,1 | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value N,2 | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value N,3 | | | | | | | | | | | | | | | | | | | | | | | +| | Historical Value N,4 | | | | | | | | | | | | | | | | | | | | | | | + +Reports to follow (8 bits) + +This value indicates how many report frames there are left, the value 0xFF means that the number of reports have not been calculated yet or that there is more than 255 reports to follow. + +Rate Parameter Set ID (8 bits) + +The Rate Parameter Set ID addresses the wanted parameter set. The rate parameter set identifier MUST be a sequence starting from 1 to Rates Supported. Dataset (24 bits) + +The dataset parameter indicates which data is included in the report. This field MUST be encoded [according to Table 68.](04.52-meter-table-monitor-command-class-version-1/04.52.06-meter-table-capability-report-command.md#4526-meter-table-capability-report-command) + +Year 1, 2 (16 bits) + +Specify the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. + +Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December). A year equal to 0x0000 indicates that a accumulated value is not determined yet. + +Day (8 bits) + +Specify the day of the month between 01 and 31. + +Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00..23) in local time. + +Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00..59) in local time. + +Second Local Time (8 bits) + +Specify the number of complete seconds since the start of the minute (00..59) in local time. The value 60 used to keep UTC from wandering away is not supported. + +Historical Precision (N * 3 bits) + +The Historical Precision field describes what the precision of the value is. The number indicates the number of decimals. The decimal value 1025 with precision 2 is therefore equal to 10.25. + +Historical Scale (N * 5 bits) + +The Historical Scale used to indicate the scale (unit) of the following value. The Historical Scale parameter is of the variable type Meter Scale [; refer to 4.52.13 Meter Table Current Data Report](04.52-meter-table-monitor-command-class-version-1/04.52.13-meter-table-current-data-report-command.md#45213-meter-table-current-data-report-command) Command. + +Historical Value (N * 32 bits) + +The Historical Value is a 32 bit signed field defined by dataset requested field. The first byte (Value 1) is the most significant byte. shows signed decimal values together with their hexadecimal equivalents. + +NOTICE: The device receiving the Rate Table Historical Data Report MUST show the value even though the Scale is not supported. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.72-scene-activation-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.72-scene-activation-command-class-version-1.md new file mode 100644 index 0000000..0b33365 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.72-scene-activation-command-class-version-1.md @@ -0,0 +1,50 @@ + +# 4.72 Scene Activation Command Class, version 1 + +The Scene Activation Command Class used for launching scenes in a number of actuator nodes e.g. another scene-controlling unit, a multilevel switch, a binary switch etc. + +## 4.72.1 Compatibility considerations + +A node supporting this Command Class MUST also support the Scene Actuator Configuration Command Class. + +This command class requires an initial configuration of the scenes to be launched by the Scene Actuator Configuration Set. + +Since a common identifier that is sent out, multicast addressing may be used. Multicast addressing may eliminate the potential popping effect which could be the result if individual Set Commands were send out to a large number of nodes distributed over a vast area. The multicast transmission MUST be followed by individual singlecast transmissions to ensure all the nodes have received the command. + +## 4.72.2 Scene Activation Set Command + +This command is used to activate the setting associated to the scene ID. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCENE ACTIVATION _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCENE ACTIVATION SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Scene ID | | | | | | | | | | | | | | | | | | | | | | | | +| Dimming Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Scene ID (8 bits) + +This field is used to specify the Scene ID that the receiving node MUST activate This field MUST be in the range 1..255. + +Dimming Duration (8 bits) + +This field MUST specify the time that the transition from the current level to the target level (indicated by the Scene ID) should take.. + +Supporting actuator nodes without duration capabilities MUST ignore this field. + +Supporting actuator nodes with a duration capabilities SHOULD respect the indicated dimming duration to reach the target level. + +[This field MUST be encoded according to Table 97.](04.72-scene-activation-command-class-version-1.md#4722-scene-activation-set-command) Table 97, Scene Activation Set:: Dimming Duration encoding + +| | Value | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Instantly | | | +| 0x01..0x7F | | | Obtain dimming durations from 1 second (0x01) to 127 seconds (0x7F) in 1-second resolution | | | +| 0x80..0xFE | | | Specify dimming durations from 1 minute (0x80) to 127 minutes (0xFE) in 1-minute resolution. | | | +| 0xFF | | | Specify dimming duration configured by the Scene Actuator Configuration Set and Scene Controller Configuration Set Command depending on device used. | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.73-scene-actuator-configuration-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.73-scene-actuator-configuration-command-class-version-1.md new file mode 100644 index 0000000..4aec0c1 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.73-scene-actuator-configuration-command-class-version-1.md @@ -0,0 +1,119 @@ + +# 4.73 Scene Actuator Configuration Command Class, version 1 + +The Scene Actuator Configuration Command Class is used to configure scenes settings for a node supporting an actuator Command Class, e.g. a multilevel switch, binary switch etc. + +## 4.73.1 Compatibility considerations + +A node supporting this Command Class MUST support 255 Scene IDs. Implemented Scene IDs MUST be in a consecutive range starting from 1. + +## 4.73.2 Scene Actuator Configuration Set Command + +This command is used to associate the specified scene ID to the defined actuator settings. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCENE ACTUATOR CONF _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCENE ACTUATOR CONF SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Scene ID | | | | | | | | | | | | | | | | | | | | | | | | +| Dimming Duration | | | | | | | | | | | | | | | | | | | | | | | | +| Over- ride | | | Reserved | | | | | | | | | | | | | | | | | | | | | +| Level | | | | | | | | | | | | | | | | | | | | | | | | + +Scene ID (8 bits) + +This field is used to specify the Scene ID to be associated with the current actuator settings. This field MUST be in the range 1..255. + +Dimming Duration (8 bits) + +This field MUST specify the time it MUST take to reach the target level associated to the actual Scene ID. + +A receiving node always starts from current level. The dimming duration MUST be the same independently of the number of levels to be changed. + +Supporting actuator nodes without duration capabilities MUST ignore this field. Supporting actuator nodes with duration capabilities SHOULD respect the indicated duration to reach the target level. + +[This field MUST be encoded according to Table 7.](../03-command-class-overview/03.07-common-fields-and-encoding.md#373-duration-encoding) + +Override (1 bit) + +This field is used to specify if the current actuator settings MUST be used as settings for the actual Scene ID. If this field is set to 0, the current actuator settings at the supporting nodeMUST be associated to the actual Scene ID. In this case, the Level field MUST be ignored. If this field is set to 1, the value indicated by the Level field MUST be associated to the actual Scene ID. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Level (8 bits) + +This field is used to specify the actuator setting that MUST be used as setting for the actual Scene ID. This field MUST correspond and be interpreted as the Value field of the Basic Set Command. i.e. the supporting node receiving a Scene Activation Set for the actual Scene ID specified in this command MUST react as if it had received a Basic Set Command with the Value field set to the value indicated by this field. + +## 4.73.3 Scene Actuator Configuration Get Command + +This command is used to request the settings for a given scene identifier or for the scene currently active. + +The Scene Actuator Configuration Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCENE ACTUATOR CONF _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCENE ACTUATOR CONF GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Scene ID | | | | | | | | | | | | | | | | | | | | | | | | + +Scene ID (8 bits) + +This field is used to specify the requested Scene ID settings. + +Values in the range 1..255 MUST indicate that the receiving node MUST return settings associated to the actual Scene ID.. + +The value 0 MUST indicate that the current active scene (if any). + +## 4.73.4 Scene Actuator Configuration Report Command + +This command is used to advertise the settings associated to a scene identifier. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCENE ACTUATOR CONF _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCENE ACTUATOR CONF REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Scene ID | | | | | | | | | | | | | | | | | | | | | | | | +| Level | | | | | | | | | | | | | | | | | | | | | | | | +| Dimming Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Scene ID (8 bits) + +This field is used to specify the actual Scene ID for which the settings are being advertised. + +Values in the range 1..255 MUST indicate an actual Scene ID. + +The value 0 MUST indicate that no scene is currently active at the sending node and no scene setting is advertised in this command. In this case, the Level and Dimming Duration fields SHOULD be ignored. + +Level (8 bits) + +This field is used to advertise the actuator setting that MUST be used by the node when activating the actual Scene ID. + +The value advertised by the sending node MUST correspond to the format of the Value field when returning a Basic Report Command. + +Dimming Duration (8 bits) + +This field MUST specify the time it MUST take to reach the target level associated to the actual Scene ID.. + +Supporting actuator nodes without duration capabilities MUST ignore this field and SHOULD set it to 0x00. + +Supporting actuator nodes with duration capabilities SHOULD respect the indicated duration to reach the target level. + +[This field MUST be encoded according to Table 98.](04.73-scene-actuator-configuration-command-class-version-1.md#4734-scene-actuator-configuration-report-command) Table 98, Scene Actuator Configuration Report::Dimming Duration encoding + +| | Dimming Duration | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Instantly | | | +| 0x01..0x7F | | | Dimming durations from 1 second (0x01) to 127 seconds (0x7F) in 1-second resolution | | | +| 0x80..0xFE | | | Specify dimming durations from 1 minute (0x80) to 127 minutes (0xFE) in 1-minute resolution. | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.74-scene-controller-configuration-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.74-scene-controller-configuration-command-class-version-1.md new file mode 100644 index 0000000..883f4cf --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.74-scene-controller-configuration-command-class-version-1.md @@ -0,0 +1,100 @@ + +# 4.74 Scene Controller Configuration Command Class, version 1 + +The Scene Controller Configuration Command Class is used to configure nodes launching scenes using their association groups + +## 4.74.1 Compatibility Considerations + +A node supporting this Command Class MUST support 255 scene IDs. Implemented Scene IDs MUST be in a consecutive range starting from 1. + +A node supporting this Command Class MUST support the Association Command Class, version 1 or newer. + +A node supporting this Command Class MUST issue Scene Activation Set Command via its association groups. + +## 4.74.2 Scene Controller Configuration Set Command + +This command is used to configure settings for a given physical item on the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCENE CONTROLLER CONF _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCENE CONTROLLER CONF SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Group ID | | | | | | | | | | | | | | | | | | | | | | | | +| Scene ID | | | | | | | | | | | | | | | | | | | | | | | | +| Dimming Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Group ID (8 bits) + +This field is used to specify an Association Group Identifier. + +The grouping identifier is mapped into a physical item e.g. a push button on the device in question. The grouping identifier values MUST be a sequence starting from 1. The Association Supported Groupings Get Command may be used to request the number of groupings that a node supports. + +A sending node SHOULD NOT specify Group ID 1 as it is reserved for the Lifeline association group. + +Scene ID (8 bits) + +This field is used to specify the Scene ID that MUST be associated with the actual grouping identifier. + +Values in the range 1..255 MUST indicate that the receiving node MUST associate the Scene ID and Dimming Duration values to the actual Association Group ID. The supporting node MUST set the Scene ID value indicated by this field in the Scene Activation Set Command when issuing it via the actual Group ID. + +The value 0 MUST indicate that the receiving node MUST disable an associated scene for the specified Group ID. Dimming Duration (8 bits) + +This field is used to specify what value the supporting node MUST set in the Dimming Duration field of the Scene Activation Set Command when issuing it via the actual Group ID. + +## 4.74.3 Scene Controller Configuration Get Command + +This command is used to request the settings for a given association grouping identifier or the active settings. + +The Scene Controller Configuration Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCENE CONTROLLER CONF _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCENE CONTROLLER CONF GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Group ID | | | | | | | | | | | | | | | | | | | | | | | | + +Group ID (8 bits) + +This field is used to request scene settings configured for an actual Association Group Identifier. + +Values in the range 1..255 MUST indicate the requested Group Identifier. + +The value 0 MUST indicate that the receiving node MUST return the currently active Group Identifier and Scene ID (last activated group/scene). + +A node receiving a non-supported group or having no currently active Group Identifier SHOULD return a report for Group ID 0. + +## 4.74.4 Scene Controller Configuration Report Command + +This command is used to advertise the current scene controller settings. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCENE CONTROLLER CONF _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCENE CONTROLLER CONF REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Group ID | | | | | | | | | | | | | | | | | | | | | | | | +| Scene ID | | | | | | | | | | | | | | | | | | | | | | | | +| Dimming Duration | | | | | | | | | | | | | | | | | | | | | | | | + +Group ID (8 bits) + +This field is used to advertise the actual Association Group Identifier for which the settings are being advertised. + +Scene ID (8 bits) + +This field is used to specify the Scene ID that is associated with the actual grouping identifier. + +Value in the range 1..255 MUST indicate the actual Scene ID setting for the specified grouping identifier. The value 0 MUST indicate that the Group ID/Scene ID is disabled. + +Dimming Duration (8 bits) + +This field is used to specify the Dimming Duration that is associated with the actual grouping identifier. + +If the actual Group ID/Scene ID is disabled, a sending node SHOULD set this field to 0. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.01-terminology.md b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.01-terminology.md new file mode 100644 index 0000000..bb59d9f --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.01-terminology.md @@ -0,0 +1,48 @@ + +# 4.75.1 Terminology + +A schedule or regular schedule is a delayed execution of one or more commands for a given duration. The commands used in a schedule are typically “Set” type commands, affecting actuating resources or states. + +A schedule is first created or set, meaning that an available Schedule ID is used and has been assigned a set of commands, a starting time and a duration. + +A schedule can be removed, meaning that a previously set Schedule ID is freed and the assigned commands, starting time and duration are erased. + +A schedule is active during the configured duration after its starting time. When a schedule is active, the states affected by the schedule commands are temporarily changed. When a schedule becomes inactive, the states affected by the schedule commands are restored to their previous values. + +Several schedules can overlap and be active simultaneously. + +Supporting nodes can optionally support enabling and disabling schedules. By default, a schedule is enabled when being created. When a schedule is disabled, it will never become active, even if the start time condition is met. It allows a controlling node to quickly enable/disable schedules without erasing the schedules configuration from the supporting nodes. + +When all schedules are inactive, the supporting node is said to be operating in Normal Mode. Regardless of whether any schedule is active, Normal Mode’s states are permanently affected by direct commands (issued without Schedule encapsulation). State changes triggered by schedules do not affect Normal [Mode. An illustration is given in Figure 28](04.75.01-terminology.md#4751-terminology) + +![Figure 28. Simple daily schedules (example)](assets/img-41477511d5.png) + +Direct commands affecting the states of a currently active schedule will cause those states to go back to normal mode and the corresponding normal mode states/values to be permanently changed. + +![Figure 29. Receiving a direct command during daily schedules (example)](assets/img-9c7dfcaef5.png) + +There are 2 types of special schedules. + +If a Fall Back Schedule is created, it takes over the role of the Normal Mode. The Fall Back Schedule is activated when all other schedules are inactive. Fall Back Schedule is used to define default settings or states for the normal mode + +If an Override Schedule is created, it suspends all other schedules. An override schedule may have a start time or start immediately. An override schedule may have a duration, run until stopped or run until [another regular schedule starts. An example is given in Figure 30](04.75.01-terminology.md#4751-terminology) + +![Figure 30. Daily schedules and an “Advance” Override Schedule (example)](assets/img-f87775eaf2.png) + +[An overview of the Schedule types and priorities is given in Table 99](04.75.01-terminology.md#4751-terminology) + +Table 99. Schedule CC terminology and priority + +| | Priority | | | Term | | | Description | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| (highest) | | | Direct command | | | Affects device state immediately. Permanently affects Normal Mode. | | | +| (higher) | | | Override Schedule (Schedule ID = 0xFF) | | | All other schedules are suspended as long as the override schedule is active. | | | +| (normal) | | | Regular Schedule(s) (Schedule ID in [1..Supported number of schedules]) | | | One or more schedules defining intended behavior. | | | +| (lower) | | | Fall Back Schedule (Schedule ID = 0xFE) | | | Fall Back Schedule becomes active when no other schedule is currently active. If the Fall Back Schedule is defined, Normal Mode is never reached, unless receiving direct commands | | | +| (lowest) | | | Normal Mode | | | No schedules are currently active. | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.02-interoperability-considerations.md b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.02-interoperability-considerations.md new file mode 100644 index 0000000..98935eb --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.02-interoperability-considerations.md @@ -0,0 +1,34 @@ + +# 4.75.2 Interoperability considerations + +A schedule causes a temporary state change that only applies to the duration of the schedule. The state value(s) of the Normal Mode MUST NOT be affected by any command executed as part of a schedule. + +The state value(s) of the Normal Mode MUST be restored when the affecting Schedule become inactive. + +Schedules are set with a start time, which requires the supporting node to be aware of the current date and/or time. It is RECOMMENDED to support the Clock Command Class or the Time Command Class in order to allow a controlling node to verify or configure correct date/time settings at the supporting node. + +## 4.75.2.1 Override Schedule + +When the Override Schedule is active, all regular schedules MUST be suspended. When the Override Schedule ends, all suspended schedules MUST resume the state they would have had if the Override Schedule had not been activated. + +If the Override Schedule is created with a duration type not set to Override, a receiving node SHOULD respect the specified duration for the Override Schedule. A supporting node MUST respect the specified duration for all regular schedules. + +## 4.75.2.2 Fall Back Schedule + +If no Fall Back Schedule is set, a supporting node MUST return to Normal Mode when no schedule is currently active. + +If a Fall Back Schedule is set, a supporting node MUST: + + Activate the Fall Back Schedule when no other schedule is active.  De-activate the Fall Back Schedule if any other schedule becomes active.  Direct commands state changes MUST be active until the start of a new schedule affecting the same state values. + +## 4.75.2.3 Multi Channel considerations + +A Multi Channel device may support different schedule types and command classes for each Multi Channel End Point. An example is a central heating boiler with a thermostat for room heating and another thermostat for water heating. Each system may implement regular weekday+time schedules as well as an override schedule for manual intervention. + +In any case, it is RECOMMENDED that multi-function devices support the Multi Channel Command Class, so that each End Point supports its own scheduling functionality. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.03-schedule-supported-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.03-schedule-supported-get-command.md new file mode 100644 index 0000000..aec2c03 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.03-schedule-supported-get-command.md @@ -0,0 +1,19 @@ + +# 4.75.3 Schedule Supported Get Command + +This command is used to query the schedule functionalities supported by a node. + +The Schedule Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE SUPPORTED GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.04-schedule-supported-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.04-schedule-supported-report-command.md new file mode 100644 index 0000000..1ca8e0a --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.04-schedule-supported-report-command.md @@ -0,0 +1,165 @@ + +# 4.75.4 Schedule Supported Report Command + +This command is used to advertise the schedule functionalities supported by a node. + +| | 7 | | 6 | | | 5 | | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE SUPPORTED REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Supported Schedule IDs | | | | | | | | | | | | | | | | | | | | | | | | +| Support Enable/ Disable | | | Fall- back Support | | | | Start Time Support | | | | | | | | | | | | | | | | | +| Number of supported CC | | | | | | | | | | | | | | | | | | | | | | | | +| | Supported CC 1 | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | | Supported | | | | | +| | | | | | | | | | | | | | | | | | | | Command 1 | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Supported CC N | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | | Supported | | | | | +| | | | | | | | | | | | | | | | | | | | Command N | | | | | +| Override Support | | | Supported Override Types | | | | | | | | | | | | | | | | | | | | | + +Number of Supported Schedule IDs (8 bits) + +This field MUST advertise the number of regular Schedule IDs supported by the node. + +The implemented Schedule IDs MUST be in the range 1..[Number of Supported Schedule IDs]. i.e. a node supporting 10 regular schedules MUST accept Schedule ID values in the range 1..10. + +The following special Schedule IDs MAY also be supported by a device: + + Schedule ID = 0xFF (Override Schedule)  Schedule ID = 0xFE (Fall Back schedule) + +Special Schedule IDs MUST NOT be included in the number advertised in this field. Start Time Support (6 bits) + +This field is used to advertise the start time options supported for regular schedules by a node. + +Regular schedules MUST support the advertised start time options. The Override Schedule SHOULD support the advertised start time options. + +[This field MUST be treated as a bitmask and MUST be encoded according to Table 100](04.75.04-schedule-supported-report-command.md#4754-schedule-supported-report-command) + +Table 100. Start Time Support encoding + +| | Bit | | | Indicates support for | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0 | | | Start now. Refer to 4.75.4.1 | | | 1 | | | +| 1 | | | Start Hour and Minute. Refer to 4.75.4.2 | | | 1 | | | +| 2 | | | Calendar time. Refer to 4.75.4.3 | | | 1 | | | +| 3 | | | Weekdays. Refer to 4.75.4.4 | | | 1 | | | +| 4..5 | | | Reserved | | | N/A | | | + +Each bit indicates the support for a given Start Time option. + +The value 1 MUST indicate that the node supports the corresponding start time option. The value 0 MUST indicate that the node does not support the corresponding start time option. + +While support is advertised as a bitmask, the actual functionality is triggered by different combinations of Schedule Set start time fields. The following subsections outline the mandatory supported combinations when advertising support for the corresponding option. + +## 4.75.4.1 Start Time option: Start now + +The start now option is used to make a configured schedule start immediately (upon reception of the Schedule Set Command). + +A node that supports the start now option, MUST support the creation of a schedule starting immediately when all start time fields are left unspecified. + +## 4.75.4.2 Start Time option: Hour and Minute + +The start hour and minute option is used to make a schedule start at a specified time of the day. + +If Start Hour and Start Minute are specified, node supporting this option MUST activate the schedule at the specified start time. + +A node supporting the Hour and Minute start option MUST support the creation of a schedule with the following start time fields’ combination: + + Every day @ Hour:Minute (YYMMDD = 0xFF, 0x00, 0x00, Weekdays = 0x00, HH:MM = Hour:Minute) + +A node that also supports the Weekdays start option MUST support the creation of a schedule with the following start time fields’ combination:  Same weekday(s) every week @ Hour:Minute (YYMMDD = 0xFF, 0x00, 0x00, Weekdays = weekdays, HH:MM = Hour:Minute) A node that also supports the Calendar Time start option MUST support the creation of a schedule with the following start time fields’ combination:  Same day every month @ Hour:Minute (YYMMDD = 0xFF, 0x00, day, Weekdays = 0x00, HH:MM = Hour:Minute) + + Same day every year @ Hour:Minute (YYMMDD = 0xFF, month, day, Weekdays = 0x00, HH:MM = Hour:Minute) + + One specific date in a specific year @ Hour:Minute (YYMMDD = year, month, day, Weekdays = 0x00, HH:MM = Hour:Minute) + +## 4.75.4.3 Start Time option: Calendar time + +The calendar time option is used to make a schedule start at a specified date. + +If Start Year, Start Month and Start Day are specified, node supporting this option MUST activate the schedule at the specified date(s). + +A node that supports the Calendar Time option MUST support the creation of a schedule with the following start time fields’ combination:  Same day every month @ 00:00 (YYMMDD = 0xFF, 0x00, day, Weekdays = 0x00, HH:MM = 0x1F, 0x3F)  Same day every year @ 00:00 (YYMMDD = 0xFF, month, day, Weekdays = 0x00, HH:MM = 0x1F, 0x3F)  One specific date in a specific year @ 00:00 (YYMMDD = year, month, day, Weekdays = 0x00, HH:MM = 0x1F, 0x3F) + +## 4.75.4.4 Start Time option: Weekday + +The start weekday option is used to make a schedule start at on specified weekdays. + +If weekdays are specified, node supporting this option MUST activate the schedule on the specified weekdays. + +A node that supports the Weekdays option MUST support the creation of a schedule with the following start time fields’ combination:  Same weekday(s) every week @ 00:00 (YYMMDD = 0xFF, 0x00, 0x00, Weekdays = weekdays, HH:MM = 0x1F, 0x3F) + +Fall Back Support (1 bit) + +This bit is used to advertise the support of the Fall Back Schedule (Schedule ID = 0xFE). + +The bit MUST be set to 1 if the node supports the Fall Back Schedule. The bit MUST be set to 0 if the node does not support the Fall Back Schedule. Support Enable/Disable (1 bit) + +This bit is used to advertise the support for enabling/disabling set/used schedules via the Schedule State Set Command. + +The bit MUST be set to 0 if the node supports enabling/disabling schedules. The bit MUST be set to 1 if the node does not support enabling/disabling schedules. + +A node that does not support enabling/disabling schedules MUST consider every set/used schedule ID as enabled. + +Number of supported CC (8 bits) + +This field MUST advertise the number of supported Command Classes advertised in this command with the Supported CC and Supported Command fields. + +The value 0xFF MUST be used if all the command classes supported by the node are also supported for scheduling. If this field is set to 0xFF: + + This command MUST NOT carry any Command Class entries (Supported CC and Supported Command fields).  The node MUST support “Get” as well as “Set” commands. (i.e. Supported Commands fields set to 0x00) + +Supported CC (N * 8 bits) + +This field is used to advertise the list of Command Classes that can be scheduled by the node. + +The length of this field MUST be according to the Number of supported CC field value. + +A sending node MUST support every Command Class advertised in this field. A sending node SHOULD NOT advertise the Supervision Command Class in this field. A sending node MUST NOT advertise the following encapsulation Command Classes: + + S0/S2 Command Class  Transport Service Command Class  Multi Channel Command Class  Multi Command Command Class Supported Command (N * 2 bits) + +This field MUST advertise the supported commands for the actual command class entry. This field MUST [comply with Table 101.](04.75.04-schedule-supported-report-command.md#47544-start-time-option-weekday) + +Table 101. Supported Command + +| | Value | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | Both Set and Get Commands are supported | | | 1 | | | +| 0x01 | | | Only Set Commands are supported | | | 1 | | | +| 0x02 | | | Only Get Commands are supported | | | 1 | | | +| 0x03 | | | Reserved | | | N/A | | | + +Certain command classes commands do not contain the string “Set” or “Get” in their name. Nodes MUST consider all commands mandating to return a response to be of type “Get” and all other commands to be of type “Set”. + +The length of this field MUST be according to the Number of supported CC field value. + +Override Support (1 bit) + +This field is used to advertise support for the Override Schedule (Schedule ID = 0xFF). + +This bit MUST be set to 1 if the node supports the Override Schedule. This bit MUST be set to 0 if the node does not support the Override Schedule. + +Supported Override Types (7 bits) + +This field is used to advertise the supported Override Schedule duration types. + +A receiving node MUST ignore this bit mask if the Override Schedule is not supported by the sending node. + +[This field MUST be treated as a bitmask and MUST be encoded according to Table 102.](04.75.04-schedule-supported-report-command.md#47544-start-time-option-weekday) + +Table 102. Schedule Supported Report::Supported Override Types encoding + +| | Bit | | | Name | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0 | | | Advance | | | The override schedule MUST run until the start of the next regular schedule. | | | 1 | | | +| 1 | | | Run forever | | | The override schedule MUST run until the schedule is removed | | | 1 | | | +| 2..6 | | | Reserved | | | Reserved | | | N/A | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.05-schedule-set-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.05-schedule-set-command.md new file mode 100644 index 0000000..96b8aab --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.05-schedule-set-command.md @@ -0,0 +1,203 @@ + +# 4.75.5 Schedule Set Command + +This command is used to create a new schedule or modify an existing schedule. This command MUST enable the schedule if a new schedule is created. This command MUST NOT change the enabled/disabled state of existing schedules. + +If the receiving node supports S0 or S2 Command Class, it MUST NOT process the schedule creation if any of the scheduled command classes is not supported at the security level of the received Schedule Set Command. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Start Month | | | | | | | | | | | | +| Reserved | | | | | | | | | | Start Day of Month | | | | | | | | | | | | | | +| Res. | | | Start Weekday | | | | | | | | | | | | | | | | | | | | | +| Duration Type | | | | | | | | | Start Hour | | | | | | | | | | | | | | | +| Reserved | | | | | | Start Minute | | | | | | | | | | | | | | | | | | +| Duration Byte 1 MSB | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Byte 2 LSB | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Cmd to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Length 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte 1 - 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte 1 - N | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Length P | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte P - 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte P - N | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. Schedule ID (8 bits) + +This field is used to indicate which Schedule ID is being set. + +Values in the range 1..[Number of supported Schedule] MUST indicate regular Schedule IDs The value 0xFE MUST indicate the Fall Back Schedule. The value 0xFF MUST indicate the Override Schedule. + +A receiving node MUST ignore this command if a non-supported Schedule ID is specified. + +If this field is set to 0xFF: + + The sending node SHOULD set the start time fields to the Start Now pattern.  The receiving node MUST respond immediately to an Override Schedule . + +If this field is set to 0xFE: + + The sending node SHOULD set the start time fields and duration fields to 0x00.  The receiving node MUST ignore the start time fields and duration fields + +## 4.75.5.1 Start time fields + +The schedule start time is defined by the following fields: + + Start Year  Start Month  Start Day of Month  Start Weekday  Start Hour  Start Minute + +[A receiving node MUST support the start time fields combinations indicated in sections 4.75.4.1, 4.75.4.2](04.75.04-schedule-supported-report-command.md#47541-start-time-option-start-now) [4.75.4.3 and 4.75.4.4 if the corresponding start time option is supported.](04.75.04-schedule-supported-report-command.md#47543-start-time-option-calendar-time) + +If none of the start time fields are specified, the schedule MUST start immediately if the start now option is supported. In this case, the schedule MUST NOT be activated again at a later time unless receiving another Schedule Set Command. + +Start Year (8 bits) + +This field is used to set the year for which the schedule is to start. This field MUST be in the range 0..99 or set to 0xFF. + +Values in the range 0..99 MUST indicate the actual year last 2 digits. A node MUST accept a value lower than the current year to allow schedules starting in the next century. + +The value 0xFF MUST be used to indicate that the start year is unspecified. + +This field MUST be ignored and treated as unspecified by a receiving node advertising no support for the Calendar time start time option in the Schedule Supported Report Command. Start Month (4 bits) + +This field is used to set the month for which the schedule is to start. This field MUST be in the range 0..12. + +Values in the range 1..12 MUST indicate the actual start month. + +The value 0x00 MUST be used to indicate that the start month is unspecified. + +This field MUST be ignored and treated as unspecified by a receiving node advertising no support for the Calendar time start time option in the Schedule Supported Report Command. + +Start Day of Month (5 bits) + +This field is used to set the day of month for which the schedule is to start. This field MUST be in the range 0..31. + +Values in the range 1..31 MUST indicate the actual start day of the month. If the specified value does not exist in the actual Year/Month tuple (28/29/30 day month), a receiving node MAY ignore this command. + +The value 0x00 MUST be used to indicate that the day of the month is unspecified. + +This field MUST be ignored and treated as unspecified by a receiving node advertising no support for the Calendar time start time option in the Schedule Supported Report Command. + +Start Weekday (7 bits) + +This field is used to set one or more weekdays for which the schedule is to start. This field MUST be [treated a as bitmask and MUST be encoded according to Table 103.](04.75.05-schedule-set-command.md#47551-start-time-fields) + +Table 103. Weekday bitmask encoding + +| | Bit | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0 | | | Monday | | | 1 | | | +| 1 | | | Tuesday | | | 1 | | | +| 2 | | | Wednesday | | | 1 | | | +| 3 | | | Thursday | | | 1 | | | +| 4 | | | Friday | | | 1 | | | +| 5 | | | Saturday | | | 1 | | | +| 6 | | | Sunday | | | 1 | | | + +The value 1 MUST indicate that the specified Schedule ID MUST start on the corresponding day. The value 0 MUST indicate that the specified Schedule ID MUST NOT start on the corresponding day. + +If any of the Start Year, Start Month or Start Day of Month field is specified, this field MUST be set to 0x00 by a sending node and MUST be ignored by a receiving node. + +This field MUST be ignored and treated as unspecified by a receiving node advertising no support for the Weekday start time option in the Schedule Supported Report Command. Start Hour (5 bits) + +This field is used to set the hour for which the schedule is to start. This field MUST be in the range 0..23 or set to 0x1F. + +Values in the range 0..23 MUST indicate the start hour of the day. + +The value 0x1F (31) MUST be used to indicate that the start hour is unspecified. + +This field MUST be ignored and treated as unspecified by a receiving node advertising no support for the hour and minute start time option in the Schedule Supported Report Command. + +Start Minute (6 bits) + +This field is used to set the minute for which the schedule is to start. This field MUST be in the range 0..59 or set to 0x3F. + +Values in the range 0..59 MUST indicate the starting minute of the schedule. + +The value 0x3F (63) MUST be used to indicate that the start minute is unspecified. + +This field MUST be ignored and treated as unspecified by a receiving node advertising no support for the hour and minute start time option in the Schedule Supported Report Command. + +## 4.75.5.2 Duration fields + +The schedule duration is defined by the following fields: + + Duration Type  Duration + +Duration Type (3 bits) + +This field is used to indicate how to interpret the duration field. This field MUST be encoded according to [Table 104.](04.75.05-schedule-set-command.md#47552-duration-fields) + +Table 104. Duration Type encoding + +| | Value | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | The duration field is expressed in Minutes | | | 1 | | | +| 0x01 | | | The duration field is expressed in Hours | | | 1 | | | +| 0x02 | | | The duration field is expressed in Days | | | 1 | | | +| 0x03 | | | Override: The duration field is indicating the Override Type. This value MUST NOT be used if the Schedule ID field is not set to 0xFF | | | 1 | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. Duration (16 bits) + +This field is used to specify the duration of the schedule being set. The Duration Type field MUST be inspected before interpreting this field. + +If the Duration Type field is not set to Override (0x03), this field MUST indicate the duration of the actual schedule. The Duration Type field indicates the unit of this field. + +If the Duration Type field is set to Override (0x03), the LSB of this field MUST be encoded according to [Table 105 and the MSB of this field MUST be set to 0x00.](04.75.05-schedule-set-command.md#47552-duration-fields) + +Table 105. Override Types duration + +| | Name | | | Duration value (LSB) | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Advance | | | 0x01 | | | The override schedule MUST run until the start of the next regular schedule. | | | 1 | | | +| Run forever | | | 0x02 | | | The override schedule MUST run until it is removed | | | 1 | | | +| Reserved | | | 0x03..0x07 | | | Reserved | | | N/A | | | + +CC:0053.01.03.11.02E Run forever 0x02 The override schedule MUST run until it is 1 + +## 4.75.5.3 Command and other fields + +Reports to Follow (8 bits) + +This field MUST be used if multiple Schedule Set commands are used to define a single schedule. + +The value MUST indicate the remaining number of Schedule Set Commands. The header bytes (Schedule ID, Start time, Duration, etc.) MUST be the same for all Schedule Set Commands. + +Number of Cmd to Follow (8 bits) + +This field is used to advertise the number of command blocks (Cmd Length/Cmd Byte fields units) included within the actual Schedule Set Command (represented by P in the command structure). + +Each command block MUST comprise the Cmd Length and Cmd Byte fields. + +If the list of scheduled commands and their payload is longer than the maximum available Z-Wave MAC frame size, multiple Schedule Set commands MUST be used to send the complete list of scheduled commands. In this case, this field MUST advertise how many commands are included in the actual/current Schedule Set Command. + +Cmd Length (8 bits) + +This field is used to indicate the length in byte of the corresponding Cmd Byte field. Cmd Byte (N bytes) + +This field is used to set the commands to be executed during the actual Schedule. + +This field MUST carry a complete command including Command Class identifier, Command identifier and the required parameter bytes. + +The length of each Cmd Byte entry MUST be according to the corresponding Cmd Length field entry. The number of Cmd Byte entries MUST be according to the Number of Cmd to Follow field. + +If a schedule includes commands mandating to return a response, responses MUST be returned to the node that has set the schedule. + +A receiving node SHOULD ignore the entire Schedule Set Command if this field carries a command not advertised as supported for scheduling in the Schedule Supported Report Command. In any case, the receiving node MUST NOT accept commands non-supported for scheduling as part of the Schedule. + +A controlling node SHOULD avoid creating conflicting schedules and a supporting node SHOULD discard a new conflicting schedule, even if the conflict is with a temporarily disabled schedule. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.06-schedule-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.06-schedule-get-command.md new file mode 100644 index 0000000..aeff96a --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.06-schedule-get-command.md @@ -0,0 +1,24 @@ + +# 4.75.6 Schedule Get Command + +This command is used to request the configuration for a specific schedule ID. + +The Schedule Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE GET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID | | | | | | | | | | | | | | | | | | | | | | | | + +Schedule ID (8 bits) + +This field MUST carry the requested Schedule ID. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.07-schedule-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.07-schedule-report-command.md new file mode 100644 index 0000000..9af0ee4 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.07-schedule-report-command.md @@ -0,0 +1,60 @@ + +# 4.75.7 Schedule Report Command + +This command is used to report the configuration for a specific schedule. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year | | | | | | | | | | | | | | | | | | | | | | | | +| Active ID _ | | | | | | | | | | | | Start Month | | | | | | | | | | | | +| Reserved | | | | | | | | | | Start Day of Month | | | | | | | | | | | | | | +| Res. | | | Start Weekday | | | | | | | | | | | | | | | | | | | | | +| Duration Type | | | | | | | | | Start Hour | | | | | | | | | | | | | | | +| Reserved | | | | | | Start Minute | | | | | | | | | | | | | | | | | | +| Duration Byte 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Byte 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Report to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Cmd to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Length 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte 1 - 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte 1 – N | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Length P | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte P - 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte P - N | | | | | | | | | | | | | | | | | | | | | | | + +[Fields not described below are described in the Schedule Set Command; refer to 4.75.5.](04.75.05-schedule-set-command.md#4755-schedule-set-command) + +Schedule ID (8 bits) + +This field is used to indicate the advertised Schedule ID. + +If this command is advertising an unused or unsupported Schedule ID, all parameters until Number of Cmd to Follow MUST be set to 0x00. The Cmd Length and Cmd Byte fields MUST be omitted. + +Active_ID (4 bits) + +This field is used to advertise the status for the requested Schedule ID. This field MUST be encoded [according to Table 107.](04.75.11-schedule-state-report-command.md#47511-schedule-state-report-command) Duration (16 bits) + +This field is used to advertise either the configured duration for a schedule or how much time is left before the schedule becomes inactive. + +The Duration Type, Start Time and Schedule ID fields MUST be inspected before interpreting this field. [This field MUST advertise a value according to Table 106.](04.75.07-schedule-report-command.md#4757-schedule-report-command) + +Table 106. Duration field usage + +| | Duration Type | | | Schedule ID | | | Start time | | | Advertised duration | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Time (0x00..0x02) | | | Regular | | | Specified start time | | | Configured duration | | | +| Time (0x00..0x02) | | | Regular or Override | | | Start now | | | Remaining time | | | +| Override (0x03) | | | Override (0xFF) | | | Start now | | | Configured override type (Table 105) | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.08-schedule-remove-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.08-schedule-remove-command.md new file mode 100644 index 0000000..59e99a8 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.08-schedule-remove-command.md @@ -0,0 +1,22 @@ + +# 4.75.8 Schedule Remove Command + +This command is used to request the removal of one or all Schedules in a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE REMOVE _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID | | | | | | | | | | | | | | | | | | | | | | | | + +Schedule ID (8 bits) + +This field is used to indicate the schedule that is to be removed/erased. + +If this field is set to 0x00, all configured schedules MUST be removed. If this field is set to 0xFE, the Fall Back Schedule MUST be removed (if defined). If this field is set to 0xFF, the Override Schedule MUST be removed (if defined). If this field is in the range 0x01..[Number of supported Schedules], the receiving node MUST remove the corresponding schedule. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.09-schedule-state-set-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.09-schedule-state-set-command.md new file mode 100644 index 0000000..8982453 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.09-schedule-state-set-command.md @@ -0,0 +1,39 @@ + +# 4.75.9 Schedule State Set Command + +This command is used to enable or disable a schedule. + +This command MUST be ignored by a node advertising no support for Enabling/Disabling schedules in the Schedule Supported Report Command. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE STATE SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule State | | | | | | | | | | | | | | | | | | | | | | | | + +Schedule ID (8 bits) + +This field is used to indicate the schedule that is to be enabled or disabled. + +The value 0x00 MUST cause the receiving node to change the state for all schedules, except for the Override Schedule. Values in the range 0x01..[number of supported schedules] and 0xFE MUST indicate the actual schedule ID which state is to be updated. + +The value 0xFF MUST be ignored by a receiving node. Override schedules cannot be enabled/disabled and may only be removed using the Schedule Remove Command. + +Schedule state (8 bits) + +This field is used to indicate the new state of one or more schedules. + +The value 0xFF MUST indicate that the actual schedule MUST be enabled. The value 0x00 MUST indicate that the actual schedule MUST be disabled. + +Disabling a schedule MUST NOT cause the schedule settings to be permanently removed. Schedules may be permanently removed via the Schedule Remove Command. + +If a schedule is enabled, the receiving node MUST assess if the actual schedule should have been active and activate it accordingly. + +If a schedule is disabled while being active, the receiving node MUST treat the disabling operation as if the schedule ended. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.10-schedule-state-get-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.10-schedule-state-get-command.md new file mode 100644 index 0000000..a2cf8f2 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.10-schedule-state-get-command.md @@ -0,0 +1,19 @@ + +# 4.75.10 Schedule State Get Command + +This command is used to request the status of all schedules supported by a node. + +The Schedule State Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | 3 | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE STATE GET _ _ | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.11-schedule-state-report-command.md b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.11-schedule-state-report-command.md new file mode 100644 index 0000000..a3ff8fc --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/04.75.11-schedule-state-report-command.md @@ -0,0 +1,65 @@ + +# 4.75.11 Schedule State Report Command + +This command is used to advertise the status of all schedules supported by a device. + +| | 7 | | | 6 | | | 5 | | | 4 | 3 | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE STATE REPORT _ _ | | | | | | | | | | | | | | | | | | | | | +| Number of Supported Schedule ID | | | | | | | | | | | | | | | | | | | | | +| Reports to Follow | | | | | | | | | | | | | | | | | | Override | | | +| Active ID 2 _ | | | | | | | | | | | Active ID 1 _ | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | +| Active ID N _ | | | | | | | | | | | Active ID N-1 _ | | | | | | | | | | + +. + +Number of Supported Schedule ID (8 bits) + +This field is used to advertise the number of supported regular schedule IDs. This field’s value MUST be the same as the value advertised in the Schedule Supported Report Command. + +Override (1 bit) + +This field MUST be used to advertise the status of the Override Schedule (ID = 0xFF). + +If the Override Schedule is active, this bit MUST be set to 1. If the Override Schedule is inactive, this bit MUST be set to 0. Reports to Follow (7 bits) + +The length of the Active_ID field may be larger than the maximum available Z-Wave MAC frame size. + +This field MUST be used to advertise the number of commands following this command in order to advertise the status of all Schedules IDs. + +A controlling node SHOULD use this value to detect missing reports. + +Active_ID (N * 4 bits) + +This field is used to advertise the status for each supported schedule ID. Four bits units are used for each Schedule ID to indicate the status. It means that: + + Bits 0 to 3 in Active_ID byte 1 represent Schedule ID = 1  Bits 4 to 7 in Active_ID byte 1 represent Schedule ID = 2  Bits 0 to 3 in Active_ID byte 2 represent Schedule ID = 3  … + +The size of this field MUST be the smallest number of bytes needed to advertise the number of supported Schedule IDs advertised in this command. + +If several Reports are returned (using the Reports to follow field), the first Report advertises Schedule ID 1 to Schedule ID N and the subsequent report MUST be interpreted as representing Schedule ID starting from N+1. + +[Each 4 bits unit MUST be encoded according to Table 107.](04.75.11-schedule-state-report-command.md#47511-schedule-state-report-command) Table 107. Active_ID encoding + +| | Hex | | | Description | | | Detailed description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | Not used | | | The Schedule ID is not used. (not set/configured) or unsupported | | | 1 | | | +| 0x01 | | | [DEPRECATED] Override + Not used | | | [DEPRECATED] A sending node SHOULD NOT use this status. It is RECOMMENDED to use 0x00 instead. A receiving node MUST interpret this status as Active ID = 0x00 (and the override field set _ to 1 for the Schedule State Report Command). | | | 1 | | | +| 0x02 | | | Not Active | | | The Schedule ID is used, enabled and currently not active. | | | 1 | | | +| 0x03 | | | Active | | | The Schedule ID is used, enabled and currently active. | | | 1 | | | +| 0x04 | | | Disabled | | | The Schedule ID is used and disabled. | | | 1 | | | +| 0x05 | | | Override + Active | | | The Schedule ID is used, enabled and should currently be active but it is suspended by the Override Schedule The override field MUST be set to 1 when using this status in the Schedule State Report Command. | | | 1 | | | +| 0x06 | | | [DEPRECATED] Override + Not Active | | | [DEPRECATED] A sending node SHOULD NOT use this status. It is RECOMMENDED to use 0x02 instead. A receiving node MUST interpret this status as Active ID = 0x02 (and the override field set _ to 1 for the Schedule State Report Command) | | | 1 | | | +| 0x07 | | | [DEPRECATED] Override + Disabled | | | [DEPRECATED] A sending node SHOULD NOT use this status. It is RECOMMENDED to use 0x04 instead. A receiving node MUST interpret this status as Active ID = 0x04 (and the override field set _ to 1 for the Schedule State Report Command) | | | 1 | | | + +CC:0053.01.09.11.00B interpret this status as Active_ID = 0x02 (and the override field set + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/index.md b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/index.md new file mode 100644 index 0000000..7fa5f34 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.75-schedule-command-class-version-1/index.md @@ -0,0 +1,24 @@ + +# 4.75 Schedule Command Class, version 1 + +The Schedule Command Class allows scheduling the execution of commands for a given duration in a supporting device. It is a generic Command Class that may be used to schedule commands of any other Command Class. + +## Contents + +- [4.75.1 Terminology](04.75.01-terminology.md) +- [4.75.2 Interoperability considerations](04.75.02-interoperability-considerations.md) +- [4.75.3 Schedule Supported Get Command](04.75.03-schedule-supported-get-command.md) +- [4.75.4 Schedule Supported Report Command](04.75.04-schedule-supported-report-command.md) +- [4.75.5 Schedule Set Command](04.75.05-schedule-set-command.md) +- [4.75.6 Schedule Get Command](04.75.06-schedule-get-command.md) +- [4.75.7 Schedule Report Command](04.75.07-schedule-report-command.md) +- [4.75.8 Schedule Remove Command](04.75.08-schedule-remove-command.md) +- [4.75.9 Schedule State Set Command](04.75.09-schedule-state-set-command.md) +- [4.75.10 Schedule State Get Command](04.75.10-schedule-state-get-command.md) +- [4.75.11 Schedule State Report Command](04.75.11-schedule-state-report-command.md) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.76-schedule-command-class-version-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.76-schedule-command-class-version-2.md new file mode 100644 index 0000000..699af86 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.76-schedule-command-class-version-2.md @@ -0,0 +1,315 @@ + +# 4.76 Schedule Command Class, version 2 + +The Schedule Command Class version 2 allows scheduling the execution of commands for a given duration in a supporting node. It is a generic command class that may be used to schedule commands from any other Command Class. + +## 4.76.1 Compatibility considerations + +The Schedule Command Class, version 2 is backwards compatible with version 1. A node supporting the Schedule Command Class, version 2 MUST also support version 1. + +Schedule Command Class, version 2 introduces the following: + + Schedule ID Blocks  Clarification on using Schedule Command Class with Security + +All commands or fields not described in this version remain unchanged from version 1. + +### 4.76.1.1 Schedule ID Blocks + +In Schedule Command Class version 1, all Schedule IDs have to support the same Start Time Options, Override Types and supported commands. + +The Schedule ID Blocks allows a node to implement several Schedule ID pools sharing the same scheduling functionalities. + +Each Schedule ID Block MUST have its own range of Schedule ID’s. The ID for each Block MUST be in the range 1..[Number of Supported Schedule IDs]. + +Schedule ID Block = 1 is the default Block. A version 1 node MUST be assumed to be using Schedule ID block 1. + +### 4.76.1.2 Schedule Command Class with Security + +The Schedule Command Class may be implemented by secure devices. Depending on the type of device, a given Command Class may be supported only via secure communication or via secure as well as unsecure communication. + +The following command class categories may be considered: + + Always unsecure Examples of command classes which are always supported via unsecure communication – as well as via secure communication if the device is securely included (e.g Z-Wave Plus Info Command Class). + + Migrate to secure Examples of command classes which are supported via unsecure communication if the device is not securely included – but only via secure communication if the device is securely included. (e.g. Multilevel Switch or Association Command Class) + + Secure only: Examples of command classes which are supported only via secure communication. (e.g. Door Lock Command Class) To reflect the above mentioned dynamic support scenarios, a device MUST advertise the supported Command Classes for scheduling in a way that matches the current secure/non-secure supported Command Class lists found in the NIF and S0/S2 Commands Supported Report Commands. + +Clarification is added to the Schedule Supported Report Command and Schedule Set Command for proper reporting and configuration of unsecure and secure command classes scheduling. + +It is RECOMMENDED to support the Schedule Command Class only at the highest security level in order to avoid dynamic listing. + +## 4.76.2 Schedule Supported Get Command + +This command is used to query the properties of a node. + +The Schedule Supported Report Command MUST be returned in response to this command. + +If the receiving node supports S0 or S2 Command Class and this command is issued via non-secure communication, the receiving node MUST advertise Command Classes that can be scheduled but also CC:0053.02.01.11.002 supported at the received security level. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE SUPPORTED GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | + +Schedule ID Block (1 byte) + +This field is used to request a particular Schedule ID Block. + +If this field is set to 0x00, the receiving node MUST return the default Schedule ID Block (ID = 1). + +A node receiving a version 1 Schedule Supported Get Command (without the Schedule ID Block field) MUST return a response for the default Schedule ID Block (ID = 1). + +A node receiving a non-supported Schedule ID Block SHOULD return a report for the default Schedule ID Block. + +## 4.76.3 Schedule Supported Report Command + +This command is used to advertise the scheduling functionalities supported by a node for a given Schedule ID Block. + +| | 7 | | 6 | | | 5 | | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE SUPPORTED REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Supported Schedule IDs | | | | | | | | | | | | | | | | | | | | | | | | +| Support Enable/ Disable | | | Fall- back Support | | | | Start Time Support | | | | | | | | | | | | | | | | | +| Number of supported CC | | | | | | | | | | | | | | | | | | | | | | | | +| | Supported CC 1 | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | | Supported | | | | | +| | | | | | | | | | | | | | | | | | | | Command 1 | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Supported CC N | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | | Supported | | | | | +| | | | | | | | | | | | | | | | | | | | Command N | | | | | +| Override Support | | | Supported Override Types | | | | | | | | | | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Supported Schedule Blocks | | | | | | | | | | | | | | | | | | | | | | | | + +Fields not described below remain unchanged from version 1. + +All fields contained in this command advertise the scheduling supported functionalities for the actual Schedule ID Block. + +Schedule ID Block (8 bits) + +This field is used to indicate the actual Schedule ID Block for which the supported scheduling functionalities are advertised. + +The advertised supported functionalities SHOULD be different for every Schedule ID Block. + +Number of Schedule ID Blocks (8 bits) + +This field MUST advertise the total number of Schedule ID blocks supported by the node. + +This field MUST be in the range 1..255. + +The implemented Schedule ID Blocks MUST be in the range 1..[Number of Supported Schedule ID Blocks]. i.e. a node supporting 10 Schedules ID Blocks MUST accept Schedule ID Blocks values in the range 1..10. + +## 4.76.4 Schedule Set Command + +This command is used to create a new schedule or modify an existing schedule. This command MUST enable the schedule if a new schedule is created. This command MUST NOT change the enabled/disabled state of existing schedules + +If the receiving node supports S0 or S2 Command Class, it MUST NOT process the schedule creation if any of the scheduled command classes is not supported at the security level of the received Schedule Set Command. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Start Month | | | | | | | | | | | | +| Reserved | | | | | | | | | | Start Day of Month | | | | | | | | | | | | | | +| Res. | | | Start Weekday | | | | | | | | | | | | | | | | | | | | | +| Duration Type | | | | | | | | | Start Hour | | | | | | | | | | | | | | | +| Reserved | | | | | | Start Minute | | | | | | | | | | | | | | | | | | +| Duration Byte 1 MSB | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Byte 2 LSB | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Cmd to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Length 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd 1 Byte 1 - 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd 1 Byte 1 - N | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Length P | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte P - 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte P - N | | | | | | | | | | | | | | | | | | | | | | | + +Fields not described below remain unchanged from version 1. + +Schedule ID Block (8 bits) + +This field is used to specify the Schedule ID Block in which the specified Schedule ID is being set. + +A node receiving a version 1 Schedule Set Command (with the Schedule ID Block field set to 0x00) MUST assume the default Schedule ID Block (ID = 0x01). + +## 4.76.5 Schedule Get Command + +This command is used to request the configuration for a specific schedule ID. + +The Schedule Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE GET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | + +Fields not described below remain unchanged from version 1. + +Schedule ID Block (8 bits) + +This field is used to specify the requested Schedule ID Block. + +A node receiving a version 1 Schedule Get Command (without the Schedule ID Block field) MUST return a response for the default Schedule ID Block (ID = 1). + +## 4.76.6 Schedule Report Command + +This command is used to advertise the configuration for a specific schedule. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year | | | | | | | | | | | | | | | | | | | | | | | | +| Active ID _ | | | | | | | | | | | | Start Month | | | | | | | | | | | | +| Reserved | | | | | | | | | | Start Day of Month | | | | | | | | | | | | | | +| Res. | | | Start Weekday | | | | | | | | | | | | | | | | | | | | | +| Duration Type | | | | | | | | | Start Hour | | | | | | | | | | | | | | | +| Reserved | | | | | | Start Minute | | | | | | | | | | | | | | | | | | +| Duration Byte 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Byte 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Report to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Cmd to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Length 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte 1 - 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte 1 – N | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Length P | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte P - 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte P - N | | | | | | | | | | | | | | | | | | | | | | | + +Fields not described below remain unchanged from version 1. + +Schedule ID Block (8 bits) + +This field is used to specify the advertised Schedule ID Block. + +## 4.76.7 Schedule Remove Command + +This command is used to request the removal of one or all Schedules in a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE REMOVE _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | + +Schedule ID (8 bits) + +This field is used to indicate the schedule that is to be removed. + +If this field is set to 0x00, all schedules within the Schedule ID Block MUST be removed. If this field is set to 0xFE, the Fall Back Schedule MUST be removed (if defined for the Schedule ID Block). If this field is set to 0xFF, the Override Schedule MUST be removed (if defined for the Schedule ID Block). If this field is in the range 0x01..[Number of supported Schedules], the receiving node MUST remove the corresponding schedule in the Schedule ID Block. + +Schedule ID Block (8 bits) + +This field is used to indicate the Schedule ID Block in which a schedule is being removed. + +A node receiving a version 1 Schedule Set Command (without the Schedule ID Block field) MUST assume the default Schedule ID Block (ID = 0x01). + +A node receiving this command with Schedule ID = 0x00 and Schedule ID Block = 0x00 MUST remove all Schedule IDs in all Schedule ID Blocks + +A node receiving this command with Schedule ID = 0x00 and Schedule ID Block ≠ 0x00 MUST remove all Schedule IDs from the specified Schedule ID Block. + +A node receiving this command with Schedule ID ≠ 0x00 and Schedule ID Block = 0x00 MUST ignore the command + +## 4.76.8 Schedule State Set Command + +This command is used to enable or disable one or more schedules. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE STATE SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule State | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | + +Fields not described below remain unchanged from version 1. + +Schedule ID Block (8 bits) + +This field is used to specify the Schedule ID Block in which one or more schedule are being enabled or disabled. + +This command MUST be ignored by a node advertising no support for Enabling/Disabling schedules in the Schedule Supported Report Command for the given Schedule ID Block. + +A node receiving a version 1 Schedule Set Command (without the Schedule ID Block field) MUST assume the default Schedule ID Block (ID = 0x01). + +A node receiving this command with Schedule ID = 0x00 and Schedule ID Block = 0x00 MUST enable/disable all Schedule IDs from all Schedule ID Blocks. + +A node receiving this command with Schedule ID = 0x00 and Schedule ID Block ≠ 0x00 MUST enable/disable all Schedule IDs from the specified Schedule ID Block. + +A node receiving this command with Schedule ID ≠ 0x00 and Schedule ID Block = 0x00 MUST ignore the command. + +## 4.76.9 Schedule State Get Command + +This command is used to request the status of all schedules within a Schedule ID Block supported by a node. + +The Schedule State Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE STATE GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | + +Schedule ID Block (8 bits) + +This field is used to request a particular Schedule ID Block. + +A node receiving a version 1 Schedule Supported Get Command (without the Schedule ID Block field) MUST return a response for the default Schedule ID Block (ID = 1). + +## 4.76.10 Schedule State Report Command + +This command is used to advertise the status of all schedules supported by a device in a given Schedule ID block. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE STATE REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Supported Schedule ID | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to Follow | | | | | | | | | | | | | | | | | | | | | Override | | | +| Active ID 2 _ | | | | | | | | | | | | Active ID 1 _ | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Active ID N _ | | | | | | | | | | | | Active ID N-1 _ | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | + +Fields not described below remain unchanged from version 1. + +Number of Supported Schedule ID (8 bits) + +This field is used to advertise the number of supported regular schedule IDs for the actual Schedule ID Block. This field’s value MUST be the same as the value advertised in the Schedule Supported Report Command. + +Schedule ID Block (8 bits) + +This field is used to specify the Schedule ID Block in which all schedule states are advertised. + +If several Reports are returned (using the Reports to Follow field), this field MUST be present in every Report. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.77-schedule-command-class-version-3.md b/docs/specs/command-class-specification/04-command-class-definitions/04.77-schedule-command-class-version-3.md new file mode 100644 index 0000000..bd32b60 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.77-schedule-command-class-version-3.md @@ -0,0 +1,274 @@ + +# 4.77 Schedule Command Class, version 3 + +The Schedule Command Class, version 3 allows scheduling the execution of commands for a given duration in a supporting node. It is a generic command class that may be used to schedule commands of any other Command Class. + +## 4.77.1 Terminology + +The Schedule Command Class version 3 introduces new terminology, complementing the terminology introduced in The Schedule Command Class version 1: + +Regular schedules may be triggered repeatedly by two mechanisms. From version 1, a Repeating Schedule can be created by setting parts of the start time to unspecified values, e.g. if month is unspecified, the schedule can start the first day of each month. From version 3, Recurrence settings may specify additional periodical triggers, e.g. every second day measured from the most recent trigger of the regular schedule. + +## 4.77.2 Compatibility considerations + +The Schedule Command Class, version 3 is backwards compatible with version 2. A node supporting the Schedule Command Class, version 3 MUST also support version 2. + +The Schedule Command Class version 3 introduces the “Recurring Mode” start mode and “Time from now” start time option. + +The “Time from now” start time option allows to set a schedule to start a after a given time from the reception of the command. + +The “Recurring Mode” start mode allows to set a schedule to restart repeatedly at fixed intervals since the last activation, e.g. every second day or every 6 months since the last activation. + +The Active_ID advertised in the Schedule Report Command of versions 1 and 2 is now overloaded with the Recurrence Offset field. A new AID_RO_CTL flag in the Schedule Get Command controls which value is actually returned. + +All commands or fields not described in this version remain unchanged from version 2. + +## 4.77.3 Schedule Supported Report Command + +This command is used to advertise the scheduling functionalities supported by a node. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE SUPPORTED REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Supported Schedule IDs | | | | | | | | | | | | | | | | | | | | | | | | +| Support Enable/ Disable | | | Fall- back Support | | | Start Time Support | | | | | | | | | | | | | | | | | | +| Number of supported CC | | | | | | | | | | | | | | | | | | | | | | | | +| | Supported CC 1 | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | | Supported | | | | | +| | | | | | | | | | | | | | | | | | | | Command 1 | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Supported CC N | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | | Supported | | | | | +| | | | | | | | | | | | | | | | | | | | Command N | | | | | +| Override Support | | | Supported Override Types | | | | | | | | | | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Supported Schedule Blocks | | | | | | | | | | | | | | | | | | | | | | | | + +Fields not described below remain unchanged from version 2. + +Start Time Support (6 bits) + +This field is used to advertise the start time options supported by the sending node. + +Regular schedules MUST support the advertised start time options. The Override Schedule SHOULD support the advertised start time options. + +The Override Schedule MUST NOT support the Recurring Mode. + +[This field MUST be treated as a bitmask and MUST be encoded according to Table 108](04.77-schedule-command-class-version-3.md#4773-schedule-supported-report-command) Table 108. Start Time Support encoding + +| | Category | | | Bit | | | Indicates support for | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Start Time option | | | 0 | | | Start now. Refer to 4.75.4.1 | | | 1 | | | +| | | | 1 | | | Start Hour and Minute. Refer to 4.75.4.2 | | | 1 | | | +| | | | 2 | | | Calendar time. Refer to 4.75.4.3 | | | 1 | | | +| | | | 3 | | | Weekdays. Refer to 4.75.4.4 | | | 1 | | | +| | | | 4 | | | Time from now. Refer to 4.77.3.1 | | | 3 | | | +| Start Time mode | | | 5 | | | Recurring Mode. Refer to 4.77.3.2 | | | 3 | | | + +Each bit indicates the support for a given Start Time option or mode. + +The value 1 MUST indicate that the node supports the corresponding start time option/mode. The value 0 MUST indicate that the node does not support the corresponding start time option/mode. + +While support is advertised as a bitmap, the actual functionality is triggered by different combinations of Schedule Set start time fields. The following subsections outline the mandatory supported combinations when advertising support for the corresponding option. + +### 4.77.3.1 Start Time option: Start from now + +The start now option is used to make a configured schedule start after the indicated time has elapsed from the reception of the Schedule Set Command. + +The Start from now option MUST cause a schedule to be activated at the specified relative time measured from the reception of the Schedule Set Command and run for the specified duration. + +A node supporting the Time from now option MUST support the creation of a schedule with the following start time fields’ combination: Relative = ‘1’ and YYMMDD = 0xFF, 0x00, Days, Weekdays = 0x00, HH:MM = Hours:Minutes + +A receiving node MUST ignore all combinations which do not comply with the one above if the Relative flag is set. + +A node supporting this option is NOT REQUIRED to support the Start hour and Minute option or Calendar time option even though it MUST be able to read the start day, start hour and start minutes fields when using this option. + +### 4.77.3.2 Start Time mode: Recurring Mode + +This mode is used to trigger a schedule repeatedly at fixed intervals. When using this mode, a schedule will start at the specified start time and will restart after a given time has elapsed since the last activation. + +The recurring mode is configured with the Recurrence Offset and Recurrence Mode fields of the Schedule Set Command. + +A node supporting the Recurring Mode MUST support at least one start time option. + +## 4.77.4 Schedule Set Command + +This command is used to create a new schedule or modify an existing schedule This command MUST enable the schedule if a new schedule is created. This command MUST NOT change the enabled/disabled state of existing schedules. + +If the receiving node supports S0 or S2 Command Class, it MUST NOT process the schedule creation if any of the scheduled command classes is not supported at the security level of the received Schedule Set Command. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year | | | | | | | | | | | | | | | | | | | | | | | | +| Recurrence Offset | | | | | | | | | | | | Start Month | | | | | | | | | | | | +| Res. | | | Recurrence Mode | | | | | | Start Day of Month | | | | | | | | | | | | | | | +| Res. | | | Start Weekday | | | | | | | | | | | | | | | | | | | | | +| Duration Type | | | | | | | | | Start Hour | | | | | | | | | | | | | | | +| Res. | | | Relative | | | Start Minute | | | | | | | | | | | | | | | | | | +| Duration Byte 1 MSB | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Byte 2 LSB | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Cmd to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Length 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte 1 - 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte 1 - N | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Length P | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte P - 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte P - N | | | | | | | | | | | | | | | | | | | | | | | + +Fields not described below remain unchanged from version 2. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +### 4.77.4.1 Recurrence fields + +The recurrence settings of a schedule are set by the following fields: + + Recurrence Mode  Recurrence Offset + +These fields MUST be ignored by a node advertising no support for the Recurring Mode start time mode in the Schedule Supported Report Command. + +Recurrence mode (2 bits) + +This field is used to specify the unit of the Recurrence Offset field. [This field MUST comply with Table 109.](04.77-schedule-command-class-version-3.md#47741-recurrence-fields) + +Table 109. Recurrence Mode encoding + +| | Value | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | The recurrence Offset is expressed in Hours | | | 3 | | | +| 0x01 | | | The recurrence Offset is expressed in Days | | | 3 | | | +| 0x02 | | | The recurrence Offset is expressed in Weeks | | | 3 | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +This field MUST be ignored if the Recurrence Offset field is set to 0. + +Recurrence Offset (4 bits) + +This field is used to specify the interval at which the recurring schedule will be triggered. + +[This field MUST be encoded according to Table 110 and MUST be interpreted together with the](04.77-schedule-command-class-version-3.md#47741-recurrence-fields) Recurrence Mode field. + +Table 110. Recurrence Offset encoding + +| | Offset | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0 | | | Recurrence Disabled | | | +| 1..15 | | | Repeat every 1..15 hour, day or week The unit (hour, day or week) is indicated by the Recurrence Mode field. | | | + +When a schedule starts due to its start time options, it MUST restart the current recurrence timer. It CC:0053.03.03.11.00B means that a schedule MUST start every time the start time condition is met and the recurrence offset CC:0053.03.03.11.00C MUST trigger the schedule to restart based on the last time it started. + +st For example, a schedule set to start on the 1 of each month with a 2 day recurrence offset MUST start st rd th th th st st rd on the 1, 3, 5 …, 27, 29, 31 and will start again the next month on the 1, 3, etc. + +A receiving node MUST accept a schedule set to start in the past if recurrence is enabled. In this case, the recurrence MUST trigger the schedule to restart based on the time it should have been started last. + +### 4.77.4.2 Start time fields + +The Schedule start time is defined by the following fields: + + Start Year  Start Month  Start Day of Month  Start Weekday  Start Hour  Start Minute  Relative + +[A receiving node MUST support the start time fields combinations indicated in sections 4.75.4.1, 4.75.4.2](04.75-schedule-command-class-version-1/04.75.04-schedule-supported-report-command.md#47541-start-time-option-start-now) [4.75.4.3, 4.75.4.4 and 4.77.3.1 if the corresponding start time option is supported.](04.75-schedule-command-class-version-1/04.75.04-schedule-supported-report-command.md#47543-start-time-option-calendar-time) + +If none of the start time fields are specified, the schedule MUST start immediately if the start now option is supported. In this case, the schedule MUST NOT be activated again at a later time unless receiving another Schedule Set Command. + +Relative (1 bit) + +This field is used to indicate if the schedule start time is using the start from now start option. + +The value 1 MUST indicate that the start time fields MUST be interpreted as the time left before the [schedule starts. In this case, the start time fields MUST be set and interpreted as indicated in 4.77.3.1](04.77-schedule-command-class-version-3.md#47731-start-time-option-start-from-now) and the schedule MUST NOT be activated again at a later time unless receiving another Schedule Set Command. + +The value 0 MUST indicate that the start time fields MUST be interpreted as an absolute start time for the schedule. + +## 4.77.5 Schedule Get Command + +This command is used to request the configuration for a specific schedule ID. + +The Schedule Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE GET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | +| AID RO CTL _ _ | | | Reserved | | | | | | | | | | | | | | | | | | | | | + +Fields not described below remain unchanged from version 2. Active_ID / Recurrence Offset control (AID_RO_CTL) (1 bit) + +This field is used to request either the Active_ID or the Recurrence Offset value in the Schedule Report Command which is returned in response to this command. + +A receiving node MUST return a Schedule Report Command advertising the Active_ID of the Schedule if this field is set to 0. + +A receiving node MUST return a Schedule Report Command advertising the Recurrence Offset of the schedule if this field is set to 1. + +## 4.77.6 Schedule Report Command + +The Schedule Report Command is used to advertise the configuration for a specific schedule. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year | | | | | | | | | | | | | | | | | | | | | | | | +| Active ID/Recurrence Offset (AID RO) _ _ | | | | | | | | | | | | Start Month | | | | | | | | | | | | +| AID RO _ _ CTL | | | Recurrence Mode | | | | | | Start Day of Month | | | | | | | | | | | | | | | +| Res. | | | Start Weekday | | | | | | | | | | | | | | | | | | | | | +| Duration Type | | | | | | | | | Start Hour | | | | | | | | | | | | | | | +| Res. | | | Relative | | | | Start Minute | | | | | | | | | | | | | | | | | +| Duration Byte 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Byte 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Report to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Cmd to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Length 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte 1 - 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte 1 – N | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Length P | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte P - 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte P - N | | | | | | | | | | | | | | | | | | | | | | | + +Fields not described below remain unchanged from version 2. Active_ID/Recurrence Offset (AID_RO) (4 bits) + +This field is used to advertise the Active_ID or the Recurrence Offset of the advertised schedule. + +[If this field carries the Active_ID value, this field MUST be encoded according to Table 107.](04.75-schedule-command-class-version-1/04.75.11-schedule-state-report-command.md#47511-schedule-state-report-command) + +[If this field carries the Recurrence Offset, this field MUST be encoded according to Table 110 and MUST](04.77-schedule-command-class-version-3.md#47741-recurrence-fields) be interpreted together with the Recurrence Mode field. + +Active_ID / Recurrence Offset control (AID_RO_CTL) (1 bit) + +This field is used to indicate whether the Active_ID or the Recurrence Offset value is advertised in the command. + +The value 0 MUST indicate that the Active_ID/Recurrence Offset (AID_RO) field carried the Active_ID value. + +The value 1 MUST indicate that the Active_ID/Recurrence Offset (AID_RO) field carried the Recurrence Offset value. + +Recurrence mode (2 bits) + +This field is used to specify the Recurrence Offset unit. + +This field MUST be ignored if the AID_RO_CTL field is set to 0. [This field MUST comply with Table 109 if the AID_RO_CTL field is set to 1.](04.77-schedule-command-class-version-3.md#47741-recurrence-fields) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.78-schedule-command-class-version-4.md b/docs/specs/command-class-specification/04-command-class-definitions/04.78-schedule-command-class-version-4.md new file mode 100644 index 0000000..210001c --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.78-schedule-command-class-version-4.md @@ -0,0 +1,265 @@ + +# 4.78 Schedule Command Class, version 4 + +The Schedule Command Class, version 4 allows supporting nodes to advertise the list of commands they support for scheduling. + +## 4.78.1 Compatibility considerations + +The Schedule Command Class version 4 introduces the possibility to advertise the list of command supported for scheduling and explicitly allows scheduling extended command classes. The following commands are introduced: + + [Schedule Supported Commands Get Command](04.78-schedule-command-class-version-4.md#4783-schedule-supported-commands-get-command)  [Schedule Supported Commands Report Command](04.78-schedule-command-class-version-4.md#4784-schedule-supported-commands-report-command) + +The following functionalities become obsoleted: + + Redundant values in the Active_ID field encoding  The Report to Follow field. + +A supporting node no longer needs to be able to parse and handle several commands in order to set or report schedules or schedules states. Supporting nodes MUST use the Transport Service Command Class, version 2 in order to transmit long Z-Wave payloads. + +A node supporting the Schedule Command Class, version 4 MUST also support version 3. + +Commands not mentioned in this version remain unchanged from version 3. + +## 4.78.2 Schedule Supported Report Command + +This command is used to advertise the scheduling properties of a device. + +| | 7 | | | 6 | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE SUPPORTED REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | +| Number of Supported Schedule IDs | | | | | | | | | | | | | | | | | | | | | | +| Support Enable/Di sable | | | Fall- back Support | | Start Time Support | | | | | | | | | | | | | | | | | +| Number of supported CC | | | | | | | | | | | | | | | | | | | | | | +| | Supported CC 1 | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | Supported | | | | | +| | | | | | | | | | | | | | | | | | Command 1 | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | +| | Supported CC N | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | Supported | | | | | +| | | | | | | | | | | | | | | | | | Command N | | | | | +| Override Support | | | Supported Override Types | | | | | | | | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | +| Number of Supported Schedule Blocks | | | | | | | | | | | | | | | | | | | | | | + +All fields not described below remain unchanged from version 3. + +Supported Command (N * 2 bits) + +This field MUST advertise the supported commands for the command class entry. This field MUST [comply with Table 111.](04.78-schedule-command-class-version-4.md#4782-schedule-supported-report-command) + +Table 111. Schedule Supported Report v4::Supported Command + +| | Value | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | All Commands within the Command Class are supported | | 1 | | | +| 0x01 | | Only Set Commands are supported | | 1 | | | +| 0x02 | | Only Get Commands are supported | | 1 | | | +| 0x03 | | Custom list of commands are supported. | | 4 | | | + +Certain command classes commands do not contain the string “Set” or “Get” in their name. Nodes MUST consider all commands mandating to return a response to be of type “Get” and all other commands to be of type “Set”. + +The length of this field MUST be according to the Number of supported CC field value. A supporting node MUST NOT advertise the 0x03 value if the list of supported command can be advertised with the other values. + +If a sending node advertises 0x03 for a given Schedule ID Block and Command Class, a controlling node SHOULD retrieve the exact list of supported commands using the Schedule Supported Commands Get Command. + +## 4.78.3 Schedule Supported Commands Get Command + +This command is used to query the list of commands that can be scheduled within for a given command class and Schedule ID Block. + +The Schedule Supported Commands Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE SUPPORTED COMMANDS GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | + +Schedule ID Block (8 bits) + +This field is used to request a particular Schedule ID Block. + +If a non-supported Schedule ID Block is specified, a receiving node SHOULD return a response for the Schedule ID block 1. + +## 4.78.4 Schedule Supported Commands Report Command + +This command is used to advertise the list of commands that can be scheduled within for a given Schedule ID Block + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE SUPPORTED COMMANDS REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | +| Command Class List Length | | | | | | | | | | | | | | | | | | | | | | | | +| | Command Class 1 (1 or 2 bytes) | | | | | | | | | | | | | | | | | | | | | | | +| | Supported Command List Length 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Supported Command 1 – 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Supported Command 1 – K | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Command Class N (1 or 2 bytes) | | | | | | | | | | | | | | | | | | | | | | | +| | Supported Command List Length N | | | | | | | | | | | | | | | | | | | | | | | +| | Supported Command N – 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Supported Command N – K | | | | | | | | | | | | | | | | | | | | | | | + +Schedule ID Block (8 bits) + +This field is used to specify the requested Schedule ID Block. + +Command Class List Length (8 bit) + +This field is used to advertise the number of command classes contained in the command. + +This field MUST be set to the number of Command Class entries present in this command (represented by N in the command structure). + +Command Class (8 or 16 bits) + +This field is used to indicate the command class to which the advertised commands belong. This field MAY carry extended Command Classes + +Supported Command List Length (8 bits) + +This field is used to advertise how many commands are advertised in the current Command Class’ list. + +This field MUST be set to the number of Supported Commands present in the current Command Class entry (represented by K in the command structure). Supported Command (K bytes) + +This field is used to advertise the list of commands for the given Command Class entry that can be scheduled for the actual Schedule ID Block. + +The length of this field in bytes MUST be according to the corresponding Supported Command List Length field value. + +## 4.78.5 Schedule Set Command + +This command is used to create a new schedule or modify an existing schedule. This command MUST enable the schedule if a new schedule is created. This command MUST NOT change the enabled/disabled state of existing schedules + +If the receiving node supports S0 or S2 Command Class, it MUST NOT process the schedule creation if any of the scheduled command classes is not supported at the security level of the received Schedule Set Command. + +A controlling node using previous versions may try to schedule unsupported commands. In this case, a receiving node MUST ignore the Schedule Set Command. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE SET _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year | | | | | | | | | | | | | | | | | | | | | | | | +| Recurrence Offset | | | | | | | | | | | | Start Month | | | | | | | | | | | | +| Res. | | | Recurrence Mode | | | | | | Start Day of Month | | | | | | | | | | | | | | | +| Res. | | | Start Weekday | | | | | | | | | | | | | | | | | | | | | +| Duration Type | | | | | | | | | Start Hour | | | | | | | | | | | | | | | +| Res. | | | Relative | | | Start Minute | | | | | | | | | | | | | | | | | | +| Duration Byte 1 MSB | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Byte 2 LSB | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to Follow [OBSOLETED] | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Cmd to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Length 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte 1 - 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte 1 - N | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Length P | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte P - 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte P - N | | | | | | | | | | | | | | | | | | | | | | | + +Fields not described below remain unchanged from version 3. Reports to Follow (8 bits) [OBSOLETED] + +This field has been OBSOLETED: a sending node MUST use the Transport Service Command Class in order to set a schedule containing commands payload too large to fit in the Z-Wave MAC frame size. + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +## 4.78.6 Schedule Report Command + +The Schedule Report Command is used to advertise the configuration for a specific schedule. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE REPORT _ | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year | | | | | | | | | | | | | | | | | | | | | | | | +| Active ID/Recurrence Offset (AID RO) _ _ | | | | | | | | | | | | Start Month | | | | | | | | | | | | +| AID RO _ _ CTL | | | Recurrence Mode | | | | | | Start Day of Month | | | | | | | | | | | | | | | +| Res. | | | Start Weekday | | | | | | | | | | | | | | | | | | | | | +| Duration Type | | | | | | | | | Start Hour | | | | | | | | | | | | | | | +| Res. | | | Relative | | | | Start Minute | | | | | | | | | | | | | | | | | +| Duration Byte 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Byte 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Report to Follow [OBSOLETED] | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Cmd to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Length 1 | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte 1 - 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte 1 – N | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Length P | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte P - 1 | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Cmd Byte P - N | | | | | | | | | | | | | | | | | | | | | | | + +Fields not described below remain unchanged from version 3. Active_ID/Recurrence Offset (4 bits) + +This field is used to advertise the Active_ID or the Recurrence Offset of the advertised schedule. + +[If this field carries the Active_ID value, this field MUST be encoded according to Table 112.](04.78-schedule-command-class-version-4.md#4787-schedule-state-report-command) + +[If this field carries the Recurrence Offset, this field MUST be encoded according to Table 110 and MUST](04.77-schedule-command-class-version-3.md#47741-recurrence-fields) be interpreted together with the Recurrence Mode field. + +Reports to Follow (8 bits) [OBSOLETED] + +This field has been OBSOLETED: a sending node MUST use the Transport Service Command Class in order to report a schedule containing commands payload too large to fit in the Z-Wave MAC frame size. + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +## 4.78.7 Schedule State Report Command + +This command is used to advertise the status of all schedules supported by the specified schedule block. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE STATE REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Supported Schedule ID | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to Follow [OBSOLETED] | | | | | | | | | | | | | | | | | | | | Override | | | | +| Active ID 2 _ | | | | | | | | | | | | Active ID 1 _ | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Active ID N _ | | | | | | | | | | | | Active ID N-1 _ | | | | | | | | | | | | +| Schedule ID Block | | | | | | | | | | | | | | | | | | | | | | | | + +Fields not described below remain unchanged from version 3. + +Reports to Follow (8 bits) [OBSOLETED] + +This field has been OBSOLETED: a sending node MUST use the Transport Service Command Class in order to advertise an Active_ID field too large to fit in the Z-Wave MAC frame size. + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. Active_ID (N * 4 bits) + +The Active_ID field MUST be used to advertise the status for each supported schedule ID. Four bits are used for each Schedule ID to indicate the status. This means that : + + Bits 0 to 3 in Active_ID byte 1 represent Schedule ID = 1,.  Bits 4 to 7 in Active_ID byte 1 represent Schedule ID = 2  Bits 0 to 3 in Active_ID byte 2 represent Schedule ID = 3  … + +The size of this field MUST be the smallest number of bytes needed to advertise the number of supported Schedule IDs advertised in this command. + +[Each 4 bits unit MUST be encoded according to Table 112.](04.78-schedule-command-class-version-4.md#4787-schedule-state-report-command) + +Table 112. Active_ID encoding, version 4 + +| | Hex | | | Description | | | _ Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0x00 | | | Not used | | | The Schedule ID is not used (not set/configured) or unsupported. | | | 1 | | | +| 0x01 | | | [OBSOLETED] Override + Not used | | | [OBSOLETED] A sending node MUST NOT use this status and MUST use 0x00 instead (and the override field set to 1 for the Schedule State Report Command). | | | 4 | | | +| 0x02 | | | Not Active | | | The Schedule ID is used, enabled and currently not active. | | | 1 | | | +| 0x03 | | | Active | | | The Schedule ID is used, enabled and currently active. | | | 1 | | | +| 0x04 | | | Disabled | | | The Schedule ID is used and disabled. | | | 1 | | | +| 0x05 | | | Override + Active | | | The Schedule ID is used, enabled and should currently be active but it is suspended by the Override Schedule The override field MUST be set to 1 when using this status in the Schedule State Report Command | | | 1 | | | +| 0x06 | | | [OBSOLETED] Override + Not Active | | | [OBSOLETED] A sending node MUST NOT use this status and MUST use 0x02 instead. (and the override field set to 1 for the Schedule State Report Command). | | | 4 | | | +| 0x07 | | | [OBSOLETED] Override + Disabled | | | [OBSOLETED] A sending node MUST NOT use this status and MUST use 0x04 instead. (and the override field set to 1 for the Schedule State Report Command). | | | 4 | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.79-schedule-entry-lock-command-class-version-1-deprecated.md b/docs/specs/command-class-specification/04-command-class-definitions/04.79-schedule-entry-lock-command-class-version-1-deprecated.md new file mode 100644 index 0000000..e93f9a2 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.79-schedule-entry-lock-command-class-version-1-deprecated.md @@ -0,0 +1,324 @@ + +# 4.79 Schedule Entry Lock Command Class, version 1 [DEPRECATED] + +THIS COMMAND CLASS HAS BEEN DEPRECATED + +A device MAY implement this command class, but it is RECOMMENDED that new implementations use the Schedule Command Class. If implementing this command class, it is RECOMMENDED that the Schedule Command Class is also implemented. + +The Schedule Entry Lock Command Class provides Z-Wave devices the capability to exchange scheduling information. The Schedule Entry Lock Type Commands are for controlling the schedules of an Entry Lock using schedule based user code Ids. The Entry Lock supports two types of schedules for each user ID supported in the device. The two schedule types are a time-fenced weekly schedule and a time-fenced one-time range schedule. When these schedules are configured and enabled, it allows the specified user ID’s code to be active during the time intervals configured in the scheduling slots. + +The Week Day schedule is a day-to-day schedule that will repeat weekly for the enabled user ID. A single schedule slot cannot span days. + +Example: A homeowner has a Secure Keypad Door Lock and a dog that needs walking three times a week. The dog walker can be given access to the house using this schedule. The homeowner would give the dog walker a keypad code that would be active M, W, F from 1pm – 2pm. + +The Year Day schedule is an extended schedule that allows two points in time to be specified that is beyond a daily schedule. A particular slot can span weeks, months or years. Once the end point is reached that schedule slot is no longer valid because it is out of range. + +Example: A homeowner is going away on vacation for two weeks. The homeowner could give the nd th neighbor a keypad code to the neighbor that would be active from April 2, 2008 to April 16 2008. The th code would be invalid after April 16 2008. + +## 4.79.1 Schedule Entry Lock Enable Set Command + +This command enables or disables schedules for a specified user code ID. It affects only the schedules associated with the specific user ID. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE ENTRY LOCK _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE ENTRY LOCK ENABLE SET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| User Identifier | | | | | | | | | | | | | | | | | | | | | | | | +| Enabled | | | | | | | | | | | | | | | | | | | | | | | | + +User Identifier (8 bits) + +The User Identifier is used to recognize the user identity. A valid User Identifier MUST be a value starting from 1 to the maximum number of users supported by the device; refer to the User Code Command Class. If the user identifier is out of range, the command will be ignored. + +Enabled (8 bits) + +Table 113, Schedule Entry Lock Enable Set:: Enabled encoding + +| | Value | | Description | | +| --- | --- | --- | --- | --- | +| 0x00 | | | Schedule for the user identified is disabled | | +| 0x01 | | | Schedule for the user identified is enabled | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +## 4.79.2 Schedule Entry Lock Enable All Set Command + +This command enables or disables all schedules for type Entry Lock. + +| | 7 | 6 | | | 5 | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE ENTRY LOCK _ _ _ _ | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE ENTRY LOCK ENABLE ALL SET _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | +| Enabled | | | | | | | | | | | | | | | | | | | | + +Enabled (8 bits) + +See description in Schedule Entry Lock Enable Set Command. + +## 4.79.3 Schedule Entry Lock Supported Get Command + +This command is used to request the number of schedule slots each type of schedule the device supports for every user. + +The Schedule Entry Lock Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | 6 | | | 5 | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE ENTRY LOCK _ _ _ _ | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE ENTRY TYPE SUPPORTED GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | + +## 4.79.4 Schedule Entry Lock Supported Report Command + +This command is used to report the number of supported schedule slots an Entry Lock schedule device supports for each user in the system. It lists how many schedule slots there are for Week Days type and how many slots for the Year Day type. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE ENTRY LOCK _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE ENTRY TYPE SUPPORTED REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Slots Week Day | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Slots Year Day | | | | | | | | | | | | | | | | | | | | | | | | + +Number of Slots Week Day (8 bits) + +A number from 0 – 255 that represents how many different schedule slots are supported each week for every user in the system for type Week Day. + +Number of Slots Year Day (8 bits) + +A number from 0 – 255 that represents how many different schedule slots are supported for every user in the system for type Year Day. + +## 4.79.5 Schedule Entry Lock Week Day Schedule Set Command + +This command set or erase a weekday schedule for a identified user who already has valid user access code. + +When setting, the week day schedule is automatically enabled and the identified user if it is not already. The start parameters of the time fence needs to occur prior to the stop parameters. When erasing the schedule slot ID, the user code ID will continue to use week day type scheduling. + +Note: Each user can only use one type of scheduling at a time. + +| | 7 | | 6 | | | 5 | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE ENTRY LOCK _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE ENTRY LOCK WEEK DAY SET _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | +| Set Action | | | | | | | | | | | | | | | | | | | | | | +| User Identifier | | | | | | | | | | | | | | | | | | | | | | +| Schedule Slot ID | | | | | | | | | | | | | | | | | | | | | | +| Day of Week | | | | | | | | | | | | | | | | | | | | | | +| Start Hour | | | | | | | | | | | | | | | | | | | | | | +| Start Minute | | | | | | | | | | | | | | | | | | | | | | +| Stop Hour | | | | | | | | | | | | | | | | | | | | | | +| Stop Minute | | | | | | | | | | | | | | | | | | | | | | + +Set Action (8 bits) + +Table 114, Schedule Entry Lock Week Day Schedule Set::Set Action encoding + +| Set Action | | Description | | +| --- | --- | --- | --- | +| 0 | Erase the schedule slot | | | +| 1 | Modify the schedule slot for the identified user | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +User Identifier (8 bits) + +The User Identifier is used to recognize the user identity. A valid User Identifier MUST be a value starting from 1 to the maximum number of users supported by the device; refer to the User Code Command Class. If the user identifier is out of range, the command will be ignored + +Schedule Slot ID (8 bits) + +A value from 1 to Number of Slots Week Day Supported. + +Day of Week (8 bits) + +A value from 0 to 6 where 0 is Sunday. Start Hour (8 bits) + +A value from 0 to 23 representing the starting hour of the time fence. + +Start Minute (8 bits) + +A value from 0 to 59 representing the starting minute of the time fence. + +Stop Hour (8 bits) + +A value from 0 to 23 representing the stop hour of the time fence. + +Stop Minute (8 bits) + +A value from 0 to 59 representing the stop minute of the time fence + +## 4.79.6 Schedule Entry Lock Week Days Schedule Get Command + +This command gets a week day schedule slot for a identified user and specified schedule slot ID. + +The Schedule Entry Lock Week Days Schedule Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE ENTRY LOCK _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE ENTRY LOCK WEEK DAY GET _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| User Identifier | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule Slot ID | | | | | | | | | | | | | | | | | | | | | | | | + +User Identifier (8 bits) + +The User Identifier is used to recognize the user identity. A valid User Identifier MUST be a value starting from 1 to the maximum number of users supported by the device; refer to the User Code Command Class. If the user identifier is out of range, the command will be ignored + +Schedule Slot ID (8 bits) + +A value from 1 to Number of Slots Week Day Supported. + +## 4.79.7 Schedule Entry Lock Week Day Schedule Report Command + +This command returns week day schedule report for the requested schedule slot ID for identified user. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE ENTRY LOCK _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE ENTRY LOCK WEEK DAY REPORT _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| User Identifier | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule Slot ID | | | | | | | | | | | | | | | | | | | | | | | | +| Day of Week | | | | | | | | | | | | | | | | | | | | | | | | +| Start Hour | | | | | | | | | | | | | | | | | | | | | | | | +| Start Minute | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Hour | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Minute | | | | | | | | | | | | | | | | | | | | | | | | + +Refer to the description under the Schedule Set Week Day Schedule. + +Note: If a requested schedule slot is erased/empty, the time fields SHOULD be set to 0xFF. + +## 4.79.8 Schedule Entry Lock Year Day Schedule Set Command + +This command sets or erases a schedule slot for a identified user who already has valid user access code. The year day schedule represents two days, any time apart, where the specified user ID’s code is valid. When setting the schedule slot, the start parameters of the time fence needs to occur prior to the stop parameters and the year day schedule is automatically enabled for the identified user. When erasing, the user code does not change from year day scheduling. + +Note: Each user can only use one type of scheduling at a time. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE ENTRY LOCK _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE ENTRY LOCK YEAR DAY SET _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Set Action | | | | | | | | | | | | | | | | | | | | | | | | +| User Identifier | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule Slot ID | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year | | | | | | | | | | | | | | | | | | | | | | | | +| Start Month | | | | | | | | | | | | | | | | | | | | | | | | +| Start Day | | | | | | | | | | | | | | | | | | | | | | | | +| Start Hour | | | | | | | | | | | | | | | | | | | | | | | | +| Start Minute | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Year | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Month | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Day | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Hour | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Minute | | | | | | | | | | | | | | | | | | | | | | | | + +Set Action (8 bits) + +Table 115, Schedule Entry Lock Year Day Schedule Set:: Set Action encoding + +| | Value | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Erase the schedule slot | | | +| 0x01 | | | Modify the schedule slot for the identified user | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +User Identifier (8 bits) + +The User Identifier is used to recognize the user identity. A valid User Identifier MUST be a value starting from 1 to the maximum number of users supported by the device; refer to the User Code Command Class. If the user identifier is out of range, the command will be ignored Schedule Slot ID (8 bits) + +A value from 1 to Number of Slots Year Day Supported. + +Start Year (8 bits) + +A value from 0 to 99 that represents the 2 year in the century. + +Start Month (8 bits) + +A value from 1 to 12 that represents the month in a year. + +Start Day (8 bits) + +A value from 1 to 31 that represents the date of the month. + +Start Hour (8 bits) + +A value from 0 to 23 representing the starting hour of the time fence. + +Start Minute (8 bits) + +A value from 0 to 59 representing the starting minute of the time fence. + +Stop Year (8 bits) + +A value from 0 to 99 that represents the 2 year in the century. + +Stop Month (8 bits) + +A value from 1 to 12 that represents the month in a year. + +Stop Day (8 bits) + +A value from 1 to 31 that represents the date of the month. + +Stop Hour (8 bits) + +A value from 0 to 23 representing the stop hour of the time fence. + +Stop Minute (8 bits) + +A value from 0 to 59 representing the stop minute of the time fence + +## 4.79.9 Schedule Entry Lock Year Day Schedule Get Command + +This command gets a year/day schedule slot for an identified user and specified schedule slot ID. + +The Schedule Entry Lock Year Day Schedule Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE ENTRY LOCK _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE ENTRY LOCK YEAR DAY GET _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| User Identifier | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule Slot ID | | | | | | | | | | | | | | | | | | | | | | | | + +User Identifier (8 bits) + +The User Identifier is used to recognize the user identity. A valid User Identifier MUST be a value starting from 1 to the maximum number of users supported by the device; refer to the User Code Command Class. If the user identifier is out of range, the command will be ignored + +Schedule Slot ID (8 bits) + +A value from 1 to Number of Slots Year Day Supported. + +## 4.79.10 Schedule Entry Lock Year Day Schedule Report Command + +This command returns year/day schedule report for the requested schedule slot ID for the identified user. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE ENTRY LOCK _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE ENTRY LOCK YEAR DAY REPORT _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| User Identifier | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule Slot ID | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year | | | | | | | | | | | | | | | | | | | | | | | | +| Start Month | | | | | | | | | | | | | | | | | | | | | | | | +| Start Day | | | | | | | | | | | | | | | | | | | | | | | | +| Start Hour | | | | | | | | | | | | | | | | | | | | | | | | +| Start Minute | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Year | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Month | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Day | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Hour | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Minute | | | | | | | | | | | | | | | | | | | | | | | | + +Refer to the description under Schedule Set Year Day Schedule command. + +Note: If a requested schedule slot is erased/empty the time fields SHOULD be set to 0xFF. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.80-schedule-entry-lock-command-class-version-2-deprecated.md b/docs/specs/command-class-specification/04-command-class-definitions/04.80-schedule-entry-lock-command-class-version-2-deprecated.md new file mode 100644 index 0000000..89a7307 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.80-schedule-entry-lock-command-class-version-2-deprecated.md @@ -0,0 +1,77 @@ + +# 4.80 Schedule Entry Lock Command Class, version 2 [DEPRECATED] + +THIS COMMAND CLASS HAS BEEN DEPRECATED + +A device MAY implement this command class, but it is RECOMMENDED that new implementations use the Schedule Command Class. If implementing this command class, it is RECOMMENDED that the Schedule Command Class is also implemented. + +The Schedule Entry Lock Command Class provides Z-Wave devices the capability to exchange scheduling information. The Schedule Entry Lock Type Commands are for controlling the schedules of an Entry Lock using schedule based user code Ids. The Entry Lock supports two types of schedules for each user ID supported in the device. The two schedule types are a time-fenced weekly schedule and a time-fenced one-time range schedule. When these schedules are configured and enabled, it allows the specified user ID’s code to be active during the time intervals configured in the scheduling slots. + +In Version 2 local time is used instead of UTC time, and Time Offset commands are added. + +The commands not mentioned here remain the same as in version 1. + +## 4.80.1 Schedule Entry Lock Time Offset Get Command + +This command is used to request time zone offset and daylight savings parameters. + +The Schedule Entry Lock Time Offset Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE ENTRY LOCK _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE ENTRY LOCK TIME OFFSET GET _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.80.2 Schedule Entry Lock Time Offset Set Command + +This command is used to set the current local TZO and DST offsets into an Entry Lock Device. Any schedules that are already in the device before or after issuing the Schedule Entry Time Offset Set command are now assumed to be programmed in the Local time set by this command. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE ENTRY LOCK _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE ENTRY LOCK TIME OFFSET SET _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sign TZO | | | Hour TZO | | | | | | | | | | | | | | | | | | | | | +| Minute TZO | | | | | | | | | | | | | | | | | | | | | | | | +| Sign Offset DST | | | Minute Offset DST | | | | | | | | | | | | | | | | | | | | | + +Sign TZO (1 bit) + +Plus (0) or minus (1) sign to indicate a positive or negative offset from UTC. + +Hour TZO (7 bits) + +Specify the number of hours that the originating time zone deviates from UTC. Refer to the DST field regarding daylight savings handling. + +Minute TZO (7 bits) + +Specify the number of minutes that the originating time zone deviates UTC. Refer to the DST field regarding daylight savings handling. + +Sign Offset DST (1 bit) + +Plus (0) or minus (1) sign to indicate a positive or negative offset from UTC. + +Minute Offset DST (7 bits) + +This field MUST specify the number of minutes the time is to be adjusted when daylight savings mode is enabled. + +## 4.80.3 Schedule Entry Lock Time Offset Report Command + +This command is used to advertise the time zone offset and daylight savings parameters. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE ENTRY LOCK _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE ENTRY LOCK TIME OFFSET REPORT _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sign TZO | | | Hour TZO | | | | | | | | | | | | | | | | | | | | | +| Minute TZO | | | | | | | | | | | | | | | | | | | | | | | | +| Sign Offset DST | | | Minute Offset DST | | | | | | | | | | | | | | | | | | | | | + +Refer to description under the Schedule Entry Lock Time Offset Set command. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.81-schedule-entry-lock-command-class-version-3-deprecated.md b/docs/specs/command-class-specification/04-command-class-definitions/04.81-schedule-entry-lock-command-class-version-3-deprecated.md new file mode 100644 index 0000000..adfe896 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.81-schedule-entry-lock-command-class-version-3-deprecated.md @@ -0,0 +1,147 @@ + +# 4.81 Schedule Entry Lock Command Class, Version 3 [DEPRECATED] + +THIS COMMAND CLASS HAS BEEN DEPRECATED + +A device MAY implement this command class, but it is RECOMMENDED that new implementations use the Schedule Command Class. If implementing this command class, it is RECOMMENDED that the Schedule Command Class is also implemented. + +The Schedule Entry Lock Command Class provides a scheduling type alongside the existing types Week Day and Year Day. The new type is similar to Week Day functionality but provides a simpler implementation to repeat a time slot daily (selected days) and repeat those days weekly. The commands not mentioned here remain the same as in Version 2. + +## 4.81.1 Schedule Entry Type Supported Report Command + +This command is used to report the number of supported schedule slots an Entry Lock schedule device supports for each user in the system. It lists how many schedule slots there are for Week Day, Year Day, and Daily Repeating types. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE ENTRY LOCK _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE ENTRY TYPE SUPPORTED REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Slots Week Day | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Slots Year Day | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Slots Daily Repeating | | | | | | | | | | | | | | | | | | | | | | | | + +Number of Slots Week Day (8 bits) + +A number from 0 to 255 that represents how many different schedule slots are supported each week for every user in the system for type Week Day. + +Number of Slots Year Day (8 bits) + +A number from 0 to 255 that represents how many different schedule slots are supported for every user in the system for type Year Day. + +Number of Slots Daily Repeating (8 bits) + +A number from 0 to 255 that represents how many different schedule slots are supported for every user in the system for type Daily Repeating Day. + +## 4.81.2 Schedule Entry Lock Daily Repeating Set Command + +This command is used to set or erase a daily repeating schedule for an identified user who already has valid user access code. + +When setting; the daily repeating schedule is automatically enabled for the identified user if it is not already. The start parameters of the time fence needs to occur prior to the stop parameters. When erasing the schedule slot ID, the user code ID will continue to use daily repeating type scheduling. + +Note: Each user can only use one type of scheduling at a time. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE ENTRY LOCK _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE ENTRY LOCK DAILY REPEATING SET _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Set Action | | | | | | | | | | | | | | | | | | | | | | | | +| User Identifier | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule Slot ID | | | | | | | | | | | | | | | | | | | | | | | | +| Week Day Bitmask | | | | | | | | | | | | | | | | | | | | | | | | +| Start Hour | | | | | | | | | | | | | | | | | | | | | | | | +| Start Minute | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Hour | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Minute | | | | | | | | | | | | | | | | | | | | | | | | + +Set Action (8 bits) + +Table 116, Schedule Entry Lock Daily Repeating Set:: Set Action encoding + +| | Value | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Erase the schedule slot | | | +| 0x01 | | | Modify the schedule slot for the identified user | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +User Identifier (8 bits) + +The User Identifier is used to recognize the user identity. A valid User Identifier MUST be a value starting from 1 to the maximum number of users supported by the device; refer to the User Code Command Class. If the user identifier is out of range, the command will be ignored + +Schedule Slot ID (8 bits) + +A value from 1 to Number of Slots Daily Repeating Supported. + +Week Day Bitmask (8 bits) + +A bitmask of the days of the week for this schedule entry is active. Table 117, Schedule Entry Lock Daily Repeating Set:: Week Day Bitmask encoding + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Res | | | Sat | | | Fri | | | Thr | | | Wed | | | Tue | | | Mon | | | Sun | | | + +Bit 7 6 5 4 3 2 1 0 + +Value Res Sat Fri Thr Wed Tue Mon Sun + +The ‘Res’ bit is reserved and MUST be set to zero by a sending node. Reserved bits MUST be ignored by a receiving node. + +Start Hour (8 bits) + +A value from 0 to 23 representing the starting hour of the time fence. + +Start Minute (8 bits) + +A value from 0 to 59 representing the starting minute of the time fence. + +Duration Hour (8 bits) + +A value from 0 to 23 representing how many hours the time fence will last. Duration hour will be maxed at the documented capability of the specific device since this scheduling type is memory conscious. + +Duration Minute (8 bits) + +A value from 0 to 59 representing how many minutes the time fence will last past the Duration Hour field. + +## 4.81.3 Schedule Entry Lock Daily Repeating Get Command + +This command is used to request a daily repeating schedule slot for a identified user and specified schedule slot ID. + +The Schedule Entry Lock Daily Repeating Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE ENTRY LOCK _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE ENTRY LOCK DAILY REPEATING GET _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| User Identifier | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule Slot ID | | | | | | | | | | | | | | | | | | | | | | | | + +User Identifier (8 bits) + +The User Identifier is used to recognize the user identity. A valid User Identifier MUST be a value starting from 1 to the maximum number of users supported by the device; refer to the User Code Command Class. If the user identifier is out of range, the command will be ignored Schedule Slot ID (8 bits) + +A value from 1 to Number of Slots Daily Repeating Supported. + +## 4.81.4 Schedule Entry Lock Daily Repeating Report + +This command is used to return the requested schedule slot ID for identified user. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCHEDULE ENTRY LOCK _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCHEDULE ENTRY LOCK DAILY REPEATING REPORT _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| User Identifier | | | | | | | | | | | | | | | | | | | | | | | | +| Schedule Slot ID | | | | | | | | | | | | | | | | | | | | | | | | +| Week Day Bitmask | | | | | | | | | | | | | | | | | | | | | | | | +| Start Hour | | | | | | | | | | | | | | | | | | | | | | | | +| Start Minute | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Hour | | | | | | | | | | | | | | | | | | | | | | | | +| Duration Minute | | | | | | | | | | | | | | | | | | | | | | | | + +Refer to the description under the Schedule Set Daily Repeating Schedule. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.82-screen-attributes-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.82-screen-attributes-command-class-version-1.md new file mode 100644 index 0000000..a160b62 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.82-screen-attributes-command-class-version-1.md @@ -0,0 +1,65 @@ + +# 4.82 Screen Attributes Command Class, version 1 + +The Screen Attribute Command Class is used to retrieve screen attributes from the device hosting the screen. This allows another device to send data formatted according to the screen attributes to the device hosting the screen. The screen may be located on any device in the network. + +## 4.82.1 Screen Attributes Get Command + +This command is used to request the screen attributes. + +The Screen Attributes Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCREEN ATTRIBUTES _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCREEN ATTRIBUTES GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.82.2 Screen Attributes Report Command + +This command is used to advertise the screen attributes. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCREEN ATTRIBUTES _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCREEN ATTRIBUTES REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Number of Lines | | | | | | | | | | | | | | | +| Characters per Line | | | | | | | | | | | | | | | | | | | | | | | | +| Line Buffer Size | | | | | | | | | | | | | | | | | | | | | | | | +| Character Encoding | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Number of Lines (5 bits) + +Number of lines the screen supports (1..16). + +Characters per Line (8 bits) + +Number of characters the screen supports on each line (1..255). Line Buffer Size (8 bits) + +Number of characters the line buffer supports for each line (1..255). Size of line buffer will always be equal or larger than the number of visual characters per line. The text will typically scroll in case it is larger than the number of visual characters. + +Character Encoding (8 bits) + +The screen supports the following numerical representations of a character: + +Table 118, Screen Attributes Report::Character Encoding encoding + +| | Bit Map | | | Description | | +| --- | --- | --- | --- | --- | --- | +| Bit 0 | | | Supports ASCII codes if the bit is 1 and the opposite if 0. See APPENDIX A (values 128-255 are ignored) | | | +| Bit 1 | | | Supports ASCII codes and Extended ASCII codes if the bit is 1 and the opposite if 0. See APPENDIX A | | | +| Bit 2 | | | Supports Unicode UTF-16 if the bit is 1 and the opposite if 0. | | | +| Bit 3 | | | Supports ASCII codes and Player codes, see APPENDIX A (undefined values are ignored) | | | + +All other bits are reserved and MUST be set to zero by a sending node. Reserved bits MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.83-screen-attributes-command-class-version-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.83-screen-attributes-command-class-version-2.md new file mode 100644 index 0000000..d555f1f --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.83-screen-attributes-command-class-version-2.md @@ -0,0 +1,54 @@ + +# 4.83 Screen Attributes Command Class, version 2 + +The Screen Attribute Command Class, version 2 introduces the Screen Timeout of the Screen Attributes Command. + +Details not mentioned remain the same as in version 1. + +## 4.83.1 Screen Attributes Report Command + +This command is used to advertise the screen attributes. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCREEN ATTRIBUTES _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCREEN ATTRIBUTES REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | Escape Sequence | | | Number of Lines | | | | | | | | | | | | | | | +| Characters per Line | | | | | | | | | | | | | | | | | | | | | | | | +| Line Buffer Size | | | | | | | | | | | | | | | | | | | | | | | | +| Character Encoding | | | | | | | | | | | | | | | | | | | | | | | | +| Screen Timeout | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Escape Sequence(1 bit) + +If set to 0, escape sequences are not supported by the device. If set to 1, escape sequences are supported by the device. + +Number of Lines (5 bits) + +Number of lines the screen supports (1..16). + +Characters per Line (8 bits) + +Number of characters the screen supports on each line (1..255). + +Line Buffer Size (8 bits) + +Number of characters the line buffer supports for each line (1..255). Size of line buffer will always be equal or larger than the number of visual characters per line. The text will typically scroll in case it is larger than the number of visual characters. Character Encoding (8 bits) + +[This field MUST be encoded according to Table 118](04.82-screen-attributes-command-class-version-1.md#4822-screen-attributes-report-command) + +All other bits are reserved and MUST be set to zero by a sending node. Reserved bits MUST be ignored by a receiving node. + +Screen Timeout (8 bits) + +If Screen Timeout is set to 0, the display is always on. A value larger than 0 MUST specify the display timeout in seconds. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.84-screen-meta-data-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.84-screen-meta-data-command-class-version-1.md new file mode 100644 index 0000000..4bd13e9 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.84-screen-meta-data-command-class-version-1.md @@ -0,0 +1,141 @@ + +# 4.84 Screen Meta Data Command Class, version 1 + +The Screen Meta Data Command Class is used to streaming data containing user related information to a screen located on a device in a Z-Wave network. The screen can request single or multiple data packets. The device having the data containing user related information to the screen can also initiate the data streaming. + +In order not to congest the Z-Wave network, large data transfers MUST leave transmit opportunities for other nodes in the network. If sending a command longer than two frames, a node MUST implement a delay between every transmitted frame. The minimum required time delay and number of frames before a delay must be inserted depends on the actual bit rate. + + 40 kbit/s: At least 35 ms if sending more than 2 frames back-to-back  100 kbit/s: At least 15 ms if sending more than 2 frames back-to-back + +## 4.84.1 Screen Meta Data Get Command + +This command is used to request the Screen Meta Data Report Command. The Screen Meta Data Get Command is used as handshake to avoid buffer overflow in the receiving node. The Screen Meta Data Get Command will optionally be able to request multiple Screen Meta Data Report Commands to improve the effective bandwidth. + +The Screen Meta Data Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCREEN MD _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCREEN MD GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Number of Reports | | | | | | | | | | | | | | | | | | | | | | | | +| NodeID | | | | | | | | | | | | | | | | | | | | | | | | + +Number of Reports (8 bits) + +Number of Screen Meta Data Report Commands to be received without requesting each Screen Meta Data Report Command (1..255). Be aware of overflow when requesting multiple reports. + +NodeID (8 bits) + +The NodeID (1..232) specifies the device to receive the requested reports. In case NodeID is equal to 0x00, the information is requested by the source NodeID of the Screen Meta Data Get Command. + +## 4.84.2 Screen Meta Data Report Command + +This command is used to send data to the device hosting the screen. + +The size of the payload SHOULD NOT be bigger than 48 bytes. It is possible to write characters to multiple lines in the same frame. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCREEN MD _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCREEN MD REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| More Data | | | Reser- ved | | | Screen Settings | | | | | | | | | Character Encoding | | | | | | | | | +| | Line Settings A | | | | | | | | | Clear A | | | Line Number A | | | | | | | | | | | +| | Character Position A | | | | | | | | | | | | | | | | | | | | | | | +| | Number of Characters A | | | | | | | | | | | | | | | | | | | | | | | +| | Character 1,A | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Character N,A | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Line Settings B | | | | | | | | | Clear B | | | Line Number B | | | | | | | | | | | +| | Character Position B | | | | | | | | | | | | | | | | | | | | | | | +| | Number of Characters B | | | | | | | | | | | | | | | | | | | | | | | +| | Character 1,B | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Character N,B | | | | | | | | | | | | | | | | | | | | | | | + +More Data (1 bit) + +The more data bit indicates if additional reports are expected before the whole data streaming is completed. If the more data bit is set to 1 then additional reports are expected and the opposite if 0. Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Screen Settings (3 bits) + +[This field MUST comply with Table 119:](04.84-screen-meta-data-command-class-version-1.md#4842-screen-meta-data-report-command) + +[Table 119, Screen Meta Data Report::Screen Settings encoding](04.84-screen-meta-data-command-class-version-1.md#4842-screen-meta-data-report-command) + +| | Screen Settings | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0 | | | Whole screen is cleared before lines are written | | | +| 1 | | | Current content on screen is scrolled one line down | | | +| 2 | | | Current content on screen is scrolled one line up | | | +| 7 | | | Do not change the current content on the screen | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Character Encoding (3 bits) + +[This field MUST comply with Table 120:](04.84-screen-meta-data-command-class-version-1.md#4842-screen-meta-data-report-command) + +Table 120, Screen Meta Data Report::Character Encoding encoding + +| | Character Encoding | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0 | | | Using standard ASCII codes, see APPENDIX A (values 128-255 are ignored) | | | +| 1 | | | Using standard ASCII codes and OEM Extended ASCII codes, see APPENDIX A | | | +| 2 | | | Unicode UTF-16 | | | +| 3 | | | Using standard ASCII codes and Player codes, see APPENDIX A (undefined values are ignored) | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Note: Devices supporting Unicode UTF-16 characters are described by a 2 byte long decimal representation. The first byte is the most significant byte. E.g. if there is one Unicode character in the set frame the char 1 will be MSB and char 2 will be LSB of the Unicode character. Line Settings (3 bits) + +[This field MUST comply with Table 121:](04.84-screen-meta-data-command-class-version-1.md#4842-screen-meta-data-report-command) + +Table 121, Screen Meta Data Report::Line Settings encoding + +| | Line Settings | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0 | | | Characters are written in selected font | | | +| 1 | | | Characters are written as highlighted | | | +| 2 | | | Characters are written using a larger font compared to line settings equal to 0 | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Clear (1 bit) + +Determine if the characters are written directly or line is cleared first. + +Table 122, Screen Meta Data Report::Clear encoding + +| | Clear | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0 | | | Characters are written directly | | | +| 1 | | | Line is cleared before characters are written | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Line Number (4 bits) + +The line number field indicates the line to write the characters to counting from zero (0..15). + +Character Position (8 bits) + +The character position field indicates where on the line to write the characters counting from zero (0..255). The character position may be larger than the display size in case the line buffer is bigger (See the Screen Attributes Report Command). + +Number of Characters (8 bits) + +The number of characters field indicates how many characters to be written on the screen for the specified line number, counting from 1. + +Character (N bytes) + +The character fields hold the string to output in specified character representation. Characters will be ignored in case there is no room left in the line buffer. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.85-screen-meta-data-command-class-version-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.85-screen-meta-data-command-class-version-2.md new file mode 100644 index 0000000..a5bd618 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.85-screen-meta-data-command-class-version-2.md @@ -0,0 +1,103 @@ + +# 4.85 Screen Meta Data Command Class, version 2 + +The Screen Meta Data Command Class, version 2 introduces a Screen Timeout bit. The support for the Screen Timeout bit may be advertised by the Screen Attribute Command Class, version 2. + +Details not mentioned remain the same as in version 1. + +## 4.85.1 Screen Meta Data Report Command + +This command is used to transfer data to the device hosting the screen. The size of the payload MUST NOT be bigger than 48 bytes. It is possible to write characters to multiple lines in the same frame. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SCREEN MD _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SCREEN MD REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| More Data | | | Ex- tended Setup | | | Screen Settings | | | | | | | | | Character Encoding | | | | | | | | | +| | Line Settings A | | | | | | | | | Clear A | | | Line Number A | | | | | | | | | | | +| | Character Position A | | | | | | | | | | | | | | | | | | | | | | | +| | Number of Characters A | | | | | | | | | | | | | | | | | | | | | | | +| | Character 1,A | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Character N,A | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Line Settings B | | | | | | | | | Clear B | | | Line Number B | | | | | | | | | | | +| | Character Position B | | | | | | | | | | | | | | | | | | | | | | | +| | Number of Characters B | | | | | | | | | | | | | | | | | | | | | | | +| | Character 1,B | | | | | | | | | | | | | | | | | | | | | | | +| | … | | | | | | | | | | | | | | | | | | | | | | | +| | Character N,B | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | | | | Screen Timeout | | | + +More Data (1 bit) + +The more data bit indicates if additional reports are expected before the whole data streaming is completed. If the more data bit is set to 1 then additional reports are expected and the opposite if 0. Extended Setup (1 bit) + +If set to true, the last byte of the payload defines an extended setup. + +Screen Settings (3 bits) + +[The screen settings identifier MUST be encoded according to Table 119.](04.84-screen-meta-data-command-class-version-1.md#4842-screen-meta-data-report-command) + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Character Encoding (3 bits) + +[The Character Encoding identifier MUST be encoded according to Table 120.](04.84-screen-meta-data-command-class-version-1.md#4842-screen-meta-data-report-command) + +Note: Devices supporting Unicode UTF-16 characters are described by a 2 byte long decimal representation. The first byte is the most significant byte. E.g. if there is one Unicode character in the set frame the char 1 will be MSB and char 2 will be LSB of the Unicode character. + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Line Settings (3 bits) + +[The line settings identifier MUST be encoded according to Table 123.](04.85-screen-meta-data-command-class-version-2.md#4851-screen-meta-data-report-command) + +Table 123, Screen Meta Data Report version 2::Line Settings encoding + +| | Line Settings | | | Description | | | Version | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 0 | | | Characters are written in selected font | | | 1 | | | +| 1 | | | Characters are written as highlighted | | | 1 | | | +| 2 | | | Characters are written using a larger font compared to line settings equal to 0 | | | 1 | | | +| 3 | | | Characters are written using a larger font (font B) & highlighted | | | 2 | | | +| 4 | | | Characters are written in selected font (font A), no scroll | | | 2 | | | +| 5 | | | Characters are written in selected font (font A) & highlighted, no scroll | | | 2 | | | +| 6 | | | Characters are written using a larger font (font B), no scroll | | | 2 | | | +| 7 | | | Characters are written using a larger font (font B) & highlighted, no scroll | | | 2 | | | + +For values 0-3, text will be scrolled. For values 4-7 the text will not be scrolled, and will be truncated if it is longer than the width of the display. + +Clear (1 bit) + +[Determine if the characters are written directly or line is cleared first. Refer to Table 122](04.84-screen-meta-data-command-class-version-1.md#4842-screen-meta-data-report-command) + +Line Number (4 bits) + +The line number field indicates the line to write the characters to counting from zero (0..15). Character Position (8 bits) + +The character position field indicates where on the line to write the characters counting from zero (0..255). The character position MAY be larger than the display size in case the line buffer is bigger (See the Screen Attributes Report Command). + +Number of Characters (8 bits) + +The number of characters field indicates how many characters to be written on the screen for the specified line number, counting from 1. + +Character (N bytes) + +The character fields hold the string to output in specified character representation. Characters will be ignored in case there is no room left in the line buffer. If the Escape Sequence Bit is true in the SCREEN_ATTRIBUTES_REPORT Command, the device supports advanced display features by making escape sequences in the form of an Escape char followed by a char value 0..255. + +Screen Timeout (1 bit) + +If the screen timeout is set to 0 the preset timeout SHOULD be used. + +If set to 1 the device SHOULD keep the display powered. This does not affect the RF. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.86-sensor-configuration-command-class-version-1-obsoleted.md b/docs/specs/command-class-specification/04-command-class-definitions/04.86-sensor-configuration-command-class-version-1-obsoleted.md new file mode 100644 index 0000000..8f3245e --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.86-sensor-configuration-command-class-version-1-obsoleted.md @@ -0,0 +1,112 @@ + +# 4.86 Sensor Configuration Command Class, version 1 [OBSOLETED] + +THIS COMMAND CLASS HAS BEEN OBSOLETED + +New implementations MUST NOT use the Sensor Configuration Command Class. Refer to the Configuration Command Classes. + +The Sensor Configuration Command Class adds the possibility for sensors to act on either a measured value or on a preconfigured value. With this command class an application can act on a specific event. It is up to the application to implement the actual event. This could e.g. be implementation of the Association Command Class where the application would activate a group based on a trigger from the sensor. + +The trigger types that may be configured are the same types as the values specified in the Multilevel Sensor Command Class + +Most movement sensors may be configured to "ignore" movement if it is not dark. Typically this is done manually. With the Sensor Configuration Command Class this may be configured remotely in a standardised way. + +A device supporting the Sensor Configuration Command Class may be configured via the trigger level, but the decision on what the level change should trigger is up to the application. For the movement sensor this trigger level could be an input parameter to the logic that controls the light. + +## 4.86.1 Sensor Trigger Level Set Command + +This command is used to set different triggers to either a specified value or to the current measured value. The Command also supports to restore a factory default value. + +All configurable trigger types and values MUST be mapped directly from the Multilevel Sensor Command Class. + +It is RECOMMENDED that all combinations of precision, scale and size parameters are supported. The Set command MUST support same format of precision, scale and size parameters as can be returned in the report command. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR CONFIGURATION _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR TRIGGER LEVEL SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Default | | | Current | | | Reserved | | | | | | | | | | | | | | | | | | +| Sensor Type | | | | | | | | | | | | | | | | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | | | | +| Trigger Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Trigger Value N | | | | | | | | | | | | | | | | | | | | | | | | + +Default (1 bit) + +Reset level of trigger type to factory default when this bit is set to 1. If any value is set in this frame when the Default bit is 1 this value will be ignored. + +Current (1 bit) + +The current measured value will be stored as trigger value when this bit is set to 1. The trigger value in this frame will be ignored when the Current bit is set to 1. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Precision (3 bits) + +The precision field describes what the precision of the trigger value is. The number indicates the number of decimals. The decimal value 1025 with precision 2 is therefore equal to 10.25. + +Scale (2 bits) + +The Scale used to indicate what unit the trigger uses. Refer to the table in the Multilevel Sensor Command Class with respect to defined scales for the relevant triggers. Scales are defined by the Z-Wave Alliance. Size (3 bits) + +The size field indicates the number of bytes used for the Trigger Value field. This field can take values from 1 (001b), 2 (010b) or 4 (100b). + +Sensor Type (8 bits) + +The Sensor Type specifies what type of trigger this Command will set. Refer to the Multilevel Sensor Command Class specification, where Sensor Type is defined in the Multilevel Sensor Report Command. + +Trigger Value (N bytes) + +Refer to the Multilevel Sensor Report Command for information on what trigger values to set. + +## 4.86.2 Sensor Trigger Level Get Command + +This command can request the stored trigger level. + +The Sensor Trigger Level Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR CONFIGURATION _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR TRIGGER LEVEL GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.86.3 Sensor Trigger Level Report Command + +This command returns the stored trigger value. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR CONFIGURATION _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR TRIGGER LEVEL REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sensor Type | | | | | | | | | | | | | | | | | | | | | | | | +| Precision | | | | | | | | | Scale | | | | | | Size | | | | | | | | | +| Trigger Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Trigger Value N | | | | | | | | | | | | | | | | | | | | | | | | + +For fields’ description, refer to the Sensor Trigger Level Set Command. + +## 4.86.4 Mapping example + +The report structure of the Multilevel Sensor Command Class can be mapped direct into the Sensor Configuration Set Command Class. This example frame below will set the trigger level in the receiving node to 10.25 degree Celsius. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SENSOR CONFIGURATION _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SENSOR TRIGGER LEVEL SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Default(0) | | | Current(0) | | | Reserved | | | | | | | | | | | | | | | | | | +| Temperature (0x01) | | | | | | | | | | | | | | | | | | | | | | | | +| Precision (010b) | | | | | | | | | Celsius (00b) | | | | | | Size (010b) | | | | | | | | | +| 0x04 | | | | | | | | | | | | | | | | | | | | | | | | +| 0x01 | | | | | | | | | | | | | | | | | | | | | | | | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.87-simple-av-control-command-class-version-1-4.md b/docs/specs/command-class-specification/04-command-class-definitions/04.87-simple-av-control-command-class-version-1-4.md new file mode 100644 index 0000000..0c7bc58 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.87-simple-av-control-command-class-version-1-4.md @@ -0,0 +1,130 @@ + +# 4.87 Simple AV Control Command Class, version 1-4 + +The Simple AV Control Command Class is used to control an AV device in a Z-Wave network. The Simple AV Control Command Class is suited for IR remote replacement. Furthermore, this command class supports Windows Vista Media Center and Media Center 2005 remote controls. + +## 4.87.1 Simple AV Control Set Command + +This command is used to control an AV device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SIMPLE AV CONTROL _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SIMPLE AV CONTROL SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Sequence Number | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | Key Attributes | | | | | | | | | +| Reseved [OBSOLETED] | | | | | | | | | | | | | | | | | | | | | | | | +| Reseved [OBSOLETED] | | | | | | | | | | | | | | | | | | | | | | | | +| | Command MSB,1 | | | | | | | | | | | | | | | | | | | | | | | +| | Command LSB,1 | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Command MSB,N | | | | | | | | | | | | | | | | | | | | | | | +| | Command LSB,N | | | | | | | | | | | | | | | | | | | | | | | + +Sequence Number (8 bits) + +The sequence number is incremented each time a Simple AV Control Set Command is issued. The receiving node uses the sequence number to ignore duplicates. + +Key Attributes (3 bits) + +The key attributes specifies the state of the key. Currently the following key attribute definitions exist: Table 124, Simple AV Control Set::Key Attributes encoding + +| | Key Attribute | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | Key Down – Sent when a new key is pressed. It is mandatory to send a Simple AV Control Set Command when this event occurs. | | | +| 0x01 | | | Key Up – Sent when the key is released. It is optional to send a Simple AV Control Set Command when this event occurs. Only the sequence number and key attribute parameter is changed in the Command. | | | +| 0x02 | | | Keep Alive – Sent every 100-200ms while the key is still held down. Event used as a failsafe feature for the ramping function, e.g. avoid volume jumps to maximum in case a key up event is not received. The keep alive event can also be used to control the speed of the ramping function, e.g. the first few seconds of the key held down is the speed slow and afterwards will it gradually accelerate. It is optional to send a Simple AV Control Set Command when this event occurs. Only the sequence number and key attribute parameter is changed in the Command. | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Un-supported key attribute values MUST be ignored. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Command MSB, Command LSB (N * 16 bits) + +This field is used to carry the AV Control command. + +[Each 16 bits-unit MUST carry a defined AV Control code. Refer to [19] for the defined AV Control codes. Values not defined in [19] are reserved and MUST NOT be used.](04.107-window-covering-command-class-version-1.md#410710-window-covering-stop-level-change-command) + +It is possible to specify a sequence of AV commands in one frame. If an AV control command is not supported, it MUST be ignored by a receiving node. + +Command numbers 1 through 40 are the most popular commands used in AV remotes. Command numbers 41 through 363 are less popular and is sorted in alphanumerical order. Support for Windows Vista Media Center and Media Center 2005 remote controls is added with command numbers from 364 to 377 including 16, 200 and 231. + +## 4.87.2 Simple AV Control Get Command + +This command is used to request the number of reports necessary to report the supported AC Commands from the device. + +The Simple AV Control Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SIMPLE AV CONTROL _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SIMPLE AV CONTROL GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.87.3 Simple AV Control Report Command + +This command is used to report the necessary number of reports to report the supported AC Commands from the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SIMPLE AV CONTROL _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SIMPLE AV CONTROL REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Number of reports | | | | | | | | | | | | | | | | | | | | | | | | + +Number of reports (8 bits) + +The number of reports necessary to report the entire list of supported AC Commands. + +## 4.87.4 Simple AV Control Supported Get Command + +This command is used to request the AV Commands supported by the AV device. + +The Simple AV Control Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SIMPLE AV CONTROL _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SIMPLE AV CONTROL SUPPORTED GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Report No | | | | | | | | | | | | | | | | | | | | | | | | + +Report No (8 bits) + +Report no. field is used to request wanted report number. The report no. values MUST be a sequence starting from 1. + +## 4.87.5 Simple AV Control Supported Report Command + +This command is used to report the supported AC Commands from the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SIMPLE AV CONTROL _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SIMPLE AV CONTROL SUPPORTED REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Report No | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | | + +Report No (8 bits) + +Report no. field specify the request report number. + +Bit Mask (N bytes) + +The Bit Mask fields describe the supported AV Control Commands by the device. + + Bit 0 in Bit Mask 1 indicates if Command #1 is supported.  Bit 1 in Bit Mask 1 indicates if Command #2 is supported.  … + +If a Command is supported, the bit MUST be set to 1. If a Command is not supported, the bit MUST be set to 0. It is only necessary to send the Bit Mask fields from 1 and up to the one indicating the last supported Command #. Mask fields bigger than 45 bytes not allowed. The number of Bit Mask fields transmitted MUST be determined from the length field in the frame. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.88-sound-switch-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.88-sound-switch-command-class-version-1.md new file mode 100644 index 0000000..02e7cc6 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.88-sound-switch-command-class-version-1.md @@ -0,0 +1,255 @@ + +# 4.88 Sound Switch Command Class, version 1 + +The Sound Switch Command Class is used to manage nodes with a speaker or sound notification capability. It can be used for a doorbell, alarm clock, siren or any device issuing sound notifications. + +## 4.88.1 Terminology + +A Sound Switch is a sound notification device with pre-recorded tones. A tone can be a short sound effect as well as an entire song. The volume setting can be configured and the node will subsequently play tones using the configured volume for any tone. A default tone can also be configured, allowing the Sound Switch to play same sound when controlled by a node without the ability to select between tones. + +A Sound Switch node advertises a name and duration for each tone. This information is used to guide an end-user in its tone selection and helps controlling nodes to know when the tone is finished playing. + +## 4.88.2 Compatibility considerations + +[The Sound Switch Command Class is an actuator control Command Class. Refer to section 3.6.](../03-command-class-overview/03.06-actuator-control.md#36-actuator-control) + +A node supporting this Command Class MUST support at least 1 tone. + +The implemented tone identifier values MUST be in a sequence starting from 1, i.e. a node supporting 10 tones MUST accept Tone Identifiers in the range 1..10. + +## 4.88.3 Sound Switch Tones Number Get Command + +This command is used to request the number of tones supported by the receiving node. + +[The Sound Switch Tones Number Report Command MUST be returned in response to this command.](04.88-sound-switch-command-class-version-1.md#4884-sound-switch-tones-number-report-command) + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SOUND SWITCH _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SOUND SWITCH TONES NUMBER GET (0x01) _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.88.4 Sound Switch Tones Number Report Command + +This command is used to advertise the number of tones supported by the sending node. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SOUND SWITCH _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SOUND SWITCH TONES NUMBER REPORT (0x02) _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Supported Tones | | | | | | | | | | | | | | | | | | | | | | | | + +Supported Tones (8 bits) + +This field MUST be set to the total amount of supported tones. This field MUST be in the range 1..255. + +## 4.88.5 Sound Switch Tone Info Get Command + +This command is used to query the information associated to a tone at a supporting node. + +[The Sound Switch Tone Info Report MUST be returned in response to this command.](04.88-sound-switch-command-class-version-1.md#4886-sound-switch-tone-info-report-command) + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SOUND SWITCH _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SOUND SWITCH TONE INFO GET (0x03) _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Tone Identifier | | | | | | | | | | | | | | | | | | | | | | | | + +Tone Identifier (8 bits) + +This field is used to specify the requested Tone Identifier. + +The implemented tone identifier values MUST be in a sequence starting from 1, i.e. a node supporting 10 tones MUST accept Tone Identifiers in the range 1..10. + +A sending node MUST specify a Tone Identifier that is supported by a receiving node, i.e. in the range 1..{Total number of supported tones}. + +A node receiving this command for an unsupported Tone Identifier or for Tone Identifier 0x00 MUST return a zero duration and a zero length name. + +## 4.88.6 Sound Switch Tone Info Report Command + +This command is used to advertise the information associated to a tone at a supporting node. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SOUND SWITCH _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SOUND SWITCH TONE INFO REPORT (0x04) _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Tone Identifier | | | | | | | | | | | | | | | | | | | | | | | | +| Tone Duration 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Tone Duration 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Name Length | | | | | | | | | | | | | | | | | | | | | | | | +| Name 1 | | | | | | | | | | | | | | | | | | | | | | | | +| ... | | | | | | | | | | | | | | | | | | | | | | | | +| Name N | | | | | | | | | | | | | | | | | | | | | | | | + +Tone Identifier (8 bits) + +This field is used to advertise the Tone Identifier for which the associated information is being advertised. + +Tone Duration (16 bits) + +This field is used to advertise duration of the Tone Identifier. + +This field MUST indicate the time in seconds it takes to play the actual Tone Identifier. + +This field MUST be set to 0 if the Tone Identifier is set to 0x00 or a value higher than the total number of [supported tones advertised in the Sound Switch Tones Number Report Command.](04.88-sound-switch-command-class-version-1.md#4884-sound-switch-tones-number-report-command) + +Name Length (8 bits) + +This field indicates the length in bytes of the Name field. This field MUST be in the range 1..255 if the Tone Identifier is supported. + +This field MUST be set to 0 if the Tone Identifier is set to 0x00 or a value higher than the total number of [supported tones advertised in the Sound Switch Tones Number Report Command.](04.88-sound-switch-command-class-version-1.md#4884-sound-switch-tones-number-report-command) + +Name (N bytes) + +This field is used to indicate the assigned name or label for the actual Tone Identifier. + +The length of this field in bytes MUST comply with the advertised value in the Name Length field. This field MUST be omitted if the Name Length field is set to 0. The field MUST be formatted as a byte array with no zero termination. The characters MUST be encoded in UTF-8 format. + +## 4.88.7 Sound Switch Configuration Set Command + +This command is used to set the configuration for playing tones at the supporting node. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SOUND SWITCH _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SOUND SWITCH CONFIGURATION SET (0x05) _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Volume | | | | | | | | | | | | | | | | | | | | | | | | +| Default Tone Identifier | | | | | | | | | | | | | | | | | | | | | | | | + +Volume (8 bits) + +This field is used to specify the volume at which the node will play tones. + +[The encoding of the Volume field MUST be according to Table 125.](04.88-sound-switch-command-class-version-1.md#4887-sound-switch-configuration-set-command) + +Table 125, Sound Switch Configuration Set::Volume encoding + +| | Value | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0 (0x00) | | | This value MUST indicate an Off/Mute volume setting (0%) | | | +| 1..100 (0x01..0x64) | | | These values MUST indicate the actual volume setting from respectively 1% to 100%. A supporting node MAY implement fewer than 100 hardware level. In this case, mapping of hardware levels MUST be monotonous. , i.e. a higher value MUST be mapped to either the same or a higher hardware level. | | | +| 255 (0xFF) | | | This value MUST indicate to restore most recent non-zero volume setting. This value MUST be ignored if the current volume is not zero (0x00). This value MAY be used to set the Default Tone Identifier and do not modify the volume setting | | | + +CC:0079.01.05.11.002 0 (0x00) This value MUST indicate an Off/Mute volume setting (0%) + +CC:0079.01.05.11.003 1..100 These values MUST indicate the actual volume setting from respectively 1% to 100%. + +CC:0079.01.05.11.004 255 (0xFF) This value MUST indicate to restore most recent non-zero volume setting. + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +Default Tone Identifier (8 bits) + +[This field is used to specify the Default Tone. This Tone will be played if receiving the Sound Switch Tone Play Set Command for an unsupported value or for the 0xFF value.](04.88-sound-switch-command-class-version-1.md#4889-sound-switch-configuration-report-command) + +The value 0x00 MUST indicate that the receiving node MUST NOT update its current default tone and the command is sent to configure the volume only. + +Values in the range 1..{Total number of supported tones} MUST indicate that the receiving node MUST use the specified Identifier as Default Tone. + +[Values higher than the Total number of supported tones advertised in the Sound Switch Tones Number Report Command MUST be ignored by a receiving node.](04.88-sound-switch-command-class-version-1.md#4884-sound-switch-tones-number-report-command) + +## 4.88.8 Sound Switch Configuration Get Command + +This command is used to request the current configuration for playing tones at the supporting node. + +[The Sound Switch Configuration Report Command MUST be returned in response to this command.](04.88-sound-switch-command-class-version-1.md#4889-sound-switch-configuration-report-command) + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SOUND SWITCH _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SOUND SWITCH CONFIGURATION GET (0x06) _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.88.9 Sound Switch Configuration Report Command + +This command is used to advertise the current configuration for playing tones at the sending node. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SOUND SWITCH _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SOUND SWITCH CONFIGURATION REPORT (0x07) _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Volume | | | | | | | | | | | | | | | | | | | | | | | | +| Default Tone Identifer | | | | | | | | | | | | | | | | | | | | | | | | + +Volume (8 bits) + +This field is used to advertise the current volume setting at the sending node. + +This field MUST be in the range 0..100. Values in the range 0..100 MUST indicate the current volume percentage. + +Default Tone Identifier (8 bits) + +This field is used to advertise the current configured Default Tone. This Tone Identifier will be played if [receiving a Sound Switch Tone Play Set Command for an unsupported value or for the 0xFF value.](04.88-sound-switch-command-class-version-1.md#4889-sound-switch-configuration-report-command) + +This field MUST be in the range 1..{Total number of supported Tones}. Sound Switch Tone Play Set Command 4.88.10 + +This command is used to instruct a supporting node to play (or stop playing) a tone. + +The supporting node MUST play the specified tone immediately when receiving this command. A node already playing a tone MUST interrupt the current tone and start playing the tone specified in this command. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SOUND SWITCH _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SOUND SWITCH TONE PLAY SET (0x08) _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Tone identifier | | | | | | | | | | | | | | | | | | | | | | | | + +Tone Identifier (8 bits) + +This field is used to specify the tone that the receiving node MUST play. [This field MUST be encoded according to Table 126.](04.88-sound-switch-command-class-version-1.md#4889-sound-switch-configuration-report-command) + +Table 126, Sound Switch Tone Play Set::Tone Identifier encoding + +| | Value | | | Description | | +| --- | --- | --- | --- | --- | --- | +| 0x00 | | | No Tone MUST be played. A supporting node MUST stop playing any tone when receiving this value. | | | +| 0x01..0xFE | | | A supporting node MUST play the specified Tone identifier using the configured volume setting. A node receiving a non-supported Tone Identifier (higher than the Total number of supported tones) MUST play the default tone using the configured volume setting. | | | +| 0xFF | | | The supporting node MUST play the default tone using the configured volume setting. | | | + +CC:0079.01.08.11.005 0x00 No Tone MUST be played. + +CC:0079.01.08.11.006 0x01..0xFE A supporting node MUST play the specified Tone identifier using the configured volume + +CC:0079.01.08.11.007 0xFF The supporting node MUST play the default tone using the configured volume setting. + +## 4.88.11 Sound Switch Tone Play Get Command + +This command is used to request the current tone being played by the receiving node. + +[The Sound Switch Tone Play Report Command MUST be returned in response to this command.](04.88-sound-switch-command-class-version-1.md#48812-sound-switch-tone-play-report-command) + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SOUND SWITCH _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SOUND SWITCH TONE PLAY GET (0x09) _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.88.12 Sound Switch Tone Play Report Command + +This command is used to advertise the current tone being played by the sending node. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS SOUND SWITCH _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = SOUND SWITCH TONE PLAY REPORT (0x0A) _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Tone Identifier | | | | | | | | | | | | | | | | | | | | | | | | + +Tone Identifier (8 bits) + +This field MUST indicate which tone is currently being played by the sending node. This field MUST be in the range 0..{Total number of supported tones}. + +The value 0 MUST indicate that no Tone is currently being played. This field MUST be set to 0x00 by a sending node if the configured volume is 0x00 (muted). + +Values in the range 1..{Total number of supported tones} MUST indicate the Tone that is currently being played. + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.89-tariff-table-configuration-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.89-tariff-table-configuration-command-class-version-1.md new file mode 100644 index 0000000..c44b227 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.89-tariff-table-configuration-command-class-version-1.md @@ -0,0 +1,165 @@ + +# 4.89 Tariff Table Configuration Command Class, version 1 + +The Tariff Table Configuration Command Class defines the cost for a range of rates. + +The Tariff Table configuration commands are separated for the Tariff Table monitor commands in the Tariff Table Monitor Command Class, allowing the classes to be optionally supported at different Z-Wave security levels. + +## 4.89.1 Tariff Table Supplier Set Command + +This command is used to set the name of the utility supplier in the metering device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TARIFF CONFIG _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = TARIFF TBL SUPPLIER SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Utility Timestamp Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Utility Timestamp Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Utility Timestamp Month | | | | | | | | | | | | | | | | | | | | | | | | +| Utility Timestamp Day | | | | | | | | | | | | | | | | | | | | | | | | +| Utility Timestamp Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Utility Timestamp Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Utility Timestamp Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Currency 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Currency 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Currency 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Standing Charge Precision | | | | | | | | | Standing Charge Period | | | | | | | | | | | | | | | +| Standing Charge Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Standing Charge Value 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Standing Charge Value 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Standing Charge Value 4 | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Number of Supplier Characters | | | | | | | | | | | | | | | +| Supplier Character 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Supplier Character N | | | | | | | | | | | | | | | | | | | | | | | | + +Utility Timestamp Year (16 bits) + +Tariff applies from the specified year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. + +Utility Timestamp Month (8 bits) + +Tariff applies from the specified month of the year between 01 (January) and 12 (December). A year equal to 0x0000 indicates that a accumulated value is not determined yet. + +Utility Timestamp Day (8 bits) + +Tariff applies from the specified day of the month between 01 and 31. + +Utility Timestamp Hour Local Time (8 bits) + +Tariff applies from the specified number of complete hours that have passed since midnight (00-23) in local time. + +Utility Timestamp Minute Local Time (8 bits) + +Tariff applies from the specified number of complete minutes that have passed since the start of the hour (00-59) in local time. + +Utility Timestamp Second Local Time (8 bits) + +Tariff applies from the specified number of complete seconds since the start of the minute (00-59) in local time. The value 60 used to keep UTC from wandering away is not supported. + +Currency (3 bytes) + +ISO 4217 defines the currency code. In the table below are some examples of the codes listed: + +Table 127, Tariff Table Supplier Set::Currency encoding examples + +| | Currency Code | | | Currency 1 | | | Currency 2 | | | Currency 3 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Pound sterling | | | G | | | B | | | P | | | +| US Dollar | | | U | | | S | | | D | | | + +Standing Charge Period (5 bits) + +This field indicates the stated period that standing charge applies e.g. 50p/week. + +Table 128, Tariff Table Supplier Set::Standing Charge Period encoding + +| | Period | | | Value | | +| --- | --- | --- | --- | --- | --- | +| Weekly | | | 0x01 | | | +| Monthly | | | 0x02 | | | +| Quarterly | | | 0x03 | | | +| Yearly | | | 0x04 | | | +| Reserved | | | 0x05-0x1F | | | + +Standing Charge Precision (3 bits) + +The precision field describes what the precision of the value is. The number indicates the number of decimals. The decimal value 1025 with precision 2 is therefore equal to 10.25. + +Standing Charge Value (32 bits) + +The Standing Charge value MUST be encoded as a 32-bit signed integer. The first byte MUST be the [most significant byte. Table 10 shows signed decimal values together with their hexadecimal equivalents.](../03-command-class-overview/03.07-common-fields-and-encoding.md#375-signed-encoding) + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Number of Supplier Characters (5 bits) + +Number of characters defining the name of the utility supplier ID (1 … 32). + +Supplier Character (N bytes) + +The supplier character fields hold the string identifying the utility supplier. The character presentation uses standard ASCII codes (values 128-255 are ignored). + +## 4.89.2 Tariff Table Set Command + +This command adds a tariff to a given rate parameter set identifier. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TARIFF TBL _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = TARIFF TBL REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Parameter Set ID | | | | | | | | | | | | | | | | | | | | | | | | +| Tariff Precision | | | | | | | | | Reserved | | | | | | | | | | | | | | | +| Tariff Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Tariff Value 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Tariff Value 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Tariff Value 4 | | | | | | | | | | | | | | | | | | | | | | | | + +Rate Parameter Set ID (8 bits) + +The Rate Parameter Set ID indicates the requested parameter set. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Tariff Precision (3 bits) + +The precision field describes what the precision of the value is. The number indicates the number of decimals. The decimal value 1025 with precision 2 is therefore equal to 10.25. + +Tariff Value (32 bits) + +The Tariff value is a 32 bit signed field. The first byte is the most significant byte. shows signed decimal values together with their hexadecimal equivalents. + +## 4.89.3 Tariff Table Remove Command + +This command is used to remove rate parameter set(s). + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TARIFF TBL CONFIG _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = TARIFF TBL REMOVE _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | Rate Parameter Set IDs | | | | | | | | | | | | | | | | | | +| Rate Parameter Set ID 1 | | | | | | | | | | | | | | | | | | | | | | | | +| ... | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Parameter Set ID N | | | | | | | | | | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Rate Parameter Set IDs (6 bits) + +The rate parameter set id’s indicates the number of rate parameter set id’s in the command. + +Rate Parameter Set ID (N bytes) + +These fields contain a list of Tariffs to be removed from the Tariff Table. All Tariffs are cleared in case no Rate Parameter Set ID’s are supplied. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.90-tariff-table-monitor-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.90-tariff-table-monitor-command-class-version-1.md new file mode 100644 index 0000000..f1e9cfb --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.90-tariff-table-monitor-command-class-version-1.md @@ -0,0 +1,235 @@ + +# 4.90 Tariff Table Monitor Command Class, version 1 + +The Tariff Table Monitor Command Class defines the cost for a range of rates. + +## 4.90.1 Tariff Table Supplier Get Command + +This command is used to request the name of the utility supplier. + +The Tariff Table Supplier Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TARIFF TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = TARIFF TBL SUPPLIER GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.90.2 Tariff Table Supplier Report Command + +This command is used to advertise the name of the utility supplier. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TARIFF TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = TARIFF TBL SUPPLIER REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Utility Timestamp Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Utility Timestamp Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Utility Timestamp Month | | | | | | | | | | | | | | | | | | | | | | | | +| Utility Timestamp Day | | | | | | | | | | | | | | | | | | | | | | | | +| Utility Timestamp Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Utility Timestamp Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Utility Timestamp Second Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Currency 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Currency 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Currency 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Standing Charge Precision | | | | | | | | | Standing Charge Period | | | | | | | | | | | | | | | +| Standing Charge Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Standing Charge Value 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Standing Charge Value 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Standing Charge Value 4 | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Number of Supplier Characters | | | | | | | | | | | | | | | +| Supplier Character 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Supplier Character N | | | | | | | | | | | | | | | | | | | | | | | | + +[Refer to description of fields under the Tariff Table Supplier Set Command (section 4.89.1)](04.89-tariff-table-configuration-command-class-version-1.md#4891-tariff-table-supplier-set-command) + +## 4.90.3 Tariff Table Get Command + +This command is used to request the tariff for the corresponding rate parameter set. + +The Tariff Table Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TARIFF TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = TARIFF TBL GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Parameter Set ID | | | | | | | | | | | | | | | | | | | | | | | | + +Rate Parameter Set ID (8 bits) + +[The Rate Parameter Set ID addresses the price for the accompanying rate parameter set. The Rate Table Supported Report Command determines the number of supported rate parameter sets.](04.71-rate-table-monitor-command-class-version-1.md#4712-rate-table-supported-report-command) + +## 4.90.4 Tariff Table Report Command + +This commandis used to advertise information relating to a given Rate Parameter Set Identifier. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TARIFF TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = TARIFF TBL REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Parameter Set ID | | | | | | | | | | | | | | | | | | | | | | | | +| Tariff Precision | | | | | | | | | Reserved | | | | | | | | | | | | | | | +| Tariff Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Tariff Value 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Tariff Value 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Tariff Value 4 | | | | | | | | | | | | | | | | | | | | | | | | + +[Refer to description of fields under the Tariff Table Set Command (section 4.89.2)](04.89-tariff-table-configuration-command-class-version-1.md#4892-tariff-table-set-command) + +## 4.90.5 Tariff Table Cost Get Command + +This command is used to request the cost according to rate parameter set ID, rate type, dataset mask and time interval. + +The Tariff Table Cost Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TARIFF TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = TARIFF TBL COST GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Parameter Set ID | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Start Month | | | | | | | | | | | | | | | | | | | | | | | | +| Start Day | | | | | | | | | | | | | | | | | | | | | | | | +| Start Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Start Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Month | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Day | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | + +Rate Parameter Set ID (8 bits) + +The Rate Parameter Set ID indicates the requested parameter set. Rate Parameter Set ID equal to 0xFF returns overall accumulated cost. + +Start Year (16 bits) + +Specify the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. + +Start Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December). + +Start Day (8 bits) + +Specify the day of the month between 01 and 31. Start Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00-23) in local time. + +Start Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00-59) in local time. + +Stop Year (16 bits) + +Specify the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. Setting the parameter to 0xFFFF indicates now. + +Stop Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December). A year equal to 0x0000 indicates that an accumulated value is not determined yet. Setting the parameter to 0xFF indicates now. + +Stop Day (8 bits) + +Specify the day of the month between 01 and 31. Setting the parameter to 0xFF indicates now. + +Stop Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00-23) in local time. Setting the parameter to 0xFF indicates now. + +Stop Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00-59) in local time. Setting the parameter to 0xFF indicates now. + +Stop Second Local Time (8 bits) + +Specify the number of complete seconds since the start of the minute (00-59) in local time. The value 60 used to keep UTC from wandering away is not supported. Setting the parameter to 0xFF indicates now. + +## 4.90.6 Tariff Table Cost Report Command + +This command is used to report a number of time stamped values (historical) in physical units in the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS TARIFF TBL MONITOR _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = TARIFF TBL COST REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Rate Parameter Set ID | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | | | | | | | | Rate Type | | | | | +| Start Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Start Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Start Month | | | | | | | | | | | | | | | | | | | | | | | | +| Start Day | | | | | | | | | | | | | | | | | | | | | | | | +| Start Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Start Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Year 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Year 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Month | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Day | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Hour Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Stop Minute Local Time | | | | | | | | | | | | | | | | | | | | | | | | +| Currency 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Currency 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Currency 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Cost Precision | | | | | | | | | Reserved | | | | | | | | | | | | | | | +| Cost Value 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Cost Value 2 | | | | | | | | | | | | | | | | | | | | | | | | +| Cost Value 3 | | | | | | | | | | | | | | | | | | | | | | | | +| Cost Value 4 | | | | | | | | | | | | | | | | | | | | | | | | + +Rate Parameter Set ID (8 bits) + +The Rate Parameter Set ID indicates the requested parameter set. Rate Parameter Set ID equal to 0xFF returns accumulated cost. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. Rate Type (2 bits) + +[Rate Type specifies the type of parameters in the report. This field MUST be encoded according to Table 58.](04.47-meter-command-class-version-2.md#4475-meter-report-command) + +Start/Stop Year (16 bits) + +Specify the year in the usual Gregorian calendar. The first byte (Year 1) is the most significant byte. + +Start/Stop Month (8 bits) + +Specify the month of the year between 01 (January) and 12 (December). A year equal to 0x0000 indicates that a accumulated value is not determined yet. + +Start/Stop Day (8 bits) + +Specify the day of the month between 01 and 31. + +Start/Stop Hour Local Time (8 bits) + +Specify the number of complete hours that have passed since midnight (00-23) in local time. + +Start/Stop Minute Local Time (8 bits) + +Specify the number of complete minutes that have passed since the start of the hour (00-59) in local time. + +Currency (3 bytes) + +[ISO 4217 defines the currency code. Examples are given in Table 127.](04.89-tariff-table-configuration-command-class-version-1.md#4891-tariff-table-supplier-set-command) + +Cost Precision (3 bits) + +The precision field describes what the precision of the value is. The number indicates the number of decimals. The decimal value 1025 with precision 2 is therefore equal to 10.25. + +Cost Value (32 bits) + +The Cost value is a 32 bit un-signed field. The first byte is the most significant byte. + +The value 0xFFFFFFFF is reserved, and SHOULD be used to report that the cost calculation has not yet been performed. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.91-thermostat-fan-mode-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.91-thermostat-fan-mode-command-class-version-1.md new file mode 100644 index 0000000..93da8ff --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.91-thermostat-fan-mode-command-class-version-1.md @@ -0,0 +1,92 @@ + +# 4.91 Thermostat Fan Mode Command Class, version 1 + +The Thermostat Fan Mode Command Class, version 1 used for the HVAC’s systems manual fan. + +## 4.91.1 Thermostat Fan Mode Set Command + +This command is used to set the fan mode in the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN MODE SET _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Fan Mode | | | | | | | | | + +Fan Mode (8 bits) + +[This field MUST comply with the values indicated for version 1 in Table 129.](04.94-thermostat-fan-mode-command-class-version-4.md#4941-thermostat-fan-mode-set-command) + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +## 4.91.2 Thermostat Fan Mode Get Command + +This command is used to request the fan mode in the device. + +The Thermostat Fan Mode Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN MODE GET _ _ _ | | | | | | | | | | | | | | | | | | | | | + +## 4.91.3 Thermostat Fan Mode Report Command + +This command is used to report the fan mode in a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN MODE REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Fan Mode | | | | | | | | | + +Fan Mode (8 bits) + +[Refer to description under 4.91.1 Thermostat Fan Mode Set Command.](04.91-thermostat-fan-mode-command-class-version-1.md#4911-thermostat-fan-mode-set-command) + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +## 4.91.4 Thermostat Fan Mode Supported Get Command + +This command is used to request the supported fan modes from the device. + +The Thermostat Fan Mode Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN MODE SUPPORTED GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | + +## 4.91.5 Thermostat Fan Mode Supported Report Command + +This command is used to report the supported fan modes from the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN MODE SUPPORTED REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | | + +Bit Mask (N bytes) + +The Bit Mask fields describe the supported fan modes by the thermostat. + + Bit 0 in Bit Mask 1 indicates if Fan Mode = 0 (Auto / Auto Low) is supported.  Bit 1 in Bit Mask 1 indicates if Fan Mode = 1 (On / On Low) is supported.  … + +If a Fan Mode is supported the bit MUST be set to 1. If a Fan Mode is not supported the bit MUST be set to 0. It is only necessary to send the Bit Mask fields from 1 and up to the one indicating the last supported fan mode. The number of Bit Mask fields transmitted MUST be determined from the length field in the frame. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.92-thermostat-fan-mode-command-class-version-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.92-thermostat-fan-mode-command-class-version-2.md new file mode 100644 index 0000000..abd85fd --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.92-thermostat-fan-mode-command-class-version-2.md @@ -0,0 +1,52 @@ + +# 4.92 Thermostat Fan Mode Command Class, Version 2 + +The Thermostat Fan Mode Command Class, version 2 is used for the HVAC’s systems manual fan. + +The commands not mentioned here will remain the same as specified for Thermostat Fan Mode Command Class (Version 1). + +## 4.92.1 Thermostat Fan Mode Set Command + +This command is used to set the fan mode in the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN MODE SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Off | | | Reserved | | | | | | | | | Fan Mode | | | | | | | | | | | | + +Off (1 bit) + +The “Off bit” set to “1” will switch the fan fully OFF regardless of what fan mode has been set. In order to activate a fan mode the “Off bit” MUST be set to “0”. + +Fan Mode (4 bits) + +[This field MUST comply with the values indicated for version 2 and older in Table 129.](04.94-thermostat-fan-mode-command-class-version-4.md#4941-thermostat-fan-mode-set-command) + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +## 4.92.2 Thermostat Fan Mode Report Command + +This command is used to report the fan mode in a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN MODE REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Fan Mode | | | | | | | | | | | | + +Fan Mode (4 bits) + +Refer to description under the Thermostat Fan Mode Set Command. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.93-thermostat-fan-mode-command-class-version-3.md b/docs/specs/command-class-specification/04-command-class-definitions/04.93-thermostat-fan-mode-command-class-version-3.md new file mode 100644 index 0000000..c800ae6 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.93-thermostat-fan-mode-command-class-version-3.md @@ -0,0 +1,69 @@ + +# 4.93 Thermostat Fan Mode Command Class, Version 3 + +The Thermostat Fan Mode Command Class, version 3 is used for the HVAC’s systems manual fan. + +## 4.93.1 Thermostat Fan Mode Set Command + +This command is used to set the fan mode in the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN MODE SET _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Off | | | Reserved | | | | | | | | | Fan Mode | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Off (1 bit) + +The “Off bit” set to “1” will switch the fan fully OFF. In order to activate a fan mode the “Off bit” MUST be set to “0”. However, for some applications it is critical that the fan is ON in certain modes. In this case, the application can decide to ignore the Off bit. + +Fan Mode (4 bits) + +[This field MUST comply with the values indicated for version 3 and older in Table 129.](04.94-thermostat-fan-mode-command-class-version-4.md#4941-thermostat-fan-mode-set-command) + +## 4.93.2 Thermostat Fan Mode Get Command + +This command is used to request the fan mode in the device. + +The Thermostat Fan Mode Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN MODE GET _ _ _ | | | | | | | | | | | | | | | | | | | | | + +## 4.93.3 Thermostat Fan Mode Report Command + +This command is used to report the fan mode in a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN MODE REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Off | | | Reserved | | | | | | | | | Fan Mode | | | | | | | | | | | | + +Fan Mode (4 bits) + +[Refer to description under 4.93.1 Thermostat Fan Mode Set Command.](04.93-thermostat-fan-mode-command-class-version-3.md#4931-thermostat-fan-mode-set-command) + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Off (1 bit) + +The “Off bit” set to “1” indicates that the fan is fully OFF. The “Off bit” set to “0” indicates that it is possible to change between Fan Modes. + +For some applications, it is critical that the fan is ON in certain modes. In this case, the application can decide to ignore the Off bit. This means that the Off bit in the Report MUST always be set to “0” diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.94-thermostat-fan-mode-command-class-version-4.md b/docs/specs/command-class-specification/04-command-class-definitions/04.94-thermostat-fan-mode-command-class-version-4.md new file mode 100644 index 0000000..94c0258 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.94-thermostat-fan-mode-command-class-version-4.md @@ -0,0 +1,127 @@ + +# 4.94 Thermostat Fan Mode Command Class, Version 4 + +The Thermostat Fan Mode Command Class is an extension to support control and status monitoring functions of air-conditioning devices in order to achieve a global framework that covers the majority of generic functions implemented by world-wide air-conditioning manufacturer. The new features comprises of: + + New Thermostat Fan Modes: LEFT & RIGHT, UP & DOWN, QUIET + +## 4.94.1 Thermostat Fan Mode Set Command + +This command is used to set the fan mode in the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN MODE SET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Off | | | Reserved | | | | | | | | | Fan Mode | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Off (1 bit) + +“Off bit” set to “1” will switch the fan fully OFF. In order to activate a fan mode the “Off bit” MUST be set to “0”. However for some applications it is critical that the fan is ON in certain modes. In this case the application may ignore the off bit. Fan Mode (4 bits) + +If the device transmitting the Thermostat Fan Mode Set command attempts to set a non-supported mode, the receiving thermostat device MUST ignore the command. + +Table 129, Thermostat Fan Mode Set version 4::Fan Mode encoding + +| Fan Mode (4 bits) | | Description | | CC | | +| --- | --- | --- | --- | --- | --- | +| | | | | Version | | +| 0x00 | AUTO LOW | Will turn the manual fan operation off unless turned on by the manufacturer specific “auto low” algorithms | 1 | | | +| 0x01 | LOW | Will turn the manual fan operation on. Low speed is selected. | 1 | | | +| 0x02 | AUTO HIGH | Will turn the manual fan operation off unless turned on by the manufacturer specific “auto high” algorithms | 1 | | | +| 0x03 | HIGH | Will turn the manual fan operation on. High speed is selected. | 1 | | | +| 0x04 | AUTO MEDIUM | Will turn the manual fan operation off unless turned on by the manufacturer specific “auto medium” algorithms | 2 | | | +| 0x05 | MEDIUM | Will turn the manual fan operation on. Medium speed is selected. | 2 | | | +| 0x06 | CIRCULATION | Will turn the manual fan operation off unless turned on by the manufacturer specific circulation algorithms | 3 | | | +| 0x07 | HUMIDITY CIRCULATION | Will turn the manual fan operation off unless turned on by the manufacturer specific “humidity circulation” algorithms | 3 | | | +| 0x08 | LEFT & RIGHT | Will turn the manual fan operation off unless turned on by the manufacturer specific “left & right” circulation algorithms | 4 | | | +| 0x09 | UP & DOWN | Will turn the manual fan operation off unless turned on by the manufacturer specific “up & down” circulation algorithms | 4 | | | +| 0x0A | QUIET | Will turn the manual fan operation off unless turned on by the manufacturer specific “quiet” algorithms | 4 | | | +| 0x0B- 0x0F | Reserved | These values/modes are reserved for future use. The values cannot be supported by any device and will be ignored. | - | | | + +## 4.94.2 Thermostat Fan Mode Get Command + +This command is used to request the fan mode in the device. + +The Thermostat Fan Mode Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN MODE GET _ _ _ | | | | | | | | | | | | | | | | | | | | | + +## 4.94.3 Thermostat Fan Mode Report Command + +This command is used to report the fan mode in a device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN MODE REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Off | | | Reserved | | | | | | | | | Fan Mode | | | | | | | | | + +Refer to Thermostat Fan Mode Set command for parameter/field descriptions. + +## 4.94.4 Thermostat Fan Mode Supported Get Command + +This command is used to request the supported modes from the device. + +The Thermostat Fan Mode Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN MODE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN MODE SUPPORTED GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | + +## 4.94.5 Thermostat Fan Mode Supported Report Command + +This command is used to report the supported thermostat modes from the device. + +| | 7 | | | 6 | | 5 | | | 4 | | | 3 | | | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN MODE _ _ _ _ | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN MODE SUPPORTED REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | + +Bit Mask (N bytes) + +[The Bit Mask fields describe the supported modes by the device (Refer to 4.94.1 Thermostat Fan Mode Set Command).](04.94-thermostat-fan-mode-command-class-version-4.md#4941-thermostat-fan-mode-set-command) + +[](04.94-thermostat-fan-mode-command-class-version-4.md#4941-thermostat-fan-mode-set-command) Bit 0 in Bit Mask 1 field indicates support for mode = 0 (AUTO LOW)  Bit 1 in Bit Mask 1 field indicates support for mode = 1 (LOW)  Bit 2 in Bit Mask 1 field indicates support for mode = 2 (AUTO HIGH)  … + +The mode is supported if the bit is 1 and the opposite if 0. It is only necessary to send the Bit Mask fields from 1 and up to the one indicating the last supported mode. The number of Bit Mask fields transmitted MUST be determined from the length field in the frame. + +Example: + +To indicate the thermostat device supports AUTO LOW, AUTO HIGH and AUTO MEDIUM, the Thermostat Fan Mode Supported Report command MUST be structured as illustrated below. + +| | 7 | | | 6 | | 5 | | | 4 | | | 3 | | | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN MODE _ _ _ _ | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN MODE SUPPORTED REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | +| Bit Mask 1 0 0 0 1 0 1 0 1 | | | | | | | | | | | | | | | | | | + +![figure p532](assets/img-2f5fb50cdf.png) + +![figure p532](assets/img-2f5fb50cdf.png) + +![figure p532](assets/img-2f5fb50cdf.png) + +| 0 | 0 | 0 | 1 | 0 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.95-thermostat-fan-state-command-class-version-1-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.95-thermostat-fan-state-command-class-version-1-2.md new file mode 100644 index 0000000..467dbb1 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.95-thermostat-fan-state-command-class-version-1-2.md @@ -0,0 +1,67 @@ + +# 4.95 Thermostat Fan State Command Class, version 1-2 + +The Thermostat Fan State Command Class is used to obtain the fan operating state of the thermostat. + +## 4.95.1 Compatibility considerations + +A device supporting Thermostat Fan State CC, Version 2 MUST support Thermostat Fan State CC, Version 1. + +Version 2 adds Fan Operating State identifiers for use in the Thermostat Fan State Report Command. + +Commands not described in Version 2 stays unchanged from version 1. + +## 4.95.2 Thermostat Fan State Get Command + +This command is used to request the fan operating state from the device. + +The Thermostat Fan State Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN STATE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN STATE GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.95.3 Thermostat Fan State Report Command + +This command is used to report the fan operating state of the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT FAN STATE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT FAN STATE REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Fan Operating State | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Fan Operating State (4 bits) + +[The fan operating state identifier MUST comply with Table 130.](04.95-thermostat-fan-state-command-class-version-1-2.md#4953-thermostat-fan-state-report-command) + +Table 130, Thermostat Fan State Report::Fan Operating State encoding + +| | Fan | | Description | CC Version | +| --- | --- | --- | --- | --- | +| | Operating | | | | +| | State | | | | +| 0 | | | Idle / Off | 1 | +| 1 | | | Running / Running Low – If device only supports one fan speed, this state is used to report the fan is running. If the device is a multi-speed device, this state is used to report that the fan is running at the low speed. | 1 | +| 2 | | | Running High | 1 | +| 3 | | | Running Medium | 2 | +| 4 | | | Circulation Mode | 2 | +| 5 | | | Humidity Circulation Mode | 2 | +| 6 | | | Right – Left Circulation Mode | 2 | +| 7 | | | Up – Down Circulation Mode | 2 | +| 8 | | | Quiet Circulation Mode | 2 | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.96-thermostat-mode-command-class-version-1-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.96-thermostat-mode-command-class-version-1-2.md new file mode 100644 index 0000000..e56f207 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.96-thermostat-mode-command-class-version-1-2.md @@ -0,0 +1,112 @@ + +# 4.96 Thermostat Mode Command Class, version 1-2 + +The Thermostat Mode Command Class is used to control a thermostat. These Commands allow applications to set and get the thermostat parameters. Version 2 extends the available number of modes. + +NOTE: A device supporting the Thermostat Mode Command Class cannot support Auto and Auto Changeover mode simultaneously. Devices controlling a device supporting the Thermostat Mode Command Class MUST be able to control both modes to ensure interoperability. + +## 4.96.1 Thermostat Mode Set Command + +This command is used to set the wanted mode in the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT MODE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT MODE SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Mode | | | | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Mode (5 bits) + +[The thermostat mode identifier MUST comply with Table 131.](04.97-thermostat-mode-command-class-version-3.md#4971-thermostat-mode-set-command) + +## 4.96.2 Thermostat Mode Get Command + +This command is used to request the current mode from the device. + +The Thermostat Mode Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT MODE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT MODE GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.96.3 Thermostat Mode Report Command + +This command is used to report the mode from the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT MODE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT MODE REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | Mode | | | | | | | | | | | | | | | + +Mode (5 bits) + +Refer to description under the Thermostat Mode Set Command. + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +## 4.96.4 Thermostat Mode Supported Get Command + +This command is used to request the supported modes. + +The Thermostat Mode Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT MODE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT MODE SUPPORTED GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.96.5 Thermostat Mode Supported Report Command + +This command is used to report the supported modes from the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT MODE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT MODE SUPPORTED REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | | + +Bit Mask (N bytes) + +The Bit Mask fields describe the supported modes by the device. + + Bit 0 in Bit Mask 1 indicates if Mode = 0 (Off) is supported.  Bit 1 in Bit Mask 1 indicates if Mode = 1 (Heat) is supported.  … + +If the Mode is supported the bit MUST be set to 1. If the Mode is supported the bit MUST be set to 0. It is only necessary to send the Bit Mask fields from 1 and up to the one indicating the last supported mode. The number of Bit Mask fields transmitted MUST be determined from the length field in the frame. + +For example if thermostat supports Heat, Cool, Energy Save Heat and Energy Save Cool bit mask would be 0x06 and 0x18 respectively: + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| | 0 | | | 0 | | | 0 | | | 0 | | | 0 | | | 1 | | | 1 | | | 0 | | + +Bit Mask Byte 1 = 0x06 Heat + +Cool + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| | 0 | | | 0 | | | 0 | | | 1 | | | 1 | | | 0 | | | 0 | | | 0 | | + +Bit Mask Byte 2 = 0x18 Energy Save Heat + +Energy Save Cool diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.97-thermostat-mode-command-class-version-3.md b/docs/specs/command-class-specification/04-command-class-definitions/04.97-thermostat-mode-command-class-version-3.md new file mode 100644 index 0000000..d79fd2f --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.97-thermostat-mode-command-class-version-3.md @@ -0,0 +1,157 @@ + +# 4.97 Thermostat Mode Command Class, version 3 + +The Thermostat Mode Command Class is an extension to support control and status monitoring functions of air-conditioning devices in order to achieve a global framework that covers the majority of generic functions implemented by world-wide air-conditioning manufacturer. The new features comprises of: + + FULL POWER thermostat mode + + MANUFACTURER SPECIFIC mode allowed under defined rules + +NOTE: A device supporting the Thermostat Mode Command Class cannot support AUTO and AUTO CHANGEOVER mode simultaneously. Devices controlling a device supporting the Thermostat Mode Command Class MUST be able to control both modes to ensure interoperability. + +## 4.97.1 Thermostat Mode Set Command + +The Thermostat Mode Set Command is used to set the desired mode in the thermostat device. + +The controlling device SHOULD interview the thermostat device for supported modes to avoid setting an unsupported thermostat mode. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT MODE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT MODE SET _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| No of Manufacturer Data fields | | | | | | | | | Mode | | | | | | | | | | | | | | | +| Manufacturer Data 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Manufacturer Data N | | | | | | | | | | | | | | | | | | | | | | | | + +No of Manufacturer Data fields (3 bits) + +To indicate 0-7 bytes of appended Manufacturer Data. This field is only used when setting a MANUFACTURER SPECIFIC mode (Mode = 0x1F). If not setting the MANUFACTURER SPECIFIC mode this field MUST be set to 0. Mode (5 bits) + +If the Thermostat Mode Set command specifies a non-supported mode, the receiving node MUST ignore the command. + +MANUFACTURER SPECIFIC (proprietary) mode MUST NOT be implemented unless the following conditions are fulfilled: + + The device MUST support minimum two Z-Wave specified thermostat modes e.g. HEAT and COOL and MAY use MANUFACTURER SPECIFIC mode for vendor specific thermostat modes.  If the MANUFACTURER SPECIFIC mode can in whole or in part be supported by a Z-Wave specified thermostat mode, the device MUST include support of the Z-Wave specified thermostat mode. For instance if the device manufacturer desires MANUFACTURER SPECIFIC mode to set the thermostat into energy saving heating mode, the Z-Wave specified thermostat mode: ENERGY HEAT, MUST be used instead.  The MANUFACTURER SPECIFIC mode and all of its associated Manufacturer Data fields MUST be described in the product manual. + +Table 131, Thermostat Mode Set version 3::Mode encoding + +| Mode (5 bits) | | Description | | CC | | +| --- | --- | --- | --- | --- | --- | +| | | | | Version | | +| 0x00 | OFF | System is OFF. | 1 | | | +| 0x01 | HEAT | Continuous heating only. | 1 | | | +| 0x02 | COOL | Continuous cooling only. | 1 | | | +| 0x03 | AUTO | The system will automatically switch between heating and cooling when the temperature exceeds the HEAT and COOL set point types. | 1 | | | +| 0x04 | AUXILIARY | Auxiliary/Emergency Heat. A heat pump (especially air exchange types) is not efficient when the outside temperature is below 35 degrees Fahrenheit (~0 degrees centigrade). Thus, the thermostat may be put into auxiliary heat mode simply to use a more efficient secondary heat source when there are no failures of the compressor or heat pump unit itself. | 1 | | | +| 0x05 | RESUME (ON) | The system MUST resume to last active mode. The Thermostat Mode Report command MUST NOT advertise this Mode identifier. | 1 | | | +| 0x06 | FAN | Fan only - cycle fan to circulate air. | 1 | | | +| 0x07 | FURNACE | Cycle fan to circulate air - heating or cooling will be activated according to the FURNACE set point. | 1 | | | +| 0x08 | DRY | Dehumidification - The system will cycle cooling in relation to the room and the DRY set point temperature in order to remove moisture from ambient. | 1 | | | +| 0x09 | MOIST | Humidification - Moist Air, heating or cooling will be activated according to the MOIST set point. | 1 | | | +| 0x0A | AUTO CHANGEOVER | Auto Changeover - heating or cooling will be activated according to the AUTO CHANGEOVER set point. | 1 | | | + +| Mode (5 bits) | | Description | | CC | | +| --- | --- | --- | --- | --- | --- | +| | | | | Version | | +| 0x0B | ENERGY HEAT | Energy Saving Heating (usually lower than normal set point) - heating will be activated according to the ENERGY HEAT set point. | 2 | | | +| 0x0C | ENERGY COOL | Energy Saving Cooling (usually higher than normal set point) - cooling will be activated according to the ENERGY COOL set point. | 2 | | | +| 0x0D | AWAY | Away mode, e.g. preventing water from freezing in forced water systems - heating or cooling will be activated when temperature exceeds the AWAY HEAT and/or AWAY COOL set points. | 2 | | | +| 0x0E | Reserved | Reserved for future use. | 3 | | | +| 0x0F | FULL POWER | SPEED UP / FULL POWER heating or cooling mode will be activated when temperature exceeds FULL POWER set point. | 3 | | | +| 0x10 - 0x1E | Reserved | Reserved for future use. | 3 | | | +| 0x1F | MANUFACTURER SPECIFIC | Reserved for vendor specific thermostat mode | 3 | | | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +## 4.97.2 Thermostat Mode Get Command + +This ommand is used to request the current mode from the device. + +The Thermostat Mode Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT MODE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT MODE GET _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.97.3 Thermostat Mode Report Command + +This command is used to report the current mode of the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT MODE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT MODE REPORT _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| No of Manufacturer Data fields | | | | | | | | | | Mode | | | | | | | | | | | | | | +| Manufacturer Data 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Manufacturer Data N | | | | | | | | | | | | | | | | | | | | | | | | + +Refer to Thermostat Mode Set command for field description. + +## 4.97.4 Thermostat Mode Supported Get Command + +This command is used to request the supported modes. + +The Thermostat Mode Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT MODE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT MODE SUPPORTED GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.97.5 Thermostat Mode Supported Report Command + +This command is used to report the supported thermostat modes from the device. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT MODE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT MODE SUPPORTED REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | | | | + +Bit Mask (N bytes) + +The Bit Mask fields describe the supported modes by the device (see Thermostat Mode Set command). MANUFACTURER SPECIFIC thermostat mode cannot be listed in this command. + + Bit 0 in Bit Mask 1 field indicates support for mode = 0 (OFF)  Bit 1 in Bit Mask 1 field indicates support for mode = 1 (HEAT)  Bit 2 in Bit Mask 1 field indicates support for mode = 2 (COOL)  … + +The mode is supported if the bit is 1 and the opposite if 0. It is only necessary to send the Bit Mask fields from 1 and up to the one indicating the last supported mode. The number of Bit Mask fields transmitted MUST be determined from the length field in the frame. Example: + +To indicate the thermostat device supports OFF, HEAT, COOL, AUTO and DRY, the Thermostat Mode Supported Report command MUST be structured as illustrated below. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT MODE _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT MODE SUPPORTED REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 1 0 0 0 0 1 1 1 1 | | | | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 2 0 0 0 0 0 0 0 1 | | | | | | | | | | | | | | | | | | | | | | | | + +![figure p543](assets/img-2f5fb50cdf.png) + +![figure p543](assets/img-2f5fb50cdf.png) + +![figure p543](assets/img-2f5fb50cdf.png) + +![figure p543](assets/img-2f5fb50cdf.png) + +| 0 | 0 | 0 | 0 | 1 | 1 | 1 | 1 | +| --- | --- | --- | --- | --- | --- | --- | --- | + +![figure p543](assets/img-2f5fb50cdf.png) + +| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | +| --- | --- | --- | --- | --- | --- | --- | --- | diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.98-thermostat-operating-state-command-class-version-1.md b/docs/specs/command-class-specification/04-command-class-definitions/04.98-thermostat-operating-state-command-class-version-1.md new file mode 100644 index 0000000..74acea3 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.98-thermostat-operating-state-command-class-version-1.md @@ -0,0 +1,41 @@ + +# 4.98 Thermostat Operating State Command Class, version 1 + +The Thermostat Operating State Command Class is used to obtain the operating state of the thermostat. + +## 4.98.1 Thermostat Operating State Get Command + +This command is used to request the operating state. + +The Thermostat Operating State Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT OPERATING STATE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT OPERATING STATE GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.98.2 Thermostat Operating State Report Command + +The Thermostat Operating State Report Command is used to report the operating state. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT OPERATING STATE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT OPERATING STATE REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reserved | | | | | | | | | | | | Operating State | | | | | | | | | | | | + +Reserved + +This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node. + +Operating State (4 bits) + +[The thermostat operating state identifier MUST comply with Table 132.](04.99-thermostat-operating-state-command-class-version-2.md#4992-thermostat-operating-state-report) diff --git a/docs/specs/command-class-specification/04-command-class-definitions/04.99-thermostat-operating-state-command-class-version-2.md b/docs/specs/command-class-specification/04-command-class-definitions/04.99-thermostat-operating-state-command-class-version-2.md new file mode 100644 index 0000000..5bc5e16 --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/04.99-thermostat-operating-state-command-class-version-2.md @@ -0,0 +1,153 @@ + +# 4.99 Thermostat Operating State Command Class, version 2 + +The Thermostat Operating State Command Class is used to obtain the operating state of the thermostat as well as logged operating runtime times of thermostat. + +## 4.99.1 Thermostat Operating State Get + +This command gets the operating state of the thermostat. + +The Thermostat Operating State Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT OPERATING STATE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT OPERATING STATE GET _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.99.2 Thermostat Operating State Report + +This command is used to report the operating state. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT OPERATING STATE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT OPERATING STATE REPORT _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Operating State | | | | | | | | | | | | | | | | | | | | | | | | + +Operating State (8 bits) + +[The thermostat operating state identifier MUST be set according to Table 132.](04.99-thermostat-operating-state-command-class-version-2.md#4992-thermostat-operating-state-report) Table 132, Thermostat Operating State Report version 2::Operating State encoding + +| | Operating | | Description | Version | +| --- | --- | --- | --- | --- | +| | State | | | | +| 0x00 | | | Idle | 1 | +| 0x01 | | | Heating | 1 | +| 0x02 | | | Cooling | 1 | +| 0x03 | | | Fan Only | 1 | +| 0x04 | | | Pending Heat. Short cycle prevention feature used in heat pump applications to protect the compressor. | 1 | +| 0x05 | | | Pending Cool. Short cycle prevention feature used in heat pump applications to protect the compressor. | 1 | +| 0x06 | | | Vent/Economizer. | 1 | +| 0x07 | | | Aux Heating | 2 | +| 0x08 | | | 2nd Stage Heating | 2 | +| 0x09 | | | 2nd Stage Cooling | 2 | +| 0x0A | | | 2nd Stage Aux Heat | 2 | +| 0x0B | | | 3rd Stage Aux Heat | 2 | + +All other values are reserved and MUST NOT be used by a sending node. Reserved values MUST be ignored by a receiving node. + +## 4.99.3 Thermostat Operating State Logging Supported Get + +This command is used to request the operating state logging supported by the device. + +The Thermostat Operating State Logging Supported Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT OPERATING STATE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT OPERATING STATE LOGGING SUPPORTED GET _ _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | + +## 4.99.4 Thermostat Operating State Logging Supported Report + +This command is used to report the operating state logging supported by the device. + +| | 7 | | | 6 | 5 | | | 4 | | | 3 | | | 2 | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT OPERATING STATE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT OPERATING LOGGING SUPPORTED REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | + +Bit Mask (N bytes) + +The Bit Mask fields describe the operating state logging supported by the device. + + Bit 0 in Bit Mask 1 is not allocated to any Operating State and MUST beset to zero.  Bit 1 in Bit Mask 1 indicates if Operating State = 1 (Heating) log is supported.  Bit 2 in Bit Mask 1 indicates if Operating State = 2 (Cooling) is supported.  … + +If the Operating State log is supported the bit MUST be set to 1. If the Operating State log is not supported the bit MUST be set to 0. It is only necessary to send the Bit Mask fields from 1 and up to the one indicating the last supported operating state log. The number of Bit Mask fields transmitted MUST be determined from the length field in the frame. + +## 4.99.5 Thermostat Operating State Logging Get + +This command is used to request the operating state logging supported by the device. + +The Thermostat Operating State Logging Report Command MUST be returned in response to this command. + +This command MUST NOT be issued via multicast addressing. A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods. + +| | 7 | | | 6 | 5 | | | 4 | | | 3 | | | 2 | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT OPERATING STATE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT OPERATING STATE LOGGING GET _ _ _ _ | | | | | | | | | | | | | | | | | | | | | +| Bit Mask 1 | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | +| Bit Mask N | | | | | | | | | | | | | | | | | | | | | + +Bit Mask (N bytes) + +The Bit Mask fields describe the operating state log types to be requested.  Bit 0 in Bit Mask 1 is not allocated to any Operating State and MUST be set to zero.  Bit 1 in Bit Mask 1 indicates if Operating State = 1 (Heating) log is supported.  Bit 2 in Bit Mask 1 indicates if Operating State = 2 (Cooling) is supported.  … + +If the Operating State log is supported the bit MUST be set to 1. If the Operating State log is not supported the bit MUST be set to 0. It is only necessary to send the Bit Mask fields from 1 and up to the one indicating the last requested operating state log type. The number of Bit Mask fields transmitted MUST be determined from the length field in the frame. + +## 4.99.6 Thermostat Operating State Logging Report + +This command is used to report the operating state logged for requested operating states. + +| | 7 | | | 6 | | | 5 | | | 4 | | | 3 | | | 2 | | | 1 | | | 0 | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Command Class = COMMAND CLASS THERMOSTAT OPERATING STATE _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Command = THERMOSTAT OPERATING STATE LOGGING REPORT _ _ _ _ | | | | | | | | | | | | | | | | | | | | | | | | +| Reports to Follow | | | | | | | | | | | | | | | | | | | | | | | | +| | Reserved | | | | | | | | | | | | Operating State Log Type 1 | | | | | | | | | | | +| | Usage Today (Hours) | | | | | | | | | | | | | | | | | | | | | | | +| | Usage Today (Minutes) | | | | | | | | | | | | | | | | | | | | | | | +| | Usage Yesterday (Hours) | | | | | | | | | | | | | | | | | | | | | | | +| | Usage Yesterday (Minutes) | | | | | | | | | | | | | | | | | | | | | | | +| … | | | | | | | | | | | | | | | | | | | | | | | | +| | Reserved | | | | | | | | | | | | Operating State Log Type N | | | | | | | | | | | +| | Usage Today (Hours) | | | | | | | | | | | | | | | | | | | | | | | +| | Usage Today (Minutes) | | | | | | | | | | | | | | | | | | | | | | | +| | Usage Yesterday (Hours) | | | | | | | | | | | | | | | | | | | | | | | +| | Usage Yesterday (Minutes) | | | | | | | | | | | | | | | | | | | | | | | + +Reports to Follow (8 bits) + +This value indicates how many report frames left before transferring all of the requested thermostat operating state logs. + +Operating State Log Type (N * 4 bits) + +The Operating State Log Type indicates the operating state type to be requested. + +Usage Today Hours (8 bits) + +The number of hours (00:24) the thermostat has been in the indicated operating state since 12:00 am of the current day. Usage Today Minutes (8 bits) + +The number of minutes (00-59) the thermostat has been in the indicated operating state since 12:00 am of the current day. + +Usage Yesterday Hours (8 bits) + +The number of hours (00:24) the thermostat had been in the indicated operating state between 12:00 am and 11:59pm of the previous day. + +Usage Yesterday Hours (8 bits) + +The number of minutes (00-59) the thermostat had been in the indicated operating state between 12:00 am and 11:59pm of the previous day. diff --git a/docs/specs/command-class-specification/04-command-class-definitions/index.md b/docs/specs/command-class-specification/04-command-class-definitions/index.md new file mode 100644 index 0000000..da4320f --- /dev/null +++ b/docs/specs/command-class-specification/04-command-class-definitions/index.md @@ -0,0 +1,124 @@ + +# 4 Command Class Definitions + +The following subchapters contain definitions of Application Command Classes. + +## Contents + +- [4.1 Alarm Command Class, version 1 [DEPRECATED]](04.01-alarm-command-class-version-1-deprecated.md) +- [4.2 Alarm Command Class, version 2 [DEPRECATED]](04.02-alarm-command-class-version-2-deprecated.md) +- [4.3 Alarm Sensor Command Class, version 1 [DEPRECATED]](04.03-alarm-sensor-command-class-version-1-deprecated.md) +- [4.4 Alarm Silence Command Class, version 1](04.04-alarm-silence-command-class-version-1.md) +- [4.1 All Switch Command Class, version 1 [OBSOLETED]](04.01-all-switch-command-class-version-1-obsoleted.md) +- [4.2 Anti-theft Command Class, version 1 [OBSOLETED]](04.02-anti-theft-command-class-version-1-obsoleted.md) +- [4.3 Anti-theft Command Class, version 2](04.03-anti-theft-command-class-version-2.md) +- [4.4 Barrier Operator Command Class, version 1](04.04-barrier-operator-command-class-version-1.md) +- [4.5 Basic Command Class, version 1](04.05-basic-command-class-version-1.md) +- [4.6 Basic Command Class, version 2](04.06-basic-command-class-version-2.md) +- [4.7 Basic Tariff Information Command Class, version 1](04.07-basic-tariff-information-command-class-version-1.md) +- [4.8 Basic Window Covering Command Class, version 1 [OBSOLETED]](04.08-basic-window-covering-command-class-version-1-obsoleted.md) +- [4.9 Binary Sensor Command Class, version 1 [DEPRECATED]](04.09-binary-sensor-command-class-version-1-deprecated.md) +- [4.10 Binary Sensor Command Class, version 2 [DEPRECATED]](04.10-binary-sensor-command-class-version-2-deprecated.md) +- [4.11 Binary Switch Command Class, version 1](04.11-binary-switch-command-class-version-1.md) +- [4.12 Binary Switch Command Class, version 2](04.12-binary-switch-command-class-version-2.md) +- [4.13 Binary Toggle Switch Command Class, version 1 [OBSOLETED]](04.13-binary-toggle-switch-command-class-version-1-obsoleted.md) +- [4.14 Climate Control Schedule Command Class, version 1 [DEPRECATED]](04.14-climate-control-schedule-command-class-version-1-deprecated.md) +- [4.15 Central Scene Command Class, version 1 [OBSOLETED]](04.15-central-scene-command-class-version-1-obsoleted.md) +- [4.16 Central Scene Command Class, version 2 [OBSOLETED]](04.16-central-scene-command-class-version-2-obsoleted.md) +- [4.17 Central Scene Command Class, version 3](04.17-central-scene-command-class-version-3.md) +- [4.18 Clock Command Class, version 1](04.18-clock-command-class-version-1.md) +- [4.19 Color Switch Command Class, version 1](04.19-color-switch-command-class-version-1.md) +- [4.20 Color Switch Command Class, version 2](04.20-color-switch-command-class-version-2.md) +- [4.21 Color Switch Command Class, version 3](04.21-color-switch-command-class-version-3.md) +- [4.22 Configuration Command Class, version 1](04.22-configuration-command-class-version-1.md) +- [4.23 Configuration Command Class, version 2](04.23-configuration-command-class-version-2.md) +- [4.24 Configuration Command Class, version 3](04.24-configuration-command-class-version-3.md) +- [4.25 Configuration Command Class, version 4](04.25-configuration-command-class-version-4.md) +- [4.26 Controller Replication Command Class, version 1](04.26-controller-replication-command-class-version-1.md) +- [4.27 Demand Control Plan Configuration Command Class, version 1](04.27-demand-control-plan-configuration-command-class-version-1.md) +- [4.28 Demand Control Plan Monitor Command Class, version 1](04.28-demand-control-plan-monitor-command-class-version-1.md) +- [4.29 Door Lock Command Class, version 1-2](04.29-door-lock-command-class-version-1-2.md) +- [4.30 Door Lock Command Class, version 3](04.30-door-lock-command-class-version-3.md) +- [4.31 Door Lock Logging Command Class, version 1](04.31-door-lock-logging-command-class-version-1.md) +- [4.32 Energy Production Command Class, version 1](04.32-energy-production-command-class-version-1.md) +- [4.33 Entry Control Command Class, version 1](04.33-entry-control-command-class-version-1.md) +- [4.34 Geographic Location Command Class, version 1](04.34-geographic-location-command-class-version-1.md) +- [4.35 HRV Status Command Class, version 1](04.35-hrv-status-command-class-version-1.md) +- [4.36 HRV Control Command Class, version 1](04.36-hrv-control-command-class-version-1.md) +- [4.37 Humidity Control Mode Command Class, version 1](04.37-humidity-control-mode-command-class-version-1.md) +- [4.38 Humidity Control Operating State Command Class, version 1](04.38-humidity-control-operating-state-command-class-version-1.md) +- [4.39 Humidity Control Setpoint Command Class, version 1](04.39-humidity-control-setpoint-command-class-version-1.md) +- [4.40 Indicator Command Class, version 1](04.40-indicator-command-class-version-1.md) +- [4.41 Indicator Command Class, version 2](04.41-indicator-command-class-version-2.md) +- [4.42 Irrigation Command Class, version 1](04.42-irrigation-command-class-version-1/index.md) +- [4.43 Language Command Class, version 1](04.43-language-command-class-version-1.md) +- [4.44 Lock Command Class, version 1 [DEPRECATED]](04.44-lock-command-class-version-1-deprecated.md) +- [4.45 Manufacturer Proprietary Command Class, version 1](04.45-manufacturer-proprietary-command-class-version-1.md) +- [4.46 Meter Command Class, version 1](04.46-meter-command-class-version-1.md) +- [4.47 Meter Command Class, version 2](04.47-meter-command-class-version-2.md) +- [4.48 Meter Command Class, version 3](04.48-meter-command-class-version-3.md) +- [4.49 Meter Command Class, version 4](04.49-meter-command-class-version-4.md) +- [4.50 Meter Command Class, version 5](04.50-meter-command-class-version-5.md) +- [4.51 Meter Table Configuration Command Class, version 1](04.51-meter-table-configuration-command-class-version-1.md) +- [4.52 Meter Table Monitor Command Class, version 1](04.52-meter-table-monitor-command-class-version-1/index.md) +- [4.53 Meter Table Monitor Command Class, version 2](04.53-meter-table-monitor-command-class-version-2/index.md) +- [4.54 Meter Table Push Configuration Command Class version 1](04.54-meter-table-push-configuration-command-class-version-1.md) +- [4.55 Move To Position Window Covering Command Class, version 1 [OBSOLETED]](04.55-move-to-position-window-covering-command-class-version-1-obsoleted.md) +- [4.56 Multilevel Sensor Command Class, version 1-4](04.56-multilevel-sensor-command-class-version-1-4.md) +- [4.57 Multilevel Sensor Command Class, Version 5-11](04.57-multilevel-sensor-command-class-version-5-11.md) +- [4.58 Multilevel Switch Command Class, version 1](04.58-multilevel-switch-command-class-version-1.md) +- [4.59 Multilevel Switch Command Class, version 2](04.59-multilevel-switch-command-class-version-2.md) +- [4.60 Multilevel Switch Command Class, version 3](04.60-multilevel-switch-command-class-version-3.md) +- [4.61 Multilevel Switch Command Class, version 4](04.61-multilevel-switch-command-class-version-4.md) +- [4.62 Multilevel Toggle Switch Command Class, version 1 [DEPRECATED]](04.62-multilevel-toggle-switch-command-class-version-1-deprecated.md) +- [4.63 Notification Command Class, version 3-8](04.63-notification-command-class-version-3-8/index.md) +- [4.64 Prepayment Command Class, version 1](04.64-prepayment-command-class-version-1.md) +- [4.65 Prepayment Encapsulation Command Class, version 1](04.65-prepayment-encapsulation-command-class-version-1.md) +- [4.66 Proprietary Command Class, version 1 [DEPRECATED]](04.66-proprietary-command-class-version-1-deprecated.md) +- [4.67 Protection Command Class, version 1](04.67-protection-command-class-version-1.md) +- [4.68 Protection Command Class, version 2](04.68-protection-command-class-version-2.md) +- [4.69 Pulse Meter Command Class, version 1 [DEPRECATED]](04.69-pulse-meter-command-class-version-1-deprecated.md) +- [4.70 Rate Table Configuration Command Class, version 1](04.70-rate-table-configuration-command-class-version-1.md) +- [4.71 Rate Table Monitor Command Class, version 1](04.71-rate-table-monitor-command-class-version-1.md) +- [4.72 Scene Activation Command Class, version 1](04.72-scene-activation-command-class-version-1.md) +- [4.73 Scene Actuator Configuration Command Class, version 1](04.73-scene-actuator-configuration-command-class-version-1.md) +- [4.74 Scene Controller Configuration Command Class, version 1](04.74-scene-controller-configuration-command-class-version-1.md) +- [4.75 Schedule Command Class, version 1](04.75-schedule-command-class-version-1/index.md) +- [4.76 Schedule Command Class, version 2](04.76-schedule-command-class-version-2.md) +- [4.77 Schedule Command Class, version 3](04.77-schedule-command-class-version-3.md) +- [4.78 Schedule Command Class, version 4](04.78-schedule-command-class-version-4.md) +- [4.79 Schedule Entry Lock Command Class, version 1 [DEPRECATED]](04.79-schedule-entry-lock-command-class-version-1-deprecated.md) +- [4.80 Schedule Entry Lock Command Class, version 2 [DEPRECATED]](04.80-schedule-entry-lock-command-class-version-2-deprecated.md) +- [4.81 Schedule Entry Lock Command Class, Version 3 [DEPRECATED]](04.81-schedule-entry-lock-command-class-version-3-deprecated.md) +- [4.82 Screen Attributes Command Class, version 1](04.82-screen-attributes-command-class-version-1.md) +- [4.83 Screen Attributes Command Class, version 2](04.83-screen-attributes-command-class-version-2.md) +- [4.84 Screen Meta Data Command Class, version 1](04.84-screen-meta-data-command-class-version-1.md) +- [4.85 Screen Meta Data Command Class, version 2](04.85-screen-meta-data-command-class-version-2.md) +- [4.86 Sensor Configuration Command Class, version 1 [OBSOLETED]](04.86-sensor-configuration-command-class-version-1-obsoleted.md) +- [4.87 Simple AV Control Command Class, version 1-4](04.87-simple-av-control-command-class-version-1-4.md) +- [4.88 Sound Switch Command Class, version 1](04.88-sound-switch-command-class-version-1.md) +- [4.89 Tariff Table Configuration Command Class, version 1](04.89-tariff-table-configuration-command-class-version-1.md) +- [4.90 Tariff Table Monitor Command Class, version 1](04.90-tariff-table-monitor-command-class-version-1.md) +- [4.91 Thermostat Fan Mode Command Class, version 1](04.91-thermostat-fan-mode-command-class-version-1.md) +- [4.92 Thermostat Fan Mode Command Class, Version 2](04.92-thermostat-fan-mode-command-class-version-2.md) +- [4.93 Thermostat Fan Mode Command Class, Version 3](04.93-thermostat-fan-mode-command-class-version-3.md) +- [4.94 Thermostat Fan Mode Command Class, Version 4](04.94-thermostat-fan-mode-command-class-version-4.md) +- [4.95 Thermostat Fan State Command Class, version 1-2](04.95-thermostat-fan-state-command-class-version-1-2.md) +- [4.96 Thermostat Mode Command Class, version 1-2](04.96-thermostat-mode-command-class-version-1-2.md) +- [4.97 Thermostat Mode Command Class, version 3](04.97-thermostat-mode-command-class-version-3.md) +- [4.98 Thermostat Operating State Command Class, version 1](04.98-thermostat-operating-state-command-class-version-1.md) +- [4.99 Thermostat Operating State Command Class, version 2](04.99-thermostat-operating-state-command-class-version-2.md) +- [4.100 Thermostat Setback Command Class, version 1](04.100-thermostat-setback-command-class-version-1.md) +- [4.101 Thermostat Setpoint Command Class, version 1-2](04.101-thermostat-setpoint-command-class-version-1-2.md) +- [4.102 Thermostat Setpoint Command Class, version 3](04.102-thermostat-setpoint-command-class-version-3.md) +- [4.103 Time Command Class, version 1](04.103-time-command-class-version-1.md) +- [4.104 Time Command Class, version 2](04.104-time-command-class-version-2.md) +- [4.105 Time Parameters Command Class, version 1](04.105-time-parameters-command-class-version-1.md) +- [4.106 User Code Command Class, version 1](04.106-user-code-command-class-version-1.md) +- [4.107 Window Covering Command Class, version 1](04.107-window-covering-command-class-version-1.md) diff --git a/docs/specs/command-class-specification/assets/img-031d09cc57.jpeg b/docs/specs/command-class-specification/assets/img-031d09cc57.jpeg new file mode 100644 index 0000000..f8e3c02 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-031d09cc57.jpeg differ diff --git a/docs/specs/command-class-specification/assets/img-0546536017.png b/docs/specs/command-class-specification/assets/img-0546536017.png new file mode 100644 index 0000000..f47f833 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-0546536017.png differ diff --git a/docs/specs/command-class-specification/assets/img-0d25374112.png b/docs/specs/command-class-specification/assets/img-0d25374112.png new file mode 100644 index 0000000..8bc9dcf Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-0d25374112.png differ diff --git a/docs/specs/command-class-specification/assets/img-0f5e748af7.png b/docs/specs/command-class-specification/assets/img-0f5e748af7.png new file mode 100644 index 0000000..8365ef1 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-0f5e748af7.png differ diff --git a/docs/specs/command-class-specification/assets/img-10ce66b311.png b/docs/specs/command-class-specification/assets/img-10ce66b311.png new file mode 100644 index 0000000..4c18d7f Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-10ce66b311.png differ diff --git a/docs/specs/command-class-specification/assets/img-13ece31554.png b/docs/specs/command-class-specification/assets/img-13ece31554.png new file mode 100644 index 0000000..047461d Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-13ece31554.png differ diff --git a/docs/specs/command-class-specification/assets/img-17ed9bdd33.png b/docs/specs/command-class-specification/assets/img-17ed9bdd33.png new file mode 100644 index 0000000..d69a6e6 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-17ed9bdd33.png differ diff --git a/docs/specs/command-class-specification/assets/img-1f27ee63d2.png b/docs/specs/command-class-specification/assets/img-1f27ee63d2.png new file mode 100644 index 0000000..1a5feaf Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-1f27ee63d2.png differ diff --git a/docs/specs/command-class-specification/assets/img-234b052b98.png b/docs/specs/command-class-specification/assets/img-234b052b98.png new file mode 100644 index 0000000..bae74a0 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-234b052b98.png differ diff --git a/docs/specs/command-class-specification/assets/img-2ed45acc64.png b/docs/specs/command-class-specification/assets/img-2ed45acc64.png new file mode 100644 index 0000000..24b0576 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-2ed45acc64.png differ diff --git a/docs/specs/command-class-specification/assets/img-2f5fb50cdf.png b/docs/specs/command-class-specification/assets/img-2f5fb50cdf.png new file mode 100644 index 0000000..c198635 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-2f5fb50cdf.png differ diff --git a/docs/specs/command-class-specification/assets/img-41477511d5.png b/docs/specs/command-class-specification/assets/img-41477511d5.png new file mode 100644 index 0000000..43a9910 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-41477511d5.png differ diff --git a/docs/specs/command-class-specification/assets/img-5e2a35351b.png b/docs/specs/command-class-specification/assets/img-5e2a35351b.png new file mode 100644 index 0000000..59a062a Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-5e2a35351b.png differ diff --git a/docs/specs/command-class-specification/assets/img-68e758a97d.png b/docs/specs/command-class-specification/assets/img-68e758a97d.png new file mode 100644 index 0000000..4200834 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-68e758a97d.png differ diff --git a/docs/specs/command-class-specification/assets/img-6ceb291c6e.png b/docs/specs/command-class-specification/assets/img-6ceb291c6e.png new file mode 100644 index 0000000..1a029d9 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-6ceb291c6e.png differ diff --git a/docs/specs/command-class-specification/assets/img-73381c079f.png b/docs/specs/command-class-specification/assets/img-73381c079f.png new file mode 100644 index 0000000..1ce5b6e Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-73381c079f.png differ diff --git a/docs/specs/command-class-specification/assets/img-762e99613e.png b/docs/specs/command-class-specification/assets/img-762e99613e.png new file mode 100644 index 0000000..8914b29 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-762e99613e.png differ diff --git a/docs/specs/command-class-specification/assets/img-7e17d638c6.png b/docs/specs/command-class-specification/assets/img-7e17d638c6.png new file mode 100644 index 0000000..b9dfc4f Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-7e17d638c6.png differ diff --git a/docs/specs/command-class-specification/assets/img-8ec64d3ea0.jpeg b/docs/specs/command-class-specification/assets/img-8ec64d3ea0.jpeg new file mode 100644 index 0000000..80e686f Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-8ec64d3ea0.jpeg differ diff --git a/docs/specs/command-class-specification/assets/img-91ca87aebd.png b/docs/specs/command-class-specification/assets/img-91ca87aebd.png new file mode 100644 index 0000000..ac63365 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-91ca87aebd.png differ diff --git a/docs/specs/command-class-specification/assets/img-95385a795f.png b/docs/specs/command-class-specification/assets/img-95385a795f.png new file mode 100644 index 0000000..3faa917 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-95385a795f.png differ diff --git a/docs/specs/command-class-specification/assets/img-9c7dfcaef5.png b/docs/specs/command-class-specification/assets/img-9c7dfcaef5.png new file mode 100644 index 0000000..2eeace5 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-9c7dfcaef5.png differ diff --git a/docs/specs/command-class-specification/assets/img-9fde74cbd0.jpeg b/docs/specs/command-class-specification/assets/img-9fde74cbd0.jpeg new file mode 100644 index 0000000..ad53569 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-9fde74cbd0.jpeg differ diff --git a/docs/specs/command-class-specification/assets/img-a5a0d9d7be.png b/docs/specs/command-class-specification/assets/img-a5a0d9d7be.png new file mode 100644 index 0000000..cdc47a9 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-a5a0d9d7be.png differ diff --git a/docs/specs/command-class-specification/assets/img-ac16ca2e4f.png b/docs/specs/command-class-specification/assets/img-ac16ca2e4f.png new file mode 100644 index 0000000..610b32e Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-ac16ca2e4f.png differ diff --git a/docs/specs/command-class-specification/assets/img-b897b5e07d.png b/docs/specs/command-class-specification/assets/img-b897b5e07d.png new file mode 100644 index 0000000..ba9805d Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-b897b5e07d.png differ diff --git a/docs/specs/command-class-specification/assets/img-bda7a771b4.jpeg b/docs/specs/command-class-specification/assets/img-bda7a771b4.jpeg new file mode 100644 index 0000000..a31d5c9 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-bda7a771b4.jpeg differ diff --git a/docs/specs/command-class-specification/assets/img-be382647c3.png b/docs/specs/command-class-specification/assets/img-be382647c3.png new file mode 100644 index 0000000..30beef5 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-be382647c3.png differ diff --git a/docs/specs/command-class-specification/assets/img-c52ce0b218.png b/docs/specs/command-class-specification/assets/img-c52ce0b218.png new file mode 100644 index 0000000..72d601e Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-c52ce0b218.png differ diff --git a/docs/specs/command-class-specification/assets/img-db9abf0d3d.png b/docs/specs/command-class-specification/assets/img-db9abf0d3d.png new file mode 100644 index 0000000..e8bb810 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-db9abf0d3d.png differ diff --git a/docs/specs/command-class-specification/assets/img-de17561660.png b/docs/specs/command-class-specification/assets/img-de17561660.png new file mode 100644 index 0000000..a408e60 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-de17561660.png differ diff --git a/docs/specs/command-class-specification/assets/img-ec0eea3305.png b/docs/specs/command-class-specification/assets/img-ec0eea3305.png new file mode 100644 index 0000000..911ded5 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-ec0eea3305.png differ diff --git a/docs/specs/command-class-specification/assets/img-ec65ec745a.png b/docs/specs/command-class-specification/assets/img-ec65ec745a.png new file mode 100644 index 0000000..5384344 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-ec65ec745a.png differ diff --git a/docs/specs/command-class-specification/assets/img-f586b8bafd.png b/docs/specs/command-class-specification/assets/img-f586b8bafd.png new file mode 100644 index 0000000..8dd5002 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-f586b8bafd.png differ diff --git a/docs/specs/command-class-specification/assets/img-f5af822b72.png b/docs/specs/command-class-specification/assets/img-f5af822b72.png new file mode 100644 index 0000000..61b59ac Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-f5af822b72.png differ diff --git a/docs/specs/command-class-specification/assets/img-f87775eaf2.png b/docs/specs/command-class-specification/assets/img-f87775eaf2.png new file mode 100644 index 0000000..0a0030c Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-f87775eaf2.png differ diff --git a/docs/specs/command-class-specification/assets/img-f8baa4593b.png b/docs/specs/command-class-specification/assets/img-f8baa4593b.png new file mode 100644 index 0000000..5f5ad3d Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-f8baa4593b.png differ diff --git a/docs/specs/command-class-specification/assets/img-f94675db5a.png b/docs/specs/command-class-specification/assets/img-f94675db5a.png new file mode 100644 index 0000000..ac73583 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-f94675db5a.png differ diff --git a/docs/specs/command-class-specification/assets/img-fb25e9706c.png b/docs/specs/command-class-specification/assets/img-fb25e9706c.png new file mode 100644 index 0000000..8a197f2 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-fb25e9706c.png differ diff --git a/docs/specs/command-class-specification/assets/img-fbc9bfea32.png b/docs/specs/command-class-specification/assets/img-fbc9bfea32.png new file mode 100644 index 0000000..12d5a69 Binary files /dev/null and b/docs/specs/command-class-specification/assets/img-fbc9bfea32.png differ diff --git a/docs/specs/command-class-specification/index.md b/docs/specs/command-class-specification/index.md new file mode 100644 index 0000000..07dc232 --- /dev/null +++ b/docs/specs/command-class-specification/index.md @@ -0,0 +1,19 @@ + + +# SDS13781-4 Z-Wave Application Command Class Specification + +*Source:* [SDS13781-4 Z-Wave Application Command Class Specification.pdf](../sources/SDS13781-4 Z-Wave Application Command Class Specification.pdf) +*Pages:* 592 +*Generated by:* `tools/pdf2md/convert.py` (PyMuPDF 1.27.1) + + +## Chapters + +- [1 Abbreviations](01-abbreviations.md) +- [2 Introduction](02-introduction/index.md) +- [3 Command Class Overview](03-command-class-overview/index.md) +- [4 Command Class Definitions](04-command-class-definitions/index.md) diff --git a/docs/specs/sources/INS13954-Instruction-Z-Wave-500-Series-Appl-Programmers-Guide-v6_8x_0x.pdf b/docs/specs/sources/INS13954-Instruction-Z-Wave-500-Series-Appl-Programmers-Guide-v6_8x_0x.pdf new file mode 100644 index 0000000..63dc9c1 Binary files /dev/null and b/docs/specs/sources/INS13954-Instruction-Z-Wave-500-Series-Appl-Programmers-Guide-v6_8x_0x.pdf differ diff --git a/docs/specs/sources/SDS13781-4 Z-Wave Application Command Class Specification.pdf b/docs/specs/sources/SDS13781-4 Z-Wave Application Command Class Specification.pdf new file mode 100644 index 0000000..4262702 Binary files /dev/null and b/docs/specs/sources/SDS13781-4 Z-Wave Application Command Class Specification.pdf differ diff --git a/docs/specs/sources/Z-Wave Host API Specification.pdf b/docs/specs/sources/Z-Wave Host API Specification.pdf new file mode 100644 index 0000000..c78a927 Binary files /dev/null and b/docs/specs/sources/Z-Wave Host API Specification.pdf differ diff --git a/docs/specs/zwave-500-series-programmers-guide/01-abbreviations.md b/docs/specs/zwave-500-series-programmers-guide/01-abbreviations.md new file mode 100644 index 0000000..5615c11 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/01-abbreviations.md @@ -0,0 +1,73 @@ + +# 1 Abbreviations + +| Abbreviation | Explanation | +| --- | --- | +| ACK | Acknowledge | +| AES | The Advanced Encryption Standard is a symmetric block cipher algorithm. The AES is a NIST-standard cryptographic cipher that uses a block length of 128 bits and key lengths of 128, 192 or 256 bits. Officially replacing the Triple DES method in 2001, AES uses the Rijndael algorithm developed by Joan Daemen and Vincent Rijmen of Belgium. | +| ANZ | Australia/New Zealand | +| AODV | Ad hoc On-Demand Distance Vector (AODV) Routing. | +| API | Application Programming Interface | +| APR | Application Priority Route | +| ASIC | Application-Specific Integrated Circuit | +| CR | Carriage Return, move the position of the cursor to the first position on the same line. | +| DLL | Dynamic Link Library | +| DUT | Device Under Test | +| ECB | Electronic CookBook (block cipher mode) | +| ERTT | Enhanced Reliability Test tool | +| EU | Europe | +| FET | Field-Effect Transistor | +| FLiRS | Frequently Listening Routing Slave. Communication to a FLiRS node can be established by a wakeup beam. | +| GNU | An organization devoted to the creation and support of Open Source software | +| HK | Hong Kong | +| HW | Hardware | +| IGBT | Insulated Gate Bipolar Transistor | +| IL | Israel | +| IN | India | +| IR | InfraRed | +| ISR | Interrupt Service Routines | +| JP | Japan | +| KR | South Korea | +| LF | Line Feed, Move cursor to the next line | +| LRC | Longitudinal Redundancy Check | +| LS | Less significant | +| LWR | Last Working Route | +| MS | Most significant | +| MTP | Many Times Programmable memory | +| MY | Malaysia | +| NAK | Not Acknowledged | +| NLWR | Next to Last Working Route | +| NVM | Non-Volatile Memory | +| NVR | Non-Volatile Read memory (cannot write) | +| NWI | Network Wide Inclusion (add node out of direct range) | +| NWE | Network Wide Exclusion (remove node out of direct range) | +| OTA | Over The Air (e.g., making a firmware update wireless) | +| OTW | Over The Wire (e.g., making a firmware update via the serial API interface) | +| PA | Power Amplifier | +| POR | Power On Reset | +| PRBS | Pseudo-Random Binary Sequence | +| PRNG | Pseudo-Random Number Generator | +| PWM | Pulse Width Modulator | +| RF | Radio Frequency | +| RFRNG | Radio Frequency Random Number Generator | + +| Abbreviation | Explanation | +| --- | --- | +| RU | Russian Federation | +| SDK | Software Developer’s Kit | +| SFR | Special Function Registers | +| SIS | SUC ID Server | +| SoC | System-on-Chip | +| SOF | Start Of Frame | +| SPI | Serial Peripheral Interface | +| SUC | Static Update Controller | +| UPnP | Universal Plug and Play | +| US | United States | +| WUT | Wake Up Timer | +| XML | eXtensible Markup Language | diff --git a/docs/specs/zwave-500-series-programmers-guide/02-introduction/02.01-purpose.md b/docs/specs/zwave-500-series-programmers-guide/02-introduction/02.01-purpose.md new file mode 100644 index 0000000..03e4b82 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/02-introduction/02.01-purpose.md @@ -0,0 +1,14 @@ + +# 2.1 Purpose + +The Application Programming Guide gives guidance for developing Z-Wave application programs, which use the Z-Wave application programming interface (API) to access the Z-Wave Protocol services and [500 Series SoC resources. For host processor application development using the serial API, refer also to [2].](../08-references.md#8-references) + +[For details about working in the 500 Series environment, refer to [14].](../08-references.md#8-references) + +The document is also an API reference guide for programmers. diff --git a/docs/specs/zwave-500-series-programmers-guide/02-introduction/02.02-audience-and-prerequisites.md b/docs/specs/zwave-500-series-programmers-guide/02-introduction/02.02-audience-and-prerequisites.md new file mode 100644 index 0000000..84f6abf --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/02-introduction/02.02-audience-and-prerequisites.md @@ -0,0 +1,10 @@ + +# 2.2 Audience and Prerequisites + +The audience is Z-Wave partners and Silicon Labs involved in application development. The application programmer should be familiar with the PK51 Keil Development Tool Kit for 8051 micro controllers. diff --git a/docs/specs/zwave-500-series-programmers-guide/02-introduction/02.03-key-words-to-indicate-requirement-levels.md b/docs/specs/zwave-500-series-programmers-guide/02-introduction/02.03-key-words-to-indicate-requirement-levels.md new file mode 100644 index 0000000..ef59acc --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/02-introduction/02.03-key-words-to-indicate-requirement-levels.md @@ -0,0 +1,10 @@ + +# 2.3 Key words to Indicate Requirement Levels + +[The guidelines outlined in IETF RFC 2119 “Key words for use in RFCs to Indicate Requirement Levels” [17] apply:](../08-references.md#8-references) The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. diff --git a/docs/specs/zwave-500-series-programmers-guide/02-introduction/index.md b/docs/specs/zwave-500-series-programmers-guide/02-introduction/index.md new file mode 100644 index 0000000..9d9220e --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/02-introduction/index.md @@ -0,0 +1,14 @@ + +# 2 Introduction + +## Contents + +- [2.1 Purpose](02.01-purpose.md) +- [2.2 Audience and Prerequisites](02.02-audience-and-prerequisites.md) +- [2.3 Key words to Indicate Requirement Levels](02.03-key-words-to-indicate-requirement-levels.md) diff --git a/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.01-z-wave-system-startup-code.md b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.01-z-wave-system-startup-code.md new file mode 100644 index 0000000..ecff7a7 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.01-z-wave-system-startup-code.md @@ -0,0 +1,12 @@ + +# 3.1 Z-Wave System Startup Code + +The Z-Wave modules include the system startup function (main). The Z-Wave system startup function first initializes the Z-Wave hardware and then calls the application hardware initialization function ApplicationInitHW. Then initializing the Z-Wave software (including the software timer used by the timer module), initializes the NVM if necessary and finally calling the application software initialization function ApplicationInitSW. Execution then proceeds in the Z-Wave main loop. + +Notice: Initialization of the external NVM is now handled internally by the Z-Wave protocol library. The protocol will now delete and initialize the NVM on bootup if a 16 bit validation field in the NVM is not correct Therefore the NVM initialization file extern_epp.hex is now obsoleted. diff --git a/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.02-z-wave-main-loop.md b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.02-z-wave-main-loop.md new file mode 100644 index 0000000..91f7183 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.02-z-wave-main-loop.md @@ -0,0 +1,12 @@ + +# 3.2 Z-Wave Main Loop + +The Z-Wave main loop will call the list of Z-Wave protocol functions, including the ApplicationPoll function and the ApplicationCommandHandler function (if a frame was received) in round robin order. The functions must therefore be designed to return to the caller as fast as possible to allow the MCU to do other tasks. Busy loops are not allowed. This will make it possible to receive Z-Wave data, transfer data via the UART and check user-activated buttons, etc. “simultaneously”. In order not to disrupt the radio communication and the protocol, no application function must execute code for more than 5ms without returning. + +For production testing the application can be forced into the ApplicationTestPoll function instead of the ApplicationPoll function. diff --git a/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.03-z-wave-protocol-layers.md b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.03-z-wave-protocol-layers.md new file mode 100644 index 0000000..1c5f9c3 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.03-z-wave-protocol-layers.md @@ -0,0 +1,12 @@ + +# 3.3 Z-Wave Protocol Layers + +When transmission of data to another node is requested, the Z-Wave protocol layer adds a frame header and a checksum to the data before transmission. The protocol layer also handles frame retransmissions, as well as routing of frames through “repeater” nodes to Z-Wave nodes that are not within direct RF communication reach. When the frame transmission is completed, an application-specified transmit complete callback function is called. The transmission complete callback function includes a parameter that indicates the transmission result. The transmission complete callback function indicate also when the next frame can be send to avoid overwriting the transmit queue. + +The Z-Wave frame receiver module (within the MAC layer) can include more than one frame receive buffer, so the upper layers can interpret one frame while the next frame is received. diff --git a/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.04-z-wave-routing-principles.md b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.04-z-wave-routing-principles.md new file mode 100644 index 0000000..f2f3527 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.04-z-wave-routing-principles.md @@ -0,0 +1,32 @@ + +# 3.4 Z-Wave Routing Principles + +The Z-Wave protocol use source routing, which is a technique whereby the sender of a frame specifies the exact route the frame must take to reach the destination node. Source routing assumes that the sender knows the topology of the network, and can therefore determine a route having a minimum number of hops. The Z-Wave protocol supports up to four repeaters between sender and destination node. Routing can also be used to reach FLiRS destination nodes. Source routing allows implementation of a leightweight protocol by avoiding distributed topologies in all repeaters. Nodes containing the topology can also assign routes to a topology-less node enabling it to communicate with a number of destination nodes using routes. + +In case sender fails to reach destination node using routes an explorer mechanism can be launched on demand to discover a working route to the destination node in question. The explorer mechanism builds on AODV routing with adjustments for source routing and memory footprint. Explorer frames implement managed multi-hop broadcast forwarding and returns a working route to sender as result. The application payload piggybacks on explorer frame to reduce latency. + +The routing algorithm in controllers store information about successful attempts to reach a destination node avoiding repetition of previously failed attempts. The last successful route used between sender and destination node are stored in NVM and is called Last Working Route(LWR). The LWR list comprises of 232 destination nodes having up to two routes each, called the LWR and the Next to Last Working Route (NLWR). A LWR/NLWR can contain either a direct or a routed route. Updating LWR and NLWR happens in the following situations (if new route != current LWR): + + When receiving a successful explorer frame route, new route becomes LWR and old LWR becomes NLWR.  When receiving a successful routed/direct request from another node, new route becomes LWR and old LWR becomes NLWR. However, there are two exceptions where the new route does not become LWR. The LWR and NLWR stays unchanged when a speed modified frame (lower speed) or 9.6kbps direct frame are received successfully.  When receiving a successful acknowledge for a transmitted explorer frame, new route becomes LWR and old LWR becomes NLWR.  When receiving a successful acknowledge for a transmitted NLWR, NLWR becomes LWR.  When receiving a successful acknowledge for a transmitted routed/direct frame, new route becomes LWR and old LWR becomes NLWR. + +Incase a LWR/NLWR fails the LWR and NLWR are updated as follows: + + If a LWR fails; it is ‘exiled’ to become the NLWR and the current NLWR (if present) is tried as the next route.  If a NLWR fails it is removed. + +The Application can, instead of having both the LWR and the NLWR entries for a destination node, overload the LWR with an Application Priority Route (APR), which then upgrades the NLWR to LWR status as the protocol now is down to one dynamic LWR for the destination node in question. The APR will after being set always be tried prior to any possible present LWR. The APR can only be removed by the Application. If destination node has an APR defined the updating of the LWR happens in the following situations (if new route != APR AND new route != LWR) + + When receiving a successful explorer frame route, new route becomes LWR.  When receiving a successful routed/direct request from another node, new route becomes LWR.  When receiving a successful acknowledge for a transmitted explorer frame, new route becomes LWR.  When receiving a successful acknowledge for a transmitted routed/direct frame, new route becomes LWR.  Incase LWR fails it is removed. + +The routing algorithm in slaves store information about successful attempts to reach a destination node in response routes after the following principles: + + When receiving a successful explorer frame route, new route becomes a new Response Route.  When receiving a successful routed/direct request from another node, new route becomes a new Response Route.  When receiving a successful acknowledge for a transmitted explorer frame, new route becomes a new Response Route.  When receiving a successful acknowledge for a transmitted routed/direct frame, new route becomes a new Response Route.  Incase Response Route fails it is removed. However, the response routes only contains up to two routes to different destination nodes. A response route for a new destination node overwrites the oldest of the two buffered response routes. A new response route for an existing destination overwrites the old response route for that specific destination. + +[The routing attempts depend on the Z-Wave library and transmit options used in the node, for details refer to section 3.10.](03.10-z-wave-nodes.md#310-z-wave-nodes) + +The source routing algorithm does not alter the topology due to failed attempts or store any statistics regarding link quality. diff --git a/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.05-z-wave-application-layer.md b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.05-z-wave-application-layer.md new file mode 100644 index 0000000..b2df944 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.05-z-wave-application-layer.md @@ -0,0 +1,66 @@ + +# 3.5 Z-Wave Application Layer + +The application layer provides the interface to the communications environment which is used by the application process. The application software is located in the hardware initialization function ApplicationInitHW, software initialization function ApplicationInitSW, application state machine (called from the Z-Wave main poll loop) ApplicationPoll, command complete callback functions, and a receive command handler function ApplicationCommandHandler. + +The application implements communication on application level with other nodes in the network. On application level, a framework is defined of Device and Command Classes to obtain interoperability [between Z-Wave enabled products from different vendors. For details of the Z-Wave Plus Framework refer to [4]-[5] and [7]-[12]. For details of the old Z-Wave Framework but still interoperable refer to [6].](../08-references.md#8-references) The basic structure of these commands provides the capability to set parameters in a node and to request parameters from a node responding with a report containing the requested parameters. The Device and Command Classes are defined in the header file ZW_classcmd.h. + +Wireless communication is by nature unreliable because a well-defined coverage area simply does not exist since propagation characteristics are dynamic and unpredictable. The Z-Wave protocol minimizes these "noise and distortion" problems by using a transmission mechanisms of the frame there include two re-transmissions to ensure reliable communication. In addition are single casts acknowledged by the receiving node so the application is notified about how the transmission went. No precautions can unfortunately prevent that multiple copies of the same frame are passed to the application. Therefore is it very important to implement a robust state machine on application level there can handle multiple copies of the same frame. Below are shown a couple of examples how this can happen: Node A Node B + +Set Cmd + +Ack + +Random backoff + +Set Cmd (Retry) + +Ack Time + +Figure 2. Multiple Copies of the Same Set Frame + +Node A Node B Get Cmd + +Ack + +Report + +Ack + +Get Cmd (Retry) + +Ack + +Report + +Ack Time + +Figure 3. Multiple Copies of the Same Get/Report Frame + +The Z-Wave protocol is designed to have low latency on the expense of handling simultaneously communication to a number of nodes in the Z-Wave network. To obtain this is the number of random backoff values limited to 4 (0, 1, 2, and 3). The figure below shows how simultaneous communication to even a small number of nodes easily can block the communication completely. + +Node A Nodes within direct range + +Get Cmd as Broadcast + +100% of the nodes responds + +25% of the nodes responds (RB=0) + +25% of the nodes responds (RB=1) + +25% of the nodes responds (RB=2) + +25% of the nodes responds (RB=3) + +Time + +Figure 4. Simultaneous Communication to a Number of Nodes + +Avoid simultaneous request to a number of nodes in a Z-Wave network in case the nodes in question respond on the application level. diff --git a/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.06-z-wave-software-timers.md b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.06-z-wave-software-timers.md new file mode 100644 index 0000000..a8cd450 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.06-z-wave-software-timers.md @@ -0,0 +1,14 @@ + +# 3.6 Z-Wave Software Timers + +The Z-Wave timer module is designed to handle a limited number of simultaneous active software timers. The Z-Wave basis software reserves some of these timers for protocol timeouts. + +A delayed function call is initiated by a TimerStart API call to the timer module, which saves the function address, sets up the timeout value and returns a timer-handle. The timer-handle can be used to cancel the timeout action e.g., an action completed before the time runs out. + +The timer can also be used for frequent inspection of special hardware e.g., a keypad. Specifying the time settings to 50 ms and repeating forever will call the timer call-back function every 50 msec. diff --git a/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.07-z-wave-hardware-timers.md b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.07-z-wave-hardware-timers.md new file mode 100644 index 0000000..d6287da --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.07-z-wave-hardware-timers.md @@ -0,0 +1,20 @@ + +# 3.7 Z-Wave Hardware Timers + +The 200/300/400/500 Series Z-Wave SoCs have a number of hardware timers/counters. Some are reserved by the protocol and others are free to be used by the application as shown in the table below: + +Table 1. 200/300/400/500 Series Z-Wave SoCs Hardware Timer Allocation + +| | 200 Series | 300 Series | 400 Series | 500 Series | +| --- | --- | --- | --- | --- | +| TIMER0 | Protocol system clock | Protocol system clock | Available for the application | Available for the application | +| TIMER1 | Available for the application | Available for the application | Used by the protocol | Available for the application | +| GPTIMER | Available for the application | Available for the application | Available for the application | Available for the application | + +The TIMER0 and TIMER1 are standard 8051 timers/counters. diff --git a/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.08-z-wave-hardware-interrupts.md b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.08-z-wave-hardware-interrupts.md new file mode 100644 index 0000000..4eae7ea --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.08-z-wave-hardware-interrupts.md @@ -0,0 +1,20 @@ + +# 3.8 Z-Wave Hardware Interrupts + +Application interrupt service routines (ISR) must use 8051 register bank 0. However, do not use USING 0 attribute when declaring ISR’s. The Z-Wave protocol uses 8051 register bank 1 for protocol ISR’s, see table below regarding application ISR availability: + +Table 2. 200/300/400/500 Series Z-Wave SoC Application ISR Availability + +| 200 Series | 300 Series | 400 Series | 500 Series | +| --- | --- | --- | --- | +| INUM INT1 _ INUM TIMER1 _ INUM SERIAL _ INUM SPI _ INUM TRIAC _ INUM GP TIMER _ _ INUM ADC _ | INUM INT1 _ INUM TIMER1 _ INUM SERIAL _ INUM SPI _ INUM TRIAC _ INUM GP TIMER _ _ INUM ADC _ | INUM INT0 _ INUM TIMER0 _ INUM SERIAL0 _ INUM SPI0 _ INUM TRIAC _ INUM GP TIMER _ _ INUM ADC _ INUM USB _ INUM IR _ | INUM INT0 _ INUM INT1 _ INUM TIMER0 _ INUM SERIAL0 _ INUM SPI0 _ INUM TRIAC _ INUM GP TIMER _ _ INUM ADC _ INUM USB _ INUM IR _ | + +The duration of an application interrupt routine must be below 80us. + +Refer to ZW020x.h, ZW030x.h, ZW040x.h and ZW050x.h header files with respect to ISR definitions. For an example, refer to UART ISR in serial API sample application. diff --git a/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.09-interrupt-service-routines.md b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.09-interrupt-service-routines.md new file mode 100644 index 0000000..e25a0ec --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.09-interrupt-service-routines.md @@ -0,0 +1,32 @@ + +# 3.9 Interrupt Service Routines + +When using interrupt service routines from one of the hardware interfaces such as ADC, GP timer or UART, one should be aware of certain issues as described in the following sections. + +## 3.9.1 SFR Pages + +The 500 Series Z-Wave SoC uses multiple pages of 8051 SFR registers. The page selection is set using SFRPAGE. Consequently the SFRPAGE must be preserved when calling an Interrupt Service Routine (ISR) in your code. In order to do this the intrinsic functions _push_() and _pop_() must be called. Function _push_() must be called when the ISR starts, and _pop_() just before returning from the ISR. + +For example, the ISR of the ADC should be look as follow: + +#include + +void ADC_int(void) interrupt INUM_ADC { _push_(SFRPAGE) 1; + +call api’s _pop_(SFRPAGE); } + +## 3.9.2 Calling Functions from ISR + +The 8051 core of the 500 Series Z-Wave SoC has no register-to-register move. Therefore, the compiler generates register to memory moves instead. Since the compiler knows the register bank, the physical address of a register in a register bank can be calculated. For example, when the compiler calculates the address of register R2 in register bank 0, the address is 0x02. If the register bank selected is not really 0, then the function overwrites this register. This might result in unpredictable behavior of the program. This technique of accessing a register using its absolute address is called absolute register addressing. + +In the Z-Wave system the system timer and RF interrupt use register bank 1. The default register bank used for non-interrupt code is register bank 0. Therefore, if a function is called from an ISR it might be looking in the wrong place for its register values. + +To solve this problem, one of these solutions can be used: + +1. Use the C51’s REGISTERBANK directive to specify that a certain function uses the same register bank as the ISR that calls the function. Hence, no code is generated in the function to switch the register bank. For example: #pragma registerbank(1) void foo (void) { } 2. Use the NOAREGS directive to specify that the compiler should not use absolute register addressing. This make the function register bank independent so that it may be called from any function that uses a different register bank than the default. diff --git a/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.10-z-wave-nodes.md b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.10-z-wave-nodes.md new file mode 100644 index 0000000..99e6241 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/03.10-z-wave-nodes.md @@ -0,0 +1,207 @@ + +# 3.10 Z-Wave Nodes + +From a protocol point of view, there are five types of Z-Wave nodes: Portable Controller nodes, Static Controller nodes, Bridge Controller nodes, Routing Slave nodes, and Enhanced 232 Slave nodes. All controller based nodes stores information about other nodes in the Z-Wave network. The node information includes the nodes each of the nodes can communicate with (routing information). The Installation node will present itself as a Controller node, which includes extra functionality to help a professional installer setup, configure, and troubleshoot a Z-Wave network. The bridge controller node stores information about the nodes in the Z-Wave network and in addition is it possible to generate up to 128 Virtual Slave nodes. + +## 3.10.1 Z-Wave Portable Controller Node + +The software components of a Z-Wave portable controller are split into the controller application and the Z-Wave-Controller basis software, which includes the Z-Wave protocol layers and control of the various data stored into the NVM. + +Portable controller nodes include an external NVM in which the non-volatile application data area can be placed. The Z-Wave basis software has reserved the first area of the external NVM. Controller Application + +Z-Wave Controller + +Figure 5. Portable Controller Node Architecture + +The Portable Controller node has a unique home ID number assigned, which is stored in the Z-Wave basis area of the external NVM. Care must be taken, when reprogramming the external NVM, that different controller nodes do not get the same home ID number. + +When new Slave nodes are registered to the Z-Wave network, the Controller node assigns the home ID and a unique node ID to the Slave node. The Slave node stores the home ID and node ID. + +When a controller is primary, it will send any networks changes to the SUC node in the network. Controllers can request network topology updates from the SUC node. + +The routing attempts done by a portable controller to reach the destination node are as follows:  If APR, LWR and NLWR all are non-existing and TRANSMIT_OPTION_ACK set. Try direct with retries.  If APR exist and TRANSMIT_OPTION_ACK set. Try direct without retries. In case it fails, try the APR. If APR fails then try LWR if it exist and if it also fails then remove the LWR.  If APR do not exist, LWR exist and TRANSMIT_OPTION_ACK set. Try direct without retries. In case it fails, try the LWR. In case the LWR also fails, ‘exile’ it to become NLWR and try old NLWR if it exist. if the NLWR also fails, remove it.  If APR do not exist, LWR do not exist, NLWR exist and TRANSMIT_OPTION_ACK set. Try direct without retries. In case it fails, try the NLWR. In case the NLWR also fails remove it.  If TRANSMIT_OPTION_ACK and TRANSMIT_OPTION_AUTO_ROUTE are set then calculate up to two routing attempts per entry/repeater node. In case TRANSMIT_OPTION_EXPLORE set, a maximum number limits number of tries.  If TRANSMIT_OPTION_ACK and TRANSMIT_OPTION_NO_ROUTE are set, then direct with retries.  If TRANSMIT_OPTION_ACK and TRANSMIT_OPTION_EXPLORE are set then issue an explore frame as last resort. + +When developing application software, the header file “ZW_controller_api.h” also include the other Z-Wave API header files e.g., ZW_timer_api.h. + +The following define must be set when compiling the application: ZW_CONTROLLER. + + The application must be linked with ZW_CONTROLLER_PORTABLE_ZW S.LIB  (= 050X for 500 Series Z-Wave modules, etc). + +## 3.10.2 Z-Wave Static Controller Node + +The software components of a Z-Wave static controller node are split into a Static Controller application and the Z-Wave Static Controller basis software, which includes the Z-Wave protocol layers and control of the various data stored into the NVM. + +[The difference between the static controller and the controller described in chapter 3.10.1 is that the](03.10-z-wave-nodes.md#3101-z-wave-portable-controller-node) static controller cannot be powered down, that is it cannot be used for battery-operated devices. The static controller has the ability to look for neighbors when requested by a controller. This ability makes it possible for a primary controller to assign static routes from a routing slave to a static controller. + +The Static Controller can be set as a SUC node, so it can sends network topology updates to any requesting secondary controller. A secondary static controller not functioning as SUC can also request network Topology updates. + +The routing attempts done by a static controller to reach the destination node are as follows:  If APR, LWR and NLWR all are non-existing and TRANSMIT_OPTION_ACK set. Try direct when neighbors with retries.  If APR exist and TRANSMIT_OPTION_ACK set. Try the APR. If APR fails then try LWR if it exist and if it also fails then remove the LWR and try direct if neighbor.  If APR do not exist, LWR exist and TRANSMIT_OPTION_ACK set. Try the LWR. In case the LWR fails, ‘exile’ it to become NLWR and try old NLWR if it exist. if the NLWR also fails, remove it and try direct if neighbor.  If APR do not exist, LWR do not exist, NLWR exist and TRANSMIT_OPTION_ACK set. Try the NLWR. In case the NLWR fails remove it and try direct if neighbor.  If TRANSMIT_OPTION_ACK and TRANSMIT_OPTION_AUTO_ROUTE are set then calculate up to two routing attempts per entry/repeater node. If enough routes exist try a settable maximum number of tries.  If TRANSMIT_OPTION_ACK and TRANSMIT_OPTION_NO_ROUTE are set, then direct with retries.  If TRANSMIT_OPTION_ACK and TRANSMIT_OPTION_EXPLORE are set then issue an explore frame as last resort. + +When developing application software, the header file “ZW_controller_static_api.h” also includes the other Z-Wave API header files e.g., ZW_timer_api.h. + +The following define is being included compiling the application: ZW_CONTROLLER_STATIC. + + The application must be linked with ZW_CONTROLLER_STATIC_ZW S.LIB  (= 050X for 500 Series Z-Wave modules, and so on). + +## 3.10.3 Z-Wave Bridge Controller Node + +The software components of a Z-Wave Bridge Controller node are split into a Bridge Controller application and the Z-Wave Bridge Controller basis software, which includes the Z-Wave protocol layer. + +The Bridge Controller is essential a Z-Wave Static Controller node, which incorporates extra functionality that can be used to implement controllers, targeted for bridging between the Z-Wave network and others network (ex. UPnP). + +The Bridge application interface is an extended Static Controller application interface, which besides the Static Controller application interface functionality gives the application the possibility to manage Virtual Slave nodes. Virtual Slave nodes is a routing slave node without repeater and assign return route functionality, which physically resides in the Bridge Controller. This makes it possible for other Z-Wave nodes to address up to 128 Slave nodes that can be bridged to some functionality or to devices, which resides on a foreign Network type. + +The routing attempts done by a bridge controller to reach the destination node are as follows:  If APR, LWR and NLWR all are non-existing and TRANSMIT_OPTION_ACK set. Try direct when neighbors with retries.  If APR exist and TRANSMIT_OPTION_ACK set. Try the APR. If APR fails then try LWR if it exist and if it also fails then remove the LWR and try direct if neighbor.  If APR do not exist, LWR exist and TRANSMIT_OPTION_ACK set. Try the LWR. In case the LWR fails, ‘exile’ it to become NLWR and try old NLWR if it exist. if the NLWR also fails, remove it and try direct if neighbor.  If APR do not exist, LWR do not exist, NLWR exist and TRANSMIT_OPTION_ACK set. Try the NLWR. In case the NLWR fails remove it and try direct if neighbor.  If TRANSMIT_OPTION_ACK and TRANSMIT_OPTION_AUTO_ROUTE are set then calculate up to two routing attempts per entry/repeater node. In case TRANSMIT_OPTION_EXPLORE set, a maximum number limits number of tries.  If TRANSMIT_OPTION_ACK and TRANSMIT_OPTION_AUTO_ROUTE are set, then direct with retries.  If TRANSMIT_OPTION_ACK and TRANSMIT_OPTION_EXPLORE are set then issue an explore frame as last resort. + +When developing application software the header file “ZW_controller_bridge_api.h” also include the other Z-Wave API header files. + +The following define is being included compiling the application: ZW_CONTROLLER_BRIDGE. + + The application must be linked with ZW_CONTROLLER_BRIDGE_ZW S.LIB  (= 050X for 500 Series Z-Wave modules, etc). + +## 3.10.4 Z-Wave Routing Slave Node + +The software components of a Z-Wave routing slave node are split into a Slave application and the Z-Wave-Slave basis software, which includes the Z-Wave protocol layers. + +Slave Application + +| Trans | port API | +| --- | --- | + +Z-Wave Slave + +Figure 6. Routing Slave Node Architecture + +The routing slave is capable of initiating communication. Examples of a routing slave could be a wall control or temperature sensor. If a user activates the wall control, the routing slave sends an “on” command to a lamp (slave). The routing slave does not have a complete routing table. Frames are sent to destinations configured during association. The association is performed via a controller. If routing is needed for reaching the destinations, it is also up to the controller to calculate the routes. + +Routing slave nodes have an area of 256 bytes MTP (Many Times Programmable memory) for storing data. The Z-Wave basis software reserves the first part of this area, and application data uses the remaning part. + +The home ID is set to a randomly generated value and node ID is zero. When registering a slave node to a Z-Wave network the slave node receive home and node ID from the networks primary controller node. These IDs are stored in the Z-Wave basis data area in the flash. The routing slave can send unsolicited and non-routed broadcasts, singlecasts, and multicasts. Singlecasts can also be routed. Further, it can respond with a routed singlecast (response route) in case another node has requested this by sending a routed singlecast to it. A received multicast or broadcast results in a response route without routing. + +A temperature sensor based on a routing slave may be battery operated. To improve battery lifetime, the application may bring the node into sleep mode most of the time. Using the wake-up timer (WUT), the application may wake up once per second, measure the temperature and go back to sleep. In case the measurement exceeded some threshold, a command (e.g., “start heating”) may be sent to a heating device before going back to sleep. + +The routing attempts done by a routing slave to reach the destination node are as follows: + + If TRANSMIT_OPTION_ACK is set and destination is available in response routes, try response route.  If TRANSMIT_OPTION_ACK and TRANSMIT_OPTION_AUTO_ROUTE are set then try return routes if any exists for specified destination.  If TRANSMIT_OPTION_ACK and TRANSMIT_OPTION_AUTO_ROUTE are set then try direct.  If TRANSMIT_OPTION_ACK and TRANSMIT_OPTION_EXPLORE are set, issue an explore frame as last resort. + +The return routes comprises of up to five destinations having up to 4 routes each. Return routes can contain a no repeater route (direct) up to a full 4 repeater route. + +The return routes are tried in the order of priority, highest first. The priority of the return routes are dynamically updated when return routes either succeed or fails. + +The Application can set a Priority Return Route, which always will have the highest priority and therefor always be tried as the first return route and can only be removed by the Application. The priority return route will when set use one of the available 4 route entries. + +New routes/direct are qualified for return route insertion by checking if the destination exist and route/direct do not exist. In that event the new route/direct entry will be placed either in a free route or the one having lowest priority. A number of limitations are unfortunately necessary with respect to Security S2 due to lack of external NVM: + + All key classes supported but only one can be active after inclusion (add).  Slave routing based devices will when entering Sleep mode save the “Most Recently Used” (MRU) S2 SPAN entry in critical RAM. The MRU S2 SPAN entry are restored on power up if a valid S2 SPAN entry resides in critical RAM.  [S2 Public-Private key pair resides in Protocol part of NVR and written to NVR at production. Refer to [22] for details.](../08-references.md#8-references)  Cannot send S2 multicast but do support S2 multicast receive. + +The table below show the NVM memory budget of the full routing slave with S0/S2 functionality included is as follows: + +| # | Functionality | Bytes | +| --- | --- | --- | +| 1 | Home ID, Node ID, magic bytes and SUC return routes. | 25 | +| 2 | Return routes: 5 destinations having 4 full hop routes each 5 destinations x (1 destination byte + 4 x (4 hop bytes + 1 aux. byte)) | 105 | +| 3 | Keyclass byte – Which security keyclass is active – Only ONE keyclass can be active at any time, can be either S0, S2 (3 keyclasses) | 1 | +| 4 | S0/S2 Network key | 16 | +| 5 | Critical SPAN nodeID – Identifies the SPAN, which is saved in Critical RAM when going into Sleepmode and reloaded on wakeup from Sleepmode – This means that no resync (S2) is needed for the Critical SPAN nodeID after wakeup from Sleepmode. If equal to ZERO the MRU SPAN entry will be stored/restored. | 1 | + +The routing slave NVM is placed in the MTP (Total of 255 Bytes) resulting in 107 Bytes available for the application. + +No SPAN/MPAN are saved in NVM, which for a FLiRS node would mean that the node needs to sync every time it wakes up in case it want to communicate with another node. But to minimize the resync after Sleepmode we do save ONE SPAN in Critical RAM (retention RAM). + +The Critical RAM is 128 Bytes retention memory – Currently 32 Bytes are allocated for Application and 96 bytes are allocated for protocol. The table below shows the protocol Critical RAM requirement for a Routing Slave with one SPAN entry. + +| # | Functionality | Bytes | +| --- | --- | --- | +| 1 | Protocol usage: phyRfData, ResponseRoutes, FLiRS, NodeID, HomeID etc. | 51 | +| 2 | 1 S2 SPAN | 39 | +| 3 | Smart Start-specific variables | 6 | + +[The ECDH keypair for routing slaves is stored in the NVR [22] and must be generated and pre-](../08-references.md#8-references) programmed during production. The updated NVR layout must be used when producing a SDK 6.8x based routing slaves. The routing slave cannot detect if the keypair is missing. + +When developing application software, the header file “ZW_slave_routing_api.h” also includes the other Z-Wave API header files e.g., ZW_timer_api.h. + +The following define will be generated by the headerfile, if it does not already exist when when compiling the application: ZW_SLAVE. + + The application must be linked with ZW_SLAVE_ROUTING_ZW S.LIB  (= 050X for 500 Series Z-Wave modules, etc). + +## 3.10.5 Z-Wave Enhanced 232 Slave Node + +The Z-Wave enhanced 232 slave has the same basic functionality as a Z-Wave routing slave node, but offers return route assignment of up to 232 destination nodes instead of 5. + +Slave Application + +| Timer API | | +| --- | --- | +| | RTC API | + +| External EEPROM | | | | +| --- | --- | --- | --- | +| | | | | +| | | Z-Wav data | e | + +| Trans | port API | +| --- | --- | + +Z-Wave Slave + +Figure 7. Enhanced 232 Slave Node Architecture Enhanced 232 slave nodes have an external NVM and a WUT. The Z-Wave basis software reserves the first area of the external NVM: The last area of the NVM is reserved for the application data. + +The routing attempts done by an enhanced 232 slave to reach the destination node are as follows: + + If TRANSMIT_OPTION_ACK is set and destination is available in response routes, try response route.  If TRANSMIT_OPTION_ACK and TRANSMIT_OPTION_AUTO_ROUTE are set then try return routes if any exists for specified destination.  If TRANSMIT_OPTION_ACK and TRANSMIT_OPTION_AUTO_ROUTE are set then try direct.  If TRANSMIT_OPTION_ACK and TRANSMIT_OPTION_EXPLORE are set, issue an explore frame as last resort. + +The return route comprises of up to 232 destinations having up to four routes each. Return routes can contain a no repeater route (direct) up to a full 4 repeater route. + +The return routes are tried in the order of priority, highest first. The priority of the return routes are dynamically updated when return routes either succeed or fails. + +The Application can set a Priority Return Route, which always will have the highest priority and therefor always be tried as the first return route and can only be removed by the Application. The priority return route will when set use one of the available 4 route entries. + +New routes/direct are qualified for return route insertion by checking if the destination exist and route/direct do not exist. In that event the new route/direct entry will be placed either in a free route or the one having lowest priority. + +When developing application software, the header file “ZW_slave_32_api.h” also includes the other Z-Wave API header files e.g., ZW_timer_api.h. + +The following define will be generated by the headerfile, if it does not already exist when compiling the application: ZW_SLAVE and ZW_SLAVE_32. + + The application must be linked with ZW_SLAVE_ENHANCED_232_ZW S.LIB  (= 050X for 500 Series Z-Wave modules, etc). + +## 3.10.6 Adding and Removing Nodes to/from the Network + +Its only controllers that can add new nodes to the Z-Wave network, and reset them again is the primary or inclusion controller. The home ID of the Primary Z-Wave Controller identifies a Z-Wave network. + +Information about the result of a learn process is passed to the callback function in a variable with the following structure: + +typedef struct _LEARN_INFO_ { BYTE bStatus; /* Status of learn mode */ BYTE bSource; /* Node id of the node that send node info */ BYTE *pCmd; /* Pointer to Application Node information */ BYTE bLen; /* Node info length */ } LEARN_INFO; + +When adding nodes to the network the controller have a number of choices of how to add, and what nodes to add to the network. + +### 3.10.6.1 Adding a Node Normally + +The normal way to add a node to the network is to use ZW_AddNodeToNetwork() function on the primary controller, and use the function ZW_SetLearnMode() on the node that should be included into the network. + +### 3.10.6.2 Adding a New Controller and Make it the Primary Controller + +A primary controller can add a controller to the network and in the same process give the role as primary controller to the new controller. This is done by using the ZW_ControllerChange() on the primary controller, and use the function ZW_SetLearnMode() on the controller that should be included into the network. Note that the original primary controller will become a secondary controller when the inclusion (add) is finished. + +### 3.10.6.3 SUC ID Server (SIS) + +Previously Z-Wave offered a Static Update Controller (SUC) functionality that could be enabled in a static controller. This functionality can no longer be enabled alone but is now an intregrated part of the SUC ID Server (SIS). The SIS becomes the primary controller in the network because it always has the latest update of the network topology and capability to include/exclude nodes in the network. When including a controller to the network it becomes an inclusion controller because it has the capability to include/exclude nodes in the network via the SIS. The inclusion controller’s network topology is dated from last time a node was included or it requested a network update from the SIS. The SUC and the SIS functionality can not be spilt and will always be avalible on the same controller + +## 3.10.7 The Automatic Network Update + +A Z-Wave network consists of slaves, a primary controller and secondary controllers. New nodes can only be added and removed to/from the network by using the primary controller. This could cause secondary controllers and routing slaves to misbehave, if for instance a preferred repeater node is removed. Without automatic network updating a new replication (copy) has to be made from the primary controller to all secondary controllers and routing slaves should also be manually updated with the changes. In networks with several controller and routing slave nodes, this process will be cumbersome. + +To automate this process, an automatic network update scheme has been introduced to the Z-Wave protocol. To use this scheme a static controller must be available in the network. This static controller is dedicated to hold a copy of the network topology and the latest changes that have occurred to the network. The static controller used in the Automatic update scheme is called the SUC ID Server (SIS). + +Each time a node is added, deleted or a routing change occurs, the inclusion controller will send the node information to the SIS. Other controllers can then ask the SIS if any updates are pending. The SIS will then in turn respond with any changes since last time this controller asked for updates. In the controller requesting an update, ApplicationControllerUpdate will be called to notify the application that a new node has been added or removed in the network. + +The SIS holds up to 64 changes of the network. If a node requests an update after more than 64 changes occurred, then it will get a complete copy (see ZW_RequestNetWorkUpdate). + +Routing slaves have the ability to request updates for its known destination nodes. If any changes have occurred to the network, the SIS will send updated route information for the destination nodes to the Routing slave that requested the update. The Routing slave application will be notified when the process is done, but will not get information about any changes to its routes. + +If an inclusion controller sends a new node’s node information and its routes to the SIS while it is updating another controller, the updating process will be aborted to process the new nodes information. diff --git a/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/index.md b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/index.md new file mode 100644 index 0000000..792819c --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/03-z-wave-software-architecture/index.md @@ -0,0 +1,37 @@ + +# 3 Z-Wave Software Architecture + +Z-Wave software relies on polling of functions, command complete callback function calls, and delayed function calls. + +The software is split into two groups of program modules: Z-Wave basis software and Application software. The Z-Wave basis software includes system startup code, low-level poll function, main poll loop, Z-Wave protocol layers, and memory and timer service functions. From the Z-Wave basis point of view the Application software include application hardware and software initialization functions, application state machine (called from the Z-Wave main poll loop), command complete callback functions, and a received command handler function. In addition to that, the application software can include hardware drivers. + +| | | Completed aeam ctlle kp bcd fl auea cntlle kcbd ta ioc nk | | +| --- | --- | --- | --- | +| | Co | aeam ctlle kp bcd fl auea cntlle kcbd ta ioc | | +| C co am llp bc fl auea cntlle kcbcd f tau ia ocnl function | am llp bc fl auea cntlle kcbcd f tau ia ocnl | aea ctlle kbcd faua cnl | | +| | | | n | + +Application modules + +Z-Wave modules + +Figure 1. Software Architecture + +## Contents + +- [3.1 Z-Wave System Startup Code](03.01-z-wave-system-startup-code.md) +- [3.2 Z-Wave Main Loop](03.02-z-wave-main-loop.md) +- [3.3 Z-Wave Protocol Layers](03.03-z-wave-protocol-layers.md) +- [3.4 Z-Wave Routing Principles](03.04-z-wave-routing-principles.md) +- [3.5 Z-Wave Application Layer](03.05-z-wave-application-layer.md) +- [3.6 Z-Wave Software Timers](03.06-z-wave-software-timers.md) +- [3.7 Z-Wave Hardware Timers](03.07-z-wave-hardware-timers.md) +- [3.8 Z-Wave Hardware Interrupts](03.08-z-wave-hardware-interrupts.md) +- [3.9 Interrupt Service Routines](03.09-interrupt-service-routines.md) +- [3.10 Z-Wave Nodes](03.10-z-wave-nodes.md) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.01-api-usage-guidelines.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.01-api-usage-guidelines.md new file mode 100644 index 0000000..fb118f2 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.01-api-usage-guidelines.md @@ -0,0 +1,38 @@ + +# 4.1 API Usage Guidelines + +The following guidelines should be followed when making a Z-Wave application. + +## 4.1.1 Code Space, Data Space and Internal/External NVM + +One code bank of 32KB memory in flash is allocated for application development. The data SRAM avalible for the application is 4KB. + +To enable full utilization of the 500 series with respect to future protocol features and OTA firmware update results in the following recommendations for external NVM: + +Minimum requirements when selecting external NVM for devices without OTA firmware update support: + + 32KB – Required for slave and controller devices + +Minimum requirements when selecting external NVM for devices without OTA firmware update support: + + 128KB – Required for slave devices  256KB – Required for controller devices + +[Initialization of the external NVM is completely handled by the Z-Wave protocol and for details about data layout in external NVM refer to [14]. For selection of external NVM refer also to [21].](../08-references.md#8-references) + +## 4.1.2 Buffer Protection + +Some API calls has one parameter that is a pointer to a buffer in the application SRAM area and another parameter that is a pointer to a callback function. When using these API functions in Z-Wave, it is important that the application does not change the contents of the buffer before the last callback from the API function has been issued. If the content of the buffer is changed before that callback, the Z-Wave protocol might perform the function on invalid data. + +## 4.1.3 Overlapping API Calls + +In general, it should be avoided to call an API function before the previously started API function is finished and has called the callback function for the last time. Due to the limited resources available for the API not all combinations of API calls will work, some API calls will use the same state machine or the same buffers so if multiple functions is started one or both of the functions might fail. + +## 4.1.4 Error Handling + +For purpose of robustness, an application implementation may choose to guard callback API calls whith a timer. In this guide, a timeout value for each API call, which uses a callback, is given. In some functions it is necessarry to to execute some commands in order to recover from a timeout exception. Recovery handling is described for each operation. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.02-z-wave-libraries.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.02-z-wave-libraries.md new file mode 100644 index 0000000..eaf0bfa --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.02-z-wave-libraries.md @@ -0,0 +1,88 @@ + +# 4.2 Z-Wave Libraries + +## 4.2.1 Library Functionality + +Each of the API’s provided in the Developer’s Kit contains a subset of the full Z-Wave functionality; the table below shows what kind of functionality the API’s support independent of the network configuration: + +Table 3. Library Functionality + +| | Routing Slave | Enhanced 232 Slave | Portable Controller | Static Controller | Bridge Controller | +| --- | --- | --- | --- | --- | --- | +| Basic Functionality | | | | | | +| Singlecast (non-secure) | X | X | X | X | X | +| Multicast (non-secure) | X | X | X | X | X | +| Broadcast (non-secure) | X | X | X | X | X | +| Controller replication (copy) | - | - | X | X | X | +| Promiscuous mode | - | - | X | X | X | +| Random number generator | X | X | X | X | X | +| Able to act as NWI center | - | - | X | X | X | +| Able to be included via the NWI mechanism | X | X | X | X | X | +| Able to issue an explorer frame | X | X | X | X | X | +| Able to forward an explorer frame | X | X | - | X | X | +| S0 Security (singlecast) | X | X | - | - | - | +| S2 Security (singlecase and multicast) | X | X | - | - | - | +| Send multicast wakeup to FLiRS nodes | | | X | X | X | +| | | | | | | +| Memory Location | | | | | | +| NVM data located in internal MTP | X | - | - | - | - | +| NVM data located in external FLASH/EEPROM | - | X | X | X | X | +| Firmware update with automatic NVM data conversion | - | X | X | X | X | +| | | | | | | +| Network Management | | | | | | +| Network router (repeater) | X1 | X1 | - | X1 | X1 | +| Assign routes to routing slave | - | - | X | X | X | +| Routing slave functionality | X | X | - | - | - | +| Access to routing table | - | - | X | - | - | +| Maintain virtual slave nodes | - | - | - | - | X2 | +| Able to be a FLiRS node | X | X | - | - | - | +| Able to beam when repeater | X | X | - | X | X | +| Able to create route containing beam | X3 | X3 | X | X | X | + +### 4.2.1.1 Library Functionality without a SIS + +Some of the API’s functionality provided on the Developer’s Kit depends on the network configuration. The table below shows what kind of functionality the API’s support without a SIS in the Z-Wave network: + +Table 4. Library Functionality without a SIS + +| | Routing Slave | Enhanced 232 Slave | Portable Controller | Static Controller | Bridge Controller | +| --- | --- | --- | --- | --- | --- | +| Network Management | | | | | | +| Controller replication (copy) | - | - | X | X | X | +| Controller shift | - | - | X1 | X1 | X1 | +| Create new primary controller | - | - | - | - | - | +| Request network updates | - | - | - | - | - | +| Request rediscovery of a node | - | - | X1 | X1 | X1 | +| Remove failing nodes | - | - | X1 | X1 | X1 | +| Replace failing nodes | - | - | X1 | X1 | X1 | +| Provide routing table info | - | - | X | X | X | + +### 4.2.1.2 Library Functionality with a SIS + +Some of the API’s functionality provided on the Developer’s Kit depends on the network configuration. The table below shows what kind of functionality the API’s support with a SUC ID Server (SIS) in the Z-Wave network: + +Table 5. Library Functionality with a SIS + +| | Routing Slave | Enhanced 232 Slave | Portable Controller | Static Controller | Bridge Controller | +| --- | --- | --- | --- | --- | --- | +| Network Management | | | | | | +| Controller replication (copy) | - | - | X | X | X | +| Controller shift | - | - | - | - | - | +| Create new primary controller | - | - | - | - | - | +| Request network updates | X | X | X | X | X | +| Request rediscovery of a node | - | - | X1 | X1 | X1 | +| Remove failing nodes | - | - | X1 | X1 | X1 | +| Replace failing nodes | - | - | X1 | X1 | X1 | +| Set static ctrl. to SIS | - | - | X2 | X2 | X2 | +| Work as SIS | - | - | - | X | X | +| Work as inclusion controller | | | X | X | X | +| “I’m lost“ – provide help | X3 | X3 | X3 | X4 | X | +| Provide routing table info | - | - | X | X | X | + +Note that the ability to provide help for “I’m lost” requests is limited to forwarding the request to the SIS. Only the portable controller configured as SIS can actually do the updating of the device. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.01-applicationinithw.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.01-applicationinithw.md new file mode 100644 index 0000000..051736b --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.01-applicationinithw.md @@ -0,0 +1,38 @@ + +# 4.3.1.1 ApplicationInitHW + +BYTE ApplicationInitHW( BYTE bWakeupReason ) + +ApplicationInitHW is used to initialize hardware used by the application. The Z-Wave hardware initialization function set all application IO pins to input mode. The ApplicationInitHW function MUST be called by the Z-Wave main function during system startup. At this point of time the Z-Wave timer system is not started so waiting on hardware to get ready SHOULD be done by MCU busy loops. + +Defined in: ZW_basis_api.h + +Return value: + +BYTE TRUE Application hardware initialized + +FALSE Application hardware initialization failed. Protocol enters test mode and Calls ApplicationTestPoll + +Parameters: + +bWakeupReason IN Wakeup flags: + +ZW_WAKEUP_RESET Woken up by reset or external interrupt + +ZW_WAKEUP_WUT Woken up by the WUT timer + +ZW_WAKEUP_SENSOR Woken up by a wakeup beam + +ZW_WAKEUP_WATCHDOG Reset because of a watchdog timeout + +ZW_WAKEUP_EXT_INT Woken up by external interrupt + +ZW_WAKEUP_POR Reset by Power on reset circuit + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.02-applicationinitsw.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.02-applicationinitsw.md new file mode 100644 index 0000000..503998e --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.02-applicationinitsw.md @@ -0,0 +1,40 @@ + +# 4.3.1.2 ApplicationInitSW + +BYTE ApplicationInitSW( ZW_NVM_STATUS bNvmStatus ) + +ApplicationInitSW is used to initialize memory used by the application and driver software before the Z- Wave protocol is started. + +ApplicationInitSW return value is used to make the protocol determine if the node should go into Power Down mode and if so; when and which Power Down mode the protocol should use. The application can request power down through the return value in ApplicationPoll + +ApplicationInitSW MUST be called from the Z-Wave main function during system startup. Notice that watchdog is disabled by default. + +Defined in: ZW_basis_api.h + +Return value: + +BYTE APPLICATION_NODEINFO_LISTENING Application is a listening always ON node and Application should always return E_APPLICATION_STATE_A CTIVE in the ApplicationPoll return value. + +APPLICATION_NODEINFO_NOT_LISTENING Application is a none listening node. When Application indicates E_APPLICATION_STATE_R EADY_FOR_POWERDOWN in the ApplicationPoll return value the protocol will set the module in WUT powerdown mode according to [ZW_Power_Management_I](../04.03.02-z-wave-basis-api/04.03.02.27-zw_power_management_init.md#43227-zw_power_management_init) nit [settings (See 4.3.2.27)](../04.03.02-z-wave-basis-api/04.03.02.27-zw_power_management_init.md#43227-zw_power_management_init) + +APPLICATION_FREQ_LISTENING_MODE_250 Application is a 250ms FLiRS ms node. When Application indicates E_APPLICATION_STATE_R EADY_FOR_POWERDOWN in the ApplicationPoll return value the protocol will set the module in 250ms FLiRS mode. + +APPLICATION_FREQ_LISTENING_MODE_1000 Application is a 1000ms ms FLiRS node. When Application indicates E_APPLICATION_STATE_R EADY_FOR_POWERDOWN in the ApplicationPoll return value the protocol will set the module in 1000ms FLiRS mode. + +Parameters: + +ZW_NVM_STATUS Status of NVM initialization during power-up bNvmStatus IN + +ZW_NVM_INITIALIZED NVM was empty or invalid during startup and has now been initialized as first time startup. + +ZW_NVM_VALID NVM is valid, that is in normal running condition. + +ZW_NVM_UPDATED NVM has been updated to match the layout of a newly installed firmware. NVM is therefore ready for normal operation. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.03-applicationtestpoll.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.03-applicationtestpoll.md new file mode 100644 index 0000000..21d561e --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.03-applicationtestpoll.md @@ -0,0 +1,24 @@ + +# 4.3.1.3 ApplicationTestPoll + +void ApplicationTestPoll( void ) + +The ApplicationTestPoll function is the entry point from the Z-Wave basis software to the application software when the production test mode is enabled in the protocol. This will happen when ApplicationInitHW returns FALSE. The ApplicationTestPoll function will be called indefinitely until the device is reset. The device must be reset and ApplicationInitHW must return TRUE in order to exit this mode. When ApplicationTestPoll is called the protocol will acknowledge frames sent to home ID equal to 0x00000000 and node ID as follows. + +| Device | Node ID | +| --- | --- | +| Slave | 0x00 | +| Controllers before Dev. Kit v3.40 | 0xEF | +| Controllers from Dev. Kit v3.40 or later | 0x01 | + +The following API calls are only available in production test mode: 1. ZW_EepromInit is used to initialize the external NVM. Remember to initialize controllers with a unique home ID that typically can be transferred via the UART on the production line. 2. ZW_SendConst is used to validate RF communication. Remember to enable RF communication when testing products based on a portable controller, routing slave or enhanced 232 slave. + +Defined in: ZW_basis_api.h + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.04-applicationpoll.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.04-applicationpoll.md new file mode 100644 index 0000000..5d9bb6a --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.04-applicationpoll.md @@ -0,0 +1,43 @@ + +# 4.3.1.4 ApplicationPoll + +E_APPLICATION_STATE ApplicationPoll(E_PROTOCOL_STATE bProtocolState ) + +The ApplicationPoll function is the entry point from the Z-Wave basis software to the application software modules. The ApplicationPoll function is called from the Z-Wave main loop when no low-level time critical actions are active. In order not to disrupt the radio communication and the protocol, the application code MUST return within 2ms measured from the call of ApplicationPoll. + +To determine the ApplicationPoll frequency (see table below) is a LED Dimmer application modified to be able to measure how often ApplicationPoll is called via an output pin. The minimum value is measured when the module is idle, i.e., no RF communication, no push button activation etc. The maximum value is measured when the ERTT application at the same time sends Basic Set Commands (value equal 0) as fast as possible to the LED Dimmer (DUT). + +Table 6. ApplicationPoll Frequency + +| | ZW0201 LED Dimmer | ZW0301 LED Dimm,er | 400 Series LED Dimmer | 500 Series LED Dimmer | +| --- | --- | --- | --- | --- | +| Minimum | 7.2 us | 7.2 us | 80 us | 80 us | +| Maximum | 2.4 ms | 2.4 ms | 180 us | 180 us | + +The above mentioned output pin mapped to the ApplicationPoll SHOULD also be used during application testing to ensure that the application code never runs for more than 2ms even in worst-case scenarios; setting the pin high when entering and low when leaving the ApplicationPoll function. + +The ApplicationPoll function return value is used for requesting power down mode, the application can specify if it is ready for power down or if it needs to be running. + +Defined in: ZW_basis_api.h + +Return value: + +E_APPLICATION_STATE E_APPLICATION_STATE_ACTIVE Application active - not ready for sleep/powerdown + +E_APPLICATION_STATE_READY_FOR Application is ready to _POWERDOWN System Powerdown and protocol will set module in Power down according to value Application returned at the [ApplicationInitSW](04.03.01.02-applicationinitsw.md#4312-applicationinitsw) () [call (See 4.3.1.2)](04.03.01.02-applicationinitsw.md#4312-applicationinitsw) Parameters: + +E_PROTOCOL_STATE Current protocol state bProtocolState IN + +E_PROTOCOL_STATE_ACTIVE Protocol active - not ready for sytem shutdown + +E_PROTOCOL_STATE_SHUTDOWN_ Protocol power down pending PENDING - protocol making ready for system shutdown + +E_PROTOCOL_STATE_READY_FOR_ Protocol going in powerdown SHUTDOWN - now ready for system shutdown + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.05-applicationcommandhandler-not-bridge-controller-library.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.05-applicationcommandhandler-not-bridge-controller-library.md new file mode 100644 index 0000000..c8b8cfb --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.05-applicationcommandhandler-not-bridge-controller-library.md @@ -0,0 +1,78 @@ + +# 4.3.1.5 ApplicationCommandHandler (Not Bridge Controller Library) + +void ApplicationCommandHandler( ZW_APPLICATION_TX_BUFFER *pCmd, BYTE cmdLength, RECEIVE_OPTIONS_TYPE *rxopt) + +The Z-Wave protocol will call the ApplicationCommandHandler function when an application command or request has been received from another node. The receive buffer is released when returning from this function. The type of frame used by the request can be determined (single cast, mulitcast or broadcast frame). This is used to avoid flooding the network by responding on a multicast or broadcast. In order not to disrupt the radio communication and the protocol, no application function must execute code for more than 5ms without returning. + +Except for the Bridge Controller library, this function MUST be implemented by the Application layer. + +NOTE: For Controllers the rxopt->securityKey is ALWAYS SECURITY_KEY_NONE. Defined in: ZW_basis_api.h + +Parameters: + +rxopt->rxStatus IN Received frame status flags Refer to ZW_transport_API.h header file + +RECEIVE_STATUS_ROUTED_BUSY A response route is locked by the xxxxxxx1 application + +RECEIVE_STATUS_LOW_POWER Received at low output power xxxxxx1x level + +RECEIVE_STATUS_TYPE_SINGLE Received a single cast frame xxxx00xx + +RECEIVE_STATUS_TYPE_BROAD Received a broadcast frame xxxx01xx + +RECEIVE_STATUS_TYPE_MULTI Received a multicast frame xxxx10xx + +RECEIVE_STATUS_TYPE_EXPLORE Received an explore frame xxx10xxx + +RECEIVE_STATUS_FOREIGN_FRAME The received frame is not x1xxxxxx addressed to this node (Only valid in promiscuous mode) + +RECEIVE_STATUS_FOREIGN_HOMEID The received frame is received 1xxxxxxx from a foreign HomeID. Only Controllers in Smart Start AddNode mode can receive this status. + +rxopt->destNode IN Command destination Node ID Only valid in promiscuous mode and for singlecast frames. + +rxopt->sourceNode Command sender Node ID IN + +rxopt->rxRSSIVal IN RSSI measurement of the received frame This is a signed 8-bit value. + +Values from RSSI_RESERVED_START to 124 are reserved. + +All values below RSSI_RESERVED_START are received power in dBms. + +RSSI_NOT_AVAILABLE - RSSI measurement not available + +RSSI_MAX_POWER_SATURAT ED - Receiver saturated. RSSI too high to measure precisely + +RSSI_BELOW_SENSITIVITY - No signal detected. The RSSI is too low to measure precisely. + +rxopt->securityKey Security key frame was decrypted with. Refer to ZW_security_api.h IN header file. + +SECURITY_KEY_NONE Nonsecure transmission – no decryption done. + +SECURITY_KEY_S2_UNAUTHENTICAT S2 Unauthenticated key ED + +SECURITY_KEY_S2_AUTHENTICATED S2 Authenticated key + +SECURITY_KEY_S2_ACCESS S2 Access key + +SECURITY_KEY_S0 Security Scheme 0 key + +pCmd IN Payload from the received frame. The command class is the very first byte. + +cmdLength IN Number of Command class bytes. + +Serial API: + +ZW->HOST: REQ | 0x04 | rxStatus | sourceNode | cmdLength | pCmd[] | rxRSSIVal | securityKey + +When a foreign frame is received in promiscuous mode: ZW->HOST: REQ | 0xD1 | rxStatus | sourceNode | cmdLength | pCmd[] | destNode | multiNodeMaskLen [| multiNodeMask[multiNodeMaskLen]] | rxRSSIVal + +The destNode parameter is only valid for singlecast frames. + +If multiNodeMaskLen is ZERO the next parameter in SerialAPI frame is rssiVal. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.06-applicationnodeinformation.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.06-applicationnodeinformation.md new file mode 100644 index 0000000..bcc16f6 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.06-applicationnodeinformation.md @@ -0,0 +1,84 @@ + +# 4.3.1.6 ApplicationNodeInformation + +void ApplicationNodeInformation(BYTE *deviceOptionsMask, APPL_NODE_TYPE *nodeType, BYTE **nodeParm, BYTE *parmLength ) + +The Z-Wave Application Layer MUST use the ApplicationNodeInformation function to generate the Node Information frame and to save information about node capabilities. All Z-Wave application-related [fields of the Node Information structure MUST be initialized by this function. For a description of the Generic Device Classes, Specific Device Classes, and Command Classes refer to [4]-[5] and [7]-[12].](../../../08-references.md#8-references) The deviceOptionsMask is a Bit mask where Listening and Optional functionality flags MUST be set or cleared accordingly to the nodes capabilities. + +The listening option in the deviceOptionsMask (APPLICATION_NODEINFO_LISTENING) indicates a continuously powered node ready to receive frames. A listening node assists as repeater in the network. + +The non-listening option in the deviceOptionsMask (APPLICATION_NODEINFO_NOT_LISTENING) indicates a battery-operated node that power off RF reception when idle (prolongs battery lifetime).. + +The optional functionality option in the deviceOptionsMask (APPLICATION_NODEINFO_OPTIONAL_FUNCTIONALITY) indicates that this node supports other command classes than the mandatory classes for the selected generic and specific device class. + +Examples: + +To set a device as Listening with Optional Functionality: + +*deviceOptionsMask = APPLICATION_NODEINFO_LISTENING | APPLICATION_NODEINFO_OPTIONAL_FUNCTIONALITY; + +To set a device as not listening and with no Optional functionality support: + +*deviceOptionsMask = APPLICATION_NODEINFO_NOT_LISTENING; + +Note for Controllers: Because controller libraries store some basic information about themselves from ApplicationNodeInformation in nonvolatile memory. ApplicationNodeInformation should be set to the correct values before Application return from ApplicationInitHW(), for applications where this cannot be done. The Application must call ZW_SetDefault() after updating ApplicationNodeInformation in order to force the Z-Wave library to store the correct values. + +A way to verify if ApplicationNodeInformation is stored by the protocol is to call ZW_GetNodeProtocolInfo to verify that Generic and specific nodetype are correct. If they differ from what is expected, the Application should Set the ApplicationNodeInformation to the correct values and call ZW_SetDefault() to force the protocol to update its information. Defined in: ZW_basis_api.h + +Parameters: + +deviceOptionsMask Bitmask with options OUT + +APPLICATION_NODEINFO_LISTENING In case this node is always listening (typically AC powered nodes) and stationary. + +APPLICATION_NODEINFO_NOT_LISTENING In case this node is non- listening (typically battery powered nodes). + +APPLICATION_NODEINFO_ If the node supports other command classes than the ones mandatory for OPTIONAL_FUNCTIONALITY this nodes Generic and Specific Device Class + +APPLICATION_FREQ_LISTENING_MODE_250ms This option bit should be set if the node should act as a Frequently Listening Routing Slave with a wakeup interval of 250ms. This option is only available on Routing Slaves. This option is not available on 3-channel systems (the JP frequency). + +APPLICATION_FREQ_LISTENING_MODE_1000ms This option bit should be set if the node should act as a Frequently Listening Routing Slave with a wakeup interval of 250ms. This option is only available on Routing Slaves. + +nodeType OUT Pointer to structure with the Device Class: + +(*nodeType).generic [The Generic Device Class [5]. Do not enter zero in](../../../08-references.md#8-references) this field. + +(*nodeType).specific [The Specific Device Class [5].](../../../08-references.md#8-references) nodeParm OUT Command Class buffer pointer. [Command Classes [12]](../../../08-references.md#8-references) supported by the device itself and optional Command Classes the device can control in other devices. + +parmLength OUT Number of Command Class bytes. + +Serial API: + +HOST->ZW: REQ | 0x03 | deviceOptionsMask | generic | specific | parmLength | nodeParm[ ] + +The ApplicationNodeInformation is replaced by SerialAPI_ApplicationNodeInformation. Used to set information that will be used in subsequent calls to ZW_SendNodeInformation. Replaces the functionality provided by the ApplicationNodeInformation() callback function. + +void SerialAPI_ApplicationNodeInformation(BYTE deviceOptionsMask, APPL_NODE_TYPE *nodeType, BYTE *nodeParm, BYTE parmLength) + +The define APPL_NODEPARM_MAX in serialappl.h must be modified accordingly to the number of command classes to be notified. Prior to either start or join a Z-Wave network the HOST needs to initially setup the Node Information Frame (NIF) which should define the type of Z-Wave node the SerialAPI module is supposed to be. For the NIF to be stored in the protocol NVM area as well as in the application NVM area the HOST need to perform the following steps: + +1. HOST->ZW: send SerialAPI_ApplicationNodeInformation() with NIF information + +2. HOST->ZW: send ZW_SetDefault() The figure below lists the Node Information Frame structure on application level. The Z-Wave Protocol creates this frame via ApplicationNodeInformation. The Node Information Frame structure when transmitted by RF does not include the Basic byte descriptor field. The Basic byte descriptor field on application level is deducted from the Capability and Security byte descriptor fields. + +| Byte descriptor \ bit number | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Capability | Liste- ning | Z-Wave Protocol-Specific Part | | | | | | | +| Security | Opt. Func. | Z-Wave Protocol-Specific Part | | | | | | | +| Reserved | Z-Wave Protocol-Specific Part | | | | | | | | +| Basic | Basic Device Class (Z-Wave Protocol-Specific Part) | | | | | | | | +| Generic | Generic Device Class | | | | | | | | +| Specific | Specific Device Class | | | | | | | | +| NodeInfo[0] | Command Class 1 | | | | | | | | +| … | … | | | | | | | | +| NodeInfo[n-1] | Command Class n | | | | | | | | + +Figure 8. Node Information Frame Structure on Application Level + +WARNING: Must use deviceOptionsMask parameter and associated defines to initialize Node Information Frame with respect to listening, non-listening and optional functionality options. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.07-applicationslaveupdate-only-slave-libraries.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.07-applicationslaveupdate-only-slave-libraries.md new file mode 100644 index 0000000..4fbef87 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.07-applicationslaveupdate-only-slave-libraries.md @@ -0,0 +1,32 @@ + +# 4.3.1.7 ApplicationSlaveUpdate (only Slave Libraries) + +void ApplicationSlaveUpdate ( BYTE bStatus, BYTE bNodeID, BYTE *pCmd, BYTE bLen) + +The Z-Wave protocol MAY notify a slave application by calling ApplicationSlaveUpdate when a Node Information Frame has been received. The Z-Wave protocol MAY refrain from calling the function if the protocol is currently expecting node information. + +All slave libraries requires this function implemented by the application. + +Defined in: ZW_slave_api.h + +Parameters: + +bStatus IN The status, value could be one of the following: + +UPDATE_STATE_NODE_INFO_RECEIVED A node has sent its Node Info while the Z-Wave protocol is idle. + +bNodeID IN The updated node’s node ID (1..232). + +pCmd IN Pointer of the updated node’s node info. + +bLen IN The length of the pCmd parameter. + +Serial API: + +ZW->HOST: REQ | 0x49 | bStatus | bNodeID | bLen | basic | generic | specific | commandclasses[ ] diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.08-applicationcontrollerupdate-only-controller-libraries.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.08-applicationcontrollerupdate-only-controller-libraries.md new file mode 100644 index 0000000..9a7d709 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.08-applicationcontrollerupdate-only-controller-libraries.md @@ -0,0 +1,66 @@ + +# 4.3.1.8 ApplicationControllerUpdate (only Controller Libraries) + +void ApplicationControllerUpdate (BYTE bStatus, BYTE bNodeID, BYTE *pCmd, BYTE bLen) + +A controller application MAY use the information provided by ApplicationControllerUpdate to update local data structures or to control smart start inclusion. + +The Z-Wave protocol MUST notify a controller application by calling ApplicationControllerUpdate when a new node has been added or deleted from the controller through the network management features. + +The Z-Wave protocol MUST call ApplicationControllerUpdate in response to ZW_RequestNodeInfo being called by the controller application. The Z-Wave protocol MAY notify a controller application by calling ApplicationControllerUpdate when a Node Information Frame has been received. The Z-Wave protocol MAY refrain from calling the function if the protocol is currently expecting a Node Information frame. + +ApplicationControllerUpdate MUST be called in a controller node operating as SIS each time a node is added or deleted by the primary controller. ApplicationControllerUpdate MUST be called in a controller node operating as SIS each time a node is added/deleted by an inclusion controller. + +A controller application MAY send a ZW_RequestNetWorkUpdate command to a SIS or SIS node. In response, the SIS MUST return update information for each node change since the last update handled by the requesting controller node. The application of the requesting controller node MAY receive multiple calls to ApplicationControllerUpdate in response to ZW_RequestNetWorkUpdate. + +The Z-Wave protocol MUST NOT call ApplicationControllerUpdate in a controller node acting as primary controller or inclusion controller when a node is added or deleted. + +Any controller application MUST implement this function. + +Defined in: ZW_controller_api.h + +Parameters: + +bStatus The status of the update process, value could IN be one of the following: + +UPDATE_STATE_NEW_ID_ASSIGNED A new node has been added to the network + +UPDATE_STATE_DELETE_DONE A node has been deleted from the network + +UPDATE_STATE_NODE_INFO_RECEIVED A node has sent its node info either unsolicited or as a response to a ZW_RequestNodeInfo call + +UPDATE_STATE_SUC_ID The SIS node Id was updated + +UPDATE_STATE_NODE_INFO_SMARTSTART_HOMEID A Smart Start inclusion request has been received. Only Controllers in Smart Start AddNode mode can receive this status. UPDATE_STATE_INCLUDED_NODE_INFO_RECEIVED A Smart Included Node Information Frame has been received. Only Controllers in Smart Start AddNode mode can receive this status. + +bNodeID The updated node’s node ID (1..232). IN + +pCmd IN Pointer of the updated node’s node info. If bStatus equals + +the pCmd points to a OMEID_RECEIVED buffer containing the Smart Start DSK derived HomeId of the Smart Start node wanting to be included, followed by the node’s node info. + +If bStatus equals + +[the pCmd points to a buffer](04.03.01.09-applicationcommandhandler_bridge-only-bridge-controller-library.md#4319-applicationcommandhandler_bridge-only-bridge-controller-library) EIVED [containing rxStatus (see 4.3.1.9) and the](04.03.01.09-applicationcommandhandler_bridge-only-bridge-controller-library.md#4319-applicationcommandhandler_bridge-only-bridge-controller-library) Smart Start DSK derived HomeID of an already included Smart Start node. If INIF received are from a foreign Network rxStatus will have set. RECEIVE_STATUS_FOREIGN_HOMEID + +bLen IN The length of the pCmd parameter. + +Serial API: + +ZW->HOST: REQ | 0x49 | bStatus | bNodeID | bLen | basic | generic | specific | commandclasses[ ] + +ApplicationControllerUpdate via the Serial API also have the possibility for receiving the status, which means that a node did not acknowledge a UPDATE_STATE_NODE_INFO_REQ_FAILED ZW_RequestNodeInfo call. + +ZW->HOST: REQ | 0x49 | 0x85 | bNodeID | bLen | dskID[4] | ccLen | basic | generic | specific | cmdclasses[ccLen] + +If Controller has been put into Smart Start mode by calling ZW_AddNodeToNetwork with, the controller will when a Smart Start inclusion request are received use ADD_NODE_SMART_START ApplicationControllerUpdate with UPDATE_STATE_NODE_INFO_SMARTSTART_HOMEID_RECEIVED (0x85) to inform the Application that a Smart Start node with the specified caracteristics requests for Inclusion. + +ZW->HOST: REQ | 0x49 | 0x86 | bNodeID | bLen | rxStatus | dskID[4] + +If Controller has been put into Smart Start mode by calling ZW_AddNodeToNetwork with, the controller will when a Smart Start Included Node Information Frame (INIF) ADD_NODE_SMART_START are received use ApplicationControllerUpdate with UPDATE_STATE_INCLUDED_NODE_INFO_RECEIVED (0x86) to inform the Application that a Smart Start node with the specified caracteristics has been powered up. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.09-applicationcommandhandler_bridge-only-bridge-controller-library.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.09-applicationcommandhandler_bridge-only-bridge-controller-library.md new file mode 100644 index 0000000..9f47425 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.09-applicationcommandhandler_bridge-only-bridge-controller-library.md @@ -0,0 +1,64 @@ + +# 4.3.1.9 ApplicationCommandHandler_Bridge (only Bridge Controller Library) + +void ApplicationCommandHandler_Bridge(ZW_MULTI_DEST multi, ZW_APPLICATION_TX_BUFFER *pCmd, BYTE cmdLength, RECEIVE_OPTIONS_TYPE *rxopt) + +The Z-Wave protocol MUST call the ApplicationCommandHandler_Bridge function when an application command has been received from another node to the Bridge Controller or an existing virtual slave node. The Z-Wave protocol MUST NOT reuse the receive buffer until the application has exited this function. + +A bridge controller application MUST implement this function. + +Defined in: ZW_controller_bridge_api.h + +Parameters: + +rxopt->rxStatus Frame header info: IN + +RECEIVE_STATUS_ROUTED_BUSY A response route is locked by the xxxxxxx1 application + +RECEIVE_STATUS_LOW_POWER Received at low output power level xxxxxx1x + +RECEIVE_STATUS_TYPE_SINGLE Received a single cast frame xxxx00xx + +RECEIVE_STATUS_TYPE_BROAD Received a broadcast frame xxxx01xx + +RECEIVE_STATUS_TYPE_MULTI Received a multicast frame xxxx10xx + +RECEIVE_STATUS_TYPE_EXPLORE Received an explore frame xxx1xxxx + +RECEIVE_STATUS_FOREIGN_FRAME The received frame is not x1xxxxxx addressed to this node (Only valid in promiscuous mode) but are addressed to another node belonging to same HomeID as current node. + +RECEIVE_STATUS_FOREIGN_HOMEID The received frame is received from 1xxxxxxx a foreign HomeID. Only Controllers in Smart Start AddNode mode can receive this status. rxopt->destNode Command receiving Node ID. Either Bridge IN Controller Node ID, virtual slave Node ID or if in promiscuous mode Node ID on node belonging to same HomeID as current node. + +If received frame is a multicast frame then destNode is not valid and multi points to a multicast structure containing the destination nodes. + +rxopt- Command sender Node ID.>sourceNode IN + +rxopt->rxRSSIVal RSSI measurement of the received frame This is a signed 8-bit value. IN Values from RSSI_RESERVED_START to 124 are reserved. + +All values below RSSI_RESERVED_START are received power in dBms. + +RSSI_NOT_AVAILABLE - RSSI measurement not available + +RSSI_MAX_POWER_SATURATED - Receiver saturated. RSSI too high to measure precisely + +RSSI_BELOW_SENSITIVITY - No signal detected. The RSSI is too low to measure precisely. + +pCmd IN Payload from the received frame. The command class is the very first byte. + +cmdLength IN Number of Command class bytes. + +Serial API: + +ZW->HOST: REQ | 0xA8 | rxStatus | destNodeID | srcNodeID | cmdLength | pCmd[ ] | multiDestsOffset_NodeMaskLen | multiDestsNodeMask | rxRSSIVal + +When a foreign frame is received in promiscuous mode: ZW->HOST: REQ | 0xD1 | rxStatus | sourceNode | cmdLength | pCmd[] | destNode | multiNodeMaskLen [| multiNodeMask[multiNodeMaskLen]] | rxRSSIVal + +The destNode parameter is only valid for singlecast frames. + +If multiNodeMaskLen is ZERO the next parameter in SerialAPI frame is rxRSSIVal. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.10-applicationslavenodeinformation-only-bridge-controller-library.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.10-applicationslavenodeinformation-only-bridge-controller-library.md new file mode 100644 index 0000000..21d96b6 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.10-applicationslavenodeinformation-only-bridge-controller-library.md @@ -0,0 +1,40 @@ + +# 4.3.1.10 ApplicationSlaveNodeInformation (only Bridge Controller Library) + +void ApplicationSlaveNodeInformation(BYTE destNode, BYTE *listening, APPL_NODE_TYPE *nodeType, BYTE **nodeParm, BYTE *parmLength) + +Request Application Virtual Slave Node information. The Z-Wave protocol layer calls ApplicationSlaveNodeInformation just before transmitting a "Node Information" frame. + +The Z-Wave Bridge Controller library requires this function implemented by the application. + +Defined in: ZW_controller_bridge_api.h + +Parameters: + +destNode IN Which Virtual Node do we want the node information from. + +listening OUT TRUE if this node is always listening and not moving. + +nodeType OUT Pointer to structure with the Device Class: + +(*nodeType).generic [The Generic Device Class [5].](../../../08-references.md#8-references) Do not enter zero in this field. + +(*nodeType).specific [The Specific Device Class [5].](../../../08-references.md#8-references) + +nodeParm OUT Command Class buffer pointer. [Command Classes [12]](../../../08-references.md#8-references) supported by the device itself and optional Command Classes the device can control in other devices. + +parmLength OUT Number of Command Class bytes. + +Serial API: + +The ApplicationSlaveNodeInformation is replaced by SerialAPI_ApplicationSlaveNodeInformation. Used to set node information for all Virtual Slave Nodes in the embedded module this node information will then be used in all subsequent calls to ZW_SendSlaveNodeInformation regardless if using different destNode value as only one Virtual Slave Node node information are kept in RAM at a time. Replaces the functionality provided by the ApplicationSlaveNodeInformation() callback function. + +void SerialAPI_ApplicationSlaveNodeInformation(BYTE destNode, BYTE listening, APPL_NODE_TYPE * nodeType, BYTE *nodeParm, BYTE parmLength) + +HOST->ZW: REQ | 0xA0 | destNode | listening | genericType | specificType | parmLength | nodeParm[] diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.11-applicationnetworklearnmodecompleted-only-controller-libraries.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.11-applicationnetworklearnmodecompleted-only-controller-libraries.md new file mode 100644 index 0000000..a1948b0 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.11-applicationnetworklearnmodecompleted-only-controller-libraries.md @@ -0,0 +1,42 @@ + +# 4.3.1.11 ApplicationNetworkLearnModeCompleted (only Controller Libraries) + +void ApplicationNetworkLearnModeCompleted(LEARN_INFO *glearnNodeInfo) + +Called when node have started inclusion/exclusion through ZW_NetworkLearnModeStart and node has been included, excluded or learnmode either failed or timed out. + +A controller application MUST implement this function. + +*learnNodeInfo.bStatus Status of learn mode: IN LEARN_MODE_STARTED The learn process has been started + +LEARN_MODE_DONE The learn process is complete and the controller is now included into the network + +LEARN_MODE_FAILED The learn process failed. + +*learnNodeInfo.bSource Valid values: IN + +0 Node has been Excluded + +1-232 node has been Included and has been assigned this nodeID + +APPLICATION_NETWORK Smart Start secure inclusion failed _LEARN_MODE_COMPLE TED_FAILED + +APPLICATION_NETWORK A nodeID has been assigned do not go into _LEARN_MODE_COMPLE sleepmode – Inclusion NOT done TED_SMART_START_IN_ PROGRESS + +APPLICATION_NETWORK LearnMode process timeout _LEARN_MODE_COMPLE inclusion/exclusion did not start TED_TIMEOUT + +*learnNodeInfo.pReserv Reserved ed IN + +*learnNodeInfo.bReserv Length of Reserved edLen IN + +Serial API: + +The ZW_NetworkLearnModeStart functionality is reached through the Serial API functionality FUNC_ID_ZW_SET_LEARN_MODE and the ApplicationNetworkLearnModeCompleted results is transmitted to HOST as a FUNC_ID_ZW_SET_LEARN_MODE request. + +ZW->HOST: REQ | 0x50 | funcID | bStatus | bSource | bReservedLen | bReserved[bReservedLen] diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.12-applicationnetworklearnmodecompleted-only-slave-libraries.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.12-applicationnetworklearnmodecompleted-only-slave-libraries.md new file mode 100644 index 0000000..2318baf --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.12-applicationnetworklearnmodecompleted-only-slave-libraries.md @@ -0,0 +1,32 @@ + +# 4.3.1.12 ApplicationNetworkLearnModeCompleted (only Slave Libraries) + +void ApplicationNetworkLearnModeCompleted(BYTE bNodeID) + +Called when node have started inclusion/exclusion through ZW_NetworkLearnModeStart and node has been included, excluded or learnmode either failed or timed out. + +A slave application MUST implement this function. + +bNodeID IN Valid values: + +0 Node has been Excluded + +1-232 node has been Included and has been assigned this nodeID + +APPLICATION_NETWORK_LEARN_ Smart Start secure inclusion failed MODE_COMPLETED_FAILED + +APPLICATION_NETWORK_LEARN_ A nodeID has been assigned do not go into MODE_COMPLETED_SMART_STAR sleepmode – Inclusion NOT done T_IN_PROGRESS + +APPLICATION_NETWORK_LEARN_ LearnMode process timeout MODE_COMPLETED_TIMEOUT inclusion/exclusion did not start + +Serial API: + +The ZW_NetworkLearnModeStart functionality is reached through the Serial API functionality FUNC_ID_ZW_SET_LEARN_MODE and the ApplicationNetworkLearnModeCompleted results is transmitted to HOST as a FUNC_ID_ZW_SET_LEARN_MODE request. + +ZW->HOST: REQ | 0x50 | funcID | bNodeID diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.13-applicationrfnotify.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.13-applicationrfnotify.md new file mode 100644 index 0000000..d5bb339 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.13-applicationrfnotify.md @@ -0,0 +1,36 @@ + +# 4.3.1.13 ApplicationRfNotify + +void ApplicationRfNotify (BYTE rfState) + +This function is used to inform the application about the current state of the radio enabling control of an external power amplifier (PA). The Z-Wave protocol will call the ApplicationRfNotify function when the radio changes state as follows: + + From Tx to Rx  From Rx to Tx  From power down to Rx  From power down to Tx  When internal Tx PA is powered up  When internal Tx PA is powered down + +[This enables the application to control an external PA using the appropriate number of I/O pins. For details, refer to [19].](../../../08-references.md#8-references) + +The ApplicationRfNotify function MUST be defined in the application even if not being used for controlling an external PA. Remember to includer header file config_lib.h in application to enable function. + +Defined in: ZW_basis_api.h + +Parameters: + +rfState IN The current mode of the radio. Refer to ZW_transport_API.h header file + +ZW_RF_TX_MODE The radio is in Tx mode. Previous mode is either Rx or power down + +ZW_RF_RX_MODE The radio is in Rx mode. Previous mode is either Tx or power down + +ZW_RF_PA_ON The radio is in Tx mode and the PA is powered on + +ZW_RF_PA_OFF The radio is in Tx mode and the PA is powered off + +Serial API: + +Not implemented diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.14-applicationsecurekeysrequested-only-slave-libraries.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.14-applicationsecurekeysrequested-only-slave-libraries.md new file mode 100644 index 0000000..3b95e23 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.14-applicationsecurekeysrequested-only-slave-libraries.md @@ -0,0 +1,32 @@ + +# 4.3.1.14 ApplicationSecureKeysRequested (only Slave Libraries) + +BYTE ApplicationSecureKeysRequested(void); + +This function lets the application select which Security network keys are requested during inclusion (add) to a Security 2 capable controller. The including controller may grant all or a subset of the requested keys. + +This function is only required in slave_routing and slave_enhanced_232 based applications. + +Defined in: ZW_security_api.h + +Return value: + +BYTE Bitmask of requested keys. The possible values are Refer to ZW_security_API.h header file + +SECURITY_KEY_S2_UNAUTHENTICATED_BIT Request the unauthenticated key. + +SECURITY_KEY_S2_AUTHENTICATED_BIT Request the authenticated key. + +SECURITY_KEY_S2_ACCESS_BIT Request the Access Control key. + +SECURITY_KEY_S0_BIT Request the Security scheme 0 key for backwards compatibility. + +Serial API: + +Not implemented. The Requested Security keys can either be set through the Serial API FUNC_ID_ZW_SECURITY_SETUP function [E_SECURITY_SETUP_CMD_SET_SECURITY_INCLUSION_REQUESTED_KEYS (See 4.3.15.1) or](../04.03.15-security-api.md#43151-zw_getsecuritykeys-only-slave-libraries) at compile-time through the config_app.h file for SerialAPIPlus. See the REQUESTED_SECURITY_KEYS define. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.15-applicationsecureauthenticationrequested-only-slave-libraries.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.15-applicationsecureauthenticationrequested-only-slave-libraries.md new file mode 100644 index 0000000..8bc9ea8 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.15-applicationsecureauthenticationrequested-only-slave-libraries.md @@ -0,0 +1,76 @@ + +# 4.3.1.15 ApplicationSecureAuthenticationRequested (only Slave Libraries) + +BYTE ApplicationSecureAuthenticationRequested(void); + +This function lets the application select which Security network authentication are requested during inclusion (add) to a Security 2 capable controller. + +This function is only required in slave_routing and slave_enhanced_232 based applications. + +Defined in: ZW_security_api.h + +Return value: + +BYTE S2 Inclusion Authentication method. The possible Refer to ZW_security_API.h header values are file + +SECURITY_AUTHENTICATION_SSA Request Server Side Authentication. + +SECURITY_AUTHENTICATION_CSA Request Client Side Authentication. + +Serial API: + +Not implemented. The Requested Authentication can either be set through the Serial API FUNC_ID_ZW_SECURITY_SETUP function [E_SECURITY_SETUP_CMD_SET_SECURITY_INCLUSION_REQUESTED_AUTHENTICATION (See 4.3.15.1) or at compile-time through the config_app.h file for SerialAPIPlus. See the](../04.03.15-security-api.md#43151-zw_getsecuritykeys-only-slave-libraries) REQUESTED_SECURITY_AUTHENTICATION define. 4.3.1.16 ApplicationSecureCommandsSupported (only Slave Libraries) + +void ApplicationSecureCommandsSupported(enum SECURITY_KEY eKey, BYTE **pCmdClasses, BYTE *pLength); + +The application uses this function to notify the protocol of the command classes it supports using each security key. + +This function is only required in slave_routing and slave_enhanced_232 based applications. + +Defined in: ZW_security_api.h + +Parameters: + +eKey IN The security key to report on. + +pCmdClasses OUT Cmd classes supported using eKey + +pLength OUT Length of pCmdClasses + +Serial API: + +This SerialAPI call replaces the functionality provided by the ApplicationSecureCommandsSupported() callback function. Must be set prior to inclusion (add). Will be cached in NVM of the SerialAPI embedded node and needs to be set only once. + +The define APPL_NODEPARM_MAX in serialappl.h must be modified accordingly to the number of command classes to be notified. + +HOST->ZW: REQ | 0x0C | unincluded_pLength | unincluded_nodeParm[] | included_unsecure_p | included_unsecure_nodeParm[] | pLength | pCmdClasses + +Note: unincluded_nodeParm is sent to ApplicationNodeInformation when the node is not included and when the node is unsecurely included. included_unsecure_nodeParm is being sent to ApplicationNodeInformation when the node is securely included. pLength and pCmdClasses is sent to ApplicationSecureCommandsSupported. 4.3.1.17 ApplicationSecurityEvent (only Slave Libraries) + +void ApplicationSecurityEvent(s_application_security_event_data_t *securityEvent); + +The protocol uses this function to notify the application of security events. + +This function is only required in slave_routing and slave_enhanced_232 based applications. + +Defined in: ZW_security_api.h + +Parameters: + +s_application_security_event_data_t IN securityEvent->event Security Event descriptor securityEvent->eventDataLength + +securityEvent->eventData + +SecurityEvent can contain following events: + +event = E_APPLICATION_SECURITY_EVENT_S2_INCLUSION_REQUEST_DSK_CSA (eventDataLength = 0). This event occurs when node is in LearnMode and the S2 Inclusion (add) [requires the CSA DSK (a fragment of the including Controller DSK) to finish. The application should then deliver the CSA DSK by calling ZW_SetSecurityS2InclusionPublicDSK_CSA (See 4.3.15.3)](../04.03.15-security-api.md#43153-zw_setsecuritys2inclusionpublicdsk_csaonly-slave-libraries) accordingly. + +Serial API: + +ZW->HOST: 0x9D | event | evenDataLength | eventData[eventDataLength] diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/index.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/index.md new file mode 100644 index 0000000..01e089e --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.01-required-application-functions/index.md @@ -0,0 +1,28 @@ + +# 4.3.1 Required Application Functions + +The Z-Wave library requires the functions mentioned here implemented within the Application layer. + +## Contents + +- [4.3.1.1 ApplicationInitHW](04.03.01.01-applicationinithw.md) +- [4.3.1.2 ApplicationInitSW](04.03.01.02-applicationinitsw.md) +- [4.3.1.3 ApplicationTestPoll](04.03.01.03-applicationtestpoll.md) +- [4.3.1.4 ApplicationPoll](04.03.01.04-applicationpoll.md) +- [4.3.1.5 ApplicationCommandHandler (Not Bridge Controller Library)](04.03.01.05-applicationcommandhandler-not-bridge-controller-library.md) +- [4.3.1.6 ApplicationNodeInformation](04.03.01.06-applicationnodeinformation.md) +- [4.3.1.7 ApplicationSlaveUpdate (only Slave Libraries)](04.03.01.07-applicationslaveupdate-only-slave-libraries.md) +- [4.3.1.8 ApplicationControllerUpdate (only Controller Libraries)](04.03.01.08-applicationcontrollerupdate-only-controller-libraries.md) +- [4.3.1.9 ApplicationCommandHandler_Bridge (only Bridge Controller Library)](04.03.01.09-applicationcommandhandler_bridge-only-bridge-controller-library.md) +- [4.3.1.10 ApplicationSlaveNodeInformation (only Bridge Controller Library)](04.03.01.10-applicationslavenodeinformation-only-bridge-controller-library.md) +- [4.3.1.11 ApplicationNetworkLearnModeCompleted (only Controller Libraries)](04.03.01.11-applicationnetworklearnmodecompleted-only-controller-libraries.md) +- [4.3.1.12 ApplicationNetworkLearnModeCompleted (only Slave Libraries)](04.03.01.12-applicationnetworklearnmodecompleted-only-slave-libraries.md) +- [4.3.1.13 ApplicationRfNotify](04.03.01.13-applicationrfnotify.md) +- [4.3.1.14 ApplicationSecureKeysRequested (only Slave Libraries)](04.03.01.14-applicationsecurekeysrequested-only-slave-libraries.md) +- [4.3.1.15 ApplicationSecureAuthenticationRequested (only Slave Libraries)](04.03.01.15-applicationsecureauthenticationrequested-only-slave-libraries.md) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.01-zw_explorerequestinclusion.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.01-zw_explorerequestinclusion.md new file mode 100644 index 0000000..f6ded47 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.01-zw_explorerequestinclusion.md @@ -0,0 +1,32 @@ + +# 4.3.2.1 ZW_ExploreRequestInclusion + +BYTE ZW_ExploreRequestInclusion() + +An application MAY use this function to initiate a Network-Wide Inclusion process. In response to the call, the Z-Wave protocol MUST send out an explorer frame requesting inclusion (add) into a network. + +[The application MUST enable Learn Mode (refer to 4.4.30 for controllers or 4.8.2 for slaves) with the](../../04.04-z-wave-controller-api/04.04.30-zw_setlearnmode.md#4430-zw_setlearnmode) parameter ZW_SET_LEARN_MODE_NWI before calling this function. + +A controller in Network-Wide Inclusion mode MAY accept the inclusion request. In that case, the application requesting inclusion MUST get notified through the callback function specified when calling the ZW_SetLearnMode() function. Once a callback is received from ZW_SetLearnMode() saying that the inclusion process has started, the application MUST NOT make further calls to this function. + +NOTE: An application SHOULD NOT call this function more than once every 4 seconds. + +Defined in: ZW_basis_api.h + +Return value: + +BYTE TRUE Inclusion request queued for transmission + +FALSE Node is not in learn mode + +Serial API + +HOST->ZW: REQ | 0x5E + +ZW->HOST: RES | 0x5E | retVal diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.02-zw_explorerequestexclusion.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.02-zw_explorerequestexclusion.md new file mode 100644 index 0000000..1b0853c --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.02-zw_explorerequestexclusion.md @@ -0,0 +1,34 @@ + +# 4.3.2.2 ZW_ExploreRequestExclusion + +BYTE ZW_ExploreRequestExclusion() + +An application MAY use this function to initiate a Network-Wide Exclusion process. In response to the call, the Z-Wave protocol MUST send out an explorer frame requesting exclusion (remove) out of a network. + +[The application MUST enable Learn Mode (refer to 4.4.30 for controllers or 4.8.2 for slaves) with the](../../04.04-z-wave-controller-api/04.04.30-zw_setlearnmode.md#4430-zw_setlearnmode) parameter ZW_SET_LEARN_MODE_NWE before calling this function and thereby enabling the node to be excluded routed. + +A controller in Network-Wide Exclusion mode MAY accept the exclusion request. In that case, the application requesting exclusion MUST get notified through the callback function specified when calling the ZW_SetLearnMode() function. Once a callback is received from ZW_SetLearnMode() saying that the exclusion process has started, the application MUST NOT make further calls to this function. + +NOTE: Only an excluding controller on the same HomeID as the excludee can do a routed exclusion. + +NOTE: An application SHOULD NOT call this function more than once every 4 seconds. + +Defined in: ZW_basis_api.h + +Return value: + +BYTE TRUE Exclusion (remove) request queued for transmission + +FALSE Node is not in learn mode + +Serial API + +HOST->ZW: REQ | 0x5F + +ZW->HOST: RES | 0x5F | retVal diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.03-zw_getbackgroundrssi.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.03-zw_getbackgroundrssi.md new file mode 100644 index 0000000..51e28f7 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.03-zw_getbackgroundrssi.md @@ -0,0 +1,54 @@ + +# 4.3.2.3 ZW_GetBackgroundRSSI + +Void ZW_GetBackgroundRSSI(RSSI_LEVELS *rssi_levels) + +This function returns the most recent background RSSI levels detected. The RSSI is only measured when the radio is in receive mode. + +Defined in: ZW_basis_api.h + +Return value: + +RSSI_LEVELS* Returns a pointer to a struct containing the rssi levels for each channel in dBms. + +The rssi levels struct is defined as + +typedef struct { signed char rssi_dBm[NUM_CHANNELS]; } RSSI_LEVELS; + +[Each value in the rssi_dBm contains an RSSI value encoded according to Table 7.](04.03.02.03-zw_getbackgroundrssi.md#4323-zw_getbackgroundrssi) NUM_CHANNELS is 2 or 3 depending on the geographic region of the product. + +The rssi level in a single channel is contained in a BYTE encoded as a signed integer: + +Table 7, RSSI Encoding + +| Bit pattern | Value (signed) | Meaning | +| --- | --- | --- | +| 0x7F | 127 | RSSI NOT AVAILABLE. _ _ Returned by ZW GetBackgroundRSSI if the node has not yet _ had time to sample the rssi since powerup. Returned by ZW SendData for unused hops or from pre 6.60 _ repeaters that does not support appending rssi to the routed frame. | +| 0x7E | 126 | RSSI MAX POWER SATURATED _ _ _ | +| 0x7D | 125 | RSSI BELOW SENSITIVITY. _ _ No signal detected. | +| … | … | Reserved | +| 0xE0 | -32 | -32 dBm | +| 0xDF | -33 | -33 dBm | +| … | … | … | + +| 0xA2 | -94 | -94 dBm | +| --- | --- | --- | +| 0xA1 | -95 | Reserved | +| … | … | Reserved | +| 0x80 | -128 | Reserved | + +Notes: The rssi level is defined as the RSSI measured at the antenna when no Z-Wave traffic is present. The dynamic range of rssi measurements on a 500-series Z-Wave chip is from -94 dBm to -32 dBm. The precision of the measurement is +/- 2 dBm. The returned values assume a path loss of ~7 dBm from chip input to antenna. This corresponds to a typical SAW filter and antenna. For maximum accuracy, these readings should be calibrated with RF measurements performed on a final product including the final antenna design. + +Serial API + +HOST->ZW: REQ | 0x3B + +ZW->HOST: RES | 0x3B | Ch0 | Ch1 for 2-channel systems OR + +ZW->HOST: RES | 0x3B | Ch0 | Ch1 | Ch2 for 3-channel systems diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.04-zw_getprotocolstatus.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.04-zw_getprotocolstatus.md new file mode 100644 index 0000000..568ef00 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.04-zw_getprotocolstatus.md @@ -0,0 +1,32 @@ + +# 4.3.2.4 ZW_GetProtocolStatus + +BYTE ZW_GetProtocolStatus(void) + +Macro: ZW_GET_PROTOCOL_STATUS() + +The application MAY request the status of the protocol by calling this function. In response to this function, the Z-Wave protocol MUST return a bitmask reporting the current status of the protocol. + +Defined in: ZW_basis_api.h + +Return value: + +BYTE Returns the protocol status as one of the following: + +Zero Protocol is idle. + +ZW_PROTOCOL_STATUS_ROUTING Protocol is analyzing the routing table. + +ZW_PROTOCOL_STATUS_SUC SIS sends pending updates. + +Serial API + +HOST->ZW: REQ | 0xBF + +ZW->HOST: RES | 0xBF | retVal diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.05-zw_getrandomword.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.05-zw_getrandomword.md new file mode 100644 index 0000000..85fd8f7 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.05-zw_getrandomword.md @@ -0,0 +1,48 @@ + +# 4.3.2.5 ZW_GetRandomWord + +BYTE ZW_GetRandomWord(BYTE *randomWord) + +Macro: ZW_GET_RANDOM_WORD(randomWord) + +An application SHOULD NOT use this function during normal operation as the radio communication is disabled during function execution. The function MAY however be used for algorithms depending on true [randomness, e.g., as a seed generator for Pseudo-Random Number Generator (PRNG) functions used for security encryption. Instead, the function ZW_Random SHOULD be used (refer to 4.3.2.6).](04.03.02.06-zw_random.md#4326-zw_random) + +This function returns a random word using the 500 series built-in hardware random number generator based on (internal) RF noise (RFRNG). + +Defined in: ZW_basis_api.h + +Return value: + +BOOL TRUE If possible to generate random number. + +FALSE If not possible – will happen if RF is busy at the time of the function call. + +Parameters: + +randomWord OUT Pointer to word variable, which should receive the random word. Serial API + +The Serial API function 0x1C makes use of the ZW_GetRandomWord to generate a specified number of random bytes: + + Call ZW_GetRandomWord until enough random bytes generated or ZW_GetRandomWord returns FALSE. + + Return result to HOST. + +HOST -> ZW: REQ | 0x1C | [noRandomBytes] + +noRandomBytes Number of random bytes needed. Optional if not present or equal ZERO then 2 random bytes are returned Range 1...32 random bytes are supported. + +ZW -> HOST: RES | 0x1C | randomGenerationSuccess | noRandomBytesGenerated | noRandomGenerated[noRandomBytesGenerated] + +randomGenerationSuccess TRUE if random bytes could be generated + +FALSE if no random bytes could be generated + +noRandomBytesGenerated Number of random numbers generated + +noRandomBytesGenerated[] Array of generated random bytes diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.06-zw_random.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.06-zw_random.md new file mode 100644 index 0000000..f1f07a0 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.06-zw_random.md @@ -0,0 +1,28 @@ + +# 4.3.2.6 ZW_Random + +BYTE ZW_Random( void ) + +Macro: ZW_RANDOM() + +This function implements a simple pseudo-random number generator that generates a sequence of numbers, the elements of which are approximately independent of each other. The same sequence of pseudo-random numbers will be repeated in case the module is power cycled. + +An application MAY use this function for implementing random behavior, e.g., when multiple nodes respond to a multicast message. The Z-Wave protocol MAY also use this function for random backoff, etc. Due to its simple nature, an application MUST NOT use this function for obtaining random values for security key calculation and encryption. + +Defined in: ZW_basis_api.h + +Return value: + +BYTE Random number (0 – 0xFF) + +Serial API + +HOST->ZW: REQ | 0x1D + +ZW->HOST: RES | 0x1D | rndNo diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.07-zw_registerbackgroundrssicallback.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.07-zw_registerbackgroundrssicallback.md new file mode 100644 index 0000000..86e3d1b --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.07-zw_registerbackgroundrssicallback.md @@ -0,0 +1,44 @@ + +# 4.3.2.7 ZW_RegisterBackgroundRSSICallback + +void ZW_RegisterBackgroundRSSICallback(VOID_CALLBACKFUNC(cbFun)(RSSI_LEVELS *)) + +ZW_RegisterBackgroundRSSICallback registers a callback function that is called whenever new background RSSI measurements for all channel are ready. + +The callback function is invoked with a pointer argument to a structure containing the RSSI values per channel. + +Defined in: ZW_basis_api.h + +Parameters: + +cbFun IN Function pointer to the callback function. The callback function must accept a RSSI_LEVELS pointer as its first and only argument. + +The callback function must accept a pointer argument to a RSSI_LEVELS structure containing the RSSI values per channel. The RSSI_LEVELS structure is defined as: + +typedef struct { signed char rssi_dBm[NUM_CHANNELS]; } RSSI_LEVELS; + +NUM_CHANNELS has a value of 2 or 3 depending on geographical region. + +The RSSI values in rssi_dBm are signed byte values with the largest positive values having special meanings. On a 500-series Z-Wave chip, RSSI values between -94 dBm and -32 dBm are returned. RSSI_MAX_POWER_SATURATED is returned if the received background noise exceeds -32 dBm. RSSI_BELOW_SENSITIVITY is returned if the received noise power is below -94 dBm. The precision of the reading is +/- 2 dBms. + +The frequency of callbacks is typically around 100 Hz. But it depends on many factors, including how much work is performed in ApplicationPoll and how many interrupts are generated. Customers with specific requirements on the sampling frequency is adviced to validate their customized firmware. + +A note on loss calibration (The power levels returned are power levels at the antenna. A path loss of approx. 7 dBms from antenna to chip RF input is assumed to account for SAW filter loss, antenna loss, temperature variations and other factors. For precise readings, it is important to calibrate the measurement to the antenna design of the finished product. Example use + +#include + +void ZCB_rssi_level_callback( RSSI_LEVELS *noise); code const void (code * ZCB_rssi_level_callback_p)(RSSI_LEVELS*) = &ZCB_rssi_level_callback; /*========================== ZCB_rssi_level_callback ================== ** Callback func for rssi level detection ** **-------------------------------------------------------------------------- */ void /* RET Nothing */ ZCB_rssi_level_callback(RSSI_LEVELS *rssi) /* IN RSSI levels pointer */ { /* Do something with rssi values...*/ ZW_DEBUG_SEND_NUM(noise->rssi_dBm[0]); ZW_DEBUG_SEND_NUM(noise->rssi_dBm[1]); #ifdef ZW_3CH_SYSTEM ZW_DEBUG_SEND_NUM(noise->rssi_dBm[2]); #endif } + +/*============================== ApplicationInitSW ===================== = ** Initialization of the Application Software ** **-------------------------------------------------------------------------- */ BYTE /*RET TRUE */ ApplicationInitSW(void) /*IN Nothing */ { /* Other initialization code here... */ + +ZW_RegisterBackgroundRSSICallback(ZCB_rssi_level_callback); } + +Serial API: + +ZW_GetBackgroundRSSI() Not available via SerialAPI. See the function instead. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.08-zw_rfpowerlevelset.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.08-zw_rfpowerlevelset.md new file mode 100644 index 0000000..2f4be8b --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.08-zw_rfpowerlevelset.md @@ -0,0 +1,52 @@ + +# 4.3.2.8 ZW_RFPowerLevelSet + +BYTE ZW_RFPowerLevelSet(BYTE powerLevel ) + +Macro: ZW_RF_POWERLEVEL_SET(POWERLEVEL) + +An application MAY use this function to set the power level used for RF transmission. The actual RF power is dependent on the settings for transmit power level in App_RFSetup.a51. If this value is changed from the default library value the resulting power levels might differ from the intended values. The returned value is however always the actual one used. + +NOTE: This function should only be used in an install/test link situation and the power level should always be set back to normal Power when the testing is done. + +Defined in: ZW_basis_api.h + +Parameters: + +powerLevel IN Powerlevel to use in RF transmission, valid values: + +normalPower Max power possible + +minus1dB Normal power - 1dB (mapped to minus2dB 1) + +minus2dB Normal power - 2dB + +minus3dB Normal power - 3dB (mapped to minus4dB) + +minus4dB Normal power - 4dB + +minus5dB Normal power - 5dB (mapped to minus6dB) + +minus6dB Normal power - 6dB + +minus7dB Normal power - 7dB (mapped to minus8dB) + +minus8dB Normal power - 8dB + +minus9dB Normal power - 9dB (mapped to minus10dB) + +Return value: + +BYTE The powerlevel set. + +Serial API (Serial API protocol version 4): + +HOST->ZW: REQ | 0x17 | powerLevel + +ZW->HOST: RES | 0x17 | retVal diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.09-zw_rfpowerlevelget.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.09-zw_rfpowerlevelget.md new file mode 100644 index 0000000..8f46642 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.09-zw_rfpowerlevelget.md @@ -0,0 +1,28 @@ + +# 4.3.2.9 ZW_RFPowerLevelGet + +BYTE ZW_RFPowerLevelGet( void ) + +Macro: ZW_RF_POWERLEVEL_GET() + +Get the current power level used in RF transmitting. + +NOTE: This function should only be used in an install/test link situation. + +Defined in: ZW_basis_api.h + +Return value: + +BYTE The power level currently in effect during RF transmissions. + +Serial API + +HOST->ZW: REQ | 0xBA + +ZW->HOST: RES | 0xBA | powerlevel diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.10-zw_requestnetworkupdate.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.10-zw_requestnetworkupdate.md new file mode 100644 index 0000000..020277c --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.10-zw_requestnetworkupdate.md @@ -0,0 +1,60 @@ + +# 4.3.2.10 ZW_RequestNetWorkUpdate + +BYTE ZW_RequestNetWorkUpdate ( VOID_CALLBACKFUNC (completedFunc)(BYTE txStatus, TX_STATUS_TYPE* txStatusReport)) + +Macro: ZW_REQUEST_NETWORK_UPDATE (func) + +This API call is used to request a network update from a SUC/SIS controller. Any changes are reported to the application by calling the ApplicationControllerUpdate). + +All controllers MAY use this call if there is a SUC/SIS in the network. Secondary controllers MUST NOT use this call if there is no SUC/SIS in the network. + +All types of routing slaves MAY use this call if there is a SUC/SIS in the network. Routing Slaves MUST NOT use this call if there is no SUC/SIS in the network. In case the Routing Slave has called ZW_RequestNewRouteDestinations prior to ZW_RequestNetWorkUpdate, then Return Routes for the destinations specified by the application in ZW_RequestNewRouteDestinations will be updated along with the SUC Return Route. + +Checking if a SUC/SIS is known by the node is done using the API call ZW_GetSUCNodeID. + +NOTE: The SUC/SIS can only handle one network update process at a time. If another request is made during a network update process then the latest requesting node receives a ZW_SUC_UPDATE_WAIT status. + +WARNING: This API call will generate a lot of network activity that will use bandwidth and stress the SUC/SIS in the network. Therefore, network updates SHOULD be requested as seldom as possible and never more often that once every hour from a controller. + +Defined in: ZW_controller_api.h and ZW_slave_routing_api.h + +Return value: + +BYTE TRUE If the updating process is started. + +FALSE If the requesting controller is the SUC node or the SUC node is unknown. + +Parameters: + +completedFunc Transmit complete call back. IN Callback function Parameters: + +txStatus IN Status of command: + +ZW_SUC_UPDATE_DONE The update process succeeded. + +ZW_SUC_UPDATE_ABORT The update process aborted because of an error. + +ZW_SUC_UPDATE_WAIT The SUC node is busy. + +ZW_SUC_UPDATE_DISABLED The SUC functionality is disabled. + +ZW_SUC_UPDATE_OVERFLOW The controller requested an update after more than 64 changes have occurred in the network. The update information is then out of date in respect to that controller. In this situation the controller have to make a replication (copy) before trying to request any new network updates. + +txStatusReport (see ZW_SendData) IN + +Serial API: + +HOST->ZW: REQ | 0x53 | funcID + +Notice: funcID is used to correlate callback with original request. Callback is disabled by setting funcID equal to zero in original request. + +ZW->HOST: RES | 0x53 | retVal + +ZW->HOST: REQ | 0x53 | funcID | txStatus diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.11-zw_rfpowerlevelrediscoveryset.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.11-zw_rfpowerlevelrediscoveryset.md new file mode 100644 index 0000000..27eaaae --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.11-zw_rfpowerlevelrediscoveryset.md @@ -0,0 +1,48 @@ + +# 4.3.2.11 ZW_RFPowerlevelRediscoverySet + +void ZW_RFPowerlevelRediscoverySet(BYTE bNewPower) + +Macro: ZW_RF_POWERLEVEL_REDISCOVERY_SET(bNewPower) + +This function MAY be used to set the power level locally in the node when finding neighbors. + +The default power level used for rediscovery is normal power minus 6dB. The default power level SHOULD be used. The call to ZW_RFPowerlevelRediscoverySet MAY be omitted if the default power level is to be used. + +It is NOT RECOMMENDED to use other power levels. Increased power levels may cause weak RF links to be included in the routing table. Weak RF links can increase latency in the network due to retries to get through. Further reduced power levels may cause nodes with good link properties to not be discovered. This may lead to increased latency due to additional hops to the destination. + +A call to this function affects the power level used for all future neighbor discovery operations. The function can be called from ApplicationInit or during runtime from ApplicationPoll or Application- CommandHandler. + +Defined in: ZW_basis_api.h + +Parameters: + +bNewPower IN Powerlevel to use when doing neighbor discovery, valid values: + +normalPower Max power possible + +minus1dB Normal power - 1dB (mapped to minus2dB 1) + +minus2dB Normal power - 2dB + +minus3dB Normal power - 3dB (mapped to minus4dB) + +minus4dB Normal power - 4dB + +minus5dB Normal power - 5dB (mapped to minus6dB) + +minus6dB Normal power - 6dB + +minus7dB Normal power - 7dB (mapped to minus8dB) + +minus8dB Normal power - 8dB + +minus9dB Normal power - 9dB (mapped to minus10dB) + +Serial API: HOST->ZW: REQ | 0x1E | powerLevel diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.12-zw_sendnodeinformation.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.12-zw_sendnodeinformation.md new file mode 100644 index 0000000..c5e56f1 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.12-zw_sendnodeinformation.md @@ -0,0 +1,50 @@ + +# 4.3.2.12 ZW_SendNodeInformation + +BYTE ZW_SendNodeInformation(BYTE destNode, BYTE txOptions, VOID_CALLBACKFUNC(completedFunc)(BYTE txStatus)) + +Macro: ZW_SEND_NODE_INFO(node,option,func) + +Create and transmit a “Node Information” frame. The Z-Wave transport layer builds a frame, request application node information (see ApplicationNodeInformation) and queue the “Node Information” frame for transmission. The completed call back function (completedFunc) is called when the transmission is complete. + +The Node Information Frame is a protocol frame and will therefore not be directly available to the application on the receiver. The API call ZW_SetLearnMode() can be used to instruct the protocol to pass the Node Information Frame to the application. + +When ZW_SendNodeInformation() is used in learn mode for adding or removing the node from the network the transmit option TRANSMIT_OPTION_LOW_POWER should NOT be used. + +NOTE: ZW_SendNodeInformation uses the transmit queue in the API, so using other transmit functions before the complete callback has been called by the API is not recommended. + +WARNING: It is not allowed to call ZW_SendNodeInformation() from a controller when ZW_SetLearnMode() is active. + +Defined in: ZW_basis_api.h + +Return value: + +BYTE TRUE If frame was put in the transmit queue + +FALSE If it was not (callback will not be called) + +Parameters: + +destNode IN Destination Node ID (NODE_BROADCAST == all nodes) + +txOptions IN Transmit option flags. (see ZW_SendData) + +completedFunc Transmit completed call back function IN + +Callback function Parameters: + +txStatus IN (see ZW_SendData) + +txStatusReport IN (see ZW_SendData) + +Serial API: + +HOST->ZW: REQ | 0x12 | destNode | txOptions | funcID ZW->HOST: RES | 0x12 | retVal + +ZW->HOST: REQ | 0x12 | funcID | txStatus diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.13-zw_sendtestframe.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.13-zw_sendtestframe.md new file mode 100644 index 0000000..166f9a8 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.13-zw_sendtestframe.md @@ -0,0 +1,62 @@ + +# 4.3.2.13 ZW_SendTestFrame + +BYTE ZW_SendTestFrame(BYTE nodeID, BYTE powerlevel, VOID_CALLBACKFUNC(func)(BYTE txStatus, TX_STATUS_TYPE* txStatusReport)) + +Macro: ZW_SEND_TEST_FRAME(nodeID, power, func) + +Send a test frame directly to nodeID without any routing, RF transmission power is previously set to powerlevel by calling ZW_RF_POWERLEVEL_SET. The test frame is acknowledged at the RF transmission powerlevel indicated by the parameter powerlevel by nodeID (if the test frame got through). This test will be done using 9600 kbit/s transmission rate. + +NOTE: This function should only be used in an install/test link situation. + +Defined in: ZW_basis_api.h + +Parameters: + +nodeID IN Node ID on the node ID (1..232) the test frame should be transmitted to. + +powerLevel IN Powerlevel to use in RF transmission, valid values: + +normalPower Max power possible + +minus1dB Normal power - 1dB (mapped to minus2dB 1) + +minus2dB Normal power - 2dB + +minus3dB Normal power - 3dB (mapped to minus4dB) + +minus4dB Normal power - 4dB + +minus5dB Normal power - 5dB (mapped to minus6dB) + +minus6dB Normal power - 6dB + +minus7dB Normal power - 7dB (mapped to minus8dB) + +minus8dB Normal power - 8dB + +minus9dB Normal power - 9dB (mapped to minus10dB) + +func IN Call back function called when done. Callback function Parameters: + +txStatus IN (see ZW_SendData) + +txStatusReport IN (see ZW_SendData) + +Return value: + +BYTE FALSE If transmit queue overflow. + +Serial API + +HOST->ZW: REQ | 0xBE | nodeID| powerlevel | funcID + +ZW->HOST: RES | 0xBE | retVal + +ZW->HOST: REQ | 0xBE | funcID | txStatus diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.14-zw_setextintlevel.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.14-zw_setextintlevel.md new file mode 100644 index 0000000..4fb97c5 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.14-zw_setextintlevel.md @@ -0,0 +1,39 @@ + +# 4.3.2.14 ZW_SetExtIntLevel + +void ZW_SetExtIntLevel(BYTE intSrc, BYTE triggerLevel) + +Macro: ZW_SET_EXT_INT_LEVEL(SRC, TRIGGER_LEVEL) + +This function MAY be used to set the trigger level for external interrupts. Level triggered interrupt MUST be selected as follows: + +| | Level Triggered | +| --- | --- | +| External interrupt 0 | IT0 = 0; | +| External interrupt 1 | IT1 = 0; | + +Defined in: ZW_basis_api.h + +Parameters: + +intSrc IN The external interrupt valid values: + +ZW_INT0 External interrupt 0 (Pin P1.0) + +ZW_INT1 External interrupt 1 (Pin P1.1) + +triggerLevel IN The external interrupt trigger level: + +TRUE Set the interrupt trigger to high level + +FALSE Set the interrupt trigger to low level + +Serial API + +HOST->ZW: REQ | 0xB9 | intSrc | triggerLevel diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.15-zw_setpromiscuousmode-only-controller-libraries.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.15-zw_setpromiscuousmode-only-controller-libraries.md new file mode 100644 index 0000000..6189311 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.15-zw_setpromiscuousmode-only-controller-libraries.md @@ -0,0 +1,42 @@ + +# 4.3.2.15 ZW_SetPromiscuousMode (only Controller Libraries) + +void ZW_SetPromiscuousMode(BOOL state) + +Macro: ZW_SET_PROMISCUOUS_MODE(state) + +The API call ZW_SetPromiscuousMode enable / disable promiscuous mode. + +A Controller in promiscuous mode will transfer payload from a promiscuously received application frame destined and originated from nodes residing in same network (HomeID). The promiscuously received application frame (only end destination frame) will be transferred to the application through ApplicationCommandHandler / ApplicationCommandHandler_Bridge with the RECEIVE_STATUS_FOREIGN_FRAME bit set in rxStatus. + +A promiscuously application received frame is defined as: + + A frame transmitted using the same HomeID as the promiscuous controller itself.  A frame neither originated by nor destined the promiscuous controller itself.  A frame containing the application command class payload + +An end destination frame is defined as either: + + Direct frame,  Outgoing routed frame sent by last repeater,  Multicast frame or  Explore frame + +With the following exceptions when the controller is a repeater itself: + + Explore frames the controller actively repeats is not transferred to the application.  Routed frames with the controller as the last repeater - only one promiscuously received application frame is transferred through ApplicationCommandHandler / ApplicationCommandHandler_Bridge and is transferred on the receiving of the frame transmitted by the previous Repeater. This is done even if the controller, as repeater, does retries. Acting as repeater the controller will try transmitting up to 3 times before giving up -> Routed Error. + +[Promiscuously received frames are delivered to the application via the ApplicationCommandHandler / ApplicationCommandHandler_Bridge callback function (see section 0 / 4.3.1.9).](../04.03.01-required-application-functions/04.03.01.04-applicationpoll.md#4314-applicationpoll) + +Defined in: ZW_basis_api.h + +Parameters: + +state IN TRUE to enable the promiscuous mode, FALSE to disable it. + +Serial API: + +HOST->ZW: REQ | 0xD0 | state + +[See section 0 / 4.3.1.9 for callback syntax when a frame has been promiscuously received.](../04.03.01-required-application-functions/04.03.01.04-applicationpoll.md#4314-applicationpoll) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.16-zw_setrfreceivemode.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.16-zw_setrfreceivemode.md new file mode 100644 index 0000000..1e1c950 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.16-zw_setrfreceivemode.md @@ -0,0 +1,34 @@ + +# 4.3.2.16 ZW_SetRFReceiveMode + +BYTE ZW_SetRFReceiveMode( BYTE mode ) + +Macro: ZW_SET_RX_MODE(mode) + +ZW_SetRFReceiveMode is used to power down the RF when not in use e.g., expects nothing to be received. ZW_SetRFReceiveMode can also be used to set the RF into receive mode. This functionality is useful in battery powered Z-Wave nodes e.g., the Z-Wave Remote Controller. The RF is automatic powered up when transmitting data. + +Defined in: ZW_basis_api.h + +Return value: + +BYTE TRUE If operation was successful + +FALSE If operation was none successful + +Parameters: + +mode IN TRUE On: Set the RF in receive mode and starts the receive data sampling + +FALSE Off: Set the RF in power down mode (for battery power save). + +Serial API + +HOST->ZW: REQ | 0x10 | mode + +ZW->HOST: RES | 0x10 | retVal diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.17-zw_type_library.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.17-zw_type_library.md new file mode 100644 index 0000000..6ab2820 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.17-zw_type_library.md @@ -0,0 +1,40 @@ + +# 4.3.2.17 ZW_Type_Library + +BYTE ZW_Type_Library( void ) + +Macro: ZW_TYPE_LIBRARY() + +Get the Z-Wave library type. + +Defined in: ZW_basis_api.h + +Return value: + +BYTE Returns the library type as one of the following: + +ZW_LIB_CONTROLLER_STATIC Static controller library + +ZW_LIB_CONTROLLER_BRIDGE Bridge controller library + +ZW_LIB_CONTROLLER Portable controller library + +ZW_LIB_SLAVE_ENHANCED Enhanced 232 slave library + +ZW_LIB_SLAVE_ROUTING Routing slave library + +ZW_LIB_SLAVE Slave library + +ZW_LIB_INSTALLER Installer library + +Serial API + +HOST->ZW: REQ | 0xBD + +ZW->HOST: RES | 0xBD | retVal diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.18-zw_version.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.18-zw_version.md new file mode 100644 index 0000000..f2c5565 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.18-zw_version.md @@ -0,0 +1,48 @@ + +# 4.3.2.18 ZW_Version + +BYTE ZW_Version( BYTE *buffer ) + +Macro: ZW_VERSION(buffer) + +Get the Z-Wave basis API library version. + +Defined in: ZW_basis_api.h + +Parameters: + +buffer OUT Returns the API library version in text using the format: + +Z-Wave x.yy + +where x.yy is the library version. + +Return value: + +BYTE Returns the library type as one of the following: + +ZW_LIB_CONTROLLER_STATIC Static controller library + +ZW_LIB_CONTROLLER_BRIDGE Bridge controller library + +ZW_LIB_CONTROLLER Portable controller library + +ZW_LIB_SLAVE_ENHANCED Enhanced 232 slave library + +ZW_LIB_SLAVE_ROUTING Routing slave library + +ZW_LIB_SLAVE Slave library + +ZW_LIB_INSTALLER Installer library + +Serial API: + +HOST->ZW: REQ | 0x15 + +ZW->HOST: RES | 0x15 | buffer (12 bytes) | library type diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.19-zw_version_major-zw_version_minor-zw_version_beta.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.19-zw_version_major-zw_version_minor-zw_version_beta.md new file mode 100644 index 0000000..bc9d0a9 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.19-zw_version_major-zw_version_minor-zw_version_beta.md @@ -0,0 +1,18 @@ + +# 4.3.2.19 ZW_VERSION_MAJOR / ZW_VERSION_MINOR / ZW_VERSION_BETA + +Macro: ZW_VERSION_MAJOR/ZW_VERSION_MINOR/ ZW_VERSION_BETA + +These #defines can be used to get a decimal value of the used Z-Wave library. ZW_VERSION_MINOR should be 0 padded when displayed to users EG: ZW_VERSION_MAJOR = 1 ZW_VERSION_MINOR =2 should be shown as: 1.02 to the user where as ZW_VERSION_MAJOR = 1 ZW_VERSION_MINOR =20 should be shown as 1.20. + +ZW_VERSION_BETA is only defined for beta releases of the Z-Wave Library. In which case it is defined as a single char for instance: 'b' + +Defined in: ZW_basis_api.h + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.20-zw_watchdogenable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.20-zw_watchdogenable.md new file mode 100644 index 0000000..194d6ad --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.20-zw_watchdogenable.md @@ -0,0 +1,24 @@ + +# 4.3.2.20 ZW_WatchDogEnable + +void ZW_WatchDogEnable(void) + +Macro: ZW_WATCHDOG_ENABLE() + +This function may be used to enable the 500 Series Z-Wave SoC built-in watchdog. + +It is possible to implement a reliable safety system with a hardware watchdog; resetting the entire hardware if a part of the system stops operating correctly. Properly designed, the watchdog handler [monitors a critical chain of conditions that must be met before the watchdog is kicked again. See 4.3.2.22.](04.03.02.22-zw_watchdogkick.md#43222-zw_watchdogkick) + +By default, the watchdog is disabled. The watchdog SHOULD be enabled in released product firmware. It is however RECOMMENDED that the watchdog is not enabled during development and testing prior to final release testing. An enabled watchdog may prevent firmware crashes and stalls from being discovered during development and initial testing. As a side note, debugging a system with an enabled watchdog can be a challenge. + +Defined in: ZW_basis_api.h + +Serial API + +HOST->ZW: REQ | 0xB6 diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.21-zw_watchdogdisable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.21-zw_watchdogdisable.md new file mode 100644 index 0000000..f30ae03 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.21-zw_watchdogdisable.md @@ -0,0 +1,20 @@ + +# 4.3.2.21 ZW_WatchDogDisable + +void ZW_WatchDogDisable(void) + +Macro: ZW_WATCHDOG_DISABLE () + +This function may be used to disable the 500 Series Z-Wave SoC built in watchdog. + +Defined in: ZW_basis_api.h + +Serial API + +HOST->ZW: REQ | 0xB7 diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.22-zw_watchdogkick.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.22-zw_watchdogkick.md new file mode 100644 index 0000000..4824c35 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.22-zw_watchdogkick.md @@ -0,0 +1,28 @@ + +# 4.3.2.22 ZW_WatchDogKick + +void ZW_WatchDogKick(void) + +Macro: ZW_WATCHDOG_KICK () + +This function SHOULD be used to keep the watchdog timer from resetting the 500 Series Z-Wave SoC. The watchdog timeout interval is 1 second. If enabled, the watchdog MUST be kicked at least one time per interval. Failing to do so will cause the 500 Series Z-Wave SoC to be reset. + +It is possible to implement a reliable safety system with a hardware watchdog; resetting the entire hardware if a part of the system stops operating correctly. Properly designed, the watchdog handler monitors a critical chain of conditions that must be met before the watchdog is kicked again. + +It is RECOMMENDED that the designer seeks inspiration in the literature for the design of a reliable watchdog handler. + +The resulting executable code does not necessarily require much code space. As a minimum, one SHOULD call ZW_WatchDogKick from the function ApplicationPoll. An unconditional call of ZW_WatchDogKick from ApplicationPoll will however only catch Z-Wave protocol exceptions. Without the abovementioned critical chain of conditions, an application may hang infinitely in an unforeseen state without getting reset by the hardware watchdog. + +The watchdog SHOULD be kicked one or more times from the function ApplicationInitSW to avoid unintentional reset of the application during initialization. + +Defined in: ZW_basis_api.h + +Serial API + +HOST->ZW: REQ | 0xB8 diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.23-zw_gettxtimer.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.23-zw_gettxtimer.md new file mode 100644 index 0000000..d99776e --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.23-zw_gettxtimer.md @@ -0,0 +1,26 @@ + +# 4.3.2.23 ZW_GetTxTimer + +void ZW_GetTxTimer(BYTE bChannel, DWORD *dwTxTime) + +This function gets the protocols internal tx timer for the specified channel. The returned value is in milli seconds from the last call to ZW_ClearTxTimers(). The tx timers are updated by the protocol exery time a frame is send. + +Defined in: ZW_basis_api.h + +Parameters: + +bChannel IN The channel to get the tx timer from. Valid channels are 0, 1 and 2 + +dwTxTime OUT The time the transmitter has been active since the last reset or call to ZW_ClearTxTimers() + +Serial API: + +HOST->ZW: REQ | 0x38 + +ZW->HOST: RES | 0x38 | TxTimeChannel0 | TxTimeChannel1 | TxTimeChannel2 diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.24-zw_cleartxtimers.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.24-zw_cleartxtimers.md new file mode 100644 index 0000000..8b472d7 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.24-zw_cleartxtimers.md @@ -0,0 +1,18 @@ + +# 4.3.2.24 ZW_ClearTxTimers + +void ZW_ClearTxTimers(void) + +This function clears the protocols internal tx timers. The tx timers are updated by the protocol exery time a frame is send. + +Defined in: ZW_basis_api.h + +Serial API + +HOST->ZW: REQ | 0x37 diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.25-zw_getnetworkstats.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.25-zw_getnetworkstats.md new file mode 100644 index 0000000..1976b9e --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.25-zw_getnetworkstats.md @@ -0,0 +1,58 @@ + +# 4.3.2.25 ZW_GetNetworkStats + +void ZW_GetNetworkStats(S_NETWORK_STATISTICS *sNetworkStats) + +This function retrieves the current Network Statistics as collected by the Z-Wave protocol. The Z-Wave protocol will continuesly update any Network Statistics counter until it reaches 65535, which then [indicates that the specific counter has reached 65535 or more occurrences. The Network Statistics counters are cleared either on module startup or by calling ZW_ClearNetworkStats().](04.03.02.26-zw_clearnetworkstats.md#43226-zw_clearnetworkstats) + +Defined in: ZW_basis_api.h + +Parameters: + +*sNetworkStats typedef struct _S_NETWORK_STATISTICS_ + +OUT { WORD wRFTxFrames Transmitted Frames – + +including Retries and ACKs + +WORD wRFTxLBTBackOffs; Receiving Z-Wave frame or + +RSSI detected to be too high + +for starting transmission. 3 + +channel will if too high RSSI + +change channel on next try to + +start same frame transmission. + +2 channel will Fail frame after 1 + +second of continuously LBT + +Backoffs. + +WORD wRFRxFrames; Received Frames (No errors) + +WORD wRFRxLRCErrors; Received Checksum Errors (2 + +channel only) + +WORD wRFRxCRC16Errors; Received CRC16 Errors + +WORD wRFRxForeignHomeID; Received Foreign Home ID + +} S_NETWORK_STATISTICS; + +Serial API: + +HOST->ZW: REQ | 0x3A + +ZW->HOST: RES | 0x3A | wRFTxFrames_MSB | wRFTxFrames_LSB | wRFTxLBTBackOffs_MSB | wRFTxLBTBackOffs_LSB | wRFRxFrames_MSB | wRFRxFrames_LSB | wRFRxLRCErrors_MSB | wRFRxLRCErrors_LSB | wRFRxCRC16Errors_MSB | wRFRxCRC16Errors_LSB | wRFRxForeignHomeID_MSB | wRFRxForeignHomeID_LSB diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.26-zw_clearnetworkstats.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.26-zw_clearnetworkstats.md new file mode 100644 index 0000000..7c1266d --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.26-zw_clearnetworkstats.md @@ -0,0 +1,20 @@ + +# 4.3.2.26 ZW_ClearNetworkStats + +void ZW_ClearNetworkStats(void) + +This function clears the current Network Statistics collected by the Z-Wave protocol. + +Defined in: ZW_basis_api.h + +Serial API + +HOST->ZW: REQ | 0x39 + +ZW->HOST: RES | 0x01 diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.27-zw_power_management_init.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.27-zw_power_management_init.md new file mode 100644 index 0000000..88e642d --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.27-zw_power_management_init.md @@ -0,0 +1,34 @@ + +# 4.3.2.27 ZW_Power_Management_Init + +void ZW_Power_Management_Init(DWORD sleepPeriod, BYTE intEnable ) + +This function is used to set the WUT sleep period (in seconds) for None listening node which periodically enter WUT sleep mode to preserve power. Also settable is if node should be able to wake up through the EXT1 pin activation. + +Defined in: ZW_basis_api.h + +Parameters: + +sleepPeriod IN Number of seconds the node + +should be in WUT mode before + +application is called again. + +intEnable IN Interrupt enable bit mask. Valid + +bit masks are: + +ZW_INT_MASK_EXT1 External interrupt 1 (PIN P1_1) is enabled as + +interrupt source + +0x00 No external Interrupts will wakeup. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.28-zw_networklearnmodestart.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.28-zw_networklearnmodestart.md new file mode 100644 index 0000000..0a75482 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.28-zw_networklearnmodestart.md @@ -0,0 +1,50 @@ + +# 4.3.2.28 ZW_NetworkLearnModeStart + +void ZW_NetworkLearnModeStart(E_NETWORK_LEARN_MODE_ACTION eMode) + +This function enables/disables the Network Management module inclusion/exclusion mode sequence according to specified mode. + +The Application defined ApplicationNetworkLearnModeCompleted [(See 4.3.1.11, 4.3.1.12) is called](../04.03.01-required-application-functions/04.03.01.11-applicationnetworklearnmodecompleted-only-controller-libraries.md#43111-applicationnetworklearnmodecompleted-only-controller-libraries) with either status or final result of mode sequence. + +Defined in: ZW_basis_api.h + +Parameters: + +eMode Valid mode values are: + +IN E_NETWORK_LEARN_MODE_ Disable learn process + +DISABLE + +E_NETWORK_LEARN_MODE_ Enable the learn process to do an inclusion. Will first try + +INCLUSION Classic inclusion followed by 4 tries of NWI. + +E_NETWORK_LEARN_MODE_ Enable the learn process to do a Classic exclusion. + +EXCLUSION + +E_NETWORK_LEARN_MODE_ Enable the learn process to do a NWE with 4 tries. + +EXCLUSION_NWE + +E_NETWORK_LEARN_MODE_ Enable the learn process to do an SMART START + +INCLUSION_SMARTSTART inclusion. + +Serial API + +The ZW_NetworkLearnModeStart functionality can through Serial API be reached with the FUNC_ID_ZW_SET_LEARN_MODE functionality by adding SERIALPI_SET_LEARN_MODE_LEARN_PLUS_OFFSET to the needed Network Learn Mode. + +SERIALPI_SET_LEARN_MODE_LEARN_PLUS_OFFSET = 0x80 + +HOST->ZW: REQ | 0x50 | eMode + 0x80 | funcID + +ZW->HOST: RES | 0x01 diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.29-zw_networkmanagementsetmaxinclusionrequestintervals.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.29-zw_networkmanagementsetmaxinclusionrequestintervals.md new file mode 100644 index 0000000..ad33871 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/04.03.02.29-zw_networkmanagementsetmaxinclusionrequestintervals.md @@ -0,0 +1,30 @@ + +# 4.3.2.29 ZW_NetworkManagementSetMaxInclusionRequestIntervals + +BYTE ZW_NetworkManagementSetMaxInclusionRequestIntervals( BYTE bInclRequestIntervals) + +This function can be used to set the maximum interval between SmartStart inclusion requests. + +Defined in: ZW_basis_api.h + +Return value: + +BYTE FALSE 0: Requested maximum intervals either 0(default) or not valid + +TRUE 5-99: The requested number of intervals set + +Parameters: + +bInclRequestIntervals The maximum number of 128 sec The unit is 128sec and valid range IN ticks between SmartStart inclusion is 5-99. requests. [5…99] => [640 sec … 12672 sec] + +Serial API + +HOST->ZW: REQ | 0xD6 | bInclRequestIntervals + +ZW->HOST: RES | 0xD6 | RetVal diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/index.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/index.md new file mode 100644 index 0000000..f880b3a --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.02-z-wave-basis-api/index.md @@ -0,0 +1,42 @@ + +# 4.3.2 Z-Wave Basis API + +This section defines functions that are implemented in all Z-Wave nodes. + +## Contents + +- [4.3.2.1 ZW_ExploreRequestInclusion](04.03.02.01-zw_explorerequestinclusion.md) +- [4.3.2.2 ZW_ExploreRequestExclusion](04.03.02.02-zw_explorerequestexclusion.md) +- [4.3.2.3 ZW_GetBackgroundRSSI](04.03.02.03-zw_getbackgroundrssi.md) +- [4.3.2.4 ZW_GetProtocolStatus](04.03.02.04-zw_getprotocolstatus.md) +- [4.3.2.5 ZW_GetRandomWord](04.03.02.05-zw_getrandomword.md) +- [4.3.2.6 ZW_Random](04.03.02.06-zw_random.md) +- [4.3.2.7 ZW_RegisterBackgroundRSSICallback](04.03.02.07-zw_registerbackgroundrssicallback.md) +- [4.3.2.8 ZW_RFPowerLevelSet](04.03.02.08-zw_rfpowerlevelset.md) +- [4.3.2.9 ZW_RFPowerLevelGet](04.03.02.09-zw_rfpowerlevelget.md) +- [4.3.2.10 ZW_RequestNetWorkUpdate](04.03.02.10-zw_requestnetworkupdate.md) +- [4.3.2.11 ZW_RFPowerlevelRediscoverySet](04.03.02.11-zw_rfpowerlevelrediscoveryset.md) +- [4.3.2.12 ZW_SendNodeInformation](04.03.02.12-zw_sendnodeinformation.md) +- [4.3.2.13 ZW_SendTestFrame](04.03.02.13-zw_sendtestframe.md) +- [4.3.2.14 ZW_SetExtIntLevel](04.03.02.14-zw_setextintlevel.md) +- [4.3.2.15 ZW_SetPromiscuousMode (only Controller Libraries)](04.03.02.15-zw_setpromiscuousmode-only-controller-libraries.md) +- [4.3.2.16 ZW_SetRFReceiveMode](04.03.02.16-zw_setrfreceivemode.md) +- [4.3.2.17 ZW_Type_Library](04.03.02.17-zw_type_library.md) +- [4.3.2.18 ZW_Version](04.03.02.18-zw_version.md) +- [4.3.2.19 ZW_VERSION_MAJOR / ZW_VERSION_MINOR / ZW_VERSION_BETA](04.03.02.19-zw_version_major-zw_version_minor-zw_version_beta.md) +- [4.3.2.20 ZW_WatchDogEnable](04.03.02.20-zw_watchdogenable.md) +- [4.3.2.21 ZW_WatchDogDisable](04.03.02.21-zw_watchdogdisable.md) +- [4.3.2.22 ZW_WatchDogKick](04.03.02.22-zw_watchdogkick.md) +- [4.3.2.23 ZW_GetTxTimer](04.03.02.23-zw_gettxtimer.md) +- [4.3.2.24 ZW_ClearTxTimers](04.03.02.24-zw_cleartxtimers.md) +- [4.3.2.25 ZW_GetNetworkStats](04.03.02.25-zw_getnetworkstats.md) +- [4.3.2.26 ZW_ClearNetworkStats](04.03.02.26-zw_clearnetworkstats.md) +- [4.3.2.27 ZW_Power_Management_Init](04.03.02.27-zw_power_management_init.md) +- [4.3.2.28 ZW_NetworkLearnModeStart](04.03.02.28-zw_networklearnmodestart.md) +- [4.3.2.29 ZW_NetworkManagementSetMaxInclusionRequestIntervals](04.03.02.29-zw_networkmanagementsetmaxinclusionrequestintervals.md) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.01-zw_senddata.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.01-zw_senddata.md new file mode 100644 index 0000000..3df25e8 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.01-zw_senddata.md @@ -0,0 +1,210 @@ + +# 4.3.3.1 ZW_SendData + +BYTE ZW_SendData(BYTE nodeID, BYTE *pData, BYTE dataLength, BYTE txOptions, VOID_CALLBACKFUNC(completedFunc)(BYTE txStatus, TX_STATUS_TYPE* txStatusReport )) + +NOTE: Not supported by the Enhanced 232 Slave library, use ZW_SendDataEx instead. + +Macro: ZW_SEND_DATA(node,data,length,options,func) + +This function MAY be used to transmit contents of a data buffer to a single node or all nodes (broadcast). The data buffer contents are encapsulated in a Z-Wave transport frame by adding a protocol header and a checksum trailer. The frame is appended to the end of the transmit queue (first in; first out) and transmitted whenever possible. + +The protocol layer automatically handles the necessary signaling when the ZW_SendData function is used to initiate a transmission to a FliRS node. + +A bridge controller library MUST NOT send to a virtual node belonging to the bridge itself. + +The following parameters MUST be specified for the SendData function. + +4.3.3.1.1 nodeID parameter The nodeID parameter MUST specify the destination nodeID. + +The nodeID parameter MAY specify the broadcast nodeID (0xFF). + +4.3.3.1.2 *pData parameter The *pData parameter MUST specify a pointer to a data buffer containing a valid Z-Wave command. The data buffer referenced by the *pData parameter MUST contain the number of bytes indicated by the dataLength parameter. + +4.3.3.1.3 dataLength parameter The data buffer referenced by the *pData parameter is used to hold a valid Z-Wave command. The dataLength parameter MUST specify the length of the Z-Wave command. + +4.3.3.1.4 txOptions parameter The calling application MUST compose the txOptions parameter value by combining relevant options chosen from the table below. + +One or more callbacks to the completedFunc pointer indicate the status of the operation. + +The TRANSMIT_OPTION_ACK option SHOULD be used to request that an acknowledgement is returned by the destination node. If the TRANSMIT_OPTION_ACK transmit option is specified, the protocol layer monitors the arrival of the acknowledgement frame. Up to two retransmissions may be attempted if no acknowledgement frame is received. The application SHOULD specify the TRANSMIT_OPTION_AUTO_ROUTE option. This will enable mesh routing to destinations which are out of direct range. + +The TRANSMIT_OPTION_NO_ROUTE option MAY be specified to limit the transmission to direct range for special application purposes. + +Table 8. SendData :: txOptions + +| TRANSMIT OPTION _ _ | Description | Priority | +| --- | --- | --- | +| ACK | Request acknowledged transmission. | If ACK is disabled (0), all other options are ignored by the SendData function | +| NO ROUTE _ | Request acknowledged transmission and explicitly disable routing. | ACK MUST be enabled (1) | +| AUTO ROUTE _ | Request acknowledged transmission and allow routing. If TRANSMIT OPTION AUTO ROUTE == _ _ _ 0, only the Last Working Route is used for routing if direct range transmission fails. If TRANSMIT OPTION AUTO ROUTE == _ _ _ 1, routed transmission uses the Last Working Route and routing table if direct range transmission fails | ACK MUST be enabled (1) NO ROUTE MUST be _ disabled (0) | +| EXPLORE | Request acknowledged transmission and allow routing. Allow dynamic route resolution if Last Working Route, routing table and direct range transmission fails. | ACK MUST be enabled (1) NO ROUTE MUST be _ disabled (0) AUTO ROUTE SHOULD be _ enabled (1) | + +If the broadcast nodeID (0xFF) is specified, the txOptions parameter SHOULD carry the following option values + + TRANSMIT_OPTION_ACK = 0  TRANSMIT_OPTION_NO_ROUTE = 1  TRANSMIT_OPTION_AUTO_ROUTE = 0  TRANSMIT_OPTION_EXPLORE = 0 Table 9. Use of Transmit Options for Controller Libraries + +| TRANSMIT OPTION | | | Protocol behaviour | +| --- | --- | --- | --- | +| NO ROUTE _ | _ ACK | _ AUTO ROUTE _ | | +| 1 | 0 | (ignore) | Transmit frame with no routing, nor retransmission; just as if it was a broadcast frame. | +| 1 | 1 | (ignore) | Frame will be transmitted with direct communication i.e., no routing regardless whether a APR or a LWR exist or not. | +| 0 | 1 | 0 | In case direct transmission fails, the frame will be transmitted using LWR if one exists to the destination in question. | +| 0 | 1 | 1 | If direct communication fails, then attempt with LWR. If LWR also fails or simply do not exist to the destination, then routes from the routing table will be used. | + +4.3.3.1.4.1 TRANSMIT_OPTION_ACK The transmit option TRANSMIT_OPTION_ACK MAY be used to request the destination node to return a transfer acknowledgement. The Z-Wave protocol layer will retry the transmission if no acknowledgement is received. + +The transmit option TRANSMIT_OPTION_ACK SHOULD be specified for all normal application communication. + +If the nodeID parameter specifies the broadcast nodeID (0xFF), the Z-Wave protocol layer ignores the transmit option TRANSMIT_OPTION_ACK. + +4.3.3.1.4.2 TRANSMIT_OPTION_NO_ROUTE The transmit option TRANSMIT_OPTION_NO_ROUTE MAY be used to force the protocol to send the frame without routing. All available routing information is ignored. + +The transmit option TRANSMIT_OPTION_NO_ROUTE SHOULD NOT be specified for normal application communication. + +If the nodeID parameter specifies the broadcast nodeID (0xFF), the Z-Wave protocol layer ignores the transmit option TRANSMIT_OPTION_NO_ROUTE. + +4.3.3.1.4.3 TRANSMIT_OPTION_AUTO_ROUTE The transmit option TRANSMIT_OPTION_AUTO_ROUTE MAY be used to enable routing. + +The Z-Wave protocol layer will then try transmitting the frame via repeater nodes in case destination node is out of direct range. + +Controller nodes MAY use the TRANSMIT_OPTION_AUTO_ROUTE to enable routing via Last Working Routes, calculated routes and routes discovered via dynamic route resolution. + +Routing Slave and Enhanced 232 Slave nodes MAY use the TRANSMIT_OPTION_AUTO_ROUTE to enable routing via return routes for the actual destination nodeID (if any exist). If the nodeID parameter specifies the broadcast nodeID (0xFF), the Z-Wave protocol layer ignores the transmit option TRANSMIT_OPTION_AUTO_ROUTE. + +4.3.3.1.4.4 TRANSMIT_OPTION_EXPLORE The transmit option TRANSMIT_OPTION_EXPLORE MAY be used to enable dynamic route resolution. Dynamic route resolution allows a node to discover new routes if all known routes are failing. An explorer frame cannot wake up FLiRS nodes. + +An explorer frame uses normal RF power level minus 6dB. This is also the power level used by a node finding its neighbors. + +The API function ZW_SetRoutingMAX MAY be used to specify the maximum number of routing attempts based on routing table lookups to use before the Z-Wave protocol layer resorts to dynamic route resolution. A default value of five routing attempts SHOULD be used. + +For backwards compatibility reasons, transmissions to nodes which do not support dynamic route resolution will ignore the transmit option flag TRANSMIT_OPTION_EXPLORE. + +4.3.3.1.4.5 TRANSMIT_OPTION_LOW_POWER The TRANSMIT_OPTION_LOW_POWER option should only be used when the two nodes that are communicating are close to each other (<2 meter). In all other cases, this option SHOULD NOT be used. + +4.3.3.1.4.6 completedFunc The completedFunc parameter MUST specify the calling address of a function that can be called when the SendData frame transmission completes. Completion includes a range of possible situations: + + Direct range frame was successfully transmitted (as requested) without acknowledgement  Direct range frame was successfully acknowledged  Routed frame was successfully acknowledged + +The transmit status txStatus indicates how the transmission operation was completed. + +Table 10. txStatus Values + +| txStatus | Description | +| --- | --- | +| TRANSMIT COMPLETE OK _ _ | The operation was successful. | +| TRANSMIT COMPLETE NO ACK _ _ _ | No acknowledgement was received from the destination node. | +| TRANSMIT COMPLETE FAIL _ _ | Indicates that the network is busy (jammed). | + +WARNING: Allways use the completeFunc callback to determine when the next frame can be send. Calling the ZW_SendData or ZW_SendDataMulti in a loop without checking the completeFunc callback will overflow the transmit queue and eventually fail. The data buffer in the application must not be changed before completeFunc callback is received because it is only the pointer there is passed to the transmit queue. + +4.3.3.1.5 Payload size The maximum size of a frame is 64 bytes. The protocol header and checksum takes 10 bytes in a single cast or broadcast frame leaving 54 bytes for the payload. A S0 security enabled single cast takes 20 bytes as overhead. The maximum dataLength field depends on the transmit options and whether a non- secure/secure frame is used. + +Table 11. Maximum Payload Size + +| Transmit option | Maximum dataLength | | +| --- | --- | --- | +| Notice: Always use lowest maximum dataLength depending on options used. | Non-secure | Secure | +| TRANSMIT OPTION EXPLORE _ _ | 46 bytes | 26 bytes | +| TRANSMIT OPTION AUTO ROUTE _ _ _ | 48 bytes | 28 bytes | +| TRANSMIT OPTION NO ROUTE _ _ _ | 54 bytes | 34 bytes | + +4.3.3.1.6 Embedded API function prototypes + +Defined in: ZW_transport_api.h + +Return value: + +BYTE FALSE If transmits queue overflow + +Parameters: + +nodeID IN Destination node ID The frame will also be transmitted in case (NODE_BROADCAST == all nodes) the source node ID is equal destination node ID + +pData IN Data buffer pointer + +dataLength IN Data buffer length The maximum dataLength field depends on the transmit options and whether a [non-secure/secure frame is used. For details, see section 3.4. The payload](../../../03-z-wave-software-architecture/03.04-z-wave-routing-principles.md#34-z-wave-routing-principles) must be minimum one byte. txOptions IN Transmit option flags: + +TRANSMIT_OPTION_LOW_POWER Transmit at low output power level (1/3 of normal RF range). + +TRANSMIT_OPTION_NO_ROUTE Only send this frame directly, even if a response route exist + +TRANSMIT_OPTION_ACK Request acknowledge from destination node. + +TRANSMIT_OPTION_AUTO_ROUTE Controllers: Request retransmission via repeater nodes (at normal output power level). Number of max routes can be set using ZW_SetRoutingMax + +Routing and Enhanced 232 Slaves: Send the frame to nodeID using the return routes assigned for nodeID to the routing/enhanced 232 slave, if no routes are valid then transmit directly to nodeID (if nodeID = NODE_BROADCAST then the frame will be a BROADCAST). If return routes exists and the nodeID = NODE_BROADCAST then the frame will be transmitted to all assigned return route destinations. If nodeID != NODE_BROADCAST then the frame will be transmitted via the assigned return routes for nodeID. + +TRANSMIT_OPTION_EXPLORE Transmit frame as an explore frame if everything else fails. + +completedFunc Transmit completed call back function Callback function Parameters: + +txStatus Transmit completion status: + +TRANSMIT_COMPLETE_OK Successfully + +TRANSMIT_COMPLETE_NO_ACK No acknowledge is received before timeout from the destination node. Acknowledge is discarded in case it is received after the timeout. + +TRANSMIT_COMPLETE_FAIL Not possible to transmit data because the Z-Wave network is busy (jammed). + +txStatusReport typedef struct _TX_STATUS_TYPE_ + +{ WORD wTransmitTicks; Passed 10ms ticks + +BYTE bRepeaters; Repeaters in route + +struct rssi_dBm rssi_values; [Rssi value for each hop (see Table 7).](../04.03.02-z-wave-basis-api/04.03.02.03-zw_getbackgroundrssi.md#4323-zw_getbackgroundrssi) BYTE bACKChannelNo; Channel ack was received on BYTE bLastTxChannelNo; Channel frame was send on E_ROUTING_SCHEME bRouteSchemeState; The last used routing scheme + +BYTE pLastUsedRoute[LAST_USED_ROUTE_SIZE]; Last used route (5 byte array) BYTE bRouteTries; Routing attempts S_ROUTE_LINK bLastFailedLink; Last route that failed } TX_STATUS_TYPE; Timeout: 65s. This is a worst case scenario that happens very seldom. The ZW_SendData call typically returns a callback. + +Exception recovery: If a timeout occurs, it is important to call ZW_SendDataAbort to stop the sending of the frame. + +![Figure 9. Application State Machine for ZW_SendData](assets/img-13f50a1628.png) + +Table 12. ZW_SendData : State/Event Processing + +![figure p110](assets/img-b9bf4cd14c.png) + +4.3.3.1.7 Serial API function prototypes + +HOST->ZW: REQ | 0x13 | nodeID | dataLength | pData[ ] | txOptions | funcID + +ZW->HOST: RES | 0x13 | RetVal + +If either (funcID == 0) OR (RetVal == FALSE) -> no callback + +If (funcID != 0) AND (RetVal == TRUE) then callback returns with: + +ZW->HOST: REQ | 0x13 | funcID | txStatus + +SerialAPI targets supporting IMA + +The Devkit 6.60.00 adds a txStatusReport structure to the ZW_SendData callback parameter and this have been introduced into the IMA supporting SerialAPI targets by extending the number of parameters in the ZW_SendData callback parameter list. + +HOST->ZW: REQ | 0x13 | nodeID | dataLength | pData[ ] | txOptions | funcID + +ZW->HOST: RES | 0x13 | RetVal + +If either (funcID == 0) OR (RetVal == FALSE) -> no callback + +If (funcID != 0) AND (RetVal == TRUE) then callback returns with: + +ZW->HOST: REQ | 0x13 | funcID | txStatus | wTransmitTicksMSB | wTransmitTicksLSB | bRepeaters | rssi_values.incoming[0] | rssi_values.incoming[1] | rssi_values.incoming[2] | rssi_values.incoming[3] | rssi_values.incoming[4] | bACKChannelNo | bLastTxChannelNo | bRouteSchemeState | repeater0 | repeater1 | repeater2 | repeater3 | routespeed | bRouteTries | bLastFailedLink.from | bLastFailedLink.to + +The SerialAPI command FUNC_ID_SERIAL_API_SETUP (0x0B) has been added to enable/disable the transmission of the txStatusReport structure to HOST on ZW_SendData callback. + +Notice: For IMA enabled targets the transmission of txStatusReport to HOST is ENABLED at module startup. For NON IMA enabled targets the transmission of txStatusReport to HOST is DISABLED at module startup. + +HOST->ZW: REQ | 0x0B | 0x02 | bEnable + +ZW->HOST: RES | 0x0B | 0x02 | RetVal + +bEnable = 1 -> ENABLE txStatusReport transmission to HOST on ZW_SendData callback. bEnable = 0 -> DISABLE txStatusReport transmission to HOST on ZW_SendData callback. RetVal = 1 -> Operation executed successfully. RetVal = 0 -> Operation executed unsuccessfully. + +Notice: Serial API version is unchanged despite changed format in ZW-SendData for this particular application. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.02-zw_senddataex-only-slave-libraries.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.02-zw_senddataex-only-slave-libraries.md new file mode 100644 index 0000000..563e55f --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.02-zw_senddataex-only-slave-libraries.md @@ -0,0 +1,151 @@ + +# 4.3.3.2 ZW_SendDataEx (only Slave Libraries) + +ZW_SENDDATA_EX_RETURN_CODES ZW_SendDataEx(BYTE *pData, BYTE dataLength, TRANSMIT_OPTIONS_TYPE * pTxOptionsEx, VOID_CALLBACKFUNC(completedFunc)(BYTE txStatus, TX_STATUS_TYPE* txStatusReport )) + +NOTE: Only supported by the Enhanced 232 and Routing Slave libraries. All Controller libraries based applications must use ZW_SendData. + +NOTE: Broadcast are only allowed unsecure. + +This function MAY be used to transmit either unsecure or secure (S0, S2) contents of specified data buffer to a single node or all nodes (broadcast). The data buffer is optionally security encapsulated and then encapsulated in a Z-Wave transport frame by adding a protocol header and a checksum trailer. The frame is appended to the end of the transmit queue (first in; first out) and transmitted whenever possible. + +The protocol layer automatically handles the necessary signaling when the ZW_SendDataEx function is used to initiate a transmission to a FliRS node. + +The following parameters MUST be specified for the SendDataEx function. + +4.3.3.2.1 *pData parameter The *pData parameter MUST specify a pointer to a data buffer containing a valid Z-Wave command. The data buffer referenced by the *pData parameter MUST contain the number of bytes indicated by the dataLength parameter. + +4.3.3.2.2 dataLength parameter The data buffer referenced by the *pData parameter is used to hold a valid Z-Wave command. The dataLength parameter MUST specify the length of the Z-Wave command. + +4.3.3.2.3 pTxOptionsEx parameter The calling application MUST fill the application TRANSMIT_OPTIONS_TYPE structure the pTxOptionsEx parameter referes to by setting relevant TRANSMIT_OPTIONS_TYPE members: + +4.3.3.2.3.1 destNode Destination node for the specified payload data. + +4.3.3.2.3.2 bSrcNode Reserved for future use. + +4.3.3.2.3.3 txOptions [See ZW_Sendata txOptions parameter description (4.3.3.1.4)](04.03.03.01-zw_senddata.md#4331-zw_senddata) + +4.3.3.2.3.4 txSecOptions Options for enabling specific Security S2 funtionality. + +4.3.3.2.3.5 securityKey Security key to use for sending. + +4.3.3.2.3.6 txOptions2 Reserved for future use. + +4.3.3.2.4 completedFunc The completedFunc parameter MUST specify the calling address of a function that can be called when the SendData frame transmission completes. Completion includes a range of possible situations: + + Direct range frame was successfully transmitted (as requested) without acknowledgement  Direct range frame was successfully acknowledged  Routed frame was successfully acknowledged + +The transmit status txStatus indicates how the transmission operation was completed. + +Table 13. txStatus values + +| txStatus | Description | +| --- | --- | +| TRANSMIT COMPLETE OK _ _ | The operation was successful. | +| TRANSMIT COMPLETE NO ACK _ _ _ | No acknowledgement was received from the destination node. | +| TRANSMIT COMPLETE FAIL _ _ | Indicates that the network is busy (jammed). | + +WARNING: Allways use the completeFunc callback to determine when the next frame can be send. + +4.3.3.2.5 Payload size The maximum size of a frame is 64 bytes. The protocol header and checksum takes 10 bytes in a single cast or broadcast frame leaving 54 bytes for the payload. A S0 security enabled single cast takes 20 bytes as overhead. The maximum dataLength field depends on the transmit options and whether a non- secure/secure frame is used. + +Table 14. Maximum payload size + +| Transmit option | Maximum dataLength | | | +| --- | --- | --- | --- | +| Notice: Always use lowest maximum dataLength depending on options used. | Non-secure | Security S0 | Security2 | +| TRANSMIT OPTION EXPLORE _ _ | 46 bytes | 26 bytes | 46 bytes | +| TRANSMIT OPTION AUTO ROUTE _ _ _ | 48 bytes | 28 bytes | 46 bytes | +| TRANSMIT OPTION NO ROUTE _ _ _ | 54 bytes | 34 bytes | 46 bytes | + +4.3.3.2.6 Embedded API function prototypes + +Defined in: ZW_transport_api.h + +Return value: + +ZW_SENDDATA_ ZW_TX_FAILED If not queued in transmit queue. No EX_RETURN_ callback will be done. CODES + +ZW_TX_IN_PROGRESS If frame is queued for transmission. + +Parameters: + +txOptionsEx Destination node ID The frame will also be transmitted in.destNode IN (NODE_BROADCAST == all nodes) case the source node ID is equal destination node ID + +pData IN Data buffer pointer + +dataLength IN Data buffer length The maximum dataLength field depends on the transmit options and [whether a non-secure/secure frame is used. For details, see section 3.4.](../../../03-z-wave-software-architecture/03.04-z-wave-routing-principles.md#34-z-wave-routing-principles) The payload must be minimum one byte. txOptionsEx Transmit option flags:.txOptions IN + +TRANSMIT_OPTION_LOW_POWER Transmit at low output power level (1/3 of normal RF range). + +TRANSMIT_OPTION_NO_ROUTE Only send this frame directly, even if a response route exist + +TRANSMIT_OPTION_ACK Request acknowledge from destination node. + +TRANSMIT_OPTION_AUTO_ROUTE Send the frame to nodeID using the return routes assigned for nodeID to the enhanced 232 slave, if no routes are valid then transmit directly to nodeID (if nodeID = NODE_BROADCAST then the frame will be a BROADCAST). If return routes exists and the nodeID = NODE_BROADCAST then the frame will be transmitted to all assigned return route destinations. If nodeID != NODE_BROADCAST then the frame will be transmitted via the assigned return routes for nodeID. + +TRANSMIT_OPTION_EXPLORE Transmit frame as an explore frame if everything else fails. + +txOptionsEx Reserved for future use..bSrcNode IN + +txOptionsEx Security2-specific options.txSecOptions IN + +S2_TXOPTION_VERIFY_DELIVERY This flag will activate frame delivery verification. In this transmission mode ZW_SendDataEx will try to verify that the receiver understood the message sent. This is done by waiting a little to see if the node will respond nonce report to the encrypted message. If the node does respond with a nonce report then the option will automatically cause the system to re- sync the node, and deliver the message. The TRANSMIT_COMPLETE_VERIFIED (0x05) is returned if it could be determined that a successful (Ack received) transmitted S2 encrypted message has been successfully decrypted by destination. The way this can be determined is by the destination returning a decryptable S2 encrypted answer message. A normal TRANSMIT_COMPLETE is returned as callback status if message was transmitted successfully (Ack) but no decryptable S2 encrypted message is returned inside timeout (~250ms). + +An example where this can be seen is in the SUPERVISION COMMAND CLASS + +S2_TXOPTION_SINGLECAST_ This flag must be present on all single FOLLOWUP cast followup messages to a multicast. + +S2_TXOPTION_FIRST_SINGLECAST_ This flag must be present on the first, FOLLOWUP and only the first singlecast followup message in a multicast transmission. + +txOptionsEx Select security key for transmission.securityKey IN + +SECURITY_KEY_NONE Nonsecure transmission + +SECURITY_KEY_S2_ Use S2 Unauthenticated key UNAUTHENTICATED + +SECURITY_KEY_S2_ Use S2 Authenticated key AUTHENTICATED + +SECURITY_KEY_S2_ACCESS Use S2 Access key + +SECURITY_KEY_S0 Use Security Scheme 0 key + +txOptionsEx More transmit option flags..txOptions2 IN Reserved for future use. Must be set to 0x00. + +completedFunc Transmit completed call back function Callback function Parameters: + +txStatus Transmit completion status: + +TRANSMIT_COMPLETE_OK Successfully + +TRANSMIT_COMPLETE_NO_ACK No acknowledge is received before timeout from the destination node. Acknowledge is discarded in case it is received after the timeout. + +TRANSMIT_COMPLETE_FAIL Not possible to transmit data because the Z-Wave network is busy (jammed). + +TRANSMIT_COMPLETE_VERIFIED A S2 encrypted message has been successfully decrypted by destination. + +txStatusReport typedef struct _TX_STATUS_TYPE_ + +{ WORD wTransmitTicks; Passed 10ms ticks + +BYTE bRepeaters; Repeaters in route + +struct rssi_dBm rssi_values; [Rssi value for each hop (see Table 7).](../04.03.02-z-wave-basis-api/04.03.02.03-zw_getbackgroundrssi.md#4323-zw_getbackgroundrssi) BYTE bACKChannelNo; Channel ack was received on BYTE bLastTxChannelNo; Channel frame was send on E_ROUTING_SCHEME bRouteSchemeState; The last used routing scheme + +BYTE pLastUsedRoute[LAST_USED_ROUTE_SIZE]; Last used route (5 byte array) BYTE bRouteTries; Routing attempts S_ROUTE_LINK bLastFailedLink; Last route that failed } TX_STATUS_TYPE; + +4.3.3.2.7 Serial API function prototypes + +HOST->ZW: REQ | 0x0E | nodeID | dataLength | pData[ ] | txOptions | txSecOptions | securityKey | txOptions2 | funcID + +ZW->HOST: RES | 0x0E | RetVal + +If either (funcID == 0) OR (RetVal == FALSE) -> no callback + +If (funcID != 0) AND (RetVal == TRUE) then callback returns with: ZW->HOST: REQ | 0x0E | funcID | txStatus | wTransmitTicksMSB | wTransmitTicksLSB | bRepeaters | rssi_values.incoming[0] | rssi_values.incoming[1] | rssi_values.incoming[2] | rssi_values.incoming[3] | rssi_values.incoming[4] | bACKChannelNo | bLastTxChannelNo | bRouteSchemeState | repeater0 | repeater1 | repeater2 | repeater3 | routespeed | bRouteTries | bLastFailedLink.from | bLastFailedLink.to diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.03-zw_senddata_bridge.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.03-zw_senddata_bridge.md new file mode 100644 index 0000000..005a69a --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.03-zw_senddata_bridge.md @@ -0,0 +1,82 @@ + +# 4.3.3.3 ZW_SendData_Bridge + +BYTE ZW_SendData_Bridge( BYTE srcNodeID, BYTE destNodeID, BYTE *pData, BYTE dataLength, BYTE txOptions, Void (*completedFunc)(BYTE txStatus, TX_STATUS_TYPE* txStatusReport)) + +NOTE: Only supported by the Bridge Controller library. For backward compatibility macros for the Bridge Controller library has been made for ZW_SendData(node,data,length,options,func) and ZW_SEND_DATA(node,data,length,options,func) + +Macro: ZW_SEND_DATA_BRIDGE(srcnodeid, destnodeid, data, length, options, func) + +Transmit the data buffer to a single Z-Wave Node or all Z-Wave Nodes (broadcast). The data buffer is queued to the end of the transmit queue (first in; first out) and when ready for transmission the Z-Wave protocol layer frames the data with a protocol header in front and a checksum at the end. + +The transmit option TRANSMIT_OPTION_ACK requests the destination node to return a transfer acknowledge to ensure proper transmission. The transmitting node will retry the transmission if no acknowledge received. The Controller nodes can add the TRANSMIT_OPTION_AUTO_ROUTE flag to the transmit option parameter. The Controller will then try transmitting the frame via repeater nodes if the direct transmission failed. + +The transmit option TRANSMIT_OPTION_NO_ROUTE force the protocol to send the frame without routing, even if a response route exist. + +To enable dynamic route resolution a new transmit option TRANSMIT_OPTION_EXPLORE must be appended to the well known send API calls. This instruct the protocol to transmit the frame as an explore frame to the destination node if source routing fails. An explore frame uses normal RF power level minus 6dB similar to a node finding neighbors. It is also possible to specify the maximum number of source routing attempts before the explorer frame kicks in using the API call ZW_SetRoutingMAX. Default value is five with respect to maximum number of source routing attempts. When communicating with nodes, which do not support dynamic route resolution the transmit option flag TRANSMIT_OPTION_EXPLORE is ignored. Notice that an explorer frame cannot wake up FLiRS nodes. + +The completedFunc is called when the frame transmission completes, that is when transmitted if ACK is not requested; when acknowledge received from the destination node, or when routed acknowledge completed if the frame was transmitted via one or more repeater nodes. The transmit status TRANSMIT_COMPLETE_NO_ACK indicate that no acknowledge is received from the destination node. The transmit status TRANSMIT_COMPLETE_FAIL indicate that the Z-Wave network is busy (jammed). + +The TRANSMIT_OPTION_LOW_POWER option should only be used when the two nodes that are communicating are close to each other (<2 meter). In all other cases this option should not be used. + +NOTE: Always use the completeFunc callback to determine when the transmit is done. The completeFunc should flag the application state machine that the transmit has been done and next state/action can be started. A frame transmit should always be started through the application state machine in order to be sure that the transmit buffer is ready for sending next frame. Calling the ZW_SendData_Bridge in a loop without using the completeFunc callback will overflow the transmit queue and eventually fail. The payload data buffer in the application must not be changed before completeFunc callback is received because it is only the pointer that is passed to the transmit queue. Defined in: ZW_transport_api.h + +Return value: + +BYTE FALSE If transmit queue overflow + +Parameters: + +srcNodeID IN Source node ID. Valid values: + +NODE_BROADCAST = Bridge Controller NodeID. + +Bridge Controller NodeID. + +Virtual Slave NodeID (only existing Virtual Slave NodeIDs). + +destNodeID IN Destination node ID The frame will also be transmitted in case (NODE_BROADCAST == all nodes) the source node ID is equal destination node ID + +pData IN Data buffer pointer + +dataLength IN Data buffer length The maximum dataLength field depends on the transmit options and whether a non-secure/secure frame is used. The payload must be minimum one byte. + +txOptions IN Transmit option flags: + +TRANSMIT_OPTION_LOW_POWER Transmit at low output power level (1/3 of normal RF range). + +TRANSMIT_OPTION_NO_ROUTE Only send this frame directly, even if a response route exist + +TRANSMIT_OPTION_EXPLORE Transmit frame as an Explore frame if all else fails + +TRANSMIT_OPTION_ACK Request acknowledge from destination node. + +TRANSMIT_OPTION_AUTO_ROUTE Request retransmission via repeater nodes (at normal output power level). + +completedFunc Transmit completed call back function Callback function Parameters: + +txStatus Transmit completion status: + +TRANSMIT_COMPLETE_OK Successfully + +TRANSMIT_COMPLETE_NO_ACK No acknowledge is received before timeout from the destination node. Acknowledge is discarded in case it is received after the timeout. + +TRANSMIT_COMPLETE_FAIL Not possible to transmit data because the Z-Wave network is busy (jammed). + +txStatusReport See ZW_SendData + +Serial API: + +HOST->ZW: REQ | 0xA9 | srcNodeID | destNodeID | dataLength | pData[ ] | txOptions | pRoute[4] | funcID + +Devkit 6.x+ -> pRoute[4] not used – use pRoute[4] = {0, 0, 0, 0} + +ZW->HOST: RES | 0xA9 | RetVal + +ZW->HOST: REQ | 0xA9 | funcID | txStatus | wTransmitTicksMSB | wTransmitTicksLSB | bRepeaters | rssi_values.incoming[0] | rssi_values.incoming[1] | rssi_values.incoming[2] | rssi_values.incoming[3] | rssi_values.incoming[4] | bAckChannelNo | | bLastTxChannelNo | bRouteSchemeState | repeater0 | repeater1 | repeater2 | repeater3 | routespeed | bRouteTries | bLastFailedLink.from | bLastFailedLink.to diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.04-zw_senddatamulti.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.04-zw_senddatamulti.md new file mode 100644 index 0000000..16f2959 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.04-zw_senddatamulti.md @@ -0,0 +1,58 @@ + +# 4.3.3.4 ZW_SendDataMulti + +BYTE ZW_SendDataMulti(BYTE *pNodeIDList, BYTE *pData, BYTE dataLength, BYTE txOptions, Void (*completedFunc)(BYTE txStatus)) + +Macro: ZW_SEND_DATA_MULTI(nodelist,data,length,options,func) + +NOTE: This function is not available in the Bridge Controller library (See ZW_SendDataMulti_Bridge). + +Transmit the data buffer to a list of Z-Wave Nodes (multicast frame). If the transmit optionflag TRANSMIT_OPTION_ACK is set the data buffer is also sent as a singlecast frame to each of the Z-Wave Nodes in the node list. + +The completedFunc is called when the frame transmission completes in the case that ACK is not requested; When TRANSMIT_OPTION_ACK is requested the callback function is called when all single casts have been transmitted and acknowledged. + +The transmit status TRANSMIT_COMPLETE_NO_ACK indicate that no acknowledge is received from the destination node. The transmit status TRANSMIT_COMPLETE_FAIL indicate that the Z-Wave network is busy (jammed). The data pointed to by pNodeIDList should not be changed before the callback is called. + +NOTE: Allways use the completeFunc callback to determine when the next frame can be send. Calling the ZW_SendData or ZW_SendDataMulti in a loop without checking the completeFunc callback will overflow the transmit queue and eventually fail. The data buffer in the application must not be changed before completeFunc callback is received because it is only the pointer there is passed to the transmit queue. + +Defined in: ZW_transport_api.h + +Return value: + +BYTE FALSE If transmit queue overflow Parameters: + +pNodeIDList IN List of destination node ID's This is a fixed length bit-mask. + +Pdata IN Data buffer pointer + +DataLength IN Data buffer length The maximum size of a packet is 64 bytes. The protocol header, multicast addresses and checksum takes 39 bytes in a multicast frame leaving 25 bytes for the payload. The payload must be minimum one byte. + +TxOptions IN Transmit option flags: + +TRANSMIT_OPTION_LOW_POWER Transmit at low output power level (1/3 of normal RF range). + +TRANSMIT_OPTION_EXPLORE If TRANSMIT_OPTION_ACK is set the will make the node try sending as an Explore frame if all else fails when doing the single cast transmits + +TRANSMIT_OPTION_ACK The multicast frame will be followed by a number of single cast frames to each of the destination nodes and request acknowledge from each destination node. + +TRANSMIT_OPTION_AUTO_ROUTE Request retransmission on single cast (Controller API only) frames via repeater nodes (at normal output power level) + +completedFunc Transmit completed call back function + +Callback function Parameters: + +txStatus IN (see ZW_SendData) + +Serial API: + +HOST->ZW: REQ | 0x14 | numberNodes | pNodeIDList[ ] | dataLength | pData[ ] | txOptions | funcID + +ZW->HOST: RES | 0x14 | RetVal + +ZW->HOST: REQ | 0x14 | funcID | txStatus diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.05-zw_senddatamultiex-only-slave-libraries.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.05-zw_senddatamultiex-only-slave-libraries.md new file mode 100644 index 0000000..a2e47c2 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.05-zw_senddatamultiex-only-slave-libraries.md @@ -0,0 +1,64 @@ + +# 4.3.3.5 ZW_SendDataMultiEx (only Slave Libraries) + +ZW_SENDDATA_EX_RETURN_CODES ZW_SendDataMultiEx(BYTE *pData, BYTE dataLength, TRANSMIT_MULTI_OPTIONS_TYPE *pTxOptionsMultiEx, Void (*completedFunc)(BYTE txStatus)) + +NOTE: Only supported by the Enhanced 232 and Routing Slave libraries. + +Transmit the data buffer using S2 multicast to a list of Z-Wave Nodes. Only the multicast frame is transmitted, if singlecast frames are needed then application needs to do this using ZW_SendDataEx for every node in the group. + +NOTE: Can only be called successfully if node is S2 included and txOptionsEx.securityKey is set to a supported S2 key. + +The completedFunc is called when the frame transmission completes. + +The transmit status TRANSMIT_COMPLETE_FAIL indicate that the Z-Wave network is busy (jammed). + +NOTE: Allways use the completeFunc callback to determine when the next frame can be send. Trying to transmit in a loop without checking the completeFunc callback will overflow the transmit queue and eventually fail. + +Defined in: ZW_transport_api.h + +Return value: + +ZW_SENDDATA_EX_RETURN_CODES ZW_TX_FAILED If not queued in transmit queue. No callback will be done. + +ZW_TX_IN_PROGRESS If frame is queued for transmission. Parameters: + +txOptionsMultiEx Destination groupID Group which is to.groupID IN receive the S2 Multicast frame + +pData IN Data buffer pointer + +dataLength IN Data buffer length The maximum dataLength field depends on the transmit options and whether a non-secure/secure frame [is used. For details, see section 3.4. The payload](../../../03-z-wave-software-architecture/03.04-z-wave-routing-principles.md#34-z-wave-routing-principles) must be minimum one byte. + +txOptionsMultiEx Reserved to future use..txOptions IN + +txOptionsEx Select security key for transmission.securityKey IN + +SECURITY_KEY_S2_UNAUTHENTICATED Use S2 Unauthenticated key + +SECURITY_KEY_S2_AUTHENTICATED Use S2 Authenticated key + +SECURITY_KEY_S2_ACCESS Use S2 Access key + +completedFunc Transmit completed call back function + +Callback function Parameters: + +txStatus IN (see ZW_SendData) + +Serial API: + +HOST->ZW: REQ | 0x0F | dataLength | pData[ ] | txOptions | securityKey | groupID | funcID + +ZW->HOST: RES | 0x0F | RetVal + +If either (funcID == 0) OR (RetVal == FALSE) -> no callback + +If (funcID != 0) AND (RetVal == TRUE) then callback returns with: + +ZW->HOST: REQ | 0x0F | funcID | txStatus diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.06-zw_senddatamulti_bridge.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.06-zw_senddatamulti_bridge.md new file mode 100644 index 0000000..e4ec0db --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.06-zw_senddatamulti_bridge.md @@ -0,0 +1,64 @@ + +# 4.3.3.6 ZW_SendDataMulti_Bridge + +BYTE ZW_SendDataMulti_Bridge(BYTE srcNodeID, BYTE *pNodeIDList, BYTE *pData, BYTE dataLength, BYTE txOptions, Void (*completedFunc)(BYTE txStatus)) + +Macro: ZW_SEND_DATA_MULTI_BRIDGE(srcnodid,nodelist,data,length,options,func) + +NOTE: This function is only available in the Bridge Controller library. + +Transmit the data buffer to a list of Z-Wave Nodes (multicast frame). If the transmit optionflag TRANSMIT_OPTION_ACK is set the data buffer is also sent as a singlecast frame to each of the Z-Wave Nodes in the node list. + +The completedFunc is called when the frame transmission completes in the case that ACK is not requested; When TRANSMIT_OPTION_ACK is requested the callback function is called when all single casts have been transmitted and acknowledged. + +The transmit status TRANSMIT_COMPLETE_NO_ACK indicate that no acknowledge is received from the destination node. The transmit status TRANSMIT_COMPLETE_FAIL indicate that the Z-Wave network is busy (jammed). The data pointed to by pNodeIDList should not be changed before the callback is called. + +NOTE: Allways use the completeFunc callback to determine when the next frame can be send. Calling the ZW_SendData_Bridge or ZW_SendDataMulti_Bridge in a loop without checking the completeFunc callback will overflow the transmit queue and eventually fail. The data buffer in the application must not be changed before completeFunc callback is received because it’s only the pointer there is passed to the transmit queue. + +Defined in: ZW_transport_api.h + +Return value: + +BYTE FALSE If transmit queue overflow Parameters: + +srcNodeID IN Source node ID. Valid values: + +NODE_BROADCAST = Bridge Controller NodeID. + +Bridge Controller NodeID. + +Virtual Slave NodeID (only existing Virtual Slave NodeIDs). + +pNodeIDList IN List of destination node ID's This is a fixed length bit-mask. + +Pdata IN Data buffer pointer + +DataLength IN Data buffer length The maximum size of a packet is 64 bytes. The protocol header, multicast addresses and checksum takes 39 bytes in a multicast frame leaving 25 bytes for the payload. In case routed single casts follow multicast the source routing info takes up to 6 bytes depending on the number of hops leaving minimum 19 bytes for the payload. In case it is a singlecast, which piggyback on an explorer frame overhead is 8 bytes leaving minimum 17 bytes for the payload. The payload must be minimum one byte. + +TxOptions IN Transmit option flags: + +TRANSMIT_OPTION_LOW_POWER Transmit at low output power level (1/3 of normal RF range). + +TRANSMIT_OPTION_EXPLORE If TRANSMIT_OPTION_ACK is set the will make the node try sending as an Explore frame if all else fails when doing the single cast transmits + +TRANSMIT_OPTION_ACK The multicast frame will be followed by a number of single cast frames to each of the destination nodes and request acknowledge from each destination node. + +TRANSMIT_OPTION_AUTO_ROUTE Request retransmission on single cast frames via repeater nodes (at normal output power level) + +completedFunc Transmit completed call back function + +Callback function Parameters: + +txStatus IN (see ZW_SendData) Serial API: + +HOST->ZW: REQ | 0xAB | srcNodeID | numberNodes | pNodeIDList[ ] | dataLength | pData[ ] | txOptions | funcID + +ZW->HOST: RES | 0xAB | RetVal + +ZW->HOST: REQ | 0xAB | funcID | txStatus diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.07-zw_senddataabort.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.07-zw_senddataabort.md new file mode 100644 index 0000000..8ccfe95 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.07-zw_senddataabort.md @@ -0,0 +1,20 @@ + +# 4.3.3.7 ZW_SendDataAbort + +void ZW_SendDataAbort( void ) + +Macro: ZW_SEND_DATA_ABORT + +Abort the ongoing transmit started with ZW_SendData() or ZW_SendDataMulti(). If an ongoing transmission is aborted, the callback function from the send call will return with the status TRANSMIT_COMPLETE_NO_ACK. + +Defined in: ZW_transport_api.h + +Serial API: + +HOST->ZW: REQ | 0x16 diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.08-zw_lockroute-only-controllers.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.08-zw_lockroute-only-controllers.md new file mode 100644 index 0000000..9be292b --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.08-zw_lockroute-only-controllers.md @@ -0,0 +1,24 @@ + +# 4.3.3.8 ZW_LockRoute (only Controllers) + +void ZW_LockRoute( bLockRoute ) + +Macro: ZW_LOCK_ROUTE + +This function locks and unlocks all last working routes (LWR) for purging. + +Defined in: ZW_transport_api.h + +Parameters: + +bLockRoute IN Lock and unlocks all LWR TRUE lock all LWR – no purging allowed. FALSE unlock purging of LWR + +Serial API + +HOST->ZW: REQ | 0x90 | bLockRoute diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.09-zw_lockroute-only-slaves.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.09-zw_lockroute-only-slaves.md new file mode 100644 index 0000000..2d1dfac --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.09-zw_lockroute-only-slaves.md @@ -0,0 +1,24 @@ + +# 4.3.3.9 ZW_LockRoute (only Slaves) + +void ZW_LockRoute( node ) + +Macro: ZW_LOCK_ROUTE + +This function locks and unlocks response route for a given node ID. + +Defined in: ZW_transport_api.h + +Parameters: + +node IN Lock and unlocks response node = 1..232 lock response route for the specified route for a given node ID node ID. node = 0 unlock response route. + +Serial API + +HOST->ZW: REQ | 0x90 | node diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.10-zw_sendconst.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.10-zw_sendconst.md new file mode 100644 index 0000000..fe60305 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.10-zw_sendconst.md @@ -0,0 +1,30 @@ + +# 4.3.3.10 ZW_SendConst + +void ZW_SendConst(BYTE bStart, BYTE bChNo, BYTE bSignalType ) + +This function start/stop generating RF test signal. The test signal can be on of the following: + + Test signal with only the carrier frequency.  Test signal with a modulated carrier frequency; the signal will switch between sending logical 1 frequency and logical zero frequency The function also selects which channel to send the test signal on. + +This API call can only be called in production test mode from ApplicationTestPoll. + +The API should only be called when starting\stopping a test. + +Defined in: ZW_transport_api.h + +Parameters: + +bStart IN Start/Stop generating RF test TRUE start sending RF test signal. signal FALSE stop sending RF test signal + +bChNot IN The number of channel to 0..1 for 2 channels targets send the test signal on. 0..2 for 3 channels targets + +bSignalType IN type of the RF test signal to ZW_RF_TEST_SIGNAL_CARRIER generater ZW_RF_TEST_SIGNAL_CARRIER_MODULATED + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.11-zw_setlistenbeforetalkthreshold.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.11-zw_setlistenbeforetalkthreshold.md new file mode 100644 index 0000000..3b5fcdd --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.11-zw_setlistenbeforetalkthreshold.md @@ -0,0 +1,34 @@ + +# 4.3.3.11 ZW_SetListenBeforeTalkThreshold + +void ZW_SetListenBeforeTalkThreshold(BYTE bChannel, BYTE bThreshold ) + +This function sets the “Listen Before Talk” threshold that controlles at what RSSI level a Z-Wave node will refuse to transmit because of noise. The default threshold value is set to a value corresponding to the RF regulatory requirements for a Z-Wave module in the specific country. The appropriate value range goes from 34(dec) to 78(dec) and each threshold step corresponds to a 1.5dB input power step. + +| Region | Default Threshold (dec) | dBm | +| --- | --- | --- | +| JP | 50 | -80 | +| KR | 64 | -65 | +| EU, US, HK, ANZ, CN, IL, IN, MY & RU | 64 | -65 | + +For instance, if a SAW filter with an insertion loss of 3dB is inserted between the antenna feed-point and the chip on a JP product, the threshold value should be set to 48(dec) . + +NOTICE: In some contries (JP and KR) the value of the LBT threshold is specified in the RF regulatory for the country and must be set to the value corresponding to the regulatory requirements. + +Parameters: + +bChannel IN Channel number the Threshold should be set for. Valid channel numbers are 0,1 and 2 + +bThreshold IN The threshold the RSSI should use. Valid threshold range is from 34(dec) to 78(dec). + +Defined in: ZW_transport_api.h + +Serial API + +HOST->ZW: REQ | 0x3C | bChannel | bThreshold ZW->HOST: RES | 0x3C | TRUE diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.12-zw_transport_commandclassversionget.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.12-zw_transport_commandclassversionget.md new file mode 100644 index 0000000..54ebf1e --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.12-zw_transport_commandclassversionget.md @@ -0,0 +1,26 @@ + +# 4.3.3.12 ZW_Transport_CommandClassVersionGet + +BYTE ZW_CommandClassVersionGet(BYTE commandClass) + +This function is used to determine the version of the Command Classes handled by the Z-Wave protocol. SHOULD be used as a default case when receiving VERSION GET for Command Class not supported by Application. + +Defined in: ZW_transport_api.h + +Return value: + +BYTE 1.. Command Class Version of the Z- Wave protocol handled commandClass. + +Specified Command Class not handled UNKNOWN_VERSION by the Z-Wave protocol. + +Parameters: + +commandClass IN BYTE Command Class ID for whom Version is needed. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.13-zw_getdefaultpowerlevels.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.13-zw_getdefaultpowerlevels.md new file mode 100644 index 0000000..edec650 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.13-zw_getdefaultpowerlevels.md @@ -0,0 +1,16 @@ + +# 4.3.3.13 ZW_GetDefaultPowerLevels + +BYTE ZW_GetDefaultPowerLevels(BYTE *pPowerLevels) + +This API call is reserved for serial API binaries delivered by Silicon Labs. + +Defined in: ZW_basis_api.h + +Serial API [(Not supported, see SERIAL_API_SETUP_CMD_TX_POWERLEVEL_GET in [2])](../../../08-references.md#8-references) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.14-zw_setdefaultpowerlevels.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.14-zw_setdefaultpowerlevels.md new file mode 100644 index 0000000..70681d3 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.14-zw_setdefaultpowerlevels.md @@ -0,0 +1,16 @@ + +# 4.3.3.14 ZW_SetDefaultPowerLevels + +BYTE ZW_SetDefaultPowerLevels(BYTE bNormalPower0, BYTE bNormalPower1, BYTE bNormalPower2, BYTE bLowPower0, BYTE bLowPower1, BYTE bLowPower2) + +This API call is reserved for serial API binaries delivered by Silicon Labs. + +Defined in: ZW_basis_api.h + +Serial API [(Not supported, see SERIAL_API_SETUP_CMD_TX_POWERLEVEL_SET in [2])](../../../08-references.md#8-references) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/index.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/index.md new file mode 100644 index 0000000..89d2fa1 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.03-z-wave-transport-api/index.md @@ -0,0 +1,27 @@ + +# 4.3.3 Z-Wave Transport API + +The Z-Wave transport layer controls transfer of data between Z-Wave nodes including retransmission, frame check and acknowledgement. The Z-Wave transport interface includes functions for transfer of data to other Z-Wave nodes. Application data received from other nodes is handed over to the application via the ApplicationCommandHandler function. The ZW_MAX_NODES define defines the maximum of nodes possible in a Z-Wave network. + +## Contents + +- [4.3.3.1 ZW_SendData](04.03.03.01-zw_senddata.md) +- [4.3.3.2 ZW_SendDataEx (only Slave Libraries)](04.03.03.02-zw_senddataex-only-slave-libraries.md) +- [4.3.3.3 ZW_SendData_Bridge](04.03.03.03-zw_senddata_bridge.md) +- [4.3.3.4 ZW_SendDataMulti](04.03.03.04-zw_senddatamulti.md) +- [4.3.3.5 ZW_SendDataMultiEx (only Slave Libraries)](04.03.03.05-zw_senddatamultiex-only-slave-libraries.md) +- [4.3.3.6 ZW_SendDataMulti_Bridge](04.03.03.06-zw_senddatamulti_bridge.md) +- [4.3.3.7 ZW_SendDataAbort](04.03.03.07-zw_senddataabort.md) +- [4.3.3.8 ZW_LockRoute (only Controllers)](04.03.03.08-zw_lockroute-only-controllers.md) +- [4.3.3.9 ZW_LockRoute (only Slaves)](04.03.03.09-zw_lockroute-only-slaves.md) +- [4.3.3.10 ZW_SendConst](04.03.03.10-zw_sendconst.md) +- [4.3.3.11 ZW_SetListenBeforeTalkThreshold](04.03.03.11-zw_setlistenbeforetalkthreshold.md) +- [4.3.3.12 ZW_Transport_CommandClassVersionGet](04.03.03.12-zw_transport_commandclassversionget.md) +- [4.3.3.13 ZW_GetDefaultPowerLevels](04.03.03.13-zw_getdefaultpowerlevels.md) +- [4.3.3.14 ZW_SetDefaultPowerLevels](04.03.03.14-zw_setdefaultpowerlevels.md) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.04-zwave-firmware-update-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.04-zwave-firmware-update-api.md new file mode 100644 index 0000000..455d3d0 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.04-zwave-firmware-update-api.md @@ -0,0 +1,162 @@ + +# 4.3.4 ZWave Firmware Update API + +The Firmware Update API provides functionality which together with the SDK supplied ZW_Bootloader module and a big enough external NVM makes it possible to implement firmware update. Currently the external NVM needs to be minimum 1Mbit(128KB) in size to allow for Firmware Updates, but this minimum requirement indicates that the firmware image must have a maximum size for it to be possible to fit in the 1 Mbit NVM together with protocol and application NVM data. The Max firmware using 1Mbit NVM introduces effectively a maximum on the possible usage of BANK3: 0x20000 – 0x7800 – (3 * 0x8000) = 0x2000, which equals 8KB. If a NVM bigger or equal to 2Mbit a full 128KB firmware image can be updated. + +NOTE: The Application MUST call ZW_FirmwareUpdate_NVM_Init prior to calling any other Firmware Update module functionality. If ZW_FirmwareUpdate_NVM_Init returns FALSE it means Firmware Update is NOT possible with attached NVM. + +Serial API: The Firmware Update API is also supported by the serial API enabling firmware update via [Serial API also called Over The Wire (OTW) firmware update. This is an alternative to program the chip in programming mode [3] via SPI, UART or USB. However, OTW requires a target containing a boot loader and serial API support. The PC Controller supports OTW firmware update via the serial API, refer to [20] for details.](../../08-references.md#8-references) + +The Firmware Update functionality contains several functions and are all controlled through the FUNC_ID_ZW_FIRMWARE_UPDATE_NVM serialAPI funcID: + +HOST->ZW: REQ | 0x78 | FIRMWARE_UPDATE_NVM_functionality | functionalityParameters[] + +FIRMWARE_UPDATE_NVM_functionality Defined: + +FIRMWARE_UPDATE_NVM_INIT = 0 FIRMWARE_UPDATE_NVM_SET_NEW_IMAGE = 1 FIRMWARE_UPDATE_NVM_GET_NEW_IMAGE = 2 FIRMWARE_UPDATE_NVM_UPDATE_CRC16 = 3 FIRMWARE_UPDATE_NVM_IS_VALID_CRC16 = 4 FIRMWARE_UPDATE_NVM_WRITE = 5 + +## 4.3.4.1 ZW_FirmwareUpdate_NVM_Init + +BYTE ZW_FirmwareUpdate_NVM_Init() + +Initialize the Firmware Update functionality. The initialization includes determining if attached NVM can be used for Firmware Update. If it is determined the the attached NVM do not support (or if ZW_Firmware_Update_NVM_Init has not been called) following calls to any other FirmwareUpdate_NVM_xyz functionality will do nothing. + +defined in: ZW_firmware_update_nvm_api.h + +Return value: + +BYTE NVM_FIRMWARE_UPDATE_SUPPORTED If NVM is Firmware Update compatible. + +NVM_FIRMWARE_UPDATE_NOT_SUPPORTED If NVM is NOT Firmware Update compatible + +Serial API + +HOST->ZW: REQ | 0x78 | 0x00 ZW->HOST: RES | 0x78 | 0x00 | retVal + +## 4.3.4.2 ZW_FirmwareUpdate_NVM_Set_NEWIMAGE + +BYTE ZW_FirmwareUpdate_NVM_Set_NEWIMAGE(BYTE bValue) + +Set the NEWIMAGE marker in NVM. Used to signal to ZW_Bootloader if a new Firmware Image are present in NVM or not. + +NOTE: The Application MUST call ZW_FirmwareUpdate_NVM_Init prior to calling any other Firmware Update module functionality. If ZW_FirmwareUpdate_NVM_Init returns FALSE it means Firmware Update is NOT possible with attached NVM. + +Return value: + +BYTE TRUE If specified bValue has been written to NVM + +FALSE If the Firmware NEWIMAGE value is already set to bValue + +Defined in: ZW_firmware_update_nvm_api.h + +Parameters: + +bValue IN Value to set “NEWIMAGE” mark to in NVM, which ZW_Bootloader uses to determine if a possible new Firmware exist in external NVM. FIRMWARE_UPDATE_NVM_NEWIMAGE_NEW informs the Bootloader that a possible NEW firmware image exist in external NVM. FIRMWARE_UPDATE_NVM_NEWIMAGE_NOT_NEW informs the ZW_Bootloader that NO NEW firmware image exists in external NVM + +Serial API + +HOST->ZW: REQ | 0x78 | 0x01 | value ZW->HOST: RES | 0x78 | 0x01 | retVal + +## 4.3.4.3 ZW_FirmwareUpdate_NVM_Get_NEWIMAGE + +BYTE ZW_FirmwareUpdate_NVM_Get_NEWIMAGE() + +Get New Firmware Image available indicator in NVM. The New Firmware Image indicator is used to signal the ZW_Bootloader if a possible new Firmware Image is present in NVM. + +NOTE: The Application MUST call ZW_FirmwareUpdate_NVM_Init prior to calling any other Firmware Update module functionality. If ZW_FirmwareUpdate_NVM_Init returns FALSE it means Firmware Update is NOT possible with attached NVM. + +Defined in: ZW_firmware_update_nvm_api.h + +Return value: + +BYTE FIRMWARE_UPDATE_NVM_NEWIMAGE_NOT_NEW If Indicator indicates NO NEW Firmware Image present + +FIRMWARE_UPDATE_NVM_NEWIMAGE_NEW If Indicator indicates NEW Firmware Image is present in NVM + +Serial API + +HOST->ZW: REQ | 0x78 | 0x02 ZW->HOST: RES | 0x78 | 0x02 | retVal + +## 4.3.4.4 ZW_FirmwareUpdate_NVM_UpdateCRC16 + +WORD ZW_FirmwareUpdate_NVM_UpdateCRC16(WORD crc, DWORD nvmOffset, WORD blockSize) + +Calculate CRC16 for specified NVM block of data. + +Defined in: ZW_firmware_update_nvm_api.h + +Return value: + +WORD 0x0000-0xFFFF Resulting CRC16 value after CRC16 calculation on specified block of data in external NVM + +Parameters: + +crc IN Seed CRC16 value to start CRC16 calculation with + +nvmOffset IN Offset into NVM (full address space) where block of data are placed + +blockSize IN Size of block of data in NVM to calculate CRC16 on + +Serial API + +HOST->ZW: REQ | 0x78 | 0x03 | offset3byte(MSB) | offset3byte | offset2byte(LSB) | length2byte(MSB) | length2byte(LSB) | seedCRC16_high | seedCRC16_low ZW->HOST: RES | 0x78 | 0x03 | resCRC16_high | resCRC16_low + +## 4.3.4.5 ZW_FirmwareUpdate_NVM_isValidCRC16 + +BYTE ZW_FirmwareUpdate_NVM_isValidCRC16(WORD *presCRC16) + +Check if Firmware present in NVM is valid using Firmware Descriptor information regarding BANK sizes and the corresponding firmware CRC16 calculated and placed in the Firmware Descriptor structure at compile/link time (fixbootcrc tool). Uses variables initialized by ZW_FirmwareUpdate_NVM_Init to determine where in NVM to find the stored firmware, if present. On return the resulting CRC16 is placed in the WORD which presCRC16 points at. + +NOTE: The Application MUST call ZW_FirmwareUpdate_NVM_Init prior to calling any other Firmware Update module functionality. If ZW_FirmwareUpdate_NVM_Init returns FALSE it means Firmware Update is NOT possible with attached NVM. + +Defined in: ZW_firmware_update_nvm_api.h + +Return value: + +BYTE TRUE If NVM contains a valid ZW_Bootloader upgradable Firmware + +FALSE If NVM do NOT contain a valid ZW_Bootloader upgradable Firmware + +Parameters: + +*resCRC16 ZERO if NVM contains a valid ZW_Bootloader Firmware OUT 0x0001-0xFFFF if NVM do not contain a valid ZW_Bootloader Firmware + +Serial API + +HOST->ZW: REQ | 0x78 | 0x04 ZW->HOST: RES | 0x78 | 0x04 | retVal | resCRC16_high | resCRC16_low + +## 4.3.4.6 ZW_FirmwareUpdate_NVM_Write + +BYTE ZW_FirmwareUpdate_NVM_Write(BYTE *sourceBuffer, WORD fw_bufsize, DWORD firmwareOffset) + +Write Firmware.Image block to NVM if applicable. + +Uses variables initialized by the ZW_FirmwareUpdate_NVM_Init together with the specified firmware offset (where the sourceBuffer belongs) to determine if and where in the external NVM space the sourceBuffer should be written, so that the Bootloader can later do the actual Firmware Update if update was successful. + +NOTE: The Application MUST call ZW_FirmwareUpdate_NVM_Init prior to calling any other Firmware Update module functionality. If ZW_FirmwareUpdate_NVM_Init returns FALSE it means Firmware Update is NOT possible with attached NVM. + +Defined in: ZW_firmware_update_nvm_api.h + +Return value: + +BYTE TRUE If specified sourceBuffer has been written to NVM + +FALSE If the sourceBuffer contents already are present at specified firmware offset in NVM + +Parameters: + +sourceBuffer IN Buffer containing data to write to NVM + +fw_bufsize IN Size of block to write the NVM + +firmwareOffset IN Offset in firmware where sourceBuffer should be written in NVM + +Serial API + +HOST->ZW: REQ | 0x78 | 0x05 |offset3byte(MSB) | offset3byte | offset2byte(LSB) | length2byte(MSB) | length2byte(LSB) | buffer[] ZW->HOST: RES | 0x78 | 0x05 | retVal diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.05-z-wave-node-mask-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.05-z-wave-node-mask-api.md new file mode 100644 index 0000000..f0aca45 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.05-z-wave-node-mask-api.md @@ -0,0 +1,110 @@ + +# 4.3.5 Z-Wave Node Mask API + +The Node Mask API contains a set of functions to manipulate bit masks. This API is not necessary when writing a Z-Wave application, but is provided as an easy way to work with node ID lists as bit masks. + +## 4.3.5.1 ZW_NodeMaskSetBit + +void ZW_NodeMaskSetBit(BYTE_P pMask, BYTE bNodeID) + +Macro: ZW_NODE_MASK_SET_BIT(pMask, bNodeID) + +Set the node bit in a node bit mask. + +Defined in: ZW_nodemask_api.h + +Parameters: + +pMask IN Pointer to node mask + +bnodeID IN Node id (1..232) to set in node mask + +Serial API (Not supported) + +## 4.3.5.2 ZW_NodeMaskClearBit + +void ZW_NodeMaskClearBit(BYTE_P pMask, BYTE bNodeID) + +Macro: ZW_NODE_MASK_CLEAR_BIT(pMask, bNodeID) + +Clear the node bit in a node bit mask. + +Defined in: ZW_nodemask_api.h + +Parameters: + +PMask IN Pointer to node mask + +bNodeID IN Node ID (1..232) to clear in node mask + +Serial API (Not supported) + +## 4.3.5.3 ZW_NodeMaskClear + +void ZW_NodeMaskClear(BYTE_P pMask, BYTE bLength) + +Macro: ZW_NODE_MASK_CLEAR(pMask, bLength) + +Clear all bits in a node mask. + +Defined in: ZW_nodemask_api.h + +Parameters: + +pMask IN Pointer to node mask + +bLength IN Length of node mask + +Serial API (Not supported) + +## 4.3.5.4 ZW_NodeMaskBitsIn + +BYTE ZW_NodeMaskBitsIn( BYTE_P pMask, BYTE bLength) + +Macro: ZW_NODE_MASK_BITS_IN (pMask, bLength) + +Number of bits set in node mask. + +Defined in: ZW_nodemask_api.h + +Return value: + +BYTE Number of bits set in node mask + +Parameters: + +pMask IN Pointer to node mask + +bLength IN Length of node mask + +Serial API (Not supported) + +## 4.3.5.5 ZW_NodeMaskNodeIn + +BYTE ZW_NodeMaskNodeIn (BYTE_P pMask, BYTE bNode) + +Macro: ZW_NODE_MASK_NODE_IN (pMask, bNode) + +Check if a node is in a node mask. + +Defined in: ZW_nodemask_api.h + +Return value: + +BYTE ZERO If not in node mask + +NONEZERO If in node mask + +Parameters: + +pMask IN Pointer to node mask + +bNode IN Node to clear in node mask + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.06-io-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.06-io-api.md new file mode 100644 index 0000000..34529b6 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.06-io-api.md @@ -0,0 +1,82 @@ + +# 4.3.6 IO API + +The 500 Series Z-Wave SoC has four ports: P0, P1, P2, and P3. All IO’s can be set as either input or output. The initial state of IO’s are input mode with the internal pull-up enabled. The IO cells are push/pull cells. When an IO is set as input, a pull-up can be enabled optionally on the input pin of that IO. + +The IO’s can be used either as a general purpose IO (GPIO) or for some of the IO’s, it can be used by one or more of the built-in HW peripherals. The IO’s are default set as GPIO’s. This means that they are directly controlled by the MCU. If a built-in HW peripheral is enabled it can take over control of the IO, this means the direction of the IO, the pull-up state or the output state. In the case where several HW peripherals that it takes control over can use a particular IO. The control is prioritized, for example pin P0.4 on a SD3502 support the following functions: GPIO, Key scanner Column 4 output and LED0 output module (Listed with lowest priority first). Refer to the relevant Z-Wave module datasheet for a complete overview of IO functions supported. + +The state of the IO’s must be fixed before the 500 Series Z-Wave SoC is put into powerdown mode and must be enabled after the 500 Series Z-Wave SoC is powered-up. This is done to avoid unwanted glitches on the IO’s when the 500 Series Z-Wave SoC is powered up. + +## 4.3.6.1 ZW_IOS_enable + +void ZW_IOS_enable(BYTE bStatus) + +This function is used to unlock or lock the state of the GPIO + +Defined in: ZW_basis_api.h + +Parameters: + +bStatus IN Lock or Unlock the state of the IO pins TRUE + +The state of the IO pins can now be changed. If the state of a IO pin was changed before the IO’s are enabled then the change will be made when the IO’s are enabled + +FALSE + +The state of the IO pins are now locked and any changes made to the state will not be made until the IO’s are enable again + +Serial API (Not supported) + +## 4.3.6.2 ZW_IOS_set + +void ZW_IOS_set(BYTE bPort, BYTE bDirection, BYTE bValue) + +This function is used to set the state of the GPIO’s In ApplicationInitHW(). + +Defined in: ZW_basis_api.h + +Parameters: + +bPort IN 0-3 Port number 0 => P0, 1 => P1, 2 => P2, 3 => P3 + +bDirection IN bit pattern Direction. 0b=output, 1b=input. + +For example, 0xF0=> upper 4 IO's are inputs and the lower 4 IO's are outputs + +bValue IN bit pattern Output setting / Pull-up state + +When an IO is set as output the corresponding bit in bValue will determine the output setting: 1b=high 0b=low + +When an IO is set as input the corresponding bit in bValue will determine the state of the pull-up resistor in the IO cell: 1b=pull-up disabled 0b=pull-up enabled + +Serial API (Not supported) + +## 4.3.6.3 ZW_IOS_get + +void ZW_IOS_get(BYTE *bPort, BYTE *bDirection, BYTE *bValue) + +This function is used to read the state of the GPIO’s In ApplicationInitHW(). + +Defined in: ZW_basis_api.h + +Parameters: + +bPort IN 0-3 Port number 0 => P0, 1 => P1, 2 => P2, 3 => P3 + +bDirection OUT bit pattern Direction. 0b=output, 1b=input. + +For example, 0xF0=> upper 4 IO's are inputs and the lower 4 IO's are outputs + +bValue OUT bit pattern Output setting / Pull-up state + +When an IO is set as output the corresponding bit in bValue will determine the output setting: 1b=high 0b=low + +When an IO is set as input the corresponding bit in bValue will determine the state of the pull-up resistor in the IO cell: 1b=pull-up disabled 0b=pull-up enabled + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.07-gpio-macros.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.07-gpio-macros.md new file mode 100644 index 0000000..5a81235 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.07-gpio-macros.md @@ -0,0 +1,128 @@ + +# 4.3.7 GPIO Macros + +The GPIOs MAY be controlled individually via a set of helper macros. These macros can set a GPIO as input/output, set the state of the output GPIO or read the value of an input GPIO. + +The GPIO name MUST be specified as a parameter in all the macros. The format of the pin name is as follow: + +P(port number)(IO number) + +Therefore, I/O pin 3 in port 1 name will be P13. + +WARNING: Be aware of limitations when using GPIO macros in ApplicationInitHW(). Refer to the individual GPIO macros for details. + +## 4.3.7.1 PIN_OUT + +PIN_OUT(pin) + +This macro sets a GPIO as an output IO. + +Defined in: ZW_pindefs.h + +Parameters: + +pin IN Pxy Name of a GPIOr x = port number; y = IO number + +Example: + +PIN_OUT(P12); + +## 4.3.7.2 PIN_IN + +PIN_IN(pin, pullup) + +This macro sets a GPIO as an input and determines whether the internal pullup is enabled or disabled. + +Defined in: ZW_pindefs.h + +Parameters: + +pin IN Pxy Name of a GPIO x = port number; y = IO number + +pullup IN Boolean Pull-up state. 0b=disabled, 1b=enabled. + +Example: + +PIN_IN(P30,TRUE); + +## 4.3.7.3 PIN_LOW + +PIN_LOW(pin) + +This macro sets the state of an output GPIO to low. + +WARNING: This macro can be called in ApplicationInitHW() but GPIO output level will first change immediately after exit of ApplicationInitHW(). + +Defined in: ZW_pindefs.h + +Parameters: + +pin IN Pxy Name of a GPIOr x = port number; y = IO number + +Example: + +PIN_LOW(P12); + +## 4.3.7.4 PIN_HIGH + +PIN_HIGH(pin) + +This macro sets the state of an output GPIO to HIGH. + +WARNING: This macro can be called in ApplicationInitHW() but GPIO output level will first change immediately after exit of ApplicationInitHW(). + +Defined in: ZW_pindefs.h + +Parameters: + +pin IN Pxy Name of a GPIOr x = port number; y = IO number + +Example: + +PIN_HIGH(P12); + +## 4.3.7.5 PIN_TOGGLE + +PIN_TOGGLE(pin) + +This macro toggle the state of an output GPIO from high to low or low to high. + +WARNING: This macro can be called in ApplicationInitHW() but GPIO output level will first change immediately after exit of ApplicationInitHW(). + +Defined in: ZW_pindefs.h + +Parameters: + +pin IN Pxy Name of a GPIOr x = port number; y = IO number + +Example: + +PIN_TOGGLE(P12); + +## 4.3.7.6 PIN_GET + +PIN_GET(pin) + +This macro gets the state of the pin of a GPIO. + +WARNING: The API call ZW_IOS_enable MUST be called before calling PIN_GET in ApplicationInitHW(). It is not necessary to call ZW_IOS_enable in case PIN_GET is not called in ApplicationInitHW(). + +Defined in: ZW_pindefs.h + +Parameters: + +pin IN Pxy Name of a GPIOr x = port number; y = IO number + +Return value + +BOOL TRUE The pin is high FALSE The pin is low + +Example: + +a=PIN_GET(P12); diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.08-z-wave-nvm-memory-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.08-z-wave-nvm-memory-api.md new file mode 100644 index 0000000..df6840b --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.08-z-wave-nvm-memory-api.md @@ -0,0 +1,414 @@ + +# 4.3.8 Z-Wave NVM Memory API + +The memory application interface handles accesses to the application data area in NVM. + +Routing slave nodes use MTP for storing application data. Enhanced 232 slave and all controller nodes use an external NVM for storing application data. The Z-Wave protocol uses the first part of the external [NVM for home ID, node ID, routing table etc. The external NVM is accessed via the SPI1 interface and using P2.5 as chip select. Alternative chip select pins, refer to [18].](../../08-references.md#8-references) + +NVM variables are declared and defined just like any other variables, apart from the needed use of the"far" keyword: However, when declaring NVM variables use the #pragma ORDER at the top of the file to keep the variables in order. When adding a new variable then append it at the end of the defined far variables. Obsoleting a variable remember to keep a dummy far variable to maintain the variables offset. + +BYTE far EEOFFSET_SENSOR_LEVEL_far; /* Just an example */ + +NVM variables declared like this will be located in a virtual XDATA class called HDATA ranging from address 0x10000 and upwards. The application NVM variables are located at offset 0x16000 (0x13000 for 16K NVM). The NVM variables can only be accessed through the NVM Memory API, and not directly. The way you should access the NVM variables are like this: + +ZW_MEM_PUT_BYTE((WORD)&EEOFFSET_SENSOR_LEVEL_far, toggleBasicSet); /* An example */ + +The map file from the linker tells you where your variable are located like this: + +02016006H HDATA BYTE EEOFFSET_SENSOR_LEVEL_far /* An example */ + +where the first two digits means external data. The last 6 digits are the address of the variable, which is offset by 0x10000 from the physical NVM chip address. + +The NVM variables will not be initialized at reset or power on. Only the first time the device is started, the pre-initialized variables will be initialized, because we have a sanity check of the contents. Example of a pre-initialized far variable: + +BYTE far EEOFFSET_SENSOR_LEVEL_far = 0xff; /* Just an example */ + +You can force an initialization of the pre-initialized NVM contents by calling ZW_SetDefault(); + +NOTE: The MCU halts while the API is writing to flash memory, so care should be taken not to write to + +## 4.3.8.1 MemoryGetID + +void MemoryGetID(BYTE *pHomeID, BYTE *pNodeID ) + +Macro: ZW_MEMORY_GET_ID(homeID, nodeID) + +The MemoryGetID function copy the Home-ID and Node-ID from the NVM to the specified RAM addresses. + +NOTE: A NULL pointer can be given as the pHomeID parameter if the application is only interested in reading the Node ID. + +Defined in: ZW_mem_api.h + +Parameters: + +pHomeID OUT Home-ID pointer + +pNodeID OUT Node-ID pointer + +Serial API: + +HOST->ZW: REQ | 0x20 + +ZW->HOST: RES | 0x20 | HomeId(4 bytes) | NodeId + +## 4.3.8.2 MemoryGetByte + +BYTE MemoryGetByte(WORD offset ) + +Macro: ZW_MEM_GET_BYTE(offset) + +Read one byte from the NVM allocated for the application. + +If a write operation is in progress, the write queue will be checked for the actual data. + +Defined in: ZW_mem_api.h + +Return value: + +BYTE Data from the application area of the external NVM + +Parameters: + +offset IN [Address of declared far variable (see section 4.3.8).](04.03.07-gpio-macros.md#4376-pin_get) + +Serial API: + +HOST->ZW: REQ 0x21 offset(MSB) offset into host application NVM memory array offset(LSB) + +ZW->HOST: RES 0x21 retVal data byte read + +## 4.3.8.3 MemoryPutByte + +BYTE MemoryPutByte(WORD offset, BYTE data ) + +Macro: ZW_MEM_PUT_BYTE(offset,data) + +Write one byte to the application area of the NVM. + +On controllers and enhanced 232 slaves this function is based on external NVM and a long write time (2- 5 msec.) must be taken into consideration when implementing the application. + +The data to be written to FLASH are not written immediately to the FLASH. Instead it is saved in a RAM buffer and then written when the RF is not active and it is more than 200ms ago the buffer was accessed. + +Defined in: ZW_mem_api.h + +Return value: + +BYTE FALSE If write buffer full. + +Parameters: + +offset IN [Address of declared far variable (see section 4.3.8).](04.03.07-gpio-macros.md#4376-pin_get) + +data IN Data to store + +Serial API: + +HOST->ZW: REQ 0x22 offset(MSB) offset into host application NVM memory array offset(LSB) data + +ZW->HOST: RES 0x22 retVal retVal=0 ==> error | retVal=1 ==> OK (NVM no change) | retVal>=2 ==> OK (NVM data bytes written + 1) + +## 4.3.8.4 MemoryGetBuffer + +void MemoryGetBuffer( WORD offset, BYTE *buffer, BYTE length ) + +Macro: ZW_MEM_GET_BUFFER(offset,buffer,length) + +Read a number of bytes from the NVM allocated for the application. + +If a write operation is in progress, the write queue will be checked for the actual data. + +Defined in: ZW_mem_api.h + +Parameters: + +offset IN [Address of declared far variable (see section 4.3.8).](04.03.07-gpio-macros.md#4376-pin_get) + +buffer IN Buffer pointer + +length IN Number of bytes to read + +Serial API: + +HOST->ZW: REQ 0x23 offset(MSB) offset into host application NVM memory array offset(LSB) length desired length of read operation + +ZW->HOST: RES 0x23 buffer[] buffer + +## 4.3.8.5 MemoryPutBuffer + +BYTE MemoryPutBuffer(WORD offset, BYTE *buffer, WORD length, VOID_CALLBACKFUNC(func)(void)) + +Macro: ZW_MEM_PUT_BUFFER(offset,buffer,length, func) + +Copy a number of bytes from a RAM buffer to the application area of the NVM. + +If an area is to be set to zero there is no need to specify a buffer, just specify a NULL pointer. + +Defined in: ZW_mem_api.h + +Return value: + +BYTE FALSE If the buffer put queue is full. + +Parameters: + +offset IN [Address of declared far variable (see section 4.3.8).](04.03.07-gpio-macros.md#4376-pin_get) + +buffer IN Buffer pointer If NULL all of the area will be set to 0x00 + +length IN Number of bytes to read + +func IN Buffer write completed function pointer + +Serial API: + +HOST->ZW: REQ 0x24 offset(MSB) offset into host application NVM memory array offset(LSB) length(MSB) desired length of write operation length(LSB) buffer[] buffer funcID + +ZW->HOST: RES 0x24 retVal=0 ==> error | retVal=1 ==> OK (NVM no change) | retVal>=2 ==> OK (NVM data bytes written + 1) + +ZW->HOST: REQ 0x24 funcID + +## 4.3.8.6 ZW_EepromInit + +BOOL ZW_EepromInit(BYTE *homeID) + +Macro: ZW_EEPROM_INIT(HOMEID) + +Initialize the external NVM by writing zeros to the entire NVM. The API then writes the content of homeID if not zero to the home ID address in the external NVM. + +This API call can only be called in production test mode from ApplicationTestPoll. + +NOTE: This function is not implemented in Routing Slave API Library due to lack of external NVM. + +Defined in: ZW_mem_api.h + +Return value: + +BOOL TRUE If the external NVM initialized successfully + +FALSE Initialization failed + +Parameters: + +homeID IN The home ID to be written to the external NVM. + +Serial API (Not supported) + +## 4.3.8.7 ZW_MemoryFlush + +void ZW_MemoryFlush(void) + +Macro: ZW_MEM_FLUSH() + +This call writes data immediately to the application area of the NVM. + +The data to be written to FLASH are not written immediately to the FLASH. Instead it is saved in a SRAM buffer and then written when the RF is not active and it is more than 200ms ago the buffer was accessed. This function can be used to write data immediately to FLASH without waiting for the RF to be idle. + +NOTE: This function is only implemented in Routing Slave API libraries because they are the only libaries that use a temporary SRAM buffer. The other libraries use an external NVM. Data is written directly to the external NVM. + +Defined in: ZW_mem_api.h 4.3.8.8 ZW_NVRGetValue + +void NVRGetValue(BYTE bOffset, BYTE bLength, BYTE *pNVRValue) + +Macro: None + +Read a value from the NVR Flash memory area. The function will check the checksum of the NVR page and if the checksum is correct the function will read the value in NVR. If the checksum is incorrect the default unitialized value 0xFF will be read from all fields. The valid offset goes from 0x00 to 0xEF and to hide the lock bits from the application it is offset with 0x10 compared to the addresses that can be seen in the Z-Wave programmer when doing a raw read of the NVR. + +The offset of a specific value can be found using the NVR_FLASH_STRUCT. An example of reading the NVM Type could be: + +ZW_NVRGetValue(offsetof(NVR_FLASH_STRUCT, bNVMType) , 1, &bMyNVMType); + +Defined in: ZW_nvr_api.h + +Return value: + +pNVRValue NVR Value. OUT Valid values are 0x00-0xFF where a values of 0xFF indicates that the field in the NVR is not valid + +Parameters: + +bOffset IN Offset of the NVR value as given by the NVR_FLASH_STRUCT + +bLength IN Length of the NVR value that should be read + +Serial API: + +HOST->ZW: REQ | 0x28 | offset | length + +ZW->HOST: RES | 0x28 | NVRdata[] + +## 4.3.8.9 ZW_NVRCheck + +BOOL ZW_NVRCheck() + +Macro: None + +[Check if the NVR Flash page contains a valid CRC field [22].](../../08-references.md#8-references) + +Defined in: ZW_nvr_api.h + +Return value: + +BOOL FALSE, NVR Flash contens is not valid + +TRUE, NVR Flash contens is valid + +Serial API: + +Not supported + +## 4.3.8.10 NVM_get_id + +void NVM_get_id(NVM_TYPE_T *p NVMid) + +Macro: None + +Get NVM ID from external NVM. The NVM ID is collected using a NVM “read ID” command, but not all supported NVMs support this command, so the memoryCapacity is set according to the NVM information in the NVR. + +NOTE: This function is only available in libraries that has an external NVM. + +Defined in: ZW_firmware_bootloader_defs.h + +Return value: + +pNVMid OUT NVM ID structure. + +pNVMid->manufacturerID + +Valid values for manufacturerID: 0x00-0xFE, NVM_MANUFACTURER_UNKNOWN + +pNVMid->memoryType + +Valid values for memoryType: NVM_TYPE_FLASH, NVM_TYPE_EEPROM (all NVMs not supporting NVM read ID command) + +pNVMid->memoryCapacity + +Valid values for memoryCapacity: NVM_SIZE_16KB, NVM_SIZE_32KB, NVM_SIZE_128KB, NVM_SIZE_256KB, NVM_SIZE_512KB, NVM_SIZE_UNKNOWN + +Serial API: + +HOST->ZW: REQ | 0x29 + +ZW->HOST: RES | 0x29 | length | NVMid + +## 4.3.8.11 NVM_ext_read_long_byte + +BYTE NVM_ext_read_long_byte(DWORD offset ) + +Macro: None + +Read a byte from external NVM at address offset. + +NOTE: This function is used when doing OTA, and it is only avalible in libraries that has an external NVM. + +Defined in: ZW_firmware_bootloader_defs.h + +Return value: + +BYTE Data read from the external NVM + +Parameters: + +offset IN Offset where to data is to be read. Currently only the 3 least significant bytes are used when addressing the NVM + +Serial API: + +HOST->ZW: REQ | 0x2C | offset3byte(MSB) | offset3byte | offset3byte(LSB) + +ZW->HOST: RES | 0x2C | retval + +## 4.3.8.12 NVM_ext_write_long_byte + +BYTE NVM_ext_write_long_byte(DWORD offset, BYTE data ) + +Macro: None + +Write a byte to external NVM at address offset. + +NOTE: This function is used when doing OTA, and it is only avalible in libraries that has an external NVM. + +WARNING: This function can write in the full NVM address space and is not offset to start at the application area. So care should be taken when using this function to avoid writing in the protocol NVM area. + +Defined in: ZW_firmware_bootloader_defs.h + +Return value: + +BYTE FALSE If no write was needed. + +TRUE If write was done + +Parameters: + +offset IN Offset where to data is to be written. Currently only the 3 least significant bytes are used when addressing the NVM. + +data IN Data to write to external NVM + +Serial API: + +HOST->ZW: REQ | 0x2D | offset3byte(MSB) | offset3byte | offset3byte(LSB) | data + +ZW->HOST: RES | 0x2D | retval + +## 4.3.8.13 NVM_ext_read_long_buffer + +void NVM_ext_read_long_buffer( DWORD offset, BYTE *buffer, WORD length ) + +Macro: None + +Read a number of bytes from external NVM starting from address offset. + +NOTE: This function is used when doing OTA, and it is only avalible in libraries that has an external NVM. + +Defined in: ZW_firmware_bootloader_defs.h + +Parameters: + +offset IN Offset from where data is to be read. Currently only the 3 least significant bytes are used when addressing the NVM + +buffer OUT Buffer pointer + +length IN Number of bytes to read + +Serial API: + +ZW->HOST: REQ | 0x2A | offset3byte(MSB) | offset3byte | offset3byte(LSB) | length(MSB) | length(LSB) + +ZW->HOST: RES | 0x2A | buffer[] + +## 4.3.8.14 NVM_ext_write_long_buffer + +byte NVM_ext_write_long_buffer(DWORD offset, BYTE *buffer, WORD length ) + +Macro: None + +Write a number of bytes to external NVM starting from address offset. + +NOTE: This function is used when doing OTA, and it is only avalible in libraries that has an external NVM. + +WARNING: This function can write in the full NVM address space and is not offset to start at the application area. So care should be taken when using this function to avoid writing in the protocol NVM area. + +Defined in: ZW_firmware_bootloader_defs.h + +Return Value: + +BYTE FALSE If no write was needed. + +TRUE If write was done + +Parameters: + +offset IN Offset where to data is to be written. Currently only the 3 least significant bytes are used when addressing the NVM. + +buffer IN Buffer pointer + +length IN Number of bytes to write + +Serial API: + +HOST->ZW: REQ | 0x2B | offset3byte(MSB) | offset3byte | offset3byte(LSB) | length(MSB) | length(LSB) | buffer[] + +ZW->HOST: RES | 0x2B | retval diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.09-z-wave-timer-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.09-z-wave-timer-api.md new file mode 100644 index 0000000..6afc504 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.09-z-wave-timer-api.md @@ -0,0 +1,188 @@ + +# 4.3.9 Z-Wave Timer API + +The Z-Wave Timer API provides a set a functions which MAY be used by an application to control the timing of events. Applications SHOULD use the Z-Wave Timer API functions. The Z-Wave Timer API supports a high number of concurrent software timer instances. In addition to the software timers, the application MAY use one or two hardware timers provided by the 8051 architecture. Before using a hardware timer, the application designer MUST make sure that the [actual hardware timer is not already allocated for use by the Z-Wave protocol library. Refer to section 3.7.](../../03-z-wave-software-architecture/03.07-z-wave-hardware-timers.md#37-z-wave-hardware-timers) + +Software timers are based on a “tick-function” every 10 ms. The “tick-function” triggers a global tick counter and a number of active timers. The global tick counter is incremented on each “tick”. Active software timers are decremented on each “tick”. When an active timer value reaches 0, the registered timer function is called. The timer function is called from the Z-Wave main loop (non-interrupt environment). + +Software timers provide limited accuracy. They are stopped while changing RF transmission direction and during sleep mode. The global tick counter and software timers will continue from their current state when resuming operation after sleep mode. + +Software timers are targeted for a limited time duration. Longer timers may implemented by the application designer by multiple software timer periods combined with referring to the global tick counter. The global tick counter is stored in the global variable: + +WORD tickTime + +## 4.3.9.1 TimerStart + +BYTE TimerStart( VOID_CALLBACKFUNC(func)(), BYTE bTimerTicks, BYTE bRepeats) + +Macro: ZW_TIMER_START(func, bTimerTicks, bRepeats) + +Register a function that is called when the specified time has elapsed. Remember to check if the timer is allocated by testing the return value. The call back function is called "bRepeats" times before the timer is stopped. It’s possible to have up to 5 timers running simultaneously. + +Defined in: ZW_timer_api.h + +Return value: + +BYTE Timer handle (timer table index). 0xFF is returned if the timer start operation failed. + +The timer handle is used when calling other timer functions such as TimerRestart, etc. + +Parameters: + +pFunc IN Timeout function address (not NULL). + +bTimerTicks IN Timeout value (value * 10 ms). Predefined values: + +TIMER_ONE_SECOND + +bRepeats IN Number of function calls. Maximum value is 253. Predefined values: + +TIMER_ONE_TIME + +TIMER_FOREVER + +Serial API (Not supported) + +## 4.3.9.2 TimerRestart + +BYTE TimerRestart( BYTE bTimerHandle) + +Macro: ZW_TIMER_RESTART(BYTE bTimerHandle) + +Set the specified timer’s tick count to the initial value (extend timeout value). + +NOTE: There is no protection in the API against calling this function with a wrong handler, so care should be taken not to use a handler of a timer that has already expired or been canceled. + +Defined in: ZW_timer_api.h + +Return value: + +BYTE TRUE Timer restarted + +Parameters: + +bTimerHandle IN Timer to restart + +Serial API (Not supported) + +## 4.3.9.3 TimerCancel + +BYTE TimerCancel(BYTE bTimerHandle) + +Macro: ZW_TIMER_CANCEL( bTimerHandle) + +Stop and unregister the specified timer. + +NOTE: There is no protection in the API against calling this function with a wrong handler, so care should be taken not to use a handler of a timer that has already expired. + +Defined in: ZW_timer_api.h + +Return value: + +BYTE TRUE Timer cancelled + +Parameters: + +bTimerHandle IN Timer number to stop + +Serial API (Not supported) + +## 4.3.9.4 ZW_TimerLongStart + +bTimerHandle_t + +ZW_TimerLongStart( + +VOID_CALLBACKFUNC(func)(), + +DWORD dwtimerTicks, + +BYTE bRepeats); + +Register a function that is called when the specified time has elapsed. Remember to check if the timer is allocated by testing the return value. The callback function is called "bRepeats" times before the timer is stopped. + +Defined in: ZW_timer_api.h + +Return value: + +bTimerHandle_t Timer handle (timer table index). 0xFF is returned if the timer start operation failed. + +The timer handle is used when calling other timer functions such as TimerLongRestart, etc. + +Parameters: + +func IN Callback function (not NULL). + +dwtimerTicks IN Timeout value in ms (32 bit). + +bRepeats IN Number of function calls. Maximum value is 253. Predefined values: + +TIMER_ONE_TIME + +TIMER_FOREVER + +Serial API (Not supported) + +## 4.3.9.5 ZW_TimerLongRestart + +BYTE ZW_TimerLongRestart(bTimerHandle_t bTimerHandle) + +Set the specified timer’s tick count to the initial value (extend timeout value). + +NOTE: There is no protection in the API against calling this function with a wrong handler, so care should be taken not to use a handler of a timer that has already expired or been canceled. + +Defined in: ZW_timer_api.h + +Return value: + +BYTE TRUE Timer restarted + +Parameters: + +bTimerHandle IN Timer to restart + +Serial API (Not supported) + +## 4.3.9.6 ZW_TimerLongCancel + +BYTE ZW_TimerLongCancel(bTimerHandle_t bTimerHandle) + +Stop and unregister the specified timer. + +NOTE: There is no protection in the API against calling this function with a wrong handler, so care should be taken not to use a handler of a timer that has already expired. + +Defined in: ZW_timer_api.h + +Return value: + +BYTE TRUE Timer cancelled + +Parameters: + +bTimerHandle IN Timer number to stop + +Serial API (Not supported) + +## 4.3.9.7 ZW_TimerLongGetTimeLeft + +DWORD ZW_TimerLongGetTimeLeft(bTimerHandle_t bTimerHandle) + +Returns the time left before the timer calls the registered callback function. + +Defined in: ZW_timer_api.h + +Return value: + +DWORD Time left in ms. + +Parameters: + +bTimerHandle IN Handle to the timer in question. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.10-power-control-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.10-power-control-api.md new file mode 100644 index 0000000..15a9abc --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.10-power-control-api.md @@ -0,0 +1,98 @@ + +# 4.3.10 Power Control API + +The 500 Series Z-Wave SoC has two types of power down modes: WUT mode and Stop mode. + +Stopped mode is the lowest power mode of the SoC where all circuitry is shut down except for a small basic block that keeps the IO states. + +WUT mode is identical to Stopped mode except for enabling of a low power ring oscillator that ticks every second or 1/128 second. The WUT timer can wake up the chip after a programmable period of time. + +Wake up of the two modes can also be accomplished by an external source (EXT1 pin). + +During power down mode is a small part of the RAM powered called Critical Memory. + +## 4.3.10.1 ZW_SetSleepMode + +BOOL ZW_SetSleepMode( BYTE mode, BYTE intEnable, BYTE beamCount ) + +Macro: ZW_SET_SLEEP_MODE(MODE,MASK_INT) + +This function MAY be used to set the SoC in a specified power down mode. Battery-operated devices may use this functionality in order to save power when idle. + +If the Z-Wave protocol is currently busy, the node may stay awake for some time after the application issues a call to ZW_SetSleepMode(). When the protocol is idle, (stopped RF transmission etc.) the MCU will power down. + +The RF transceiver is turned off so nothing can be received while in WUT or Stop mode. The ADC is also disabled when in WUT or Stop mode. The Z-Wave main loop is stopped until the MCU is awake again. Refer to the mode parameter description regarding how the MCU can be wakened up from sleep mode. In STOP and WUT modes interrupt(s) may be masked out so they cannot wake up the chip. + +Any external hardware controlled by the application should be turned off before returning from the application poll function. The Z-Wave main loop is stopped until the MCU is wakened. The chip resumes from sleep mode via a reset event. Therefore, all temporary state must be re- established after the sleep mode. + +It is RECOMMENDED that applications implementing FLiRS node functionality stays awake for two seconds after receiving a frame; either singlecast or multicast. This allows a transmitting node to send additional frames to the FLiRS node without prepending a beam to each frame. A two second stay- awake period after each received frame allows a FLiRS to quickly initiate secure communication and to transfer long payloads such as security certificates and firmware images. + +When the ASIC is in power-down mode the EXT1 pin can get the SoC out of the power-down state by asserting it. This mode of operation can be activated by setting the intEnable parameter in ZW_SetSleepMode to ZW_INT_MASK_EXT1. If the EXT1 pin is asserted when the SoC is in power- down mode, the ASIC will wake up from reset. If we are in FLIRS mode and the EXT1 pin is asserted and the unasserted during beam search then it will not wakeup the SoC. If we are in FLIRS mode and WUT timeout occur and an event on EXT1 happens simultaneously, the Z-Wave protocol will search for a beam, and if no beam is detected, then it will power down again. So to make sure that an event in EXT1 is detected when in FLiRS mode we should ensure that it is asserted longer than the beam search time (2.5ms for 2 channels and 4ms for 3 channels). Warning: Using EXT1 pin as both an external interrupt source by setting EX1 = 1 and as wake up source for a FLiRS node requires that the EXT1 Interrupt Service Routine (ISR) can handle wake up events in an appropriate manner. + +NOTE: This function is only implemented in Routing Slave, Enhanced 232 Slave and Portable Controller API libraries. + +Defined in: ZW_power_api.h + +Return values + +BOOL TRUE The chip will power down when the protocol is ready + +FALSE The protocol can not power down because a wakeup beam is being received, try again later. + +Parameters: + +mode IN Specify the type of power save mode: + +ZW_STOP_MODE The whole chip is turned down. The chip can be wakened up again by Hardware reset or by the external interrupt INT1. + +ZW_WUT_MODE The chip is powered down, and it can only be waked by the timer timeout or by the external interrupt INT1. The timeout interval of the WUT timer is controlled by the API call ZW_SetWutTimeout. + +ZW_WUT_FAST_MODE This mode has the same functionality as ZW_WUT_MODE, except that the timer resolution is 1/128 s. The maximum timeout value is 2 s. + +ZW_FREQUENTLY_LISTENING_MODE This mode make the module enter a Frequently Listening mode where the module will wakeup for a few milliseconds every 1000 ms or 250 ms [and check for radio transmissions to the module (See 4.3.1.6 for details about](04.03.01-required-application-functions/04.03.01.06-applicationnodeinformation.md#4316-applicationnodeinformation) selecting wakeup speed). The application will only wakeup if there is incoming RF traffic or if the intEnable or beamCount parameters are used. intEnable IN Interrupt enable bit mask. If a bit mask is 1, the corresponding interrupt is enabled and this interrupt will wakeup the chip from power down. Valid bit masks are: + +ZW_INT_MASK_EXT1 External interrupt 1 (PIN P1_1) is enabled as interrupt source + +0x00 No external Interrupts will wakeup. + +Useful in WUT mode + +beamCount IN Frequently listening WUT wakeups + +0x00 No WUT wakeups in Frequently listening mode. Both macro and serial API call use this value when called. + +0x01-0xFF Number of frequently listening wakeup interval between the module does a normal WUT wakeup. This parameter is only used if mode is set to ZW_FREQUENTLY_LISTENING_MODE. + +Serial API + +HOST->ZW: REQ | 0x11 | mode | intEnable + +## 4.3.10.2 ZW_SetWutTimeout + +void ZW_SetWutTimeout (BYTE wutTimeout) + +Macro: ZW_SET_WUT_TIMEOUT(TIME) + +ZW_SetWutTimeout is speficially intended to set the WUT timer interval. + +The chip resumes from sleep mode via a reset event. Therefore, ZW_SetWutTimeout SHOULD be called before every call to ZW_SetSleepMode when enabling ZW_WUT_MODE. If not calling ZW_SetWutTimeout, a default value of 0 (zero) will be used (corresponding to 1 second). + +The timer resolution of the WUT timer is one second. The maximum timeout value is 256 secs. + +NOTE: This function is only implemented in Routing Slave, Enhanced 232 Slave and Portable Controller API libraries. + +Defined in: ZW_power_api.h + +Parameters: + +wutTimeout IN The Wakeup Timer timeout value. The unit is the second. The resolution is 8 bit. [0..255] => [1 sec .. 256 sec] + +Serial API + +HOST->ZW: REQ | 0xB4 | wutTimeout diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.01-operation.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.01-operation.md new file mode 100644 index 0000000..967a883 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.01-operation.md @@ -0,0 +1,12 @@ + +# 4.3.11.1 Operation + +Data to be transmitted is written to a SPI data register, one byte at the time and data received is read from a SPI data register one byte at the time. + +A SPI interrupt is set when the SPI interface has transferred a byte on the SPI interface. T diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.02-zw_spi0_init.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.02-zw_spi0_init.md new file mode 100644 index 0000000..f25c84f --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.02-zw_spi0_init.md @@ -0,0 +1,42 @@ + +# 4.3.11.2 ZW_SPI0_init + +void ZW_SPI0_init(BYTE bSpiInit) + +Initializes the 500 Series Z-Wave SoC built-in SPI0 master/slave controller. Notice that not all 500 Series Z-Wave SoC/modules has this SPI available on the pin-out and for some Z-Wave device types this SPI is reserved for the Z-Wave protocol. + +This function sets the SPI clock speed, the signaling mode and the data order. For example, + +ZW_SPI0_init(SPI_SPEED_8_MHZ|SPI_MODE_0|SPI_MSB_FIRST) + +Sets clock speed to 8MHz, SPI clock idle to low, data sampled at rising edge and clocked at falling edge, and sends most significant bit first. + +Defined in: ZW_spi_api.h + +Parameters: + +bSpiInit IN bit mask: + +Speed of the SPI clock (master mode only) + +SPI clock runs at @8MHz SPI_SPEED_8_MHZ SPI clock runs at @4MHz SPI_SPEED_4_MHZ SPI_SPEED_2_MHZ SPI clock runs at @2MHz SPI clock runs at @1MHz SPI_SPEED_1_MHZ + +SPI signaling modes 1 + +SPI_MODE_0 SPI clock idle low, data sampled at rising edge and clocked at falling edge SPI_MODE_1 SPI clock idle low, data sampled at falling edge and clocked at rising edge SPI_ MODE_2 SPI clock idle high, data sampled at falling edge and clocked at rising edge SPI_ MODE_3 SPI clock idle high, data sampled at rising edge and clocked at falling edge + +Data order + +SPI_MSB_FIRST send MSB bit first SPI_LSB_FIRST send LSB bit first + +Master/Slave + +SPI_MASTER enable SPI master mode SPI_SLAVE enable SPI slave mdoe Slave Select (Slave mode only) + +SPI_SS_N_SS use io SS_N IO as the slave select signal input when the 500 Series Z-Wave SoC is in SPI slave mode SPI_SS_N_GPIO slave controller is always enabled when the 500 Series Z-Wave SoC is in SPI slave mode. The IO, SS_N, can freely be used as a GPIO or for another HW function. Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.03-zw_spi0_enable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.03-zw_spi0_enable.md new file mode 100644 index 0000000..78fc2ad --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.03-zw_spi0_enable.md @@ -0,0 +1,22 @@ + +# 4.3.11.3 ZW_SPI0_enable + +void ZW_SPI0_enable(BYTE bState) + +Function enables the SPI0 master and allocates the pins MISO0, MOSI0, and SCK0. If SPI_SS_N_SS is set in ZW_SPI0_init() then also SS_N0 is allocated. + +Defined in: ZW_spi_api.h + +Parameters: + +bState IN TRUE enable the SPI0 controller + +FALSE disable the SPI0 controller + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.04-zw_spi0_rx_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.04-zw_spi0_rx_get.md new file mode 100644 index 0000000..b14a877 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.04-zw_spi0_rx_get.md @@ -0,0 +1,22 @@ + +# 4.3.11.4 ZW_SPI0_rx_get + +BYTE ZW_SPI0_rx_get(void) + +Function returns a previously received byte from SPI0. + +This function does not wait until data has been received. + +Defined in: ZW_spi_api.h + +Return value: + +BYTE Received data. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.05-zw_spi0_tx_set.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.05-zw_spi0_tx_set.md new file mode 100644 index 0000000..c2cbb90 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.05-zw_spi0_tx_set.md @@ -0,0 +1,26 @@ + +# 4.3.11.5 ZW_SPI0_tx_set + +void ZW_SPI0_tx_set(BYTE data) + +For SPI master: + +Function starts transmission over the SPI0. Waits until SPI0 transmitter is idle before it sends the new data and will then immediately return before the serial transmission has taken place. + +For SPI slave: + +Function transfers a data byte to the SPI0 register. Waits until SPI0 transmitter is idle before it transfers the new data, but it will not ensure that the transfer of data to the SPI0 register didn't happen without colliding with the next byte transfer. Use the function ZW_SPI0_rx_coll_get() to check whether a collition has occurred. The function will then immediately return possibly before the serial transmission is started (initiated by the SPI master). + +Defined in: ZW_spi_api.h + +Parameters: + +data IN Data to be send. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.06-zw_spi0_active_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.06-zw_spi0_active_get.md new file mode 100644 index 0000000..caa1265 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.06-zw_spi0_active_get.md @@ -0,0 +1,22 @@ + +# 4.3.11.6 ZW_SPI0_active_get + +BYTE ZW_SPI0_active_get(void) + +Read the SPI0 send data status. + +Defined in: ZW_spi_api.h + +Return value: + +BYTE non-zero SPI0 Transmitter is busy + +zero (0x00) SPI0 Transmitter is idle + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.07-zw_spi0_coll_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.07-zw_spi0_coll_get.md new file mode 100644 index 0000000..3417ac1 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.07-zw_spi0_coll_get.md @@ -0,0 +1,22 @@ + +# 4.3.11.7 ZW_SPI0_coll_get + +BYTE ZW_SPI0_coll_get(void) + +This function returns the state of the SPI0 collision flag and then clears the collision flag. + +Defined in: ZW_spi_api.h + +Return value: + +BYTE non-zero SPI0 data collided + +zero (0x00) SPI0 no collisions + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.08-zw_spi0_int_enable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.08-zw_spi0_int_enable.md new file mode 100644 index 0000000..55c8921 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.08-zw_spi0_int_enable.md @@ -0,0 +1,20 @@ + +# 4.3.11.8 ZW_SPI0_int_enable + +void ZW_SPI0_int_enable(BYTE boEnable) + +Call will enable or disable the SPI0 interrupt. If enabled an interrupt routine must be defined. Default is the SPI0 interrupt is disabled. If the SPI0 interrupt is used, then the SPI0 interrupt flag should be reset before returning from the NOTE: interrupt routine by calling ZW_SPI0_int_clear.. Defined in: ZW_spi_api.h + +Parameters: + +boEnable IN TRUE Enables the SPI0 interrupt. + +FALSE Disables the SPI0 interrupt. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.09-zw_spi0_int_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.09-zw_spi0_int_get.md new file mode 100644 index 0000000..569f179 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.09-zw_spi0_int_get.md @@ -0,0 +1,22 @@ + +# 4.3.11.9 ZW_SPI0_int_get + +BYTE ZW_SPI0_int_get(void) + +This function returns the state of the SPI0 interrupt/transmission done flag. + +Defined in: ZW_spi_api.h + +Return value: + +BYTE non-zero SPI0 interrupt/transmission flag is set + +zero (0x00) SPI0 interrupt/transmission flag is cleared + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.10-zw_spi0_int_clear.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.10-zw_spi0_int_clear.md new file mode 100644 index 0000000..005457c --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.10-zw_spi0_int_clear.md @@ -0,0 +1,16 @@ + +# 4.3.11.10 ZW_SPI0_int_clear + +void ZW_SPI0_int_clear(void) + +Function clears the SPI0 interrupt/transmission done flag + +Defined in: ZW_spi_api.h + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.11-zw_spi1_init.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.11-zw_spi1_init.md new file mode 100644 index 0000000..99c8ad9 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.11-zw_spi1_init.md @@ -0,0 +1,40 @@ + +# 4.3.11.11 ZW_SPI1_init + +void ZW_SPI1_init(BYTE bSpiInit) + +Initializes the 500 Series Z-Wave SoC built-in SPI master controller, SPI1. Notice that not all 500 Series Z-Wave SoC/modules has this SPI available on the pin-out and for some Z-Wave device types this SPI is reserved for the Z-Wave protocol. + +The function sets the SPI clock speed, the signaling mode and the data order. E.g.: + +ZW_SPI1_init(SPI_SPEED_8_MHZ|SPI_MODE_0|SPI_MSB_FIRST) + +Sets clock speed to 8MHz, SPI clock idle to low, data sampled at rising edge and clocked at falling edge, and sends most significant bit first. + +Defined in: ZW_spi_api.h + +Parameters: + +bSpiInit IN bit mask: + +Speed of the SPI clock + +SPI clock runs at @8MHz SPI_SPEED_8_MHZ SPI clock runs at @4MHz SPI_SPEED_4_MHZ SPI_SPEED_2_MHZ SPI clock runs at @2MHz SPI clock runs at @1MHz SPI_SPEED_1_MHZ + +SPI signaling modes 1 + +SPI_MODE_0 SPI clock idle low, data sampled at rising edge and clocked at falling edge SPI_MODE_1 SPI clock idle low, data sampled at falling edge and clocked at rising edge SPI_ MODE_2 SPI clock idle high, data sampled at falling edge and clocked at rising edge SPI_ MODE_3 SPI clock idle high, data sampled at rising edge and clocked at falling edge + +Data order + +SPI_MSB_FIRST send MSB bit first + +SPI_LSB_FIRST send LSB bit first + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.12-zw_spi1_enable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.12-zw_spi1_enable.md new file mode 100644 index 0000000..8037f19 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.12-zw_spi1_enable.md @@ -0,0 +1,22 @@ + +# 4.3.11.12 ZW_SPI1_enable + +void ZW_SPI1_enable(BYTE bState) + +Function enables the SPI1 master and allocates the pins MISO1, MOSI1, and SCK1. + +Defined in: ZW_spi_api.h + +Parameters: + +bState IN TRUE enable the SPI1 controller + +FALSE disable the SPI1 controller + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.13-zw_spi1_rx_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.13-zw_spi1_rx_get.md new file mode 100644 index 0000000..0c48951 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.13-zw_spi1_rx_get.md @@ -0,0 +1,22 @@ + +# 4.3.11.13 ZW_SPI1_rx_get + +BYTE ZW_SPI1_rx_get(void) + +This function returns a previously received byte from SPI1. + +This function does not wait until data has been received. + +Defined in: ZW_spi_api.h + +Return value: + +BYTE Received data. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.14-zw_spi1_tx_set.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.14-zw_spi1_tx_set.md new file mode 100644 index 0000000..d516237 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.14-zw_spi1_tx_set.md @@ -0,0 +1,20 @@ + +# 4.3.11.14 ZW_SPI1_tx_set + +void ZW_SPI1_tx_set(BYTE data) + +Function starts transmission over the SPI1. Waits until SPI1 transmitter is idle before it sends the new data and will then immediately return before the serial transmission has taken place. + +Defined in: ZW_spi_api.h + +Parameters: + +data IN Data to be send. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.15-zw_spi1_active_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.15-zw_spi1_active_get.md new file mode 100644 index 0000000..f54093a --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.15-zw_spi1_active_get.md @@ -0,0 +1,22 @@ + +# 4.3.11.15 ZW_SPI1_active_get + +BYTE ZW_SPI1_active_get(void) + +Read the SPI1 send data status. + +Defined in: ZW_spi_api.h + +Return value: + +BYTE non-zero SPI1 Transmitter is busy + +zero (0x00) SPI1 Transmitter is idle + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.16-zw_spi1_coll_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.16-zw_spi1_coll_get.md new file mode 100644 index 0000000..e88d748 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.16-zw_spi1_coll_get.md @@ -0,0 +1,22 @@ + +# 4.3.11.16 ZW_SPI1_coll_get + +BYTE ZW_SPI1_coll_get(void) + +This function returns the state of the SPI1 collision flag and then clears the collision flag. + +Defined in: ZW_spi_api.h + +Return value: + +BYTE non-zero SPI1 data collided + +zero (0x00) SPI1 no collisions + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.17-zw_spi1_int_enable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.17-zw_spi1_int_enable.md new file mode 100644 index 0000000..9591e7e --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.17-zw_spi1_int_enable.md @@ -0,0 +1,20 @@ + +# 4.3.11.17 ZW_SPI1_int_enable + +void ZW_SPI1_int_enable(BYTE boEnable) + +Call will enable or disable the SPI1 interrupt. If enabled an interrupt routine must be defined. Default is the SPI1 interrupt is disabled. If the SPI1 interrupt is used, then the SPI1 interrupt flag should be reset before returning from the NOTE: interrupt routine by calling ZW_SPI1_int_clear.. Defined in: ZW_spi_api.h + +Parameters: + +boEnable IN TRUE Enables the SPI1 interrupt. + +FALSE Disables the SPI1 interrupt. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.18-zw_spi1_int_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.18-zw_spi1_int_get.md new file mode 100644 index 0000000..62c9403 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.18-zw_spi1_int_get.md @@ -0,0 +1,22 @@ + +# 4.3.11.18 ZW_SPI1_int_get + +BYTE ZW_SPI1_int_get(void) + +This function returns the state of the SPI1 interrupt/transmission done flag. + +Defined in: ZW_spi_api.h + +Return value: + +BYTE non-zero SPI1 interrupt/transmission flag is set + +zero (0x00) SPI1 interrupt/transmission flag is cleared + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.19-zw_spi1_int_clear.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.19-zw_spi1_int_clear.md new file mode 100644 index 0000000..3406c35 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/04.03.11.19-zw_spi1_int_clear.md @@ -0,0 +1,16 @@ + +# 4.3.11.19 ZW_SPI1_int_clear + +void ZW_SPI1_int_clear(void) + +Function clears the SPI1 interrupt/transmission done flag + +Defined in: ZW_spi_api.h + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/index.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/index.md new file mode 100644 index 0000000..a5f8700 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.11-spi-interface-api/index.md @@ -0,0 +1,40 @@ + +# 4.3.11 SPI Interface API + +The 500 Series Z-Wave SoC offers up to two SPI interfaces: + +SPI0: operate as a SPI master or as a SPI slave SPI1: operates as a SPI master + +The SPI master, SPI1, is reserved by the Z-Wave protocol, if the 500 Series Z-Wave SoC is programmed as one of the following Z-Wave nodes types: Portable Controller, Static Controller, Bridge Controller, or Enhanced 232 Slave. + +The state of the IO's used for SCK, MOSI, MISO and SS_N automatically setup by the SPI once it is enabled. + +The SS_N input is used as SPI Slave Select for an SPI setup as a slave. If the SPI controller is master and it needs to select the slave(s), this has to be controlled by the application SW and an extra IO pin(s) has to be used for that purpose. + +## Contents + +- [4.3.11.1 Operation](04.03.11.01-operation.md) +- [4.3.11.2 ZW_SPI0_init](04.03.11.02-zw_spi0_init.md) +- [4.3.11.3 ZW_SPI0_enable](04.03.11.03-zw_spi0_enable.md) +- [4.3.11.4 ZW_SPI0_rx_get](04.03.11.04-zw_spi0_rx_get.md) +- [4.3.11.5 ZW_SPI0_tx_set](04.03.11.05-zw_spi0_tx_set.md) +- [4.3.11.6 ZW_SPI0_active_get](04.03.11.06-zw_spi0_active_get.md) +- [4.3.11.7 ZW_SPI0_coll_get](04.03.11.07-zw_spi0_coll_get.md) +- [4.3.11.8 ZW_SPI0_int_enable](04.03.11.08-zw_spi0_int_enable.md) +- [4.3.11.9 ZW_SPI0_int_get](04.03.11.09-zw_spi0_int_get.md) +- [4.3.11.10 ZW_SPI0_int_clear](04.03.11.10-zw_spi0_int_clear.md) +- [4.3.11.11 ZW_SPI1_init](04.03.11.11-zw_spi1_init.md) +- [4.3.11.12 ZW_SPI1_enable](04.03.11.12-zw_spi1_enable.md) +- [4.3.11.13 ZW_SPI1_rx_get](04.03.11.13-zw_spi1_rx_get.md) +- [4.3.11.14 ZW_SPI1_tx_set](04.03.11.14-zw_spi1_tx_set.md) +- [4.3.11.15 ZW_SPI1_active_get](04.03.11.15-zw_spi1_active_get.md) +- [4.3.11.16 ZW_SPI1_coll_get](04.03.11.16-zw_spi1_coll_get.md) +- [4.3.11.17 ZW_SPI1_int_enable](04.03.11.17-zw_spi1_int_enable.md) +- [4.3.11.18 ZW_SPI1_int_get](04.03.11.18-zw_spi1_int_get.md) +- [4.3.11.19 ZW_SPI1_int_clear](04.03.11.19-zw_spi1_int_clear.md) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.01-zw_adc_init.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.01-zw_adc_init.md new file mode 100644 index 0000000..ce43834 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.01-zw_adc_init.md @@ -0,0 +1,58 @@ + +# 4.3.12.1 ZW_ADC_init + +void ZW_ADC_init ( BYTE bMode, BYTE bUpper_ref, BYTE bLower_ref, BYTE bPin_en) + +This function MAY be used to power up and initialize the ADC unit. The ADC unit may be operated in two different modes, battery monitoring mode and I/O mode. + +In battery monitoring mode the ADC will automatically be configured to have the VDD as upper reference voltage, VSS as lower reference voltage and the band gap as the ADC input. In battery monitoring mode the parameters bUpper_ref, bLower_ref and bPin_en are ignored. + +[Refer to [15] for a detailed description of battery monitoring mode and of battery powered Z-Wave](../../../08-references.md#8-references) applications in general.. + +In I/O mode the ADC unit can sample four hardware inputs with user selectable upper and lower voltage references. + +The upper reference voltage can be set to be VDD, internal bandgab or external voltage on ADC_PIN3. Lower reference voltage can be set to be either VSS (GND) or external voltage on pin ADC_PIN2. + +If called in I/O mode, the parameter bPin_en MUST be used to enable one or more of the I/O pins P3.4 .. P3.7 (ADC_PIN0 .. ADC_PIN3) as ADC inputs pins. If a pin is enabled as ADC input this pin can not be used as a GPIO at the same time. Be aware that enabling other peripherals (like Keypad scanner, IR and Triac Controller) can overrule this setting. + +Even though the bPin_en is set, no I/O pin will be selected as the active ADC input by this function. To select the active ADC input, ZW_ADC_pin_select MUST be called before ZW_ADC_enable(TRUE) is called. + +The ADC can either run in single conversion mode or multi (continuous) conversion mode + +[Refer to [16] for a detailed description of the ADC hardware and of PCB layout.](../../../08-references.md#8-references) Defined in: ZW_adcdriv_api.h + +Parameters + +bMode IN ADC_IO_MULTI_ MODE Set the ADC in multi conversion mode ADC input will be from the I/O's. The ADC will continue converting until it is stopped. + +ADC_IO_SINGLE_ MODE Set the ADC in single conversion mode ADC input will be from the I/O's. The ADC will convert one time then stop. + +ADC_BATT_MULTI_MODE Set the ADC in battery monitoring mode. The chip supply voltage (VDD) is selected as upper reference. GND will be selected as lower reference voltage. The ADC input will be the band gap circuit. The ADC will continue converting until it is stopped. + +ADC_BATT_SINGLE_MODE Set the ADC in battery monitoring mode. The chip supply voltage (VDD) is selected as upper reference. GND will be selected as lower reference voltage. The ADC input will be the band gap circuit. The ADC will convert one time then stop. + +bUpper_ref Ignored when battery monitoring mode is enabled + +ADC_REF_U_VDD Select the chip power supply (VDD) as the upper reference voltage. Ignored when ADC in battery monitor mode. + +ADC_REF_U_EXT Select IO P3.7 as the upper reference voltage. Ignored when ADC in battery monitor mode. + +ADC_REF_U_BGAB Select the band gab circuit as the upper reference voltage. Ignored when ADC in battery monitor mode. + +bLower_ref Ignored when battery monitoring mode is enabled + +ADC_REF_L_VSS Select the ground (VSS) as the lower reference voltage. Ignored when ADC in battery monitor mode. + +ADC_REF_L_EXT Select IO P3.6 as lower reference voltage. Ignored when ADC in battery monitor mode. bPin_en Ignored when battery monitoring mode is enabled + +Bitmask Select which IO to enable as ADC inputs. Selected pins MUST NOT be used as GPIOs + +ADC_PIN0 Select I/O P3.4 as an ADC input ADC_PIN1 Select I/O P3.5 as an ADC input ADC_PIN2 Select I/O P3.6 as an ADC input ADC_PIN3 Select I/O P3.7 as an ADC input + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.02-zw_adc_power_enable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.02-zw_adc_power_enable.md new file mode 100644 index 0000000..8fdadde --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.02-zw_adc_power_enable.md @@ -0,0 +1,24 @@ + +# 4.3.12.2 ZW_ADC_power_enable + +void ZW_ADC_power_enable(BYTE boEnable) + +This function SHOULD be used to control when the ADC unit is powered. ADC is powered down, when the module enters sleep mode. + +Calling ZW_ADC_init() will power up the ADC. + +Defined in: ZW_adcdriv_api.h + +Parameters: + +boEnable IN TRUE Turn the ADC power on + +FALSE Turn the ADC power off. The ADC will cancel any activity immediately. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.03-zw_adc_enable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.03-zw_adc_enable.md new file mode 100644 index 0000000..1746ab5 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.03-zw_adc_enable.md @@ -0,0 +1,26 @@ + +# 4.3.12.3 ZW_ADC_enable + +void ZW_ADC_enable(BYTE boStart) + +This function MAY be used to start / stop the ADC unit. + +If ZW_ADC_enable(FALSE) is called when the ADC unit is currently performing multi conversions, any current running conversion process will continue running is has finished whereafter this function call will return. + +If the ADC is powered off ZW_ADC_power_enable(TRUE) MUST be called before ZW_ADC_enable(TRUE) is called. + +Defined in: ZW_adcdriv_api.h + +Parameters: + +boStart IN TRUE Start the ADC and begin conversion + +FALSE Single mode: stop the ADC. Multi mode: wait for conversion to finish then stop ADC + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.04-zw_adc_pin_select.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.04-zw_adc_pin_select.md new file mode 100644 index 0000000..7b40662 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.04-zw_adc_pin_select.md @@ -0,0 +1,24 @@ + +# 4.3.12.4 ZW_ADC_pin_select + +void ZW_ADC_pin_select(BYTE bAdcPin) + +This function MAY be used to select the IO pin to use as the active ADC input. + +Not applicable in battery monitoring mode. + +The IO pin MUST be enabled as an ADC input before calling ZW_ADC_enable(TRUE). + +Defined in: ZW_adcdriv_api.h + +Parameters: + +bAdcPin IN ADC_PIN0 Select I/O P3.4 as an ADC input ADC_PIN1 Select I/O P3.5 as an ADC input ADC_PIN2 Select I/O P3.6 as an ADC input ADC_PIN3 Select I/O P3.7 as an ADC input + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.05-zw_adc_threshold_mode_set.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.05-zw_adc_threshold_mode_set.md new file mode 100644 index 0000000..ac381d3 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.05-zw_adc_threshold_mode_set.md @@ -0,0 +1,22 @@ + +# 4.3.12.5 ZW_ADC_threshold_mode_set + +void ZW_ADC_threshold_mode_set(BYTE bThresMode) + +This function MAY be used to set the threshold mode of the ADC unit. The threshold mode controls when the ADC generates an interrupt request. + +Use ZW_ADC_threshold_set() to set the actual threshold level. + +Defined in: ZW_adcdriv_api.h + +Parameters: + +bThresMode ADC_THRES_UPPER Generate an interrupt request when input is above/equal to the threshold value + +ADC_THRES_LOWER Generate an interrupt request when input is below/equal to the threshold value Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.06-zw_adc_threshold_set.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.06-zw_adc_threshold_set.md new file mode 100644 index 0000000..2a78c3c --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.06-zw_adc_threshold_set.md @@ -0,0 +1,24 @@ + +# 4.3.12.6 ZW_ADC_threshold_set + +void ZW_ADC_threshold_set(WORD wThreshold) + +This function MAY be used to set the ADC threshold value. Depending on the threshold mode (set by ZW_ADC_threshold_mode_set) , the threshold value is used to trigger an interrupt when the sampled value is above/equal or below/equal the threshold value. + +The API ZW_ADC_ threshold_mode_set MUST be called before calling this function. + +Defined in: ZW_adcdriv_api.h + +Parameters: + +wThreshold IN 8-bit resolution Threshold value range is 0 .. 255 + +12-bit resolution Threshold value range is 0 .. 4095 + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.07-zw_adc_int_enable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.07-zw_adc_int_enable.md new file mode 100644 index 0000000..2ef8bc8 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.07-zw_adc_int_enable.md @@ -0,0 +1,24 @@ + +# 4.3.12.7 ZW_ADC_int_enable + +void ZW_ADC_int_enable(BYTE boEnable) + +Therefore, function MAY be used to enable or disable ADC interrupt requests. If enabled, an interrupt routine MUST be defined. The ADC interrupt is disabled by default. + +If ADC interrupts are enabled, the ADC interrupt flag MUST be reset by calling ZW_ADC_int_clear before returning from the interrupt routine. + +Defined in: ZW_adcdriv_api.h + +Parameters: + +boEnable IN TRUE Enable the ADC interrupt + +FALSE Disable the ADC interrupt + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.08-zw_adc_int_clear.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.08-zw_adc_int_clear.md new file mode 100644 index 0000000..106c2d4 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.08-zw_adc_int_clear.md @@ -0,0 +1,16 @@ + +# 4.3.12.8 ZW_ADC_int_clear + +void ZW_ADC_int_clear(void) + +If ADC interrupts are enabled, this function MUST be called before returning from the interrupt routine. + +Defined in: ZW_adcdriv_api.h + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.09-zw_adc_is_fired.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.09-zw_adc_is_fired.md new file mode 100644 index 0000000..c0998d7 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.09-zw_adc_is_fired.md @@ -0,0 +1,22 @@ + +# 4.3.12.9 ZW_ADC_is_fired + +BOOL ZW_ADC_is_fired(void) + +This function MAY be used to check if the most recent ADC conversion result meets the threshold criterion. + +Defined in: ZW_adcdriv_api.h + +Retrun value: + +BOOL TRUE The most recent conversion result meets the threshold criterion + +FALSE ADC conversion is not finished or the most recent conversion result does not meet the threshold criterion + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.10-zw_adc_result_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.10-zw_adc_result_get.md new file mode 100644 index 0000000..1bf801d --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.10-zw_adc_result_get.md @@ -0,0 +1,22 @@ + +# 4.3.12.10 ZW_ADC_result_get + +WORD ZW_ADC_result_get(void) + +This function MAY be used to read back the result of the most recent ADC conversion. The return value is an 8-bit or 12-bit integer depending on the ADC resolution mode. The value ADC_NOT_FINISHED may be returned in case the ADC conversion process is still running. + +Defined in: ZW_adcdriv_api.h + +Return value: + +WORD 8-bit resolution Return value range is 0 .. 255 in bits 0..7 The 8 MS bits of the return value MUST be ignored + +12-bit resolution Return value range is 0 .. 4095 in bits 0..11 The 4 MS bits of the return value MUST be ignored. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.11-zw_adc_buffer_enable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.11-zw_adc_buffer_enable.md new file mode 100644 index 0000000..2706bd4 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.11-zw_adc_buffer_enable.md @@ -0,0 +1,24 @@ + +# 4.3.12.11 ZW_ADC_buffer_enable + +void ZW_ADC_buffer_enable(BYTE boEnable) + +This function MAY be used to enable or disable an input buffer between the analog input and the ADC converter. The input buffer is disabled by default. + +The input buffer SHOULD be enabled when interfacing to a high impedance analog input. A high impedance analog input connected directly to the ADC converter may cause increased ADC settling time. + +Not applicable in battery monitoring mode. + +Defined in: ZW_adcdriv_api.h + +Parameters: + +boEnable TRUE Enable the input buffer FALSE Disable the input buffer + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.12-zw_adc_auto_zero_set.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.12-zw_adc_auto_zero_set.md new file mode 100644 index 0000000..7a1854d --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.12-zw_adc_auto_zero_set.md @@ -0,0 +1,26 @@ + +# 4.3.12.12 ZW_ADC_auto_zero_set + +void ZW_ADC_auto_zero_set(BYTE bAzpl) + +This function MAY be used to define the ADC sampling period. Default value is ADC_AZPL_128. It is RECOMMENDED to use longer sampling periods for high impedance analog inputs. + +Defined in: ZW_adcdriv_api.h + +Parameters: + +bAzpl ADC_AZPL_1024 Set the autozero period to 128us RECOMMENDED for high impedance analog inputs + +ADC_AZPL_512 Set the autozero period to 64us RECOMMENDED for medium to high impedance analog inputs. + +ADC_ZPL_256 Set the autozero period to 32us RECOMMENDED for medium to low impedance analog inputs. + +ADC_ZPL_128 Set the autozero period to 16us RECOMMENDED for low impedance analog inputs. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.13-zw_adc_resolution_set.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.13-zw_adc_resolution_set.md new file mode 100644 index 0000000..00146e0 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/04.03.12.13-zw_adc_resolution_set.md @@ -0,0 +1,28 @@ + +# 4.3.12.13 ZW_ADC_resolution_set + +void ZW_ADC_resolution_set(BYTE bReso) + +Therefore, function SHOULD be used to set the resolution of the ADC. The threshold value SHOULD also be updated when changing the ADC resolution. + +Apart from setting the resolution this function will, together with the auto zero period, also set the sampling rate. + +When resolution is ADC_8_BIT the sampling rate is 23.6k samples/s @autozero=128 17.1k samples/s @autozero=256 11.1k samples/s @autozero=512 6.5k samples/s @autozero=1024 + +When resolution is ADC_12_BIT the sampling rate is 10.9k samples/s @autozero=128 9.3k samples/s @autozero=256 7.2k samples/s @autozero=512 4.9k samples/s @autozero=1024 + +Defined in: ZW_adcdriv_api.h + +Parameters: + +bReso ADC_12_BIT Set the ADC resolution to 12 bits + +ADC_8_BIT Set the ADC resolution to 8 bits + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/index.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/index.md new file mode 100644 index 0000000..0228938 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.12-adc-interface-api/index.md @@ -0,0 +1,82 @@ + +# 4.3.12 ADC Interface API + +The ADC interface API provides access to an 8/12-bit ADC with input multiplexer. + +[Refer to [16] for a detailed description of the ADC hardware.](../../../08-references.md#8-references) + +[The ADC MAY be used for monitoring battery levels [15], voltages across various sensors etc. The ADC](../../../08-references.md#8-references) MAY be configured to generate an interrupt request if the measured voltage is above, below or equal to a threshold depending on the configuration settings. The ADC MAY use up to 4 GPIO as inputs depending on its configuration. Input pins that are not enabled MAY be used as GPIO's for by other peripherals. + +Three sources can work as voltage-references for the ADC, namely either the power-supply for the chip, an internal 1.2V voltage-reference or the P3.7 pin (ADC_PIN3). The maximum sample rate when in continuous conversion mode is 23.6k sample/s for 8 bit conversions and 10.9k sample/s for 12 bit conversions. + +The figures below show when the ADC interrupt is released dependent on, how the ADC threshold gradient is set: + +| Tim | | | | | +| --- | --- | --- | --- | --- | +| | | | | | +| | | | | | +| | | | | | + +Figure 10. Threshold Functionality when Threshold Gradient Set to High + +| Tim | | | | | +| --- | --- | --- | --- | --- | +| | | | | | +| | | | | | +| | | | | | + +Figure 11. Threshold Functionality when Threshold Gradient Set to Low The figure below shows how the connections to the ADC can be configured: + +ADC + +Comparator P3.7 Out P3.6 BG P3.5 P3.4 Buf. + +Figure 12. Configuration of Input Pins + +/************************************************* * To be placed in interrupt routine module **************************************************/ + +void adc_int (void) interrupt INUM_ADC { _push_(SFRPAGE); ZW_ADC_int_clear(); adc_triggered=TRUE; adc_value=ZW_ADC_result_get(); _pop_(SFRPAGE); } + +: + +/************************************************* * To be placed in applicationInitHW() **************************************************/ + +// Power up ADC and set ADC conversion mode, references, pins ZW_ADC_init(ADC_IO_MULTI_MODE,ADC_REF_U_VDD,ADC_REF_L_VSS,\ ADC_PIN1|ADC_PIN2); // Set auto zero period ZW_ADC_auto_zero_set(ADC_AZPL_128); // Set ADC resolution ZW_ADC_resolution_set(ADC_8_BIT); // Clear ADC interrupt flag ZW_ADC_int_clear(); // Enable ADC interrupt ZW_ADC_int_enable(TRUE); + +: /************************************************* * To be placed in applicationPoll() **************************************************/ + +if (state==powerUp) { // select ADC input pin if (measure==sensor1) { // sensor 1 is on ADC pin 1 ZW_ADC_pin_select(ADC_PIN1); // enable lower threshold ZW_ADC_threshold_mode_set(ADC_THRES_LOWER); // set threshold level to ~25% of VDD ZW_ADC_threshold_set(0x0040); } else { // sensor 2 is on ADC pin 2 ZW_ADC_pin_select(ADC_PIN2); // enable upper threshold ZW_ADC_threshold_mode_set(ADC_THRES_UPPER); // set threshold level to ~50% of VDD ZW_ADC_threshold_set(0x0080); } // Start ADC ZW_ADC_enable(TRUE); state=xxx; }: if (state==running) { // React on sampled ADC value if (adc_triggered) { if (measure==sensor1) do_something1(adc_value); else do_something2(adc_value); adc_triggered=FALSE; }: } + +Figure 13, ADC Code Sample Snippets Using an I/O as Input /************************************************* * To be placed in applicationInitHW() **************************************************/ + +// Set ADC to battery monitoring mode, other parameters are ignored ZW_ADC_init(ADC_BATT_SINGLE_MODE, 0, 0, 0); // Set auto zero period ZW_ADC_auto_zero_set(ADC_AZPL_128); // Set ADC resolution ZW_ADC_resolution_set(ADC_12_BIT); + +/************************************************* * To be placed in applicationPoll() **************************************************/ + +if (state==startBatteryVoltageMeasurement) { // Power up ADC ZW_ADC_power_enable(TRUE); // Start ADC ZW_ADC_enable(TRUE); state=awatingBatteryVoltageMeasurement; } + +: + +if ((state==awatingBatteryVoltageMeasurement) { battLevel=ZW_ADC_result_get(); if (battLevel!= ADC_NOT_FINISHED)) { // Calc battery level in mV (Vbg is the band gab voltage) battVol=(DWORD)Vbg*4096/(DWORD)battLevel // Return battery voltage in mV send(battVol); state=xxx; // Power down ADC ZW_ADC_power_enable(FALSE); } } Figure 14, ADC Code Sample Snippets Using Battery Monitoring Mode + +## Contents + +- [4.3.12.1 ZW_ADC_init](04.03.12.01-zw_adc_init.md) +- [4.3.12.2 ZW_ADC_power_enable](04.03.12.02-zw_adc_power_enable.md) +- [4.3.12.3 ZW_ADC_enable](04.03.12.03-zw_adc_enable.md) +- [4.3.12.4 ZW_ADC_pin_select](04.03.12.04-zw_adc_pin_select.md) +- [4.3.12.5 ZW_ADC_threshold_mode_set](04.03.12.05-zw_adc_threshold_mode_set.md) +- [4.3.12.6 ZW_ADC_threshold_set](04.03.12.06-zw_adc_threshold_set.md) +- [4.3.12.7 ZW_ADC_int_enable](04.03.12.07-zw_adc_int_enable.md) +- [4.3.12.8 ZW_ADC_int_clear](04.03.12.08-zw_adc_int_clear.md) +- [4.3.12.9 ZW_ADC_is_fired](04.03.12.09-zw_adc_is_fired.md) +- [4.3.12.10 ZW_ADC_result_get](04.03.12.10-zw_adc_result_get.md) +- [4.3.12.11 ZW_ADC_buffer_enable](04.03.12.11-zw_adc_buffer_enable.md) +- [4.3.12.12 ZW_ADC_auto_zero_set](04.03.12.12-zw_adc_auto_zero_set.md) +- [4.3.12.13 ZW_ADC_resolution_set](04.03.12.13-zw_adc_resolution_set.md) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.01-transmission.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.01-transmission.md new file mode 100644 index 0000000..53c4685 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.01-transmission.md @@ -0,0 +1,10 @@ + +# 4.3.13.1 Transmission + +An interrupt is released when D7 has been sent on the TxD pin. A new byte can be written to the buffer when the interrupt has been released. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.02-reception.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.02-reception.md new file mode 100644 index 0000000..58e3658 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.02-reception.md @@ -0,0 +1,12 @@ + +# 4.3.13.2 Reception + +The reception is activated by a falling edge on RxD. If the falling edge is not verified by the majority voting on the start bit, then the serial port stops reception and waits for another falling edge on RxD. When the MSB of the byte has been received a stop bit is expected. The first 2/3 of the stop bit is sampled and a majority decision is made on these samples. The interrupt will be released if the stop bit is recognized as high. + +When 2/3 of the stop bit has been received the serial port waits for another high-to-low transition (start bit) on the RxD pin. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.03-rs232.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.03-rs232.md new file mode 100644 index 0000000..4dbf578 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.03-rs232.md @@ -0,0 +1,19 @@ + +# 4.3.13.3 RS232 + +Connecting a RS232 level converter to the 2 pins of a UART interface makes the 500 Series Z-Wave SoC able to communicate according to the RS232 standard. + +| RS232 UART DEVICE | RxD TxD GND | +| --- | --- | + +| RxD RS232 TxD DRIVER | RxD TxD | +| --- | --- | +| | | + +Figure 16. RS232 Setup diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.04-integration.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.04-integration.md new file mode 100644 index 0000000..3f63555 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.04-integration.md @@ -0,0 +1,30 @@ + +# 4.3.13.4 Integration + +Before using the UARTx the UART should be initialized and mapped to the IO pins. This initialization should be performed in the initialization function ApplicationInitHW. The initialization and IO mapping is performed using the ZW_UARTx_init function. + +The use of the UART is typically performed in the ApplicationPoll. The UART is then polled and characters are received / transmitted. Alternatively, the UART can be serviced in an ISR, but this approach is often to slow for higher baudrates. + +A UART application typically writes a character or string to a teminal. This can be performed by initializing the modem as described above in ApplicationInitHW and then calling ZW_UARTx_tx_send_str(BYTE *str) for an entire string. The function wait until the UART is ready before sending each character. However in some cases it is not desirable to wait until the UART is ready before continuing code execution. In this case it is better to poll to see if the UART is ready and then transmit characters when the UART is ready. In this case a different set of functions are needed as given below. + +if (!ZW_UART0_tx_active_get()) { ZW_UART0_tx_send_str(); } + +Another possibility is to use the interrupt flags: + +if (ZW_UART0_tx_int_get()) { ZW_UART0_tx_int_clear(); ZW_UART0_tx_send_str(); } + +However the latter method has the disadvantage that it requires an initial write to the UART or else the first interrupt flag will not go high and the writing will never start. + +Another typical UART application is to receive a character to the 500-series Z-Wave SoC. Similarly as for the TX setup, it is possible to poll for a new character before reading it. + +An example of the preferred solution to receive characters is given below: + +if (ZW_UART0_rx_int_get()) { ZW_UART0_rx_int_clear(); // Clear flag right after detection ch = ZW_UART0_rx_data_get(); // Where ch is of the type BYTE... } Note: It is important to clear the interrupt flag as fast as possible after detecting the interrupt flag (even before reading data). Omitting to do this may lead to loss of data as the interrupt flag may trigger again before the flag is cleared. This is especially a concern at high baudrates. + +The serial interface API handles transfer of data via the serial interfaces using the 500 Series Z-Wave SoC built-in UART0 and UART1. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.05-operation.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.05-operation.md new file mode 100644 index 0000000..570292f --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.05-operation.md @@ -0,0 +1,10 @@ + +# 4.3.13.5 Operation + +Data to be transmitted is written to a UART data register, one byte at the time and data received is read from a SPI data register one byte at the time. A UART interrupt can be issued when the UART controller has transferred a byte on the UART interface. This API supports transmissions of either a single byte, or a data string. The received characters are read by the application one-by-one. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.06-zw_uart0_init-zw_uart1_init.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.06-zw_uart0_init-zw_uart1_init.md new file mode 100644 index 0000000..0ce32d5 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.06-zw_uart0_init-zw_uart1_init.md @@ -0,0 +1,30 @@ + +# 4.3.13.6 ZW_UART0_init / ZW_UART1_init + +void ZW_UART0_init(WORD bBaudRate, BYTE bEnableTx, BYTE bEnableRx) / void ZW_UART1_init(WORD bBaudRate, BYTE bEnableTx, BYTE bEnableRx) + +Initializes the 500 Series Z-Wave SoC built-in UARTx to support ZM5101 and SD3502. Using ZM5202 requires that the NVR uart pin swap bit is set in the NVR to map to correct pin configuration. The function should be called in the ApplicationInitHW() so the ports are mapped correctly when the chip starts up. + +The init functions optionally enable/disable UARTx transmit and/or receive, clears the rx and tx interrupt flags and sets the specified baud rate. + +Defined in: ZW_uart_api.h + +Parameters: + + Valid values: 96 9.6kbaud, bBaudRate IN Baud Rate / 100  144 14.4kbaud,  192 19.2kbaud,  384 38.4kbaud,  576 57.6kbaud,  1152 115.2kbaud,  2304 230.4kbaud + +bEnableTx IN TRUE Enable UARTx transmitter and allocate TxD pin as follows: UART0 TxD is allocated on P2.1 UART1 TxD is allocated on P3.1 + +FALSE Disable UARTx Transmitter and de- allocate TxD pin + +bEnableRx IN TRUE Enable UARTx receiver and allocate RxD pin as follows: UART0 RxD is allocated on P2.0 UART1 RxD is allocated on P3.0 + +FALSE Disable UARTx receiver and de-allocate RxD pin + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.07-zw_uart0_rx_data_get-zw_uart1_rx_data_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.07-zw_uart0_rx_data_get-zw_uart1_rx_data_get.md new file mode 100644 index 0000000..f34ba21 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.07-zw_uart0_rx_data_get-zw_uart1_rx_data_get.md @@ -0,0 +1,22 @@ + +# 4.3.13.7 ZW_UART0_rx_data_get / ZW_UART1_rx_data_get + +BYTE ZW_UART0_rx_data_get(void) / BYTE ZW_UART1_rx_data_get(void) + +[This function returns the last received byte from UARTx. The UART should be polled using the ZW_UART0_rx_int_get / ZW_UART1_rx_int_get](04.03.13.19-zw_uart0_rx_int_get-zw_uart1_rx_int_get.md#431319-zw_uart0_rx_int_get-zw_uart1_rx_int_get) to see whether a new byte is ready before calling this function. + +[The function does not wait for a byte to be received but returns immediately. The alternative functions ZW_UART0_rx_data_wait_get / ZW_UART1_rx_data_wait_get](04.03.13.08-zw_uart0_rx_data_wait_get-zw_uart1_rx_data_wait_get.md#43138-zw_uart0_rx_data_wait_get-zw_uart1_rx_data_wait_get) waits until a byte is received before returning. + +Defined in: ZW_uart_api.h + +Return value: + +BYTE Received data. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.08-zw_uart0_rx_data_wait_get-zw_uart1_rx_data_wait_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.08-zw_uart0_rx_data_wait_get-zw_uart1_rx_data_wait_get.md new file mode 100644 index 0000000..d0c2577 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.08-zw_uart0_rx_data_wait_get-zw_uart1_rx_data_wait_get.md @@ -0,0 +1,20 @@ + +# 4.3.13.8 ZW_UART0_rx_data_wait_get / ZW_UART1_rx_data_wait_get + +BYTE ZW_UART0_rx_data_wait_get(void) / BYTE ZW_UART1_rx_data_wait_get(void) + +Returns a byte from the UARTx receiver. If no byte is available the function waits until data has been received. This function should be used with [extreme caution as it may freeze the system if no character](04.03.13.19-zw_uart0_rx_int_get-zw_uart1_rx_int_get.md#431319-zw_uart0_rx_int_get-zw_uart1_rx_int_get) [is received. In normal cases it is better to use polling,](04.03.13.07-zw_uart0_rx_data_get-zw_uart1_rx_data_get.md#43137-zw_uart0_rx_data_get-zw_uart1_rx_data_get) [ZW_UART0_rx_int_get / ZW_UART1_rx_int_get ,](04.03.13.19-zw_uart0_rx_int_get-zw_uart1_rx_int_get.md#431319-zw_uart0_rx_int_get-zw_uart1_rx_int_get) [to check if a new byte is received and then ZW_UART0_rx_data_get / ZW_UART1_rx_data_get](04.03.13.07-zw_uart0_rx_data_get-zw_uart1_rx_data_get.md#43137-zw_uart0_rx_data_get-zw_uart1_rx_data_get) to get the byte. + +Defined in: ZW_uart_api.h + +Return value: + +BYTE Received data. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.09-zw_uart0_tx_active_get-zw_uart1_tx_active_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.09-zw_uart0_tx_active_get-zw_uart1_tx_active_get.md new file mode 100644 index 0000000..262f3c3 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.09-zw_uart0_tx_active_get-zw_uart1_tx_active_get.md @@ -0,0 +1,22 @@ + +# 4.3.13.9 ZW_UART0_tx_active_get / ZW_UART1_tx_active_get + +BYTE ZW_UART0_tx_active_get(void) / BYTE ZW_UART1_tx_active_get(void) + +Read the UARTx send data status. The function returns TRUE if the UART is currently busy transmitting [data. The function is typically used in a polled TX setup to check whether the UART is ready before](04.03.13.10-zw_uart0_tx_data_set-zw_uart1_tx_data_set.md#431310-zw_uart0_tx_data_set-zw_uart1_tx_data_set) sending the next character using [ZW_UART0_tx_data_set / ZW_UART1_tx_data_set .](04.03.13.10-zw_uart0_tx_data_set-zw_uart1_tx_data_set.md#431310-zw_uart0_tx_data_set-zw_uart1_tx_data_set) + +Defined in: ZW_uart_api.h + +Return value: + +BYTE non-zero UARTx Transmitter is busy + +zero (0x00) UARTx Transmitter is idle + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.10-zw_uart0_tx_data_set-zw_uart1_tx_data_set.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.10-zw_uart0_tx_data_set-zw_uart1_tx_data_set.md new file mode 100644 index 0000000..e894d50 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.10-zw_uart0_tx_data_set-zw_uart1_tx_data_set.md @@ -0,0 +1,22 @@ + +# 4.3.13.10 ZW_UART0_tx_data_set / ZW_UART1_tx_data_set + +void ZW_UART0_tx_data_set(BYTE data) / void ZW_UART1_tx_data_set(BYTE data) + +Function sets the transmit data register + +This function does not wait until UARTx transmitter is idle before it sends the new data. The function [should not be called unless the UART is ready. To check if the UART is ready is done using the ZW_UART0_tx_active_get / ZW_UART1_tx_active_get . Data send to the UART when it is not ready](04.03.13.09-zw_uart0_tx_active_get-zw_uart1_tx_active_get.md#43139-zw_uart0_tx_active_get-zw_uart1_tx_active_get) will be ignored. + +Defined in: ZW_uart_api.h + +Parameters: + +data IN Data to send. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.11-zw_uart0_tx_send_num-zw_uart1_tx_send_num.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.11-zw_uart0_tx_send_num-zw_uart1_tx_send_num.md new file mode 100644 index 0000000..415492b --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.11-zw_uart0_tx_send_num-zw_uart1_tx_send_num.md @@ -0,0 +1,22 @@ + +# 4.3.13.11 ZW_UART0_tx_send_num / ZW_UART1_tx_send_num + +void ZW_UART0_tx_send_num(BYTE data) / void ZW_UART1_tx_send_num(BYTE data) + +Converts a byte to a two-byte hexadecimal ASCII representation, and transmits it over the UART. This function waits until UARTx transmitter is idle before it sends the new data. The function does not wait until the last data byte has been sent. + +See also: [ZW_UART0_tx_send_str / ZW_UART1_tx_send_str](04.03.13.12-zw_uart0_tx_send_str-zw_uart1_tx_send_str.md#431312-zw_uart0_tx_send_str-zw_uart1_tx_send_str) + +Defined in: ZW_uart_api.h + +Parameters: + +data IN Byte value to be converted into two-byte hexadecimal ASCII respresentation and transmitted via the UART. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.12-zw_uart0_tx_send_str-zw_uart1_tx_send_str.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.12-zw_uart0_tx_send_str-zw_uart1_tx_send_str.md new file mode 100644 index 0000000..45ad01d --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.12-zw_uart0_tx_send_str-zw_uart1_tx_send_str.md @@ -0,0 +1,22 @@ + +# 4.3.13.12 ZW_UART0_tx_send_str / ZW_UART1_tx_send_str + +void ZW_UART0_tx_send_str(BYTE* pStr) / void ZW_UART1_tx_send_str(BYTE* pStr) + +Transmit a null terminated string over UARTx. The null data is not transmitted. This function waits until UARTx transmitter is idle before it sends the first data byte data. The function does not wait until the last data byte has been sent. + +See also: [ZW_UART0_tx_send_num / ZW_UART1_tx_send_num](04.03.13.11-zw_uart0_tx_send_num-zw_uart1_tx_send_num.md#431311-zw_uart0_tx_send_num-zw_uart1_tx_send_num) + +Defined in: ZW_uart_api.h + +Parameters: + +pStr IN Pointer to zero terminated string to be transmitted via the UART. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.13-zw_uart0_int_enable-zw_uart1_int_enable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.13-zw_uart0_int_enable-zw_uart1_int_enable.md new file mode 100644 index 0000000..84f5c8b --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.13-zw_uart0_int_enable-zw_uart1_int_enable.md @@ -0,0 +1,16 @@ + +# 4.3.13.13 ZW_UART0_INT_ENABLE / ZW_UART1_INT_ENABLE + +ZW_UART0_INT_ENABLE / ZW_UART1_INT_ENABLE + +This macros enables UARTx interrupts + +Defined in: ZW_uart_api.h + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.14-zw_uart0_int_disable-zw_uart1_int_disable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.14-zw_uart0_int_disable-zw_uart1_int_disable.md new file mode 100644 index 0000000..c7c9a09 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.14-zw_uart0_int_disable-zw_uart1_int_disable.md @@ -0,0 +1,16 @@ + +# 4.3.13.14 ZW_UART0_INT_DISABLE / ZW_UART1_INT_DISABLE + +ZW_UART0_INT_DISABLE / ZW_UART1_INT_DISABLE + +This macros disables UARTx interrupts + +Defined in: ZW_uart_api.h + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.15-zw_uart0_tx_send_nl-zw_uart1_tx_send_nl.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.15-zw_uart0_tx_send_nl-zw_uart1_tx_send_nl.md new file mode 100644 index 0000000..2207e63 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.15-zw_uart0_tx_send_nl-zw_uart1_tx_send_nl.md @@ -0,0 +1,18 @@ + +# 4.3.13.15 ZW_UART0_tx_send_nl / ZW_UART1_tx_send_nl + +void ZW_UART0_tx_send_nl(void) / void ZW_UART1_tx_send_nl(void) + +Transmit “new line” sequence (CR + LF) over UARTx . + +[See also:](04.03.13.12-zw_uart0_tx_send_str-zw_uart1_tx_send_str.md#431312-zw_uart0_tx_send_str-zw_uart1_tx_send_str) [ZW_UART0_tx_send_num / ZW_UART1_tx_send_num](04.03.13.11-zw_uart0_tx_send_num-zw_uart1_tx_send_num.md#431311-zw_uart0_tx_send_num-zw_uart1_tx_send_num) and [ZW_UART0_tx_send_str / ZW_UART1_tx_send_str](04.03.13.12-zw_uart0_tx_send_str-zw_uart1_tx_send_str.md#431312-zw_uart0_tx_send_str-zw_uart1_tx_send_str) + +Defined in: ZW_uart_api.h + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.16-zw_uart0_tx_int_clear-zw_uart1_tx_int_clear.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.16-zw_uart0_tx_int_clear-zw_uart1_tx_int_clear.md new file mode 100644 index 0000000..337fb34 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.16-zw_uart0_tx_int_clear-zw_uart1_tx_int_clear.md @@ -0,0 +1,18 @@ + +# 4.3.13.16 ZW_UART0_tx_int_clear / ZW_UART1_tx_int_clear + +void ZW_UART0_tx_int_clear(void) / void ZW_UART1_tx_int_clear(void) + +Clear the UARTx transmit interrupt/done flag. + +See also: [ZW_UART0_tx_int_get / ZW_UART1_tx_int_get](04.03.13.18-zw_uart0_tx_int_get-zw_uart1_tx_int_get.md#431318-zw_uart0_tx_int_get-zw_uart1_tx_int_get) + +Defined in: ZW_uart_api.h + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.17-zw_uart0_rx_int_clear-zw_uart1_rx_int_clear.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.17-zw_uart0_rx_int_clear-zw_uart1_rx_int_clear.md new file mode 100644 index 0000000..fe0d90c --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.17-zw_uart0_rx_int_clear-zw_uart1_rx_int_clear.md @@ -0,0 +1,18 @@ + +# 4.3.13.17 ZW_UART0_rx_int_clear / ZW_UART1_rx_int_clear + +void ZW_UART0_rx_int_clear(void) / void ZW_UART1_rx_int_clear(void) + +Clear the UARTx receiver interrupt/ready flag. + +See also: [ZW_UART0_rx_int_get / ZW_UART1_rx_int_get](04.03.13.19-zw_uart0_rx_int_get-zw_uart1_rx_int_get.md#431319-zw_uart0_rx_int_get-zw_uart1_rx_int_get) + +Defined in: ZW_uart_api.h + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.18-zw_uart0_tx_int_get-zw_uart1_tx_int_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.18-zw_uart0_tx_int_get-zw_uart1_tx_int_get.md new file mode 100644 index 0000000..cc96e6c --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.18-zw_uart0_tx_int_get-zw_uart1_tx_int_get.md @@ -0,0 +1,24 @@ + +# 4.3.13.18 ZW_UART0_tx_int_get / ZW_UART1_tx_int_get + +BYTE ZW_UART0_tx_int_get(void) / BYTE ZW_UART1_tx_int_get(void) + +[Returns the state of the Transmitter done/interrupt flag. This function has limited used and in practice it is preferred to check if the UART is ready using the ZW_UART0_tx_active_get / ZW_UART1_tx_active_get function in a polled configuration. The ZW_UART0_tx_active_get / ZW_UART1_tx_active_get](04.03.13.09-zw_uart0_tx_active_get-zw_uart1_tx_active_get.md#43139-zw_uart0_tx_active_get-zw_uart1_tx_active_get) does not require the interrupt flag to be cleared. + +See also : [ZW_UART0_tx_int_clear / ZW_UART1_tx_int_clear](04.03.13.16-zw_uart0_tx_int_clear-zw_uart1_tx_int_clear.md#431316-zw_uart0_tx_int_clear-zw_uart1_tx_int_clear) + +Defined in: ZW_uart_api.h + +Return value: + +BYTE non-zero UARTx Transmitter done/interrupt flag is set + +zero (0x00) UARTx Transmitter done/interrupt flag is cleared + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.19-zw_uart0_rx_int_get-zw_uart1_rx_int_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.19-zw_uart0_rx_int_get-zw_uart1_rx_int_get.md new file mode 100644 index 0000000..f440f85 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.19-zw_uart0_rx_int_get-zw_uart1_rx_int_get.md @@ -0,0 +1,24 @@ + +# 4.3.13.19 ZW_UART0_rx_int_get / ZW_UART1_rx_int_get + +BYTE ZW_UART0_rx_int_get(void) / BYTE ZW_UART1_rx_int_get(void) + +Returns the state of the receiver data ready/interrupt flag. The flag goes high when a new byte has been received. The flag should be cleared as soon as possible after detection in order to minimize risk of data [loss (especially at high baud rates). Clearing the interrupt flag is done using the function ZW_UART0_rx_int_clear / ZW_UART1_rx_int_clear](04.03.13.17-zw_uart0_rx_int_clear-zw_uart1_rx_int_clear.md#431317-zw_uart0_rx_int_clear-zw_uart1_rx_int_clear) [. When a new byte is detected the byte can be read using the ZW_UART0_rx_data_get / ZW_UART1_rx_data_get function.](04.03.13.07-zw_uart0_rx_data_get-zw_uart1_rx_data_get.md#43137-zw_uart0_rx_data_get-zw_uart1_rx_data_get) + +[See also:](04.03.13.07-zw_uart0_rx_data_get-zw_uart1_rx_data_get.md#43137-zw_uart0_rx_data_get-zw_uart1_rx_data_get) [ZW_UART0_rx_int_clear / ZW_UART1_rx_int_clear](04.03.13.17-zw_uart0_rx_int_clear-zw_uart1_rx_int_clear.md#431317-zw_uart0_rx_int_clear-zw_uart1_rx_int_clear) and [ZW_UART0_rx_data_get / ZW_UART1_rx_data_get](04.03.13.07-zw_uart0_rx_data_get-zw_uart1_rx_data_get.md#43137-zw_uart0_rx_data_get-zw_uart1_rx_data_get) + +Defined in: ZW_uart_api.h + +Return value: + +BYTE non-zero UARTx Receiver data ready/interrupt flag is set + +zero (0x00) UARTx receiver data ready/interrupt flag is cleared + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.20-zw_uart0_rx_enable-zw_uart1_rx_enable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.20-zw_uart0_rx_enable-zw_uart1_rx_enable.md new file mode 100644 index 0000000..e69d0e8 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.20-zw_uart0_rx_enable-zw_uart1_rx_enable.md @@ -0,0 +1,22 @@ + +# 4.3.13.20 ZW_UART0_rx_enable / ZW_UART1_rx_enable + +void ZW_UART0_rx_enable(BYTE bState) / void ZW_UART1_rx_enable(BYTE bState) + +This function is used to enable or disable the UARTx Rx function in runtime. Use the function ZW_UARTx_init to set the initial state of the Rx function. When enabling the UARTx Rx function the UARTx Rx pin will become an intput. + +Defined in: ZW_uart_api.h + +Parameters: + +bState IN TRUE UARTx Rx enabled + +FALSE UARTx Rx disabled + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.21-zw_uart0_tx_enable-zw_uart1_tx_enable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.21-zw_uart0_tx_enable-zw_uart1_tx_enable.md new file mode 100644 index 0000000..b5b8b01 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/04.03.13.21-zw_uart0_tx_enable-zw_uart1_tx_enable.md @@ -0,0 +1,22 @@ + +# 4.3.13.21 ZW_UART0_tx_enable / ZW_UART1_tx_enable + +void ZW_UART0_tx_enable(BYTE bState) / void ZW_UART1_tx_enable(BYTE bState) + +This function is used to enable or disable the UARTx TX function in runtime. Use the function ZW_UARTx_init to set the initial state of the Rx function. When enabling the UARTx Tx function the UARTx Tx pin will become an output. + +Defined in: ZW_uart_api.h + +Parameters: + +bState IN TRUE UARTx Tx enabled + +FALSE UARTx Tx disabled + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/index.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/index.md new file mode 100644 index 0000000..482dfdb --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.13-uart-interface-api/index.md @@ -0,0 +1,47 @@ + +# 4.3.13 UART Interface API + +The UART (Universal Asynchronous Receiver Transmitter) interface is for serial communication with external devices such as PC’s, host controllers etc. The two UART interfaces transmits data in an asynchronous way, and is a two-way communication protocol, using 2 pins each as a communications means: TxD and RxD. The two pins can be enabled and disabled individually. If only using RX mode the TxD pin can be used as general IO pins and vice versa. The UART’s use dedicated timers and do not take up any 8051 timer resources. + +Since the two UART’s are identical the description of each function is collapsed using the notation UARTx, where x is either 0 or 1. + +The UARTx supports full duplex and can operate with the baud rates between 9.6kbaud and 230.4 kbaud. (See under ZW_UARTx_init) + +The interface operates with 8 bit words, one start bit (low), one stop bit (high) and no parity. This setup is hardwired and can not be changed. + +The UARTx shifts data in/out in the following order: start bit, data bits (LSB first) and stop bit. The figure below gives the waveform of a serial byte. + +| D0 | D1 | D2 | D3 | D4 | D5 | D6 | D7 | +| --- | --- | --- | --- | --- | --- | --- | --- | + +Figure 15. Serial Waveform + +## Contents + +- [4.3.13.1 Transmission](04.03.13.01-transmission.md) +- [4.3.13.2 Reception](04.03.13.02-reception.md) +- [4.3.13.3 RS232](04.03.13.03-rs232.md) +- [4.3.13.4 Integration](04.03.13.04-integration.md) +- [4.3.13.5 Operation](04.03.13.05-operation.md) +- [4.3.13.6 ZW_UART0_init / ZW_UART1_init](04.03.13.06-zw_uart0_init-zw_uart1_init.md) +- [4.3.13.7 ZW_UART0_rx_data_get / ZW_UART1_rx_data_get](04.03.13.07-zw_uart0_rx_data_get-zw_uart1_rx_data_get.md) +- [4.3.13.8 ZW_UART0_rx_data_wait_get / ZW_UART1_rx_data_wait_get](04.03.13.08-zw_uart0_rx_data_wait_get-zw_uart1_rx_data_wait_get.md) +- [4.3.13.9 ZW_UART0_tx_active_get / ZW_UART1_tx_active_get](04.03.13.09-zw_uart0_tx_active_get-zw_uart1_tx_active_get.md) +- [4.3.13.10 ZW_UART0_tx_data_set / ZW_UART1_tx_data_set](04.03.13.10-zw_uart0_tx_data_set-zw_uart1_tx_data_set.md) +- [4.3.13.11 ZW_UART0_tx_send_num / ZW_UART1_tx_send_num](04.03.13.11-zw_uart0_tx_send_num-zw_uart1_tx_send_num.md) +- [4.3.13.12 ZW_UART0_tx_send_str / ZW_UART1_tx_send_str](04.03.13.12-zw_uart0_tx_send_str-zw_uart1_tx_send_str.md) +- [4.3.13.13 ZW_UART0_INT_ENABLE / ZW_UART1_INT_ENABLE](04.03.13.13-zw_uart0_int_enable-zw_uart1_int_enable.md) +- [4.3.13.14 ZW_UART0_INT_DISABLE / ZW_UART1_INT_DISABLE](04.03.13.14-zw_uart0_int_disable-zw_uart1_int_disable.md) +- [4.3.13.15 ZW_UART0_tx_send_nl / ZW_UART1_tx_send_nl](04.03.13.15-zw_uart0_tx_send_nl-zw_uart1_tx_send_nl.md) +- [4.3.13.16 ZW_UART0_tx_int_clear / ZW_UART1_tx_int_clear](04.03.13.16-zw_uart0_tx_int_clear-zw_uart1_tx_int_clear.md) +- [4.3.13.17 ZW_UART0_rx_int_clear / ZW_UART1_rx_int_clear](04.03.13.17-zw_uart0_rx_int_clear-zw_uart1_rx_int_clear.md) +- [4.3.13.18 ZW_UART0_tx_int_get / ZW_UART1_tx_int_get](04.03.13.18-zw_uart0_tx_int_get-zw_uart1_tx_int_get.md) +- [4.3.13.19 ZW_UART0_rx_int_get / ZW_UART1_rx_int_get](04.03.13.19-zw_uart0_rx_int_get-zw_uart1_rx_int_get.md) +- [4.3.13.20 ZW_UART0_rx_enable / ZW_UART1_rx_enable](04.03.13.20-zw_uart0_rx_enable-zw_uart1_rx_enable.md) +- [4.3.13.21 ZW_UART0_tx_enable / ZW_UART1_tx_enable](04.03.13.21-zw_uart0_tx_enable-zw_uart1_tx_enable.md) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.01-zw_timer0_init.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.01-zw_timer0_init.md new file mode 100644 index 0000000..dc3a757 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.01-zw_timer0_init.md @@ -0,0 +1,28 @@ + +# 4.3.14.1 ZW_TIMER0_init + +void ZW_TIMER0_init(BYTE bValue) + +This function SHOULD be used to initialize Timer0. + +Defined in: ZW_appltimer_api.h + +Parameters: + +bValue Timer0 Mode: + +TIMER_MODE_0 13 bit mode. The 5 lower bits of the low register acts as a 5 bit prescaler for the high byte + +TIMER_MODE_1 16 bit mode + +TIMER_MODE_2 8bit - auto reload mode. The 8bit timer runs in the high byte register. After an overflow the low byte register value is loaded into the high byte register + +TIMER_MODE_3 Timer 0 division mode. Timer 0 is divided into two 8 bit timers, one controlled by the Timer 0 control bits and the other controlled by the Timer 1 control bits. Warning: Enabling this will stop Timer 1 + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.02-zw_timer1_init.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.02-zw_timer1_init.md new file mode 100644 index 0000000..cd7dcc7 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.02-zw_timer1_init.md @@ -0,0 +1,28 @@ + +# 4.3.14.2 ZW_TIMER1_init + +void ZW_TIMER1_init(BYTE bValue) + +This function SHOULD be used to initialize Timer1. + +Defined in: ZW_appltimer_api.h + +Parameters: + +bValue Timer1 Mode: + +TIMER_MODE_0 13 bit mode. The 5 lower bits of the low register acts as a 5 bit prescaler for the high byte + +TIMER_MODE_1 16 bit mode (no reload) + +TIMER_MODE_2 8bit - auto reload mode. The 8bit timer runs in the high byte register. After an overflow the low byte register value is loaded into the high byte register + +TIMER_MODE_3 Disabled. Warning: If Timer0 uses mode 3 then Timer1 is stopped. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.03-zw_timer0_int_clear-zw_timer1_int_clear.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.03-zw_timer0_int_clear-zw_timer1_int_clear.md new file mode 100644 index 0000000..92a99f6 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.03-zw_timer0_int_clear-zw_timer1_int_clear.md @@ -0,0 +1,18 @@ + +# 4.3.14.3 ZW_TIMER0_INT_CLEAR / ZW_TIMER1_INT_CLEAR + +ZW_TIMERx_INT_CLEAR + +This macro SHOULD be used to clear timer interrupt/overflow flags. + +Mode0-2: This macro clears the TIMER0/TIMER1 interrupt/overflow flag. Mode3: This macro clears the TIMER0/TIMER1 high counter interrupt/overflow flag. + +Defined in: ZW_appltimer_api.h + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.04-zw_timer0_int_enable-zw_timer1_int_enable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.04-zw_timer0_int_enable-zw_timer1_int_enable.md new file mode 100644 index 0000000..9c05be3 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.04-zw_timer0_int_enable-zw_timer1_int_enable.md @@ -0,0 +1,22 @@ + +# 4.3.14.4 ZW_TIMER0_INT_ENABLE / ZW_TIMER1_INT_ENABLE + +ZW_TIMERx_INT_ENABLE(BYTE bState) + +This macro SHOULD be used to enable or disable the Timer0/Timer1 interrupt. + +Defined in: ZW_appltimer_api.h + +Parameters: + +bState IN TRUE Mode 0-2: TIMER0/TIMER1 interrupt is enabled Mode 3: TIMER0/TIMER1 high counter interrupt is enabled + +FALSE Mode 0-2: TIMER0/TIMER1 interrupt is disabled Mode 3: TIMER0/TIMER1 high counter interrupt is disabled + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.05-zw_timer0_enable-zw_timer1_enable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.05-zw_timer0_enable-zw_timer1_enable.md new file mode 100644 index 0000000..5d208ae --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.05-zw_timer0_enable-zw_timer1_enable.md @@ -0,0 +1,22 @@ + +# 4.3.14.5 ZW_TIMER0_ENABLE / ZW_TIMER1_ENABLE + +ZW_TIMERx_ENABLE(BYTE bState) + +This macro SHOULD be used to enable or halt Timer0/Timer1. + +Defined in: ZW_appltimer_api.h + +Parameters: + +bState IN TRUE Mode 0-2: TIMER0/TIMER1 runs Mode 3: Timer0/Timer1 high counter runs + +FALSE Mode 0-2: TIMER0/TIMER1 is halted Mode 3: Timer0/timer1 high counter is halted + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.06-zw_timer0_ext_clk-zw_timer1_ext_clk.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.06-zw_timer0_ext_clk-zw_timer1_ext_clk.md new file mode 100644 index 0000000..dc6eb0c --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.06-zw_timer0_ext_clk-zw_timer1_ext_clk.md @@ -0,0 +1,22 @@ + +# 4.3.14.6 ZW_TIMER0_ext_clk / ZW_TIMER1_ext_clk + +ZW_TIMERx_ext_clk(BYTE bState) + +This function SHOULD be used to set the clock source for timer0/timer1 + +Defined in: ZW_appltimer_api.h + +Parameters: + +bState IN TRUE Timer0 runs on external clock (falling edge) of P3.4. Timer1 runs on external clock (falling edge) of P3.5. (synchronized to the system clock) + +FALSE Timer0/Timer1 runs on system clock (divided by 2) - default value after reset + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.07-zw_timer0_lowbyte_set-zw_timer1_lowbyte_set.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.07-zw_timer0_lowbyte_set-zw_timer1_lowbyte_set.md new file mode 100644 index 0000000..623a295 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.07-zw_timer0_lowbyte_set-zw_timer1_lowbyte_set.md @@ -0,0 +1,22 @@ + +# 4.3.14.7 ZW_TIMER0_LOWBYTE_SET / ZW_TIMER1_LOWBYTE_SET + +ZW_TIMERx_LOWBYTE_SET (BYTE bValue) + +This macro SHOULD be used to set the timer0/timer1 low byte value, see below. + +Defined in: ZW_appltimer_api.h + +Parameters: + +bValue IN The input value depends on the chosen mode: + +Mode0: Lower 5 bits sets the prescaler value for the 13 bit timer Mode1: Sets the lower 8 bits of the 16 bit timer Mode2: N.A. Mode3: N.A. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.08-zw_timer0_highbyte_set-zw_timer1_highbyte_set.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.08-zw_timer0_highbyte_set-zw_timer1_highbyte_set.md new file mode 100644 index 0000000..8adde85 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.08-zw_timer0_highbyte_set-zw_timer1_highbyte_set.md @@ -0,0 +1,22 @@ + +# 4.3.14.8 ZW_TIMER0_HIGHBYTE_SET / ZW_TIMER1_HIGHBYTE_SET + +ZW_TIMERx_HIGHBYTE_SET (BYTE bValue) + +This macro SHOULD be used to set the timer0/timer1 high byte value, see below. + +Defined in: ZW_appltimer_api.h + +Parameters: + +bValue IN The input value depends on the chosen mode: + +Mode0: Sets the 8 bit timer value Mode1: Sets the upper 8 bits of the 16 bit timer Mode2: Sets the 8 bit reload value of the 8 bit timer0 Mode3: N.A. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.09-zw_timer0_highbyte_get-zw_timer1_highbyte_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.09-zw_timer0_highbyte_get-zw_timer1_highbyte_get.md new file mode 100644 index 0000000..575d8bf --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.09-zw_timer0_highbyte_get-zw_timer1_highbyte_get.md @@ -0,0 +1,22 @@ + +# 4.3.14.9 ZW_TIMER0_HIGHBYTE_GET / ZW_TIMER1_HIGHBYTE_GET + +BYTE ZW_TIMERx_HIGHBYTE_GET + +This macro MAY be used to query the timer0/timer1 high register value + +Defined in: ZW_appltimer_api.h + +Return value: + +BYTE The return value depends on the chosen mode: + +Mode0: 8 bit timer value Mode1: upper 8 bits of the 16 bit timer Mode2: 8 bit timer value Mode3: N.A. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.10-zw_timer0_lowbyte_get-zw_timer1_lowbyte_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.10-zw_timer0_lowbyte_get-zw_timer1_lowbyte_get.md new file mode 100644 index 0000000..5340b8c --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.10-zw_timer0_lowbyte_get-zw_timer1_lowbyte_get.md @@ -0,0 +1,22 @@ + +# 4.3.14.10 ZW_TIMER0_LOWBYTE_GET / ZW_TIMER1_LOWBYTE_GET + +BYTE ZW_TIMERx_LOWBYTE_GET + +This macro MAY be used to query the timer0/timer1 timer low register value + +Defined in: ZW_appltimer_api.h + +Return value: + +BYTE The return value depends on the chosen mode: + +Mode0: 5 bit prescaler value for the 13 bit timer. (lower 5 bits) Mode1: lower 8 bits of the 16 bit timer Mode2: 8 bit timer value Mode3: N.A. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.11-zw_timer0_word_get-zw_timer1_word_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.11-zw_timer0_word_get-zw_timer1_word_get.md new file mode 100644 index 0000000..71cb473 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.11-zw_timer0_word_get-zw_timer1_word_get.md @@ -0,0 +1,20 @@ + +# 4.3.14.11 ZW_TIMER0_word_get / ZW_TIMER1_word_get + +WORD ZW ZW_TIMERx_word_get (void) + +This function MAY be used to query the two 8 bit timer0/timer1 register values as one 16 bit value. Used when timer0/timer1 is set in mode 1. + +Defined in: ZW_appltimer_api.h + +Return value: + +WORD 16bit timer value + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.12-zw_gptimer_init.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.12-zw_gptimer_init.md new file mode 100644 index 0000000..c1d52e1 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.12-zw_gptimer_init.md @@ -0,0 +1,36 @@ + +# 4.3.14.12 ZW_GPTIMER_init + +void ZW_GPTIMER_init(BYTE bValue) + +This function SHOULD be used to initialize the GPTimer. Calling ZW_GPTIMER_init() will disable the PWM, since the GP Timer and the PWM share the same hardware resources. The GPTimer is hardcoded to count down. + +Defined in: ZW_appltimer_api.h + +Parameters: + +bValue IN Bit mask: + +Prescaler setting + +When set: Timer counter runs @ PRESCALER_BIT 32MHz / 1024 = 31.25kHz + +When nor set: Timer counter runs @ 32MHz / 8 = 4MHz Reload Timer + +RELOAD_BIT When set: The GPTimer counter registers are reloaded with the reload register value upon underrun. + +When not set: The GPTimer stops upon underrun. + +Immediate write + +IMWR_BIT When set: The GP Timer counters will be loaded with the value of the reload register when it is disabled or immediately when the reload values are set. + +When not set: The GP Timer counters will be loaded with the value of the reload register when it is disabled or when it times out (underrun). + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.13-zw_gptimer_int_clear.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.13-zw_gptimer_int_clear.md new file mode 100644 index 0000000..76f295f --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.13-zw_gptimer_int_clear.md @@ -0,0 +1,16 @@ + +# 4.3.14.13 ZW_GPTIMER_int_clear + +void ZW_GPTIMER_int_clear (void) + +This function SHOULD be used to clear the GP Timer interrupt flag. + +Defined in: ZW_appltimer_api.h + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.14-zw_gptimer_int_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.14-zw_gptimer_int_get.md new file mode 100644 index 0000000..06bf87e --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.14-zw_gptimer_int_get.md @@ -0,0 +1,20 @@ + +# 4.3.14.14 ZW_GPTIMER_int_get + +BYTE ZW_GPTIMER_int_get (void) + +This function MAY be used to query the state of the GP Timer interrupt flag. + +Defined in: ZW_appltimer_api.h + +Return value: + +BYTE 0x00: interrupt flag is not set mom-0x00: Interrupt is set + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.15-zw_gptimer_int_enable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.15-zw_gptimer_int_enable.md new file mode 100644 index 0000000..770759d --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.15-zw_gptimer_int_enable.md @@ -0,0 +1,24 @@ + +# 4.3.14.15 ZW_GPTIMER_int_enable + +void ZW_GPTIMER_int_enable(BYTE bState) + +This function SHOULD be used to enable or disable the GPTimer interrupt. + +[The application designer MUST declare an Interrupt Service Routine (ISR) to handle the GP Timer interrupt. The ISR MUST use the ISR number INUM_GP_TIMER as declared in section 3.9.](../../../03-z-wave-software-architecture/03.09-interrupt-service-routines.md#39-interrupt-service-routines) + +Defined in: ZW_appltimer_api.h + +Parameters: + +bState IN TRUE enable GPTimer interrupt + +FALSE disable GPTimer interrupt + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.16-zw_gptimer_enable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.16-zw_gptimer_enable.md new file mode 100644 index 0000000..0b48c76 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.16-zw_gptimer_enable.md @@ -0,0 +1,22 @@ + +# 4.3.14.16 ZW_GPTIMER_enable + +void ZW_GPTIMER_enable(BYTE bState) + +This function SHOULD be used to enable or disable the GPTimer. Disabling the GPTimer also clears the interrupt flag and resets the GPTimer counters. + +Defined in: ZW_appltimer_api.h + +Parameters: + +bState IN TRUE enable GPTimer. + +FALSE disable GPTimer. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.17-zw_gptimer_pause.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.17-zw_gptimer_pause.md new file mode 100644 index 0000000..7a27847 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.17-zw_gptimer_pause.md @@ -0,0 +1,22 @@ + +# 4.3.14.17 ZW_GPTIMER_pause + +void ZW_GPTIMER_pause(BYTE bState) + +This function MAY be used to control the GPTimer pause state. When entering the pause state, the GPTimer counters stops counting. When leaving the pause state, the counters will start counting from the state they were in when the pause state was entered. + +Defined in: ZW_appltimer_api.h + +Parameters: + +bState IN TRUE Enter GPTimer pause state. + +FALSE Leave GPTimer pause state. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.18-zw_gptimer_reload_set.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.18-zw_gptimer_reload_set.md new file mode 100644 index 0000000..30e6825 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.18-zw_gptimer_reload_set.md @@ -0,0 +1,22 @@ + +# 4.3.14.18 ZW_GPTIMER_reload_set + +void ZW_GPTIMER_reload_set(WORD wReloadValue) + +This function SHOULD be used to set the 16 bit GPTimer reload register. This value sets the time from where the GPTimer is enabled or is reloaded until it reaches zero (issues an interrupt). As an example, if the GPtimer reload value is set to 0x0137 and the prescaler is set to 1024, the timer will reach zero after 0x137 * 1024 * (32MHz) -1 = 9.95ms. + +The value 0x0000 equals a timer reload value of 0x10000. E.g. if the GPtimers reload value is set to 0x0000 and the prescaler is set to 8, the timer will reach zero after 0x10000 * 8 * (32MHz) -1 = 16.38ms. + +Defined in: ZW_appltimer_api.h + +Parameters: + +wReloadValue IN 16 bit reload value + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.19-zw_gptimer_reload_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.19-zw_gptimer_reload_get.md new file mode 100644 index 0000000..9205f03 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.19-zw_gptimer_reload_get.md @@ -0,0 +1,20 @@ + +# 4.3.14.19 ZW_GPTIMER_reload_get + +WORD ZW_GPTIMER_reload_get(void) + +This function MAY be used to query the 16 bit GPTimer reload register value. + +Defined in: ZW_appltimer_api.h + +Return value: + +WORD 16 bit reload value + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.20-zw_gptimer_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.20-zw_gptimer_get.md new file mode 100644 index 0000000..f8b711c --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.20-zw_gptimer_get.md @@ -0,0 +1,22 @@ + +# 4.3.14.20 ZW_GPTIMER_get + +WORD ZW_GPTIMER_get(void) + +This function MAY be used to query the 16 bit GPTimer counter register value. The returned value is in the range [reload_value-1;0]. As an example, if the reload value is set to 0x2A40, ZW_GPTIMER_get() will return a value in the range [0x2A3F;0]. + +An application SHOULD be designed to be robust if a higher value is returned, e.g. because the reload value was not correctly stored in the chip. + +Defined in: ZW_appltimer_api.h + +Return value: + +WORD 16 bit counter value + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.21-zw_pwm_init.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.21-zw_pwm_init.md new file mode 100644 index 0000000..a71dd78 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.21-zw_pwm_init.md @@ -0,0 +1,38 @@ + +# 4.3.14.21 ZW_PWM_init + +void ZW_PWM_init(BYTE bValue) + +This function SHOULD be used to initialize the pulse width modulator. Calling ZW_PWM_init() will disable the GPTimer function, since the PWM and the GP Timer share the same hardware. + +It is NOT RECOMMENDED that Immediate write mode is enabled as it introduces a risk of unintended waveforms. + +Defined in: ZW_appltimer_api.h + +Parameters: + +bValue IN Bit mask: + +Prescaler setting + +PRESCALER_BIT When set: PWM counter runs @ 32MHz / 1024 = 31.25kHz When nor set: PWM counter runs @ 32MHz / 8 = 4MHz + +Invert signal + +PWMINV_BIT When set: PWM signal is inverted. + +When not set: The signal is not inverted + +Immediate write + +IMWR_BIT When set: The PWM counters will be loaded with the value of the waveform registers when it is disabled or immediately when the waveform values are set. + +When not set: The PWM counters will be loaded with the value of the waveform registers when it is disabled or at the end of a PWM signal period. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.22-zw_pwm_enable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.22-zw_pwm_enable.md new file mode 100644 index 0000000..beb78ca --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.22-zw_pwm_enable.md @@ -0,0 +1,22 @@ + +# 4.3.14.22 ZW_PWM_enable + +void ZW_PWM_enable(BYTE bState) + +This function SHOULD be used to enable or disable the PWM. Disabling the PWM also clears the interrupt flag and resets the PWM counter. + +Defined in: ZW_appltimer_api.h + +Parameters: + +bState IN TRUE enable PWM. + +FALSE disable PWM. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.23-zw_pwm_int_clear.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.23-zw_pwm_int_clear.md new file mode 100644 index 0000000..1d437de --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.23-zw_pwm_int_clear.md @@ -0,0 +1,16 @@ + +# 4.3.14.23 ZW_PWM_int_clear + +void ZW_PWM_int_clear (void) + +This function SHOULD be used to clear the PWM interrupt flag. + +Defined in: ZW_appltimer_api.h + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.24-zw_pwm_int_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.24-zw_pwm_int_get.md new file mode 100644 index 0000000..c2104d1 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.24-zw_pwm_int_get.md @@ -0,0 +1,20 @@ + +# 4.3.14.24 ZW_PWM_int_get + +BYTE ZW_PWM_int_get (void) + +This function MAY be used to query the state of the PWM interrupt flag. + +Defined in: ZW_appltimer_api.h + +Return value: + +BYTE 0x00: interrupt flag is not set non-0x00: Interrupt is set + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.25-zw_pwm_int_enable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.25-zw_pwm_int_enable.md new file mode 100644 index 0000000..27f915f --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.25-zw_pwm_int_enable.md @@ -0,0 +1,26 @@ + +# 4.3.14.25 ZW_PWM_int_enable + +void ZW_PWM_int_enable(BYTE bState) + +This function SHOULD be used to enable or disable the PWM interrupt. The PWM interrupt is triggered on the rising edge of the PWM signals (or at the falling edge of the PWM signal if PWMINV_BIT is set in ZW_PWM_init()). + +[The application designer MUST declare an Interrupt Service Routine (ISR) to handle the PWM controller interrupt. The ISR MUST use the ISR number INUM_GP_TIMER as declared in section 3.9.](../../../03-z-wave-software-architecture/03.09-interrupt-service-routines.md#39-interrupt-service-routines) + +[Section 4.3.14.25 recommends that Immediate write is not enabled. With Immediate write disabled, the](04.03.14.25-zw_pwm_int_enable.md#431425-zw_pwm_int_enable) [application may unintentionaly inhibit the flow of IRQs from the PWM controller. This may happen if the application calls ZW_PWM_waveform_set with the parameter value (0,0). Refer to 4.3.14.26 on how to](04.03.14.26-zw_pwm_waveform_set.md#431426-zw_pwm_waveform_set) recover from this situation. + +Defined in: ZW_appltimer_api.h + +Parameters: + +bState IN TRUE enable PWM interrupt + +FALSE disable PWM interrupt + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.26-zw_pwm_waveform_set.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.26-zw_pwm_waveform_set.md new file mode 100644 index 0000000..c9486c7 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.26-zw_pwm_waveform_set.md @@ -0,0 +1,38 @@ + +# 4.3.14.26 ZW_PWM_waveform_set + +void ZW_PWM_waveform_set (BYTE bHigh, BYTE bLow) + +This function SHOULD be used to set the high and low time of the PWM signal. Refer to figure below. + +High time of PWM signal: t = (bHigh * PRESCALER)/f hPWM sys Low time of PWM signal t = (bLow * PRESCALER) /f lPWM sys Total period of PWM signal: T = t + t PWM hPWM lPWM + +where f is 32MHz and sys PRESCALER is 1024 when PRESCALER_BIT is set by ZW_PWM_init() and PRESCALER is 8 when PRESCALER_BIT is not set. + +NOTE: If PWMINV_BIT was set by ZW_PWM_init(), bHigh defines the duration of the low period and bLow defines the duration of the high period.. + +T PWM + +t t lPWM lPWM + +t t hPWM hPWM + +Figure 19. PWM Waveform + +[Section 4.3.14.25 recommends that Immediate write is not enabled. With Immediate write disabled, the](04.03.14.25-zw_pwm_int_enable.md#431425-zw_pwm_int_enable) application SHOULD NOT call ZW_PWM_waveform_set with the parameter value (0,0). In case the parameter value (0,0) has been used, the application MUST call ZW_PWM_waveform_set with one or two non-zero values and subsequently disable and re-enable the PWM controller by calling ZW_PWM_enable. While NOT RECOMMENDED, Immediate write MAY be enabled. In that case, the application MAY call ZW_PWM_waveform_set with any parameter value. + +Defined in: ZW_appltimer_api.h + +Parameters: + +bHigh IN high time + +bLow IN low time + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.27-zw_pwm_waveform_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.27-zw_pwm_waveform_get.md new file mode 100644 index 0000000..c6a0b68 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/04.03.14.27-zw_pwm_waveform_get.md @@ -0,0 +1,22 @@ + +# 4.3.14.27 ZW_PWM_waveform_get + +void ZW_waveform_get(BYTE *bHigh, BYTE *bLow) + +This function MAY be used to query the values of the waveform registers. + +Defined in: ZW_appltimer_api.h + +Parameters: + +bHigh OUT high time + +bLow OUT low time + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/index.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/index.md new file mode 100644 index 0000000..3eb1961 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.14-application-hw-timerspwm-interface-api/index.md @@ -0,0 +1,62 @@ + +# 4.3.14 Application HW Timers/PWM Interface API + +The 500 Series Z-Wave SoC has three built-in HW timers available for the application: + +1. Timer0 2. Timer1 3. GPTimer or PWM generator. + +| Timer | bits | Clocked by | Count up/down | +| --- | --- | --- | --- | +| Timer0 | 8/13/16 | 32MHz / 2 or P3.4 | Counts up | +| Timer1 | 8/13/16 | 32MHz / 2 or P3.5 | Counts up | +| GPTimer | 16 | 32MHz / 8 or 32MHz / 1024 | Counts down | + +Timer0 and Timer1 are standard 8051 timers that can be configured to: + + be enabled/disabled  use the system clock divided by 2 (16MHz) or use a pin as clock source  generate an interrupt at overflow + +Refer to figure below for principle diagrams of how the clock control works for Timer0. + +Figure 17. Principle of Clock Control for Timer0 + +Refer to figure below for principle diagrams of how the clock control works for Timer0. + +Figure 18. Principle of Clock Control (mode 0-2) for Timer1 + +Timer0 and Timer1 can operate in four different modes. Refer to the description of ZW_TIMER1_init + +## Contents + +- [4.3.14.1 ZW_TIMER0_init](04.03.14.01-zw_timer0_init.md) +- [4.3.14.2 ZW_TIMER1_init](04.03.14.02-zw_timer1_init.md) +- [4.3.14.3 ZW_TIMER0_INT_CLEAR / ZW_TIMER1_INT_CLEAR](04.03.14.03-zw_timer0_int_clear-zw_timer1_int_clear.md) +- [4.3.14.4 ZW_TIMER0_INT_ENABLE / ZW_TIMER1_INT_ENABLE](04.03.14.04-zw_timer0_int_enable-zw_timer1_int_enable.md) +- [4.3.14.5 ZW_TIMER0_ENABLE / ZW_TIMER1_ENABLE](04.03.14.05-zw_timer0_enable-zw_timer1_enable.md) +- [4.3.14.6 ZW_TIMER0_ext_clk / ZW_TIMER1_ext_clk](04.03.14.06-zw_timer0_ext_clk-zw_timer1_ext_clk.md) +- [4.3.14.7 ZW_TIMER0_LOWBYTE_SET / ZW_TIMER1_LOWBYTE_SET](04.03.14.07-zw_timer0_lowbyte_set-zw_timer1_lowbyte_set.md) +- [4.3.14.8 ZW_TIMER0_HIGHBYTE_SET / ZW_TIMER1_HIGHBYTE_SET](04.03.14.08-zw_timer0_highbyte_set-zw_timer1_highbyte_set.md) +- [4.3.14.9 ZW_TIMER0_HIGHBYTE_GET / ZW_TIMER1_HIGHBYTE_GET](04.03.14.09-zw_timer0_highbyte_get-zw_timer1_highbyte_get.md) +- [4.3.14.10 ZW_TIMER0_LOWBYTE_GET / ZW_TIMER1_LOWBYTE_GET](04.03.14.10-zw_timer0_lowbyte_get-zw_timer1_lowbyte_get.md) +- [4.3.14.11 ZW_TIMER0_word_get / ZW_TIMER1_word_get](04.03.14.11-zw_timer0_word_get-zw_timer1_word_get.md) +- [4.3.14.12 ZW_GPTIMER_init](04.03.14.12-zw_gptimer_init.md) +- [4.3.14.13 ZW_GPTIMER_int_clear](04.03.14.13-zw_gptimer_int_clear.md) +- [4.3.14.14 ZW_GPTIMER_int_get](04.03.14.14-zw_gptimer_int_get.md) +- [4.3.14.15 ZW_GPTIMER_int_enable](04.03.14.15-zw_gptimer_int_enable.md) +- [4.3.14.16 ZW_GPTIMER_enable](04.03.14.16-zw_gptimer_enable.md) +- [4.3.14.17 ZW_GPTIMER_pause](04.03.14.17-zw_gptimer_pause.md) +- [4.3.14.18 ZW_GPTIMER_reload_set](04.03.14.18-zw_gptimer_reload_set.md) +- [4.3.14.19 ZW_GPTIMER_reload_get](04.03.14.19-zw_gptimer_reload_get.md) +- [4.3.14.20 ZW_GPTIMER_get](04.03.14.20-zw_gptimer_get.md) +- [4.3.14.21 ZW_PWM_init](04.03.14.21-zw_pwm_init.md) +- [4.3.14.22 ZW_PWM_enable](04.03.14.22-zw_pwm_enable.md) +- [4.3.14.23 ZW_PWM_int_clear](04.03.14.23-zw_pwm_int_clear.md) +- [4.3.14.24 ZW_PWM_int_get](04.03.14.24-zw_pwm_int_get.md) +- [4.3.14.25 ZW_PWM_int_enable](04.03.14.25-zw_pwm_int_enable.md) +- [4.3.14.26 ZW_PWM_waveform_set](04.03.14.26-zw_pwm_waveform_set.md) +- [4.3.14.27 ZW_PWM_waveform_get](04.03.14.27-zw_pwm_waveform_get.md) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.15-security-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.15-security-api.md new file mode 100644 index 0000000..2861bc3 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.15-security-api.md @@ -0,0 +1,144 @@ + +# 4.3.15 Security API + +This API handles security keys on application level. + +## 4.3.15.1 ZW_GetSecurityKeys (Only slave libraries) + +BYTE ZW_GetSecurityKeys() + +This function returns a bitmask of security keys the node posses. The application can request ZW_SendDataEx() to use these keys for outgoing messages. Incoming messages sent with any of these keys will be decrypted and delivered to the application. An excluded node returns no security keys. + +Defined in: ZW_security_api.h + +Parameters: + +BYTE OUT Bit mask: + +0x00 = SECURITY_KEY_NONE_MASK No security keys + +0x01 = SECURITY_KEY_S2_UNAUTHENTICATED_BIT + +0x02 = SECURITY_KEY_S2_AUTHENTICATED_BIT + +0x04 = SECURITY_KEY_S2_ACCESS_BIT + +0x80 = SECURITY_KEY_S0_BIT + +Serial API + +HOST->ZW: REQ | 0x9C | 0 + +ZW->HOST: RES | 0x9C | 0 | securityKeys_bitmaskLen(1) | securityKeys_bitmask + +In the Serial API the Security API functions are reached through the FUNC_ID_ZW_SECURITY_SETUP (0x9C) and this Serial API FUNC_ID makes it possible to set the Requested Security Keys and Requested Authentication method in a Slave Routing/Enhanced 232 based Serial API Node prior to inclusion (add). The Requested Security Keys and Authentication is requested by the protocol during S2 inclusion. + +Set Requested Security Inclusion Keys (E_SECURITY_SETUP_CMD_SET_SECURITY_INCLUSION_REQUESTED_KEYS): + +HOST->ZW: REQ | 0x9C | 5 | registeredSecurityKeysLen(1) | registeredSecurityKeys + +ZW->HOST: RES | 0x9C | 5 | retValLen(1) | retVal - retVal == TRUE => success + +Set Requested Security Inclusion Authentication (E_SECURITY_SETUP_CMD_SET_SECURITY_INCLUSION_REQUESTED_AUTHENTICATION): + +HOST->ZW: REQ | 0x9C | 6 | registeredSecurityAuthenticationLen(1) | registeredSecurityAuthentication + +ZW->HOST: RES | 0x9C | 6 | retValLen(1) | retVal - retVal == TRUE => success + +## 4.3.15.2 ZW_s2_inclusion_init(Only slave libraries) + +void ZW_s2_inclusion_init(void) + +Initialises the S2 inclusion machine. Must only be called if Requested Security Keys or Requested Authentication method is changed. + +Defined in: ZW_security_api.h + +Serial API + +[Not implemented. SerialAPI Application calls ZW_s2_inclusion_init() when changing either the Requested Security Keys or the Requested Authentication Method (See 4.3.15.1).](04.03.15-security-api.md#43151-zw_getsecuritykeys-only-slave-libraries) + +## 4.3.15.3 ZW_SetSecurityS2InclusionPublicDSK_CSA(Only slave libraries) + +void ZW_SetSecurityS2InclusionPublicDSK_CSA(s_SecurityS2InclusionCSAPublicDSK_t *response) + +Set the Controller DSK requested by protocol through ApplicationSecurityEvent with the Security Event E_APPLICATION_SECURITY_EVENT_S2_INCLUSION_REQUEST_DSK_CSA. + +Defined in: ZW_security_api.h + +Parameters: + +s_SecurityS2InclusionCSAPublicDSK_t* IN response->aCSA_DSK[4] Pointer to 4 BYTE Public CSA DSK + +Serial API + +HOST->ZW: REQ | 0x9C | 4 | bCSA_DSKLen(4) | aCSA_DSK[4] + +ZW->HOST: RES | 0x9C | 4 | retValLen(1) | retVal - retVal == TRUE => success + +## 4.3.15.4 ZW_GetSecurityS2PublicDSK(Only slave libraries) + +void ZW_GetSecurityS2PublicDSK(BYTE *buf) + +This function returns the 16 byte Public DSK for the node in the 16 byte long array buf points to – buf most point to an array at least 16 byte in size. Can be used to do S2 SSA Authenticated inclusion (add) by using the returned DSK to present to user which then must enter the needed part of the DSK on the Controller when doing Authenticated S2 inclusion. + +Defined in: ZW_security_api.h + +Parameters: + +BYTE OUT *buf Pointer to 16 byte array the DSK should be written to. + +Serial API + +HOST->ZW: REQ | 0x9C | 2 + +ZW->HOST: RES | 0x9C | 2 | publicDSKLen(16) | publicDSK[16] + +## 4.3.15.5 ZW_SetSecurityS2CriticalNodeID (Only routing slave library) + +void ZW_SetSecurityS2CriticalNodeID(BYTE bNodeID) + +This function set the S2 Critical NodeID used when a S2 included slave_routing based node enter sleepmode. When Sleepmode is entered the SPAN used in connection with S2 communicating with the Critical NodeID is saved in Retention RAM and restored when wakeup. This makes SPAN resync not necessary when communicating with the Critical NodeID after wakeup. + +Defined in: ZW_security_api.h + +Parameters: + +BYTE IN bNodeID: + +0 Save MRU SPAN in retention RAM when going into Sleep Mode. + +1 – 232 Save SPAN concerning bNodeID (if present) in retention when going into Sleep Mode. + +233 – 255 Reserved. + +Serial API + +HOST->ZW: REQ | 0x9C | 3 | bNodeIDLen(1) | nodeID ZW->HOST: RES | 0x9C | 3 | retValLen(1) | retVal - retVal == TRUE => success + +## 4.3.15.6 ZW_SetSecurityS0NetworkKey (Only enhanced 232 slave library) + +void ZW_SetSecurityS0NetworkKey(BYTE *network_key) + +This function is only used after a firmware update of an application that is securely included in a S0 based network. The call transfer the S0 network key from the application area in external NVM to the Z- Wave Protocol area in external NVM. + +Defined in: ZW_security_api.h + +Parameters: + +network_key IN Array of 16 bytes Pointer to byte array containing the S0 network key + +Serial API + +HOST->ZW: REQ | 0x9C | 1 | networkkeyLen(16) | network_key[16] + +ZW->HOST: RES | 0x9C | 1 | retValLen(1) | retVal - retVal == TRUE => success + +retVal = FALSE if ZW_SetSecurityS0NetworkKey was NOT called (network_key must be 16 bytes) + +retVal = TRUE if ZW_SetSecurityS0NetworkKey was called with specified network_key diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.16-aes-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.16-aes-api.md new file mode 100644 index 0000000..9463f93 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.16-aes-api.md @@ -0,0 +1,160 @@ + +# 4.3.16 AES API + +The built-in AES-128 hardware engine is a NIST standardized AES 128 block cipher. The cipher engine is used by the Z-Wave Protocol to encrypt/decrypt Z Wave frame payload and to authenticate Z Wave frames. In addition this AES-128 encryption engine can also be used to encrypt a 128bit data block (Using ECB - Electronic CookBook mode) by the application. + +The input and output data and key for the AES API’s are 16 bytes long char arrays. ZW_AES_ecb_set is used to set the input data (plaintext and key) and the function ZW_AES_ecb_get is used to return the cipher data from the AES engine. The ECB process is started using the function ZW_AES_ecb_enable(TRUE) and it lasts about 24µs. The process can be canceled by calling ZW_AES_ecb_enable(FALSE). The AES engine must be polled, using the function ZW_AES_ecb_active to check when a ECB process is done. Figure below gives an example of how the AES engine functions are called. + +[/* Example of ECB ciphering. Vectors are from FIPS-197 */](http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf) + +void ApplicationPoll() {: switch (mainState) {: case START_AES_TEST: keybuffer[15] = 0x00; keybuffer[14] = 0x01; keybuffer[13] = 0x02; keybuffer[12] = 0x03; keybuffer[11] = 0x04; keybuffer[10] = 0x05; keybuffer[9] = 0x06; keybuffer[8] = 0x07; keybuffer[7] = 0x08; keybuffer[6] = 0x09; keybuffer[5] = 0x0A; keybuffer[4] = 0x0B; keybuffer[3] = 0x0C; keybuffer[2] = 0x0D; keybuffer[1] = 0x0E; keybuffer[0] = 0x0F; + +plainbuffer[15] = 0x00; plainbuffer[14] = 0x11; plainbuffer[13] = 0x22; plainbuffer[12] = 0x33; plainbuffer[11] = 0x44; plainbuffer[10] = 0x55; plainbuffer[9] = 0x66; plainbuffer[8] = 0x77; plainbuffer[7] = 0x88; plainbuffer[6] = 0x99; plainbuffer[5] = 0xAA; plainbuffer[4] = 0xBB; plainbuffer[3] = 0xCC; plainbuffer[2] = 0xDD; plainbuffer[1] = 0xEE; plainbuffer[0] = 0xFF; + +cipherbuffer[15] = 0x69; cipherbuffer[14] = 0xC4; cipherbuffer[13] = 0xE0; cipherbuffer[12] = 0xD8; cipherbuffer[11] = 0x6A; cipherbuffer[10] = 0x7B; cipherbuffer[9] = 0x04; cipherbuffer[8] = 0x30; cipherbuffer[7] = 0xD8; cipherbuffer[6] = 0xCD; cipherbuffer[5] = 0xB7; cipherbuffer[4] = 0x80; cipherbuffer[3] = 0x70; cipherbuffer[2] = 0xB4; cipherbuffer[1] = 0xC5; cipherbuffer[0] = 0x5A; /* Set AES ECB input data pointers */ ZW_AES_ecb_set(plainbuffer,keybuffer); /* Start AES ECB function */ ZW_AES_enable(TRUE); mainState= WAIT_AES_ECB; break; case WAIT_AES_ECB: /* Check to se if AES ECB procedure is done */ ZW_AES_active_get()==FALSE) if ({ ZW_AES_ecb_get(plainbuffer); /* check against proven data */ fail=FALSE; for (i=0;i<16;i++) { if (plainbuffer[i]!=chipherbuffer[i]) { fail=TRUE; break; } } if (fail) report (); + +mainState= IDLE; }: break; } } [Figure 20. Example of ECB Ciphering. Vectors are from](http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf). [FIPS-197](http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf) + +## 4.3.16.1 ZW_AES_ecb_set + +void ZW_AES_ecb_set(BYTE *bData, BYTE *bKey) + +Call this function to setup the input data for the AES in ECB mode (Electronic Cookbook mode). Use the function ZW_AES_swap_byte to swap the order of which the data from the array is read into the AES engine. + +Defined in: ZW_aes_api.h + +Parameters: + +bData Array of 16 bytes Pointer to byte array containing the data to be encrypted. + +bKey Array of 16 bytes Pointer to byte array containing the encryption key + +Serial API (Not supported) + +## 4.3.16.2 ZW_AES_ecb_get + +void ZW_AES_ecb_get(BYTE *bData) + +After calling ZW_AES_ecb_set, use ZW_AES_active_get to see if the AES process is done. When this is the case, call ZW_AES_ecb_get to transfer the result of a AES ECB process to the array bData. Use the function ZW_AES_swap_byte to swap the order of which the data from the array is read from the AES engine. + +Defined in: ZW_aes_api.h + +Parameters: + +bData Array of 16 bytes Pointer to byte array buffer containing encrypted data + +Serial API (Not supported) + +## 4.3.16.3 ZW_AES_enable + +void ZW_AES_enable(BOOL bState) + +Call ZW_AES_enable(TRUE) to enable the AES engine and start the ECB process. The AES engine will automatically be disabled when a ECB process is done. Call ZW_AES_enable(FALSE) if a ECB process is to be canceled. + +Defined in: ZW_aes_api.h + +Parameters: + +bState TRUE Enable the AES and start the ECB mode. + +FALSE Disable the AES. + +Serial API (Not supported) + +## 4.3.16.4 ZW_AES_swap_data + +void ZW_AES_swap_data(BOOL bState) + +The function is used to enable the option to swap the byte order of the data read into and read from the the AES engine. + +Defined in: ZW_aes_api.h + +Parameters: + +bState TRUE Swap data bytes. + +FALSE Do not swap data bytes + +Serial API (Not supported) + +## 4.3.16.5 ZW_AES_active_get + +BYTE ZW_AES_active_get (void) + +Returns the active/idle state of the AES engine. Use this function to see when a ECB process is done. + +Defined in: ZW_aes_api.h + +Return value: + +BOOL TRUE The AES is busy. + +FALSE The AES is idle. + +Serial API (Not supported) + +## 4.3.16.6 ZW_AES_int_enable_get + +void ZW_AES_int_enable (BYTE bState) + +Call this function to enable or disable AES interrupts. + +Defined in: ZW_aes_api.h + +Parameters: + +bState IN TRUE The AES interrupt is enabled. + +FALSE The AES interrupt is disabled + +Serial API (Not supported) + +## 4.3.16.7 ZW_AES_int_get + +BYTE ZW_AES_int_get (void) + +The function return the state of the AES interrupt flag. + +Defined in: ZW_aes_api.h + +Return value: + +BYTE 0x00 The AES interrupt flag is set + +non-0x00 The AES interrupt flag is cleared + +Serial API (Not supported) + +## 4.3.16.8 ZW_AES_int_clear + +void ZW_AES_int_clear (void) + +Call this function to clearthe AES interrupt flag. + +Defined in: ZW_aes_api.h + +Serial API (Not supported) + +## 4.3.16.9 ZW_AES_ecb/ZW_AES_ecb_dma + +BYTE ZW_AES_ecb (BYTE *bKey BYTE *bInput BYTE *bOutput) BYTE ZW_AES_ecb_dma (BYTE *bKey BYTE *bInput BYTE *bOutput) + +These functions execute a AES-128 ECB task and return the encrypted data. Once started the functions will be blocking until the task is done.The function ZW_AES_ecb_dma will use the built-in DMA function to transfer data between the AES engine and the XRAM, whereas the data handling will be done purely by the 8051 using the function ZW_AES_ecb. Use the function ZW_AES_swap_byte to swap the order of which the data bytes from the array are written to and read from the AES engine. + +Defined in: ZW_aes_api.h + +Parameters: + +*bKey IN pointer to byte array in lower 4kB XRAM containing the input data (16 bytes) + +*bInput IN pointer to byte array in lower 4kB The AES is idle. XRAM containing the key (16 bytes) + +*bOutput OUT pointer to byte array in lower 4kB The AES is idle. XRAM containing the output data (16 bytes) + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.17-triac-controller-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.17-triac-controller-api.md new file mode 100644 index 0000000..79a72bc --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.17-triac-controller-api.md @@ -0,0 +1,269 @@ + +# 4.3.17 TRIAC Controller API + +The built-in TRIAC Controller is targeted at controlled light / power dimming applications. The Triac Controller is able to drive both TRIAC’s and FET’s/IGBT’s. The Triac Controller can dim the load with a precision of 1000 steps in each half-period. + +When controlling TRIAC’s the Triac Controller will generate one or more fire pulses in each half period of the mains to turn on the Triac. The fire angle is set by the specified dim level. The Triac Controller will generate multiple pulses if the fire angle is less than 90º. The multiple pulses ensure that at least one pulse is located after the middle of a half-period, thereby ensuring that the Triac will be fired even with fully inductive loads, while still limiting the current consumption. + +When controlling a FET/IGBT the Triac Controller will generate a fire pulse with a width that is propotional to the dim level. The pulse can be either leading or falling edge controlled. + +The Triac Controller can operate in both 50Hz and 60Hz environments. + +The application software can use the following TRIAC API calls to control the 500 Series Z-Wave SoC TRIAC Controller. + +## 4.3.17.1 ZW_TRIAC_init + +BYTE ZW_TRIAC_init(BYTE bMode, WORD wPulseLength, BYTE bPulseRepLength, BYTE bZeroXMode, BYTE bInitMask, BYTE bInvZerox, BYTE bMainsFreq, WORD wCorrection, BYTE bCorPrescale, BYTE bKeepOff) + +ZW_TRIAC_init initializes the 500 Series Z-Wave SoC's integrated TRIAC controller. Refer to the [section after the function parameter list for a description of the setup of the different zero-cross modes (page 283). Place this function call in](04.03.17-triac-controller-api.md#43171-zw_triac_init) ApplicationInitHW. + +Defined in: ZW_triac_api.h + +Parameters: + +bMode IN Mode of operation: + +TRIAC_MODE Triac mode. Multiple short pulses before 90 degrees and single short pulse after 90 degrees + +FET_TRAILING_EDGE_MODE FET/IGBT trailing edge mode. Single pulse control signal (TRIAC) which goes high at 0º and low in 0-180º depending of dim level + +FET_LEADING_EDGE_MODE FET/IGBT leading edge mode. Single pulse control signal (TRIAC) which goes high at 0-180º depending of dim level and goes low at the next zero-cross + +wPulseLength IN Triac Fire pulse length Not applicable in FET Modes,where this value must be set to 0 Legal values: 1-250 (Triac mode) Set this parameter so that is equals the minimum Triac gate high time according n Each step equals, where n to the datasheet of the specific Triac in 32 MHz use. is 265 in 60Hz systems The pulse length can not exceed a 318 in 50Hz systems quarter of the halfperiod length. E.g. for a 50Hz system the pulse length can not E.g. setting this parameter to 40 in a exceed 10ms/4=2.5ms. 50Hz system gives a Triac pulse 318 These relations must be fulfilled:   40 397 5. us length of bPulseRepLength*4+wPulseLength<500 32 MHz bPulseRepLength*4 > wPulseLength bPulseRepLength IN Triac fire pulse repetition period Not applicable in FET Mode (Where it must be set to 0) Legal values: 18-125 This parameter sets the period from the  rising edge of one fire pulse to the rising 4 n Each step equals, where n edge of the next fire pulse. 32 MHz is The Triac Controller will generate 265 in 60Hz systems multiple fire pulses when the fire angle is 318 in 50Hz systems less than 90° + +i.e., setting this parameter to 20 in a These relations must be fulfilled: 50 Hz system gives a Triac pulse bPulseRepLength*4+wPulseLength>500  4 318 bPulseRepLength > wPulseLength/4   20 795 us length of 32 MHz + +bZeroXMode IN Bridge types: + +TRIAC_FULLBRIDGE The TRIAC signal is sync'ed to - the rising edges of the ZEROX signal if bInvZerox is FALSE. or -the falling edges of the ZEROX signal if bInvZerox is TRUE. + +TRIAC_HALFBRIDGE_A The TRIAC signal is sync'ed to the rising and the falling edges of the ZEROX signal. TRIAC_HALFBRIDGE_B The TRIAC signal is sync'ed to - the rising edge of the ZEROX signal in every second halfperiod if bInvZerox is FALSE or - the falling edge of the ZEROX signal in every second halfperiod if bInvZerox is TRUE bInitMask IN Initial zero-cross mask: + +TRUE Mask out noise impulses on the mains from the point of a detected zero-cross to the start of the Triac fire pulse + +FALSE Do not Mask out impulse noise on the mains from the point of a detected zero- cross to the start of the Triac fire pulse bInvZerox IN Inverse zero-cross signal: + +TRUE Inverse zero-cross signal + +FALSE Do not inverse zero-cross signal + +bMainsFreq IN AC mains frequency: + +FREQUENCY_50HZ Using 50Hz AC mains supply + +FREQUENCY_60HZ Using 60Hz AC mains supply + +wCorrection IN ZeroX Duty-Cycle correction Half Bridge Mode A: + +Legal values: 0-1023. The parameter is used to compensate from a ZeroX signal duty-cycle that is not exactly The Triac controller has a timer, that can compensate for a non-50/50 50/50, in half bridge mode A. duty cycle of the ZeroX signal when using Half Bridge Mode A or to ajust Typically, the high time of a ZeroX the starting point of the second half signal in half bridge mode is period when using Half Bridge Mode shorter than the low time. In this B. case, setting this parameter to value greater than 0, can correct this mismatch. If the high time is The timer can run on a prescalered n ns longer than the low time, this clock (see bCorPrescale below) parameter should be set so that it equals n/2 ns. In other words, setting this parameter to 300 and bCorPrescale Half Bridge Mode B: to ‘1‘ gives a correction of 3    300 28.1 s. 60Hz systems: This value should 32 MHz   1   26 88 bKeepOff be set to   3 + +50Hz systems: This value should   31 106 be set to bKeepOff + +Full Bridge Mode: + +N.A. (Set this value to0) bCorPrescale Correction prescaler When this parameter is set to 1, the clock signal that is used for the Legal values: correction timer (see under wCorrection above) is prescaled by a factor of 3. 0: Prescaler disabled That is, the timer clock will run at 1: Prescaler enabled 32MHz/3~10.67MHz + +When this parameter is set to 0, the correction timer will run using the system clock (32.00MHz). + +Half Bridge Mode A: + +Set this parameter to 1 if the needed correction has to be longer than 1023*(32MHz) -1 = 31.97 μs + +Half Bridge Mode B: + +N.A. (Set this value to 0) + +Full Bridge Mode: + +N.A. (Set this value to 0) + +bKeepOff KeepOff distance The distance for a nominel 50Hz mains will be: Legal values: 0-9   bKeepOff  318 4    9.2 s Use this parameter to specify the   4 32 MHz minimum distance from the falling edge of the Triac pulse to the zero The distance for a nominel 60Hz mains cross of the mains signal (ZeroX). can be calculated as: This parameter will also specify the    distance from where the Triac bKeepOff 265 4    4.2 s   controller starts looking for a new 4 32 MHz ZeroX to the nominal ZeroX point. That is, use this parameter in regions where the mains frequency has large deviations. + +Return values: + +BYTE 0x00 OK + +0x01 Error: bPulseRepLength < wPulseLength/4: + +0x02 Error: bPulseRepLength < 18 + +0x03 Error: bPulseRepLength*4+wPulseLength>500 + +Serial API (Not supported) 4.3.17.1.1Zero-x configuration Half bridge A: + +In this mode, the Triac Controller uses both edges on the zero-cross signal for each period of the mains signal. That is, the zero-cross signal is expected to go high at the beginning of the mains period and the go low at the next zero-cross, as depicted in figure below. Since this is not usually the case, because of input threshold level the duty cycle, the rising edge is delayed, and the falling edge is too early. This results in a non-50/50 duty cycle, which again will result in a DC voltage over the Triac load. Use the parameters wCorrection and bCorPrescale to correct the duty-cycle, and thereby to get rid of the DC voltage. Setting these parameters will “delay” the falling edge in the Triac controller, as depicted in figure below. + +| | | | +| --- | --- | --- | +| | | | +| | | | +| | | | +| Both edges are used by | | Correction | + +Figure 21. Half-Bridge A Zero-x Signal + +Half bridge B: + +In this mode, the Triac Controller only uses one edge on the zero-x signal for each period of the mains signal. That is, the zero-x signal is expected to go high at the beginning of the mains period and the go low before the beginning of the next period, as depicted in figure below. + +| | | +| --- | --- | +| | | +| Only the rising edge of the pulse | | + +Figure 22. Example of Half-Bridge B Zero-x Signal Full Bridge: + +In this zero-x mode, the Triac Controller uses two rising edges on the zero-cross signal for each period of the mains signal. That is, the zero-cross signal is expected to go high at the beginning of the mains period and the go low before the beginning of the next half-period, then high again after the following zero-cross, and finally low again before the end of the period, as depicted in the two figures below. + +Figure 23. Example 1 of a Full Bridge Zero-x Signal + +Figure 24. Example 2 of a Full Bridge Zero-x Signal + +Zero-x mask + +Once the Triac Controller is started, the ZEROX signal is masked off the whole half period, except for a short period just before the next zero-cross. This period can be adjusted using the parameter bKeepOff. See figure below + +Mains voltage + +KeepOff KeepOff Zero-x signal is masked Zero-x signal is masked + +Zero-x detected Figure 25. Masked Zero-X Signal 4.3.17.1.2Modes of Operation The Triac controller can operate in three modes: + + Triac mode  FET trailing edge mode (for FET's and IGBT's)  FET leading mode (for FET's and IGBT's) + +Triac Mode + +In Triac Mode the Triac Controller will generate multiple pulses if the fire angle is less than 90º. The length of each of the pulses is set by the parameter wPulseLength and the repetition length is set by the parameter wPulseReplength. Depending on the dimming level the number of pulses will automatically be calculated so that at least one full pulse is generated in the period from 90º to 180º of a halfperiod. One pulse will be generated if the dimming level is set so that the first pulse is in the period from 90º to 180º of a halfperiod. The dimming level, i.e., position of the first pulse, is set by the function ZW_TRIAC_dimlevel_set. See figure below. + +| | | +| --- | --- | +| PulseLength PulseRepLength | | +| Dim Level | | +| | | +| | | + +Mains voltage + +TRIAC + +Current trough load + +Figure 26. PulseLength and PulseRepLength used in Triac Mode (Resistive Load) FET/IGBT Modes + +In the FET/IGBT Modes the Triac Controller will generate one pulse per half period. The length of the pulse is set by the function ZW_TRIAC_dimlevel_set(). In FET trailing edge mode the FET/IGBT control [signal (TRIAC) is set high at the zero-cross at 0º and set low in the halfperiod from 0º to 180º depending of the dim level. See Figure 27. In FET leading edge mode the FET/IGBT control signal (TRIAC) is set high in the halfperiod from 0º to 180º depending of the dim level and set low before the next zero-cross at 180º. See Figure 28](04.03.17-triac-controller-api.md#43171-zw_triac_init) + +| | | | | +| --- | --- | --- | --- | +| Dim Level | | | | +| | | | | +| | | | | +| | | | | +| | | | | + +Figure 27 TRIAC Output in FET Trailing Edge Mode (Example with Resistive Load) + +| | | | | | | +| --- | --- | --- | --- | --- | --- | +| | Dim Level | | | | | +| | | | | | | +| | | | | | | +| | | | | | | +| | | | | | | + +Mains voltage + +Control signal TRIAC + +Current through load + +Figure 28 TRIAC Output in FET Leading Edge Mode (Example with Resistive Load) + +## 4.3.17.2 ZW_TRIAC_enable + +void ZW_TRIAC_enable(BOOL boEnable) + +ZW_TRIAC_enable enables/disables the Triac Controller. When enabled the Triac controller takes control over the TRIAC (P3.6) and the ZEROX 1 (P3.7) pins. ZW_TRIAC_init must have been called before the Triac Controller is enabled. + +Note: Calling ZW_TRIAC_enable(TRUE) will (besides from enabling the Triac Controller Fire signal output) disable the Triac Controller ZEROX interrupt. So to use both the Triac Controller for generating the Fire siganal output and the zero-x interrupt first call ZW_TRIAC_enable(TRUE) then call ZW_TRIAC_int_enable(TRUE). + +Defined in: ZW_triac_api.h + +Parameters: + +boEnable IN TRUE or FALSE TRUE: enables the Triac Controller + +Serial API (Not supported) + +## 4.3.17.3 ZW_TRIAC_dimlevel_set + +BOOL ZW_TRIAC_dimlevel_set(WORD wLevel) + +ZW_TRIAC_dimlevel_set turns the Triac controller on and sets the dimming level. ZW_TRIAC_init must have been called before the Triac Controller is started. + +Defined in: ZW_triac_api.h + +Parameters: + +wLevel IN Dimming level (0-1000), + +where 0 is shut off and 1000 is full on + +Return values: + +BOOL TRUE The new dim level has been accepted by the Triac Controller + +FALSE The Triac Controller has not yet read in the previous dim level. Wait up to one half period of the mains signal (50Hz: 10ms, 60 Hz 8.33ms) and try again + +Serial API (Not supported) + +## 4.3.17.4 ZW_TRIAC_int_enable + +void ZW_TRIAC_int_enable(BYTE boEnable) + +ZW_TRIAC_int_enable enables/disables the zero cross (ZeroX) interrupt. The ZeroX interrupt is issued when the TRIAC controller detects a zero cross on the ZEROX signal. Hence, the Triac Controller will take control of the ZEROX pin (P3.7) when ZW_TRIAC_int_enable(TRUE) has been called. + +The ZeroX interrupt can be used to implement a SW based TRIAC controller where the TRIAC signal is controlled by the SW. The Triac Controller will generate the ZeroX interrupt when it detects a zero cross on the ZEROX signal, even if the Triac Controller has been disabled (by calling ZW_TRIAC_enable(FALSE)) as long as ZW_TRIAC_int_enable(TRUE) has been called. + +Defined in: ZW_triac_api.h + +Parameters: + +boEnable IN TRUE Enable the interrupt. The Triac controller will issue an interrupt when a zero cross is detected on the ZEROX signal. + +Disable the Triac interrupt. FALSE + +Serial API (Not supported) + +The interrupt number is set by the define, INUM_TRIAC, as described in ZW050x.h + +## 4.3.17.5 ZW_TRIAC_int_get + +BOOL ZW_TRIAC_int_get(void) + +ZW_TRIAC_int_get returns the state of the Triac Controller interrupt flag. Call ZW_TRIAC_int_enable(TRUE) to enable the interrupt. + +Defined in: ZW_triac_api.h + +Return values: + +BOOL TRUE The Triac Controller interrupt flag is set. + +FALSE The Triac Controller interrupt flag is cleared. + +Serial API (Not supported) + +## 4.3.17.6 ZW_TRIAC_int_clear + +void ZW_TRIAC_int_clear(void) + +ZW_TRIAC_int_get clears the Triac Controller interrupt flag. Call ZW_TRIAC_int_enable(TRUE) to enable the interrupt and use ZW_TRIAC_int_get to see whether the interrupt has been set. + +Defined in: ZW_triac_api.h + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.18-led-controller-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.18-led-controller-api.md new file mode 100644 index 0000000..4ce13ba --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.18-led-controller-api.md @@ -0,0 +1,98 @@ + +# 4.3.18 LED Controller API + +The built-in LED Controller is targeted at LED light dimming applications. The controller can control up to four individual channels in 3 different modes of operation. The application can use the following LED API calls to control the 500 Series Z-Wave SoC LED Controller. + +## 4.3.18.1 ZW_LED_init + +void ZW_LED_init( BYTE bMode, BYTE bChannelEn) + +ZW_LED_init SHOULD be used to initialize the 500 Series Z-Wave SoC's integrated LED controller. The function configures the desired mode of operation and the desired number of active channels. This function SHOULD be called in ApplicationHWInit. + +Defined in: ZW_led_api.h + +Parameters: + +bMode IN Mode of operation type: + +LED_MODE_NORMAL In this mode, the LED controller generates a pulse width modulated signal for each active channel. The PWM signals has no phase skew. The frequency of all of the PWM signals is 32MHz/2 16 = 488.28Hz. The duty- cycle of the PWM signals is set by the ZW_LED_waveforms_set function. + +LED_MODE_SKEW The SKEW mode is same as the NORMAL mode except that phase of the channels are skewed. That is, the signal of channel 1 is skewed ¼ of a period compared to the signal of channel 0, the signal of channel 2 is skewed ¼ of a period compared to the signal of channel 1, etc. + +LED_MODE_PRBS In this mode, the LED controller uses a PRBS signal generator to generate to LED signals. The total high time in this mode equals the total high time in the other modes. + +bChannelEn IN Bit mask of one of the channels to be enabled + +LED_CHANNEL0 Enable channel 0. The LED Controller takes control of the P0.4 pin. + +LED_CHANNEL1 Enable channel 1. The LED Controller takes control of the P0.5 pin. + +LED_CHANNEL2 Enable channel 2. The LED Controller takes control of the P0.6 pin. + +LED_CHANNEL3 Enable channel 3 The LED Controller takes control of the P0.7 pin. + +Serial API (Not supported) + +## 4.3.18.2 ZW_LED_waveforms_set + +void ZW_LED_waveforms_set(WORD *pwLevel) + +ZW_LED_waveforms_set SHOULD be used to set the duty cycle for all LED Controller channels in one operation. The function configures the waveform for all channels even if some channels are not enabled. + +The function MUST NOT be called repeatedly, as it may run for up to 2.048ms to prevent race conditions in the LED controller latch registers. This may affect frame reception and transmission in the protocol layer. + +Defined in: ZW_led_api.h + +Parameters: + +pwLevel IN A pointer to an array with 4 16-bits values. + +0x0000-0xFFFF Duty cycle times of the LED controller channels. The first 16 bit element in the array determines the value for channel 0. The next 16 bit element determines the value for channel 1, etc. + +Serial API (Not supported) + +## 4.3.18.3 ZW_LED_waveform_set + +void ZW_LED_waveform_set(BYTE bChannel WORD wLevel) + +ZW_LED_waveform_set MAY be used to set the duty cycle time of one LED controller channel. + +The function SHOULD NOT be called repeatedly. This may cause race conditions in the LED controller latch registers. The companion function ZW_LED_data_busy MAY be used to check if the LED controller is ready for a new value. The application MUST NOT repeatedly call ZW_LED_data_busy from a busy waiting loop as this may affect frame reception and transmission in the protocol layer. + +Defined in: ZW_led_api.h + +Parameters: + +bChannel IN The channel ID + +LED_CHANNEL0 LED_CHANNEL1 LED_CHANNEL2 LED_CHANNEL3 + +wLevel The duty cycle of the channel + +0x0000-0xFFFF + +Serial API (Not supported) + +## 4.3.18.4 ZW_LED_data_busy + +BOOL ZW_LED_data_busy(void) + +ZW_LED_data_busy is used to check to see if the LED controller is ready for a new value. + +The application MUST NOT repeatedly call ZW_LED_data_busy from a busy waiting loop as this may affect frame reception and transmission in the protocol layer. + +Defined in: ZW_led_api.h + +Return values: + +BOOL TRUE The LED controller cannot accept new waveform values, since it has not yet read in the previous data set. Wait up to 2 16 /32MHz = 2.048ms and check again. + +FALSE The LED controller can accept new waveform values + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.01-carrier-detectorgenerator.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.01-carrier-detectorgenerator.md new file mode 100644 index 0000000..148d501 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.01-carrier-detectorgenerator.md @@ -0,0 +1,20 @@ + +# 4.3.19.1 Carrier Detector/Generator + +The carrier detector can detect the carrier waveform (high and low periods) of a carrier modulated IR signal. + +Carrier Low Carrier Low + +Carrier high Carrier high + +Figure 32. Carrier Waveform + +The following bullets provide a short feature list of the Carrier Detector/generator. + +1. IR Carrier Generator frequency range: 7.8 kHz – 16 MHz (50/50 duty cycle) or 10.4 kHz -10.7 MHz (33/66 duty cycle) 2. A built-in Glitch Remover is able to remove glitches on the incoming IR signal. 3. For each detection process the IR Carrier Detector can calculate an average of the “high” duration and an average of the “low” duration over 1 (no averaging), 2, 4, or 8 periods. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.02-organization-of-markspace-data-in-memory.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.02-organization-of-markspace-data-in-memory.md new file mode 100644 index 0000000..1adb104 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.02-organization-of-markspace-data-in-memory.md @@ -0,0 +1,49 @@ + +# 4.3.19.2 Organization of Mark/Space Data in Memory + +Both the IR Receiver engine and the IR Transmitter engine use SRAM to store mark/space data information. The data is stored in the same format for both engines, as depicted in figure below. The width of a mark is stored in 1 to 3 bytes – likewise the width of a space is stored in 1-3 bytes. + +Bit 7 in each byte is used to differentiate the mark and space bytes. That is, bit 7 of all “mark”-bytes are set to 1 and bit 7 of all “space”-bytes are set to 0. + +The maximum number of bits used to describe a mark or space width is 16. The means that 3 bytes are needed to store a 16 bit value (the upper 6 bits of the 3 rd byte are unused); whereas 2 bytes are needed to store a 14 bit value, and only one byte is needed to store a 7 bits value. + +Refer to the example as depicted in figure below, where: + +3 bytes are used for the start mark (PS0) 3 bytes are used for the start space (PS1) 2 bytes are used for each of the rest of the mark/spaces The maximum size of the mark/space data information is 511 bytes. The data can be stored anywhere in the lower 4K XRAM in the 500 series Z-Wave SoC. + +| | | | +| --- | --- | --- | +| 1 | PS4[6:0] | | +| 1 | PS4[13:7] | | +| 0 | PS3[6:0] | | +| 0 | PS3[13:7] | | +| 1 | PS2[6:0] | | +| 1 | PS2[13:7] | | +| 0 | PS1[6:0] | | +| 0 | PS1[13:7] | | +| 0 | | PS1[15:14] | +| 1 | PS0[6:0] | | +| 1 | PS0[13:7] | | +| 1 | | PS0[15:14] | + +Figure 33. Mark/Space Data Memory Organization + +The width is described as a certain count of prescaled clock periods. E.g if the prescaler is set to 1/16 and the width of a mark is 889us, the width will be stored as + +period 889 us   1798 LSB prescaler 16 f 32 MHz + +That is, + +ln(1798)  10. 81 ln(2) + + 11 bits are needed 2 bytes. + +Since the maximum number of bits used to store each mark or space width is 16. It results in a maximum mark or space width of: + + 262ms using clock divider of 128 or  1.7s using the Carrier Generator @ 36kHz diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.03-ir-transmitter.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.03-ir-transmitter.md new file mode 100644 index 0000000..077a902 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.03-ir-transmitter.md @@ -0,0 +1,34 @@ + +# 4.3.19.3 IR Transmitter + +Before the IR transmitter can start generating the IR stream the IR Transmitter must have been [initialized, the Mark/Space data must have been built in a buffer in the lower 4kB XRAM, and the IR interrupt is optionally enabled. The organization of the Mark/Space data is described in section 4.3.19.2.](04.03.19.01-carrier-detectorgenerator.md#43191-carrier-detectorgenerator) Additionally, the Carrier Generator must be initialized. + +The function [ZW_IR_tx_init](04.03.19.05-zw_ir_tx_init.md#43195-zw_ir_tx_init) must be called to initialize all the needed parameters as described below [and in section 4.3.19.5:](04.03.19.05-zw_ir_tx_init.md#43195-zw_ir_tx_init) + +1. The prescaler value for generating the carrier signal can be either: 1, 2, 3, 4, 5, 6, 7, or 8 resulting in a clock speed of either 32MHz, 16MHz, 32/3MHz, 8MHz, 32/5MHz, 16/3MHz, 32/7MHz, or 4MHz 2. The IR transmitter can use a prescaler that use the 32MHz clock divided by 1, 2, 4, 8, 16, 32, 64, or 128. It can also use the rising edge of the carrier generated by the Carrier Generator. 3. The output(s) can be inverted as an option 4. The Idle state of the IR signal can be either high or low 5. One, two, or three IO’s can be used in parallel for driving an IR LED. Each output buffer can drive 12mA. 6. The carrier wave form is set by the carrier prescaler and two parameters that sets the low and high period of the carrier signal. + +If only one IR coding style is used in a application the ZW_IR_tx_init function can be placed in ApplicationInitHW, otherwise it can be placed in other parts of the code, typically in ApplicationPoll + +The function ZW_IR_tx_data [must be called when a certain IR stream is to be transmitted. The parameters for this function sets is described below and in section 4.3.19.6](04.03.19.06-zw_ir_tx_data.md#43196-zw_ir_tx_data) + +1. The address of the buffer in lower 4kB XRAM. 2. Size of IR data buffer in XRAM. The maximum size of the XRAM buffer is 511 bytes. + +The IR Transmitter takes over control of the enabled IO’s (P3.4, P3.5, and/or P3.6) when the function ZW_IR_tx_data is called and releases the control of the enabled IO’s when the IR signal has been transmitted. Therefore, to make sure that IO’s used by the IR transmitter (P3.4, P3.5, and/or P3.6) are output(s) and at the correct idle state, the GPIO must be set as outputs and the state must be set accordingly. + +An IR interrupt routine is supplied with the ZW_phy_infrared_040x library. A variable ir_tx_flag (BOOL) is set TRUE when an IR message has been transmitted after ZW_IR_tx_data has been called. The variable is cleared when calling ZW_IR_tx_data. ir_tx_flag + +Once the IR Transmitter is started, use the function ZW_IR_disable to cancel the operation. + +[An example of how to initialize and run the IR Transmitter is shown in Figure 34.](04.03.19.03-ir-transmitter.md#43193-ir-transmitter) void ApplicationInitHW() { EA=1; EIR=1;: /* Carrier freq = 8MHz/(74+148)=36kHz, Carrier duty cycle 33/66 */ ZW_IR_tx_init(FALSE, // Use Mark/Space prescaler 3, // Prescaler: 32MHz/(2^3)=4MHz FALSE, // Output is not inverted FALSE, // Output state is low 0x03, // Enable P3.4 and P3.5 3, // Carrier prescaler set to 4 (32MHz/4=8MHz) 74, // Carrier low 74/8MHz = 9.25us 148); // Carrier high 148/8MHz = 18.5us: } + +void ApplicationPoll() { BYTE bIrBuffer[16]; + +switch (mainState) {: case SEND_PLAY: // This IR message send a “PLAY” command bIrBuffer[0]=0xA0; bIrBuffer[1]=0x20; bIrBuffer[2]=0xBF; bIrBuffer[3]=0x20; bIrBuffer[4]=0xA0; bIrBuffer[5]=0x20; bIrBuffer[6]=0xA0; bIrBuffer[7]=0x20; bIrBuffer[8]=0xA0; bIrBuffer[9]=0x20; bIrBuffer[10]=0xA0; bIrBuffer[11]=0x20; bIrBuffer[12]=0xBF; bIrBuffer[13]=0x20; bIrBuffer[14]=0xDF; bIrBuffer[15]=0x80; ZW_IR_status_clear(); // Clear all IR status flags /* Use IrBuffer as buffer, size 16 bytes */ ZW_IR_tx_data((WORD)bIrBuffer, // Address of buffer 16); // Size of buffer mainState=WAIT_IR_DONE; break; case WAIT_IR_DONE: if (ir_tx_flag==TRUE) // Wait until IR TX flag is set { mainState=IDLE; } + +break; } } Figure 34. Code Example on Use of IR Transmitter diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.04-ir-receiver.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.04-ir-receiver.md new file mode 100644 index 0000000..876ef47 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.04-ir-receiver.md @@ -0,0 +1,38 @@ + +# 4.3.19.4 IR Receiver + +Before the IR Receiver can be used to learn an incoming IR stream the IR receiver must have been initialized, the Mark/Space data buffer must have been allocated in the lower 4kB XRAM, and the IR interrupt must be enabled. + +[The organization of the Mark/Space data is described in section 4.3.19.2.](04.03.19.01-carrier-detectorgenerator.md#43191-carrier-detectorgenerator) + +The function [ZW_IR_learn_init](04.03.19.05-zw_ir_tx_init.md#43195-zw_ir_tx_init) must be called to initialize all the needed parameters as described below [and in section 4.3.19.5:](04.03.19.05-zw_ir_tx_init.md#43195-zw_ir_tx_init) + +1. The Rx SRAM buffer size is configurable. (1-511 bytes) 2. The Mark/Space detector in the IR Receiver can use either a prescaler that use the 32MHz clock divided by 1, 2, 4, 8, 16, 32, 64, or 128. 3. If the IR Receiver requires more SRAM space for the incoming IR stream, the MCU is interrupted and an error flag is set 4. The IR Receiver can be configured to remove glitches on the incoming IR signal 5. The IR Receiver can be configured to average the detected duration of the low/high periods of the Carrier 6. The IR input signal can be inverted as an option. 7. The IR Receiver can detect that the trailing space after the last mark of a received IR message is longer that a specific size. This size must be set and this works at the same time as a timeout if the message for some reason is shorter than expected. + +[Call the function](04.03.19.09-zw_ir_learn_data.md#43199-zw_ir_learn_data) ZW_IR_learn_data to start the learn process. The function is described below and in [section 4.3.19.9:](04.03.19.09-zw_ir_learn_data.md#43199-zw_ir_learn_data) + +1. When the learn process starts the IR receiver will start out using the highest possible prescaler value for the Carrier detector. When it then detects a carrier, it will measure the duration of the low and high periods of the carrier and, if possible, rescale the prescaler to a lower value and rerun the carrier measurement. This is done to achieve the highest precision of the carrier measurement while preventing timer overflow. 2. The learn process will terminate when the IR Receiver has detected at least one Mark and then a Space larger than a configurable amount of time, as described above. + +An IR interrupt routine is supplied with the ZW_phy_infrared_040x library. A variable ir_rx_flag (BOOL) is set TRUE when an IR message has been received. The variable is cleared ir_rx_flag when calling ZW_IR_learn_data. Call the function ZW_IR_learn_status_get to get the size of the received mark/space data, the detected carrier characteristics and error state (status flags). The function ZW_IR_status_clear clears the status flag. + +Once the IR Receiver is started, use the function ZW_IR_disable to cancel the operation. + +An example of how to initialize and run the IR Receiver is shown below. + +BYTE bIrBuffer[256]; + +void ApplicationInitHW() { + +EA=1; EIR=1; + +ZW_IR_learn_init((WORD)bIrBuffer // Buffer address 256, // Buffer Size 4, // Prescaler: 32MHz/(2^4)=2MHz 7, // Trailing space min 2^16/2MHz=32.8ms 2, // Run average over 4 periods 1, // Remove glitches below 125ns FALSE); // Do not invert input } + +void ApplicationPoll() { WORD wRxDataLen; BYTE bRxCarrierLow; BYTE bRxCarrierHigh; BYTE bRxStatus;: switch(mainState) { case START_IR_LEARN: ZW_IR_status_clear(); // Clear all IR status flags ZW_IR_learn_data(); // Start IR Receiver mainState=WAIT_IR_DONE; break; case WAIT_IR_DONE: if (ir_rx_flag==TRUE) // Wait until IR RX flag is set { ZW_IR_learn_status_get(&wRxDataLen, &bCarrierPrescaler, &bRxCarrierLow, &bRxCarrierHigh, &bRxStatus); if (bRxStatus == 0x00 || bRxStatus == IRSTAT_CDONE) { if (bRxStatus != IRSTAT_CDONE) { /* report that carrier could not be detected */: } /* decode received data */: } else { /* error handling */: } mainState=IDLE; } else { /* Cancel the operation when boCancelIR is set TRUE by other part of the code */ if (boCancelIR == TRUE) ZW_IR_disable(); mainState=IDLE; } break; } } Figure 35. Code Example on Use of IR Receiver + +The application software can use the following IR API calls to control the 500 Series Z-Wave SoC IR Controller. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.05-zw_ir_tx_init.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.05-zw_ir_tx_init.md new file mode 100644 index 0000000..c7882ac --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.05-zw_ir_tx_init.md @@ -0,0 +1,44 @@ + +# 4.3.19.5 ZW_IR_tx_init + +void ZW_IR_tx_init(BYTE boMSTimer, BYTE bMSPrescaler, BYTE boInvertOutput, BYTE boHighDrive, BYTE boIdleState, BYTE bOutputEnable, BYTE bCarrierPrescaler, BYTE bCarrierLow, BYTE bCarrierHigh) + +ZW_IR_tx_init initializes the 500 Series Z-Wave SoC's integrated IR controller to Transmitter mode and sets the required TX options. + +Defined in: ZW_infrared_api.h + +Parameters: + +boMSTimer IN TX Mark/Space prescaler mode: + +TRUE Mark/space generator runs on carrier period timer. That is, the length of the Marks/Spaces is calculated as the carrier period multiplied by the value read in XRAM + +FALSE Mark/space generator runs on a prescaled timer. That is, the length of the Marks/Spaces is calculated as the prescaled timer period multiplied by the value read in XRAM. Prescaler value is set by bMSPrescaler. + +bMSPrescaler IN Mark/Space timer prescaler + +Valid values: 0-7 Not applicable when boMSTimer is Resulting timer clock frequency: true 0: 32 MHz 1: 16 MHz 2: 8 MHz 3: 4 MHz 4: 2 MHz 5: 1 MHz 6: 500 kHz 7: 250 kHz + +boInvertOutput IN Invert IR output TRUE output is inverted FALSE output is not inverted + +boHighDrive Invert IR output TRUE use 12mA drive strength of IR Tx IO output buffers FALSE use 8mA drive strength of IR Tx IO out buffers boIdleState IN Idle State of IR output TRUE Idle state is high FALSE Idle state is low + +bOutputEnable IN Outputs enabled + +Valid values: 0-7 Idle state is high 000: All outputs disabled xx1: P3.4 enabled x1x: P3.5 enabled 1xx: P3.6 enabled + +bCarrierPrescaler IN Carrier generator prescaler + +Valid values: 0-7 Resulting timer clock frequency: 0: 32MHz 1: 32MHz/2 2: 32MHz/3 3: 32MHz/4 4: 32MHz/5 5: 32MHz/6 6: 32MHz/7 7: 32MHz/8 + +bCarrierLow IN Carrier low time 0: 1 prescaled clock period 1: 2 prescaled clock periods: : 255: 256 prescaled clock periods + +bCarrierHigh IN Carrier High time 0: 1 prescaled clock period 1: 2 prescaled clock periods: : 255: 256 prescaled clock periods + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.06-zw_ir_tx_data.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.06-zw_ir_tx_data.md new file mode 100644 index 0000000..af11486 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.06-zw_ir_tx_data.md @@ -0,0 +1,22 @@ + +# 4.3.19.6 ZW_IR_tx_data + +void ZW_IR_tx_data( WORD pBufferAddress, WORD wBufferLength) + +ZW_IR_tx_data sets the address and the length of the buffer containing the Mark/space data to be sent. The IR Controller will start to transmit immediately after these values have been set. + +Defined in: ZW_infrared_api.h + +Parameters: + +pBufferAddress IN Address of Tx buffer in lower XRAM memory + +wBufferLength IN Number of bytes in TX buffer. Valid values (1-511) + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.07-zw_ir_tx_status_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.07-zw_ir_tx_status_get.md new file mode 100644 index 0000000..3bb4cda --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.07-zw_ir_tx_status_get.md @@ -0,0 +1,24 @@ + +# 4.3.19.7 ZW_IR_tx_status_get + +BYTE ZW_IR_tx_status_get(void) + +ZW_IR_tx_status_get is used to check to the status of the IR controller after an IR message has been transmitted. + +Defined in: ZW_infrared_api.h + +Return values: + +IRSTAT_MSOVERFLOW The format of the data in the IR buffer is invalid. The perceived Mark/Space value is greater than 2 16. + +IRSTAT_PSSTARV The IR controller’s DMA engine was not able to read data from XRAM in time because the access to the XRAM was used by (an) other DMA engine(s) with higher priority. To get rid of this error, try to disable other DMA engines (USB, RF, etc.) and run the IR transmitter again. + +IRSTAT_ACTIVE The IR Controller is active + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.08-zw_ir_learn_init.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.08-zw_ir_learn_init.md new file mode 100644 index 0000000..074382a --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.08-zw_ir_learn_init.md @@ -0,0 +1,34 @@ + +# 4.3.19.8 ZW_IR_learn_init + +void ZW_IR_learn_init(WORD pBufferAddress, WORD wBufferLen, BYTE bMSPrescaler, BYTE bTrailSpace, BYTE bCAverager, BYTE bCGlitchRemover, BYTE boInvertInput) + +ZW_IR_learn_init initializes the 500 Series Z-Wave SoC's integrated IR controller to receive/learn mode and sets the required RX options. Defined in: ZW_infrared_api.h + +Parameters: + +pBufferAddress IN Address of Rx buffer in lower XRAM memory + +wBufferLength IN Size of RX buffer. + +Valid values (1-511) + +bMSPrescaler IN Mark/Space timer prescaler + +Valid values: 0-7 Resulting timer clock frequency: 0: 32MHz 1: 16MHz 2: 8MHz 3: 4MHz 4: 2MHz 5: 1MHz 6: 500kHz 7: 250kHz + +bTrailSpace IN Trailing space after last Mark. After the incoming IR signal has been low for this period of time the IR receiver stops. Valid values: 0-7 0: 512 prescaled clock periods 1: 1024 prescaled clock periods 2: 2048 prescaled clock periods 3: 4096 prescaled clock periods 4: 8192 prescaled clock periods 5: 16384 prescaled clock periods 6: 32768 prescaled clock periods 7: 65536 prescaled clock periods + +bCAverager IN Average Carrier high/low length measurement over multiple carrier periods. Valid values: 0-3 0: 1 carrier period 1: 2 carrier periods 2: 4 carrier periods 3: 8 carrier periods (Recommended value) + +bCGlitchRemover IN Remove glitches from incoming IR signal. Valid values: 0-3 0: disabled 1: < 125ns 2: < 250ns 3: < 500ns + +boInvertInput IN TRUE IR input is inverted FALSE IR input is not inverted + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.09-zw_ir_learn_data.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.09-zw_ir_learn_data.md new file mode 100644 index 0000000..03b9ad3 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.09-zw_ir_learn_data.md @@ -0,0 +1,18 @@ + +# 4.3.19.9 ZW_IR_learn_data + +void ZW_IR_learn_data(void) + +ZW_IR_learn_data clears the variable and starts the IR Controller in Rx/learn mode. Use ir_rx_flag ZW_IR_disable to cancel on ongoing learn process. + +Defined in: ZW_infrared_api.h + +Serial API (Not supported) + +[Refer to section 0 for a detailed description of the learn function.](04.03.19.03-ir-transmitter.md#43193-ir-transmitter) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.10-zw_ir_learn_status_get.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.10-zw_ir_learn_status_get.md new file mode 100644 index 0000000..da56410 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.10-zw_ir_learn_status_get.md @@ -0,0 +1,38 @@ + +# 4.3.19.10 ZW_IR_learn_status_get + +void ZW_IR_learn_status_get(WORD *wDataLength, BYTE *bCarrierPrescaler, BYTE *bCarrierLow, BYTE *bCarrierHigh, BYTE *bStatus) + +ZW_IR_learn_status_get is used to check to the status of the IR controller, to get the length of the received data, the detected carrier characteristics, and the error state. Call this function after a learn operation is done, i.e., after the ir_rx_flag variable has been set. Defined in: ZW_infrared_api.h + +Parameters: + +wDataLength OUT Length of the received data + +bCarrierPrescaler OUT Optimal Carrier prescaler value + +Valid values: 0-7 0: 32MHz 1: 32MHz/2 2: 32MHz/3 3: 32MHz/4 4: 32MHz/5 5: 32MHz/6 6: 32MHz/7 7: 32MHz/8 + +bCarrierLow OUT Length of the Low period of the Carrier (in prescaled system clocks) + +bCarrierHigh OUT Length of the High period of the Carrier (in prescaled system clocks) + +bStatus OUT IRSTAT_PSSTARV The IR controller’s DMA engine was not able to write data from XRAM in time because the access to the XRAM was used by (an) other DMA engine(s) with higher priority. To get rid of this error, try to disable other DMA engines (USB, RF, etc.) and run the IR transmitter again. + +IRSTAT_MSOVERFLOW The duration of a mark/space exceeded 2 16 prescaled clock periods. + +IRSTAT_COF The Carrier detector failed because the perceived carrier low/high period was too long. + +IRSTAT_CDONE The Carrier detector completed measuring the carrier without errors + +IRSTAT_RXBUFOVERFLOW The RX buffer was too small to store the received IR data + +IRSTAT_ACTIVE The IR Controller is active + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.11-zw_ir_status_clear.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.11-zw_ir_status_clear.md new file mode 100644 index 0000000..721601c --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.11-zw_ir_status_clear.md @@ -0,0 +1,16 @@ + +# 4.3.19.11 ZW_IR_status_clear + +void ZW_IR_status_clear(void) + +ZW_IR_status_clear clears the Tx and Rx IR Status flags. Call this function before rerunning the IR Controller. + +Defined in: ZW_infrared_api.h + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.12-zw_ir_disable.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.12-zw_ir_disable.md new file mode 100644 index 0000000..189106e --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/04.03.19.12-zw_ir_disable.md @@ -0,0 +1,16 @@ + +# 4.3.19.12 ZW_IR_disable + +void ZW_IR_disable(void) + +This function disables any ongoing IR operation and sets the IR Controller to its idle state. Use ZW_IR_status_clear to clear any status bit before starting the IR Transmitter or IR Receiver. + +Defined in: ZW_infrared_api.h + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/index.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/index.md new file mode 100644 index 0000000..7afc8c1 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.19-infrared-controller-api/index.md @@ -0,0 +1,42 @@ + +# 4.3.19 Infrared Controller API + +The built-in Infrared (IR) Controller is targeted at IR remote control applications. The IR controller can operate either as an IR transmitter or as an IR receiver. When operating as a transmitter one or more of the three outputs (P3.4, P3.5, and P3.6) can be enabled as IR outputs that drive an IR LED, as depicted in figure below. Each output can drive 12mA. Hence, using three outputs give a drive strength of 36mA. If 36mA is insufficient you will have to implement an external driver. + +| Optional driver R LED IR receiver module | Z-Wave Chip P3.4/IRTX0 P3.5/IRTX1 P3.6/IRTX2 P3.1/IRRX | +| --- | --- | + +Figure 29. External IR Hardware + +An external IR receiver module or an IR transistor must be connected to Pin P3.1 when operating in Receive mode. An IR receiver module has a built-in photo transistor and preamplifier with automatic gain control and gives a digital TTL/CMOS output signal. The IR receivers can be found in two versions, with and without demodulator. The versions without demodulator (like Vishay TSOP 98200) generates an output signal with carrier (as depicted in the upper part of figure below), whereas the versions with demodulator (like Vishay TSOP322xx) generates an output signal without the carrier (as depicted in the lower part of figure below). Therefore, the one without demodulator is best for code learning applications, where you want to be able to detect the carrier frequency. The one with modulator has improved immunity against ambient light such as fluorescent lamps. + +Using an photo transistor, where the transistor is connected directly to the 500 Series Z-Wave Chip requires that the transmitting IR LED is placed within a short range (2”-4”) of the IR transistor, since the IR transistor signal is analog and isn’t amplified. This circuit is also sensitive also to ambient light. + +Figure 30. IR Signal with and without Carrier + +In both cases, the IR Receiver detects widths of the marks (high/carrier on) and spaces (low) of a coded IR message, as seen in figure below. The mark/space width data is stored in SRAM using DMA. While running, the IR Controller requires very little MCU processing. The IR receiver is able to detect the waveform of the carrier 1. + +The IR Transmitter generates a carrier and the marks and spaces for an IR message. The widths of the marks and the spaces are read from SRAM using DMA. Figure 31. IR Coded Message with Carrier + +Both the IR Receiver and the IR Transmitter can be configured to detect/generate a wide range of IR coding formats. + +## Contents + +- [4.3.19.1 Carrier Detector/Generator](04.03.19.01-carrier-detectorgenerator.md) +- [4.3.19.2 Organization of Mark/Space Data in Memory](04.03.19.02-organization-of-markspace-data-in-memory.md) +- [4.3.19.3 IR Transmitter](04.03.19.03-ir-transmitter.md) +- [4.3.19.4 IR Receiver](04.03.19.04-ir-receiver.md) +- [4.3.19.5 ZW_IR_tx_init](04.03.19.05-zw_ir_tx_init.md) +- [4.3.19.6 ZW_IR_tx_data](04.03.19.06-zw_ir_tx_data.md) +- [4.3.19.7 ZW_IR_tx_status_get](04.03.19.07-zw_ir_tx_status_get.md) +- [4.3.19.8 ZW_IR_learn_init](04.03.19.08-zw_ir_learn_init.md) +- [4.3.19.9 ZW_IR_learn_data](04.03.19.09-zw_ir_learn_data.md) +- [4.3.19.10 ZW_IR_learn_status_get](04.03.19.10-zw_ir_learn_status_get.md) +- [4.3.19.11 ZW_IR_status_clear](04.03.19.11-zw_ir_status_clear.md) +- [4.3.19.12 ZW_IR_disable](04.03.19.12-zw_ir_disable.md) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.20-keypad-scanner-controller-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.20-keypad-scanner-controller-api.md new file mode 100644 index 0000000..5e86f59 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.20-keypad-scanner-controller-api.md @@ -0,0 +1,124 @@ + +# 4.3.20 Keypad Scanner Controller API + +The built-in hardware keypad scanner is able to scan a key matrix of up to 8 rows x 16 columns. When the Keypad Scanner is activated, the 8 row inputs (P1.0-P1.7) must either be connected to the hardware key matrix or kept open. The number of columns can be configured to the range 1-16. The actual IO’s being used as column outputs are “KSCOL0” (P0.0) when the column count is set to one, “KSCOL0, KSCOL1” (P0.0, P0.1) when the column count is set to two, “KSCOL0, KSCOL1, KSCOL2” (P0.0, P0.1, P0.2) when the column count is set to three, etc. A column output can be left open, though. + +| | | | | | | | | | | | | | | | | | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| | | | | | | | | | | | | | | | | | | +| | | | | | | | | | | | | | | | | | | +| | | | | | | | | | | | | | | | | | | +| | | | | | | | | | | | | | | | | | | +| | | | | | | | | | | | | | | | | | | +| | | | | | | | | | | | | | | | | | | +| | | | | | | | | | | | | | | | | | | +| | | | | | | | | | | | | | | | | | | + +Figure 36. Keypad Matrix + +Once the Keypad Scanner is enabled, it will scan each column for an amount of time (Scan Delay). If it, at a certain column detects a key press, it will wait for a period (Debounce delay) to get any eventual debounce noise to disappear. Then it will detect whether the input stays stable for another amount of time (Stable delay). The Keypad Scanner will issue an interrupt request to the MCU, if the row input is stable for the defined amount of “Stable delay” time. See figure below. + +| Clears MCU Handles Key Press IRQ Flag | | | | | | +| --- | --- | --- | --- | --- | --- | +| KeyPad No keys Key press No keys pressed in Column 2 Row input stable pressed | | | | | | +| Sets Key Press KeyPad interrupt flag Scans Scans Scans Awaits Verifies Scans Scanner Column 0 Column 1 Column 2 debounce stable input Idle Column 3 | | | | | | +| | | | | | | +| | | | | | | + +time + +Figure 37. Scan Flow + +Each of these delays can be configured by using the function ZW_KS_init, which must be called in ApplicationInitHW as shown in figure below. void KeyPadChanges(BYTE_P pbKeypadMatrix, BYTE bStatus) { /* Call the user defined application function InterpretKeys with the keypad matrix as parameter */ switch (bStatus) { case ZW_KS_KEYPRESS_VALID: InterpretKeys(keyPadMatrix); break; case ZW_KS_KEYPRESS_INVALID: beep(); break; case ZW_KS_KEYPRESS_RELEASED: cleanup(); break default: } } + +void ApplicationInitHW(BYTE bWakeupReason) {: ZW_KS_init(7, /* 8 Columns */ 4, /* Column scan delay 10ms */ 15, /* Debounce delay 32ms */ 5, /* Row Stable delay 12ms */ 10, /* Polling period of 100 ms*/ KeyPadChanges /* The callback function used to notify */ /* the application when changes occurs */ /* to the keypad matrix */) ZW_KS_enable(TRUE);: } + +void ApplicationPoll() {: /* Go into power down mode */ ZW_KS_pd_enable(TRUE); ZW_SetSleepMode(WUT_MODE,ZW_INT_MASK_EXT1,0);: } Figure 38. Example of the API Calls for the KeyPad Scanner + +The Keypad ISR will detect any changes occurred to the keypad matrix. The changes to the keypad matrix array will be polled periodically. The polling period is defined by the application through ZW_KS_init. + +Apart from setting the size of the key matrix and the delays, a callback function must be defined in ZW_KS_init. If any changes to the keypad matrix are detected the application will be notified by calling this user defined callback function. Figure above shows an example of how ZW_KS_init is used. + +The parameter to the callback function is an array of the type BYTE. The array has 16 elements one for each column. It has 16 elements regardless of the number of actual configured columns in use. The element with index n holds the row-status for column number n. That is, bit 0 of an element hold the status of row 0, bit 1 of an element hold the status of row 1, etc. The array is defined in the Keypad API library. + +Note: the Keypad Scanner IRQ signal is shared with “EXT1”, external interrupt 1. Therefore, that interrupt routine must not be included in the application code, when using the Keypad Scanner. + +When a key press must wake up the 500 Series Z-Wave SoC from powerdown mode, ZW_KS_pd_enable(TRUE) must be called just before the chip is put into powerdown mode. Doing so, will activate the external interrupt, if any key is pressed. When the 500 Series Z-Wave SoC is awake first the function ZW_KS_init and then ZW_KS_enabled must be called to initialize and enable the Key Scanner and thereby grab the actual key combination. + +## 4.3.20.1 ZW_KS_init + +void ZW_KS_init( BYTE bCols BYTE bScanDelay BYTE bDebounceDelay, BYTE bStableDelay BYTE bReportWaitTimeout, VOID_CALLBACKFUNC(KeyPadCallBack)(BYTE_P keyMatrix, BYTE bStatus) ) + +ZW_KS_init initializes the 500 Series Z-Wave SoC's integrated Keypad Scanner. + +Defined in: ZW_keypad_scanner_api.h + +Parameters: + +bCols IN Sets the number of enabled columns. Valid values 0-15. 0: 1 Column 1: 2 Columns: 15: 16 Columns E.g. setting this to 7 will enable KSCOL0- KSCOL7 (P0.0-P0.7) + +bScanDelay IN Sets column “Scan delay” 0: 2ms 1: 4ms: 15: 32ms + +bDebounceDelay IN Sets “debounce delay” 0: 2ms 1: 4ms: 15: 32ms + +bStableDelay IN Sets “stable delay” 0: 2ms 1: 4ms: 15: 32ms + +bReportWaitTimeout IN Set the timeout delay before the main loop call the KeyPadCallBack function. 0: not valid 1: 10 ms 2: 20 ms: 255: 2550 ms KeyPadCallBack IN The call back function that the main loop will use to notify the application about the changes in the keypad matrix. + +The function will only be called when changes to the keypad matrix occurs. + +Parameters: + +pbKeyMatrix OUT: + +Pointer to the keypad matrix BYTE array. + +bStatus OUT: + +Returns the status of the contents of the key matrix as one of the follwing: + +ZW_KS_KEYPRESS_VALID The contents of the key matrix array is valid + +ZW_KS_KEYPRESS_INVALID The contents of the key matrix array is invalid, i.e., more than 3 keys are pressed in an invalid manner + +ZW_KS_KEYPRESS_RELEASED All keys have been released + +Serial API (Not supported) + +## 4.3.20.2 ZW_KS_enable + +void ZW_KS_enable(BOOL boEnable) + +ZW_KS_enable enables or disables the Keypad Scanner. Must be called in ApplicationInitHW. + +Defined in: ZW_keypad_scanner_api.h + +Parameters: + +boEnable IN TRUE Enables Keypad Scanner + +FALSE Disables Keypad Scanner + +Serial API (Not supported) + +## 4.3.20.3 ZW_KS_pd_enable + +void ZW_KS_pd_enable(BYTE boEnable) + +ZW_KS_ pd_enable(TRUE) must be called before putting the 500 Series Z-Wave SoC into powerdown mode, if the chip is to be woken by a key press. + +Defined in: ZW_keypad_scanner_api.h + +Parameters: + +boEnable IN TRUE Enables Keypad Scanner Powerdown mode + +FALSE Disables Keypad Scanner Powerdown mode + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.21-usbuart-common-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.21-usbuart-common-api.md new file mode 100644 index 0000000..c4c1bd6 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.21-usbuart-common-api.md @@ -0,0 +1,92 @@ + +# 4.3.21 USB/UART Common API + +This is a simple unified API for using the UART0 or USB interfaces. + +If the C-define “USBVCP” is defined, then all functions in this chapter will access the USB interface, otherwise UART0 will be used + +First the API calls ZW_InitSerialIf and ZW_FinishSerialIF must be called to initialize the interface, after that data can be transferred using the put and get functions described in the following sections. + +For USB: On windows you need a driver included in the DevKit. On linux and Mac no driver is needed. On all platforms you will get a virtual serial port on the PC side. The certified USB interface complies to USB 2.0 full speed. However, USB driver supports only Bus-Powered USB devices and not Self- Powered. + +## 4.3.21.1 ZW_InitSerialIf + +void ZW_InitSerialIf(WORD wBaudRate) + +This function initializes the controller using the baud rate indicated by the parameter wBaudRate. It is important to called the function ZW_FinishSerialIf immediately after to indicate that initialization is finished. + +Notice: When using the USB-interface, this parameter does not impact the actual transmission-speed as it is dictated by the USB standard. + +Defined in: ZW_conbufio.h + +Parameters: + +bBaudRate IN 96=>9600baud/s, 1152=>115200baud/s + +Serial API (Not supported) + +## 4.3.21.2 ZW_FinishSerialIf + +BOOL ZW_FinishSerialIf(void) + +This function must be called immediately after ZW_InitSerialIf to indicate that initialization is finished. + +Defined in: ZW_conbufio.h + +Return value + +Always TRUE + +Serial API (Not supported) + +## 4.3.21.3 ZW_SerialCheck + +BYTE ZW_SerialCheck(void) + +This function checks if data has been received and is ready to be read + +Defined in: ZW_conbufio.h + +Return value + +Nonzero if there is data in the input queue + +Serial API (Not supported) + +## 4.3.21.4 ZW_SerialGetByte + +BYTE ZW_SerialGetByte(void) + +This function reads one byte from the input buffer. First use ZW_SerialCheck to make sure that there is data available. + +Defined in: ZW_conbufio.h + +Return value + +The byte received from the USB/UART interface + +Serial API (Not supported) + +## 4.3.21.5 ZW_SerialPutByte + +BYTE ZW_SerialPutByte(BYTE b) + +This function puts one byte into the USB/UART output buffer + +Defined in: ZW_conbufio.h + +Return value + +Non-zero for success + +Parameters: + +Byte b Data to be written to the USB/UART output buffer + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.22-flash-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.22-flash-api.md new file mode 100644 index 0000000..b32ac50 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.22-flash-api.md @@ -0,0 +1,118 @@ + +# 4.3.22 Flash API + +The Flash API provides functions for reading the NVR area of the Flash as well as functions for erasing and programming Flash code sectors. Each sector is 2KB and there is 64 sectors in total. The code address range for sector 0 is 0x00000-0x07FF, sector 1 is 0x00800-0x00FFF, etc. + +The Flash is erased sector by sector and each sector is programmed one page (256bytes) at a time. The data to be programmed into the flash sector is read from the lower 4kB XRAM. + +To minimize the possibility to erase or program the flash code area by a mistake a function, ZW_FLASH_code_prog_unlock() that takes a "unlock string" as parameter, has to be called before an erase or program operation can be execised. + +[Only those sectors that not have been protected by lock bits can be erased/programming by the MCU API calls. Refer to [3] for a description of how to set the protection lock bits.](../../08-references.md#8-references) + +// Program sectors 10 to 13 for (sector=10;sector<14;sector++) { // Unlock the flash erase and program funtions // the unlock string contains the four byte unlock string ZW_FLASH_code_prog_unlock(&unlock[0]); // Erase sector if(ZW_FLASH_code_sector_erase(sector)) { Handle error } // Check state if (ZW_FLASH_prog_state()) { Handle error } // lock the erase and program function ZW_FLASH_code_prog_lock(); // program flash sector page by page for (i=0; i<8; i++) { Make data ready in buffer in memory // unlock programming if(ZW_FLASH_code_prog_unlock(&unlock[0])) { Handle error } // program page 'i' in sector 'sector' with contents from // XRAM starting from the address set by '&buffer' if(ZW_FLASH_code_page_prog(&buffer, sector, i)) // page { Handle error } // lock the erase and program function ZW_FLASH_code_prog_lock(); Handle error } } // clear unlock to prevent undecired earse or prog operations unlock={0x00,0x00,0x00,0x00}; + +## 4.3.22.1 ZW_FLASH_code_prog_unlock + +BYTE ZW_Flash_code_prog_unlock(BYTE pbUnlockString) + +This function enables erase and program operations on non-protected Flash code sectors. + +Defined in: ZW_flash_api.h + +Parameters: + +pbUnlockString IN Pointer to a 4 byte The string: 0xDE, 0xAD, 0xBE, 0xEF string. + +Return value: + +BYTE Bit mask: + +Flash erase and programming is locked FLASH_STATE_LOCK: Flash erase and programming is unlocked Zero: + +Serial API (Not supported) + +## 4.3.22.2 ZW_FLASH_code_prog_lock + +BYTE ZW_Flash_code_prog_lock(void) + +This function disables erase and program operations on Flash code sectors. + +Defined in: ZW_flash_api.h + +Return value: + +BYTE Bit mask + +Flash erase and programming is locked FLASH_STATE_LOCK: Flash erase and programming is unlocked Zero: + +Serial API (Not supported) + +## 4.3.22.3 ZW_FLASH_code_sector_erase + +BYTE ZW_Flash_code_sector_erase(BYTE bSector) + +This function erases a non-protected Flash code sector. The erase operation has to be unlocked before this function will work, refer to ZW_FLASH_code_prog_unlock(). To check which sectors that have been protected use the function ZW_FLASH_nvr0_get() to read the protection bits in the bytes located at the NVR0 addresses 0-7. + +The MCU code execution will be halted for 5ms while the program operation is running. + +Defined in: ZW_flash_api.h + +Parameters: + +bSector IN Sector number (0-63). + +Return value: + +BYTE Bit mask + +FLASH_STATE_ERR: The Flash erase process failed The Flash erase process passed FLASH_STATE_DONE: + +Serial API (Not supported) + +## 4.3.22.4 ZW_FLASH_code_page_prog + +BYTE ZW_Flash_code_page_prog(BYTE pbRamAddress, BYTE bSector, BYTE bPage + +This function programs a non-protected Flash code sector page with data from XRAM. The program operation has to be unlocked before this function will work, refer to ZW_FLASH_code_prog_unlock(). To check which sectors that have been prptected use the function ZW_FLASH_nvr0_get() to read the protection bits in the bytes located in NVR0 at the addresses 0-7. + +The MCU code execution will be halted for up to 1.6ms while the program operation is running. + +Defined in: ZW_flash_api.h + +Parameters: + +pbRamAddress IN Pointer to data buffer in lower 4KB XRAM + +bSector IN Sector number (0-63). + +bPage IN Page number (0-7). + +Return value: + +BYTE Bit mask + +Flash erase and programming is locked FLASH_STATE_LOCK: The Flash programming process failed FLASH_STATE_ERR: The Flash programming process passed FLASH_STATE_DONE: + +Serial API (Not supported) + +## 4.3.22.5 ZW_FLASH_auto_prog_set + +void ZW_FLASH_auto_prog_set(void) + +This function enables the Auto Program Mode and resets the 500 Series Z-Wave SOC after 7.8ms.. + +Defined in: ZW_flash_api.h + +Parameters: + +none + +Serial API: + +HOST->ZW: REQ | 0x27 diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.23-crc-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.23-crc-api.md new file mode 100644 index 0000000..70ac571 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/04.03.23-crc-api.md @@ -0,0 +1,56 @@ + +# 4.3.23 CRC API + +The CRC API provides functions for calculating and checking CRC-16 value of a data area. The checksum is based on CRC-CCITT (0x1D0F). + +## 4.3.23.1 ZW_CheckCrc16 + +WORD ZW_CheckCrc16(WORD crc, BYTE pDataAddr, WORD bDataLen) + +This function calculates or check CRC-16 value of a data area having a starting address and length. + +Defined in: ZW_crc.h + +Parameters: + +crc IN Initialization or CRC-16 To calculate CRC-16 for a given data area set value. the initialization value equal to 0x1D0F. It can also be used to carry over CRC-16 value between separate calculations of multiple data areas. + +pDataAddr IN Address of data area. + +bDataLen IN Size of data area. + +Return value: + +WORD CRC-16 value: Calculated CRC-16 value Zero: CRC-16 value matches CRC-16 input value. + +Serial API (Not supported) + +## 4.3.23.2 ZW_CreateCrc16 + +WORD ZW_CreateCrc16(BYTE pHeaderAddr, BYTE bHeaderLen, BYTE pPayloadAddr, BYTE bPayloadLen) + +This function calculates a combined CRC-16 value of two data areas both having a starting address and length. This function calls ZW_CheckCrc16 twice. + +Defined in: ZW_crc.h + +Parameters: + +pHeaderAddr IN Pointer to address of data area1. + +bHeaderLen IN Size of data area1. + +pPayloadAddr IN Pointer to address of data area2. + +bPayloadLen IN Size of data area2. + +Return value: + +WORD CRC-16 value: Calculated CRC-16 value. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/index.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/index.md new file mode 100644 index 0000000..697f00e --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.03-z-wave-common-api/index.md @@ -0,0 +1,40 @@ + +# 4.3 Z-Wave Common API + +This section describes interface functions that are implemented within all Z-Wave nodes. The first subsection defines functions that must be implemented within the application modules, while the second subsection defines the functions that are implemented within the Z-Wave basis library. + +Functions that does not complete the requested action before returning to the application (e.g. ZW_SEND_DATA) have a callback function pointer as one of the entry parameters. Unless explicitly specified this function pointer can be set to NULL (no action to take on completion). + +[A serial API implementation provide an interface to the major part of interface functions via a serial port. The SDK contains a serial API application [18], which enables a host processor to control the interface](../../08-references.md#8-references) functions via a serial port. + +## Contents + +- [4.3.1 Required Application Functions](04.03.01-required-application-functions/index.md) +- [4.3.2 Z-Wave Basis API](04.03.02-z-wave-basis-api/index.md) +- [4.3.3 Z-Wave Transport API](04.03.03-z-wave-transport-api/index.md) +- [4.3.4 ZWave Firmware Update API](04.03.04-zwave-firmware-update-api.md) +- [4.3.5 Z-Wave Node Mask API](04.03.05-z-wave-node-mask-api.md) +- [4.3.6 IO API](04.03.06-io-api.md) +- [4.3.7 GPIO Macros](04.03.07-gpio-macros.md) +- [4.3.8 Z-Wave NVM Memory API](04.03.08-z-wave-nvm-memory-api.md) +- [4.3.9 Z-Wave Timer API](04.03.09-z-wave-timer-api.md) +- [4.3.10 Power Control API](04.03.10-power-control-api.md) +- [4.3.11 SPI Interface API](04.03.11-spi-interface-api/index.md) +- [4.3.12 ADC Interface API](04.03.12-adc-interface-api/index.md) +- [4.3.13 UART Interface API](04.03.13-uart-interface-api/index.md) +- [4.3.14 Application HW Timers/PWM Interface API](04.03.14-application-hw-timerspwm-interface-api/index.md) +- [4.3.15 Security API](04.03.15-security-api.md) +- [4.3.16 AES API](04.03.16-aes-api.md) +- [4.3.17 TRIAC Controller API](04.03.17-triac-controller-api.md) +- [4.3.18 LED Controller API](04.03.18-led-controller-api.md) +- [4.3.19 Infrared Controller API](04.03.19-infrared-controller-api/index.md) +- [4.3.20 Keypad Scanner Controller API](04.03.20-keypad-scanner-controller-api.md) +- [4.3.21 USB/UART Common API](04.03.21-usbuart-common-api.md) +- [4.3.22 Flash API](04.03.22-flash-api.md) +- [4.3.23 CRC API](04.03.23-crc-api.md) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.01-zw_addnodetonetwork.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.01-zw_addnodetonetwork.md new file mode 100644 index 0000000..cd2fb07 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.01-zw_addnodetonetwork.md @@ -0,0 +1,182 @@ + +# 4.4.1 ZW_AddNodeToNetwork + +void ZW_AddNodeToNetwork(BYTE bMode, VOID_CALLBACKFUNC(completedFunc)(LEARN_INFO *learnNodeInfo)) + +Macro: ZW_ADD_NODE_TO_NETWORK(bMode, func) Defined in: ZW_controller_api.h + +Serial API: Func_ID = 0x4A HOST->ZW: REQ | 0x4A | mode | funcID ZW->HOST: REQ | 0x4A | funcID | bStatus | bSource | bLen | basic | generic | specific | cmdclasses[ ] + +ZW_AddNodeToNetwork is used to add a node to a Z-Wave network. + +The AddNodeToNetwork function MAY be called by a primary controller application to invoke the inclusion (add) of new nodes in a Z-Wave network. Slave and secondary controller applications MUST NOT call this function. A controller application MUST implement support for the AddNodeToNetwork function. The controller application MUST provide a user interface for activation of the AddNodeToNetwork function. + +The bMode and completedFunc parameters MUST be specified for the AddNodeToNetwork function. + +[Refer to Figure 39 for a state diagram outlining the processing of status callbacks and timeouts.](04.04.01-zw_addnodetonetwork.md#4413-completedfunc-callback-timeouts) + +## 4.4.1.1 bMode parameter + +[The bMode parameter MUST be composed of commands and flags found in Table 15. The bMode](04.04.01-zw_addnodetonetwork.md#4411-bmode-parameter) parameter MUST NOT be assigned more than one command. The bMode parameter MAY be assigned [one or more option flags. One command and multiple options are combined by logically OR’ing the bMode flags of Table 15.](04.04.01-zw_addnodetonetwork.md#4411-bmode-parameter) + +Table 15. AddNode :: bMode + +| bMode flag | Description | Usage | +| --- | --- | --- | +| ADD NODE ANY _ _ | Command to initiate inclusion (add) of new node of any type. | MUST be included when initiating inclusion (add). | +| ADD NODE SLAVE _ _ | - | DEPRECATED. Use ADD NODE ANY _ _ | +| ADD NODE CONTROLLER _ _ | - | DEPRECATED. Use ADD NODE ANY _ _ | +| ADD NODE EXISTING _ _ | - | DEPRECATED. Use ADD NODE ANY _ _ | +| ADD NODE SMART START _ _ _ | Command for entering SMART START Listen mode. | MUST be used for initiating SMART START listen mode. | + +| ADD NODE STOP _ _ | Command to abort the inclusion (add) process. May only be used in certain states. | MAY be used to abort an active inclusion process. MUST be used to terminate the inclusion process when completed. | +| --- | --- | --- | +| ADD NODE STOP FAILED _ _ _ | Command to notify the remote end when a controller replication (copy) is aborted. | SHOULD be used if aborting a controller replication (copy). | +| ADD NODE OPTION _ _ _ NORMAL POWER _ | Option flag to enable normal inclusion range. | SHOULD be included with ADD NODE _ _ ANY to achieve normal inclusion range. MAY be ommitted for ADD NODE ANY _ _ to achieve reduced inclusion range. | +| ADD NODE OPTION _ _ _ NETWORK WIDE _ | Option flag to enable Network- Wide Inclusion (NWI). | MUST be used. | + +Using an illegal value as bMode parameter then ADD_NODE_ANY are used instead. + +4.4.1.1.1 ADD_NODE_ANY command To invoke inclusion (add) of a new node, a primary controller MUST call the AddNodeToNetwork function with a bMode value including the ADD_NODE_ANY command. Slave and secondary controller nodes MUST NOT call the AddNodeToNetwork function. + +The RECOMMENDED call of the AddNodeToNetwork function () when adding nodes is as follows: + +ZW_ADD_NODE_TO_NETWORK((ADD_NODE_ANY | + +ADD_NODE_OPTION_NORMAL_POWER | + +ADD_NODE_OPTION_NETWORK_WIDE), + +completedFunc); + +While defined in Z-Wave protocol libraries, it is NOT RECOMMENDED to use the ADD_NODE_SLAVE, ADD_NODE_CONTROLLER or ADD_NODE_EXISTING command codes. + +4.4.1.1.2 ADD_NODE_SMART_START command To invoke SMART START Listen mode a primary/inclusion controller MUST call the AddNodeToNetwork function with a bMode value including the ADD_NODE_SMART_START command. When a controller in [SMART START Listen mode receives either an INIF (only from foreign HomeID) or a SMART START](../04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.08-applicationcontrollerupdate-only-controller-libraries.md#4318-applicationcontrollerupdate-only-controller-libraries) inclusion request, it will inform the application through ApplicationControllerUpdate [(See 4.3.1.8) about](../04.03-z-wave-common-api/04.03.01-required-application-functions/04.03.01.08-applicationcontrollerupdate-only-controller-libraries.md#4318-applicationcontrollerupdate-only-controller-libraries) the SMART START event. 4.4.1.1.3 ADD_NODE_STOP command A controller MAY use the ADD_NODE_STOP command to abort an ongoing inclusion process. + +After receiving an ADD_NODE_STATUS_DONE status callback, the application MUST terminate the inclusion process by calling the AddNodeToNetwork function one more time. This time, the completedFunc parameter MUST be the NULL pointer. + +Due to the inherent risk of creating ghost nodes with duplicate NodeIDs, a controller SHOULD NOT call the AddNodeToNetwork function in the time window starting with the reception of an ADD_NODE_STATUS_NODE_FOUND status callback and ending with the reception of an ADD_NODE_STATUS_PROTOCOL_DONE status callback. An application may time out waiting for the ADD_NODE_STATUS_PROTOCOL_DONE status callback or the application may receive an ADD_NODE_STATUS_ FAILED status callback. In all three cases, the application MUST terminate the inclusion process by calling AddNodeToNetwork(ADD_NODE_STOP) with a valid completedFunc callback pointer. The API MUST return an ADD_NODE_STATUS_DONE status callback in response. + +After receiving an ADD_NODE_STATUS_DONE status callback, the application MUST terminate the inclusion process by calling the AddNodeToNetwork function one more time. This time, the completedFunc parameter MUST be the NULL pointer. + +4.4.1.1.4 ADD_NODE_STOP_FAILED command When a new controller node is included in a Z-Wave network, the primary controller replicates protocol- specific databases to the new controller. An optional application-specific phase may follow after protocol- specific replication (copy). A primary controller SHOULD use the ADD_NODE_STOP_FAILED command during the application- specific phase to notify the receiving end of the application replication (copy) that the process is being aborted. + +4.4.1.1.5 ADD_NODE_OPTION_NORMAL_POWER option The default power level for Z-Wave communication is the high power level. Therefore, the high power level is frequently referred to as the normal power level. When including a new node, the ADD_NODE_OPTION_NORMAL_POWER option SHOULD be added to the bMode parameter. + +If special application requirements dictate the need for low power transmission during inclusion (add) of a new node, a primary controller MAY omit the ADD_NODE_OPTION_NORMAL_POWER option from the bMode parameter. However, this is NOT RECOMMENDED. + +4.4.1.1.6 ADD_NODE_OPTION_NETWORK_WIDE option Network-Wide Inclusion (NWI) allows a new node to be included across an existing Z-Wave network without direct range connectivity between the primary controller and the new node. The ADD_NODE_OPTION_NETWORK_WIDE option enables NWI. NWI inclusion is backwards compatible with old nodes that do not implement NWI support. + +When including a new node, the ADD_NODE_OPTION_NETWORK_WIDE option MUST be added to the bMode parameter. + +## 4.4.1.2 completedFunc parameter + +Being the exception to the rule, an application calling AddNodeToNetwork(ADD_NODE_STOP) to confirm the reception of a ADD_NODE_STATUS_DONE return code MUST specify the NULL pointer for the completedFunc parameter. + +In all other cases, an application calling the AddNodeToNetwork function with any command and option combination MUST specify a valid pointer to a callback function provided by the application. The callback function MUST accept a pointer parameter to a LEARN_INFO struct. The parameter provides access to actual status as well as companion data presenting a new node. The LEARN_INFO struct only contains a valid pointer to the Node Information Frame of the new node when the status of the callback is ADD_NODE_STATUS_ADDING_SLAVE or ADD_NODE_STATUS_ADDING_CONTROLLER. + +Table 16. AddNode :: completedFunc :: learnNodeInfo + +| LEARN NODE struct member _ | Description | +| --- | --- | +| *learnNodeInfo.bStatus | Callback status code | +| *learnNodeInfo.bSource | NodeID of the new node | +| *learnNodeInfo.bLen | Length of pCmd element following the bLen element. If bLen is zero, there is no valid pCmd element. | +| *learnNodeInfo.pCmd | Pointer to Application Node Information (see ApplicationNodeInformation - nodeParm). NULL if no information present. | + +Individual status codes are presented in the following sections. + +Table 17. AddNode :: completedFunc :: learnNodeInfo.bStatus + +| LEARN NODE.bStatus _ | Description | +| --- | --- | +| ADD NODE STATUS LEARN READY _ _ _ _ | Z-Wave protocol is ready to include new node. | +| ADD NODE STATUS NODE FOUND _ _ _ _ | Z-Wave protocol detected node. | +| ADD NODE STATUS ADDING SLAVE _ _ _ _ | Z-Wave protocol included a slave type node | +| ADD NODE STATUS ADDING CONTROLLER _ _ _ _ | Z-Wave protocol included a controller type node | +| ADD NODE STATUS PROTOCOL DONE _ _ _ _ | Z-Wave protocol completed operations related to inclusion (add). If new node type is controller, the controller application MAY invoke application replication (copy). | +| ADD NODE STATUS DONE _ _ _ | All operations completed. Protocol is ready to return to idle state. | +| ADD NODE STATUS FAILED _ _ _ | Z-Wave protocol reports that inclusion (add) was not successful. New node is not ready for operation | +| ADD NODE STATUS NOT PRIMARY _ _ _ _ | Z-Wave protocol reports that the requested operation cannot be performed since it requires that the node is in primary controller state. | + +[Refer to Figure 39 for a state diagram outlining the processing of status callbacks and timeouts.](04.04.01-zw_addnodetonetwork.md#4413-completedfunc-callback-timeouts) 4.4.1.2.1 ADD_NODE_STATUS_LEARN_READY status Z-Wave protocol is ready to include new node. An application MAY time out waiting for the ADD_NODE_STATUS_LEARN_READY status if it does not receive the indication within 10 sec after calling AddNodeToNetwork(ADD_NODE_ANY) + +If the application times out waiting for the ADD_NODE_STATUS_LEARN_READY status, the application MUST call AddNodeToNetwork(ADD_NODE_STOP, NULL). + +4.4.1.2.2 ADD_NODE_STATUS_NODE_FOUND status Z-Wave protocol detected node. An application MUST time out waiting for the ADD_NODE_STATUS_NODE_FOUND status if it does not receive the indication after calling AddNodeToNetwork(ADD_NODE_ANY). The RECOMMENDED timeout interval is 60 sec. + +If the application times out waiting for the ADD_NODE_STATUS_NODE_FOUND status, the application MUST call AddNodeToNetwork(ADD_NODE_STOP, NULL). + +The application MUST NOT call AddNodeToNetwork() before the timeout occurs. This may cause the protocol to malfunction. + +4.4.1.2.3 ADD_NODE_STATUS_ADDING_SLAVE status Z-Wave protocol included a slave type node. + +An application MUST time out waiting for the ADD_NODE_STATUS_ADDING_SLAVE status if it does not receive the indication within a time period after receiving the ADD_NODE_STATUS_NODE_FOUND status. The RECOMMENDED timeout interval is 60 sec. + +If the application times out waiting for the ADD_NODE_STATUS_ADDING_SLAVE status, the application MUST call AddNodeToNetwork(ADD_NODE_STOP). The application MUST specify a valid callback function. This allows the application to receive a ADD_NODE_STATUS_DONE once the protocol has completed cleaning up its datastructures. + +The application MUST NOT call AddNodeToNetwork() before the timeout occurs. This may cause the protocol to malfunction. + +4.4.1.2.4 ADD_NODE_STATUS_ADDING_CONTROLLER status Z-Wave protocol included a controller type node. + +An application MUST time out waiting for the ADD_NODE_STATUS_ADDING_CONTROLLER status if it does not receive the indication within a time period after receiving the ADD_NODE_STATUS_NODE_FOUND status. The RECOMMENDED timeout interval is 60 sec. + +If the application times out waiting for the ADD_NODE_STATUS_ADDING_CONTROLLER status, the application MUST call AddNodeToNetwork(ADD_NODE_STOP). The application MUST specify a valid callback function. This allows the application to receive an ADD_NODE_STATUS_DONE once the protocol has completed cleaning up its datastructures. + +The application MUST NOT call AddNodeToNetwork() before the timeout occurs. This may cause the protocol to malfunction. 4.4.1.2.5 ADD_NODE_STATUS_PROTOCOL_DONE status Z Wave protocol completed operations related to inclusion (add). If new node type is controller, the controller application MAY invoke application replication (copy). + +In response to the ADD_NODE_STATUS_PROTOCOL_DONE , the application MUST call AddNodeToNetwork(ADD_NODE_STOP). The application MUST specify a valid callback function. This allows the application to receive an ADD_NODE_STATUS_DONE once the protocol has completed cleaning up its datastructures. + +An application MUST time out waiting for the ADD_NODE_STATUS_PROTOCOL_DONE status if it does not receive the indication within a time period after receiving the [ADD_NODE_STATUS_NODE_FOUND status. The time period depends on the network size and the node types in the network. Refer to 4.4.1.3.3.](04.04.01-zw_addnodetonetwork.md#4413-completedfunc-callback-timeouts) + +If the application times out waiting for the ADD_NODE_STATUS_PROTOCOL_DONE status, the application MUST call AddNodeToNetwork(ADD_NODE_STOP). The application MUST specify a valid callback function. This allows the application to receive a ADD_NODE_STATUS_DONE once the protocol has completed cleaning up its datastructures. + +The application MUST NOT call AddNodeToNetwork() before the timeout occurs. This may cause the protocol to malfunction. + +4.4.1.2.6 ADD_NODE_STATUS_DONE status All operations completed. Protocol is ready to return to idle state. + +In response to the ADD_NODE_STATUS_DONE status callback, the application MUST call AddNodeToNetwork(ADD_NODE_STOP, NULL). The application MUST specify the NULL pointer for the callback function. + +4.4.1.2.7 ADD_NODE_STATUS_FAILED status An application may time out waiting for the ADD_NODE_STATUS_PROTOCOL_DONE status callback or the application may receive an ADD_NODE_STATUS_PROTOCOL_FAILED status callback. In either [case, the application MUST terminate the inclusion process by calling AddNodeToNetwork(ADD_NODE_STOP). Refer to 4.4.1.1.3.](04.04.01-zw_addnodetonetwork.md#4411-bmode-parameter) + +4.4.1.2.8 ADD_NODE_STATUS_NOT_PRIMARY status An application MUST NOT call the AddNodeToNetwork function if the application is not running in a primary controller. If the function is called by an application running in slave or a secondary controller, the API MUST return the ADD_NODE_STATUS_NOT_PRIMARY status callback. + +## 4.4.1.3 completedFunc callback timeouts + +4.4.1.3.1 ProtocolReadyTimeout The API MUST return an ADD_NODE_STATUS_LEARN_READY status callback within less than 10 sec after receiving a call to AddNodeToNetwork(ADD_NODE_ANY). + +If an application has not received an ADD_NODE_STATUS_LEARN_READY status callback 200 msec after calling AddNodeToNetwork(ADD_NODE_ANY), the application MAY time out and return to its idle state. 4.4.1.3.2 NodeTimeout An application MUST implement a timeout for waiting for an ADD_NODE_STATUS_NODE_FOUND status callback. + +The application SHOULD NOT wait for an ADD_NODE_STATUS_NODE_FOUND status callback for more than 60 sec after calling AddNodeToNetwork(ADD_NODE_ANY). If timing out, the application SHOULD abort inclusion (add). + +4.4.1.3.3 AddNodeTimeout [An application MUST implement a timeout for waiting for the protocol library to complete inclusion (add). The timeout MUST be calculated according to the formulas presented in sections 4.4.1.3.3.1 and 4.4.1.3.3.2.](04.04.01-zw_addnodetonetwork.md#4413-completedfunc-callback-timeouts) + +4.4.1.3.3.1 New slave AddNodeTimeout.NewSlave = 76000ms + LISTENINGNODES*217ms + FLIRSNODES*3517ms + +where LISTENINGNODES is the number of listening nodes in the network, and FLIRSNODES is the number of nodes in the network that are reached via beaming. + +4.4.1.3.3.2 New controller AddNodeTimeout.NewController = 76000ms + LISTENINGNODES*217ms + FLIRSNODES*3517ms + NETWORKNODES*732ms, + +where LISTENINGNODES is the number of listening nodes in the network, and FLIRSNODES is the number of nodes in the network that are reached via beaming. + +NETWORKNODES is the total number of nodes in the network, i.e., NONLISTENINGNODES + LISTENINGNODES + FLIRSNODES. + +![Figure 39. Adding a Node to the Network](assets/img-cd5225ad49.png) + +Table 18. AddNode : State/Event processing – 1 + +![figure p357](assets/img-7770287b4b.png) + +Table 19. AddNode : State/Event processing – 2 + +![figure p358](assets/img-daa8fe3846.png) + +Table 20. AddNode : State/Event processing – 3 + +![figure p359](assets/img-bc2ffcbf33.png) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.02-zw_addnodedsktonetwork.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.02-zw_addnodedsktonetwork.md new file mode 100644 index 0000000..cf37bd0 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.02-zw_addnodedsktonetwork.md @@ -0,0 +1,52 @@ + +# 4.4.2 ZW_AddNodeDskToNetwork + +void ZW_AddNodeDskToNetwork(BYTE bMode, BYTE *pDSK, VOID_CALLBACKFUNC(completedFunc)(LEARN_INFO *learnNodeInfo)) + +Macro: ZW_ADD_NODE_DSK_TO_NETWORK(bMode, pDsk, func) Defined in: ZW_controller_api.h + +ZW_AddNodeDskToNetwork MAY be used to add a specific SMART START node to a Z-Wave network. + +The AddNodeDskToNetwork function MAY be called by a primary controller application to invoke the inclusion (add) of new nodes in a Z-Wave network. Slave and secondary controller applications MUST NOT call this function. A controller application MUST implement support for the ZW_AddNodeDskToNetwork function. The controller application MUST provide a user interface for activation of the ZW_AddNodeDskToNetwork function. + +The bMode and completedFunc parameters MUST be specified for the ZW_AddNodeDskToNetwork function. + +[Refer to Figure 39 for a state diagram outlining the processing of status callbacks and timeouts.](04.04.01-zw_addnodetonetwork.md#4413-completedfunc-callback-timeouts) + +## 4.4.2.1 bMode parameter + +[The bMode parameter MUST be composed of commands and flags found in Table 15 and Table 21. The](04.04.01-zw_addnodetonetwork.md#4411-bmode-parameter) bMode parameter MUST NOT be assigned more than one command. The bMode parameter MAY be [assigned one or more option flags. One command and multiple options are combined by logically OR’ing the bMode flags of Table 15 (See also 4.4.1.1).](04.04.01-zw_addnodetonetwork.md#4411-bmode-parameter) + +Table 21. AddNodeDsk :: bMode + +| bMode flag | Description | Usage | +| --- | --- | --- | +| ADD NODE HOME ID _ _ _ | Command for initiating the SMART START inclusion of a specific SMART START node. | MUST be used for initiating inclusion of specific SMART START. | + +4.4.2.1.1 ADD_NODE_HOME_ID command To invoke the inclusion of a specific SMART START node a primary/inclusion controller MUST call the ZW_AddNodeDskToNetwork function with a bMode value including the ADD_NODE_HOME_ID command and specify the SMART START DSK identifying the specific SMART START node to include. + +## 4.4.2.2 pDSK parameter + +If bMode == ADD_NODE_HOME_ID then the pDSK parameter MUST point to the matching DSK part of the SMART START node which should be included. Only the bMode == ADD_NODE_HOME_ID mode uses the pDSK parameter. + +## 4.4.2.3 completedFunc parameter + +See description of ZW_AddNodeToNetwork [(4.4.1) specifically 4.4.1.2 and 4.4.1.3.](04.04.01-zw_addnodetonetwork.md#441-zw_addnodetonetwork) + +## 4.4.2.4 Smart Start Network Wide Inclusion + +![Figure 40. Smart Start S2 Public Key Derived Inclusion homeIDs](assets/img-5faa92ce3d.png) + +Serial API: + +No Func_ID defined for ZW_AddNodeDskToNetwork but the Serial API uses the ZW_AddNodeToNetwork Func_ID = 0x4A to access the ZW_AddNodeDskToNetwork specific bMode == ADD_NODE_HOME_ID (0x08) command. + +HOST->ZW: REQ | 0x4A | 0x08 | funcID | pDsk[0] | pDsk[1] | pDsk[2] | pDsk[3] | pDsk[4] | pDsk[5] | pDsk[6] | pDsk[7] + +ZW->HOST: REQ | 0x4A | funcID | bStatus | bSource | bLen | basic | generic | specific | cmdclasses[ ] diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.03-zw_arenodesneighbours.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.03-zw_arenodesneighbours.md new file mode 100644 index 0000000..8b96b6a --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.03-zw_arenodesneighbours.md @@ -0,0 +1,34 @@ + +# 4.4.3 ZW_AreNodesNeighbours + +BYTE ZW_AreNodesNeighbours(BYTE bNodeA, BYTE bNodeB) + +Macro: ZW_ARE_NODES_NEIGHBOURS (nodeA, nodeB) + +Used to check if two nodes are marked as being within direct range of each other + +Defined in: ZW_controller_api.h + +Return value: + +BYTE FALSE Nodes are not neighbours. + +TRUE Nodes are neighbours. + +Parameters: + +bNodeA IN Node ID A (1...232) + +bNodeB IN Node ID B (1...232) + +Serial API + +HOST->ZW: REQ | 0xBC | nodeID | nodeID + +ZW->HOST: RES | 0xBC | retVal diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.04-zw_assignreturnroute.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.04-zw_assignreturnroute.md new file mode 100644 index 0000000..5b67369 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.04-zw_assignreturnroute.md @@ -0,0 +1,46 @@ + +# 4.4.4 ZW_AssignReturnRoute + +BOOL ZW_AssignReturnRoute(BYTE bSrcNodeID, BYTE bDstNodeID, VOID_CALLBACKFUNC(completedFunc) (BYTE txStatus, TX_STATUS_TYPE* txStatusReport)) + +Macro: ZW_ASSIGN_RETURN_ROUTE(routingNodeID,destNodeID,func) + +Use to assign static return routes (up to 4) to a Routing Slave or Enhanced 232 Slave node. This allows the Routing Slave node to communicate directly with either controllers or other slave nodes. The API call calculates the shortest routes from the Routing Slave node (bSrcNodeID) to the destination node (bDestNodeID) and transmits the return routes to the Routing Slave node (bSrcNodeID). The destination node is part of the return routes assigned to the slave. Up to 5 different destinations can be allocated return routes in a Routing Slave. Attempts to assign new return routes when all 5 destinations already are allocated will be ignored. It is possible to allocate up to 232 different destinations in an Enhanced 232 Slave. Call ZW_AssignReturnRoute repeatedly to allocate more than 5 destinations in an Enhanced 232 Slave. Use the API call ZW_DeleteReturnRoute to clear assigned return routes. + +Defined in: ZW_controller_api.h + +Return value: + +BOOL TRUE If Assign return route operation started + +FALSE If an “assign/delete return route” operation already is active. + +Parameters: + +bSrcNodeID IN Node ID (1...232) of the routing slave that should get the return routes. + +bDstNodeID IN Destination node ID (1...232) + +completedFunc IN Transmit completed call back function + +Callback function Parameters: + +txStatus IN Status of return route assignment + +(all status codes from ZW_SendData) See ZW_SendData [, section 4.3.3.1](../04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.01-zw_senddata.md#4331-zw_senddata) + +TRANSMIT_COMPLETE_NOROUTE No routes assigned because a route between source and destination node could not be found. + +txStatusReport IN (see ZW_SendData) + +Serial API: + +HOST->ZW: REQ | 0x46 | bSrcNodeID | bDstNodeID | funcID ZW->HOST: RES | 0x46 | retVal + +ZW->HOST: REQ | 0x46 | funcID | bStatus diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.05-zw_assignsucreturnroute.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.05-zw_assignsucreturnroute.md new file mode 100644 index 0000000..3ac5211 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.05-zw_assignsucreturnroute.md @@ -0,0 +1,44 @@ + +# 4.4.5 ZW_AssignSUCReturnRoute + +BOOL ZW_AssignSUCReturnRoute(BYTE bSrcNodeID, VOID_CALLBACKFUNC(completedFunc) (BYTE txStatus, TX_STATUS_TYPE* txStatusReport)) + +Macro: ZW_ASSIGN_SUC_RETURN_ROUTE(srcnode,func) + +Notify presence of a SUC/SIS to a Routing Slave or Enhanced 232 Slave. Furthermore is static return routes (up to 4) assigned to the Routing Slave or Enhanced 232 Slave to enable communication with the SUC/SIS node. The return routes can be used to get updated return routes from the SUC/SIS node by calling ZW_RequestNetWorkUpdated in the Routing Slave or Enhanced 232 Slave. + +Defined in: ZW_controller_api.h + +Return value: + +BOOL TRUE If the assign SUC return route operation is started. + +FALSE If an “assign/delete return route” operation already is active. + +Parameters: + +bSrcNodeID IN The node ID (1...232) of the routing slave that should get the return route to the SUC/SIS node. + +completedFunc Transmit complete call back. IN + +Callback function Parameters: + +bStatus IN (see ZW_SendData) + +txStatusReport (see ZW_SendData) IN + +Serial API: + +HOST->ZW: REQ | 0x51 | bSrcNodeID | funcID | funcID + +The extra funcID is added to ensures backward compatible. This parameter has been removed starting from dev. kit 4.1x. and onwards and has therefore no meaning anymore. + +ZW->HOST: RES | 0x51 | retVal + +ZW->HOST: REQ | 0x51 | funcID | bStatus diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.06-zw_assignpriorityreturnroute.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.06-zw_assignpriorityreturnroute.md new file mode 100644 index 0000000..d185cc8 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.06-zw_assignpriorityreturnroute.md @@ -0,0 +1,52 @@ + +# 4.4.6 ZW_AssignPriorityReturnRoute + +BOOL ZW_AssignPriorityReturnRoute(BYTE bSrcNodeID, BYTE bDstNodeID, XBYTE *pPriorityRoute, VOID_CALLBACKFUNC(completedFunc) (BYTE txStatus, TX_STATUS_TYPE* txStatusReport)) + +Assign a application defined Priority Return Route to a routing or an enhanced slave that always will be tried as the first return route attempt. The function will assign the specified Priority Return Route and if possible it will also assign up to three return routes calculated from the routing table in the same manner as ZW_AssignReturnRoute. + +Use the API call ZW_DeleteReturnRoute to clear the assigned Priority Return Route together with the other Return Routes. + +NOTE: If the routing/enhanced slave is based on a SDK prior to 6.60 it can not be guarantied that the first Return Route is the specified Priority Return Route. The Priority Return Route will be used but its placement in the Return Route sequence is based on internal prioritization in the slave. + +Defined in: ZW_controller_api.h + +Return value: + +BOOL TRUE If Assign return route operation started + +FALSE If an “assign/delete return route” operation already is active. + +Parameters: + +bSrcNodeID IN Node ID (1...232) of the routing slave that should get the return routes. + +bDstNodeID IN Destination node ID (1...232) + +pPriorityRoute Pointer for a 5-byte array containing the new Priority Return Route to be set. The 5-byte array contains 4 repeater node bytes (index 0 - 3) and 1 routespeed byte (index 4). The first repeater byte (starting from index 0) equaling zero indicates no more repeaters in route. If the repeater at index 0 is zero then the Priority Return Route is direct. The routespeed byte (index 4) can be either ZW_PRIORITY_ROUTE_SPEED_9600, ZW_PRIORITY_ROUTE_SPEED_40K or ZW_PRIORITY_ROUTE_SPEED_100K + +completedFunc Transmit completed call back function IN + +Callback function Parameters: + +txStatus IN Status of return route assignment + +(all status codes from ZW_SendData) See ZW_SendData [, section 4.3.3.1](../04.03-z-wave-common-api/04.03.03-z-wave-transport-api/04.03.03.01-zw_senddata.md#4331-zw_senddata) + +TRANSMIT_COMPLETE_NOROUTE No routes assigned because a route between source and destination node could not be found. + +txStatusReport IN (see ZW_SendData) + +Serial API: + +HOST->ZW: REQ | 0x4F | bSrcNodeID | bDstNodeID | PriorityRoute | funcID + +ZW->HOST: RES | 0x4F | retVal + +ZW->HOST: REQ | 0x4F | funcID | bStatus diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.07-zw_assignprioritysucreturnroute.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.07-zw_assignprioritysucreturnroute.md new file mode 100644 index 0000000..3f0fd3a --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.07-zw_assignprioritysucreturnroute.md @@ -0,0 +1,44 @@ + +# 4.4.7 ZW_AssignPrioritySUCReturnRoute + +BOOL ZW_AssignPriorityReturnRoute(BYTE bSrcNodeID, XBYTE *pPriorityRoute, VOID_CALLBACKFUNC(completedFunc) (BYTE txStatus, TX_STATUS_TYPE* txStatusReport)) + +Assign a application defined Priority SUC Return Route to a routing or an enhanced slave that always will be tried as the first return route attempt. The function will assign the specified Priority SUC Return Route and if possible it will also assign up to three return routes calculated from the routing table in the same manner as ZW_AssignSUCReturnRoute. + +Use the API call ZW_DeleteSUCReturnRoute to clear the assigned Priority SUC Return Route together with the other Return Routes. + +NOTE: If the routing/enhanced slave is based on a SDK prior to 6.60 it can not be guarantied that the first return route is the specified priority route. The priority route will be used but its placement in the return route sequence is based on internal prioritization in the slave. + +Defined in: ZW_controller_api.h + +Return value: + +BOOL TRUE If the assign Priority SUC return route operation is started. + +FALSE If an “assign/delete return route” operation already is active. + +Parameters: + +bSrcNodeID IN The node ID (1...232) of the routing slave that should get the Priority Return Route to the SUC/SIS node. + +pPriorityRoute Pointer for a 5-byte array containing the new Priority Return Route to be set. The 5-byte array contains 4 repeater node bytes (index 0 - 3) and 1 routespeed byte (index 4). The first repeater byte (starting from index 0) equaling zero indicates no more repeaters in route. If the repeater at index 0 is zero then the Priority Return Route is direct. The routespeed byte (index 4) can be either ZW_PRIORITY_ROUTE_SPEED_9600, ZW_PRIORITY_ROUTE_SPEED_40K or ZW_PRIORITY_ROUTE_SPEED_100K + +completedFunc Transmit complete call back. IN + +Callback function Parameters: bStatus IN (see ZW_SendData) + +txStatusReport (see ZW_SendData) IN + +Serial API: + +HOST->ZW: REQ | 0x58 | bSrcNodeID | PriorityRoute | funcID + +ZW->HOST: RES | 0x58 | retVal + +ZW->HOST: REQ | 0x58 | funcID | bStatus diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.08-zw_controllerchange.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.08-zw_controllerchange.md new file mode 100644 index 0000000..ab44070 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.08-zw_controllerchange.md @@ -0,0 +1,56 @@ + +# 4.4.8 ZW_ControllerChange + +void ZW_ControllerChange (BYTE mode, VOID_CALLBACKFUNC(completedFunc)(LEARN_INFO *learnNodeInfo)) + +Macro: ZW_CONTROLLER_CHANGE(mode, func) + +ZW_ControllerChange is used to add a controller to the Z-Wave network and transfer the role as primary controller to it. + +This function has the same functionality as ZW_AddNodeToNetwork(ADD_NODE_ANY,…) except that the new controller will be a primary controller and the controller invoking the function will become secondary. + +Defined in: ZW_controller_api.h + +Parameters: + +mode IN The learn node states are: + +CONTROLLER_CHANGE_START Start the process of adding a controller to the network. + +CONTROLLER_CHANGE_STOP Stop the controller change + +CONTROLLER_CHANGE_STOP_FAILED Stop the controller change and report a failure + +completedFunc IN Callback function pointer (Should only be NULL if state is turned off). Callback function Parameters (completedFunc): + +*learnNodeInfo.bStatus Status of learn mode: IN ADD_NODE_STATUS_LEARN_READY The controller is now ready to include a node into the network. + +ADD_NODE_STATUS_NODE_FOUND A node that wants to be included into the network has been found + +ADD_NODE_STATUS_ADDING_CONTROLLER A new controller has been added to the network + +ADD_NODE_STATUS_PROTOCOL_DONE The protocol part of adding a controller is complete, the application can now send data to the new controller using ZW_ReplicationSend() + +ADD_NODE_STATUS_DONE The new node has now been included and the controller is ready to continue normal operation again. + +ADD_NODE_STATUS_FAILED The learn process failed + +*learnNodeInfo.bSource Node id of the new node IN + +*learnNodeInfo.pCmd Pointer to Application Node information data (see IN ApplicationNodeInformation - nodeParm). NULL if no information present. + +The pCmd only contain information when bLen is not zero, so the information should be stored when that is the case. Regardless of the bStatus. + +*learnNodeInfo.bLen IN Node info length. + +Serial API: + +HOST->ZW: REQ | 0x4D | mode | funcID + +ZW->HOST: REQ | 0x4D | funcID | bStatus | bSource | bLen | basic | generic | specific | cmdclasses[ ] diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.09-zw_deletereturnroute.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.09-zw_deletereturnroute.md new file mode 100644 index 0000000..d0e6840 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.09-zw_deletereturnroute.md @@ -0,0 +1,42 @@ + +# 4.4.9 ZW_DeleteReturnRoute + +BOOL ZW_DeleteReturnRoute(BYTE nodeID, VOID_CALLBACKFUNC(completedFunc) (BYTE txStatus, TX_STATUS_TYPE* txStatusReport)) + +Macro: ZW_DELETE_RETURN_ROUTE(nodeID, func) + +Delete all static return routes from a Routing Slave or Enhanced 232 Slave node. + +Defined in: ZW_controller_api.h + +Return value: + +BOOL TRUE If Delete return route operation started + +FALSE If an “assign/delete return route” operation already is active. + +Parameters: + +nodeID IN Node ID (1...232) of the routing slave node. + +completedFunc Transmit completed call back function IN + +Callback function Parameters: + +txStatus IN (see ZW_SendData) + +txStatusReport (see ZW_SendData) IN + +Serial API: + +HOST->ZW: REQ | 0x47 | nodeID | funcID + +ZW->HOST: RES | 0x47 | retVal + +ZW->HOST: REQ | 0x47 | funcID | bStatus diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.10-zw_deletesucreturnroute.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.10-zw_deletesucreturnroute.md new file mode 100644 index 0000000..3850d2e --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.10-zw_deletesucreturnroute.md @@ -0,0 +1,42 @@ + +# 4.4.10 ZW_DeleteSUCReturnRoute + +BOOL ZW_DeleteSUCReturnRoute(BYTE bNodeID, VOID_CALLBACKFUNC (completedFunc) (BYTE txStatus, TX_STATUS_TYPE* txStatusReport)) + +Macro: ZW_DELETE_SUC_RETURN_ROUTE (nodeID, func) + +Delete the return routes of the SUC/SIS node from a Routing Slave node or Enhanced 232 Slave node. + +Defined in: ZW_controller_api.h + +Return value: + +BOOL TRUE If the delete SUC return route operation is started. + +FALSE If an “assign/delete return route” operation already is active. + +Parameters: + +bNodeID IN Node ID (1..232) of the routing slave node. + +completedFunc Transmit complete call back. IN + +Callback function Parameters: + +txStatus IN (see ZW_SendData) + +txStatusReport (see ZW_SendData) IN + +Serial API: + +HOST->ZW: REQ | 0x55 | nodeID | funcID + +ZW->HOST: RES | 0x55 | retVal + +ZW->HOST: REQ | 0x55 | funcID | bStatus diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.11-zw_getcontrollercapabilities.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.11-zw_getcontrollercapabilities.md new file mode 100644 index 0000000..7640966 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.11-zw_getcontrollercapabilities.md @@ -0,0 +1,36 @@ + +# 4.4.11 ZW_GetControllerCapabilities + +BYTE ZW_GetControllerCapabilities(void) + +Macro: ZW_GET_CONTROLLER_CAPABILITIES() + +ZW_GetControllerCapabilities returns a bitmask containing the capabilities of the controller. It’s an old type of primary controller (node ID = 0xEF) in case zero is returned. + +NOTE: Not all status bits are available on all controllers’ types + +Defined in: ZW_controller_api.h + +Return value: + +BYTE CONTROLLER_IS_SECONDARY If bit is set then the controller is a secondary controller + +CONTROLLER_ON_OTHER_NETWORK If this bit is set then this controller is not using its built-in home ID + +CONTROLLER_IS_SUC If this bit is set then this controller is a SUC + +CONTROLLER_NODEID_SERVER_PRESENT If this bit is set then there is a SUC ID server (SIS) in the network and this controller can therefore include/exclude nodes in the network. This is called an inclusion controller. + +CONTROLLER_IS_REAL_PRIMARY If this bit is set then this controller was the original primary controller in the network before the SIS was added to the network + +Serial API: + +HOST->ZW: REQ | 0x05 + +ZW->HOST: RES | 0x05 | RetVal diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.12-zw_getneighborcount.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.12-zw_getneighborcount.md new file mode 100644 index 0000000..08ccb26 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.12-zw_getneighborcount.md @@ -0,0 +1,34 @@ + +# 4.4.12 ZW_GetNeighborCount + +BYTE ZW_GetNeighborCount(BYTE nodeID) + +Macro: ZW_GET_NEIGHBOR_COUNT (nodeID) + +Used to get the number of neighbors the specified node has registered. + +Defined in: ZW_controller_api.h + +Return value: + +BYTE 0x00-0xE7 Number of neighbors registered. + +NEIGHBORS_ID_INVALID Specified node ID is invalid. + +NEIGHBORS_COUNT_FAILED Could not access routing information - try again later. + +Parameters: + +nodeID IN Node ID (1...232) on the node to count neighbors on. + +Serial API + +HOST->ZW: REQ | 0xBB | nodeID + +ZW->HOST: RES | 0xBB | retVal diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.13-zw_getpriorityroute.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.13-zw_getpriorityroute.md new file mode 100644 index 0000000..12ed90e --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.13-zw_getpriorityroute.md @@ -0,0 +1,40 @@ + +# 4.4.13 ZW_GetPriorityRoute + +BYTE ZW_GetPriorityRoute (BYTE bNodeID, XBYTE *pPriorityRoute) + +Macro: ZW_GET_PRIORITY_ROUTE(bNodeID, pPriorityRoute) + +Use this API call to get the route with the highest priority. If a route has been set with the ZW_SetPriorityRoute then that route will be returned. If no priority route has been set the call will return the either the Last Working Route (LWR) or the Next to Last Working Route (NLWR). The LWR is the last successful route used between sender and destination node and the NLWR is the previous LWR. The PriorityRoute, LWR and NLWR are all stored in NVM. + +Note: ZW_GetPriorityRoute superceeds the ZW_GetLastWorkingRoute functionality, which is obsoleted. + +Defined in: ZW_controller_api.h + +Return value: + +BYTE ZW_PRIORITY_ROUTE_APP_PR App defined Priority Route. + +ZW_PRIORITY_ROUTE_ZW_LWR Last Working Route + +ZW_PRIORITY_ROUTE_ZW_NLWR Next to Last Working Route + +FALSE No Priority Route found for bNodeID. + +Parameters: + +bNodeID IN The Node ID (1...232) specifies the destination node whom the Priority Route is wanted from. + +pPriorityRoute Pointer to a 5-byte array where the IN wanted Priority Route will be copied. The 5-byte array contains in the first 4 byte the max 4 repeaters (index 0 - 3) and 1 routespeed byte (index 4) used in the Route. The Route which pPriorityRoute points to is valid if function return value is NON ZERO. The first repeater byte (starting from index 0) equaling zero indicates no more repeaters in route. If the repeater at index 0 is zero then the Route is direct. The routespeed byte (index 4) can be either ZW_PRIORITY_ROUTE_SPEED_9600, ZW_PRIORITY_ROUTE_SPEED_40K or ZW_PRIORITY_ROUTE_SPEED_100K + +Serial API + +HOST->ZW: REQ | 0x92 | bNodeID + +ZW->HOST: RES | 0x92 | bNodeID | retVal | repeater0 | repeater1 | repeater2 | repeater3 | routespeed diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.14-zw_setpriorityroute.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.14-zw_setpriorityroute.md new file mode 100644 index 0000000..351b654 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.14-zw_setpriorityroute.md @@ -0,0 +1,36 @@ + +# 4.4.14 ZW_SetPriorityRoute + +BOOL ZW_SetPriorityRoute(BYTE bNodeID, XBYTE *pPriorityRoute) + +Macro: ZW_SET_PRIORITY_ROUTE(bNodeID, pPriorityRoute) + +Use this API call to set the Priority Routefor a destination node. The Priority Route is the route that will be used as the first routing attempt by the protocol when transmitting to a node. The Priority Route is stored in NVM. + +Note: ZW_SetPriorityRoute superceeds the ZW_SetLastWorkingRoute functionality, which is obsoleted. + +Defined in: ZW_controller_api.h + +Return value: + +BOOL TRUE The Priority Route for bNodeID was successfully set to the specified 5- byte Priority Route pointed out by pPriorityRoute. + +FALSE The specified bNodeID was not valid and no Priority Route was set. + +Parameters: + +bNodeID IN The Node ID (1...232) - specifies the destination node for whom the Priority Route is to be set. + +pPriorityRoute Pointer for a 5-byte array containing the new IN Priority Route to be set. If NULL then current APR is released (protocol now has 2 entries for LWRs). The 5-byte array contains 4 repeater node bytes (index 0 - 3) and 1 routespeed byte (index 4). The first repeater byte (starting from index 0) equaling zero indicates no more repeaters in route. If the repeater at index 0 is zero then the Priority Route is direct. The routespeed byte (index 4) can be either ZW_PRIORITY_ROUTE_SPEED_9600, ZW_PRIORITY_ROUTE_SPEED_40K or ZW_PRIORITY_ROUTE_SPEED_100K + +Serial API + +HOST->ZW: REQ | 0x93 | bNodeID | repeater0 | repeater1 | repeater2 | repeater3 | routespeed + +ZW->HOST: RES | 0x93 | bNodeID | retVal diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.15-zw_getnodeprotocolinfo.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.15-zw_getnodeprotocolinfo.md new file mode 100644 index 0000000..128fa88 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.15-zw_getnodeprotocolinfo.md @@ -0,0 +1,41 @@ + +# 4.4.15 ZW_GetNodeProtocolInfo + +void ZW_GetNodeProtocolInfo(BYTE bNodeID, NODEINFO *nodeInfo) + +Macro: ZW_GET_NODE_STATE(nodeID, nodeInfo) + +Return the Node Information Frame without command classes from the NVM for a given node ID: + +| Byte descriptor \ Bit number | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Capability | Liste- ning | Z-Wave Protocol-Specific Part | | | | | | | +| Security | Opt. Func. | Sensor 1000ms | Sensor 250ms | Z-Wave Protocol-Specific Part | | | | | +| Reserved | Z-Wave Protocol-Specific Part | | | | | | | | +| Basic | Basic Device Class (Z-Wave Protocol-Specific Part) | | | | | | | | +| Generic | Generic Device Class (Z-Wave Appl.-Specific Part) | | | | | | | | +| Specific | Specific Device Class (Z-Wave Appl.-Specific Part) | | | | | | | | + +Figure 41. Node Information Frame Structure without Command Classes + +All the Z-Wave protocol-specific fields are initialized by the protocol. The Listening flag, Generic, and Specific Device Class fields are initialized by the application. Regarding initialization, refer to the function ApplicationNodeInformation. + +Defined in: ZW_controller_api.h + +Parameters: + +bNodeID IN Node ID 1..232 + +nodeInfo OUT Node info buffer (see figure above) If (*nodeInfo).nodeType.generic is 0 then the node doesn’t exist. + +Serial API: + +HOST->ZW: REQ | 0x41 | bNodeID + +ZW->HOST: RES | 0x41 | nodeInfo (see figure above) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.16-zw_getroutinginfo.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.16-zw_getroutinginfo.md new file mode 100644 index 0000000..bae8131 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.16-zw_getroutinginfo.md @@ -0,0 +1,43 @@ + +# 4.4.16 ZW_GetRoutingInfo + +void ZW_GetRoutingInfo(BYTE bNodeID, BYTE_P pMask, BYTE bOptions) Macro: ZW_GET_ROUTING_INFO(bNodeID, pMask, bOptions) + +ZW_GetRoutingInfo is a function that can be used to read out neighbor information from the protocol. + +This information can be used to ensure that all nodes have a sufficient number of neighbors and to ensure that the network is in fact one network. + +The format of the data returned in the buffer pointed to by pMask is as follows: + +| pMask[i] (0  i < (ZW MAX NODES/8) _ _ | | | | | | | | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Bit | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | +| NodeID | i*8+1 | i*8+2 | i*8+3 | i*8+4 | i*8+5 | i*8+6 | i*8+7 | i*8+8 | + +If a bit n in pMask[i] is 1 it indicates that the node bNodeID has node (i*8)+n+1 as a neighbour. If n in pMask[i] is 0, bNodeID cannot reach node (i*8)+n+1 directly. + +Defined in: ZW_controller_api.h + +Parameters: + +bNodeID IN Node ID (1…232) specifies the node whom routing info is needed from. + +pMask OUT Pointer to buffer where routing info should be put. The buffer should be at least ZW_MAX_NODES/8 bytes + +bOptions IN Upper nibble (upper 4-bit in byte) is bit flag options, lower nibble is speed. Combine exactly one speed with any number of options. Bit flags options for upper nibble: GET_ROUTING_INFO_REMOVE_NON_REPS Remove non-repeaters from the (bRemoveNonReps) routing info. Remove bad link from routing info Bad links are a short list of nodes GET_ROUTING_INFO_REMOVE_BAD which recently has failed to (bRemoveBad) answer a transmission + +Speed values for lower nibble: ZW_GET_ROUTING_INFO_9600 or Return only nodes supporting this ZW_GET_ROUTING_INFO_40K or speed. ZW_GET_ROUTING_INFO_100K or Only one speed value may be ZW_GET_ROUTING_INFO_ANY used at a time. Serial API: + +HOST->ZW: REQ | 0x80 | bNodeID | bRemoveBad | bRemoveNonReps | funcID + +ZW->HOST: RES | 0x80 | NodeMask[29] + +NOTE: funcID must be set to 0. + +NOTE: Serial API func FUNC_ID_GET_ROUTING_TABLE_LINE (0x80) is the Serial API command ID for ZW_GetRoutingInfo and the current implementation do not support for specifying Speed value. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.17-zw_getsucnodeid.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.17-zw_getsucnodeid.md new file mode 100644 index 0000000..30d821c --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.17-zw_getsucnodeid.md @@ -0,0 +1,26 @@ + +# 4.4.17 ZW_GetSUCNodeID + +BYTE ZW_GetSUCNodeID(void) + +Macro: ZW_GET_SUC_NODEID() + +API call used to get the currently registered SUC/SIS node ID. + +Defined in: ZW_controller_api.h + +Return value: + +BYTE The node ID (1..232) on the currently registered SUC/SIS, if ZERO then no SUC/SIS available. + +Serial API: + +HOST->ZW: REQ | 0x56 + +ZW->HOST: RES | 0x56 | SUCNodeID diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.18-zw_isfailednode.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.18-zw_isfailednode.md new file mode 100644 index 0000000..6dea0aa --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.18-zw_isfailednode.md @@ -0,0 +1,32 @@ + +# 4.4.18 ZW_IsFailedNode + +BYTE ZW_isFailedNode(BYTE nodeID) + +Macro: ZW_IS_FAILED_NODE_ID(nodeID) + +Used to test if a node ID is stored in the failed node ID list. + +The failed node list is limited to 5 entries.If a node is added to a full list the node with the lowest failed count will be replaced with the new node ID. + +Defined in: ZW_controller_api.h + +Return value: + +BYTE TRUE If node ID (1..232) is in the list of failing nodes. + +Parameters: + +nodeID IN The node ID (1...232) to check. + +Serial API: + +HOST->ZW: REQ | 0x62 | nodeID + +ZW->HOST: RES | 0x62 | retVal diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.19-zw_isprimaryctrl.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.19-zw_isprimaryctrl.md new file mode 100644 index 0000000..c646c46 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.19-zw_isprimaryctrl.md @@ -0,0 +1,24 @@ + +# 4.4.19 ZW_IsPrimaryCtrl + +BOOL ZW_IsPrimaryCtrl (void) + +Macro: ZW_PRIMARYCTRL() + +This function is used to request whether the controller is a primary controller or a secondary controller in the network. + +Defined in: ZW_controller_api.h + +Return value: + +BOOL TRUE Returns TRUE when the controller is a primary controller in the network. + +FALSE Return FALSE when the controller is a secondary controller in the network. + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.20-zw_removefailednode.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.20-zw_removefailednode.md new file mode 100644 index 0000000..3856bb7 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.20-zw_removefailednode.md @@ -0,0 +1,54 @@ + +# 4.4.20 ZW_RemoveFailedNode + +BYTE ZW_RemoveFailedNode( BYTE NodeID, VOID_CALLBACKFUNC(completedFunc)(BYTE txStatus)) + +Macro: ZW_REMOVE_FAILED_NODE_ID(node,func) + +Used to remove a non-responding node from the routing table in the requesting controller. A non- responding node is put onto the failed node ID list in the requesting controller. In case the node responds again at a later stage then it is removed from the failed node ID list. A node must be on the failed node ID list and as an extra precaution also fail to respond before it is removed. Responding nodes can’t be removed. The call works on a primary controller and an inclusion controller. + +A call back function should be provided otherwise the function will return without removing the node. + +Defined in: ZW_controller_api.h + +Return value (If the replacing process started successfully then the function will return): + +BYTE ZW_FAILED_NODE_REMOVE_STARTED The removing process started + +Return values (If the replacing process cannot be started then the API function will return one or more of the following flags): + +BYTE ZW_NOT_PRIMARY_CONTROLLER The removing process was aborted because the controller is not the primary one. + +ZW_NO_CALLBACK_FUNCTION The removing process was aborted because no call back function is used. + +ZW_FAILED_NODE_NOT_FOUND The requested process failed. The nodeID was not found in the controller list of failing nodes. + +ZW_FAILED_NODE_REMOVE_PROCESS_BUSY The removing process is busy. + +ZW_FAILED_NODE_REMOVE_FAIL The requested process failed. Reasons include:  Controller is busy  The node responded to a NOP; therefore, the node is no longer failing. Parameters: + +nodeID IN The node ID (1..232) of the failed node to be deleted. + +completedFunc Remove process completed call back IN function Callback function Parameters: + +txStatus IN Status of removal of failed node: + +ZW_NODE_OK The node is working properly (removed from the failed nodes list). + +ZW_FAILED_NODE_REMOVED The failed node was removed from the failed nodes list. + +ZW_FAILED_NODE_NOT_REMOVED The failed node was not removed because the removing process cannot be completed. + +Serial API: + +HOST->ZW: REQ | 0x61 | nodeID | funcID + +ZW->HOST: RES | 0x61 | retVal + +ZW->HOST: REQ | 0x61 | funcID | txStatus diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.21-zw_replacefailednode.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.21-zw_replacefailednode.md new file mode 100644 index 0000000..ff05d7e --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.21-zw_replacefailednode.md @@ -0,0 +1,60 @@ + +# 4.4.21 ZW_ReplaceFailedNode + +BYTE ZW_ReplaceFailedNode( BYTE NodeID, BOOL bNormalPower, VOID_CALLBACKFUNC(completedFunc)(BYTE txStatus)) + +Macro: ZW_REPLACE_FAILED_NODE(node,func) + +This function replaces a non-responding node with a new one in the requesting controller. A non- responding node is put onto the failed node ID list in the requesting controller. In case the node responds again at a later stage then it is removed from the failed node ID list. A node must be on the failed node ID list and as an extra precaution also fail to respond before it is removed. Responding nodes can’t be replace. The call works on a primary controller and an inclusion controller. + +A call back function should be provided otherwise the function would return without replacing the node. + +Defined in: ZW_controller_api.h + +Return value (If the replacing process started successfully then the function will return): + +BYTE ZW_FAILED_NODE_REMOVE_STARTED The replacing process has started. + +Return values (If the replacing process cannot be started then the API function will return one or more of the following flags:): + +BYTE ZW_NOT_PRIMARY_CONTROLLER The replacing process was aborted because the controller is not a primary/inclusion/SIS controller. + +ZW_NO_CALLBACK_FUNCTION The replacing process was aborted because no call back function is used. + +ZW_FAILED_NODE_NOT_FOUND The requested process failed. The nodeID was not found in the controller list of failing nodes. + +ZW_FAILED_NODE_REMOVE_PROCESS_BUSY The removing process is busy. + +ZW_FAILED_NODE_REMOVE_FAIL The requested process failed. Reasons include:  Controller is busy  The node responded to a NOP; therefore, the node is no longer failing. Parameters: + +nodeID IN The node ID (1…232) of the failed node to be deleted. + +bNormalPower If TRUE then using Normal RF Power. IN + +completedFunc Replace process completed call back IN function + +Callback function Parameters: + +txStatus IN Status of replace of failed node: + +ZW_NODE_OK The node is working properly (removed from the failed nodes list). Replace process is stopped. + +ZW_FAILED_NODE_REPLACE The failed node is ready to be replaced and controller is ready to add new node with the nodeID of the failed node. Meaning that the new node must now emit a nodeinformation frame to be included. + +ZW_FAILED_NODE_REPLACE_DONE The failed node has been replaced. + +ZW_FAILED_NODE_REPLACE_FAILED The failed node has not been replaced. + +Serial API: + +HOST->ZW: REQ | 0x63 | nodeID | funcID + +ZW->HOST: RES | 0x63 | retVal + +ZW->HOST: REQ | 0x63 | funcID | txStatus diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.22-zw_removenodefromnetwork.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.22-zw_removenodefromnetwork.md new file mode 100644 index 0000000..b987a54 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.22-zw_removenodefromnetwork.md @@ -0,0 +1,129 @@ + +# 4.4.22 ZW_RemoveNodeFromNetwork + +void ZW_RemoveNodeFromNetwork(BYTE bMode, VOID_CALLBACKFUNC(completedFunc)(LEARN_INFO *learnNodeInfo)) + +Macro: ZW_REMOVE_NODE_FROM_NETWORK(bMode, func) Defined in: ZW_controller_api.h + +Serial API: Func_ID = 0x4B HOST->ZW: REQ | 0x4B | bMode | funcID ZW->HOST: REQ | 0x4B | funcID | bStatus | bSource | bLen | basic | generic | specific | cmdclasses[ ] + +ZW_RemoveNodeFromNetwork is used to remove a node from a Z-Wave network. It is also possible to perform out-of-range removal of nodes from the network when repeater nodes are capable of forwarding the new network wide exclusion (NWE) frame. It is not possible to perform out-of-range removal of nodes based on a SDK older than SDK 6.61.xx. + +The RemoveNodeFromNetwork function MAY be called by a primary controller application to invoke the removal of nodes from a Z-Wave network. Slave and secondary controller applications MUST NOT call this function. A controller application MUST implement support for the RemoveNodeFromNetwork function. The controller application MUST provide a user interface for activation of the RemoveNodeFromNetwork function. + +The bMode and completedFunc parameters MUST be specified for the RemoveNodeFromNetwork to function. + +[Refer to Figure 42 for a state diagram outlining the processing of status callbacks and timeouts.](04.04.22-zw_removenodefromnetwork.md#44223-completedfunc-callback-timeouts) + +## 4.4.22.1 bMode parameter + +[The bMode parameter MUST be carry one of the commands found in Table 22. The bMode parameter](04.04.22-zw_removenodefromnetwork.md#44221-bmode-parameter) MUST NOT be assigned more than one command. The bMode parameter MAY be assigned one or [more option flags. One command and multiple options are combined by logically OR’ing the bMode flags of Table 15.](04.04.01-zw_addnodetonetwork.md#4411-bmode-parameter) + +Table 22. RemoveNode :: bMode + +| bMode flag | Description | Usage | +| --- | --- | --- | +| REMOVE NODE ANY _ _ | Command to initiate removal of node of any type. | MUST be included when initiating removal. | +| REMOVE NODE SLAVE _ _ | - | DEPRECATED. Use REMOVE NODE ANY _ _ | +| REMOVE NODE CONTROLLER _ _ | - | DEPRECATED. Use REMOVE NODE ANY _ _ | +| REMOVE NODE STOP _ _ | Command to abort the removal process. May only be used in certain states. | MAY be used to abort an active removal process. MUST be used to terminate the removal process when completed. | +| REMOVE NODE OPTION NETWORK WIDE _ _ _ _ | Option flag to enable Network- Wide Exclusion (NWE). | MUST be used together with REMOVE NODE ANY. _ _ | + +4.4.22.1.1 REMOVE_NODE_ANY command To invoke removal of a node, a primary controller MUST call the RemoveNodeFromNetwork function with a bMode value including the REMOVE_NODE_ANY command. Slave and secondary controller nodes MUST NOT call the RemoveNodeFromNetwork function. + +The option REMOVE_NODE_OPTION_NETWORK_WIDE MUST also be used when calling RemoveNodeFromNetwork to enable the NWE feature. The NWE feature makes a Controller exclude a node transmitting the ZWAVE_CMD_EXCLUDE_REQUEST protocol command frame. The ZWAVE_CMD_EXCLUDE_REQUEST protocol command frame is essentially a Node information protocol command frame but with ZWAVE_CMD_EXCLUDE_REQUEST as command and are only transmitted as an explore frame. + +While defined in Z-Wave protocol libraries, it is NOT RECOMMENDED to use the REMOVE_NODE_SLAVE or REMOVE_NODE_CONTROLLER command codes. + +4.4.22.1.2 REMOVE_NODE_STOP command A controller MAY use the REMOVE_NODE_STOP command to abort an ongoing removal process. + +After receiving a REMOVE_NODE_STATUS_DONE status callback, the application MUST terminate the removal process by calling the RemoveNodeFromNetwork function one more time. This time, the completedFunc parameter MUST be the NULL pointer. + +## 4.4.22.2 completedFunc parameter + +Being the exception to the rule, an application calling RemoveNodeFromNetwork(REMOVE_NODE_STOP) to confirm the reception of a REMOVE_NODE_STATUS_DONE return code MUST specify the NULL pointer for the completedFunc parameter. + +In all other cases, an application calling the RemoveNodeFromNetwork function MUST specify a valid pointer to a callback function provided by the application. The callback function MUST accept a pointer parameter to a LEARN_INFO struct. The parameter provides access to actual status as well as companion data presenting the node being removed. The LEARN_INFO struct only contains a valid pointer to the Node Information Frame of a node when the status of the callback is REMOVE_NODE_STATUS_REMOVING_SLAVE or REMOVE_NODE_STATUS_REMOVING_CONTROLLER. + +Table 23. RemoveNode :: completedFunc :: learnNodeInfo + +| LEARN NODE struct member _ | Description | +| --- | --- | +| *learnNodeInfo.bStatus | Callback status code | +| *learnNodeInfo.bSource | NodeID of the node that was removed | +| *learnNodeInfo.bLen | Length of pCmd element following the bLen element. If bLen is zero, there is no valid pCmd element. | +| *learnNodeInfo.pCmd | Pointer to Application Node Information (see ApplicationNodeInformation - nodeParm). NULL if no information present. | + +Individual status codes are presented in the following sections. Table 24. RemoveNode :: completedFunc :: learnNodeInfo.bStatus + +| LEARN NODE.bStatus _ | Description | +| --- | --- | +| REMOVE NODE STATUS LEARN READY _ _ _ _ | Z-Wave protocol is ready to remove a node. | +| REMOVE NODE STATUS NODE FOUND _ _ _ _ | Z-Wave protocol detected node. | +| REMOVE NODE STATUS REMOVING _ _ _ _ SLAVE | Z-Wave protocol removed a slave type node | +| REMOVE NODE STATUS REMOVING _ _ _ _ CONTROLLER | Z-Wave protocol removed a controller type node | +| REMOVE NODE STATUS DONE _ _ _ | All operations completed. Protocol is ready to return to idle state. | +| REMOVE NODE STATUS FAILED _ _ _ | Z-Wave protocol reports that removal was not successful. Node may not have been removed. | +| ADD NODE STATUS NOT PRIMARY _ _ _ _ | Z Wave protocol reports that the requested operation cannot be performed since it requires that the node is in primary controller state. | + +[Refer to Figure 42 for a state diagram outlining the processing of status callbacks and timeouts.](04.04.22-zw_removenodefromnetwork.md#44223-completedfunc-callback-timeouts) + +4.4.22.2.1 REMOVE_NODE_STATUS_LEARN_READY status Z-Wave protocol is ready to remove a node. An application MAY time out waiting for the REMOVE_NODE_STATUS_LEARN_READY status if it does not receive the indication within 200 msec after calling RemoveNodeFromNetwork(REMOVE_NODE_ANY). + +If the application times out waiting for the REMOVE_NODE_STATUS_LEARN_READY status, the application MUST call RemoveNodeFromNetwork(REMOVE_NODE_STOP, NULL). + +4.4.22.2.2 REMOVE_NODE_STATUS_NODE_FOUND status Z-Wave protocol detected node. An application MUST time out waiting for the REMOVE_NODE_STATUS_NODE_FOUND status if it does not receive the indication after calling RemoveNodeFromNetwork(REMOVE_NODE_ANY). The RECOMMENDED interval is 60 sec. + +If the application times out waiting for the REMOVE_NODE_STATUS_NODE_FOUND status, the application MUST call RemoveNodeFromNetwork(REMOVE_NODE_STOP, NULL). + +The application MUST NOT call RemoveNodeFromNetwork() before the timeout occurs. This may cause the protocol to malfunction. + +4.4.22.2.3 REMOVE_NODE_STATUS_REMOVING_SLAVE status Z-Wave protocol is removing a slave type node. The NodeID of the node is included in the callback. An application MUST time out waiting for the REMOVE_NODE_STATUS_REMOVING_SLAVE status if it does not receive the indication within a 14 sec after receiving the REMOVE_NODE_STATUS_NODE_FOUND status. + +If the application times out waiting for the REMOVE_NODE_STATUS_REMOVNG_SLAVE status, the application MUST call RemoveNodeFromNetwork(REMOVE_NODE_STOP). The application MUST specify a valid callback function. This allows the application to receive a REMOVE_NODE_STATUS_DONE once the protocol has completed cleaning up its datastructures. + +The application MUST NOT call RemoveNodeFromNetwork() before the timeout occurs. This may cause the protocol to malfunction. + +4.4.22.2.4 REMOVE_NODE_STATUS_REMOVING_CONTROLLER status Z-Wave protocol is removing a controller type node. The NodeID of the node is included in the callback. + +An application MUST time out waiting for the REMOVE_NODE_STATUS_REMOVING_CONTROLLER status if it does not receive the indication within a 14 sec after receiving the REMOVE_NODE_STATUS_NODE_FOUND status. + +If the application times out waiting for the REMOVE_NODE_STATUS_REMOVING_CONTROLLER status, the application MUST call RemoveNodeFromNetwork(REMOVE_NODE_STOP). The application MUST specify a valid callback function. This allows the application to receive an REMOVE_NODE_STATUS_DONE once the protocol has completed cleaning up its datastructures. + +The application MUST NOT call RemoveNodeFromNetwork() before the timeout occurs. This may cause the protocol to malfunction. + +4.4.22.2.5 REMOVE_NODE_STATUS_DONE status All operations completed. Protocol is ready to return to idle state. + +In response to the REMOVE_NODE_STATUS_DONE status callback, the application MUST call RemoveNodeFromNetwork(REMOVE_NODE_STOP, NULL). The application MUST specify the NULL pointer for the callback function. + +4.4.22.2.6 REMOVE_NODE_STATUS_FAILED status If an application receives a REMOVE_NODE_STATUS_PROTOCOL_FAILED status callback, the application MUST terminate the removal process by calling [RemoveNodeFromNetwork(REMOVE_NODE_STOP). Refer to 4.4.22.1.2.](04.04.22-zw_removenodefromnetwork.md#44221-bmode-parameter) + +4.4.22.2.7 ADD_NODE_STATUS_NOT_PRIMARY status An application MUST NOT call the RemoveNodeFromNetwork function if the application is not running in a primary controller. If the function is called by an application running in slave or a secondary controller, the API MUST return the ADD_NODE_STATUS_NOT_PRIMARY status callback. + +## 4.4.22.3 completedFunc callback timeouts + +4.4.22.3.1 ProtocolReadyTimeout The API MUST return a REMOVE_NODE_STATUS_LEARN_READY status callback within less than 200 msec after receiving a call to RemoveNodeFromNetwork(REMOVE_NODE_ANY). + +If an application has not received a REMOVE_NODE_STATUS_LEARN_READY status callback 200 msec after calling RemoveNodeFromNetwork(REMOVE_NODE_ANY), the application MAY time out and return to its idle state. 4.4.22.3.2 NodeTimeout An application MUST implement a timeout for waiting for an REMOVE_NODE_STATUS_NODE_FOUND status callback. + +The application SHOULD NOT wait for a REMOVE_NODE_STATUS_NODE_FOUND status callback for more than 60 sec after calling RemoveNodeFromNetwork(REMOVE_NODE_ANY). If timing out, the application SHOULD abort removal. + +4.4.22.3.3 RemoveNodeTimeout An application MUST time out if removal has not been completed within 14 sec after the reception of the REMOVE_NODE_STATUS_NODE_FOUND status callback. + +If timing out, the application MUST evaluate the controller node list to verify that the NodeID was removed. The removal process SHOULD be repeated if the NodeID is still found in the node list. + +![Figure 42. Removing a Node from the Network](assets/img-650c78a2f9.png) + +Table 25. RemoveNode : State/Event processing - 1 + +![figure p395](assets/img-fb9a2acc23.png) + +Table 26. RemoveNode : State/Event processing - 2 + +![figure p396](assets/img-765cb9c389.png) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.23-zw_removenodeidfromnetwork.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.23-zw_removenodeidfromnetwork.md new file mode 100644 index 0000000..0857975 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.23-zw_removenodeidfromnetwork.md @@ -0,0 +1,38 @@ + +# 4.4.23 ZW_RemoveNodeIDFromNetwork + +void ZW_RemoveNodeIDFromNetwork(BYTE bMode, BYTE bNodeID, VOID_CALLBACKFUNC(completedFunc)(LEARN_INFO *learnNodeInfo)) + +Macro: ZW_REMOVE_NODE_ID_FROM_NETWORKmode, nodeid, func) Defined in: ZW_controller_api.h + +Serial API: Func_ID = 0x3F HOST->ZW: REQ | 0x3F | bMode | bNodeID | funcID ZW->HOST: REQ | 0x3F | funcID | bStatus | bSource | bLen | basic | generic | specific | cmdclasses[ ] + +ZW_RemoveNodeIDFromNetwork can be used to remove a specific node from a Z-Wave network. + +The RemoveNodeIDFromNetwork function MAY be called by a primary controller application to invoke the removal of a specific node from the Z-Wave network in question. Slave and secondary controller applications MUST NOT call this function. + +The bMode, bNodeID and completedFunc parameters MUST be specified for the RemoveNodeIDFromNetwork function to function. + +[Refer to Figure 42 and substitute ZW_RemoveNodeFromNetwork with](04.04.22-zw_removenodefromnetwork.md#44223-completedfunc-callback-timeouts) ZW_RemoveNodeIDFromNetwork for a state diagram outlining the processing of status callbacks and timeouts. + +## 4.4.23.1 bMode parameter + +[See ZW_RemoveNodeFromNetwork 4.4.22.1 and substitute ZW_RemoveNodeFromNetwork with](04.04.22-zw_removenodefromnetwork.md#44221-bmode-parameter) ZW_RemoveNodeIDFromNetwork for a description of the bMode parameter. + +## 4.4.23.2 bNodeID parameter + +The bNodeID parameter can be used to specify that only the node with the exact nodeID as specified can be excluded through the started exclusion process. + +If a valid bNodeID value (1-232) is specified then only the specified bNodeID with the same HomeID as the excluding controller and matching the mode settings can be removed. + +If REMOVE_NODE_ID_ANY or any NONE valid nodeID (0, 233-255) is specified then [ZW_RemoveNodeIDFromNetwork functions exactly as ZW_RemoveNodeFromNetwork (See 4.4.22).](04.04.22-zw_removenodefromnetwork.md#4422-zw_removenodefromnetwork) + +## 4.4.23.3 completedFunc parameter + +[See ZW_RemoveNodeFromNetwork 4.4.22.2 and substitute ZW_RemoveNodeFromNetwork with](04.04.22-zw_removenodefromnetwork.md#44222-completedfunc-parameter) ZW_RemoveNodeIDFromNetwork for a description of the completedFunc parameter. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.24-zw_replicationreceivecomplete.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.24-zw_replicationreceivecomplete.md new file mode 100644 index 0000000..ab9e497 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.24-zw_replicationreceivecomplete.md @@ -0,0 +1,20 @@ + +# 4.4.24 ZW_ReplicationReceiveComplete + +void ZW_ReplicationReceiveComplete(void) + +Macro: ZW_REPLICATION_COMMAND_COMPLETE + +Sends command completed to sending controller. Called in replication mode when a command from the sender has been processed and indicates that the controller is ready for next packet. + +Defined in: ZW_controller_api.h + +Serial API: + +HOST->ZW: REQ | 0x44 diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.25-zw_replicationsend.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.25-zw_replicationsend.md new file mode 100644 index 0000000..1166c91 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.25-zw_replicationsend.md @@ -0,0 +1,46 @@ + +# 4.4.25 ZW_ReplicationSend + +BYTE ZW_ReplicationSend(BYTE destNodeID, BYTE *pData, BYTE dataLength, BYTE txOptions, VOID_CALLBACKFUNC(completedFunc)(BYTE txStatus)) + +Macro: ZW_REPLICATION_SEND_DATA(node,data,length,options,func) + +Used when the controller is in replication mode. It sends the payload and expects the receiver to respond with a command complete message (ZW_REPLICATION_COMMAND_COMPLETE). + +Messages sent using this command should always be part of the Z-Wave controller replication command class. + +Defined in: ZW_controller_api.h + +Return value: + +BYTE FALSE If transmit queue overflow. + +Parameters: + +destNode IN Destination Node ID (not equal NODE_BROADCAST). + +pData IN Data buffer pointer + +dataLength IN Data buffer length + +txOptions IN Transmit option flags. (see ZW_SendData, but avoid using routing!) + +completedFunc Transmit completed call back function IN + +Callback function Parameters: + +txStatus IN (see ZW_SendData) + +Serial API: + +HOST->ZW: REQ | 0x45 | destNodeID | dataLength | pData[ ] | txOptions | funcID + +ZW->HOST: RES | 0x45 | RetVal + +ZW->HOST: REQ | 0x45 | funcID | txStatus diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.26-zw_requestnodeinfo.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.26-zw_requestnodeinfo.md new file mode 100644 index 0000000..9b15fd0 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.26-zw_requestnodeinfo.md @@ -0,0 +1,38 @@ + +# 4.4.26 ZW_RequestNodeInfo + +BOOL ZW_RequestNodeInfo (BYTE nodeID, VOID (*completedFunc)(BYTE txStatus)) + +Macro: ZW_REQUEST_NODE_INFO(NODEID) + +This function is used to request the Node Information Frame from a controller based node in the network. The Node info is retrieved using the ApplicationControllerUpdate callback function with the status UPDATE_STATE_NODE_INFO_RECEIVED. The ZW_RequestNodeInfo API call is also available for routing slaves. + +Defined in: ZW_controller_api.h + +Return value: + +BOOL TRUE If the request could be put in the transmit queue successfully. + +FALSE If the request could not be put in the transmit queue. Request failed. + +Parameters: + +nodeID IN The node ID (1...232) of the node to request the Node Information Frame from. + +completedFunc Transmit complete call back. IN + +Callback function Parameters: + +txStatus IN (see ZW_SendData) + +Serial API: + +HOST->ZW: REQ | 0x60 | NodeID + +ZW->HOST: RES | 0x60 | retVal diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.27-zw_requestnodeneighborupdate.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.27-zw_requestnodeneighborupdate.md new file mode 100644 index 0000000..d1e8f8c --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.27-zw_requestnodeneighborupdate.md @@ -0,0 +1,42 @@ + +# 4.4.27 ZW_RequestNodeNeighborUpdate + +BYTE ZW_RequestNodeNeighborUpdate(NODEID, VOID_CALLBACKFUNC (completedFunc)(BYTE bStatus)) + +Macro: ZW_REQUEST_NODE_NEIGHBOR_UPDATE(nodeid, func) + +Get the neighbors from the specified node. To ensure strong RF links the node uses normal RF power level minus 6dB to find its neighbors. This call can only be called by a primary/inclusion controller. An inclusion controller should call ZW_RequestNetWorkUpdate in advance because the inclusion controller may not have the latest network topology. + +Defined in: ZW_controller_api.h + +Return value: + +BYTE TRUE The discovery process is started and the function will be completed by the callback + +FALSE The discovery was not started and the callback will not be called. The reason for the failure can be one of the following:  This is not a primary/inclusion controller  There is only one node in the network, nothing to update.  The controller is busy doing another update. + +Parameters: + +nodeID IN Node ID (1...232) of the node that the controller wants to get new neighbors from. Not allowed to use controllers own node ID. + +completedFunc Transmit complete call back. IN + +Callback function Parameters: + +bStatus IN Status of command: + +REQUEST_NEIGHBOR_UPDATE_STARTED Requesting neighbor list from the node is in progress. + +REQUEST_NEIGHBOR_UPDATE_DONE New neighbor list received + +REQUEST_NEIGHBOR_UPDATE_FAIL Getting new neighbor list failed + +Serial API: HOST->ZW: REQ | 0x48 | nodeID | funcID + +ZW->HOST: REQ | 0x48 | funcID | bStatus diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.28-zw_sendsucid.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.28-zw_sendsucid.md new file mode 100644 index 0000000..7420e4c --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.28-zw_sendsucid.md @@ -0,0 +1,44 @@ + +# 4.4.28 ZW_SendSUCID + +BYTE ZW_SendSUCID (BYTE node, BYTE txOption, VOID_CALLBACKFUNC (completedFunc)(BYTE txStatus, TX_STATUS_TYPE* txStatusReport)) + +Macro: ZW_SEND_SUC_ID(nodeID, txOption, func) + +Transmit SUC/SIS node ID from a primary controller or static controller to the controller node ID specified. Routing slaves ignore this command, use instead ZW_AssignSUCReturnRoute. + +Defined in: ZW_controller_api.h + +Return value: + +TRUE In progress. + +FALSE Not a primary controller or static controller. + +Parameters: + +node IN The node ID (1...232) of the node to receive the current SUC/SIS node ID. + +txOption IN Transmit option flags. (see ZW_SendData) + +completedFunc Transmit complete call back. IN + +Callback function parameters: + +txStatus IN (see ZW_SendData) + +txStatusReport IN (see ZW_SendData) + +Serial API: + +HOST->ZW: REQ | 0x57 | node | txOption | funcID + +ZW->HOST: RES | 0x57 | RetVal + +ZW->HOST: REQ | 0x57 | funcID | txStatus diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.29-zw_setdefault.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.29-zw_setdefault.md new file mode 100644 index 0000000..4c5b609 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.29-zw_setdefault.md @@ -0,0 +1,32 @@ + +# 4.4.29 ZW_SetDefault + +void ZW_SetDefault( VOID_CALLBACKFUNC(completedFunc)(void)) + +Macro: ZW_SET_DEFAULT(func) + +This function set the Controller back to the factory default state. Erase all Nodes, routing information and assigned homeID/nodeID from the NVM. In case the previous home ID was randomly generated then a new random home ID written to the NVM (random range: 0xC0000000-0xFFFFFFFE). A home ID outside random range reuses the initially configured home ID (configured during production). + +Warning: Use this function with care as it could render a Z-Wave network unusable if the primary controller in an existing network is set back to default. + +Defined in: ZW_controller_api.h + +Parameters: + +completedFunc IN Command completed call back function + +Serial API: + +HOST->ZW: REQ | 0x42 | funcID + +ZW->HOST: REQ | 0x42 | funcID + +Timeout: 1000ms + +Exception Recovery: Resume normal operation, check nodelist to see if the controller has been reset. A controller MUST have nodeID ==1 after a set default. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.30-zw_setlearnmode.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.30-zw_setlearnmode.md new file mode 100644 index 0000000..85feab0 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.30-zw_setlearnmode.md @@ -0,0 +1,68 @@ + +# 4.4.30 ZW_SetLearnMode + +void ZW_SetLearnMode (BYTE mode, VOID_CALLBACKFUNC(completedFunc)(LEARN_INFO *learnNodeInfo)) + +Macro: ZW_SET_LEARN_MODE(mode, func) + +ZW_SetLearnMode is used to add or remove the controller to/from a Z-Wave network. + +This function is used to instruct the controller to allow it to be added or removed from the network. + +When a controller is added to the network the following things will happen: 1. If the current stored ID's are zero and the assigned ID’s are nonzero, the received ID's will be stored (node was added to the network). 2. If the received ID's are zero the stored ID's will be set to zero (node was removed from the network). 3. The controller receives updates to the node list and the routing table but the ID’s remain unchanged. + +This function will probably change the capabilities of the controller so it is recommended that the application calls ZW_GetControllerCapabilities() after completion to check the controller status. + +The learnFunc is called as the "Assign" process progresses. The returned nodeID is the nodes new Node ID. If no "Assign" is received from the including controller the callback function will not be called. It is then up to the application code to switch of Learn mode. Once the assignment process has been started the Callback function may be called more than once. The learn process is not complete before the callback function is called with LEARN_MODE_DONE. + +Network wide inclusion (add) should always be used as the default mode in inclusion to ensure compability with all implementations of Z-Wave controllers. + +[For information about how to use the different learn modes to make a inclusion that is compatible with all generations of Z-Wave nodes see [4]](../../08-references.md#8-references) + +NOTE: Learn mode should only be enabled when necessary and disabled again as quickly as possible. It is recommended that learn mode is not enabling for more than 2 second in ZW_SET_LEARN_MODE_CLASSIC mode and 5 seconds in either ZW_SET_LEARN_MODE_NWI or ZW_SET_LEARN_MODE_NWE mode. + +NOTE: When the controller is already included into a network (secondary or inclusion controller) the callback status LEARN_MODE_STARTED will not be made but the LEARN_MODE_DONE/FAILED callback will be made as normal. + +WARNING: The learn process should not be stopped with ZW_SetLearnMode(FALSE,..) between the LEARN_MODE_STARTED and the LEARN_MODE_DONE status callback. Defined in: ZW_controller_api.h + +Parameters: + +mode IN The learn node states are: + +ZW_SET_LEARN_MODE_CLASSIC Start the learn mode on the controller and only accept being included and exluded in direct range. + +ZW_SET_LEARN_MODE_NWI Start the learn mode on the controller and accept routed inclusion (add). NWI mode must not be used for exclusion (remove). + +ZW_SET_LEARN_MODE_NWE Start the learn mode on the controller and accept routed exclusion (remove) as well as direct. NWE mode must not be used for inclusion (add). + +ZW_SET_LEARN_MODE_DISABLE Stop learn mode on the controller + +completedFunc IN Callback function pointer (Should only be NULL if state is turned off). Callback function Parameters (completedFunc): + +*learnNodeInfo.bStatus Status of learn mode: IN LEARN_MODE_STARTED The learn process has been started + +LEARN_MODE_DONE The learn process is complete and the controller is now included into the network + +LEARN_MODE_FAILED The learn process failed. + +*learnNodeInfo.bSource Node id of the new node IN + +*learnNodeInfo.pCmd Pointer to Application Node information data IN (see ApplicationNodeInformation - nodeParm). NULL if no information present. + +The pCmd only contain information when bLen is not zero, so the information should be stored when that is the case. Regardless of the bStatus. + +*learnNodeInfo.bLen IN Node info length. + +Serial API: + +HOST->ZW: REQ | 0x50 | mode | funcID + +ZW->HOST: RES | TRUE + +ZW->HOST: REQ | 0x50 | funcID | bStatus | bSource | bLen | pCmd[ ] diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.31-zw_setroutinginfo.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.31-zw_setroutinginfo.md new file mode 100644 index 0000000..a419571 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.31-zw_setroutinginfo.md @@ -0,0 +1,45 @@ + +# 4.4.31 ZW_SetRoutingInfo + +void ZW_SetRoutingInfo(BYTE bNodeID, BYTE bLength, BYTE_P pMask ) + +Macro: ZW_SET_ROUTING_INFO(bNodeID, bLength, pMask) + +ZW_SetRoutingInfo is a function that can be used to overwrite the current neighbor information for a given node ID in the protocol locally. + +The format of the routing info must be organised as follows: + +| pMask[i] (0  i < (ZW MAX NODES/8) _ _ | | | | | | | | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Bit | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | +| NodeID | i*8+1 | i*8+2 | i*8+3 | i*8+4 | i*8+5 | i*8+6 | i*8+7 | i*8+8 | + +If a bit n in pMask[i] is 1 it indicates that the node bNodeID has node (i*8)+n+1 as a neighbour. If n in pMask[i] is 0, bNodeID cannot reach node (i*8)+n+1 directly. + +Defined in: ZW_controller_api.h + +Return value: + +BOOL TRUE Neighbor information updated successfully. + +FALSE Failed to update neighbor information. + +Parameters: + +bNodeID IN Node ID (1…232) to be updated with respect to neighbor information. + +bLength IN Routing info buffer length in bytes. + +pMask IN Pointer to buffer where routing info should be taken from. The buffer should be at least ZW_MAX_NODES/8 bytes + +Serial API (Only Developer’s Kit v4.5x): + +HOST->ZW: REQ | 0x1B | bNodeID | NodeMask[29] + +ZW->HOST: RES | 0x1B | retVal diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.32-zw_setroutingmax.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.32-zw_setroutingmax.md new file mode 100644 index 0000000..5fdc1c7 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.32-zw_setroutingmax.md @@ -0,0 +1,24 @@ + +# 4.4.32 ZW_SetRoutingMAX + +void ZW_SetRoutingMAX(BYTE maxRouteTries) + +Use this function to set the maximum number of source routing attempts before the next mechanism [kicks-in. Default value with respect to maximum number of source routing attempts is five. See section 3.10 wrt. the routing attempts for a given Z-Wave node. Remember to enable the transmit option flag](../../03-z-wave-software-architecture/03.10-z-wave-nodes.md#310-z-wave-nodes) TRANSMIT_OPTION_AUTO_ROUTE or TRANSMIT_OPTION_AUTO_ROUTE | TRANSMIT_OPTION_EXPLORE in the send data calls. + +Defined in: ZW_controller_api.h + +Parameters: + +maxRouteTries IN 1...20 Maximum number of source routing attempts + +Serial API: + +HOST->ZW: REQ | 0xD4 | maxRoutesTries + +ZW->HOST: RES | 0xD4 | TRUE diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.33-zw_setsucnodeid.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.33-zw_setsucnodeid.md new file mode 100644 index 0000000..5151a5a --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/04.04.33-zw_setsucnodeid.md @@ -0,0 +1,62 @@ + +# 4.4.33 ZW_SetSUCNodeID + +BYTE ZW_SetSUCNodeID (BYTE nodeID, BYTE SUCState, BYTE bTxOption, BYTE capabilities, VOID_CALLBACKFUNC (completedFunc)(BYTE txStatus, TX_STATUS_TYPE* txStatusReport)) + +Macro: ZW_SET_SUC_NODE_ID(nodeID, SUCState, bTxOption, capabilities, func) + +Used to configure a static/bridge controller to be a SUC/SIS node or not. The primary controller should use this function to set a static/bridge controller to be the SUC/SIS node, or it could be used to stop previously chosen static/bridge controller being a SUC/SIS node (not recommended). + +A controller can set itself to a SUC/SIS by ZW_SetSUCNodeID with its own node ID. It’s recommended to do this when the Z-Wave network only comprise of the primary controller to get the SUC/SIS role distributed when new nodes are included. It is possible to include a virgin primary controller with SUC/SIS capabilities configured into another Z-Wave network. + +NOTICE: It is not allowed to call ZW_SetSUCNodeID with its own node ID and SUCState = FALSE during upstart because this prevent other nodes to set it to a SUC/SIS node. + +Defined in: ZW_controller_api.h + +Return value: + +TRUE If the process of configuring the static/bridge controller is started. + +FALSE The process not started because the calling controller is not the master or the destination node is not a static/bridge controller. Parameters: + +nodeID IN The node ID (1...232) of the static controller to configure. + +SUCState IN TRUE Want the static controller to be a SUC/SIS node. + +FALSE If the static/bridge controller should not be a SUC/SIS node. + +bTxOption IN TRUE Want to send the frame with low transmission power + +FALSE Want to send the frame at normal transmission power + +capabilities IN SUC capabilities that is enabled: + +ZW_SUC_FUNC_NODEID_SERVER Enable the node ID server functionality to become a SIS. + +completedFunc Transmit complete call back. IN + +Callback function Parameters: + +txStatus IN Status of command: + +ZW_SUC_SET_SUCCEEDED The process ended successfully. + +ZW_SUC_SET_FAILED The process failed. + +txStatusReport (see ZW_SendData) IN + +Serial API: + +HOST->ZW: REQ | 0x54 | nodeID | SUCState | bTxOption | capabilities | funcID + +ZW->HOST: RES | 0x54 | RetVal + +ZW->HOST: REQ | 0x54 | funcID | txStatus + +In case ZW_SetSUCNodeID is called locally with the controllers own node ID then only the response is returned. In case true is returned in the response then it can be interpreted as the command is now executed successfully. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/index.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/index.md new file mode 100644 index 0000000..c511f87 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.04-z-wave-controller-api/index.md @@ -0,0 +1,46 @@ + +# 4.4 Z-Wave Controller API + +The Z-Wave Controller API makes it possible for different controllers to control the Z-Wave nodes and get information about each node’s capabilities and current state. The node control commands can be sent to a single node, all nodes or to a list of nodes (group, scene…). + +## Contents + +- [4.4.1 ZW_AddNodeToNetwork](04.04.01-zw_addnodetonetwork.md) +- [4.4.2 ZW_AddNodeDskToNetwork](04.04.02-zw_addnodedsktonetwork.md) +- [4.4.3 ZW_AreNodesNeighbours](04.04.03-zw_arenodesneighbours.md) +- [4.4.4 ZW_AssignReturnRoute](04.04.04-zw_assignreturnroute.md) +- [4.4.5 ZW_AssignSUCReturnRoute](04.04.05-zw_assignsucreturnroute.md) +- [4.4.6 ZW_AssignPriorityReturnRoute](04.04.06-zw_assignpriorityreturnroute.md) +- [4.4.7 ZW_AssignPrioritySUCReturnRoute](04.04.07-zw_assignprioritysucreturnroute.md) +- [4.4.8 ZW_ControllerChange](04.04.08-zw_controllerchange.md) +- [4.4.9 ZW_DeleteReturnRoute](04.04.09-zw_deletereturnroute.md) +- [4.4.10 ZW_DeleteSUCReturnRoute](04.04.10-zw_deletesucreturnroute.md) +- [4.4.11 ZW_GetControllerCapabilities](04.04.11-zw_getcontrollercapabilities.md) +- [4.4.12 ZW_GetNeighborCount](04.04.12-zw_getneighborcount.md) +- [4.4.13 ZW_GetPriorityRoute](04.04.13-zw_getpriorityroute.md) +- [4.4.14 ZW_SetPriorityRoute](04.04.14-zw_setpriorityroute.md) +- [4.4.15 ZW_GetNodeProtocolInfo](04.04.15-zw_getnodeprotocolinfo.md) +- [4.4.16 ZW_GetRoutingInfo](04.04.16-zw_getroutinginfo.md) +- [4.4.17 ZW_GetSUCNodeID](04.04.17-zw_getsucnodeid.md) +- [4.4.18 ZW_IsFailedNode](04.04.18-zw_isfailednode.md) +- [4.4.19 ZW_IsPrimaryCtrl](04.04.19-zw_isprimaryctrl.md) +- [4.4.20 ZW_RemoveFailedNode](04.04.20-zw_removefailednode.md) +- [4.4.21 ZW_ReplaceFailedNode](04.04.21-zw_replacefailednode.md) +- [4.4.22 ZW_RemoveNodeFromNetwork](04.04.22-zw_removenodefromnetwork.md) +- [4.4.23 ZW_RemoveNodeIDFromNetwork](04.04.23-zw_removenodeidfromnetwork.md) +- [4.4.24 ZW_ReplicationReceiveComplete](04.04.24-zw_replicationreceivecomplete.md) +- [4.4.25 ZW_ReplicationSend](04.04.25-zw_replicationsend.md) +- [4.4.26 ZW_RequestNodeInfo](04.04.26-zw_requestnodeinfo.md) +- [4.4.27 ZW_RequestNodeNeighborUpdate](04.04.27-zw_requestnodeneighborupdate.md) +- [4.4.28 ZW_SendSUCID](04.04.28-zw_sendsucid.md) +- [4.4.29 ZW_SetDefault](04.04.29-zw_setdefault.md) +- [4.4.30 ZW_SetLearnMode](04.04.30-zw_setlearnmode.md) +- [4.4.31 ZW_SetRoutingInfo](04.04.31-zw_setroutinginfo.md) +- [4.4.32 ZW_SetRoutingMAX](04.04.32-zw_setroutingmax.md) +- [4.4.33 ZW_SetSUCNodeID](04.04.33-zw_setsucnodeid.md) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.05-z-wave-static-controller-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.05-z-wave-static-controller-api.md new file mode 100644 index 0000000..2e6bb4d --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.05-z-wave-static-controller-api.md @@ -0,0 +1,66 @@ + +# 4.5 Z-Wave Static Controller API + +The Static Controller application interface is an extended Controller application interface with added functionality specific for the Static Controller. + +## 4.5.1 ZW_CreateNewPrimaryCtrl + +Void ZW_CreateNewPrimaryCtrl(BYTE mode, VOID_CALLBACKFUNC(completedFunc)(LEARN_INFO *learnNodeInfo)) + +Macro: ZW_CREATE_NEW_PRIMARY_CTRL + +NOTE: Legacy function. This function is no longer relevant for a controller because it is no longer possible to have a SUC without a SIS. This function should not be used. + +ZW_CreateNewPrimaryCtrl is used to add a controller to the Z-Wave network as a replacement for the old primary controller. + +This function has the same functionality as ZW_AddNodeToNetwork(ADD_NODE_CONTROLLER,…) except that the new controller will be a primary controller and it can only be called by a SUC. The function is not available if the SUC is a node ID server (SIS). + +WARNING: This function should only be used when it is 100% certain that the original primary controller is lost or broken and will not return to the network. + +Defined in: ZW_controller_static_api.h + +Parameters: + +mode IN The learn node states are: + +CREATE_PRIMARY_START Start the process of adding a a new primary controller to the network. + +CREATE_PRIMARY_STOP Stop the process. + +CREATE_PRIMARY_STOP_FAILED Stop the inclusion (add) and report a failure to the other controller. + +completedFunc IN Callback function pointer (Should only be NULL if state is turned off). + +Callback function Parameters: + +*learnNodeInfo.bStatus IN Status of learn mode: ADD_NODE_STATUS_LEARN_READY The controller is now ready to include a controller into the network. + +ADD_NODE_STATUS_NODE_FOUND A controller that wants to be included into the network has been found + +ADD_NODE_STATUS_ADDING_CONTROLLER A new controller has been added to the network + +ADD_NODE_STATUS_PROTOCOL_DONE The protocol part of adding a controller is complete, the application can now send data to the new controller using ZW_ReplicationSend() + +ADD_NODE_STATUS_DONE The new controller has now been included and the controller is ready to continue normal operation again. + +ADD_NODE_STATUS_FAILED The learn process failed + +*learnNodeInfo.bSource IN Node id of the new node + +*learnNodeInfo.pCmd IN Pointer to Application Node information data (see ApplicationNodeInformation - nodeParm). NULL if no information present. + +The pCmd only contain information when bLen is not zero, so the information should be stored when that is the case. Regardless of the bStatus. + +*learnNodeInfo.bLen IN Node info length. + +Serial API: + +HOST->ZW: REQ | 0x4C | mode | funcID + +ZW->HOST: REQ | 0x4C | funcID | bStatus | bSource | bLen | basic | generic | specific | cmdclasses[ ] diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.06-z-wave-bridge-controller-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.06-z-wave-bridge-controller-api.md new file mode 100644 index 0000000..b9cae98 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.06-z-wave-bridge-controller-api.md @@ -0,0 +1,171 @@ + +# 4.6 Z-Wave Bridge Controller API + +The Bridge Controller application interface is an extended Controller application interface with added functionality specific for the Bridge Controller. + +## 4.6.1 ZW_SendSlaveNodeInformation + +BYTE ZW_SendSlaveNodeInformation(BYTE srcNode, BYTE destNode, BYTE txOptions, VOID_CALLBACKFUNC(completedFunc)(BYTE txStatus, TX_STATUS_TYPE* txStatusReport)) + +Macro: ZW_SEND_SLAVE_NODE_INFO(srcnode, destnode, option, func) + +Create and transmit a Virtual Slave node “Node Information” frame from Virtual Slave node srcNode. The Z-Wave transport layer builds a frame, request the application slave node information (see ApplicationSlaveNodeInformation) and queue the “Node Information” frame for transmission. The completed call back function (completedFunc) is called when the transmission is complete. + +NOTE: ZW_SendSlaveNodeInformation uses the transmit queue in the API, so using other transmit functions before the complete callback has been called by the API might fail. + +Defined in: ZW_controller_bridge_api.h + +Return value: + +BYTE TRUE If frame was put in the transmit queue. + +FALSE If transmitter queue overflow or if bridge controller is primary or srcNode is invalid then completedFunc will NOT be called. + +Parameters: + +srcNode IN Source Virtual Slave Node ID + +destNode IN Destination Node ID (NODE_BROADCAST == all nodes) + +txOptions IN Transmit option flags: + +TRANSMIT_OPTION_LOW_POWER Transmit at low output power level (1/3 of normal RF range). NOTE: The TRANSMIT_OPTION_LOW_POWER option should only be used when the two nodes that are communicating are close to each other (<2 meter). In all other cases this option should not be used. + +TRANSMIT_OPTION_ACK Request acknowledge from destination node. completedFunc IN Transmit completed call back function + +Callback function Parameters: + +txStatus (see ZW_SendData) + +txStatusReport IN (see ZW_SendData) + +Serial API: + +HOST->ZW: REQ | 0xA2 | srcNode | destNode | txOptions | funcID + +ZW->HOST: RES | 0xA2 | retVal + +ZW->HOST; REQ | 0xA2 | funcID | txStatus + +## 4.6.2 ZW_SetSlaveLearnMode + +BYTE ZW_SetSlaveLearnMode(BYTE node, BYTE mode, VOID_CALLBACKFUNC(learnSlaveFunc)(BYTE state, BYTE orgID, BYTE newID)) + +Macro: ZW_SET_SLAVE_LEARN_MODE (node, mode, func) + +ZW_SetSlaveLearnMode enables the possibility for enabling or disabling “Slave Learn Mode”, which when enabled makes it possible for other controllers (primary or inclusion controllers) to add or remove a Virtual Slave Node to the Z-Wave network. Also is it possible for the bridge controller (only when primary or inclusion controller) to add or remove a Virtual Slave Node without involving other controllers. Available Slave Learn Modes are: + +VIRTUAL_SLAVE_LEARN_MODE_DISABLE – Disables the Slave Learn Mode so that no Virtual Slave Node can be added or removed. + +VIRTUAL_SLAVE_LEARN_MODE_ENABLE – Enables the possibility for other Primary/Inclusion controllers to add or remove a Virtual Slave Node. To add a new Virtual Slave node to the Z-Wave Network the provided “node” ID must be ZERO and to make it possible to remove a specific Virtual Slave Node the provided “node” ID must be the nodeID for this specific (locally present) Virtual Slave Node. When the Slave Learn Mode has been enabled the Virtual Slave node must identify itself to the external Primary/Inclusion Controller node by sending a “Node Information” frame (see ZW_SendSlaveNodeInformation) to make the add/remove operation commence. + +VIRTUAL_SLAVE_LEARN_MODE_ADD - Add Virtual Slave Node to the Z-Wave network without involving any external controller. This Slave Learn Mode is only possible when bridge controller is either a Primary controller or an Inclusion controller. + +VIRTUAL_SLAVE_LEARN_MODE_REMOVE - Remove a locally present Virtual Slave Node from the Z-Wave network without involving any external controller. This Slave Learn Mode is only possible when bridge controller is either a Primary controller or an Inclusion controller. + +The learnSlaveFunc is called as the "Assign" process progresses. The returned “orgID” is the Virtual Slave node put into Slave Learn Mode, the “newID” is the new Node ID. If the Slave Learn Mode is VIRTUAL_SLAVE_LEARN_MODE_ENABLE and nothing is received from the assigning controller the callback function will not be called. It is then up to the main application code to switch of Slave Learn mode by setting the VIRTUAL_SLAVE_LEARN_MODE_DISABLE Slave Learn Mode. Once the assignment process has been started the Callback function may be called more than once. + +NOTE: Slave Learn Mode should only be set to VIRTUAL_SLAVE_LEARN_MODE_ENABLE when necessary, and it should always be set to VIRTUAL_SLAVE_LEARN_MODE_DISABLE again as quickly as possible. It is recommended that Slave Learn Mode is never set to VIRTUAL_SLAVE_LEARN_MODE_ENABLE for more than 1 second. Defined in: ZW_controller_bridge_api.h + +Return value: + +BYTE TRUE If learnSlaveMode change was succesful. + +FALSE If learnSlaveMode change could not be done. + +Parameters: + +node IN Node ID (1...232) on node to set in Slave Learn Mode, ZERO if new node is to be learned. + +mode IN Valid modes: + +VIRTUAL_SLAVE_LEARN_MODE_DISABLE Disable Slave Learn Mode + +VIRTUAL_SLAVE_LEARN_MODE_ENABLE Enable Slave Learn Mode + +VIRTUAL_SLAVE_LEARN_MODE_ADD ADD: Create locally a Virtual Slave Node and add it to the Z-Wave network (only possible if Primary/Inclusion Controller). + +VIRTUAL_SLAVE_LEARN_MODE_REMOVE Remove locally present Virtual Slave Node from the Z-Wave network (only possible if Primary/Inclusion Controller). + +learnFunc IN Slave Learn mode complete call back function Callback function Parameters: + +bStatus Status of the assign process. + +ASSIGN_COMPLETE Is returned by the callback function when in the VIRTUAL_SLAVE_LEARN_MODE_ENABLE Slave Learn Mode and assignment is done. Now the Application can continue normal operation. + +ASSIGN_NODEID_DONE Node ID have been assigned. The “orgID” contains the node ID on the Virtual Slave Node who was put into Slave Learn Mode. The “newID” contains the new node ID for “orgID”. If “newID” is ZERO then the “orgID” Virtual Slave node has been deleted and the assign operation is completed. When this status is received the Slave Learn Mode is complete for all Slave Learn Modes except the VIRTUAL_SLAVE_LEARN_MODE_ENABLE mode. + +ASSIGN_RANGE_INFO_UPDATE Node is doing Neighbour discovery Application should not attempt to send any frames during this time, this is only applicable when in VIRTUAL_SLAVE_LEARN_MODE_ENABLE. + +orgID The original node ID that was put into Slave Learn Mode. + +newID The new Node ID. Zero if “OrgID” was deleted from the Z-Wave network. + +Serial API: + +HOST->ZW: REQ | 0xA4 | node | mode | funcID + +ZW->HOST: RES | 0xA4 | retVal + +ZW->HOST: REQ | 0xA4 | funcID | bStatus | OrgID | newID + +## 4.6.3 ZW_IsVirtualNode + +BYTE ZW_IsVirtualNode(BYTE nodeID) + +Macro: ZW_IS_VIRTUAL_NODE (nodeid) + +Checks if “nodeID” is a Virtual Slave node. + +Defined in: ZW_controller_bridge_api.h + +Return value: + +BYTE TRUE If “nodeID” is a Virtual Slave node. + +FALSE If “nodeID” is not a Virtual Slave node. + +Parameters: + +nodeID IN Node ID (1...232) on node to check if it is a Virtual Slave node. + +Serial API: + +HOST->ZW: REQ | 0xA6 | nodeID + +ZW->HOST: RES | 0xA6 | retVal + +## 4.6.4 ZW_GetVirtualNodes + +VOID ZW_GetVirtualNodes(BYTE *pnodeMask) + +Macro: ZW_GET_VIRTUAL_NODES (pnodemask) + +Request a buffer containing available Virtual Slave nodes in the Z-Wave network. + +The format of the data returned in the buffer pointed to by pnodeMask is as follows: + +| pnodeMask[i] (0  i < (ZW MAX NODES/8) _ _ | | | | | | | | | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Bit | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | +| NodeID | i*8+1 | i*8+2 | i*8+3 | i*8+4 | i*8+5 | i*8+6 | i*8+7 | i*8+8 | + +If bit n in pnodeMask[i] is 1, it indicates that node (i*8)+n+1 is a Virtual Slave node. If bit n in pnodeMask[i] is 0, it indicates that node (i*8)+n+1 is not a Virtual Slave node. + +Defined in: ZW_controller_bridge_api.h + +Parameters: + +pNodeMask IN Pointer to nodemask (29 byte size) buffer where the Virtual Slave nodeMask should be copied. + +Serial API: + +HOST->ZW: REQ | 0xA5 + +ZW->HOST: RES | 0xA5 | pnodeMask[29] diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.07-z-wave-portable-controller-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.07-z-wave-portable-controller-api.md new file mode 100644 index 0000000..c04e8dd --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.07-z-wave-portable-controller-api.md @@ -0,0 +1,86 @@ + +# 4.7 Z-Wave Portable Controller API + +The Portable application interface is basically an extended Controller interface that gives the application access to functions that can be used to create more advanced installation tools, which provide better diagnostics and error locating capabilities. + +## 4.7.1 zwTransmitCount + +BYTE zwTransmitCount + +Macro: ZW_TX_COUNTER + +ZW_TX_COUNTER is a variable that returns the number of transmits that the protocol has done since last reset of the variable. If the number returned is 255 then the number of transmits ≥ 255. The variable should be reset by the application, when it is to be restarted. + +Defined in: ZW_controller_portable_api.h + +Serial API: + +To read the transmit counter: + +HOST->ZW: REQ | 0x81| (FUNC_ID_GET_TX_COUNTER) + +ZW->HOST: RES | 0x81 | ZW_TX_COUNTER (1 byte) + +To reset the transmit counter: + +HOST->ZW: REQ | 0x82| (FUNC_ID_RESET_TX_COUNTER) + +## 4.7.2 ZW_StoreNodeInfo + +BOOL ZW_StoreNodeInfo( BYTE bNodeID, BYTE_P pNodeInfo, VOID_CALLBACKFUNC(func)()) + +Macro: ZW_STORE_NODE_INFO(NodeID,NodeInfo,function) + +ZW_StoreNodeInfo is a function that can be used to restore protocol node information from a backup or the like. The format of the node info frame should be identical with the format used by ZW_GET_NODE_STATE. + +NOTE: The restored values will not take effect before the Z-Wave module has been reset. + +Defined in: ZW_controller_portable_api.h + +Return value: + +BOOL TRUE If NodeInfo was Stored. + +FALSE If NodeInfo was not Stored. (Illegal NodeId or MemoryWrite failed) + +Parameters: + +bNodeID IN Node ID (1...232) to store information at. + +pNodeInfo IN Pointer to Node Information Frame. + +func IN Callback function. Called when data has been stored. + +Serial API: + +HOST->ZW: REQ | 0x83 | bNodeID | nodeInfo (nodeInfo is a NODEINFO field) | funcID + +ZW->HOST: RES | 0x83 | retVal + +ZW->HOST: REQ| 0x83 | funcID + +## 4.7.3 ZW_StoreHomeID + +void ZW_StoreHomeID(BYTE_P pHomeID, BYTE bNodeID) Macro: ZW_STORE_HOME_ID(pHomeID, NodeID) + +ZW_StoreHomeID is a function that can be used to restore HomeID and NodeID information from a backup. + +NOTE: The restored values will not take effect before the Z-Wave module has been reset. + +Defined in: ZW_controller_portable_api.h + +Parameters: + +pHomeID IN Pointer to HomeID structure to store + +bNodeID IN NodeID to store. + +Serial API: + +HOST->ZW: REQ | 0x84 | pHomeID[0] | pHomeID[1] | pHomeID[2] | pHomeID[3] | bNodeID diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.08-z-wave-slave-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.08-z-wave-slave-api.md new file mode 100644 index 0000000..2b93cc2 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.08-z-wave-slave-api.md @@ -0,0 +1,76 @@ + +# 4.8 Z-Wave Slave API + +The Slave application interface is an extension to the Basis application interface enabling inclusion/exclusion (add/remove) of Routing Slave, and Enhanced 232 Slave nodes. + +## 4.8.1 ZW_SetDefault + +void ZW_SetDefault(void) + +Macros: ZW_SET_DEFAULT + +This function set the slave back to the factory default state. Erase routing information and assigned homeID/nodeID from the external NVM. Finally write a new random home ID to the external NVM. + +Defined in: ZW_slave_api.h + +Serial API: + +HOST->ZW: REQ | 0x42 | funcID + +ZW->HOST: REQ | 0x42 | funcID + +## 4.8.2 ZW_SetLearnMode + +void ZW_SetLearnMode(BYTE mode, VOID_CALLBACKFUNC(learnFunc)(BYTE bStatus, BYTE nodeID) ) + +Macro: ZW_SET_LEARN_MODE(mode, func) + +ZW_SetLearnMode enable or disable home and node ID’s learn mode. Use this function to add a new Slave node to a Z-Wave network or to remove an already added node from the network again. + +The Slave node must identify itself to the including controller node by sending a Node Information Frame (see ZW_SendNodeInformation). + +When learn mode is enabled, the follwong two actions can be performed by the protocol: 1. If the current stored ID's are zero and the assigned ID’s are nonzero, the received ID's will be stored (node was added to the network). 2. If the received ID's are zero the stored ID's will be set to zero (node was removed from the network). + +The learnFunc is called as the "Assign" process progresses. The returned nodeID is the nodes new Node ID. If no "Assign" is received from the including controller the callback function will not be called. It is then up to the application code to switch of Learn mode. Once the assignment process has been started the Callback function may be called more than once. The learn process is not complete before the callback function is called with ASSIGN_COMPLETE. + +NOTE: Learn mode should only be enabled when necessary and disabled again as quickly as possible. It is recommended that learn mode is not enabled for more than 2 seconds in ZW_SET_LEARN_MODE_CLASSIC mode and 5 seconds when in either ZW_SET_LEARN_MODE_NWI or ZW_SET_LEARN_MODE_NWE mode. + +Defined in: ZW_slave_api.h + +Parameters: + +mode IN ZW_SET_LEARN_MODE_CLASSIC Start the learn mode on the slave and only accept being included and excluded in direct range. + +ZW_SET_LEARN_MODE_NWI Start the learn mode on the slave and accept routed inclusion (add). NWI mode must not be used for exclusion (remove). + +ZW_SET_LEARN_MODE_NWE Start the learn mode on the slave and accept routed exclusion (remove). NWE mode must not be used for inclusion (add). + +ZW_SET_LEARN_MODE_DISABLE Stop learn mode on the slave + +learnFunc IN Node ID learn mode completed call back function Callback function Parameters: + +bStatus Status of the assign process + +ASSIGN_COMPLETE Assignment is done and Application can continue normal operation. + +ASSIGN_NODEID_DONE Node ID has been assigned. More information may follow. + +ASSIGN_RANGE_INFO_UPDATE Node is doing Neighbor discovery Application should not attempt to send any frames during this time. + +nodeID The new (learned) Node ID (1...232) + +NOTE: The ASSIGN_COMPLETE callback is not synchronized with the ADD_NODE_STATUS_DONE callback on the including controller. The including controller MAY start sending frames to the included node before the ASSIGN_COMPLETE callback. In that case the included node MAY respond before the ASSIGN_COMPLETE callback arrives. Broadcast frames received before the ASSIGN_COMPLETE callback MUST NOT trigger a response transmission. + +Serial API: + +HOST->ZW: REQ | 0x50 | mode | funcID + +ZW->HOST: RES | TRUE + +ZW->HOST: REQ | 0x50 | funcID | bstatus | nodeID diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.09-z-wave-routing-and-enhanced-232-slave-api.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.09-z-wave-routing-and-enhanced-232-slave-api.md new file mode 100644 index 0000000..0177bc5 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.09-z-wave-routing-and-enhanced-232-slave-api.md @@ -0,0 +1,182 @@ + +# 4.9 Z-Wave Routing and Enhanced 232 Slave API + +The Routing and Enhanced 232 Slave application interface is an extension of the Basis and Slave application interface enabling control of other nodes in the Z-Wave network. + +## 4.9.1 ZW_GetSUCNodeID + +BYTE ZW_GetSUCNodeID(void) + +Macro: ZW_GET_SUC_NODEID() + +API call used to get the currently registered SUC/SIS node ID. A controller must have called ZW_AssignSUCReturnRoute before a SUC/SIS node ID is registered in the routing or enhanced 232 slave. + +Defined in: ZW_slave_routing_api.h + +Return value: + +BYTE The node ID (1..232) on the currently registered SUC/SIS, if ZERO then no SUC/SIS available. + +Serial API: + +HOST->ZW: REQ | 0x56 + +ZW->HOST: RES | 0x56 | SUCNodeID + +## 4.9.2 ZW_IsNodeWithinDirectRange + +BYTE ZW_IsNodeWithinDirectRange(BYTE bNodeID) + +Macro: ZW_IS_NODE_WITHIN_DIRECT_RANGE (bNodeID) + +Check if the supplied nodeID is marked as being within direct range in any of the existing return routes. + +Defined in: ZW_slave_routing_api.h + +Return value: + +TRUE If node is within direct range + +FALSE If the node is beyond direct range or if status is unknown to the protocol + +Parameters: + +bNodeID IN Node id to examine + +Serial API: + +HOST->ZW: REQ | 0x5D | bNodeID + +ZW->HOST: RES | 0x5D | retVal + +## 4.9.3 ZW_RediscoveryNeeded + +BYTE ZW_RediscoveryNeeded (BYTE bNodeID, VOID_CALLBACKFUNC (completedFunc)(BYTE bStatus)) + +Macro: ZW_REDISCOVERY_NEEDED(nodeid, func) + +This function can request a SUC/SIS controller to update the requesting nodes neighbors. The function will try to request a neighbor rediscovery from a SUC/SIS controller in the network. In order to reach a SUC/SIS controller it uses other nodes (bNodeID) in the network. The application must implement the algorithm for scanning the bNodeID’s to find a node which can help. + +If bNodeID supports this functionality (routing slave and enhanced 232 slave libraries), bNodeID will try to contact a SUC/SIS controller on behalf of the node that requests the rediscovery. If the functionality is unsupported by bNodeID ZW_ROUTE_LOST_FAILED will be returned in the callback function and the next node can be tried. + +NOTICE: It is highly recommended to use the transmit option TRANSMIT_OPTION_EXPLORE to enable dynamic route resolution in API calls such as ZW_SendData as an alternative to ZW_RediscoveryNeeded. + +The callback function is called when the request have been processed by the protocol. + +Defined in: ZW_slave_routing_api.h + +Return value: + +FALSE The node is busy doing another update. + +TRUE The help process is started; status will come in the callback. + +Parameters: + +bNodeID IN Node ID (1..232) to request help from + +completedFunc Transmit completed call back function IN Callback function parameters: + +ZW_ROUTE_LOST_ACCEPT The node bNodeID accepts to forward the help request. Wait for the next callback to determine the outcome of the rediscovery. + +ZW_ROUTE_LOST_FAILED The node bNodeID has responded it is unable to help and the application can try next node if it decides so. + +ZW_ROUTE_UPDATE_ABORT No reply was received before the protocol has timed out. The application can try the next node if it decides so. + +ZW_ROUTE_UPDATE_DONE The node bNodeID was able to contact a controller and the routing information has been updated. + +Serial API: + +HOST->ZW: REQ | 0x59 | bNodeID | funcID + +ZW->HOST: RES | 0x59 | retVal + +ZW->HOST: REQ | 0x59 | funcID | bStatus + +## 4.9.4 ZW_RequestNewRouteDestinations + +BYTE ZW_RequestNewRouteDestinations(BYTE *pDestList, BYTE bDestListLen , VOID_CALLBACKFUNC (completedFunc)(BYTE bStatus)) + +Macro: ZW_REQUEST_NEW_ROUTE_DESTINATIONS (pdestList, destListLen, func) + +Used to request new return route destinations from the SUC/SIS node. + +NOTE: No more than the first ZW_MAX_RETURN_ROUTE_DESTINATIONS will be requested regardless of bDestListLen. + +Defined in: ZW_slave_routing_api.h + +Return value: + +TRUE If the updating process is started. + +FALSE If the requesting routing slave is busy or no SUC/SIS node known to the slave. + +Parameters: + +pDestList IN Pointer to a list of new destinations for which return routes is needed. + +bDestListLen IN Number of destinations contained in pDestList. + +completedFunc IN Transmit completed call back function + +Callback function parameters: + +ZW_ROUTE_UPDATE_DONE The update process is ended successfully + +ZW_ROUTE_UPDATE_ABORT The update process aborted because of error + +ZW_ROUTE_UPDATE_WAIT The SUC/SIS node is busy + +ZW_ROUTE_UPDATE_DISABLED The SUC/SIS functionality is disabled + +Serial API: + +HOST->ZW: REQ | 0x5C | destList[5] | funcID + +ZW->HOST: RES | 0x5C | retVal + +ZW->HOST: REQ | 0x5C | funcID | bStatus + +## 4.9.5 ZW_RequestNodeInfo + +BOOL ZW_RequestNodeInfo (BYTE nodeID, VOID (*completedFunc)(BYTE txStatus, TX_STATUS_TYPE* txStatusReport)) + +Macro: ZW_REQUEST_NODE_INFO(NODEID) + +This function is used to request the Node Information Frame from a node in the network. The Node info is retrieved using the ApplicationSlaveUpdate callback function with the status UPDATE_STATE_NODE_INFO_RECEIVED. The ZW_RequestNodeInfo API call is also available for controllers. + +Defined in: ZW_slave_routing_api.h + +Return value: + +BOOL TRUE If the request could be put in the transmit queue successfully. + +FALSE If the request could not be put in the transmit queue. Request failed. + +Parameters: + +nodeID IN The node ID (1…232) of the node to request the Node Information Frame from. + +completedFunc Transmit complete call back. IN + +Callback function Parameters: + +txStatus IN (see ZW_SendData) + +txStatusReport IN (see ZW_SendData) + +Serial API: + +HOST->ZW: REQ | 0x60 | NodeID + +ZW->HOST: RES | 0x60 | retVal + +The Serial API implementation do not return the callback function (no parameter in the Serial API frame refers to the callback), this is done via the ApplicationSlaveUpdate callback function: + + If request nodeinfo transmission was unsuccessful, (no ACK received) then the ApplicationSlaveUpdate is called with UPDATE_STATE_NODE_INFO_REQ_FAILED (status only available in the Serial API implementation).  If request nodeinfo transmission was successful, there is no indication that it went well apart from the returned Nodeinfo frame which should be received via the ApplicationSlaveUpdate with status UPDATE_STATE_NODE_INFO_RECEIVED. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.10-serial-command-line-debugger.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.10-serial-command-line-debugger.md new file mode 100644 index 0000000..5c6839f --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.10-serial-command-line-debugger.md @@ -0,0 +1,78 @@ + +# 4.10 Serial Command Line Debugger + +The debug driver is a simple single line command interpreter, operated via the serial interface (UART – RS232). The command line debugger is used to dump and edit memory, including the memory mapped registers. + +For a controller/slave_enhanced node the debugger startup by displaying the following help text on the debug terminal: + +Z-Wave Commandline debugger Vx.nn Keyes(VT100): BS; ^,<,> arrows; F1. H Help D[X|E|F] [] Dump memory E[X|E] Edit memory (Key: SP) W[X|E|F] Watch memory location is idata (80-FF is SFR) X is xdata E is External EEPROM F is flash> + +For a slave node the debugger startup by displaying the following help text on the debug terminal: + +Z-Wave Commandline debugger Vx.nn Keyes(VT100): BS; ^,<,> arrows; F1. H Help D[X|I|F] [] Dump memory E[X|I] Edit memory (Key: SP) W[X|I|F] Watch memory location is idata (80-FF is SFR) X is xdata I is “Internal EEPROM” flash F is flash> + +The command debugger is then ready to receive commands via the serial interface. Special input keys: + +F1 (function key 1) same as the help command line. + +BS (backspace) delete the character left to the curser. + +< (left arrow) move the cursor one character left. + +> (right arrow) move the cursor one character right. + +^ (up arrow) retrieve last command line. + +Commands: + +H[elp] Display the help text. D[ump] [] Dump idata (0-7F) or SFR memory (80-FF). DX [] Dump xdata (SRAM) memory. DI [] Dump “internal EEPROM” flash (slave only). DE [] Dump external EEPROM (controllers/slave_enhanced only). DF [] Dump FLASH memory. E[dit] Edit idata (0-7F) or SFR memory (80-FF). EX Edit xdata memory. EI Edit “internal EEPROM” flash (slave only). EE Edit external EEPROM (controllers/slave_enhanced only). W[atch] Watch idata (0-7F) or SFR memory (80-FF). WX Watch xdata memory. WI Watch “internal EEPROM” flash (slave only). WE Watch external EEPROM memory (controllers/slave_enhanced only). WF Watch FLASH memory. The Watch pointer gives the following log (when memory change): idata SRAM memory Rnn xdata SRAM memory Xnn Internal EEPROM flash Inn (slave only) External EEPROM Enn (controllers/slave_enhanced only) + +Examples: + +>dx 0; Edit offset 0x0000 and 0x0001 of xdata SRAM 0000 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00>ex 0; Edit offset 0x0000 and 0x0001 of xdata SRAM 0000 00-1 00-2>dx 0; Dump offset 0x0000 to 0x000f of xdata SRAM 0000 01 02 00 00 00 00 00 00 00 00 00 00 00 00 00 00>wx 1X02; Watch offset 0x0001 of xdata SRAM>ex 1 0001 02-1X01> + +## 4.10.1 ZW_DebugInit + +void ZW_DebugInit(WORD baudRate) + +Macro: ZW_DEBUG_CMD_INIT(baud) + +Command line debugger initialization. The macro can be placed within the application initialization function (see function ApplicationInitSW). + +Example: + +ZW_DEBUG_CMD_INIT(96); /* setup command line speed to 9600 bps. */ + +Defined in: ZW_debug_api.h + +Parameters: + +baudRate IN Baud Rate / 100 (e.g. 96 = 9600 bps, 384 = 38400 bps, 1152 = 115200 bps) + +Serial API (Not supported) + +## 4.10.2 ZW_DebugPoll + +void ZW_DebugPoll( void ) + +Macro: ZW_DEBUG_CMD_POLL + +Command line debugger poll function. Collect characters from the debug terminal and execute the commands. + +Should be called via the main poll loop (see function ApplicationPoll). + +By using the debug macros (ZW_DEBUG_CMD_INIT, ZW_DEBUG_CMD_POLL) the command line debugger can be enabled by defining the compile flag “ZW_DEBUG_CMD” under CDEFINES in the makefile as follows: + +CDEFINES+= EU,\ ZW_DEBUG_CMD,\ SUC_SUPPORT,\ ASSOCIATION,\ LOW_FOR_ON,\ SIMPLELED + +Both the debug output (ZW_DEBUG) and the command line debugger (ZW_DEBUG_CMD) can be enabled at the same time. + +Defined in: ZW_debug_api.h + +Serial API (Not supported) diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.11-rf-settings-in-app_rfsetupc-file.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.11-rf-settings-in-app_rfsetupc-file.md new file mode 100644 index 0000000..0d83357 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/04.11-rf-settings-in-app_rfsetupc-file.md @@ -0,0 +1,27 @@ + +# 4.11 RF Settings in App_RFSetup.c file + +The RF normal and low power transmit levels are set by the module APP_RFSETUP in the Z-Wave library. + +Table 27. App_RFSetup.c Module Definitions for 500 Series Z-Wave SoC + +| Offset to table start | _ Define name | Default value | Description | +| --- | --- | --- | --- | +| 2 | FLASH APPL NORM POWER OFFS 0 _ _ _ _ _ FLASH APPL NORM POWER OFFS 1 _ _ _ _ _ FLASH APPL NORM POWER OFFS 2 _ _ _ _ _ | 0xFF | If 0xFF the default lib value is used: 0x3F | +| 5 | FLASH APPL LOW POWER OFFS 0 _ _ _ _ _ FLASH APPL LOW POWER OFFS 1 _ _ _ _ _ FLASH APPL LOW POWER OFFS 2 _ _ _ _ _ | 0xFF | If 0xFF the default lib value is used:0x04 | + +TXnormal Power need maybe adjustment to fulfil FCC compliance tests. According to the FCC part 15, the output-radiated power will not exceed 94dBuV/m. This radiated power is the result of the module output power and your product antenna gain. As the antenna gain is different from product to product, the module output power needs to be adjusted to comply with the FCC regulations. + +[Use the Z-Wave Programmer [13] to find the RF power transmit levels to fulfil FCC compliance tests. The](../08-references.md#8-references) entered RF power transmit levels overrule the ones defined in the App_RFSetup.c file. Update the App_RFSetup.c file with the determined RF power transmit levels and build a new hex file containing the final RF power transmit levels. + +Make a copy of the template file …\Z-Wave\IO_defines\App_RFSetup.c, and place it in your application’s directory, and fill in your final RF power transmit levels and build a new hex file containing the final RF power transmit levels. The App_RFSetup.c file in your application directory will override the one from the library. + +An alternative way is to use the file …\Z-Wave\IO_defines\App_RFSetup.c directly to override the RF normal and low power transmit levels from the Z-Wave library. Then you must set: APP_RFSETUP_FILE:=App_RFSetup.obj in your application’s Makefile somewhere before the inclusion of include $(ZWUTILDIR)\Makefile.common (during the setup of the build environment). + +Notice that the RF power transmit levels set by the Z-Wave Programmer are erased after a OTA or OTW firmware update. The Z-Wave Programmer must therefore not be used to set the RF power transmit levels on the production line. diff --git a/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/index.md b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/index.md new file mode 100644 index 0000000..ed39d17 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/04-z-wave-application-interfaces/index.md @@ -0,0 +1,24 @@ + +# 4 Z-Wave Application Interfaces + +The Z-Wave basis software consists of a number of different modules. Time critical functions are written in assembler while the other Z-Wave modules are written in C. The Z-Wave API consists of a number of C functions which give the application programmer direct access to the Z-Wave functionality. + +## Contents + +- [4.1 API Usage Guidelines](04.01-api-usage-guidelines.md) +- [4.2 Z-Wave Libraries](04.02-z-wave-libraries.md) +- [4.3 Z-Wave Common API](04.03-z-wave-common-api/index.md) +- [4.4 Z-Wave Controller API](04.04-z-wave-controller-api/index.md) +- [4.5 Z-Wave Static Controller API](04.05-z-wave-static-controller-api.md) +- [4.6 Z-Wave Bridge Controller API](04.06-z-wave-bridge-controller-api.md) +- [4.7 Z-Wave Portable Controller API](04.07-z-wave-portable-controller-api.md) +- [4.8 Z-Wave Slave API](04.08-z-wave-slave-api.md) +- [4.9 Z-Wave Routing and Enhanced 232 Slave API](04.09-z-wave-routing-and-enhanced-232-slave-api.md) +- [4.10 Serial Command Line Debugger](04.10-serial-command-line-debugger.md) +- [4.11 RF Settings in App_RFSetup.c file](04.11-rf-settings-in-app_rfsetupc-file.md) diff --git a/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.01-implementing-sucsis-support-in-all-nodes.md b/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.01-implementing-sucsis-support-in-all-nodes.md new file mode 100644 index 0000000..89b2da4 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.01-implementing-sucsis-support-in-all-nodes.md @@ -0,0 +1,10 @@ + +# 5.1 Implementing SUC/SIS Support in all Nodes + +Having Static ID Server (SIS) support in Z-Wave products requires that several API calls must be used in the right order. This chapter provides details about how SUC/SIS support can be implemented in the different node types in the Z-Wave network. diff --git a/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.02-static-controllers.md b/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.02-static-controllers.md new file mode 100644 index 0000000..8b33cf3 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.02-static-controllers.md @@ -0,0 +1,38 @@ + +# 5.2 Static Controllers + +All static controllers has the functionality needed for acting as a SUC/SIS in the network, By default all static controllers has the SUC/SIS functionality enabled A Static Controller will not act as a SUC/SIS until the primary controller in the network has requested it to do so. Or the application on the static controller has forced the controller to become SUC/SIS + +## 5.2.1 Request for Becoming an SUC Node ID Server (SIS) + +The static controller will accept to become SUC/SIS if/when the primary controller request it by calling ZW_SetSUCNodeID() with the Static controllers node ID, or the application on the static controller has forced the controller to become SUC/SIS by calling ZW_SetSUCNodeID() with its own node ID. + +There can only be one SUC/SIS in a network. + +NOTE: There can only be one SUC/SIS in a network, but there can be many static controllers that are enabled for an assignment of the SIS capabilities in a network. + +## 5.2.2 Updates from the Primary Controller + +1 + +Figure 43. Inclusion (Add) of a Node Having an SUC in the Network + +When a new node is added to the network or an existing node is removed from the network the inclusion controller will send a network update to the SUC/SIS to notify about the changes in the network. The application in the SUC/SIS will be notified about such a change through the callback function ApplicationControllerUpdate). All update of node lists and routing tables is handled by the protocol so the call is just to notify the application in the static controller that a node has been added or removed. + +## 5.2.3 Assigning SUC Routes to Routing Slaves + +When the SUC/SIS is present in a Z-Wave network routing slaves can ask it for updates, but the routing slave must first be told that there is a SUC/SIS in the network and it must be told how to reach it. That is done from the SUC/SIS by assigning a set of return routes to the routing slave so it knows how to reach the SUC/SIS. Assigning the routes to routing slaves is done by calling ZW_AssignSUCReturnRoute with the nodeID of the routing slave that should be configured. + +NOTE: Routing slaves are notified by the presence of a SUC/SIS as a part of the inclusion (add),but it is good practice to have the application on the SUC/SIS assign SUC/SIS return routes to new nodes so they have a full set of updated return routes. + +## 5.2.4 Receiving Requests for Network Updates + +When a SUC/SIS receives a request for sending network updates to a secondary controller or a routing slave, the protocol will handle all the communication needed for sending the update, so the application doesn't need to do anything and it will not get any notifications about the request. + +The SUC/SIS will also receive requests for reserving node Ids for use when other controllers add nodes to the network. The protocol will handle all that communication without any involvement from the application. diff --git a/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.03-the-primary-controller.md b/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.03-the-primary-controller.md new file mode 100644 index 0000000..fee4d8c --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.03-the-primary-controller.md @@ -0,0 +1,14 @@ + +# 5.3 The Primary Controller + +The primary controller is responsible for choosing what static controller in the network that should act as a SUC/SIS. The application in a primary controller is responsible for choosing the static controller that should be the SUC/SIS. There is no fixed strategy for how to choose the static controller, so it is entirely up to the application to choose the controller that should become SUC/SIS. Once a static controller has been selected the application must use the ZW_SetSUCNodeID to request that the static controller becomes SUC/SIS. + +Once a SUC/SIS has been selected, the protocol in the primary controller will automatically send notifications to the SUC/SIS about all changes in the network topology. + +NOTE: A controller can decline the role as SUC/SIS and in that case, the callback function from ZW_SetSUCNodeID will return with a FAILED status. The static controller (legacy controller) can also refuse to become SIS if that was what the primary controller requested, but accept to become a SUC. diff --git a/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.04-secondary-controllers.md b/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.04-secondary-controllers.md new file mode 100644 index 0000000..87e0fbe --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.04-secondary-controllers.md @@ -0,0 +1,26 @@ + +# 5.4 Secondary Controllers + +All controllers in a network containing a SUC/SIS can ask it for network topology changes and receive the updates from the SUC/SIS. It is entirely up to the application if and when an update is needed. + +Figure 44. Requesting Network Updates from a SUC/SIS in the Network + +## 5.4.1 Knowing the SUC/SIS + +The first thing the secondary controller should check is if it knows a SUC at all. Checking if a SUC is known by the controller is done with the ZW_GetSUCNodeID call and until this call returns a valid node ID the secondary controller can’t use the SUC. The only time a secondary controller gets information about the presence of a SUC is during controller replication, so it is only necessary to check after a successful controller replication. + +## 5.4.2 Asking for and Receiving Updates + +If a controller knows the SUC/SIS, it can ask for updates from the SUC/SIS. Asking for updates is done using the ZW_RequestNetWorkUpdate function. If the call was successful the update process will start and the controller application will be notified about any changes in the network through calls to ApplicationControllerUpdate). Once the update process is completed, the callback function provided in ZW_RequestNetWorkUpdate will be called. + +If the callback functions returns with the status ZW_SUC_UPDATE_OVERFLOW then it means that there has been more that 64 changes made to the network since the last update of this secondary controller and it is therefore necessary to do a controller replication (copy) to get this controller updated. + +NOTE: The SUC/SIS can refuse to update the controller for several reasons, and if that happens the callback function will return with a value explaining why the update request was refused. + +WARNING: Consider carefully how often the topology of the network changes and how important it is for the application that the secondary controller is updated with the latest. diff --git a/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.05-inclusion-controllers.md b/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.05-inclusion-controllers.md new file mode 100644 index 0000000..3d0eb70 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.05-inclusion-controllers.md @@ -0,0 +1,12 @@ + +# 5.5 Inclusion Controllers + +When a SIS is present in a Z-Wave network then all the controllers that knows the SIS will change state to Inclusion Controllers, and the concept of primary and secondary controllers will no longer apply for the [controllers. The Inclusion controllers has the functionality of a Secondary Controller so the functionality described in section 5.4 also applies for secondary controllers, but Inclusion Controllers are also able to](05.03-the-primary-controller.md#53-the-primary-controller) include/exclude nodes to the network on behalf of the SIS. The application in a controller can check if a SIS is present in the network by using the ZW_GetControllerCapabilities function call. This allows the application to adjust the user interface according to the capabilities. If a SIS is present in the network then the CONTROLLER_NODEID_SERVER_PRESENT bit will be set and the CONTROLLER_IS_SECONDARY bit will not be set. + +Figure 45. Inclusion (Add) of a Node Having a SIS in the Network diff --git a/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.06-routing-slaves.md b/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.06-routing-slaves.md new file mode 100644 index 0000000..8ea7116 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/05.06-routing-slaves.md @@ -0,0 +1,16 @@ + +# 5.6 Routing Slaves + +The routing slave can request a update of its stored return routes from a SUC/SIS by using the ZW_RequestNetWorkUpdate API call. There is no API call in the routing slave to check if the SUC/SIS is known by the slave so the application must just try ZW_RequestNetWorkUpdate and then determine from the return value if the SUC/SIS is known or not. If the SUC/SIS was known and the update was a success then the routing slave would get a callback with the status SUC_UPDATE_DONE, the slave will not get any notifications about what was changed in the network. + +A SUC/SIS can help a battery-operated routing slave to be re-discovered in case it is moved to a new location. The lost slave initiates the dynamic route resolution process because it will be the first to recognize that it is unable to reach the configured destinations. + +The lost battery operated routing slave start to send “I’m lost” frames to each node beginning with node ID = 1. It continues until it find a routing slave which can help it, i.e., the helping routing slave can obtain contact with a SUC/SIS. Scanning through the node ID’s is done on application level. Other strategies to send the “I’m lost” frame can be implemented on the application level. Figure 46. Lost Routing Slave Frame Flow + +The helping routing slave must maximum use three hops to get to the controller, because it is the fourth hop when the controller issues the re-discovery to the lost routing slave. All handling in the helping slave is implemented on protocol level. In case a primary controller is found then it will check if a SUC/SIS exists in the network. In case a SUC/SIS is available, it will be asked to execute the re-discovery procedure. When the controller receive the request “Re-discovery node ID x” it update the routing table with the new neighbor information. This allows the controller to execute a normal re-discovery procedure. diff --git a/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/index.md b/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/index.md new file mode 100644 index 0000000..39e72a0 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/05-application-note-sucsis-implementation/index.md @@ -0,0 +1,17 @@ + +# 5 Application Note: SUC/SIS Implementation + +## Contents + +- [5.1 Implementing SUC/SIS Support in all Nodes](05.01-implementing-sucsis-support-in-all-nodes.md) +- [5.2 Static Controllers](05.02-static-controllers.md) +- [5.3 The Primary Controller](05.03-the-primary-controller.md) +- [5.4 Secondary Controllers](05.04-secondary-controllers.md) +- [5.5 Inclusion Controllers](05.05-inclusion-controllers.md) +- [5.6 Routing Slaves](05.06-routing-slaves.md) diff --git a/docs/specs/zwave-500-series-programmers-guide/06-application-note-controller-shift-implementation.md b/docs/specs/zwave-500-series-programmers-guide/06-application-note-controller-shift-implementation.md new file mode 100644 index 0000000..c26579a --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/06-application-note-controller-shift-implementation.md @@ -0,0 +1,14 @@ + +# 6 Application Note: Controller Shift Implementation + +This note describes how a controller is able to include a new controller that after the inclusion (add) will become the primary controller in the network. The controller that is taking over the primary functionality should just enter learn mode like when it is to be included in a network. The existing primary controller makes the controller change by calling ZW_ControllerChange (CONTROLLER_CHANGE_START,..). ) + +After a successfull change, the controller that called ZW_ControllerChange will be secondary and no longer able to include devices. + +Figure 47. Controller Shift Frame Flow diff --git a/docs/specs/zwave-500-series-programmers-guide/07-application-note-z-wave-protocol-versions-etc.md b/docs/specs/zwave-500-series-programmers-guide/07-application-note-z-wave-protocol-versions-etc.md new file mode 100644 index 0000000..9076cf8 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/07-application-note-z-wave-protocol-versions-etc.md @@ -0,0 +1,111 @@ + +# 7 Application Note: Z-Wave Protocol Versions etc + +[The below table lists existing Z-Wave Protocol versions etc. for a given Software Developer’s Kit version . The Version Command Class [6] returns the version of Z-Wave Protocol and Z-Wave Plus Framework & Embedded Apps. Refer to [2] regarding retrieving version of Serial API interface.](08-references.md#8-references) + +| Software Developer’s Kit Version | Z-Wave Protocol & serial API Apps Version | Z-Wave Plus Framework & Certified Apps Version | Serial API Interface Version | +| --- | --- | --- | --- | +| 6.82.01 | 6.09.00 & 6.09 | 4.04.01 & 4.04 | 8 | +| 6.82.00 | 6.08.00 & 6.08 | 4.04.00 & 4.04 | 8 | +| 6.81.06 | 6.07.00 & 6.07 | 4.03.00 & 4.03 | 8 | +| 6.81.05 | 6.06.00 & 6.06 | 4.02.00 & 4.02 | 8 | +| 6.81.04 | 6.05.00 & 6.05 | 4.01.03 & 4.01 | 8 | +| 6.81.03 | 6.04.00 & 6.04 | 4.01.02 & 4.01 | 8 | +| 6.81.02 | 6.03.00 & 6.01 | 4.01.02 & 4.01 | 8 | +| 6.81.01 | 6.02.00 & 6.01 | 4.01.01 & 4.01 | 8 | +| 6.81.00 | 6.01.00 & 5.14 | 4.01.00 & 4.01 | 8 | +| 6.80.00 Beta | 6.01.00 & 5.14 | 4.01.00 & 4.01 | 8 | +| 6.71.03 | 5.03.00 & 5.50 | 3.01.01 & 3.01 | 7 | +| 6.71.02 | 5.02.00 & 3.01 | 3.01.00 & 3.01 | 7 | +| 6.71.01 | 4.61 & 5.34 | - | 7 | +| 6.71.00 | 4.60 & 5.29 | - | 7 | +| 6.70.01 Beta | 4.45 & 5.19 | - | 6 | +| 6.70.00 Beta | 4.28 & 5.05 | - | 6 | +| 6.61.01 | 4.62 & 5.36 | - | 6 | +| 6.61.00 | 4.33 & 5.10 | - | 6 | +| 6.60.00 Beta | 4.12 & 1.12 | - | 6 | +| 6.51.10 | 4.54 | - | 5 | +| 6.51.09 | 4.38 | - | 5 | +| 6.51.08 | 4.34 | - | 5 | +| 6.51.07 | 4.24 | - | 5 | +| 6.51.06 | 4.05 | - | 5 | +| 6.51.04 | 4.01 | - | 5 | +| 6.51.03 | 3.99 | - | 5 | +| 6.51.02 | 3.95 | - | 5 | +| 6.51.01 | 3.92 | - | 5 | +| 6.51.00 | 3.83 | - | 5 | +| 6.50.01 | 3.79 | - | 5 | +| 6.50.00 | 3.71 | - | 5 | +| 6.11.01 (JP) | 3.53 | - | 5 | +| 6.11.00 (JP) | 3.45 | - | 5 | +| 6.10.01 (JP) | 3.38 | - | 5 | +| 6.10.00 | 3.35 | - | 5 | +| 6.02.00 | 3.41 | - | 5 | +| 6.01.03 | 3.37 | - | 5 | +| 6.01.02 | 3.33 | - | 5 | +| 6.01.01 (2-ch) | 3.26 | - | 5 | +| 6.01.00 | 3.10 | - | 5 | +| 6.00.05 Beta 1 | 3.07 | - | 5 | +| 6.00.04 Beta 1 | 3.06 | - | 5 | +| 6.00 Beta 1 Patch 3 | 3.04 | - | 5 | +| 6.00 Beta 1 Patch 2 | 3.03 | - | 5 | + +| 6.00 Beta 1 Patch 1 | 2.99 | - | 5 | +| --- | --- | --- | --- | +| 6.00 Beta 1 | 2.96 | - | 5 | +| 5.03.00 | 3.28 | - | 5 | +| 5.02 Patch 3 | 2.78 | - | 5 | +| 5.02 Patch 2 | 2.64 | - | 5 | +| 5.02 Patch 1 | 2.51 | - | 5 | +| 5.02 | 2.48 | - | 5 | +| 5.01 | 2.36 | - | 5 | +| 5.00 Beta 1 Patch 1 | 2.22 | - | 5 | +| 5.00 Beta 1 | 2.16 | - | 5 | +| 4.55.00 | 3.67 | - | 5 | +| 4.54.02 | 3.52 | - | 5 | +| 4.54.01 | 3.42 | - | 5 | +| 4.54.00 | 3.40 | - | 5 | +| 4.53.01 | 3.36 | - | 5 | +| 4.53.00 | 3.34 | - | 5 | +| 4.52.01 | 3.22 | - | 5 | +| 4.52.00 | 3.20 | - | 5 | +| 4.51 | 2.97 | - | 5 | +| 4.50 Beta 1 Patch 1 | 2.79 | - | | +| 4.50 Beta 1 | 2.74 | - | | +| 4.30 Beta 1 | 2.30 | - | | +| 4.28 | 2.67 | - | | +| 4.27 | 2.40 | - | | +| 4.26 | 2.32 | - | | +| 4.25 | 2.31 | - | | +| 4.24 Patch 1 | 2.28 | - | | +| 4.24 | 2.24 | - | | +| 4.23 | 2.17 | - | | +| 4.22 | 2.09 | - | | +| 4.21 | 2.06 | - | | +| 4.20 | 1.97 | - | | +| 4.11 | 1.91 | - | | +| 4.10 | 1.78 | - | | +| 4.07 | 2.27 | - | | +| 4.06 | 2.23 | - | | +| 4.05 | 2.07 | - | | +| 4.04 | 1.99 | - | | +| 4.03 | 1.81 | - | | +| 4.02 | 1.69 | - | | +| 4.01 | 1.68 | - | | +| 4.00 | 1.59 | - | | +| 3.40 | 1.53 | - | | +| 3.31 | 1.44 | - | | +| 3.30 | 1.37 | - | | +| 3.22 | 1.39 | - | | +| 3.21 | 1.25 | - | | +| 3.20 | 1.21 | - | | + +Table 28, Z-Wave Protocol Version for a Given Software Developer’s Kit Version + +Warning: Products can only be Z-Wave certified based on matured versions of the Z-Wave Protocol, i.e., SDKs having versions different from x.y0 or x.y0.zz. diff --git a/docs/specs/zwave-500-series-programmers-guide/08-references.md b/docs/specs/zwave-500-series-programmers-guide/08-references.md new file mode 100644 index 0000000..917d897 --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/08-references.md @@ -0,0 +1,100 @@ + +# 8 References + +[1] SD, SDS10242, Software Design Specification, Z-Wave Device Class Specification. [2] SD, INS12350, Instruction, Serial API Host Appl. Prg. Guide. [3] SD, INS11681, Instruction, 500 Series Z-Wave Chip Programming Mode. [4] SD, SDS11846, Software Design Specification, Z-Wave Plus Role Type Specification. [5] SD, SDS11847, Software Design Specification, Z-Wave Plus Device Type Specification. [6] SD, SDS10242, Software Design Specification, Z-Wave Device Class Specification. [7] SD, SDS10865, Software Design Specification, Z-Wave Security Application Layer. [8] SD, SDS13781, Software Design Specification, Z-Wave Application Command Class Specification. [9] SD, SDS13782, Software Design Specification, Z-Wave Management Command Class Specification. [10] SD, SDS13783, Software Design Specification, Z-Wave Transport-Encapsulation Command Class Specification. [11] SD, SDS13784, Software Design Specification, Z-Wave Network-Protocol Command Class Specification. [12] SD, SDS13548, Software Design Specification, List of defined Z-Wave Command Classes. [13] SD, INS10679, Instruction, Z-Wave Programmer User Guide. [14] SD, INS12366, Instruction, Working in 500 Series Environment User Guide. [15] SD, APL12665, Application Note, Battery Powered Applications Using 500 Series Z-Wave Single Chip. [16] SD, APL12678, Application Note, 500 Series Z-Wave Single Chip ADC. [17] [IETF RFC 2119, Key words for use in RFC’s to Indicate Requirement Levels, http://tools.ietf.org/pdf/rfc2119.pdf.](http://tools.ietf.org/pdf/rfc2119.pdf) [18] SD, INS13933, Instruction, Z-Wave 500 SDK Contents Kit v6.8x.0x. [19] SD, APL12304, Application Note, ZM4125C with External RF Front-End. [20] SD, INS13114, Instruction, PC Based Controller v5 User Guide. [21] SD, INS12213, Instruction, 500 Series Integration Guide. [22] SD, SDS12467, Software Design Specification, 500 Series Z-Wave Chip NVR Flash Page Contents. INDEX + +A + +APPL_NODEPARM_MAX...................................................................................................................39, 52 ApplicationSecureCommandsSupported (Only slave libraries).................................................................52 ApplicationSecurityEvent(Only slave libraries) ..........................................................................................53 Auto Program Mode.................................................................................................................................334 + +C + +Critical memory........................................................................................................................................171 + +E + +EXT1........................................................................................................................................................171 + +O + +OTW ........................................................................................................................................................126 Over The Wire .........................................................................................................................................126 + +P + +Power down modes .................................................................................................................................171 + +R + +Response routes..........................................................................................................................................6 + +S + +SD3502....................................................................................................................................................217 SIS.............................................................................................................................................................66 Software Developer’s Kit version.............................................................................................................434 Stop mode ...............................................................................................................................................171 SUC ...........................................................................................................................................................66 + +W + +WUT mode...............................................................................................................................................171 + +Z + +ZM5101....................................................................................................................................................217 ZM5202....................................................................................................................................................217 ZW_CreateCrc16.....................................................................................................................................336 ZW_FirmwareUpdate_NVM_Get_NEWIMAGE.......................................................................................129 ZW_FirmwareUpdate_NVM_Init..............................................................................................................127 ZW_FirmwareUpdate_NVM_isValidCRC16 ............................................................................................131 ZW_FirmwareUpdate_NVM_Set_NEWIMAGE .......................................................................................128 ZW_FirmwareUpdate_NVM_UpdateCRC16 ...........................................................................................130 ZW_FirmwareUpdate_NVM_Write ..........................................................................................................132 ZW_GetDefaultPowerLevels ...................................................................................................................124 ZW_GetSecurityS2PublicDSK(Only slave libraries)................................................................................264 ZW_InitSerialIf .........................................................................................................................................324 ZW_IR_learn_status_get.........................................................................................................................312 ZW_s2_inclusion_init(Only slave libraries)..............................................................................................262 ZW_SendDataEx (Only slave libraries) ...................................................................................................101 ZW_SendDataMultiEx (Only slave libraries)............................................................................................113 ZW_SerialCheck......................................................................................................................................326 ZW_SerialGetByte...................................................................................................................................327 ZW_SerialPutByte ...................................................................................................................................328 ZW_SetDefaultPowerLevels....................................................................................................................125 ZW_SetSecurityS0NetworkKey (Only enhanced 232 slave library) ........................................................266 ZW_SetSecurityS2CriticalNodeID (Only routing slave library) ................................................................264 ZW_SetSecurityS2InclusionPublicDSK_CSA(Only slave libraries).........................................................263 ZW_TIMER0_ENABLE / ZW_TIMER1_ENABLE (Macro) ......................................................................238 ZW_TIMER0_ext_clk / ZW_TIMER1_ext_clk..........................................................................................239 ZW_TIMER0_HIGHBYTE_GET / ZW_TIMER1_HIGHBYTE_GET (Macro) ...........................................242 ZW_TIMER0_HIGHBYTE_SET / ZW_TIMER1_HIGHBYTE_SET (Macro)............................................241 ZW_TIMER0_init (Macro)........................................................................................................................234 ZW_TIMER0_INT_CLEAR / ZW_TIMER1_INT_CLEAR (Macro) ...........................................................236 ZW_TIMER0_INT_ENABLE / ZW_TIMER1_INT_ENABLE (Macro).......................................................237 ZW_TIMER0_LOWBYTE_GET / ZW_TIMER1_LOWBYTE_GET (Macro)............................................243 ZW_TIMER0_LOWBYTE_SET / ZW_TIMER1_LOWBYTE_SET (Macro)..............................................240 ZW_TIMER0_word_get / ZW_TIMER1_word_get...................................................................................244 ZW_TIMER1_init (Macro)........................................................................................................................235 ZW_Transport_CommandClassVersionGet ............................................................................................123 + +A + +App_RFSetup.c .......................................................................................................................................427 Application area in non volatile memory..................................................................................................148 Application Priority Route ............................................................................................................................6 ApplicationCommandHandler (Not Bridge Controller library) ....................................................................34 ApplicationCommandHandler_Bridge (Only bridge controller library) .......................................................44 ApplicationControllerUpdate........................................................................................22, 66, 389, 428, 430 ApplicationControllerUpdate (Only controller libraries)..............................................................................42 ApplicationInitHW ......................................................................................................................................28 ApplicationInitSW.......................................................................................................................................29 ApplicationNodeInformation.......................................................................................................................37 ApplicationPoll ...........................................................................................................................................32 ApplicationRfNotify ....................................................................................................................................49 ApplicationSecureAuthenticationRequested (Only slave libraries)............................................................51 ApplicationSecureKeysRequested (Only slave libraries)...........................................................................50 ApplicationSlaveNodeInformation (Only bridge controller library) .............................................................46 ApplicationSlaveUpdate...........................................................................................................................422 ApplicationSlaveUpdate (Only slave libraries)...........................................................................................41 ApplicationTestPoll ....................................................................................................................................31 + +E + +Enhanced 232 Slave................................................................................................................................354 External NVM.............................................................................................................................................12 External NVM.............................................................................................................................................23 + +F + +Far keyword.............................................................................................................................................148 FCC compliance test ...............................................................................................................................427 FLASH_APPL_LOW_POWER_OFFS_x.................................................................................................426 FLASH_APPL_NORM_POWER_OFFS_x..............................................................................................426 funcID ........................................................................................................................................................67 + +G + +GPTimer ....................................................................................................................................................10 I + +Inclusion controller.............................................................................................................................22, 430 Interrupt .....................................................................................................................................................10 Interrupt service routines ...........................................................................................................................10 + +L + +Last Working Route .....................................................................................................................................6 Listening flag..............................................................................................................................................37 + +M + +MemoryGetBuffer ....................................................................................................................................152 MemoryGetByte.......................................................................................................................................150 MemoryGetID ..........................................................................................................................................149 MemoryPutBuffer.....................................................................................................................................153 MemoryPutByte .......................................................................................................................................151 + +N + +Next to Last Working Route.........................................................................................................................6 Node Information Frame....................................................................................................................37, 367 NVM_ext_read_long_buffer.....................................................................................................................161 NVM_ext_read_long_byte .......................................................................................................................159 NVM_ext_write_long_buffer ....................................................................................................................162 NVM_ext_write_long_byte.......................................................................................................................160 NVM_get_id.............................................................................................................................................158 + +P + +PIN_GET .................................................................................................................................................147 PIN_HIGH................................................................................................................................................145 PIN_IN .....................................................................................................................................................143 PIN_LOW.................................................................................................................................................144 PIN_OUT .................................................................................................................................................142 PIN_TOGGLE..........................................................................................................................................146 Primary controller.........................................................................................................................14, 22, 428 Priority Route...........................................................................................................................................366 Production test...........................................................................................................................................31 + +R + +Random number generator........................................................................................................................59 Return route...............................................................................................................................................93 RF low power transmit levels...................................................................................................................427 RF normal power transmit levels .............................................................................................................427 Routing slave...........................................................................................................................................431 Routing Slave ..........................................................................................................................................354 + +S + +SerialAPI_ApplicationNodeInformation......................................................................................................39 SerialAPI_ApplicationSlaveNodeInformation.............................................................................................46 SIS.....................................................................................................................................................26, 430 Source routing .............................................................................................................................................5 Static ID Server........................................................................................................................................428 Static update controller..............................................................................................................................22 Stop mode ...............................................................................................................................................172 SUC ID Server.....................................................................................................................................22, 26 SUC/SIS node .........................................................................................................................................354 + +T + +Timer 0.......................................................................................................................................................10 Timer 1.......................................................................................................................................................10 TimerCancel ............................................................................................................................................166 TimerRestart............................................................................................................................................165 TimerStart................................................................................................................................................164 TRANSMIT_OPTION_EXPLORE............................................................................................................108 TXnormal Power......................................................................................................................................427 + +W + +Watchdog...................................................................................................................................................80 Wut fast mode..........................................................................................................................................172 Wut mode ................................................................................................................................................172 + +Z + +ZW_ GetBackgroundRSSI.........................................................................................................................56 ZW_ Power_Management_Init ..................................................................................................................87 ZW_ADC_auto_zero_set.........................................................................................................................212 ZW_ADC_buffer_enable..........................................................................................................................211 ZW_ADC_enable.....................................................................................................................................203 ZW_ADC_init...........................................................................................................................................199 ZW_ADC_int_clear..................................................................................................................................208 ZW_ADC_int_enable...............................................................................................................................207 ZW_ADC_is_fired....................................................................................................................................209 ZW_ADC_pin_select ...............................................................................................................................204 ZW_ADC_power_enable.........................................................................................................................202 ZW_ADC_resolution_set .........................................................................................................................213 ZW_ADC_result_get................................................................................................................................210 ZW_ADC_threshold_mode_set...............................................................................................................205 ZW_ADC_threshold_set..........................................................................................................................206 ZW_ADD_NODE_TO_NETWORK (Macro) ....................................................................................337, 349 ZW_AddNodeToNetwork.................................................................................................................337, 349 ZW_AES_active_get................................................................................................................................273 ZW_AES_ecb ..........................................................................................................................................277 ZW_AES_ecb_dma .................................................................................................................................277 ZW_AES_ecb_get ...................................................................................................................................270 ZW_AES_ecb_set ...................................................................................................................................269 ZW_AES_enable .....................................................................................................................................271 ZW_AES_int_clear ..................................................................................................................................276 ZW_AES_int_enable ...............................................................................................................................274 ZW_AES_int_get .....................................................................................................................................275 ZW_AES_swap_data...............................................................................................................................272 ZW_ARE_NODES_NEIGHBOURS(Macro) ............................................................................................351 ZW_AreNodesNeighbours.......................................................................................................................351 ZW_ASSIGN_RETURN_ROUTE (Macro)...............................................................................................352 ZW_ASSIGN_SUC_RETURN_ROUTE (Macro).....................................................................................354 ZW_AssignPriorityReturnRoute...............................................................................................................355 ZW_AssignPrioritySUCReturnRoute .......................................................................................................357 ZW_AssignReturnRoute..........................................................................................................................352 ZW_AssignSUCReturnRoute ..................................................................................................................354 ZW_CheckCrc16 .....................................................................................................................................335 ZW_ClearNetworkStats .............................................................................................................................86 ZW_ClearTxTimers....................................................................................................................................84 ZW_CONTROLLER_CHANGE (Macro)..................................................................................................359 ZW_ControllerChange.....................................................................................................................359, 433 ZW_CREATE_NEW_PRIMARY_CTRL (Macro).....................................................................................401 ZW_CreateNewPrimaryCtrl .....................................................................................................................401 ZW_DEBUG_CMD_INIT (Macro)............................................................................................................425 ZW_DEBUG_CMD_POLL (Macro)..........................................................................................................426 ZW_DebugInit..........................................................................................................................................425 ZW_DebugPoll.........................................................................................................................................426 ZW_DELETE_RETURN_ROUTE (Macro) ..............................................................................................361 ZW_DELETE_SUC_RETURN_ROUTE (Macro).....................................................................................362 ZW_DeleteReturnRoute ..........................................................................................................................361 ZW_DeleteSUCReturnRoute...................................................................................................................362 ZW_EEPROM_INIT (Macro) ...................................................................................................................154 ZW_EepromInit........................................................................................................................................154 ZW_ExploreRequestExclusion ..................................................................................................................55 ZW_ExploreRequestInclusion ...................................................................................................................54 ZW_FinishSerialIf ....................................................................................................................................325 ZW_FLASH_auto_prog_set.....................................................................................................................334 ZW_FLASH_code_page_prog.................................................................................................................333 ZW_FLASH_code_prog_lock ..................................................................................................................331 ZW_FLASH_code_prog_unlock ..............................................................................................................330 ZW_FLASH_code_sector_erase.............................................................................................................332 ZW_GET_CONTROLLER_CAPABILITIES (Macro)................................................................................363 ZW_GET_NEIGHBOR_COUNT (Macro) ................................................................................................364 ZW_GET_NODE_STATE (Macro) ..........................................................................................................367 ZW_GET_PROTOCOL_STATUS (Macro)................................................................................................58 ZW_GET_RANDOM_WORD (Macro).......................................................................................................59 ZW_GET_ROUTING_INFO (Macro) .......................................................................................................368 ZW_GET_SUC_NODEID (Macro)...................................................................................................370, 417 ZW_GET_VIRTUAL_NODES (Macro) ....................................................................................................409 ZW_GetControllerCapabilities .................................................................................................................363 ZW_GetNeighborCount ...........................................................................................................................364 ZW_GetNetworkStats................................................................................................................................85 ZW_GetNodeProtocolInfo........................................................................................................................367 ZW_GetPriorityRoute...............................................................................................................................365 ZW_GetProtocolStatus..............................................................................................................................58 ZW_GetRandomWord ...............................................................................................................................59 ZW_GetRoutingInfo.................................................................................................................................368 ZW_GetSecurityKeys (Only slave libraries).............................................................................................261 ZW_GetSUCNodeID........................................................................................................................370, 417 ZW_GetTxTimers ......................................................................................................................................83 ZW_GetVirtualNodes...............................................................................................................................409 ZW_GPTIMER_enable............................................................................................................................249 ZW_GPTIMER_get..................................................................................................................................253 ZW_GPTIMER_init ..................................................................................................................................245 ZW_GPTIMER_int_clear .........................................................................................................................246 ZW_GPTIMER_int_enable ......................................................................................................................248 ZW_GPTIMER_int_get............................................................................................................................247 ZW_GPTIMER_pause.............................................................................................................................250 ZW_GPTIMER_reload_get......................................................................................................................252 ZW_GPTIMER_reload_set......................................................................................................................251 ZW_IOS_enable ......................................................................................................................................139 ZW_IOS_get............................................................................................................................................141 ZW_IOS_set ............................................................................................................................................140 ZW_IR_disable ........................................................................................................................................315 ZW_IR_learn_data...................................................................................................................................311 ZW_IR_learn_init.....................................................................................................................................309 ZW_IR_status_clear ................................................................................................................................314 ZW_IR_tx_data........................................................................................................................................307 ZW_IR_tx_init ..........................................................................................................................................305 ZW_IR_tx_status_get ..............................................................................................................................308 ZW_IS_FAILED_NODE_ID (Macro)........................................................................................................371 ZW_IS_NODE_WITHIN_DIRECT_RANGE (Macro)...............................................................................418 ZW_IS_VIRTUAL_NODE (Macro)...........................................................................................................408 ZW_IsFailedNode....................................................................................................................................371 ZW_IsNodeWithinDirectRange................................................................................................................418 ZW_IsPrimaryCtrl ....................................................................................................................................372 ZW_IsVirtualNode....................................................................................................................................408 ZW_KS_enable........................................................................................................................................321 ZW_KS_init..............................................................................................................................................319 ZW_KS_pd_enable..................................................................................................................................322 ZW_LED_data_busy................................................................................................................................296 ZW_LED_init............................................................................................................................................293 ZW_LED_waveform_set..........................................................................................................................295 ZW_LED_waveforms_set........................................................................................................................294 ZW_LOCK_ROUTE (Macro) ...........................................................................................................119, 120 ZW_LockRoute (Only controllers)............................................................................................................119 ZW_LockRoute (Only slaves)..................................................................................................................120 ZW_MEM_FLUSH (Macro)......................................................................................................................155 ZW_MEM_GET_BUFFER (Macro)..........................................................................................................152 ZW_MEM_GET_BYTE (Macro)...............................................................................................................150 ZW_MEM_PUT_BUFFER (Macro)..........................................................................................................153 ZW_MEM_PUT_BYTE (Macro)...............................................................................................................151 ZW_MEMORY_GET_ID (Macro).............................................................................................................149 ZW_MemoryFlush ...................................................................................................................................155 ZW_NetworkLearnModeStart ....................................................................................................................88 ZW_NetworkManagementSetMaxInclusionRequestIntervals....................................................................89 ZW_NODE_MASK_BITS_IN (Macro)......................................................................................................137 ZW_NODE_MASK_CLEAR (Macro) .......................................................................................................136 ZW_NODE_MASK_CLEAR_BIT (Macro)................................................................................................135 ZW_NODE_MASK_NODE_IN (Macro) ...................................................................................................138 ZW_NODE_MASK_SET_BIT (Macro).....................................................................................................134 ZW_NodeMaskBitsIn...............................................................................................................................137 ZW_NodeMaskClear ...............................................................................................................................136 ZW_NodeMaskClearBit ...........................................................................................................................135 ZW_NodeMaskNodeIn ............................................................................................................................138 ZW_NodeMaskSetBit ..............................................................................................................................134 ZW_NVRCheck .......................................................................................................................................157 ZW_NVRGetValue...................................................................................................................................156 ZW_PRIMARYCTRL (Macro)..................................................................................................................372 ZW_PWM_enable....................................................................................................................................255 ZW_PWM_init..........................................................................................................................................254 ZW_PWM_int_clear.................................................................................................................................256 ZW_PWM_int_enable..............................................................................................................................258 ZW_PWM_int_get....................................................................................................................................257 ZW_PWM_waveform_get........................................................................................................................260 ZW_PWM_waveform_set........................................................................................................................259 ZW_Random..............................................................................................................................................61 ZW_RANDOM (Macro)..............................................................................................................................61 ZW_REDISCOVERY_NEEDED (Macro).................................................................................................419 ZW_RediscoveryNeeded.........................................................................................................................419 ZW_RegisterNoiseLevelCallback ..............................................................................................................62 ZW_REMOVE_FAILED_NODE_ID (Macro)............................................................................................373 ZW_REMOVE_NODE_FROM_NETWORK (Macro)...............................................................................377 ZW_REMOVE_NODE_ID_FROM_NETWORK (Macro) .........................................................................386 ZW_RemoveFailedNode .........................................................................................................................373 ZW_RemoveNodeFromNetwork..............................................................................................................377 ZW_RemoveNodeIDFromNetwork..........................................................................................................386 ZW_REPLACE_FAILED_NODE (Macro)................................................................................................375 ZW_ReplaceFailedNode..........................................................................................................................375 ZW_REPLICATION_COMMAND_COMPLETE (Macro).........................................................................387 ZW_REPLICATION_SEND_DATA (Macro) ............................................................................................388 ZW_ReplicationReceiveComplete...........................................................................................................387 ZW_ReplicationSend...............................................................................................................................388 ZW_REQUEST_NETWORK_UPDATE (Macro) .......................................................................................66 ZW_REQUEST_NEW_ROUTE_DESTINATIONS (Macro).....................................................................421 ZW_REQUEST_NODE_INFO (Macro) ...........................................................................................389, 422 ZW_REQUEST_NODE_NEIGHBOR_UPDATE (Macro) ........................................................................390 ZW_RequestNetWorkUpdate ......................................................................................42, 66, 354, 430, 431 ZW_RequestNewRouteDestinations .......................................................................................................421 ZW_RequestNodeInfo .....................................................................................................................389, 422 ZW_RequestNodeNeighborUpdate.........................................................................................................390 ZW_RF_POWERLEVEL_GET (Macro).....................................................................................................65 ZW_RF_POWERLEVEL_REDISCOVERY_SET (Macro).........................................................................68 ZW_RF_POWERLEVEL_SET (Macro) .....................................................................................................64 ZW_RFPowerLevelGet..............................................................................................................................65 ZW_RFPowerlevelRediscoverySet............................................................................................................68 ZW_RFPowerLevelSet ..............................................................................................................................64 ZW_SEND_DATA (Macro) ........................................................................................................................91 ZW_SEND_DATA_ABORT (Macro)........................................................................................................118 ZW_SEND_DATA_BRIDGE (Macro) ......................................................................................................108 ZW_SEND_DATA_MULTI (Macro) .........................................................................................................111 ZW_SEND_DATA_MULTI_BRIDGE (Macro)..........................................................................................115 ZW_SEND_NODE_INFO (Macro).............................................................................................................70 ZW_SEND_SLAVE_NODE_INFO (Macro) .............................................................................................403 ZW_SEND_SUC_ID (Macro)...................................................................................................................392 ZW_SEND_TEST_FRAME (Macro)..........................................................................................................72 ZW_SendConst .......................................................................................................................................121 ZW_SendData ...........................................................................................................................................91 ZW_SendData_Bridge.............................................................................................................................108 ZW_SendDataAbort.................................................................................................................................118 ZW_SendDataMulti..................................................................................................................................111 ZW_SendDataMulti_Bridge .....................................................................................................................115 ZW_SendNodeInformation ........................................................................................................................70 ZW_SendSlaveNodeInformation .............................................................................................................403 ZW_SendSUCID......................................................................................................................................392 ZW_SendTestFrame .................................................................................................................................72 ZW_SET_DEFAULT (Macro) ..........................................................................................................393, 413 ZW_SET_EXT_INT_LEVEL (Macro).........................................................................................................74 ZW_SET_LEARN_MODE (Macro)..................................................................................................394, 413 ZW_SET_PROMISCUOUS_MODE (Macro).............................................................................................75 ZW_SET_ROUTING_INFO (Macro)........................................................................................................397 ZW_SET_RX_MODE (Macro)...................................................................................................................76 ZW_SET_SLAVE_LEARN_MODE (Macro) ............................................................................................405 ZW_SET_SLEEP_MODE (Macro) ..........................................................................................................171 ZW_SET_SUC_NODE_ID (Macro) .........................................................................................................399 ZW_SET_WUT_TIMEOUT (Macro) ........................................................................................................174 ZW_SetDefault ................................................................................................................................393, 413 ZW_SetExtIntLevel....................................................................................................................................74 ZW_SetLearnMode..........................................................................................................................394, 413 ZW_SetListenBeforeTalkThreshold.........................................................................................................122 ZW_SetPriorityRoute...............................................................................................................................366 ZW_SetPromiscuousMode (Only controller libraries)................................................................................75 ZW_SetRFReceiveMode...........................................................................................................................76 ZW_SetRoutingInfo .................................................................................................................................397 ZW_SetRoutingMAX................................................................................................................................398 ZW_SetSlaveLearnMode.........................................................................................................................405 ZW_SetSleepMode..................................................................................................................................171 ZW_SetSUCNodeID................................................................................................................................399 ZW_SetWutTimeout ................................................................................................................................174 ZW_SPI0_active_get...............................................................................................................................181 ZW_SPI0_enable.....................................................................................................................................178 ZW_SPI0_init...........................................................................................................................................176 ZW_SPI0_int_clear..................................................................................................................................185 ZW_SPI0_int_enable...............................................................................................................................183 ZW_SPI0_int_get.....................................................................................................................................184 ZW_SPI0_rx_get .....................................................................................................................................179 ZW_SPI0_tx_set......................................................................................................................................180 ZW_SPI1_active_get...............................................................................................................................190 ZW_SPI1_coll_get...........................................................................................................................182, 191 ZW_SPI1_enable.....................................................................................................................................187 ZW_SPI1_init...........................................................................................................................................186 ZW_SPI1_int_clear..................................................................................................................................194 ZW_SPI1_int_enable...............................................................................................................................192 ZW_SPI1_int_get.....................................................................................................................................193 ZW_SPI1_rx_get .....................................................................................................................................188 ZW_SPI1_tx_set......................................................................................................................................189 ZW_STORE_HOME_ID (Macro).............................................................................................................412 ZW_STORE_NODE_INFO (Macro) ........................................................................................................411 ZW_StoreHomeID ...................................................................................................................................412 ZW_StoreNodeInfo..................................................................................................................................411 ZW_TIMER_CANCEL (Macro)................................................................................................................166 ZW_TIMER_RESTART (Macro)..............................................................................................................165 ZW_TIMER_START (Macro)...................................................................................................................164 ZW_TIMER1_init .....................................................................................................................................233 ZW_TRIAC_dimlevel_set ........................................................................................................................288 ZW_TRIAC_enable..................................................................................................................................287 ZW_TRIAC_init........................................................................................................................................279 ZW_TRIAC_int_clear...............................................................................................................................291 ZW_TRIAC_int_enable............................................................................................................................289 ZW_TRIAC_int_get..................................................................................................................................290 ZW_TX_COUNTER (Macro) ...................................................................................................................410 ZW_Type_Library ......................................................................................................................................77 ZW_TYPE_LIBRARY (Macro)...................................................................................................................77 ZW_UART0_init.......................................................................................................................................217 ZW_UART0_INT_DISABLE (Macro).......................................................................................................225 ZW_UART0_INT_ENABLE (Macro)........................................................................................................224 ZW_UART0_rx_data_get ........................................................................................................................218 ZW_UART0_rx_data_wait_get................................................................................................................219 ZW_UART0_rx_enable............................................................................................................................231 ZW_UART0_rx_int_clear.........................................................................................................................228 ZW_UART0_rx_int_get............................................................................................................................230 ZW_UART0_tx_active_get ......................................................................................................................220 ZW_UART0_tx_data_set.........................................................................................................................221 ZW_UART0_tx_enable............................................................................................................................232 ZW_UART0_tx_int_clear.........................................................................................................................227 ZW_UART0_tx_int_get............................................................................................................................229 ZW_UART0_tx_send_nl..........................................................................................................................226 ZW_UART0_tx_send_num......................................................................................................................222 ZW_UART0_tx_send_str.........................................................................................................................223 ZW_UART1_init.......................................................................................................................................217 ZW_UART1_INT_DISABLE (Macro).......................................................................................................225 ZW_UART1_INT_ENABLE (Macro)........................................................................................................224 ZW_UART1_rx_data_get ........................................................................................................................218 ZW_UART1_rx_data_wait_get................................................................................................................219 ZW_UART1_rx_enable............................................................................................................................231 ZW_UART1_rx_int_clear.........................................................................................................................228 ZW_UART1_rx_int_get............................................................................................................................230 ZW_UART1_tx_active_get ......................................................................................................................220 ZW_UART1_tx_data_set.........................................................................................................................221 ZW_UART1_tx_enable............................................................................................................................232 ZW_UART1_tx_int_clear.........................................................................................................................227 ZW_UART1_tx_int_get............................................................................................................................229 ZW_UART1_tx_send_nl..........................................................................................................................226 ZW_UART1_tx_send_num......................................................................................................................222 ZW_UART1_tx_send_str.........................................................................................................................223 ZW_Version...............................................................................................................................................78 ZW_VERSION (Macro)..............................................................................................................................78 ZW_VERSION_BETA (Macro) ..................................................................................................................79 ZW_VERSION_MAJOR (Macro)...............................................................................................................79 ZW_VERSION_MAJOR / ZW_VERSION_MINOR / ZW_VERSION_BETA .............................................79 ZW_VERSION_MINOR (Macro)................................................................................................................79 ZW_WATCHDOG_DISABLE (Macro) .......................................................................................................81 ZW_WATCHDOG_ENABLE (Macro) ........................................................................................................80 ZW_WATCHDOG_KICK (Macro)..............................................................................................................82 ZW_WatchDogDisable ..............................................................................................................................81 ZW_WatchDogEnable ...............................................................................................................................80 ZW_WatchDogKick....................................................................................................................................82 zwTransmitCount.....................................................................................................................................410 diff --git a/docs/specs/zwave-500-series-programmers-guide/assets/img-13f50a1628.png b/docs/specs/zwave-500-series-programmers-guide/assets/img-13f50a1628.png new file mode 100644 index 0000000..0f13373 Binary files /dev/null and b/docs/specs/zwave-500-series-programmers-guide/assets/img-13f50a1628.png differ diff --git a/docs/specs/zwave-500-series-programmers-guide/assets/img-5faa92ce3d.png b/docs/specs/zwave-500-series-programmers-guide/assets/img-5faa92ce3d.png new file mode 100644 index 0000000..b2ba0ed Binary files /dev/null and b/docs/specs/zwave-500-series-programmers-guide/assets/img-5faa92ce3d.png differ diff --git a/docs/specs/zwave-500-series-programmers-guide/assets/img-650c78a2f9.png b/docs/specs/zwave-500-series-programmers-guide/assets/img-650c78a2f9.png new file mode 100644 index 0000000..cdb99c5 Binary files /dev/null and b/docs/specs/zwave-500-series-programmers-guide/assets/img-650c78a2f9.png differ diff --git a/docs/specs/zwave-500-series-programmers-guide/assets/img-765cb9c389.png b/docs/specs/zwave-500-series-programmers-guide/assets/img-765cb9c389.png new file mode 100644 index 0000000..f581d2c Binary files /dev/null and b/docs/specs/zwave-500-series-programmers-guide/assets/img-765cb9c389.png differ diff --git a/docs/specs/zwave-500-series-programmers-guide/assets/img-7770287b4b.png b/docs/specs/zwave-500-series-programmers-guide/assets/img-7770287b4b.png new file mode 100644 index 0000000..26a6b0b Binary files /dev/null and b/docs/specs/zwave-500-series-programmers-guide/assets/img-7770287b4b.png differ diff --git a/docs/specs/zwave-500-series-programmers-guide/assets/img-b9bf4cd14c.png b/docs/specs/zwave-500-series-programmers-guide/assets/img-b9bf4cd14c.png new file mode 100644 index 0000000..b424050 Binary files /dev/null and b/docs/specs/zwave-500-series-programmers-guide/assets/img-b9bf4cd14c.png differ diff --git a/docs/specs/zwave-500-series-programmers-guide/assets/img-bc2ffcbf33.png b/docs/specs/zwave-500-series-programmers-guide/assets/img-bc2ffcbf33.png new file mode 100644 index 0000000..c3412f8 Binary files /dev/null and b/docs/specs/zwave-500-series-programmers-guide/assets/img-bc2ffcbf33.png differ diff --git a/docs/specs/zwave-500-series-programmers-guide/assets/img-cd5225ad49.png b/docs/specs/zwave-500-series-programmers-guide/assets/img-cd5225ad49.png new file mode 100644 index 0000000..b18edb7 Binary files /dev/null and b/docs/specs/zwave-500-series-programmers-guide/assets/img-cd5225ad49.png differ diff --git a/docs/specs/zwave-500-series-programmers-guide/assets/img-daa8fe3846.png b/docs/specs/zwave-500-series-programmers-guide/assets/img-daa8fe3846.png new file mode 100644 index 0000000..3f3ad0d Binary files /dev/null and b/docs/specs/zwave-500-series-programmers-guide/assets/img-daa8fe3846.png differ diff --git a/docs/specs/zwave-500-series-programmers-guide/assets/img-fb9a2acc23.png b/docs/specs/zwave-500-series-programmers-guide/assets/img-fb9a2acc23.png new file mode 100644 index 0000000..b1a0b6f Binary files /dev/null and b/docs/specs/zwave-500-series-programmers-guide/assets/img-fb9a2acc23.png differ diff --git a/docs/specs/zwave-500-series-programmers-guide/index.md b/docs/specs/zwave-500-series-programmers-guide/index.md new file mode 100644 index 0000000..2d0ed4a --- /dev/null +++ b/docs/specs/zwave-500-series-programmers-guide/index.md @@ -0,0 +1,24 @@ + + +# INS13954-Instruction-Z-Wave-500-Series-Appl-Programmers-Guide-v6_8x_0x + +*Source:* [INS13954-Instruction-Z-Wave-500-Series-Appl-Programmers-Guide-v6_8x_0x.pdf](../sources/INS13954-Instruction-Z-Wave-500-Series-Appl-Programmers-Guide-v6_8x_0x.pdf) +*Version:* 13 +*Pages:* 456 +*Generated by:* `tools/pdf2md/convert.py` (PyMuPDF 1.27.1) + + +## Chapters + +- [1 Abbreviations](01-abbreviations.md) +- [2 Introduction](02-introduction/index.md) +- [3 Z-Wave Software Architecture](03-z-wave-software-architecture/index.md) +- [4 Z-Wave Application Interfaces](04-z-wave-application-interfaces/index.md) +- [5 Application Note: SUC/SIS Implementation](05-application-note-sucsis-implementation/index.md) +- [6 Application Note: Controller Shift Implementation](06-application-note-controller-shift-implementation.md) +- [7 Application Note: Z-Wave Protocol Versions etc](07-application-note-z-wave-protocol-versions-etc.md) +- [8 References](08-references.md) diff --git a/docs/specs/zwave-host-api-specification/01-introduction/01.01-purpose.md b/docs/specs/zwave-host-api-specification/01-introduction/01.01-purpose.md new file mode 100644 index 0000000..8559e2a --- /dev/null +++ b/docs/specs/zwave-host-api-specification/01-introduction/01.01-purpose.md @@ -0,0 +1,10 @@ + +# 1.1 Purpose + +This document specifies the communication and commands used by host processors to interface with a module supporting a Z-Wave API. diff --git a/docs/specs/zwave-host-api-specification/01-introduction/01.02-audience-and-requirements.md b/docs/specs/zwave-host-api-specification/01-introduction/01.02-audience-and-requirements.md new file mode 100644 index 0000000..699e041 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/01-introduction/01.02-audience-and-requirements.md @@ -0,0 +1,10 @@ + +# 1.2 Audience and Requirements + +The audience of this document is the Z-Wave Alliance members and Z-Wave developers. diff --git a/docs/specs/zwave-host-api-specification/01-introduction/01.03-terms.md b/docs/specs/zwave-host-api-specification/01-introduction/01.03-terms.md new file mode 100644 index 0000000..fd4e586 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/01-introduction/01.03-terms.md @@ -0,0 +1,12 @@ + +# 1.3 Terms + +This document describes mandatory and optional aspects of the required compliance of a Z-Wave prod- uct to the Z-Wave standard. + +[The guidelines outlined in RFC 2119 with respect to key words used to indicate requirement levels are](https://tools.ietf.org/html/rfc2119.html) followed. Essentially, the key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this doc- [ument are to be interpreted as described in RFC 2119 .](https://tools.ietf.org/html/rfc2119.html) diff --git a/docs/specs/zwave-host-api-specification/01-introduction/01.04-terminology-and-abbreviations.md b/docs/specs/zwave-host-api-specification/01-introduction/01.04-terminology-and-abbreviations.md new file mode 100644 index 0000000..e40ed30 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/01-introduction/01.04-terminology-and-abbreviations.md @@ -0,0 +1,22 @@ + +# 1.4 Terminology And Abbreviations + +[Terminology and abbreviations used in this document are listed in Table 1.1](01.04-terminology-and-abbreviations.md#14-terminology-and-abbreviations) + +Table 1.1: Terminology and abbreviations + +| Term | Abbreviation | Description | +| --- | --- | --- | +| Always Listening | AL (node) | Z-Wave node that is Always Listening. Refer to [zwave nwk spec] for details. _ _ | +| Frequently Listening | FL (node) | Z-Wave node that is Frequently Listening. Refer to [zwave nwk spec] for details. _ _ | +| Least Significant Byte | LSB | Byte in the bytestream that has the lowest weight | +| Most Significant Byte | MSB | Byte in the bytestream that has the highest weight | +| Non-Listening | NL (node) | Z-Wave node that is Non-Listening. Refer to [zwave nwk spec] for details. _ _ | +| Network Wide Inclusion | NWI | Inclusion method leveraging Explore NDPU to include through repeaters. Refer to [zwave nwk spec] for details. _ _ | +| Transmitter | Tx | RF Transmitter | diff --git a/docs/specs/zwave-host-api-specification/01-introduction/index.md b/docs/specs/zwave-host-api-specification/01-introduction/index.md new file mode 100644 index 0000000..9a00748 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/01-introduction/index.md @@ -0,0 +1,15 @@ + +# 1 Introduction + +## Contents + +- [1.1 Purpose](01.01-purpose.md) +- [1.2 Audience and Requirements](01.02-audience-and-requirements.md) +- [1.3 Terms](01.03-terms.md) +- [1.4 Terminology And Abbreviations](01.04-terminology-and-abbreviations.md) diff --git a/docs/specs/zwave-host-api-specification/02-overview.md b/docs/specs/zwave-host-api-specification/02-overview.md new file mode 100644 index 0000000..cc94e45 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/02-overview.md @@ -0,0 +1,26 @@ + +# 2 Overview + +The Z-Wave Applications Programming Interface (Z-Wave API) allows a host interface to communicate with a Z-Wave chip through any kind of physical interface. + +The host may be PC or a less powerful embedded host CPU, e.g., in a remote control or in a gateway device. Depending on the chip family, the Z-Wave API is typically accessed via RS-232 or USB physical interfaces. + +Here are some of the applications leveraging the Z-Wave API: + +• Gateway Application + +• PC Controller + +• Conformance Testing Tool (CTT) + +In this specification, we will refer to: + +• The host application: It is the application making use of the Z-Wave API via the physical inter- face. + +• The Z-Wave API Module: It is the Z-Wave API implementation providing an API to make use of its Z-Wave capabilities. diff --git a/docs/specs/zwave-host-api-specification/03-interface-communication/03.01-table-syntax.md b/docs/specs/zwave-host-api-specification/03-interface-communication/03.01-table-syntax.md new file mode 100644 index 0000000..c77f117 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/03-interface-communication/03.01-table-syntax.md @@ -0,0 +1,20 @@ + +# 3.1 Table Syntax + +The data and command format tables contains a column with byte/bit numbering. This column specifies what byte offset the shown field is in the complete data frame. In some cases this is not a fixed number and special systax notations are used. + +Table 3.1: Table Syntax + +| byte\bit | Description | +| --- | --- | +| 4 | This field is a 1 byte field in byte 4 of the data frame | +| 8+N | This field is the last field of N identical fields starting in byte 8 | +| . . . | This field is a number of identical fields | +| 5/(5..6) | This field starts at byte 5 but can be both 1 or 2 bytes long | +| 6/7 | This field is a 1 byte field located either in gyte 6 or 7 | diff --git a/docs/specs/zwave-host-api-specification/03-interface-communication/03.02-frame-types.md b/docs/specs/zwave-host-api-specification/03-interface-communication/03.02-frame-types.md new file mode 100644 index 0000000..0a348b9 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/03-interface-communication/03.02-frame-types.md @@ -0,0 +1,111 @@ + +# 3.2 Frame types + +## 3.2.1 Data Frame + +The Data frame is used to transmit a command. It can be used it both directions (Z-Wave module to [host, or host to Z-Wave module). All data frames MUST be formatted according to Table 3.2 .](03.02-frame-types.md#321-data-frame) + +Table 3.2: Data frame format + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 1 | Frame Type = SOF (0x01) | | | | | | | | +| 2 | Length | | | | | | | | +| 3 | Type | | | | | | | | +| 4 | Z-Wave API Command ID | | | | | | | | +| 4+1 | Z-Wave API Command Payload 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 4+L | Z-Wave API Command Payload L | | | | | | | | +| 4+L+1 | Checksum | | | | | | | | + +Frame Type (8 bits) + +This field is used to detect the type of frame being transmitted. For a data frame, this field MUST be set to 0x01, indicating a Start of Frame (SOF). + +Length (8 bits) + +The Length field is used to indicate the total length, in bytes, of the following fields: • Length (this field) + +• Type + +• Z-Wave API Command ID • Z-Wave API Command Payload + +The following fields MUST NOT be included in the length calculation: + +• Start of frame + +• Checksum + +Type (8 bits) + +The Type field is used to indicate the type of Command being sent in the data frame. It MUST be [encoded according to Table 3.3 .](03.02-frame-types.md#321-data-frame) + +Table 3.3: Data frame format - Type encoding + +| Value | Description | +| --- | --- | +| 0x00 | Request frame. This type MUST be used by the host application for unsolicited new commands. Z-Wave API callbacks MUST also use the Request type. | +| 0x01 | Response frame. This type MUST be used by the Z-Wave Module to issue re- sponses to Request frames. | +| 0x02..0xFF | Reserved values MUST NOT be used and MUST be ignored by a receiving inter- face | + +Z-Wave API Command ID (8 bits) + +This field is used to advertise a command identifier that enable a receiving interface to parse the payload. [Commands are described in section Z-Wave API Commands .](../04-z-wave-api-commands/index.md#4-z-wave-api-commands) + +Z-Wave API Command Payload (L bytes) + +This field is used to indicate the payload associated with the Z-Wave API command. The payload for [each command is described in the Z-Wave API Commands section.](../04-z-wave-api-commands/index.md#4-z-wave-api-commands) + +Checksum (8 bits) + +The Checksum field is used to validate the data received in the Data Frame. The Checksum calculation MUST include the following fields: + +• Length + +• Type + +• Z-Wave API Command ID + +• Z-Wave API Command Payload + +The Checksum field MUST be calculated using XOR operations: Checksum = 0xFF (XOR) Length (XOR) Type (XOR) Z-Wave API Command ID (XOR) Z-Wave API Command Payload 1 (XOR) . . . (XOR) Z-Wave API Command Payload N + +[An interface receiving a non-matching checksum MUST return a NAK Frame . An interface receiving a](03.02-frame-types.md#323-nak-frame) [matching checksum MUST return an ACK Frame .](03.02-frame-types.md#322-ack-frame) + +## 3.2.2 ACK Frame + +[The ACK frame is used to indicate the successful reception of a Data Frame . It MUST be formatted](03.02-frame-types.md#321-data-frame) according to Table 3.4 Table 3.4: ACK frame format + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 1 | Frame Type = ACK (0x06) | | | | | | | | + +## 3.2.3 NAK Frame + +[The NAK frame is used to indicate an error in the reception of a Data Frame . It MUST be formatted](03.02-frame-types.md#321-data-frame) [according to Table 3.5 .](03.02-frame-types.md#323-nak-frame) + +Table 3.5: NAK frame format + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 1 | Frame Type = NAK (0x15) | | | | | | | | + +## 3.2.4 CAN Frame + +[The CAN frame is used to indicate the detection of a collision during Data Frame transmissions.](03.02-frame-types.md#321-data-frame) + +A CAN frame is most often returned when the UART is both transmitting and receiving at the same time (a collision). This results in the receiving end receiving a frame it did not expect and thus it drops the frame and returns a CAN. The transmitting end typically is also receiving a frame which it must process and ACK and then retransmit the frame that was returned with a CAN after an appropriate backoff interval. + +[It MUST be formatted according to Table 3.6 .](03.02-frame-types.md#324-can-frame) + +Table 3.6: CAN frame format + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 1 | Frame Type = CAN (0x18) | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/03-interface-communication/03.03-command-frame-flows.md b/docs/specs/zwave-host-api-specification/03-interface-communication/03.03-command-frame-flows.md new file mode 100644 index 0000000..b7c0a73 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/03-interface-communication/03.03-command-frame-flows.md @@ -0,0 +1,72 @@ + +# 3.3 Command frame flows + +[The Z-Wave API has several possible command frame flows:](03.03-command-frame-flows.md#331-unacknowledged-frame) + +• [Unacknowledged frame](03.03-command-frame-flows.md#331-unacknowledged-frame) + +• [Acknowledged frame](03.03-command-frame-flows.md#332-acknowledged-frame) + +• [Acknowledged frame with response](03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +• [Acknowledged frame with callback](03.03-command-frame-flows.md#334-acknowledged-frame-with-callback) • [Acknowledged frame with response and callback](03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) + +• [Unsolicited frame](03.03-command-frame-flows.md#336-unsolicited-frame) + +In the following subsections and the rest of this specification, the frames are numbered as follow: + +1. initial data frame: it is the initial (request type) data frame from the host to the Z-Wave module. + +2. response data frame: it is a response type data frame returned to an initial data frame from the Z-Wave module to the host. 3. callback data frame: it is a request type data frame sent from the Z-Wave module to the host, after it has completed an action triggered by an initial data frame. + +4. unsolicited data frame: it is a request type data frame sent from the Z-Wave module to the host. + +## 3.3.1 Unacknowledged frame + +There MAY be data frames that will not be acknowledged by the destination because of hardware or software restrictions. It can for example happen if the command instructs the Z-Wave module to enter reprogramming mode or go offline. + +[The communication flow MUST be as shown in Figure 3.1](03.03-command-frame-flows.md#331-unacknowledged-frame) + +![Figure 3.1: Unacknowledged frame](assets/img-875c4ec825.png) + +If a command is supposed to trigger an unacknowledged frame transmission, the host MUST NOT try to retransmit the command if no ACK frame is received. The host MUST retransmit the command if a [NAK Frame or a](03.02-frame-types.md#323-nak-frame) [CAN Frame is received.](03.02-frame-types.md#324-can-frame) + +## 3.3.2 Acknowledged frame + +Acknowledged frames are frames that will not trigger any communication back from the Z-Wave mod- [ule, apart from an ACK Frame . The communication flow MUST be as shown in](03.02-frame-types.md#322-ack-frame) [Figure 3.2](03.03-command-frame-flows.md#332-acknowledged-frame) + +![Figure 3.2: Acknowledged frame](assets/img-e76bf6450b.png) + +## 3.3.3 Acknowledged frame with response + +Acknowledged frames with response are acknowledged frames that will trigger an immediate response [from the Z-Wave module. The communication flow MUST be as shown in Figure 3.3](03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +![Figure 3.3: Acknowledged frame with response](assets/img-61f2baadba.png) + +## 3.3.4 Acknowledged frame with callback + +Acknowledged frames with callback are acknowledged frames that will trigger a callback after an op- eration has been performed by the Z-Wave module. The communication flow MUST be as shown in [Figure 3.4](03.03-command-frame-flows.md#334-acknowledged-frame-with-callback) + +![Figure 3.4: Acknowledged frame with callback](assets/img-d946ff712a.png) + +In some cases, an Initial Data Frame MAY trigger several callback frames. + +## 3.3.5 Acknowledged frame with response and callback + +Acknowledged frames with response and callback are acknowledged frames that will trigger both an immediate response and an additional callback after an operation has been performed by the Z-Wave [module. The communication flow MUST be as shown in Figure 3.5](03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) + +![Figure 3.5: Acknowledged frame with response and callback](assets/img-b5c6569539.png) + +In some cases, an Initial Data Frame MAY trigger several callback frames. + +## 3.3.6 Unsolicited frame + +Unsolicited frames are frames that are sent from the Z-Wave module to inform the host application that [an event happened. The communication flow MUST be as shown in Figure 3.6](03.03-command-frame-flows.md#336-unsolicited-frame) + +![Figure 3.6: Unsolicited frame](assets/img-aef129fd85.png) diff --git a/docs/specs/zwave-host-api-specification/03-interface-communication/03.04-error-handling.md b/docs/specs/zwave-host-api-specification/03-interface-communication/03.04-error-handling.md new file mode 100644 index 0000000..1a357c1 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/03-interface-communication/03.04-error-handling.md @@ -0,0 +1,68 @@ + +# 3.4 Error handling + +The following subsections show how to handle communications issues between the Z-Wave Module and the host application. + +## 3.4.1 Retransmission timing + +[In general, retransmissions of a Data Frame MUST apply back-off timers.](03.02-frame-types.md#321-data-frame) + +[The minimum back-off in milliseconds MUST be calculated according to ( 3.1 )](03.04-error-handling.md#341-retransmission-timing) + +𝑇 ×. (3.1) = 100 + 1000 + +where: + +• n is the retransmission number - 1. i.e. n=0 for the first retransmission. + +A sending interface SHOULD add an additional random delay to the minimum back-off. + +## 3.4.2 Missing Acknowledgment + +By default, all data frames MUST be acknowledged by the receiving interface. Acknowledgement [consists in sending an ACK Frame .](03.02-frame-types.md#322-ack-frame) + +[A sending interface MUST wait for 1600ms or more for an ACK Frame after transmitting a](03.02-frame-types.md#322-ack-frame) [Data Frame .](03.02-frame-types.md#321-data-frame) + +In case of missing acknowledgement 1600 ms after a transmission, a transmitting interface SHOULD retransmit the unacknowledged data frame. + +This recommendation MAY be adjusted based on the physical medium used for communication between the two interfaces. + +[A transmitting interface SHOULD make 3 retransmissions attempts. This is shown in Figure 3.7 .](03.04-error-handling.md#342-missing-acknowledgment) + +![Figure 3.7: Missing acknowledgment frame](assets/img-8eb49a5e62.png) + +In the unlikely event that the Z-Wave Module has been unresponsive for more than 4 seconds (or 3 [consecutive Data Frame transmission attempts), it is RECOMMENDED to issue a hard reset to the Z-](03.02-frame-types.md#321-data-frame) [Wave Module. If a hard reset is not available, a Soft Reset Command SHOULD be issued.](../04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.12-soft-reset-command.md#4312-soft-reset-command) + +## 3.4.3 Collision + +[If the Z-Wave API module receives a Data Frame while it is waiting for an](03.02-frame-types.md#321-data-frame) [ACK Frame , it MUST return](03.02-frame-types.md#322-ack-frame) [a CAN Frame . A host application SHOULD NOT issue any CAN Frame , even if it detects a collision. A host application](03.02-frame-types.md#324-can-frame) SHOULD initiate a back-off for its own frame, if it was not acknowledged. + +When a collision occurs, the Z-Wave API Module SHOULD have priority for retransmission. + +[Examples are provided in Figure 3.8 and Figure 3.9](03.04-error-handling.md#343-collision) + +![Figure 3.8: Collision detected by the host (example)](assets/img-404dc40fa3.png) + +![Figure 3.9: CAN frame from the Z-Wave API Module (example)](assets/img-54e22386da.png) + +## 3.4.4 Frame reception timeout + +[A receiving interface MUST abort an ongoing reception of a Data Frame if the reception has lasted for](03.02-frame-types.md#321-data-frame) more than 1500ms after the reception of the SOF byte. + +[When aborting the reception of a Data Frame , an interface MUST NOT issue a](03.02-frame-types.md#321-data-frame) [NAK Frame .](03.02-frame-types.md#323-nak-frame) + +## 3.4.5 Invalid frame + +[A receiving interface receiving a Data Frame with a](03.02-frame-types.md#321-data-frame) Checksum [mismatch MUST return a NAK Frame .](03.02-frame-types.md#323-nak-frame) + +[This is illustrated in Figure 3.10](03.04-error-handling.md#345-invalid-frame) + +![Figure 3.10: Invalid frame](assets/img-6f86d7178e.png) + +If more than 3 consecutive transmission result in checksum errors, it is RECOMMENDED to issue a [hard reset to the Z-Wave Module. If a hard reset is not available, a Soft Reset Command SHOULD be](../04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.12-soft-reset-command.md#4312-soft-reset-command) issued. diff --git a/docs/specs/zwave-host-api-specification/03-interface-communication/index.md b/docs/specs/zwave-host-api-specification/03-interface-communication/index.md new file mode 100644 index 0000000..9b0ffa0 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/03-interface-communication/index.md @@ -0,0 +1,17 @@ + +# 3 Interface communication + +This chapter defines the frames and communications frame flows between a Z-Wave API supporting module and a host application. Several frames types are defined to enable session-like communication. + +## Contents + +- [3.1 Table Syntax](03.01-table-syntax.md) +- [3.2 Frame types](03.02-frame-types.md) +- [3.3 Command frame flows](03.03-command-frame-flows.md) +- [3.4 Error handling](03.04-error-handling.md) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.01-command-format.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.01-command-format.md new file mode 100644 index 0000000..f38573d --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.01-command-format.md @@ -0,0 +1,10 @@ + +# 4.1 Command format + +[In the following Z-Wave API Commands section, each command description uses a](index.md#4-z-wave-api-commands) [Data Frame , where](../03-interface-communication/03.02-frame-types.md#321-data-frame) only the Z-Wave API Command ID and Z-Wave API Command Payload fields are shown. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.02-generic-command-elements.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.02-generic-command-elements.md new file mode 100644 index 0000000..00abddb --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.02-generic-command-elements.md @@ -0,0 +1,301 @@ + +# 4.2 Generic command elements + +## 4.2.1 Session identifier (8 bits) + +Some commands contain a Session Identifier. This is a 1 byte value provided by the host application for any given command that must be used by the Z-Wave module in callback commands triggered by the initial data frame. + +This Session Identifier can be used by a host application to track which command triggered the incoming callbacks or to identify associated application user data. (e.g. the host needs to retrieve data or perform actions associated to the initial command.) + +## 4.2.2 Rx Status (8 bits) + +The Rx Status field is used to indicate how a Z-Wave frame was received. This field MUST be encoded [according to Table 4.1](../01-introduction/01.04-terminology-and-abbreviations.md#14-terminology-and-abbreviations) Table 4.1: Rx Status Value encoding + +| Bit | Flag | Description | +| --- | --- | --- | +| 0 | Reserved | This bit is reserved. Reserved bits MUST NOT be used and MUST be ignored by a receiving interface. | +| 1 | Low power | This bit indicates if the Z-Wave frame has been received with low output power. • The value 0 MUST indicate that the frame was received with normal output power. • The value 1 MUST indicate that the frame was received with low output power. | +| 2 | Reserved | This bit is reserved. Reserved bits MUST NOT be used and MUST be ignored by a receiving interface. | +| 3 | Broadcast addressing | This bit indicates if the Z-Wave frame has been received using broadcast addressing. • The value 0 MUST indicate that the frame was received using multicast or singlecast addressing. • The value 1 MUST indicate that the frame was received using broadcast addressing. | + +| | 4 | Multicast addressing | This bit indicates if the Z-Wave frame has been received using multicast addressing. • The value 0 MUST indicate that the frame was received using broadcast or singlecast addressing. • The value 1 MUST indicate that the frame was received using multicast addressing. | | +| --- | --- | --- | --- | --- | +| | 5 | Explore NPDU | This bit indicates if the Z-Wave frame has been received using an Explore NPDU. • The value 0 MUST indicate that the frame was not re- ceived using an Explore NDPU. • The value 1 MUST indicate that the frame was received using an Explore NDPU. | | +| | 6 | Foreign frame | This bit indicates if the frame not addressed to the Z-Wave Mod- ule. This is useful only in promiscuous mode. • The value 0 MUST indicate that the frame was addressed to the Z-Wave Module. • The value 1 MUST indicate that the frame was not ad- dressed to the Z-Wave Module. | | +| | 7 | Foreign HomeID | This bit indicates if frame was sent on another HomeID. • The value 0 MUST indicate that the frame was sent on the current HomeID. • The value 1 MUST indicate that the frame was sent on the another HomeID. | | + +## 4.2.3 Tx Status (8 bits) + +This field is used to advertise the outcome of a Z-Wave radio transmission attempt. This field MUST be [encoded according to Table 4.2](../03-interface-communication/03.02-frame-types.md#321-data-frame) + +Table 4.2: Tx Status Value encoding + +| Value | Flag / Description | +| --- | --- | +| 0x00 | TRANSMIT COMPLETE OK _ _ Transmission completed and successful This value is used to indicate that the transmission was successful, and acknowledged if an acknowledged transmis- sion was requested. | +| 0x01 | TRANSMIT COMPLETE NO ACK _ _ _ Transmission completed but no Acknowledgment This value is used to indicate that the transmission was completed, but no Acknowledgment has been received from the destination. | +| 0x02 | TRANSMIT COMPLETE FAIL _ _ Transmission failed. This value is used to indicate that the transmission could not be done. | +| 0x03 | TRANSMIT ROUTING NOT IDLE _ _ _ Transmission failed due to routing being busy. This value is used to indicate that the transmission could not be done due to routing being locked/busy. | +| 0x04 | TRANSMIT COMPLETE NOROUTE _ _ Transmission failed due to routing resolution. This value is used to indicate that the transmission could not be done due to missing route or failed route resolution. | +| 0x05 | TRANSMIT COMPLETE VERIFIED _ _ Transmission completed and successful, including S2 resynchronization back- off This value is used to indicate that the transmission was successful, and ac- knowledged and that the destination has successfully decrypted the message. This status MUST be used only if the Z-Wave module performed Security en- cryption. | + +## 4.2.4 RSSI Measurements (8 bits) + +[All RSSI measurements MUST use signed representation and MUST be encoded according to Table 4.3](../03-interface-communication/03.02-frame-types.md#321-data-frame) + +Table 4.3: RSSI value encoding + +| Hexadecima | Decimal | Description | +| --- | --- | --- | +| 0x80..0xFF | -128..-1 | This value represents the measured RSSI in dBm | +| 0x00..0x7C | 0..124 | This value represents the measured RSSI in dBm | +| 0x7D | 125 | The RSSI is below sensitivity and could not be measured. | +| 0x7E | 126 | The radio receiver is saturated and the RSSI could not be measured. | +| 0x7F | 127 | The RSSI is not available. | + +## 4.2.5 Response status (8 bits) + +Some commands Response data frame contain Response status. It is a 1 byte field value that is used indicate if the requested operation in the Initial Data Frame has been accepted and the Callback Data Frame is expected or not. This field MUST be encoded as follow: • If this field is encoded to 0x00 and the Session Identifier is zero, the Z-Wave Module MUST not send Callback data Frame to the host. + +• If this field is encoded different from 0x00 and the the Session Identifier is not zero, the Z-Wave Module MUST send Callback data Frame to the host. + +## 4.2.6 Command Status (8 bits) + +When a Z-Wave API Module receives a command, it sometimes provides the execution status of the commands using a Command Status field in the Response data frame. + +The Command Status field MUST be encoded as follow: + +• The value 0x00 MUST indicate that the command was not accepted or an error occurred while applying it. + +• The value 0x01 MUST indicate that the command was successfully executed. + +• Values in the range 0x02..0xFF MUST also be interpreted as a successful command execution. + +## 4.2.7 Basic Device Class (8 bits) + +Some commands contain Basic Device Class field which is used to identify the Z-Wave library used by [the application for a given device (Refer to [ device_type_spec_v2 ]), and such field MUST be encoded](../05-references.md#5-references) according to Table 4.4. + +Table 4.4: Basic Device Class value encoding + +| Value | Description | +| --- | --- | +| 0x01 | BASIC TYPE CONTROLLER _ _ Node is a portable controller. | +| 0x02 | BASIC TYPE STATIC CONTROLLER _ _ _ Node is a static controller. | +| 0x03 | BASIC TYPE END NODE _ _ _ End node. | +| 0x04 | BASIC TYPE ROUTING END NODE _ _ _ _ End node with routing capabilities | +| 0x05..0xFF | Reserved Reserved values MUST NOT be used. | + +## 4.2.8 Tx Options (8 bits) + +This field is used to indicate the transmission options for sending Z-Wave frames. [This field MUST be treated as a bit mask and encoded according to Table 4.5](../03-interface-communication/03.02-frame-types.md#323-nak-frame) + +Table 4.5: Tx Options encoding + +| Bit | Description | +| --- | --- | +| 0 | MPDU Acknowledgment request (TRANSMIT OPTION ACK) _ _ This option is used to request the destination node to return an MPDU acknowledgement. This option SHOULD be used by a host application for all communication. If the destina- tion NodeID is the broadcast NodeID, the Z-Wave Module MUST ignore this bit. | +| 1 | Transmit with low power (TRANSMIT OPTION LOW POWER) _ _ _ This option is OBSOLETED. This option MUST NOT be used by a sending interface and MUST be ignored by a receiving interface. | +| 2 | Enable Automatic Routing (TRANSMIT OPTION AUTO ROUTE) _ _ _ This option is used to enable automatic routing. The Z-Wave library runs on the Z-Wave Module will try transmitting the frame via repeater nodes in case destination node is out of direct range. Controller nodes MAY use this bit to enable routing via Last Working Routes, calculated routes and routes discovered via dynamic route resolution. End Nodes MAY use this bit to enable routing via return routes for the actual destination nodeID (if any exist). If the destination is the broadcast NodeID, the Z-Wave Module MUST ignore this option. | +| 3 | Reserved This option is reserved. | +| 4 | Disable Routing (TRANSMIT OPTION NO ROUTE) _ _ _ This option is used to explicitly disable any routing. This option MAY be used to force the Z-Wave Module to send the frame without routing. All available routing information will be ignored. This option SHOULD NOT be specified for normal application communi- cation. If the destination is the broadcast NodeID, the Z-Wave Module MUST ignore this option. | +| 5 | Enable Explore NPDUs (TRANSMIT OPTION EXPLORE) _ _ This option is used to enable the usage of Explore NPDUs if needed. The transmit op- tion TRANSMIT OPTION EXPLORE MAY be used to enable dynamic route resolution. _ _ Dynamic route resolution allows a node to discover new routes if all known routes are failing. An Explore NPDU cannot wake up FLiRS nodes. An Explore NPDU uses normal RF power level minus 6dB. This is also the power level used by a node finding its neighbors. For backwards compatibility reasons, Z-Wave Module SHOULD ignore this option if the destination NodeID does not support Explore NDPUs. | +| 6..7 | Reserved These options are reserved. | + +## 4.2.9 RF Region (8 bits) + +This field is used to indicate the Z-Wave RF Region, defining the number of channels and center fre- quency on which the Z-Wave API Module operates. + +[This field MUST be encoded according to Table 4.6](../03-interface-communication/03.02-frame-types.md#324-can-frame) Table 4.6: RF Region encoding + +| Value | Protocol | Description | +| --- | --- | --- | +| 0 | Z-Wave | Region EU: Europe. | +| 1 | Z-Wave | Region US: USA. | +| 2 | Z-Wave | Region ANZ: Australia/New Zealand. | +| 3 | Z-Wave | Region HK: Hong Kong. | +| 5 | Z-Wave | Region IN: India. | +| 6 | Z-Wave | Region IL: Israel. | +| 7 | Z-Wave | Region RU: Russia | +| 8 | Z-Wave | Region CN: China | +| 9 | Z-Wave Long Range | Region US: USA. | +| 32 | Z-Wave | Region JP: Japan. | +| 33 | Z-Wave | Region KR: Korea | +| 254 | Any | Undefined/unknown region. This value can be used if there was an error retrieving the configured region. | +| 255 | Any | Default region. This value is used to indicate that the Z-Wave API mod- ule is running on the default region. The default region MUST be the EU Region. | + +## 4.2.10 Tx Status Report (N bytes) + +When a Z-Wave transmission has been completed, the Z-Wave API Module can issue a Tx Status Report providing details about the transmission that was carried out. + +The Tx Status Report is a variable length field that has grown through the revisions of the Z-Wave API. A host application MUST be resistant to unexpected length of this field (both shorter and longer). + +The Tx Status Report [field MUST be formatted according to Table 4.7](04.02-generic-command-elements.md#4210-tx-status-report-n-bytes) Table 4.7: Tx Status Report field structure + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 1 | Transmit Ticks (MSB) | | | | | | | | +| 2 | Transmit Ticks (LSB) | | | | | | | | +| 3 | Number of repeaters | | | | | | | | +| 4 | Ack RSSI | | | | | | | | +| 5 | Measured incoming RSSI for Repeater 0 | | | | | | | | +| 6 | Measured incoming RSSI for Repeater 1 | | | | | | | | +| 7 | Measured incoming RSSI for Repeater 2 | | | | | | | | +| 8 | Measured incoming RSSI for Repeater 3 | | | | | | | | +| 9 | ACK Channel No | | | | | | | | +| 10 | Tx Channel No | | | | | | | | +| 11 | Route Scheme State | | | | | | | | +| 12 | Last Route Repeater 0 | | | | | | | | +| 13 | Last Route Repeater 1 | | | | | | | | +| 14 | Last Route Repeater 2 | | | | | | | | +| 15 | Last Route Repeater 3 | | | | | | | | +| 16 | Reserved | 1000ms Beam | 250ms Beam | Reserved | | Last Route Speed | | | +| 17 | Routing Attempts | | | | | | | | +| 18 | Last route failed link functional NodeID | | | | | | | | +| 19 | Last route failed link non-functional NodeID | | | | | | | | +| 20 | Tx Power | | | | | | | | +| 21 | Measured Noise Floor | | | | | | | | +| 22 | Destination Ack MPDU Tx Power | | | | | | | | +| 23 | Destination Ack MPDU measured RSSI | | | | | | | | +| 24 | Destination Ack MPDU measured Noise floor | | | | | | | | + +Not all values can be expected to be valid when a tranmsit fails, e.g. all fields related to acknowledge can not be expected to be valid when Tx Status is TRANSMIT_COMPLETE_NO_ACK + +Transmit Ticks (16 bits) + +This field is used to indicate the transmission time in multiples of 10ms. For example, the value 30 MUST indicate that the transmission took 300ms. + +Number of repeaters (8 bits) + +This field is used to indicate the number of repeaters used in the route to the destination. + +The value 0 MUST indicate direct range communication. Values in the range 1..255 MUST indicate the number of repeaters used to reached the destination. + +ACK RSSI (8 bits) + +This field is used to indicate ythe RSSI value of the acknowledgement frame. This field MUST be [encoded according to RSSI Measurements (8 bits) and](04.02-generic-command-elements.md#424-rssi-measurements-8-bits) [Table 4.3 .](../03-interface-communication/03.02-frame-types.md#321-data-frame) + +Measured incoming RSSI for Repeater 0 (8 bits) + +This field is used to indicate the RSSI value measured from Repeater 0 for the incoming Acknowledge- [ment frame. This field MUST be encoded according to RSSI Measurements (8 bits) and](04.02-generic-command-elements.md#424-rssi-measurements-8-bits) [Table 4.3 .](../03-interface-communication/03.02-frame-types.md#321-data-frame) Measured incoming RSSI for Repeater 1 (8 bits) This field is used to indicate the RSSI value measured from Repeater 1 for the incoming Acknowledge- [ment frame. This field MUST be encoded according to RSSI Measurements (8 bits) and](04.02-generic-command-elements.md#424-rssi-measurements-8-bits) [Table 4.3 .](../03-interface-communication/03.02-frame-types.md#321-data-frame) + +Measured incoming RSSI for Repeater 2 (8 bits) + +This field is used to indicate the RSSI value measured from Repeater 2 for the incoming Acknowledge- [ment frame. This field MUST be encoded according to RSSI Measurements (8 bits) and](04.02-generic-command-elements.md#424-rssi-measurements-8-bits) [Table 4.3 .](../03-interface-communication/03.02-frame-types.md#321-data-frame) + +Measured incoming RSSI for Repeater 3 (8 bits) + +This field is used to indicate the RSSI value measured from Repeater 3 for the incoming Acknowledge- [ment frame. This field MUST be encoded according to RSSI Measurements (8 bits) and](04.02-generic-command-elements.md#424-rssi-measurements-8-bits) [Table 4.3 .](../03-interface-communication/03.02-frame-types.md#321-data-frame) + +ACK Channel No (8 bits) + +This field is used to indicate the channel number where the ACK received from. + +Tx Channel No (8 bits) + +This field is used to indicate the channel number that is used to transmit the data. + +Route Scheme State (8 bits) + +This field is used to indicate the state of the route resolution for the transmission attempt. + +The encoding of this field is implementation specific. Refer to individual manufacturer documentation for details. + +Last Route Repeater 0 (8 bits) + +This field is used to indicate the repeater 0 used in the route to communicate with the destination. The value 0 MUST indicate that no repeater 0 was used for this route. + +Last Route Repeater 1 (8 bits) + +This field is used to indicate the repeater 1 used in the route to communicate with the destination. The value 0 MUST indicate that no repeater 1 was used for this route. + +Last Route Repeater 2 (8 bits) + +This field is used to indicate the repeater 2 used in the route to communicate with the destination. The value 0 MUST indicate that no repeater 2 was used for this route. + +Last Route Repeater 3 (8 bits) + +This field is used to indicate the repeater 3 used in the route to communicate with the destination. The value 0 MUST indicate that no repeater 4 was used for this route. + +1000ms Beam (1 bit) + +This field is used to indicate if the destination requires a 1000ms beam (or a fragmented beam) to be reached. + +250ms Beam (1 bit) + +This field is used to indicate if the destination requires a 250ms beam to be reached. + +Last Route Speed (3 bits) This field is used to indicate the transmission speed used in the route to communicate with the destina- tion. + +[The field MUST be encoded according to Table 4.8 .](04.02-generic-command-elements.md#4210-tx-status-report-n-bytes) Table 4.8: Priority Route Data Rate Encoding + +| Value | Protocol | Description | +| --- | --- | --- | +| 0x01 | Z-Wave | 9.6 kbits/s | +| 0x02 | Z-Wave | 40 kbits/s | +| 0x03 | Z-Wave | 100 kbits/s | +| 0x04 | Z-Wave Long Range | 100 kbits/s | +| 0x05..0x07 | Reserved | These values are reserved and MUST NOT be used | + +Routing Attempts (8 bits) + +This field is used to indicate how many routing attempts have been made to transmit the payload to the destination NodeID. + +Last route failed link functional NodeID (8 bits) + +This field is used when a route failed and it indicates the last functional NodeID in the last used route. + +Last route failed link non-functional NodeID (8 bits) + +This field is used when a route failed and it indicates the first non-functional NodeID in the last used route. + +Tx Power (8 bits) + +This field is used to indicate the transmit power used for the transmission. This field MUST be encoded using the signed representation and MUST be expressed in dBm. + +Values in the range -127..126 MUST indicate the transmit power. The value 127 MUST indicate that the value is not available. + +Measured Noise Floor (8 bits) + +This field is used to indicate the measured noise floor during the outgoing transmission. This field MUST [be encoded according to RSSI Measurements (8 bits) and](04.02-generic-command-elements.md#424-rssi-measurements-8-bits) [Table 4.3 .](../03-interface-communication/03.02-frame-types.md#321-data-frame) + +Destination Ack MPDU Tx Power (8 bits) + +This field is used to advertise the Tx Power used by the destination in its Ack MPDU frame. + +Values in the range -127..126 MUST indicate the transmit power. The value 127 MUST indicate that the value is not available. + +Destination Ack MPDU measured RSSI (8 bits) + +This field is used to indicate the measured RSSI of the acknowledgement frame received from the des- [tination. This field MUST be encoded according to RSSI Measurements (8 bits) and](04.02-generic-command-elements.md#424-rssi-measurements-8-bits) [Table 4.3 .](../03-interface-communication/03.02-frame-types.md#321-data-frame) + +Destination Ack MPDU measured Noise floor (8 bits) + +This field is used to indicate the measured noise floor by the destination during the MDPU Ack frame [transmission. This field MUST be encoded according to RSSI Measurements (8 bits) and](04.02-generic-command-elements.md#424-rssi-measurements-8-bits) [Table 4.3 .](../03-interface-communication/03.02-frame-types.md#321-data-frame) + +## 4.2.11 Route Speed (8 bits) + +This field is used to advertise the routed packet data rate that shall be used through the return route. The [field MUST be encoded according to Table 4.9 .](04.02-generic-command-elements.md#4211-route-speed-8-bits) Table 4.9: Priority Route Data Rate Encoding + +| Value | Description | +| --- | --- | +| 0x00 | Reserved This reserved value MUST NOT be used and MUST be ignored by a receiving inter- face. | +| 0x01 | ZW PRIORITY ROUTE SPEED 9600 _ _ _ _ This flag indicates that the priority route MUST use a data rate of 9.6 kbits/seconds. | +| 0x02 | ZW PRIORITY ROUTE SPEED 40K _ _ _ _ This flag indicates that the priority route MUST use a data rate of 40 kbits/seconds. | +| 0x03 | ZW PRIORITY ROUTE SPEED 100K _ _ _ _ This flag indicates that the priority route MUST use a data rate of 100 kbits/seconds. | +| 0x04..0xFF | Reserved Reserved values MUST NOT be used and MUST be ignored by a receiving interface | + +## 4.2.12 Repeater (4 bytes) + +This field is used to indicate the list of repeaters that MUST be used in a return route. + +Regardless of the configured NodeID basetype, each of the 4 bytes indicates the NodeID (8 bits each) of a repeater. + +[Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +If the route is a direct route, the Repeater field MUST be set to 0x00, diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.01-get-init-data-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.01-get-init-data-command.md new file mode 100644 index 0000000..0ea10b5 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.01-get-init-data-command.md @@ -0,0 +1,10 @@ + +# 4.3.1 Get Init Data Command + +This command is used to request the initialization data and current node list in the network. The Get Init Data Command Identifier is 0x02 diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.01.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.01.01-frame-flow.md new file mode 100644 index 0000000..6bb5b99 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.01.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.3.1.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.01.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.01.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..e874f3e --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.01.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,16 @@ + +# 4.3.1.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.10](04.03.01.02-1-initial-data-frame-host-z-wave-module.md#4312-1-initial-data-frame-host-z-wave-module) + +Table 4.10: Get Init Data Command + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x02 | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.01.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.01.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..156fc28 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.01.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,85 @@ + +# 4.3.1.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.11](04.03.01.03-2-response-data-frame-z-wave-module-host.md#4313-2-response-data-frame-z-wave-module-host) + +Table 4.11: Get Init Data Command + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x02 | | | | | | | | +| 5 | Z-Wave API Version | | | | | | | | +| 6 | Z-Wave API Capabilities | | | | | | | | +| 7 | Z-Wave Node List Length | | | | | | | | +| 7+1 | Z-Wave Node List 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 7+N | Z-Wave Node List N | | | | | | | | +| 7+N+1 | Chip Type | | | | | | | | +| 7+N+2 | Chip Version | | | | | | | | + +Z-Wave API Version (8 bits) + +This field is used to advertise the Z-Wave API version that the Z-Wave Module is currently running. + +[This field MUST be encoded according to Table 4.12](04.03.01.03-2-response-data-frame-z-wave-module-host.md#4313-2-response-data-frame-z-wave-module-host) Table 4.12: Get Init Data Command - Z-Wave API Version encod- ing + +| Value | Description | +| --- | --- | +| 0..9 | These values are manufacturer specific. They indicate that the Z-Wave API Mod- ule implementation follows a non-standard Z-Wave API specification. | +| 10..255 | These values indicate the Z-Wave Alliance host API specification, with an offset of 9. It means that • 10 MUST represent the version 1.0 of this document • 11 MUST represent the version 2.0 of this document • etc. | + +Z-Wave API Capabilities (8 bits) + +This field is used to advertise the capabilities of the Z-Wave API running on the Z-Wave Module. This [field MUST be encoded as a bitmask and MUST be according to Table 4.13](04.03.01.03-2-response-data-frame-z-wave-module-host.md#4313-2-response-data-frame-z-wave-module-host) + +Table 4.13: Get Init Data Command - Z-Wave API Capabilities encoding + +| Bit | Flag | Description | +| --- | --- | --- | +| 0 | End Node API | This bit indicates if the module is an End Node. • The value 0 MUST indicate that the Z-Wave module is an End Node • The value 1 MUST indicate that the Z-Wave module is a Controller Node | +| 1 | Timer func- tions | This bit indicates if the module supports timer functions. • The value 0 MUST indicate that the Z-Wave module does not support timer functions • The value 1 MUST indicate that the Z-Wave module supports timer functions | +| 2 | Primary Controller | This bit indicates if the module is Primary Controller in the current network. • The value 0 MUST indicate that the Z-Wave module has the Sec- ondary Controller role in the current network. • The value 1 MUST indicate that the Z-Wave module has the Primary Controller role in the current network. | +| 3 | SIS func- tionality | This bit indicates if the module has the SIS functionality enabled. • The value 0 MUST indicate that the Z-Wave module does not have the SIS functionality enabled. • The value 1 MUST indicate that the Z-Wave module has SIS func- tionality enabled. | +| 4..7 | Reserved | These bits are reserved. Reserved bits MUST NOT be used and MUST be ignored by a receiving interface. | + +Z-Wave Node List Length (8 bits) + +This field is used to indicate the length in bytes of the Z-Wave Node List field. + +End Nodes MUST set this field to 0. Controller Nodes MUST set this field to 29. + +Z-Wave Node List (N bytes) + +This field is used to advertise the list of nodes present in the current network. + +The length of this field, in byte, MUST be according to the Z-Wave Node List Length field. This field MUST be omitted if the Z-Wave Node List Length field is set to 0. + +This field MUST encoded as a bitmask and interpreted as follow: + +• bit 0 in byte 7 MUST represent NodeID 1. + +• bit 1 in byte 7 MUST represent NodeID 2. + +• bit 7 in byte 7 MUST represent NodeID 8. + +• bit 0 in byte 8 MUST represent NodeID 9. + +• etc. + +Chip Type (8 bits) + +This field is used to advertise the chip type of the Z-Wave Module. This value SHOULD represent the chip hardware version. + +The value of this field is implementation specific. Refer to your manufacturer documentation for details. + +Chip Version (8 bits) + +This field is used to advertise the chip version of the Z-Wave Module. + +The value of this field is implementation specific. Refer to your manufacturer documentation for details. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.01.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.01.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..181f181 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.01.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.3.1.4 3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.02-set-application-node-information-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.02-set-application-node-information-command.md new file mode 100644 index 0000000..3fd8ee3 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.02-set-application-node-information-command.md @@ -0,0 +1,12 @@ + +# 4.3.2 Set Application Node Information Command + +This command is used to generate the Node Information Frame (NIF) contents and store this information about node capabilities to the Z-Wave module. The host application may initially set up the NIF prior to starting or joining a Z-Wave network. + +The Set Application Node Information Command Identifier is 0x03. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.02.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.02.01-frame-flow.md new file mode 100644 index 0000000..ab57325 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.02.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.3.2.1 Frame flow + +[The frame flow for this command is an Acknowledged frame .](../../03-interface-communication/03.03-command-frame-flows.md#332-acknowledged-frame) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.02.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.02.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..f38e4d6 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.02.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,48 @@ + +# 4.3.2.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.14](04.03.02.02-1-initial-data-frame-host-z-wave-module.md#4322-1-initial-data-frame-host-z-wave-module) + +Table 4.14: Set Application Node Information Command + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x03 | | | | | | | | +| 5 | Device Option Mask | | | | | | | | +| 6 | Generic Device Type | | | | | | | | +| 7 | Specific Device Type | | | | | | | | +| 8 | Command Class List Length | | | | | | | | +| 8+1 | Command Class List 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 8+N | Command Class List N | | | | | | | | + +Device Option Mask (8 bits) + +The device option mask is a bitmask where Listening and Optional functionality flags MUST be set [accordingly to the nodes capabilities. This field MUST comply with the format indicated in Table 4.15 .](04.03.02.02-1-initial-data-frame-host-z-wave-module.md#4322-1-initial-data-frame-host-z-wave-module) + +Table 4.15: Set Application Node Information Command - Device Option Mask encoding + +| Bit | Flags | Description | +| --- | --- | --- | +| 0..6 | Reserved | Reserved | +| 7 | Listening flag | This bit indicates if the node should be an Always Listening Node. (AL Node) The value 0 MUST indicate that the node MUST NOT be AL (either NL or FL) The value 1 MUST indicate that the node MUST be an AL node. | + +Generic Device Type (8 bits) + +The Generic Device Class field contains an identifier that identifies what Generic Device Class the Z- Wave node MUST advertise and MUST be set by the application. For a detailed description of all [available Generic Device Classes, refer to [ device_class_spec ] for Z-Wave devices, [ device_type_spec ] for Z-Wave Plus devices, and [ device_type_spec_v2 ] for Z-Wave Plus v2 devices.](../../05-references.md#5-references) + +Specific Device Type (8 bits) The Specific Device Class field contains an identifier that identifies what Specific Device Class the Z- Wave node MUST advertise and MUST be set by the application. For a detailed description of all [available Generic Device Classes, refer to [ device_class_spec ] for Z-Wave devices, [ device_type_spec ] for Z-Wave Plus devices, and [ device_type_spec_v2 ] for Z-Wave Plus v2 devices.](../../05-references.md#5-references) + +Command Class List Length (8 bits) + +This field MUST specify the length of the Command Class List field in bytes. + +Command Class List (N bytes) + +This field is used to advertise the list of supported Command Classes by the node. The length of this field MUST be according to the Command Class List Length field. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.02.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.02.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..bc0b1c6 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.02.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.3.2.3 2. Response data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.02.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.02.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..39dd2a4 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.02.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.3.2.4 3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.03-set-application-node-information-command-classes-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.03-set-application-node-information-command-classes-command.md new file mode 100644 index 0000000..bd821b4 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.03-set-application-node-information-command-classes-command.md @@ -0,0 +1,18 @@ + +# 4.3.3 Set Application Node Information Command Classes Command + +This command is used to configure the list of supported Command Classes for each of the following inclusion states: + +• Not included in a network + +• Included: Non-securely supported + +• Included: Securely supported + +The Set Application Node Information Command Classes Command Identifier is 0x0C. This command [MUST only be supported by a Z-Wave Module that employs End Node libraries (Refer to Get Library Version Command - Library Type encoding ).](04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.03.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.03.01-frame-flow.md new file mode 100644 index 0000000..9d407d2 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.03.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.3.3.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.03.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.03.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..8cd7856 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.03.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,48 @@ + +# 4.3.3.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.16 .](04.03.03.02-1-initial-data-frame-host-z-wave-module.md#4332-1-initial-data-frame-host-z-wave-module) + +Table 4.16: Set Application Node Information Command Classes Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0C | | | | | | | | +| 5 | Not Included Node Parameter Length | | | | | | | | +| 6 | Not Included Node Parameter 1 | | | | | | | | +| .. | . . . | | | | | | | | +| 6+N | Not Included Node Parameter N | | | | | | | | +| 7+N | Non-securely Included Node Parameter length | | | | | | | | +| 7+N+1 | Non-securely Included Node Parameter 1 | | | | | | | | +| .. | . . . | | | | | | | | +| 7+N+M | Non-securely Included Node Parameter M | | | | | | | | +| 8+N+M | Securely Included Node Parameter length | | | | | | | | +| 8+N+M+1 | Securely Included Node Parameter 1 | | | | | | | | +| .. | . . . | | | | | | | | +| 8+N+M+G | Securely Included Node Parameter G | | | | | | | | + +Not Included Node Parameter Length (8 bits) + +This field MUST specify the length of the Not Included Node Parameter field in bytes. + +Not Included Node Parameter (N bytes) + +This field is used to advertise the list of supported Command Classes before the node is included in a Z-Wave Network. Non-securely Included Node Parameter Length (8 bits) + +This field MUST specify the length of the Non-securely Included Node Parameter field in bytes. Non-securely Included Node Parameter (M bytes) + +This field is used to advertise the list of non-securely supported Command Classes after the node is included in a Z-Wave Network. + +Securely Included Node Parameter Length (8 bits) + +This field MUST specify the length of the Securely Included Node Parameter field in bytes. + +Securely Included Node Parameter (G bytes) + +This field is used to advertise the list of securely supported Command Classes after the node is included in a Z-Wave Network. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.03.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.03.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..d1e2563 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.03.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,21 @@ + +# 4.3.3.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.17 .](04.03.03.03-2-response-data-frame-z-wave-module-host.md#4333-2-response-data-frame-z-wave-module-host) + +Table 4.17: Set Application Node Information Command Classes Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0C | | | | | | | | +| 5 | Command Status | | | | | | | | + +Command Status (8 bits) + +[Refer to Command Status (8 bits) .](../04.02-generic-command-elements.md#426-command-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.03.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.03.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..fd5692b --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.03.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.3.3.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.04-get-controller-capabilities-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.04-get-controller-capabilities-command.md new file mode 100644 index 0000000..de04d0f --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.04-get-controller-capabilities-command.md @@ -0,0 +1,12 @@ + +# 4.3.4 Get Controller Capabilities Command + +This command is used to request a controller from its current network capabilities. + +The Get Controller Capabilities Command Identifier is 0x05 diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.04.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.04.01-frame-flow.md new file mode 100644 index 0000000..302a9fd --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.04.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.3.4.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.04.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.04.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..f8aaf53 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.04.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,16 @@ + +# 4.3.4.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.18](04.03.04.02-1-initial-data-frame-host-z-wave-module.md#4342-1-initial-data-frame-host-z-wave-module) + +Table 4.18: Get Controller Capabilities Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x05 | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.04.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.04.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..6ca43d1 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.04.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,31 @@ + +# 4.3.4.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.19](04.03.04.03-2-response-data-frame-z-wave-module-host.md#4343-2-response-data-frame-z-wave-module-host) + +Table 4.19: Get Controller Capabilities Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x05 | | | | | | | | +| 5 | Z-Wave API Controller Capabilities | | | | | | | | + +Z-Wave API Controller Capabilities (8 bits) + +This field is used to advertise the Controller capabilities in the current network. This field MUST be [treated as a bitmask and encoded according to Table 4.20](04.03.04.03-2-response-data-frame-z-wave-module-host.md#4343-2-response-data-frame-z-wave-module-host) Table 4.20: Get Controller Capabilities Command - Z-Wave API Controller Capabilities encoding + +| Bit | Flag | Description | +| --- | --- | --- | +| 0 | Secondary Controller | This bit indicates if the Z-Wave Module has the secondary controller role. • The value 0 MUST indicate that the Z-Wave module has the Primary Controller role. • The value 1 MUST indicate that the Z-Wave module has the Secon- dar Controller role. | +| 1 | Other net- work | This bit indicates if the module has been included on another network and did not start the current network. • The value 0 MUST indicate that the Z-Wave module has started the current network. • The value 1 MUST indicate that the Z-Wave module has not started the current network. | +| 2 | SIS is present | This bit indicates if a SIS is present in the current network. • The value 0 MUST indicate that a SIS is not present in the current network. • The value 1 MUST indicate that a SIS is present in the current net- work. | +| 3 | Reserved | This bit should be ignored. | +| 4 | SUC en- abled | This bit indicates if the module provides the SUC functionality in the cur- rent network. • The value 0 MUST indicate that the Z-Wave module does not have the SUC functionality enabled in this network. • The value 1 MUST indicate that the Z-Wave module has the SUC functionality enabled in this network. | +| 5 | No nodes in- cluded | This bit indicates if the module is the only node in the network. • The value 0 MUST indicate that the Z-Wave module is the only node in the network. • The value 1 MUST indicate that the Z-Wave module is not the only node in the network. | +| 6..7 | Reserved | These bits are reserved. Reserved bits MUST NOT be used and MUST be ignored by a receiving interface. | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.04.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.04.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..7b82acc --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.04.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.3.4.4 3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.05-get-capabilities-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.05-get-capabilities-command.md new file mode 100644 index 0000000..5f1221f --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.05-get-capabilities-command.md @@ -0,0 +1,10 @@ + +# 4.3.5 Get Capabilities Command + +This command is used to request the API capabilities of a Z-Wave Module. The Get Capabilities Com- mand identifier is 0x07. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.05.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.05.01-frame-flow.md new file mode 100644 index 0000000..c603dfd --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.05.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.3.5.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.05.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.05.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..c703c95 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.05.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,16 @@ + +# 4.3.5.2 1. Initial data frame (host → Z-Wave Module) + +[This Command MUST be formatted according to Table 4.21](04.03.05.02-1-initial-data-frame-host-z-wave-module.md#4352-1-initial-data-frame-host-z-wave-module) + +Table 4.21: Get Capabilities Command + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x07 | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.05.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.05.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..b21e7be --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.05.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,67 @@ + +# 4.3.5.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.22](04.03.05.03-2-response-data-frame-z-wave-module-host.md#4353-2-response-data-frame-z-wave-module-host) + +Table 4.22: Get Capabilities Command + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x07 | | | | | | | | +| 5 | Z-Wave API version | | | | | | | | +| 6 | Z-Wave API revision | | | | | | | | +| 7 | Z-Wave API manufacturer ID 1 (MSB) | | | | | | | | +| 8 | Z-Wave API manufacturer ID 2 (LSB) | | | | | | | | +| 9 | Z-Wave API Product Type 1 (MSB) | | | | | | | | +| 10 | Z-Wave API Product Type 2 (LSB) | | | | | | | | +| 11 | Z-Wave API Product ID 1 (MSB) | | | | | | | | +| 12 | Z-Wave API Product ID 2 (LSB) | | | | | | | | +| 12+1 | Supported Z-Wave API Commands Bitmask 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 12+N | Supported Z-Wave API Commands Bitmask N | | | | | | | | + +Z-Wave API version (8 bits) + +This field is used to advertise the Z-Wave API application version number. + +Z-Wave API revision (8 bits) + +This field is used to advertise the Z-Wave API application revision number. + +Z-Wave API manufacturer ID (16 bits) This field is used to define the Manufacturer ID for the Z-Wave Module. Refer to [[ zwave_manufacturer_ids ] for details.](../../05-references.md#5-references) + +Z-Wave API Product Type (16 bits) This field is used to advertise the Product Type of the Z-Wave Module. A host application MAY use its own Product Type in the Manufacturer Specific Command Class Refer to the Manufacturer Specific [Command Class in [ zwave_management_cc_spec ]](../../05-references.md#5-references) + +Z-Wave API Product ID (16 bits) + +This field is used to advertise the Product ID of the Z-Wave Module. A host application MAY use its own Product ID in the Manufacturer Specific Command Class Refer to the Manufacturer Specific Command [Class in [ zwave_management_cc_spec ]](../../05-references.md#5-references) + +Supported Z-Wave API commands bitmask (N bytes) + +This field is used to advertise the list of Z-Wave API commands supported by the Z-Wave Module. + +This field MUST encoded as a bitmask and interpreted as follow: + +• bit 0 in byte 13 MUST represent the Z-Wave API Command ID 1. + +• bit 1 in byte 13 MUST represent the Z-Wave API Command ID 2. + +•. . . + +• bit 7 in byte 13 MUST represent the Z-Wave API Command ID 8. + +• bit 0 in byte 14 MUST represent the Z-Wave API Command ID 9. + +• etc. + +Each of the bits MUST be intepreted as follow: + +• A bit set to 1 MUST indicate that the corresponding Z-Wave API Command is supported. + +• A bit set to 0 MUST indicate that the corresponding Z-Wave API Command is not supported. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.05.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.05.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..810c6c4 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.05.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.3.5.4 3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.06-get-long-range-nodes-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.06-get-long-range-nodes-command.md new file mode 100644 index 0000000..082b5c7 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.06-get-long-range-nodes-command.md @@ -0,0 +1,14 @@ + +# 4.3.6 Get Long Range Nodes Command + +This command is used to request the list of Z-Wave Long Range nodes. The Get Long Range Nodes Command Identifier is 0xDA. + +There can be up to 4000 nodes a Z-Wave Long Range network. Nodes with NodeIDs smaller or equal to 255 can be retrieved using the Get Init Data Command. NodeIDs higher than 255 can be read using this command. The full list of NodeIDs (from 256 to 4000) can be represented using a bitmask of 3745 bits, which can be comprised in 467 bytes. + +This amount may too large to be sent in a single command, and an offset mechanism is used to fetch the full list. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.06.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.06.01-frame-flow.md new file mode 100644 index 0000000..528f0ed --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.06.01-frame-flow.md @@ -0,0 +1,12 @@ + +# 4.3.6.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response . This command may require](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) multiple initial data frames and response data frames in order to read the full list. An example is shown [in Figure 4.1](../../03-interface-communication/03.03-command-frame-flows.md#331-unacknowledged-frame) + +![Figure 4.1: Reading the Z-Wave Long Range Node List (Example)](assets/img-df71f5c43a.png) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.06.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.06.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..2d77987 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.06.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,23 @@ + +# 4.3.6.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.23 .](04.03.06.02-1-initial-data-frame-host-z-wave-module.md#4362-1-initial-data-frame-host-z-wave-module) + +Table 4.23: Get Long Range Nodes Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xDA | | | | | | | | +| 5 | Long Range Node List Start Offset | | | | | | | | + +Long Range Node List Start Offset (8 bits) + +This field is used to indicate the number of bytes offset for which the Z-Wave Long Range node list must start from. + +A Z-Wave API Module MUST return a Response Data frame with the same Long Range Node List Start Offset. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.06.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.06.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..ff08ac7 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.06.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,88 @@ + +# 4.3.6.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.24 .](04.03.06.03-2-response-data-frame-z-wave-module-host.md#4363-2-response-data-frame-z-wave-module-host) + +Table 4.24: Get Long Range Nodes Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xDA | | | | | | | | +| 5 | More Nodes | | | | | | | | +| 6 | Long Range Node List Start Offset | | | | | | | | +| 7 | Long Range Node List Length | | | | | | | | +| 7+1 | Long Range Node List 1 | | | | | | | | +| .. | . . . | | | | | | | | +| 7+N | Long Range Node List N | | | | | | | | + +More Nodes (8 bits) + +This field is used to indicate if the Z-Wave API Module has advertised the last Z-Wave Long Range NodeID in the current response + +This field MUST be set to 0 if the highest Z-Wave Long Range NodeID is advertised in the Long Range Node List field. This field MUST be set to 1 if there exist a Z-Wave Long Range node with a higher NodeID than what is advertised in the Long Range Node List field. + +A host application receiving a response data frame with this field set to 1 SHOULD issue an initial data frame again with an increment of the last Long Range Node List Start Offset [. Refer to Figure 4.1 for](../../03-interface-communication/03.03-command-frame-flows.md#331-unacknowledged-frame) details. + +Long Range Node List Start Offset (8 bits) + +This field is used to indicate index where the Long Range Node List start from. Each unit in this field’s value represent a 128-byte offset. For instance: + +• The value 1 represents 1x128 = 128 bytes. + +• The value 2 represents 2x128 = 256 bytes. • The value 3 represents 3x128 = 384 bytes + +• etc. + +Long Range Node List Length (8 bits) + +This field is used to indicate the length in bytes of the Long Range Node List field. + +Long Range Node List (N bytes) + +This field is used to advertise the list of Long Range nodes present in the current network. + +The length of this field, in byte, MUST be according to the Long Range Node List Length field. This field MUST be omitted if the Long Range Node List Length field is set to 0. + +[This field MUST represent NodeIDs as described in ( 4.1 ).](04.03.06.03-2-response-data-frame-z-wave-module-host.md#4363-2-response-data-frame-z-wave-module-host) + +𝑁 𝐽 𝐼 𝑂 × × × (4.1) = 255 + 8 + + 128 8 + +with: + +• N: The NodeID being represented. + +• I: the current bit I number in the current byte (from 0 to 7). + +• J: The current byte (from 0 to Long Range Node List Length -1) + +• O: the value advertised in the Long Range Node List Start Offset field. + +For example, with the Long Range Node List Start Offset field set to 0: + +• Bit 0 in Byte 1 MUST represent NodeID 256 + +• Bit 1 in Byte 1 MUST represent NodeID 257 + +•. . . + +• Bit 0 in Byte 2 MUST represent NodeID 264 + +with the Long Range Node List Start Offset field set to 1: + +• Bit 0 in Byte 1 MUST represent NodeID 1280 + +• Bit 1 in Byte 1 MUST represent NodeID 1281 + +•. . . + +• Bit 0 in Byte 2 MUST represent NodeID 1288 + +The value 0 for a given NodeID MUST indicate that the node is not present in the network. + +The value 1 for a given NodeID MUST indicate that the node is present in the network. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.06.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.06.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..9644054 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.06.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.3.6.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.07-get-z-wave-long-range-channel-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.07-get-z-wave-long-range-channel-command.md new file mode 100644 index 0000000..23abd49 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.07-get-z-wave-long-range-channel-command.md @@ -0,0 +1,10 @@ + +# 4.3.7 Get Z-Wave Long Range Channel Command + +This command is used to request which the radio channel is in use for Z-Wave Long Range. The Get Z-Wave Long Range Channel Command Identifier is 0xDB. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.07.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.07.01-frame-flow.md new file mode 100644 index 0000000..0d857e3 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.07.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.3.7.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.07.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.07.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..209945c --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.07.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,16 @@ + +# 4.3.7.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.25](04.03.07.02-1-initial-data-frame-host-z-wave-module.md#4372-1-initial-data-frame-host-z-wave-module) + +Table 4.25: Get Z-Wave Long Range Channel Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xDB | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.07.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.07.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..7533c65 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.07.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,34 @@ + +# 4.3.7.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.26](04.03.07.03-2-response-data-frame-z-wave-module-host.md#4373-2-response-data-frame-z-wave-module-host) + +Table 4.26: Get Z-Wave Long Range Channel Command - Re- sponse data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xDB | | | | | | | | +| 5 | Z-Wave Long Range Channel | | | | | | | | + +Z-Wave Long Range Channel (8 bits) + +This field is used to advertise the currently configured Z-Wave Long Range Channel at the Z-Wave API Module. + +[This field MUST be encoded according to Table 4.27 .](04.03.07.03-2-response-data-frame-z-wave-module-host.md#4373-2-response-data-frame-z-wave-module-host) + +Table 4.27: Get Z-Wave Long Range Channel Command - Z-Wave Long Range Channel Encoding + +| Value | Description | +| --- | --- | +| 0x00 | Reserved. This values is reserved, and reserved values MUST not be used. | +| 0x01 | Z-Wave Long Range Channel A. | +| 0x02 | Z-Wave Long Range Channel B. | + +| 0x03..0xFF | Reserved. These values are reserved, and reserved values MUST not be used. | +| --- | --- | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.07.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.07.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..a37b02d --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.07.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.3.7.4 3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.08-set-z-wave-long-range-channel-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.08-set-z-wave-long-range-channel-command.md new file mode 100644 index 0000000..ebf9b86 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.08-set-z-wave-long-range-channel-command.md @@ -0,0 +1,10 @@ + +# 4.3.8 Set Z-Wave Long Range Channel Command + +This command is used to configure which radio channel to use for Z-Wave Long Range. The Set Z-Wave Long Range Channel Command Identifier is 0xDC. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.08.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.08.01-frame-flow.md new file mode 100644 index 0000000..4213c4f --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.08.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.3.8.1 Frame flow + +[The frame flow for this command is an Acknowledged frame . The execution of this command SHOULD](../../03-interface-communication/03.03-command-frame-flows.md#332-acknowledged-frame) [be verified by a host application by issuing a Get Z-Wave Long Range Channel Command .](04.03.07-get-z-wave-long-range-channel-command.md#437-get-z-wave-long-range-channel-command) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.08.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.08.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..ecddad2 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.08.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,32 @@ + +# 4.3.8.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.28](04.03.08.02-1-initial-data-frame-host-z-wave-module.md#4382-1-initial-data-frame-host-z-wave-module) + +Table 4.28: Set Z-Wave Long Range Channel Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xDC | | | | | | | | +| 5 | Z-Wave Long Range Channel | | | | | | | | + +Z-Wave Long Range Channel (8 bits) + +This field is used to specify the Z-Wave Long Range Channel that the Z-Wave API Module MUST use. + +[This field MUST be encoded according to Table 4.29 .](04.03.08.02-1-initial-data-frame-host-z-wave-module.md#4382-1-initial-data-frame-host-z-wave-module) + +Table 4.29: Set Z-Wave Long Range Channel Command - Z-Wave Long Range Channel Encoding + +| Value | Description | +| --- | --- | +| 0x00 | Reserved. This values is reserved, and reserved values MUST not be used. | +| 0x01 | Z-Wave Long Range Channel A. | +| 0x02 | Z-Wave Long Range Channel B. | +| 0x03..0xFF | Reserved. These values are reserved, and reserved values MUST not be used. | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.08.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.08.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..1508cd8 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.08.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,21 @@ + +# 4.3.8.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.30](04.03.08.03-2-response-data-frame-z-wave-module-host.md#4383-2-response-data-frame-z-wave-module-host) + +Table 4.30: Set Z-Wave Long Range Channel Command - Re- sponse data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | + +| 4 | Z-Wave API Command ID = 0xDC | +| --- | --- | +| 5 | Response status | + +Response Status (8 bits) [Refer to Response status (8 bits) .](../04.02-generic-command-elements.md#425-response-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.08.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.08.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..6999855 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.08.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.3.8.4 3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.09-get-protocol-version-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.09-get-protocol-version-command.md new file mode 100644 index 0000000..edd312e --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.09-get-protocol-version-command.md @@ -0,0 +1,10 @@ + +# 4.3.9 Get Protocol Version Command + +This command is used to request the Z-Wave Protocol version data. The Get Protocol Version Command Identifier is 0x09. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.09.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.09.01-frame-flow.md new file mode 100644 index 0000000..162fcb0 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.09.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.3.9.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.09.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.09.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..75b80a3 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.09.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,16 @@ + +# 4.3.9.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.31](04.03.09.02-1-initial-data-frame-host-z-wave-module.md#4392-1-initial-data-frame-host-z-wave-module) + +Table 4.31: Get Protocol Version Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x09 | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.09.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.09.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..93f7002 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.09.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,60 @@ + +# 4.3.9.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.32 .](04.03.09.03-2-response-data-frame-z-wave-module-host.md#4393-2-response-data-frame-z-wave-module-host) + +A host application MUST be resistant to unexpected lengths (too short or too small) for this command. + +Table 4.32: Get Protocol Version Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x09 | | | | | | | | +| 5 | Z-Wave Protocol Type | | | | | | | | +| 6 | Z-Wave Protocol Major Version Number | | | | | | | | +| 7 | Z-Wave Protocol Minor Version Number | | | | | | | | +| 8 | Z-Wave Protocol Revision Version Number | | | | | | | | +| 9 | Z-Wave Application Framework Build Number (MSB) | | | | | | | | +| 10 | Z-Wave Application Framework Build Number (LSB) | | | | | | | | +| 11 | Git Commit hash 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 26 | Git Commit hash 16 | | | | | | | | + +Z-Wave Protocol Type (8 bits) + +[This field is used to indicate the protocol type. This field MUST be encoded according to Table 4.166 .](../04.04-z-wave-api-network-management-commands/04.04.03.22-set-virtual-node-to-learn-mode-command.md#44322-set-virtual-node-to-learn-mode-command) Table 4.33: Z-Wave Get Protocol Version Command - Z-Wave Protocol Type Encoding + +| Value | Description | +| --- | --- | +| 0x00 | Z-Wave Protocol. | +| 0x01 | Z-Wave AV Protocol. This value SHOULD NOT be used by any Z-Wave API Module. | +| 0x02 | Z-Wave for IP Protocol This value SHOULD NOT be used by any Z-Wave API Module. | +| 0x03..0xFF | Reserved. These options are reserved, and reserved values MUST not be used. | + +Z-Wave Protocol Major Version Number (8 bits) + +This field is used to advertise the Major Version Number for the Z-Wave Protocol. This field MUST be encoded as an unsigned integer. + +Z-Wave Protocol Minor Version Number (8 bits) + +This field is used to advertise the Minor Version Number for the Z-Wave Protocol. This field MUST be encoded as an unsigned integer. + +Z-Wave Protocol Revision Version Number (8 bits) + +This field is used to advertise the Revision Version Number for the Z-Wave Protocol. This field MUST be encoded as an unsigned integer. + +Z-Wave Application Framework Build Number (16 bits) + +This field is used to advertise the Revision Version Number for the Z-Wave Protocol. This field MUST be encoded as an unsigned integer. + +The value 0 MUST indicate that this value is not available. Values in the range 1..65535 MUST indicate the build number for the application framework. + +Git commit hash (16 bytes) + +This field is used to advertise the git commit hash for the Z-Wave Protocol running in the Z-Wave API Module. This field SHOULD be omitted or zeroed out if this information is not available. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.09.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.09.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..d1ed13a --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.09.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.3.9.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.10-get-library-version-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.10-get-library-version-command.md new file mode 100644 index 0000000..712e7ca --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.10-get-library-version-command.md @@ -0,0 +1,10 @@ + +# 4.3.10 Get Library Version Command + +This command is used to request the Z-Wave library basis version that runs on a Z-Wave Module. The Get Library Command Identifier is 0x15. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.10.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.10.01-frame-flow.md new file mode 100644 index 0000000..4da1903 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.10.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.3.10.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.10.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.10.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..fe061d0 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.10.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,16 @@ + +# 4.3.10.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.34](04.03.10.02-1-initial-data-frame-host-z-wave-module.md#43102-1-initial-data-frame-host-z-wave-module) + +Table 4.34: Get Library Version Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x15 | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..6c03e22 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,43 @@ + +# 4.3.10.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.35](04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) + +Table 4.35: Get Library Version Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x15 | | | | | | | | +| 5 | Z-Wave Library Version 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 17 | Z-Wave Library Version 12 | | | | | | | | +| 18 | Library Type | | | | | | | | + +Z-Wave Library Version (12 bytes) + +This field is used to advertise the Z-Wave API library version that runs on the Z-Wave Module using the following text format: + +• Z-Wave x.y, where x and y are the major and minor library versions, respectively. + +Library Type (8 bits) + +This field is used to advertise the library type that runs on the Z-Wave Module. + +[This field MUST encoded according to Table 4.36](04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) Table 4.36: Get Library Version Command - Library Type encod- ing + +| Value | Networking type | Library Type | +| --- | --- | --- | +| 0x01 | Controller node | Static Controller library This library is intended for main home controllers, that are typically Primary controllers in a network. | +| 0x02 | Controller node | Portable Controller library This library is intended for small portable controllers, that are typically secondary controllers or inclusion controllers in a network. | +| 0x03 | End node | Enhanced 232 End Node Library This library is intended for end nodes. | +| 0x04 | End node | End Node library This library is intended for end nodes with more lim- ited capabilities than the Enhanced 232 End Node Library. New implementations SHOULD use the Enhanced 232 End Node Library | +| 0x05 | Controller node | Installer library This library is intended for controllers nodes used for setup and monitoring of existing networks. | +| 0x06 | End node | Routing End Node library This library is intended for end nodes with routing capa- bilities. New implementations SHOULD use the Enhanced 232 End Node Library | +| 0x07 | Controller node | Bridge controller library This library is intended for controller nodes that are able to allocate more than 1 NodeID to themselves and use them for transmitting/receiving frames. | +| 0x08..0xFF | Reserved | Reserved Reserved values MUST NOT be used and MUST be ig- nored by a receiving interface | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.10.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.10.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..f51e14e --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.10.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.3.10.4 3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.11-get-library-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.11-get-library-command.md new file mode 100644 index 0000000..08d4b7f --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.11-get-library-command.md @@ -0,0 +1,10 @@ + +# 4.3.11 Get Library Command + +This command is used to is used to request the Z-Wave library type that runs on a Z-Wave Module. The Get Library Command Identifier is 0xBD. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.11.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.11.01-frame-flow.md new file mode 100644 index 0000000..ec92893 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.11.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.3.11.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.11.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.11.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..dfc5875 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.11.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,16 @@ + +# 4.3.11.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.37](04.03.11.02-1-initial-data-frame-host-z-wave-module.md#43112-1-initial-data-frame-host-z-wave-module) + +Table 4.37: Get Library Type Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xBD | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.11.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.11.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..ab28e82 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.11.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,23 @@ + +# 4.3.11.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.38](04.03.11.03-2-response-data-frame-z-wave-module-host.md#43113-2-response-data-frame-z-wave-module-host) + +Table 4.38: Get Library Type Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xBD | | | | | | | | +| 5 | Library Type | | | | | | | | + +Library Type (8 bits) + +This field is used to advertise the library type that runs on the Z-Wave Module. + +[This field MUST encoded according to Table 4.36](04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.11.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.11.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..9ba4c9f --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.11.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.3.11.4 3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.12-soft-reset-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.12-soft-reset-command.md new file mode 100644 index 0000000..3505471 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.12-soft-reset-command.md @@ -0,0 +1,10 @@ + +# 4.3.12 Soft Reset Command + +This command is used to request the Z-Wave Module to perform a soft reset. The Soft Reset Command Identifier is 0x08. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.12.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.12.01-frame-flow.md new file mode 100644 index 0000000..4ae650b --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.12.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.3.12.1 Frame flow + +[The frame flow for this command is an Acknowledged frame .](../../03-interface-communication/03.03-command-frame-flows.md#332-acknowledged-frame) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.12.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.12.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..07631f4 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.12.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,16 @@ + +# 4.3.12.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.39](04.03.12.02-1-initial-data-frame-host-z-wave-module.md#43122-1-initial-data-frame-host-z-wave-module) + +Table 4.39: Soft Reset Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x08 | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.12.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.12.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..9c657df --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.12.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.3.12.3 2. Response data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.12.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.12.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..f992da0 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.12.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,12 @@ + +# 4.3.12.4 3. Callback data frame (Z-Wave Module → host) + +None. + +Note: [A Z-Wave Module SHOULD issue a Z-Wave API Started Command when it has completed the](../04.07-unsolicited-z-wave-api-commands.md#472-z-wave-api-started-command) reset operation. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.13-set-default-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.13-set-default-command.md new file mode 100644 index 0000000..fd0836b --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.13-set-default-command.md @@ -0,0 +1,12 @@ + +# 4.3.13 Set Default Command + +This command is used to set the Z-Wave API Module to its default state. It means that the Z-Wave API Module will leave its current network and erase all information related to its current Z-Wave network (topology, network keys, HomeID, etc.). + +The Set Default Command Identifier is 0x42. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.13.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.13.01-frame-flow.md new file mode 100644 index 0000000..4fe3f90 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.13.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.3.13.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with callback .](../../03-interface-communication/03.03-command-frame-flows.md#334-acknowledged-frame-with-callback) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.13.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.13.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..55b00b2 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.13.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,21 @@ + +# 4.3.13.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.40 .](04.03.13.02-1-initial-data-frame-host-z-wave-module.md#43132-1-initial-data-frame-host-z-wave-module) + +Table 4.40: Set Default Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x42 | | | | | | | | +| 5 | Session identifier | | | | | | | | + +[Session identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.13.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.13.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..11a8ad5 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.13.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.3.13.3 2. Response data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.13.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.13.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..28305ac --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.13.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,21 @@ + +# 4.3.13.4 3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.41 after the Z-Wave](04.03.13.04-3-callback-data-frame-z-wave-module-host.md#43134-3-callback-data-frame-z-wave-module-host) API Module has completed the set default operation. + +Table 4.41: Set Default Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x42 | | | | | | | | +| 5 | Session identifier | | | | | | | | + +Session identifier (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.14-setup-z-wave-api-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.14-setup-z-wave-api-command.md new file mode 100644 index 0000000..8bd071f --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.14-setup-z-wave-api-command.md @@ -0,0 +1,12 @@ + +# 4.3.14 Setup Z-Wave API Command + +This command is used to request and configure the Z-Wave Module and its API. The Setup Z-Wave API Command Identifier is 0x0B. + +This command contains sub-commands. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.14.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.14.01-frame-flow.md new file mode 100644 index 0000000..a32315c --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.14.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.3.14.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.14.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.14.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..6cc16eb --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.14.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,30 @@ + +# 4.3.14.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.42 .](04.03.14.02-1-initial-data-frame-host-z-wave-module.md#43142-1-initial-data-frame-host-z-wave-module) + +Table 4.42: Setup Z-Wave API Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command | | | | | | | | +| 5+1 | Sub Command Payload 1 | | | | | | | | +| .. | . . . | | | | | | | | +| 5+N | Sub Command Payload N | | | | | | | | + +Sub Command (8 bits) + +This field is used to advertise the Z-Wave API Setup Sub Command. The list of available Sub Commands [are available in Z-Wave API Setup sub-commands .](04.03.15-z-wave-api-setup-sub-commands.md#4315-z-wave-api-setup-sub-commands) + +Sub Command Payload (N bytes) + +This field is used to indicate the data payload that corresponds to a given Z-Wave API setup Sub Com- mand defined in Command field. + +Each Sub Command payload MUST be interpreted in conjunction with the actual Sub Command. refer [to Z-Wave API Setup sub-commands .](04.03.15-z-wave-api-setup-sub-commands.md#4315-z-wave-api-setup-sub-commands) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.14.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.14.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..2c27f5e --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.14.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,34 @@ + +# 4.3.14.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.43 .](04.03.14.03-2-response-data-frame-z-wave-module-host.md#43143-2-response-data-frame-z-wave-module-host) + +Table 4.43: Setup Z-Wave API Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command | | | | | | | | +| 5+1 | Sub Command Payload 1 | | | | | | | | +| .. | . . . | | | | | | | | + +| 5+N | Sub Command Payload N | +| --- | --- | + +Command (8 bits) This field is used to advertise the Z-Wave API Setup Sub Command. The list of available Sub Commands [are available in Z-Wave API Setup sub-commands .](04.03.15-z-wave-api-setup-sub-commands.md#4315-z-wave-api-setup-sub-commands) + +A Z-Wave API module that has received a non-supported Z-Wave API Setup Sub Command MUST [return the value 0 in this field. Refer to Z-Wave API Setup Get Supported Commands Sub Command for](04.03.15.01-z-wave-api-setup-get-supported-commands-sub-command.md#43151-z-wave-api-setup-get-supported-commands-sub-command) the list of supported Z-Wave API setup commands. + +The value 0 MUST indicate that the received Z-Wave API setup sub command in the Initial data frame is not supported. If this field is set to 0, the Sub Command Payload field MUST be 1 byte long and MUST be set to the unsupported Z-Wave API Setup Sub Command received in the Initial data frame + +Sub Command Payload (N bytes) + +This field is used to indicate the data payload that corresponds to a given Z-Wave API setup Sub Com- mand defined in Command field. + +Each Sub Command payload MUST be interpreted in conjunction with the actual Sub Command. refer [to Z-Wave API Setup sub-commands .](04.03.15-z-wave-api-setup-sub-commands.md#4315-z-wave-api-setup-sub-commands) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.14.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.14.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..e5002bb --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.14.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.3.14.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15-z-wave-api-setup-sub-commands.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15-z-wave-api-setup-sub-commands.md new file mode 100644 index 0000000..ce65451 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15-z-wave-api-setup-sub-commands.md @@ -0,0 +1,10 @@ + +# 4.3.15 Z-Wave API Setup sub-commands + +[This section describes subcommands of the Setup Z-Wave API Command that are used to configure the](04.03.14-setup-z-wave-api-command.md#4314-setup-z-wave-api-command) Z-Wave module. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.01-z-wave-api-setup-get-supported-commands-sub-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.01-z-wave-api-setup-get-supported-commands-sub-command.md new file mode 100644 index 0000000..bd093f7 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.01-z-wave-api-setup-get-supported-commands-sub-command.md @@ -0,0 +1,105 @@ + +# 4.3.15.1 Z-Wave API Setup Get Supported Commands Sub Command + +This command is used to request the list of Z-Wave API Setup Sub Commands that are supported by the Z-Wave API Module. + +The Z-Wave API Setup Get Supported Commands Sub Command Identifier is 0x01 + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.44](04.03.15.01-z-wave-api-setup-get-supported-commands-sub-command.md#43151-z-wave-api-setup-get-supported-commands-sub-command) + +Table 4.44: Z-Wave API Setup Get Supported Commands Sub Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x01 | | | | | | | | + +Sub Command (8 bits) + +[This field MUST be set to 0x01 to indicate the Z-Wave API Setup Get Supported Commands Sub Com- mand .](04.03.15.01-z-wave-api-setup-get-supported-commands-sub-command.md#43151-z-wave-api-setup-get-supported-commands-sub-command) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.45](04.03.15.01-z-wave-api-setup-get-supported-commands-sub-command.md#43151-z-wave-api-setup-get-supported-commands-sub-command) + +Table 4.45: Z-Wave API Setup Get Supported Commands Sub Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x01 | | | | | | | | +| 6 | Z-Wave API Setup Supported Sub Commands flags | | | | | | | | +| 6+1 | Extended Z-Wave API Setup Supported Sub Commands bitmask 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 6+N | Extended Z-Wave API Setup Supported Sub Commands bitmask N | | | | | | | | + +Sub Command (8 bits) + +[This field MUST be set to 0x01 to indicate the Z-Wave API Setup Get Supported Commands Sub Com- mand .](04.03.15.01-z-wave-api-setup-get-supported-commands-sub-command.md#43151-z-wave-api-setup-get-supported-commands-sub-command) + +Z-Wave API Setup Supported Sub Commands flags (8 bits) + +This field is used to indicate the list of supported Z-Wave API setup Sub Commands by the Z-Wave Module. This field can only advertise support for functions that have identifiers that are powers of 2. + +[This field MUST be encoded as a bitmask and according to Table 4.46](04.03.15.01-z-wave-api-setup-get-supported-commands-sub-command.md#43151-z-wave-api-setup-get-supported-commands-sub-command) + +• A bit set to 0 MUST indicate that the corresponding Z-Wave API Setup Sub Command is not supported. + +• A bit set to 1 MUST indicate that the corresponding Z-Wave API Setup Sub Command is sup- ported + +Table 4.46: Z-Wave API Setup Get Supported Commands - Sup- ported Sub Commands encoding + +| Bit num- ber | Description | +| --- | --- | +| 0 | This bit represents the Z-Wave API Setup Get Supported Commands Sub Command. | +| 1 | This bit represents the Z-Wave API Setup Set Tx Status Report Sub Command. | +| 2 | This bit represents the Z-Wave API Setup Set Powerlevel Sub Command. | +| 3 | This bit represents the Z-Wave API Setup Get Powerlevel Sub Command. | +| 4 | This bit represents the Z-Wave API Setup Get Maximum Payload Size Sub Command. | +| 5 | This bit represents the Z-Wave API Setup Get RF Region Sub Command. | +| 6 | This bit represents the Z-Wave API Setup Set RF Region Sub Command. | +| 7 | This bit represents the Z-Wave API Setup Set NodeID Base Type Sub Command. | + +Extended Z-Wave API Setup Supported Sub Commands bitmask (N bytes) + +This field is used to advertise the list of supported Sub Commands. + +If this field is not present in the response data frame sent by a Z-Wave API Module, a host applica- tion MUST assume that only the sub commands advertised in the Z-Wave API Setup Supported Sub Commands flags field are supported. + +This field MUST be treated as a bitmask and MUST be encoded as follow: + +• Bit 0 in Byte 1 MUST represent Sub Command Identifier 1. + +• Bit 1 in Byte 1 MUST represent Sub Command Identifier 2. + +• Bit 2 in Byte 1 MUST represent Sub Command Identifier 3. + +•. . . + +• Bit 7 in Byte 1 MUST represent Sub Command Identifier 8. • Bit 0 in Byte 2 MUST represent Sub Command Identifier 9. + +• Bit 1 in Byte 2 MUST represent Sub Command Identifier 10. + +• Bit 2 in Byte 2 MUST represent Sub Command Identifier 11. + +•. . . + +The list of supported Commands in the Z-Wave API Setup Supported Sub Commands bitmask field MUST also be advertised as supported in this field. + +The length of this field MUST be set to at least the minimum length that allows to advertise all supported Z- Wave API Setup Sub Commands. The length of this field can be calculated from the total length of the response data frame. + +3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.02-z-wave-api-setup-set-tx-status-report-sub-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.02-z-wave-api-setup-set-tx-status-report-sub-command.md new file mode 100644 index 0000000..db97516 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.02-z-wave-api-setup-set-tx-status-report-sub-command.md @@ -0,0 +1,64 @@ + +# 4.3.15.2 Z-Wave API Setup Set Tx Status Report Sub Command + +This command is used to configure the Z-Wave API Module to return detailed Tx Status Report after sending a frame to a destination. + +The Z-Wave API Setup Set Tx Status Report Sub Command Identifier is 0x02 + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.47](04.03.15.02-z-wave-api-setup-set-tx-status-report-sub-command.md#43152-z-wave-api-setup-set-tx-status-report-sub-command) + +Table 4.47: Z-Wave API Setup Set Tx Status Report Sub Com- mand - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x02 | | | | | | | | +| 6 | Enable Tx Status Report | | | | | | | | + +Sub Command (8 bits) + +[This field MUST be set to 0x02 to indicate the Z-Wave API Setup Set Tx Status Report Sub Command](04.03.15.02-z-wave-api-setup-set-tx-status-report-sub-command.md#43152-z-wave-api-setup-set-tx-status-report-sub-command) Command. + +Enable Tx Status Report (8 bits) + +This field is used to indicate if the Tx Status Report MUST be enabled. + +• The value 0x00 MUST indicate that the Tx Status Report MUST NOT be enabled. + +• All other values MUST indicate that the Tx Status Report MUST be enabled. + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.48](04.03.15.02-z-wave-api-setup-set-tx-status-report-sub-command.md#43152-z-wave-api-setup-set-tx-status-report-sub-command) + +Table 4.48: Z-Wave API Setup Set Tx Status Report Sub Com- mand - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x02 | | | | | | | | +| 6 | Command Status | | | | | | | | + +Sub Command (8 bits) + +[This field MUST be set to 0x02 to indicate the Z-Wave API Setup Set Tx Status Report Sub Command .](04.03.15.02-z-wave-api-setup-set-tx-status-report-sub-command.md#43152-z-wave-api-setup-set-tx-status-report-sub-command) + +Command Status (8 bits) This field is used to indicate if the setting indicated in the inital data frame was accepted and applied. + +[This field MUST be encoded according to Command Status (8 bits)](../04.02-generic-command-elements.md#426-command-status-8-bits) + +3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.03-z-wave-api-setup-set-powerlevel-sub-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.03-z-wave-api-setup-set-powerlevel-sub-command.md new file mode 100644 index 0000000..3cbee1e --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.03-z-wave-api-setup-set-powerlevel-sub-command.md @@ -0,0 +1,125 @@ + +# 4.3.15.3 Z-Wave API Setup Set Powerlevel Sub Command + +This command is used to configure the Tx Powerlevel setting of the Z-Wave API. + +The power levels set by this function will first be used by the Z-Wave protocol next time the module is restarted. + +The Z-Wave API Setup Set Powerlevel Sub Command Identifier is 0x04 + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → [Z-Wave Module)](04.03.05.02-1-initial-data-frame-host-z-wave-module.md#4352-1-initial-data-frame-host-z-wave-module) + +[Z-Wave API version 7 and above: Table 4.21](04.03.05.02-1-initial-data-frame-host-z-wave-module.md#4352-1-initial-data-frame-host-z-wave-module) + +[The initial data frame MUST be formatted according to Table 4.49](04.03.15.03-z-wave-api-setup-set-powerlevel-sub-command.md#43153-z-wave-api-setup-set-powerlevel-sub-command) + +Table 4.49: Z-Wave API Setup Set Powerlevel Sub Command (v7+) - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x04 | | | | | | | | +| 6 | Normal Powerlevel Setting | | | | | | | | +| 7 | Measured 0dBm Powerlevel Setting | | | | | | | | + +[Z-Wave API version 6 and below: Table 4.21](04.03.05.02-1-initial-data-frame-host-z-wave-module.md#4352-1-initial-data-frame-host-z-wave-module) + +[The initial data frame MUST be formatted according to Table 4.50](04.03.15.03-z-wave-api-setup-set-powerlevel-sub-command.md#43153-z-wave-api-setup-set-powerlevel-sub-command) + +Table 4.50: Z-Wave API Setup Set Powerlevel Sub Command (v6-) - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x04 | | | | | | | | +| 6 | NormalPowerCh0 | | | | | | | | +| 7 | NormalPowerCh1 | | | | | | | | +| 8 | NormalPowerCh2 | | | | | | | | +| 9 | LowPowerCh0 | | | | | | | | +| 10 | LowPowerCh1 | | | | | | | | +| 11 | LowPowerCh2 | | | | | | | | + +Sub Command (8 bits) + +[This field MUST be set to 0x04 to indicate the Z-Wave API Setup Set Powerlevel Sub Command .](04.03.15.03-z-wave-api-setup-set-powerlevel-sub-command.md#43153-z-wave-api-setup-set-powerlevel-sub-command) Normal Powerlevel Setting (8 bits) + +This field is used to indicate the requested transmit powerlevel for transmitting Z-Wave Frames. + +This field MUST be expressed in deci dBm and MUST use signed encoding. + +For example: + +• The value 10 MUST represent 1 dBm + +• The value -20 MUST represent -2 dBm + +Measured 0dBm Powerlevel Setting (8 bits) + +This field is used to indicate the output power measured from the antenna when the Normal Powerlevel Setting field is set to 0. + +This field MUST be expressed in deci dBm and MUST use signed encoding. + +For example: + +• The value 10 MUST represent 1 dBm + +• The value -20 MUST represent -2 dBm + +NormalPowerChx (8 bits) + +The power level used when transmitting frames at normal Tx power. This value is vendor specific and should be provided by your stack vendor. + +LowPowerCh0 (8 bits) + +The power level used when transmitting frames at low Tx power + +[This field MUST be formatted according to Table 4.51](04.03.15.03-z-wave-api-setup-set-powerlevel-sub-command.md#43153-z-wave-api-setup-set-powerlevel-sub-command) + +Table 4.51: Z-Wave API Setup Set Powerlevel Sub Command - Low Tx power encoding + +| Value | Description | +| --- | --- | +| 0x3F | NormalPower | +| 0x24 | NormalPower - 2dB | +| 0x1E | NormalPower - 4dB | +| 0x16 | NormalPower - 6dB | +| 0x11 | NormalPower - 8dB | +| 0x0E | NormalPower - 10dB | +| 0x0B | NormalPower - 12dB | +| 0x09 | NormalPower - 14dB | +| 0x07 | NormalPower - 16dB | +| 0x05 | NormalPower - 18dB | +| 0x04 | NormalPower - 20dB | +| 0x03 | NormalPower - 22dB | + +2. Response data frame (Z-Wave Module → host) [A Z-Wave module MUST return a response frame formatted according to Table 4.52 Table 4.52: Z-Wave API Setup Set Powerlevel Sub Command -](04.03.15.03-z-wave-api-setup-set-powerlevel-sub-command.md#43153-z-wave-api-setup-set-powerlevel-sub-command) Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x04 | | | | | | | | +| 6 | Command Status | | | | | | | | + +Sub Command (8 bits) + +[This field MUST be set to 0x04 to indicate the Z-Wave API Setup Set Powerlevel Sub Command .](04.03.15.03-z-wave-api-setup-set-powerlevel-sub-command.md#43153-z-wave-api-setup-set-powerlevel-sub-command) + +Command Status (8 bits) + +This field is used to indicate if the setting indicated in the inital data frame was accepted and applied. + +[This field MUST be encoded according to Command Status (8 bits)](../04.02-generic-command-elements.md#426-command-status-8-bits) + +3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.04-z-wave-api-setup-get-powerlevel-sub-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.04-z-wave-api-setup-get-powerlevel-sub-command.md new file mode 100644 index 0000000..753526b --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.04-z-wave-api-setup-get-powerlevel-sub-command.md @@ -0,0 +1,72 @@ + +# 4.3.15.4 Z-Wave API Setup Get Powerlevel Sub Command + +This command is used to request the Powerlevel setting of the Z-Wave API. + +The Z-Wave API Setup Get Powerlevel Sub Command Identifier is 0x08 + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.53](04.03.15.04-z-wave-api-setup-get-powerlevel-sub-command.md#43154-z-wave-api-setup-get-powerlevel-sub-command) + +Table 4.53: Z-Wave API Setup Get Powerlevel Sub Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x08 | | | | | | | | + +Sub Command (8 bits) + +[This field MUST be set to 0x08 to indicate the Z-Wave API Setup Get Powerlevel Sub Command .](04.03.15.04-z-wave-api-setup-get-powerlevel-sub-command.md#43154-z-wave-api-setup-get-powerlevel-sub-command) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.54](04.03.15.04-z-wave-api-setup-get-powerlevel-sub-command.md#43154-z-wave-api-setup-get-powerlevel-sub-command) + +Table 4.54: Z-Wave API Setup Get Powerlevel Sub Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x08 | | | | | | | | +| 6 | Normal Powerlevel Setting | | | | | | | | +| 7 | Measured 0dBm Powerlevel Setting | | | | | | | | + +Sub Command (8 bits) + +[This field MUST be set to 0x08 to indicate the Z-Wave API Setup Get Powerlevel Sub Command .](04.03.15.04-z-wave-api-setup-get-powerlevel-sub-command.md#43154-z-wave-api-setup-get-powerlevel-sub-command) + +Normal Powerlevel Setting (8 bits) + +This field is used to advertise the currently configured transmit powerlevel for transmitting Z-Wave Frames. + +This field MUST be expressed in deci dBm and MUST use signed encoding. For example: + +• The value 10 MUST represent 1 dBm • The value -20 MUST represent -2 dBm + +Measured 0dBm Powerlevel Setting (8 bits) + +This field is used to indicate the configured output power measured from the antenna when the Normal Powerlevel Setting field is set to 0. + +This field MUST be expressed in deci dBm and MUST use signed encoding. + +For example: + +• The value 10 MUST represent 1 dBm + +• The value -20 MUST represent -2 dBm + +3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.05-z-wave-api-setup-get-maximum-payload-size-sub-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.05-z-wave-api-setup-get-maximum-payload-size-sub-command.md new file mode 100644 index 0000000..1d734ff --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.05-z-wave-api-setup-get-maximum-payload-size-sub-command.md @@ -0,0 +1,55 @@ + +# 4.3.15.5 Z-Wave API Setup Get Maximum Payload Size Sub Command + +This command is used to request the maximum payload that the Z-Wave API Module can accept for transmitting Z-Wave frames. This value depends on the RF Profile. + +The Z-Wave API Setup Get Maximum Payload Size Sub Command Identifier is 0x10 + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.55](04.03.15.05-z-wave-api-setup-get-maximum-payload-size-sub-command.md#43155-z-wave-api-setup-get-maximum-payload-size-sub-command) + +Table 4.55: Z-Wave API Setup Get Maximum Payload Size Sub Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x10 | | | | | | | | + +Sub Command (8 bits) + +[This field MUST be set to 0x10 to indicate the Z-Wave API Setup Get Maximum Payload Size Sub Command .](04.03.15.05-z-wave-api-setup-get-maximum-payload-size-sub-command.md#43155-z-wave-api-setup-get-maximum-payload-size-sub-command) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.56](04.03.15.05-z-wave-api-setup-get-maximum-payload-size-sub-command.md#43155-z-wave-api-setup-get-maximum-payload-size-sub-command) + +Table 4.56: Z-Wave API Setup Get Maximum Payload Size Sub Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x10 | | | | | | | | +| 6 | Maximum Payload Size | | | | | | | | + +Sub Command (8 bits) + +[This field MUST be set to 0x10 to indicate the Z-Wave API Setup Get Maximum Payload Size Sub Command .](04.03.15.05-z-wave-api-setup-get-maximum-payload-size-sub-command.md#43155-z-wave-api-setup-get-maximum-payload-size-sub-command) + +Maximum Payload Size (8 bits) + +This field is used to advertise the Maximum Payload Size, in bytes, supported by the Z-Wave API Module for sending frames. + +Calls to Send Data functions will be ignored if the data length is longer than the value advertised in this field. 3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.06-z-wave-api-setup-get-z-wave-long-range-maximum-payload-size-sub-com-mand.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.06-z-wave-api-setup-get-z-wave-long-range-maximum-payload-size-sub-com-mand.md new file mode 100644 index 0000000..80c819b --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.06-z-wave-api-setup-get-z-wave-long-range-maximum-payload-size-sub-com-mand.md @@ -0,0 +1,55 @@ + +# 4.3.15.6 Z-Wave API Setup Get Z-Wave Long Range Maximum Payload Size Sub Com- mand + +mand + +This command is used to request the maximum payload that the Z-Wave API Module can accept for transmitting Z-Wave Long Range frames. + +Z-Wave API Setup Get Z-Wave Long Range Maximum Payload Size Sub Command Identifier is 0x11 + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.57](04.03.15.06-z-wave-api-setup-get-z-wave-long-range-maximum-payload-size-sub-com-mand.md#43156-z-wave-api-setup-get-z-wave-long-range-maximum-payload-size-sub-com-mand) + +Table 4.57: Z-Wave API Setup Get Z-Wave Long Range Maxi- mum Payload Size Sub Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x11 | | | | | | | | + +Sub Command (8 bits) + +[This field MUST be set to 0x11 to indicate the Z-Wave API Setup Get Z-Wave Long Range Maximum Payload Size Sub Command .](04.03.15.06-z-wave-api-setup-get-z-wave-long-range-maximum-payload-size-sub-com-mand.md#43156-z-wave-api-setup-get-z-wave-long-range-maximum-payload-size-sub-com-mand) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.58](04.03.15.06-z-wave-api-setup-get-z-wave-long-range-maximum-payload-size-sub-com-mand.md#43156-z-wave-api-setup-get-z-wave-long-range-maximum-payload-size-sub-com-mand) + +Table 4.58: Z-Wave API Setup Get Z-Wave Long Range Maxi- mum Payload Size Sub Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x11 | | | | | | | | +| 6 | Z-Wave Long Range Maximum Payload Size | | | | | | | | + +Sub Command (8 bits) + +[This field MUST be set to 0x11 to indicate the Z-Wave API Setup Get Maximum Payload Size Sub Command .](04.03.15.05-z-wave-api-setup-get-maximum-payload-size-sub-command.md#43155-z-wave-api-setup-get-maximum-payload-size-sub-command) + +Z-Wave Long Range Maximum Payload Size (8 bits) This field is used to advertise the Maximum Payload Size, in bytes, supported by the Z-Wave API Module for sending frames using the Z-Wave Long Range protocol. + +Calls to Send Data functions to Z-Wave Long Range NodeID destionations will be ignored if the data length is longer than the value advertised in this field. 3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.07-z-wave-api-setup-get-rf-region-sub-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.07-z-wave-api-setup-get-rf-region-sub-command.md new file mode 100644 index 0000000..1be7afe --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.07-z-wave-api-setup-get-rf-region-sub-command.md @@ -0,0 +1,55 @@ + +# 4.3.15.7 Z-Wave API Setup Get RF Region Sub Command + +This command is used to request the current RF region configured at the Z-Wave API Module. + +The Z-Wave API Setup Get RF Region Sub Command Identifier is 0x20 + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.59](04.03.15.07-z-wave-api-setup-get-rf-region-sub-command.md#43157-z-wave-api-setup-get-rf-region-sub-command) + +Table 4.59: Z-Wave API Setup Get RF Region Sub Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x20 | | | | | | | | + +Sub Command (8 bits) + +[This field MUST be set to 0x20 to indicate the Z-Wave API Setup Get RF Region Sub Command .](04.03.15.07-z-wave-api-setup-get-rf-region-sub-command.md#43157-z-wave-api-setup-get-rf-region-sub-command) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.60](04.03.15.07-z-wave-api-setup-get-rf-region-sub-command.md#43157-z-wave-api-setup-get-rf-region-sub-command) + +Table 4.60: Z-Wave API Setup Get RF Region Sub Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x20 | | | | | | | | +| 6 | RF Region | | | | | | | | + +Sub Command (8 bits) + +[This field MUST be set to 0x20 to indicate the Z-Wave API Setup Get RF Region Sub Command .](04.03.15.07-z-wave-api-setup-get-rf-region-sub-command.md#43157-z-wave-api-setup-get-rf-region-sub-command) + +RF Region (8 bits) + +[This field is used to indicate the current RF Region setting.](../04.02-generic-command-elements.md#429-rf-region-8-bits) + +[This field MUST be encoded according to RF Region (8 bits) and](../04.02-generic-command-elements.md#429-rf-region-8-bits) [Table 4.6](../../03-interface-communication/03.02-frame-types.md#324-can-frame) 3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.08-z-wave-api-setup-set-rf-region-sub-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.08-z-wave-api-setup-set-rf-region-sub-command.md new file mode 100644 index 0000000..5aa3155 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.08-z-wave-api-setup-set-rf-region-sub-command.md @@ -0,0 +1,66 @@ + +# 4.3.15.8 Z-Wave API Setup Set RF Region Sub Command + +This command is used to configure the RF region at the Z-Wave API Module. + +The Z-Wave API Setup Set RF Region Sub Command Identifier is 0x40 + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.61](04.03.15.08-z-wave-api-setup-set-rf-region-sub-command.md#43158-z-wave-api-setup-set-rf-region-sub-command) + +Table 4.61: Z-Wave API Setup Get RF Region Sub Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x40 | | | | | | | | +| 6 | RF Region | | | | | | | | + +Sub Command (8 bits) + +[This field MUST be set to 0x40 to indicate the Z-Wave API Setup Set RF Region Sub Command .](04.03.15.08-z-wave-api-setup-set-rf-region-sub-command.md#43158-z-wave-api-setup-set-rf-region-sub-command) + +RF Region (8 bits) + +[This field is used to indicate the current RF Region setting.](../04.02-generic-command-elements.md#429-rf-region-8-bits) + +[This field MUST be encoded according to RF Region (8 bits) and](../04.02-generic-command-elements.md#429-rf-region-8-bits) [Table 4.6](../../03-interface-communication/03.02-frame-types.md#324-can-frame) + +Note: The RF Region value will be in used by the Z-Wave API Module only after it restarted. A host [application SHOULD issue a Soft Reset Command after configuring the RF Region.](04.03.12-soft-reset-command.md#4312-soft-reset-command) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.62](04.03.15.08-z-wave-api-setup-set-rf-region-sub-command.md#43158-z-wave-api-setup-set-rf-region-sub-command) + +Table 4.62: Z-Wave API Setup Set RF Region Sub Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x40 | | | | | | | | +| 6 | Command Status | | | | | | | | + +Sub Command (8 bits) + +[This field MUST be set to 0x40 to indicate the Z-Wave API Setup Set RF Region Sub Command .](04.03.15.08-z-wave-api-setup-set-rf-region-sub-command.md#43158-z-wave-api-setup-set-rf-region-sub-command) Command Status (8 bits) + +This field is used to indicate if the RF Region setting indicated in the inital data frame was accepted. + +[This field MUST be encoded according to Command Status (8 bits) .](../04.02-generic-command-elements.md#426-command-status-8-bits) + +Note: The RF Region value will be in used by the Z-Wave API Module only after it restarted. A host [application SHOULD issue a Soft Reset Command after configuring the RF Region.](04.03.12-soft-reset-command.md#4312-soft-reset-command) + +3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md new file mode 100644 index 0000000..8e12ae9 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md @@ -0,0 +1,79 @@ + +# 4.3.15.9 Z-Wave API Setup Set NodeID Base Type Sub Command + +This command is used to configure the NodeID base type for the Z-Wave API. + +The Z-Wave API Setup Set NodeID Base Type Sub Command Identifier is 0x80. + +All Z-Wave API Commands MUST use the length defined in this Sub Command for encoding NodeID fields. The default NodeID field length MUST be 8 bits. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.63](04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Table 4.63: Z-Wave API Setup Set NodeID Base Type Sub Com- mand - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x80 | | | | | | | | +| 6 | NodeID Base Type | | | | | | | | + +Sub Command (8 bits) + +[This field is used to indicate the Sub Command within the Z-Wave API Setup Command.](04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be set to 0x80 for the Z-Wave API Setup Set NodeID Base Type Sub Command .](04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +NodeID Base Type (8 bits) + +[This field is used to indicate the desired base type for NodeID fields.](04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to Table 4.64 . All other values are reserved.](04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Table 4.64: Z-Wave API Setup Set NodeID Base Type Sub Com- mand - NodeID Base Type encoding + +| Value | Description | +| --- | --- | +| 0x01 | NodeID fields MUST be 8-bit long. | +| 0x02 | NodeID fields MUST be 16-bit long. | + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.65](04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) Table 4.65: Z-Wave API Setup Set NodeID Base Type Sub Com- mand - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0B | | | | | | | | +| 5 | Sub Command = 0x80 | | | | | | | | +| 6 | Command Status | | | | | | | | + +Sub Command (8 bits) + +This field is used to indicate the Sub Command within the Z-Wave API Setup Command. + +[This field MUST be set to 0x80 for the Z-Wave API Setup Set NodeID Base Type Sub Command .](04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Command Status (8 bits) + +This field is used to indicate if the setting indicated in the inital data frame was accepted and applied. + +[This field MUST be encoded according to Command Status (8 bits)](../04.02-generic-command-elements.md#426-command-status-8-bits) + +• The value 0 MUST indicate that the requested NodeID Base Type in the initial data frame was not accepted or an error occurred. The NodeID Base Type was not applied and is set to the default length. (8-bits) + +• The values 1..255 MUST indicate that the requested NodeID Base Type in the initial data frame was accepted and applied successfully. + +3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/index.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/index.md new file mode 100644 index 0000000..5f91319 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.03-z-wave-capability-api-commands/index.md @@ -0,0 +1,93 @@ + +# 4.3 Z-Wave Capability API commands + +[This section describes Z-Wave API Commands](../index.md#4-z-wave-api-commands) that are used to initialize and configure the Z-Wave module. It also comprises commands that are used to read the supported functionality of the Z-Wave API module. + +## Contents + +- [4.3.1 Get Init Data Command](04.03.01-get-init-data-command.md) +- [4.3.1.1 Frame flow](04.03.01.01-frame-flow.md) +- [4.3.1.2 1. Initial data frame (host → Z-Wave Module)](04.03.01.02-1-initial-data-frame-host-z-wave-module.md) +- [4.3.1.3 2. Response data frame (Z-Wave Module → host)](04.03.01.03-2-response-data-frame-z-wave-module-host.md) +- [4.3.1.4 3. Callback data frame (Z-Wave Module → host)](04.03.01.04-3-callback-data-frame-z-wave-module-host.md) +- [4.3.2 Set Application Node Information Command](04.03.02-set-application-node-information-command.md) +- [4.3.2.1 Frame flow](04.03.02.01-frame-flow.md) +- [4.3.2.2 1. Initial data frame (host → Z-Wave Module)](04.03.02.02-1-initial-data-frame-host-z-wave-module.md) +- [4.3.2.3 2. Response data frame (Z-Wave Module → host)](04.03.02.03-2-response-data-frame-z-wave-module-host.md) +- [4.3.2.4 3. Callback data frame (Z-Wave Module → host)](04.03.02.04-3-callback-data-frame-z-wave-module-host.md) +- [4.3.3 Set Application Node Information Command Classes Command](04.03.03-set-application-node-information-command-classes-command.md) +- [4.3.3.1 Frame flow](04.03.03.01-frame-flow.md) +- [4.3.3.2 1. Initial data frame (host → Z-Wave Module)](04.03.03.02-1-initial-data-frame-host-z-wave-module.md) +- [4.3.3.3 2. Response data frame (Z-Wave Module → host)](04.03.03.03-2-response-data-frame-z-wave-module-host.md) +- [4.3.3.4 3. Callback data frame (Z-Wave Module → host)](04.03.03.04-3-callback-data-frame-z-wave-module-host.md) +- [4.3.4 Get Controller Capabilities Command](04.03.04-get-controller-capabilities-command.md) +- [4.3.4.1 Frame flow](04.03.04.01-frame-flow.md) +- [4.3.4.2 1. Initial data frame (host → Z-Wave Module)](04.03.04.02-1-initial-data-frame-host-z-wave-module.md) +- [4.3.4.3 2. Response data frame (Z-Wave Module → host)](04.03.04.03-2-response-data-frame-z-wave-module-host.md) +- [4.3.4.4 3. Callback data frame (Z-Wave Module → host)](04.03.04.04-3-callback-data-frame-z-wave-module-host.md) +- [4.3.5 Get Capabilities Command](04.03.05-get-capabilities-command.md) +- [4.3.5.1 Frame flow](04.03.05.01-frame-flow.md) +- [4.3.5.2 1. Initial data frame (host → Z-Wave Module)](04.03.05.02-1-initial-data-frame-host-z-wave-module.md) +- [4.3.5.3 2. Response data frame (Z-Wave Module → host)](04.03.05.03-2-response-data-frame-z-wave-module-host.md) +- [4.3.5.4 3. Callback data frame (Z-Wave Module → host)](04.03.05.04-3-callback-data-frame-z-wave-module-host.md) +- [4.3.6 Get Long Range Nodes Command](04.03.06-get-long-range-nodes-command.md) +- [4.3.6.1 Frame flow](04.03.06.01-frame-flow.md) +- [4.3.6.2 1. Initial data frame (host → Z-Wave Module)](04.03.06.02-1-initial-data-frame-host-z-wave-module.md) +- [4.3.6.3 2. Response data frame (Z-Wave Module → host)](04.03.06.03-2-response-data-frame-z-wave-module-host.md) +- [4.3.6.4 3. Callback data frame (Z-Wave Module → host)](04.03.06.04-3-callback-data-frame-z-wave-module-host.md) +- [4.3.7 Get Z-Wave Long Range Channel Command](04.03.07-get-z-wave-long-range-channel-command.md) +- [4.3.7.1 Frame flow](04.03.07.01-frame-flow.md) +- [4.3.7.2 1. Initial data frame (host → Z-Wave Module)](04.03.07.02-1-initial-data-frame-host-z-wave-module.md) +- [4.3.7.3 2. Response data frame (Z-Wave Module → host)](04.03.07.03-2-response-data-frame-z-wave-module-host.md) +- [4.3.7.4 3. Callback data frame (Z-Wave Module → host)](04.03.07.04-3-callback-data-frame-z-wave-module-host.md) +- [4.3.8 Set Z-Wave Long Range Channel Command](04.03.08-set-z-wave-long-range-channel-command.md) +- [4.3.8.1 Frame flow](04.03.08.01-frame-flow.md) +- [4.3.8.2 1. Initial data frame (host → Z-Wave Module)](04.03.08.02-1-initial-data-frame-host-z-wave-module.md) +- [4.3.8.3 2. Response data frame (Z-Wave Module → host)](04.03.08.03-2-response-data-frame-z-wave-module-host.md) +- [4.3.8.4 3. Callback data frame (Z-Wave Module → host)](04.03.08.04-3-callback-data-frame-z-wave-module-host.md) +- [4.3.9 Get Protocol Version Command](04.03.09-get-protocol-version-command.md) +- [4.3.9.1 Frame flow](04.03.09.01-frame-flow.md) +- [4.3.9.2 1. Initial data frame (host → Z-Wave Module)](04.03.09.02-1-initial-data-frame-host-z-wave-module.md) +- [4.3.9.3 2. Response data frame (Z-Wave Module → host)](04.03.09.03-2-response-data-frame-z-wave-module-host.md) +- [4.3.9.4 3. Callback data frame (Z-Wave Module → host)](04.03.09.04-3-callback-data-frame-z-wave-module-host.md) +- [4.3.10 Get Library Version Command](04.03.10-get-library-version-command.md) +- [4.3.10.1 Frame flow](04.03.10.01-frame-flow.md) +- [4.3.10.2 1. Initial data frame (host → Z-Wave Module)](04.03.10.02-1-initial-data-frame-host-z-wave-module.md) +- [4.3.10.3 2. Response data frame (Z-Wave Module → host)](04.03.10.03-2-response-data-frame-z-wave-module-host.md) +- [4.3.10.4 3. Callback data frame (Z-Wave Module → host)](04.03.10.04-3-callback-data-frame-z-wave-module-host.md) +- [4.3.11 Get Library Command](04.03.11-get-library-command.md) +- [4.3.11.1 Frame flow](04.03.11.01-frame-flow.md) +- [4.3.11.2 1. Initial data frame (host → Z-Wave Module)](04.03.11.02-1-initial-data-frame-host-z-wave-module.md) +- [4.3.11.3 2. Response data frame (Z-Wave Module → host)](04.03.11.03-2-response-data-frame-z-wave-module-host.md) +- [4.3.11.4 3. Callback data frame (Z-Wave Module → host)](04.03.11.04-3-callback-data-frame-z-wave-module-host.md) +- [4.3.12 Soft Reset Command](04.03.12-soft-reset-command.md) +- [4.3.12.1 Frame flow](04.03.12.01-frame-flow.md) +- [4.3.12.2 1. Initial data frame (host → Z-Wave Module)](04.03.12.02-1-initial-data-frame-host-z-wave-module.md) +- [4.3.12.3 2. Response data frame (Z-Wave Module → host)](04.03.12.03-2-response-data-frame-z-wave-module-host.md) +- [4.3.12.4 3. Callback data frame (Z-Wave Module → host)](04.03.12.04-3-callback-data-frame-z-wave-module-host.md) +- [4.3.13 Set Default Command](04.03.13-set-default-command.md) +- [4.3.13.1 Frame flow](04.03.13.01-frame-flow.md) +- [4.3.13.2 1. Initial data frame (host → Z-Wave Module)](04.03.13.02-1-initial-data-frame-host-z-wave-module.md) +- [4.3.13.3 2. Response data frame (Z-Wave Module → host)](04.03.13.03-2-response-data-frame-z-wave-module-host.md) +- [4.3.13.4 3. Callback data frame (Z-Wave Module → host)](04.03.13.04-3-callback-data-frame-z-wave-module-host.md) +- [4.3.14 Setup Z-Wave API Command](04.03.14-setup-z-wave-api-command.md) +- [4.3.14.1 Frame flow](04.03.14.01-frame-flow.md) +- [4.3.14.2 1. Initial data frame (host → Z-Wave Module)](04.03.14.02-1-initial-data-frame-host-z-wave-module.md) +- [4.3.14.3 2. Response data frame (Z-Wave Module → host)](04.03.14.03-2-response-data-frame-z-wave-module-host.md) +- [4.3.14.4 3. Callback data frame (Z-Wave Module → host)](04.03.14.04-3-callback-data-frame-z-wave-module-host.md) +- [4.3.15 Z-Wave API Setup sub-commands](04.03.15-z-wave-api-setup-sub-commands.md) +- [4.3.15.1 Z-Wave API Setup Get Supported Commands Sub Command](04.03.15.01-z-wave-api-setup-get-supported-commands-sub-command.md) +- [4.3.15.2 Z-Wave API Setup Set Tx Status Report Sub Command](04.03.15.02-z-wave-api-setup-set-tx-status-report-sub-command.md) +- [4.3.15.3 Z-Wave API Setup Set Powerlevel Sub Command](04.03.15.03-z-wave-api-setup-set-powerlevel-sub-command.md) +- [4.3.15.4 Z-Wave API Setup Get Powerlevel Sub Command](04.03.15.04-z-wave-api-setup-get-powerlevel-sub-command.md) +- [4.3.15.5 Z-Wave API Setup Get Maximum Payload Size Sub Command](04.03.15.05-z-wave-api-setup-get-maximum-payload-size-sub-command.md) +- [4.3.15.6 Z-Wave API Setup Get Z-Wave Long Range Maximum Payload Size Sub Com- mand](04.03.15.06-z-wave-api-setup-get-z-wave-long-range-maximum-payload-size-sub-com-mand.md) +- [4.3.15.7 Z-Wave API Setup Get RF Region Sub Command](04.03.15.07-z-wave-api-setup-get-rf-region-sub-command.md) +- [4.3.15.8 Z-Wave API Setup Set RF Region Sub Command](04.03.15.08-z-wave-api-setup-set-rf-region-sub-command.md) +- [4.3.15.9 Z-Wave API Setup Set NodeID Base Type Sub Command](04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01-common-network-management-commands.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01-common-network-management-commands.md new file mode 100644 index 0000000..b4f6b24 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01-common-network-management-commands.md @@ -0,0 +1,12 @@ + +# 4.4.1 Common Network Management Commands + +[This section describes Z-Wave API Commands that are used to perform Z-Wave Network Management](../index.md#4-z-wave-api-commands) for any nodes (both controller nodes and end nodes). + +The commands described in this subsection MUST be supported by all Z-Wave API modules. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.01-send-nop-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.01-send-nop-command.md new file mode 100644 index 0000000..f2a1e53 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.01-send-nop-command.md @@ -0,0 +1,81 @@ + +# 4.4.1.1 Send NOP Command + +This command is used to send NOP Commands a destination to verify if it is responsive. This command SHOULD NOT be used by a host application for NL Nodes outside their Wake Up period. Refer to the [[ zwave_nwk_spec ] for details. The Send NOP Command Identifier is 0xE9.](../../05-references.md#5-references) + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.66](04.04.01.01-send-nop-command.md#4411-send-nop-command) + +Table 4.66: Send NOP Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xE9 | | | | | | | | +| 5/5..6 | Destination NodeID | | | | | | | | +| 6/7 | Tx Options | | | | | | | | +| 8/9 | Session identifier | | | | | | | | + +Destination NodeID (8 bits/16 bits) + +[This field is used to indicate the destination NodeID to send the Z-Wave Frame to.](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[Tx Options (8 bits)](../04.02-generic-command-elements.md#428-tx-options-8-bits) + +[Refer to Tx Options (8 bits) .](../04.02-generic-command-elements.md#428-tx-options-8-bits) + +[Session Identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.67](04.04.01.01-send-nop-command.md#4411-send-nop-command) + +Table 4.67: Send NOP Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xE9 | | | | | | | | +| 5 | Response status | | | | | | | | + +Response status (8 bits) + +[Refer to Response status (8 bits) .](../04.02-generic-command-elements.md#425-response-status-8-bits) 3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.68](04.04.01.01-send-nop-command.md#4411-send-nop-command) + +Table 4.68: Send NOP Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xE9 | | | | | | | | +| 5 | Session Identifier | | | | | | | | +| 6 | Tx Status | | | | | | | | +| 7 | Tx Status Report 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 7+N | Tx Status Report N | | | | | | | | + +[Session Identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Tx Status (8 bits)](../04.02-generic-command-elements.md#423-tx-status-8-bits) + +[Refer to Tx Status (8 bits) .](../04.02-generic-command-elements.md#423-tx-status-8-bits) + +Tx Status Report (N bytes) + +This field is used to report detailed information about the Z-Wave frame transmission. This field MUST [be omitted if the Z-Wave API module is not configured to enable Tx Status Reports in the Z-Wave API Setup Set Tx Status Report Sub Command .](../04.03-z-wave-capability-api-commands/04.03.15.02-z-wave-api-setup-set-tx-status-report-sub-command.md#43152-z-wave-api-setup-set-tx-status-report-sub-command) + +[For field description, refer to Tx Status Report (N bytes) .](../04.02-generic-command-elements.md#4210-tx-status-report-n-bytes) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.02-get-node-information-protocol-data-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.02-get-node-information-protocol-data-command.md new file mode 100644 index 0000000..dbc1d0f --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.02-get-node-information-protocol-data-command.md @@ -0,0 +1,53 @@ + +# 4.4.1.2 Get Node Information Protocol Data Command + +This command is used to request the Node Information protocol data about a NodeID to the Z-Wave API Module. The Get Node Information Protocol Data Command Identifier is 0x41. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.69](04.04.01.02-get-node-information-protocol-data-command.md#4412-get-node-information-protocol-data-command) + +Table 4.69: Get Node Information Protocol Data Command - Ini- tial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x41 | | | | | | | | +| 5/5..6 | NodeID | | | | | | | | + +NodeID (8/16 bits) + +[This field is used to indicate the NodeID for which the Node Information protocol data is requested.](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.70](04.04.01.02-get-node-information-protocol-data-command.md#4412-get-node-information-protocol-data-command) + +Table 4.70: Get Node Information Protocol Data Command - Re- sponse data frame + +| byte\ | bit 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x41 | | | | | | | | +| 5 | Listening | Routing | Supported speed | | | Protocol version | | | +| 6 | Optional Functional- ity | Sensor 1000ms | Sensor 250ms | Beam Capabil- ity | Routing End Node | Specific Device | Con- troller node | Se- cu- rity | +| 7 | Reserved | | | | | Speed Extension | | | +| 8 | Basic Device Type | | | | | | | | +| 9 | Generic Device Class | | | | | | | | +| 10 | Specific Device Class | | | | | | | | + +Fields values in this command MUST be according to the Node Information Frame Command received [by the NodeID being advertised. Refer to the [ zwave_nwk_spec ] for details.](../../05-references.md#5-references) + +If the NodeID requested in the Initial Data Frame is not part of the Network or is unknown to the Z-Wave Module, the Generic Device Class field MUST be set to 0. All other fields SHOULD also be set to 0 and ignored by a receiving interface. 3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.03-send-node-information-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.03-send-node-information-command.md new file mode 100644 index 0000000..a40551a --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.03-send-node-information-command.md @@ -0,0 +1,72 @@ + +# 4.4.1.3 Send Node Information Command + +This command is used to trigger a transmission of Node Information Frame. The Send Node Information Command Command Identifier is 0x12. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with callback .](../../03-interface-communication/03.03-command-frame-flows.md#334-acknowledged-frame-with-callback) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.71 .](04.04.01.03-send-node-information-command.md#4413-send-node-information-command) + +Table 4.71: Send Node Information Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x12 | | | | | | | | +| 5/6 | Destination NodeID | | | | | | | | +| 7/8 | Tx Option | | | | | | | | +| 8/9 | Session identifier | | | | | | | | + +Destination NodeID (8/16 bits) + +This field is used to indicate the destination NodeID of the node where the Node Information Frame is sent to. + +[Tx Option (8 bits)](../04.02-generic-command-elements.md#428-tx-options-8-bits) + +[Refer to Tx Options (8 bits) .](../04.02-generic-command-elements.md#428-tx-options-8-bits) + +[Session identifer (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.72 .](04.04.01.03-send-node-information-command.md#4413-send-node-information-command) + +Table 4.72: Send Node Information Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x12 | | | | | | | | +| 5 | Response status | | | | | | | | + +[Response status (8 bits)](../04.02-generic-command-elements.md#425-response-status-8-bits) + +[Refer to Response status (8 bits) .](../04.02-generic-command-elements.md#425-response-status-8-bits) 3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.73 after the module](04.04.01.03-send-node-information-command.md#4413-send-node-information-command) transmit the node information frame to target node. + +Table 4.73: Send Node Information Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x12 | | | | | | | | +| 5 | Session identifier | | | | | | | | +| 6 | Tx Status | | | | | | | | + +Session identifier(8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Tx Status (8 bits)](../04.02-generic-command-elements.md#422-rx-status-8-bits) + +[Refer to Rx Status (8 bits) .](../04.02-generic-command-elements.md#422-rx-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.04-request-node-information-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.04-request-node-information-command.md new file mode 100644 index 0000000..681f853 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.04-request-node-information-command.md @@ -0,0 +1,58 @@ + +# 4.4.1.4 Request Node Information Command + +This command is used to request the Node Information Frame from a Z-Wave Node. The Request Node Information Command Identifier is 0x60. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +This command will trigger additional unsolicited frames from the Z-Wave API Module. Examples of [the expected frame flows are shown in Figure 4.2 and](../../03-interface-communication/03.03-command-frame-flows.md#332-acknowledged-frame) [Figure 4.3](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +If the Z-Wave API Module receives the requested Node Information Frame Command, it MUST issue an unsolicited [Application Update Command](../04.07-unsolicited-z-wave-api-commands.md#473-application-update-command) with the status set to UP- DATE_STATE_NODE_INFO_RECEIVED. + +If the Z-Wave API Module does not receive the requested Node Information Frame Com- mand, it MUST issue an unsolicited [Application Update Command](../04.07-unsolicited-z-wave-api-commands.md#473-application-update-command) with the status set to UP- DATE_STATE_NODE_INFO_REQ_FAILED. + +![Figure 4.2: Request Node Information Command Success Example](assets/img-235bf0f9d5.png) + +![Figure 4.3: Request Node Information Command Fail Example](assets/img-bc3d7ce577.png) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.74 .](04.04.01.04-request-node-information-command.md#4414-request-node-information-command) + +Table 4.74: Request Node Information Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x60 | | | | | | | | +| 5/6 | NodeID | | | | | | | | + +NodeID (8/16 bits) + +This field is used to indicate the NodeID for which the Node Information Frame must be requested. + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.75 .](04.04.01.04-request-node-information-command.md#4414-request-node-information-command) + +Table 4.75: Request Node Information Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x60 | | | | | | | | +| 5 | Command Status | | | | | | | | + +[Command Status (8 bits)](../04.02-generic-command-elements.md#426-command-status-8-bits) + +[Refer to Command Status (8 bits) .](../04.02-generic-command-elements.md#426-command-status-8-bits) 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.05-set-learn-mode-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.05-set-learn-mode-command.md new file mode 100644 index 0000000..045b4a4 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.05-set-learn-mode-command.md @@ -0,0 +1,103 @@ + +# 4.4.1.5 Set Learn Mode Command + +This command is used to start or stop Learn Mode The Set Learn Mode Command Identifier is 0x50. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) + +[This command will trigger several callback frames. This is illustrated in Figure 4.4](../../03-interface-communication/03.03-command-frame-flows.md#334-acknowledged-frame-with-callback) + +![Figure 4.4: Set Learn Mode Command Example](assets/img-c1c5f5444f.png) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.76](04.04.01.05-set-learn-mode-command.md#4415-set-learn-mode-command) + +Table 4.76: Set Learn Mode Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x50 | | | | | | | | +| 5 | Learn Mode Intent | | | | | | | | +| 6 | Session Identifier | | | | | | | | + +Learn Mode Intent (8 bits) + +[This field is used to indicate the Learn Mode Intent. Refer to [ zwave_nwk_spec ] for](../../05-references.md#5-references) Learn Mode details. + +[This field MUST be encoded according to Table 4.77 .](04.04.01.05-set-learn-mode-command.md#4415-set-learn-mode-command) + +Table 4.77: Set Learn Mode Command - Learn Mode Intent en- coding + +| Value | Description | +| --- | --- | +| 0x00 | Disabled This value is used to stop learn mode. | +| 0x01 | Learn Mode Inclusion/Exclusion Deprecated: It is NOT RECOMMENDED to use this value, use 0x81, 0x82 or 0x83 in- stead. This value is used to start learn mode and expect either a direct-range network inclusion or a direct-range network exclusion. | +| 0x02 | Learn Mode Network Wide Inclusion Deprecated: It is NOT RECOMMENDED to use this value, use 0x81 instead. This value is used to start learn mode and expect a Network-Wide Inclusion (NWI). | +| 0x03 | Learn Mode Network Wide Exclusion Deprecated: It is NOT RECOMMENDED to use this value, use 0x83 instead. This value is used to start learn mode and expect a Network Wide Exclusion (NWE). | +| 0x81 | Learn Mode (Network Wide) Inclusion This value is used to start learn mode and expect either a network inclusion. The Z-Wave API Module SHOULD try a direct range inclusion followed by 4 NWI attempts. | +| 0x82 | Learn Mode Exclusion This value is used to start learn mode and expect a direct range Network Exclusion. | +| 0x83 | Learn Mode Network Wide Exclusion This value is used to start learn mode and expect a Network Wide Exclusion (NWE). | +| 0x84 | SmartStart Learn Mode This value is used to start SmartStart learn mode. | + +Session Identifier (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) [A Z-Wave module MUST return a response frame formatted according to Table 4.78 Table 4.78: Set Learn Mode Command - Response data frame](04.04.01.05-set-learn-mode-command.md#4415-set-learn-mode-command) + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x50 | | | | | | | | +| 5 | Response status | | | | | | | | + +Response Status (8 bits) + +[Refer to Response status (8 bits) .](../04.02-generic-command-elements.md#425-response-status-8-bits) + +3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return issue a callback data frame formatted according to Table 4.79](04.04.01.05-set-learn-mode-command.md#4415-set-learn-mode-command) + +Table 4.79: Set Learn Mode Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x50 | | | | | | | | +| 5 | Session identifier | | | | | | | | +| 6 | Learn Mode Status | | | | | | | | +| 7/7..8 | NodeID | | | | | | | | + +Session Identifier (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +Learn Mode Status (8 bits) + +This field is used to indicate the current Learn Mode Status. + +[This field MUST be encoded according to Table 4.80 .](04.04.01.05-set-learn-mode-command.md#4415-set-learn-mode-command) + +Table 4.80: Learn Mode Status encoding + +| Value | Description | +| --- | --- | +| 0x01 | Learn Mode started This value indicates that Learn Mode has started and is now ongoing | +| 0x06 | Learn Mode completed This value indicates that Learn Mode has completed with a successful outcome. | +| 0x07 | Learn Mode failed This value indicates that Learn Mode has completed with an unsuccessful outcome. | + +All other values are reserved. + +NodeID (8 bits/16 bits) + +[This field is used to indicate the NodeID currently assigned to the Z-Wave API Module.](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.06-get-suc-nodeid-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.06-get-suc-nodeid-command.md new file mode 100644 index 0000000..8dce774 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.06-get-suc-nodeid-command.md @@ -0,0 +1,47 @@ + +# 4.4.1.6 Get SUC NodeID Command + +This command is used to get currently registered SUC/SIS NodeID in a Z-Wave network. The Get SUC NodeID Command Identifier is 0x56. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.81 .](04.04.01.06-get-suc-nodeid-command.md#4416-get-suc-nodeid-command) + +Table 4.81: Get SUC NodeID Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x56 | | | | | | | | + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.82 .](04.04.01.06-get-suc-nodeid-command.md#4416-get-suc-nodeid-command) + +Table 4.82: Get SUC NodeID Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x56 | | | | | | | | +| 5/5..6 | SUC NodeID | | | | | | | | + +SUC NodeID (8 bits) + +This field is used to advertise the SUC NodeID in the Z-Wave network. + +The value 0x00 MUST indicate that there is no SUC NodeID in the current network. All other values MUST indicate the NodeID of the SUC in the current network. + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.07-set-smartstart-inclusion-request-maximum-interval-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.07-set-smartstart-inclusion-request-maximum-interval-command.md new file mode 100644 index 0000000..df8708d --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.07-set-smartstart-inclusion-request-maximum-interval-command.md @@ -0,0 +1,48 @@ + +# 4.4.1.7 Set SmartStart Inclusion Request Maximum Interval Command + +This command is used to set the maximum interval between SmartStart inclusion requests. The Set Maximum SmartStart Inclusion Request Interval Command Identifier is 0xD6. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.83 to set the maximum number of ticks](04.04.01.07-set-smartstart-inclusion-request-maximum-interval-command.md#4417-set-smartstart-inclusion-request-maximum-interval-command) between SmartStart inclusion requests. + +Table 4.83: Set Maximum SmartStart Inclusion Request Interval Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xD6 | | | | | | | | +| 5 | Requested Intervals | | | | | | | | + +Requested Intervals 1 (8 bits) + +This field is used to indicate the maximum number of ticks between SmartStart inclusion requests. Each ticks MUST have 128 seconds interval. + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.84 .](04.04.01.07-set-smartstart-inclusion-request-maximum-interval-command.md#4417-set-smartstart-inclusion-request-maximum-interval-command) + +Table 4.84: Set Maximum SmartStart Inclusion Request Interval Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xD6 | | | | | | | | +| 5 | Command Status | | | | | | | | + +Command Status (8 bits) + +This field is used to advertise the status regarding the configuration of SmartStart inclusion request [interval. The field value MUST be encoded according to Command Status (8 bits) .](../04.02-generic-command-elements.md#426-command-status-8-bits) + +3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.08-explore-request-inclusion-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.08-explore-request-inclusion-command.md new file mode 100644 index 0000000..548c5df --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.08-explore-request-inclusion-command.md @@ -0,0 +1,51 @@ + +# 4.4.1.8 Explore Request Inclusion Command + +This command is used to initiate a Network-Wide Inclusion process. When the Z-Wave module receives this command, the module MUST issue an explore frame for requesting inclusion (add) to a Z-Wave network. The Explore Request Inclusion Command Identifier is 0x5E. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +[The host application MUST send Set Learn Mode Command with a](04.04.01.05-set-learn-mode-command.md#4415-set-learn-mode-command) Learn Mode Intent field value equals to 0x81 before sending Explore Request Inclusion command for requesting the Z-Wave API module to trigger a Network-Wide Inclusion process. Once a Set Learn Mode callback data frame (that indicates the inclusion process has started) is received, the application MUST NOT send this command to the Z- [Wave API module. Figure 4.5 illustrates the usage of](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) Explore Request Inclusion Command. + +![Figure 4.5: Explore Request Inclusion Command Example](assets/img-97e08b257c.png) + +[It is not recommended to use this command since Set Learn Mode Command with a](04.04.01.05-set-learn-mode-command.md#4415-set-learn-mode-command) Learn Mode Intent field value equals to 0x81 can trigger the Inclusion process without issuing Explore Request Inclusion Command. + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.85 .](04.04.01.08-explore-request-inclusion-command.md#4418-explore-request-inclusion-command) Table 4.85: Explore Request Inclusion Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x5E | | | | | | | | + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.86 .](04.04.01.08-explore-request-inclusion-command.md#4418-explore-request-inclusion-command) + +Table 4.86: Explore Request Inclusion Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x5E | | | | | | | | +| 5 | Inclusion Request Status | | | | | | | | + +Inclusion Request Status (8 bits) + +This field is used to advertise the status regarding the acceptance of the Explore Request Inclusion Command Initial data frame. This field MUST be encoded as follow: + +• The field value MUST set to 0x01, if the inclusion request is queued for transmission by the Z-Wave module. + +• The field value MUST set to 0x00, if the Learn Mode is not set. + +3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.09-explore-request-exclusion-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.09-explore-request-exclusion-command.md new file mode 100644 index 0000000..d43ed16 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.01.09-explore-request-exclusion-command.md @@ -0,0 +1,51 @@ + +# 4.4.1.9 Explore Request Exclusion Command + +This command is used to initiate a Network-Wide Exclusion process. When the Z-Wave module receives this command, the module MUST issue an explore frame for requesting exclusion (remove) from a Z- Wave network. The Request Network Wide Exclusion Command Identifier is 0x5F. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +[The host application MUST send Set Learn Mode Command with](04.04.01.05-set-learn-mode-command.md#4415-set-learn-mode-command) Learn Mode Intent field value equals to 0x83 before sending Explore Request Exclusion command to the Z-Wave module. Once a Set Learn Mode callback data frame (that indicates the Exclusion process has started) is received, the application [MUST NOT send this command to the Z-Wave module. Figure 4.6 illustrates the usage of](../../03-interface-communication/03.03-command-frame-flows.md#336-unsolicited-frame) Explore Request Exclusion Command. + +![Figure 4.6: Explore Request Exclusion Command Example](assets/img-8faf52e1c6.png) + +[It is not recommended to use this command since Set Learn Mode Command with a](04.04.01.05-set-learn-mode-command.md#4415-set-learn-mode-command) Learn Mode Intent field value equals to 0x83 can trigger the Exclusion process without issuing Explore Request Exclusion Command. + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.87 .](04.04.01.09-explore-request-exclusion-command.md#4419-explore-request-exclusion-command) Table 4.87: Explore Request Exclusion Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x5F | | | | | | | | + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.88 .](04.04.01.09-explore-request-exclusion-command.md#4419-explore-request-exclusion-command) + +Table 4.88: Explore Request Exclusion Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x5F | | | | | | | | +| 5 | Exclusion Request Status | | | | | | | | + +Exclusion Request Status (8 bits) + +This field is used to advertise the status regarding the acceptance of the Explore Request Exclusion Command Initial data frame. This field MUST be encoded as follow: + +• The field value MUST set to 0x01, if the exclusion request is queued for transmission by the Z-Wave module. + +• The field value MUST set to 0x00, if the Learn Mode is not set. + +3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.02-end-nodes-network-management.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.02-end-nodes-network-management.md new file mode 100644 index 0000000..3e00131 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.02-end-nodes-network-management.md @@ -0,0 +1,14 @@ + +# 4.4.2 End Nodes Network Management + +[This section describes Z-Wave API Commands that are used to perform Z-Wave Network Management](../index.md#4-z-wave-api-commands) for End Nodes. + +The commands described in this subsection MUST be supported by Z-Wave API modules implementing an End Node [library type (refer to Table 4.36 ).](../04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) + +The commands described in this subsection MUST NOT be supported by Z-Wave API modules imple- menting a Controller Node [library type (refer to Table 4.36 ).](../04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.02.01-request-new-route-destinations-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.02.01-request-new-route-destinations-command.md new file mode 100644 index 0000000..c2091ce --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.02.01-request-new-route-destinations-command.md @@ -0,0 +1,89 @@ + +# 4.4.2.1 Request New Route Destinations Command + +This command is used to request a new route for destination nodes from SUC/SIS node. The Request New Route Destinations Command Identifier is 0x5C. + +This commands MUST only be supported by a Z-Wave API module implementing a Enhanced 232 End Node Library or Routing End Node library. Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) + +When the Z-Wave API module receives Request New Route Destinations Command, it will send Static Route Request Commands [for each Destination NodeIDs. This is illustrated in Figure 4.7](../../03-interface-communication/03.04-error-handling.md#342-missing-acknowledgment) + +![Figure 4.7: Request New Route Destinations Command Example](assets/img-94bdf55e26.png) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.89 .](04.04.02.01-request-new-route-destinations-command.md#4421-request-new-route-destinations-command) Table 4.89: Request New Route Destinations Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x5C | | | | | | | | +| 5 | Destinations NodeID 1 | | | | | | | | +| .. | . . . | | | | | | | | +| 5+N | Destinations NodeID N | | | | | | | | +| 6+N | Session identifier | | | | | | | | + +Destinations NodeID (N bytes) + +This field is used to indicates the new destination NodeIDs for which return routes are requested. + +Each byte in this field MUST represent a NodeID. All NodeIDs MUST be encoded using 8 bits re- [gardless of the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[Session identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.90 .](04.04.02.01-request-new-route-destinations-command.md#4421-request-new-route-destinations-command) + +Table 4.90: Request New Route Destinations Command - Re- sponse data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x5C | | | | | | | | +| 5 | Request New Route Response | | | | | | | | + +Request New Route Response (8 bits) + +This field is used to advertise the response of the Z-Wave module regarding the acceptance of the Request New Route Destinations Command Initial data frame. This field MUST be encoded as follow: + +• If the new route updating process is started, this field value MUST be set to 0x01. + +• If the protocol runs on Z-Wave module is busy or the SUC/SIS node is unknown to the protocol, this field value MUST be set to 0x00. + +3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.91 .](04.04.02.01-request-new-route-destinations-command.md#4421-request-new-route-destinations-command) + +Table 4.91: Request New Route Destinations Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x5C | | | | | | | | +| 5 | Session identifier | | | | | | | | +| 6 | Request New Route Callback Status | | | | | | | | + +Session identifier (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +Request New Route Callback Status (8 bits) + +This field is used to notify status of the new route updating process. This field MUST be encoded [according to Table 4.92 .](04.04.02.01-request-new-route-destinations-command.md#4421-request-new-route-destinations-command) + +Table 4.92: Request New Route Destinations Callback Status Value encoding + +| Value | Flag | Description | +| --- | --- | --- | +| 0x00 | ZW ROUTE UPDATE DONE _ _ _ | The new route updating process ended success- fully. | +| 0x01 | ZW ROUTE UPDATE ABORT _ _ _ | The new route updating process is aborted be- cause of error. | +| 0x02 | ZW ROUTE UPDATE WAIT _ _ _ | The SUC/SIS node is busy. | +| 0x02 | ZW ROUTE UPDATE DISABLED _ _ _ | The SUC/SIS functionality is disabled. | +| 0x04..0x | FReserved | Reserved values MUST NOT be used. | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.02.02-is-node-within-direct-range-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.02.02-is-node-within-direct-range-command.md new file mode 100644 index 0000000..121556e --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.02.02-is-node-within-direct-range-command.md @@ -0,0 +1,52 @@ + +# 4.4.2.2 Is Node Within Direct Range Command + +This command is used to check if a given NodeID is marked as a direct range node (A node that can be reached with a direct range communication from a Z-Wave API module) in any of the existing return routes. Is Node Within Direct Range Command Identifier is 0x5D. + +This commands MUST only be supported by a Z-Wave module that employs Enhanced 232 End Node Library or Routing End Node library. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.93 .](04.04.02.02-is-node-within-direct-range-command.md#4422-is-node-within-direct-range-command) + +Table 4.93: Is Node Within Direct Range Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x5D | | | | | | | | +| 5 | NodeID | | | | | | | | + +NodeID (8 bits) + +This field is used to indicate the NodeID which will be examined if it is stored as a direct range node in existing return routes. + +[This field MUST be encoded using 8 bits regardless of the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.94 .](04.04.02.02-is-node-within-direct-range-command.md#4422-is-node-within-direct-range-command) + +Table 4.94: Is Node Within Direct Range Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x5D | | | | | | | | +| 5 | Direct Range Status | | | | | | | | + +Direct Range Status (8 bits) + +This field is used to indicate a status regarding the node presence in existing return route as a direct range node. This field MUST be encoded as follow: • If the node is reachable within direct range, the field value MUST be set to 0x01. + +• If the node is beyond direct range or status is unknown to the Z-Wave protocol, the field value MUST be set to 0x00. 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.02.03-get-network-statistics-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.02.03-get-network-statistics-command.md new file mode 100644 index 0000000..822ae5c --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.02.03-get-network-statistics-command.md @@ -0,0 +1,72 @@ + +# 4.4.2.3 Get Network Statistics Command + +This command is used to request the current Network Statistics as collected by a library runs on the Z- Wave Module. It is expected that the library will continuously update any Network Statistics counter until it reaches 65535, which then indicates that the specific counter has reached 65535 or more occur- rences. The Network Statistics counters shall be cleared either on module startup, or by receiving Clear Network Statistics Command. The Get Network Statistics Command Identifier is 0x3A. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.95](04.04.02.03-get-network-statistics-command.md#4423-get-network-statistics-command) + +Table 4.95: Get Network Statistics Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x3A | | | | | | | | + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.96](04.04.02.03-get-network-statistics-command.md#4423-get-network-statistics-command) + +Table 4.96: Get Network Statistics Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x3A | | | | | | | | +| 5 | Tx Frames 1 (MSB) | | | | | | | | +| 6 | Tx Frames 2 (LSB) | | | | | | | | +| 7 | Tx LBT BackOffs 1 (MSB) | | | | | | | | +| 8 | Tx LBT BackOffs 2 (LSB) | | | | | | | | +| 9 | Rx Frames 1 (MSB) | | | | | | | | +| 10 | Rx Frames 2 (LSB) | | | | | | | | +| 11 | Rx Checksum Errors 1 (MSB) | | | | | | | | +| 12 | Rx Checksum Errors 2 (LSB) | | | | | | | | +| 13 | Rx CRC16 Errors 1 (MSB) | | | | | | | | +| 14 | Rx CRC16 Errors 2 (LSB) | | | | | | | | +| 15 | Rx Foreign HomeID 1 (MSB) | | | | | | | | +| 16 | Rx Foreign HomeID 2 (LSB) | | | | | | | | + +Tx Frames (2 bytes) This field is used to indicate the transmitted frames. This field MUST be encoded as a 16-bits unsigned integer. + +Tx LBT BackOffs (2 bytes) This field is used to advertise the numbers of times the Tx had to wait and postpone a transmission due to a measured RSSI above the allowed LBT threshold. + +This field MUST be encoded as a 16-bits unsigned integer. + +Rx Frames (2 bytes) + +This field is used to advertise the numner of received frames without any errors. This field MUST be encoded as a 16-bits unsigned integer. + +Rx Checksum Errors (2 bytes) + +This field is used to advertise the number of received frames with checksum errors. This field MUST be encoded as a 16-bits unsigned integer. + +Rx CRC16 Errors (2 bytes) + +This field is used to advertise the number of received frames with CRC16 checksum errors. This field MUST be encoded as a 16-bits unsigned integer. + +Rx Foreign HomeID (2 bytes) + +This field is used to advertise the number of valid Z-Wave frames that has been received with a HomeID not matching the HomeID of the receiving node. This field MUST be encoded as a 16-bits unsigned integer. + +3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.02.04-clear-network-statistics-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.02.04-clear-network-statistics-command.md new file mode 100644 index 0000000..d97677c --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.02.04-clear-network-statistics-command.md @@ -0,0 +1,43 @@ + +# 4.4.2.4 Clear Network Statistics Command + +This command is used to clear the current Network Statistics collected by the Z-Wave API Module. The Clear Network Statistics Command Identifier is 0x39. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.97](04.04.02.04-clear-network-statistics-command.md#4424-clear-network-statistics-command) + +Table 4.97: Clear Network Statistics Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x39 | | | | | | | | + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.98](04.04.02.04-clear-network-statistics-command.md#4424-clear-network-statistics-command) + +Table 4.98: Clear Network Statistics Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x39 | | | | | | | | +| 5 | Command Status | | | | | | | | + +Command Status (8 bits) + +[Refer to Command Status (8 bits) .](../04.02-generic-command-elements.md#426-command-status-8-bits) + +3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03-controller-nodes-network-management.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03-controller-nodes-network-management.md new file mode 100644 index 0000000..c8b1976 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03-controller-nodes-network-management.md @@ -0,0 +1,14 @@ + +# 4.4.3 Controller Nodes Network Management + +[This section describes Z-Wave API Commands that are used to perform Z-Wave Network Management](../index.md#4-z-wave-api-commands) for Controller Nodes. + +The commands described in this subsection MUST NOT be supported by Z-Wave API modules imple- menting an End Node [library type (refer to Table 4.36 ).](../04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) + +The commands described in this subsection MUST be supported by Z-Wave API modules implementing a Controller Node [library type (refer to Table 4.36 ).](../04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.01-add-node-to-network-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.01-add-node-to-network-command.md new file mode 100644 index 0000000..2964033 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.01-add-node-to-network-command.md @@ -0,0 +1,198 @@ + +# 4.4.3.1 Add Node To Network Command + +This command is used to trigger a node inclusion to a Z-Wave network. The Add Node To Network Command Identifier is 0x4A. + +This Command MUST be supported by Controller Nodes Z-Wave API implementations. This Command MUST NOT be supported by End Nodes Z-Wave API implementations. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with callback .](../../03-interface-communication/03.03-command-frame-flows.md#334-acknowledged-frame-with-callback) + +The host application may issue several 1. initial data frames several during an inclusion and the Z-Wave API module may issue sereval 3. callback data frames during an inclusion. + +[Figure 4.8 shows an example of a successful network inclusion.](../../03-interface-communication/03.04-error-handling.md#343-collision) + +![Figure 4.8: Add Node To Network Command Success Example](assets/img-37140f1865.png) + +[Figure 4.9 shows an example of a host timeout for a network inclusion.](../../03-interface-communication/03.04-error-handling.md#343-collision) + +![Figure 4.9: Add Node To Network Command Abort Example](assets/img-81e1157643.png) + +[Figure 4.10 shows an example of a SmartStart network inclusion.](../../03-interface-communication/03.04-error-handling.md#345-invalid-frame) + +![figure p127](assets/img-587ad5ef6a.png) + +[Figure 4.11 shows an example of a Z-Wave Long Range SmartStart network inclusion.](04.04.03.01-add-node-to-network-command.md#4431-add-node-to-network-command) + +![figure p128](assets/img-c06357978d.png) + +Figure 4.11: Add Node To Network Command Z-Wave Long Range SmartStart Example + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.99](04.04.03.01-add-node-to-network-command.md#4431-add-node-to-network-command) + +Table 4.99: Add Node To Network Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x4A | | | | | | | | +| 5 | Power | NWI | Protocol | Mode | | | | | +| 6 | Session Identifier | | | | | | | | +| 7 | NWI HomeID 1 | | | | | | | | +| 8 | NWI HomeID 2 | | | | | | | | +| 9 | NWI HomeID 3 | | | | | | | | +| 10 | NWI HomeID 4 | | | | | | | | +| 11 | Auth HomeID 1 | | | | | | | | +| 12 | Auth HomeID 2 | | | | | | | | +| 13 | Auth HomeID 3 | | | | | | | | +| 14 | Auth HomeID 4 | | | | | | | | + +Power (1 bit) + +This field is used to indicate which power to use for the Network Inclusion operation. + +• The value 0 MUST indicate that the Z-Wave Module MUST use reduced power for the network inclusion. + +• The value 1 MUST indicate that the Z-Wave Module MUST use normal power for the network inclusion. + +NWI (1 bit) + +This field is used to indicate if the operation must be a direct range Network Inclusion or NWI. + +• The value 0 MUST indicate that the Z-Wave Module MUST use direct range network inclusion for the network inclusion. + +• The value 1 MUST indicate that the Z-Wave Module MUST use NWI for the network inclusion. + +Protocol (1 bit) + +This field is used to indicate if the operation must be carried out using Z-Wave or Z-Wave Long Range. + +• The value 0 MUST indicate that the Z-Wave Module MUST use Z-Wave for the Add mode oper- ation. + +• The value 1 MUST indicate that the Z-Wave Module MUST use Z-Wave Long Range for the Add mode operation. + +Mode (5 bits) + +This field is used to indicate which “Add Mode” operation the Z-Wave Module MUST carry out. [This field MUST encoded according to Table 4.100](04.04.03.01-add-node-to-network-command.md#4431-add-node-to-network-command) + +Table 4.100: Add Node To Network Command - Mode encoding + +| Value | Description | +| --- | --- | +| 0x01 | Add any node. The Z-Wave Module MUST start network inclusion and attempt to add any type of node. The Z-Wave Module MUST keep in network inclusion mode until this com- mand is called again with the Mode set to 0x05 or 0x06 | +| 0x02 | Deprecated: Add controller node. Use Add any node (0x01) instead. | +| 0x03 | Deprecated: Add End Node. Use Add any node (0x01) instead. | +| 0x04 | Deprecated: Add existing node. Use Add any node (0x01) instead. | +| 0x05 | Stop network inclusion. The Z-Wave Module MUST stop the ongoing or completed network inclusion. | +| 0x06 | Stop controller replication. This value is used for stopping a network inclusion. This value SHOULD be used by a host application if a controller replication is ongoing and must be aborted. | +| 0x07 | Reserved. This value is reserved. | +| 0x08 | SmartStart Include Node. This value is used when a host application has matched a SmartStart Prime Command to a pending DSK in its provisioning list. This value indicates that the Z-Wave API module MUST initiate the SmartStart Network inclusion when the next SmartStart Inclusion Request Command is received from this node. When this value is used, the NWI HomeID and Auth HomeID fields MUST be set to the values from the matched DSK in the host application’s provisioning list. | +| 0x09 | Start SmartStart The Z-Wave API Module MUST activate NWI, start listening for SmartStart Prime Commands and report them to the host application. No inclusion will be made yet with this option. | +| 0x0A..0x19 | Reserved. These values are reserved. Reserved values MUST NOT be used and MUST be ig- nored by a receiving interface. | + +[Session Identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +NWI HomeID (4 bytes) + +This field is used to indicate the NWI HomeID of the node that MUST be included using SmartStart. + +If the Mode field is not set to 0x08, this field and the Auth HomeID field MAY be omitted. If the Mode field is not set to 0x08, this field SHOULD be set to 0x00000000. + +If the Mode field is set to 0x08, this field MUST be set to the NWI HomeID of the DSK entry that MUST be included by the Z-Wave API Module. + +Auth HomeID (4 bytes) + +This field is used to indicate the Auth HomeID of the node that MUST be included using SmartStart. + +If the Mode field is not set to 0x08, this field and the NWI HomeID field MAY be omitted. If the Mode field is not set to 0x08, this field SHOULD be set to 0x00000000. + +If the Mode field is set to 0x08, this field MUST be set to the Auth HomeID of the DSK entry that MUST be included by the Z-Wave API Module. 2. Response data frame (Z-Wave Module → host) + +None. + +3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.101](04.04.03.01-add-node-to-network-command.md#4431-add-node-to-network-command) + +Table 4.101: Add Node To Network Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x4A | | | | | | | | +| 5 | Session Identifier | | | | | | | | +| 6 | Status | | | | | | | | +| 7/7..8 | Assigned NodeID | | | | | | | | +| 8/9 | Supported Command Class List Length | | | | | | | | +| 9/10 | Basic Device Type | | | | | | | | +| 10/11 | Generic Device Type | | | | | | | | +| 11/12 | Specific Device Type | | | | | | | | +| (11/12)+1 | Supported Command Class List 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| (11/12)+N | Supported Command Class List N | | | | | | | | + +Session Identifier (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +Status (8 bits) + +This field is used to advertise the current status of the inclusion process. + +[This field MUST be according to Table 4.102](04.04.03.01-add-node-to-network-command.md#4431-add-node-to-network-command) Table 4.102: Add Node To Network Command - Status encoding + +| Value | Description | +| --- | --- | +| 0x01 | Network Inclusion Started. The Z-Wave Module has initiated Network inclusion and is ready to include new nodes | +| 0x02 | Node found. A node requesting inclusion has been found and the network inclusion is initiated. | +| 0x03 | Inclusion ongoing (End Node). The network inclusion is ongoing with an End Node. | +| 0x04 | Inclusion ongoing (Controller Node). The network inclusion is ongoing with a Controller node. | +| 0x05 | Inclusion completed (protocol part). The network inclusion is completed. The host application SHOULD issue a new Add Node To Network Command - Initial data frame with the Mode field set to 0x05 to stop the network inclusion. | +| 0x06 | Inclusion completed The network inclusion is completed. The Z-Wave Module is ready to return to idle and the host application SHOULD issue a new Add Node To Network Command - Initial data frame with the Mode field set to 0x05 to stop the network inclusion. | + +Assigned NodeID (8/16 bits) + +[This field is used to advertise the NodeID that was assigned during the inclusion process.](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +The value 0 MUST indicate that no NodeID was assigned at that stage of the inclusion process. + +Supported Command Class List Length (8 bits) + +This field is used to advertise the length of the Supported Command Class List field, in bytes. + +Basic Device Type (8 bits) + +This field is used to advertise the Basic Device Type reported by the node. + +For a detailed description of the Basic Device Type [field, refer to [ device_class_spec ] for Z-Wave nodes, [ device_type_spec ] for Z-Wave Plus nodes, and [ device_type_spec_v2 ] for Z-Wave Plus v2 nodes.](../../05-references.md#5-references) + +Generic Device Type (8 bits) + +[This field is used to advertise the Generic Device Type reported by the node.](../../05-references.md#5-references) + +For a detailed description of the Generic Device Type [field, refer to [ device_class_spec ] for Z-Wave nodes, [ device_type_spec ] for Z-Wave Plus nodes, and [ device_type_spec_v2 ] for Z-Wave Plus v2](../../05-references.md#5-references) nodes. + +Specific Device Type (8 bits) + +[This field is used to advertise the Specific Device Type reported by the node.](../../05-references.md#5-references) + +For a detailed description of the Specific Device Type [field, refer to [ device_class_spec ] for Z-Wave nodes, [ device_type_spec ] for Z-Wave Plus nodes, and [ device_type_spec_v2 ] for Z-Wave Plus v2](../../05-references.md#5-references) nodes. + +Supported Command Class List (N bytes) This field is used to advertise the list of supported Command Classes reported by the node during its inclusion. + +This list represents the non-secure supported Command Classes. + +The length of this field, in bytes, MUST be according to the Supported Command Class List Length field. + +A host application SHOULD request the node’s capabilities again after S0/S2 bootstrapping. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.02-add-controller-and-assign-primary-controller-role-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.02-add-controller-and-assign-primary-controller-role-command.md new file mode 100644 index 0000000..45c3810 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.02-add-controller-and-assign-primary-controller-role-command.md @@ -0,0 +1,90 @@ + +# 4.4.3.2 Add Controller And Assign Primary Controller Role Command + +This command is used to include and give the Primary Controller Role to another controller node. The Assign Primary Controller Role Command Identifier is 0x4C. + +This command MUST be used by a host application only if the Z-Wave API Module is Secondary Controller, has the SUC Role and the Primary Controller has been removed from the network. + +This command MUST NOT be used in any other case. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with callback .](../../03-interface-communication/03.03-command-frame-flows.md#334-acknowledged-frame-with-callback) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.103](04.04.03.02-add-controller-and-assign-primary-controller-role-command.md#4432-add-controller-and-assign-primary-controller-role-command) + +Table 4.103: Add Controller And Assign Primary Controller Role Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x4C | | | | | | | | +| 5 | Power | NWI | Reserved | Mode | | | | | +| 6 | Session Identifier | | | | | | | | + +Power (1 bit) + +This field is used to indicate which power to use for the Network Inclusion operation. + +• The value 0 MUST indicate that the Z-Wave Module MUST use reduced power for the network inclusion. + +• The value 1 MUST indicate that the Z-Wave Module MUST use normal power for the network inclusion. + +NWI (1 bit) + +This field is used to indicate if the operation must be a direct range Network Inclusion or NWI. + +• The value 0 MUST indicate that the Z-Wave Module MUST use direct range network inclusion for the network inclusion. + +• The value 1 MUST indicate that the Z-Wave Module MUST use NWI for the network inclusion. + +Mode (5 bits) + +This field is used to indicate which “Add Mode” operation the Z-Wave Module MUST carry out. + +[This field MUST encoded according to Table 4.104](04.04.03.02-add-controller-and-assign-primary-controller-role-command.md#4432-add-controller-and-assign-primary-controller-role-command) Table 4.104: Add Controller And Assign Primary Controller Role Command - Mode encoding + +| Value | Description | +| --- | --- | +| 0x01 | Start Add Mode The Z-Wave API Module MUST start network inclusion and attempt to add a con- troller node. The Z-Wave API Module MUST keep in network inclusion mode until this command is called again with the Mode set to 0x05 or 0x06 | +| 0x02..0x04 | Reserved. These values are reserved. Reserved values MUST NOT be used and MUST be ig- nored by a receiving interface. | +| 0x05 | Stop Add Mode The Z-Wave API Module MUST stop network inclusion. | +| 0x06 | Stop Add Mode due to a failure The Z-Wave API Module MUST stop network inclusion and report a failure to the other controller node. | +| 0x07..0xFF | Reserved. These values are reserved. Reserved values MUST NOT be used and MUST be ig- nored by a receiving interface. | + +[Session Identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +None. + +3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.105](04.04.03.02-add-controller-and-assign-primary-controller-role-command.md#4432-add-controller-and-assign-primary-controller-role-command) + +Table 4.105: Add Controller And Assign Primary Controller Role Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x4C | | | | | | | | +| 5 | Session Identifier | | | | | | | | +| 6 | Status | | | | | | | | +| 7/7..8 | Assigned NodeID | | | | | | | | +| 8/9 | Supported Command Class List Length | | | | | | | | +| 9/10 | Basic Device Type | | | | | | | | +| 10/11 | Generic Device Type | | | | | | | | +| 11/12 | Specific Device Type | | | | | | | | +| 12/13 | Supported Command Class List 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 12/13+N | Supported Command Class List N | | | | | | | | + +[For fields description, refer to Add Node To Network Command](04.04.03.01-add-node-to-network-command.md#4431-add-node-to-network-command) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.03-add-primary-controller-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.03-add-primary-controller-command.md new file mode 100644 index 0000000..0fb7a61 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.03-add-primary-controller-command.md @@ -0,0 +1,90 @@ + +# 4.4.3.3 Add Primary Controller Command + +This command is used to include a controller node and assign it the Primary Controller Role. The Add Primary Controller Command Identifier is 0x4D. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with callback .](../../03-interface-communication/03.03-command-frame-flows.md#334-acknowledged-frame-with-callback) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.106](04.04.03.03-add-primary-controller-command.md#4433-add-primary-controller-command) + +Table 4.106: Add Primary Controller Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x4D | | | | | | | | +| 5 | Power | NWI | Reserved | Mode | | | | | +| 6 | Session Identifier | | | | | | | | + +Power (1 bit) + +This field is used to indicate which power to use for the Network Inclusion operation. + +• The value 0 MUST indicate that the Z-Wave Module MUST use reduced power for the network inclusion. + +• The value 1 MUST indicate that the Z-Wave Module MUST use normal power for the network inclusion. + +NWI (1 bit) + +This field is used to indicate if the operation must be a direct range Network Inclusion or NWI. + +• The value 0 MUST indicate that the Z-Wave Module MUST use direct range network inclusion for the network inclusion. + +• The value 1 MUST indicate that the Z-Wave Module MUST use NWI for the network inclusion. + +Mode (5 bits) + +This field is used to indicate which “Add Mode” operation the Z-Wave Module MUST carry out. + +[This field MUST encoded according to Table 4.107](04.04.03.03-add-primary-controller-command.md#4433-add-primary-controller-command) + +Table 4.107: Add Primary Controller Command - Mode encoding + +| Value | Description | +| --- | --- | + +| | 0x01 | Start Add Mode The Z-Wave API Module MUST start network inclusion and attempt to add a con- troller node. The Z-Wave API Module MUST keep in network inclusion mode until this command is called again with the Mode set to 0x05 or 0x06. | | +| --- | --- | --- | --- | +| | 0x02..0x04 | Reserved. These values are reserved. Reserved values MUST NOT be used and MUST be ig- nored by a receiving interface. | | +| | 0x05 | Stop Add Mode The Z-Wave API Module MUST stop network inclusion. | | +| | 0x06 | Stop Add Mode due to a failure The Z-Wave API Module MUST stop network inclusion and report a failure to the other controller node. | | +| | 0x07..0xFF | Reserved. These values are reserved. Reserved values MUST NOT be used and MUST be ig- nored by a receiving interface. | | + +Session Identifier (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +None. + +3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.108](04.04.03.03-add-primary-controller-command.md#4433-add-primary-controller-command) + +Table 4.108: Add Primary Controller Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x4D | | | | | | | | +| 5 | Session Identifier | | | | | | | | +| 6 | Status | | | | | | | | +| 7/8 | Assigned NodeID | | | | | | | | +| 8/9 | Supported Command Class List Length | | | | | | | | +| 9/10 | Basic Device Type | | | | | | | | +| 10/11 | Generic Device Type | | | | | | | | +| 11/12 | Specific Device Type | | | | | | | | +| 12/13 | Supported Command Class List 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 12/13+N | Supported Command Class List N | | | | | | | | + +[For fields description, refer to Add Node To Network Command](04.04.03.01-add-node-to-network-command.md#4431-add-node-to-network-command) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.04-remove-node-from-network-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.04-remove-node-from-network-command.md new file mode 100644 index 0000000..08dcf0b --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.04-remove-node-from-network-command.md @@ -0,0 +1,126 @@ + +# 4.4.3.4 Remove Node From Network Command + +This command is used to trigger a node removal operation from a Z-Wave network. It is also possible to perform out-of-range removal of nodes from the network when repeater nodes are capable of forwarding the new network wide exclusion (NWE) frame. The Remove Node From Network Command Identifier is 0x4B. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with callback .](../../03-interface-communication/03.03-command-frame-flows.md#334-acknowledged-frame-with-callback) + +The host application may issue several 1. initial data frames several during an inclusion and the Z-Wave API module may issue sereval 3. callback data frames during an inclusion. + +[Figure 4.12 and Figure 4.13 show examples of successful network exclusion.](04.04.03.04-remove-node-from-network-command.md#4434-remove-node-from-network-command) + +![Figure 4.12: Remove Node From Network Command Success Example](assets/img-61cdc0dbcd.png) + +![Figure 4.13: Remove Node From Network Command foreign network Success Example](assets/img-1758be6e77.png) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.109](04.04.03.04-remove-node-from-network-command.md#4434-remove-node-from-network-command) + +Table 4.109: Remove Node From Network Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x4B | | | | | | | | +| 5 | Power | NWE | Res | Mode | | | | | +| 6 | Session Identifier | | | | | | | | + +Power (1 bit) + +This field is used to indicate which power to use for the removal node operation. + +• The value 0 MUST indicate that the Z-Wave Module MUST use reduced power for the removal node operation. + +• The value 1 MUST indicate that the Z-Wave Module MUST use normal power for the removal node operation. + +NWE (1 bit) This field is used to indicate if direct range Network Exclusion or NWE. • The value 0 MUST indicate that the Z-Wave Module MUST use direct range exclusion for the removal node operation. + +• The value 1 MUST indicate that the Z-Wave Module MUST use NWE for the removal node operation. + +Mode (4 bits) + +This field is used to indicate which “Remove Mode” operation the Z-Wave Module MUST carry out. + +[This field MUST encoded according to Table 4.110](04.04.03.04-remove-node-from-network-command.md#4434-remove-node-from-network-command) + +Table 4.110: Remove Node From Network Command - Mode en- coding + +| Vale | Description | +| --- | --- | +| 0x01 | Remove any node. The Z-Wave Module MUST start network exclusion and attempt to remove any type of node. The Z-Wave Module MUST keep in removal process (network exclusion mode) until this command is called again with the Mode set to 0x05. | +| 0x02 | Deprecated: Remove controller node. Use Remove any node (0x01) instead. | +| 0x03 | Deprecated: Remove End Node. Use Remove any node (0x01) instead. | +| 0x04 | Reserved. This value is reserved. | +| 0x05 | Stop network exclusion. The Z-Wave Module MUST stop the ongoing or completed network exclusion. | +| 0x06..0x3F | Reserved. These values are reserved. Reserved values MUST NOT be used and MUST be ig- nored by a receiving interface. | + +[Session Identifier(8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +None. + +3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.111](04.04.03.04-remove-node-from-network-command.md#4434-remove-node-from-network-command) Table 4.111: Remove Node From Network Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x4B | | | | | | | | +| 5 | Session Identifier | | | | | | | | +| 6 | Status | | | | | | | | +| 7/7..8 | NodeID | | | | | | | | +| 8/9 | Supported Command Class List Length | | | | | | | | +| 9/10 | Basic Device Type | | | | | | | | +| 10/11 | Generic Device Type | | | | | | | | +| 11/12 | Specific Device Type | | | | | | | | +| 12/13 | Supported Command Class List 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 12/13+N | Supported Command Class List N | | | | | | | | + +[For fields not described below, refer to Add Node To Network Command - 3. Callback data frame .](04.04.03.01-add-node-to-network-command.md#4431-add-node-to-network-command) + +Session Identifier (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +Status (8 bits) + +This field is used to advertise the current status of the node removal process. + +[This field MUST be according to Table 4.112](04.04.03.04-remove-node-from-network-command.md#4434-remove-node-from-network-command) + +Table 4.112: Remove Node From Network Command - Status en- coding + +| Value | Description | +| --- | --- | +| 0x01 | Network Exclusion Started. The Z-Wave Module has initiated Network exclusion and is ready to remove existing nodes | +| 0x02 | Node found. A node requesting exclusion has been found and the node removal operation is initi- ated. | +| 0x03 | Exclusion ongoing (End Node) The network exclusion is ongoing with an End Node. | +| 0x04 | Exclusion ongoing (controller node) The network exclusion is ongoing with a Controller node. | +| 0x05 | Reserved. This value is reserved. | +| 0x06 | Exclusion completed Node removal operation is completed. The Z-Wave Module is ready to return to idle and the host application SHOULD issue a new Remove Node From Network Com- mand - Initial data frame with the Mode set to 0x05 to stop the network exclusion. | + +| 0x07 | Exclusion failed Removal node operation is failed. This indicates the node may not have been re- moved, and the host application SHOULD issue a new Remove Node From Network Command - Initial data frame with the Mode set to 0x05 to stop the network exclu- sion. | +| --- | --- | +| 0x23 | Not Primary The node exclusion operation cannot be performed because the Z-Wave API Module does not have the Primary Controller role and the SIS functionality is not available in the current network. | + +Values that are not described in table_remove_node_from_network_status_encoding are reserved and MUST NOT be used. + +NodeID (8/16 bits) + +This field indicates the NodeID of the node that was removed from a network. + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +The value 0 MUST indicate that no node was removed (yet) in our current network. A Z-Wave API Moduel MUST set this value to 0 if excluding a node from a foreign network. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.05-remove-specific-node-from-network-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.05-remove-specific-node-from-network-command.md new file mode 100644 index 0000000..93afb86 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.05-remove-specific-node-from-network-command.md @@ -0,0 +1,61 @@ + +# 4.4.3.5 Remove Specific Node From Network Command + +This command is used to trigger a specific node removal operation from a Z-Wave network. It is also possible to perform out-of-range removal of specific node from the network when repeater nodes are capable of forwarding the new network wide exclusion (NWE) frame. The Remove Specific Node From Network Command Identifier is 0x3F. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with callback .](../../03-interface-communication/03.03-command-frame-flows.md#334-acknowledged-frame-with-callback) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.113 .](04.04.03.05-remove-specific-node-from-network-command.md#4435-remove-specific-node-from-network-command) + +Table 4.113: Remove Specific Node From Network Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x3F | | | | | | | | +| 5 | Power | NWE | Res | Mode | | | | | +| 6/6..7 | NodeID | | | | | | | | +| 7/8 | Session Identifier | | | | | | | | + +[Refer to Remove Node From Network Command Initial data frame for fields that are not described below.](04.04.03.04-remove-node-from-network-command.md#4434-remove-node-from-network-command) + +NodeID (8/16 bits) + +This field is used to indicate the NodeID to be removed from a network. + +Nodes with this NodeID seeking exclusion will be excluded from their network by the Z-Wave API Module. Nodes with a different NodeID seeking exclusion will not be excluded from their network by the Z-Wave API Module. + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +2. Response data frame (Z-Wave Module → host) + +None. + +3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.114 after a specific](04.04.03.05-remove-specific-node-from-network-command.md#4435-remove-specific-node-from-network-command) node removal operation is performed. Table 4.114: Remove Specific Node From Network Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x3F | | | | | | | | +| 5 | Session Identifier | | | | | | | | +| 6 | Status | | | | | | | | +| 7/7..8 | NodeID | | | | | | | | +| 8/9 | Supported Command Class List Length | | | | | | | | +| 9/10 | Basic Device Type | | | | | | | | +| 10/11 | Generic Device Type | | | | | | | | +| 11/12 | Specific Device Type | | | | | | | | +| 12/13 | Supported Command Class List 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 12/13+N | Supported Command Class List N | | | | | | | | + +[For fields description, refer to Remove Node From Network Command Callback data frame .](04.04.03.04-remove-node-from-network-command.md#4434-remove-node-from-network-command) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.06-is-node-failed-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.06-is-node-failed-command.md new file mode 100644 index 0000000..75795e3 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.06-is-node-failed-command.md @@ -0,0 +1,52 @@ + +# 4.4.3.6 Is Node Failed Command + +This command is used to request if a given NodeID is considered as failed by the Z-Wave API Module. Is Failed Node Command Identifier is 0x62. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.115 to check a given NodeID presence](04.04.03.06-is-node-failed-command.md#4436-is-node-failed-command) in the Z-Wave API Module failed NodeID list. + +Table 4.115: Is Failed Node Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x62 | | | | | | | | +| 5/5..6 | NodeID | | | | | | | | + +NodeID (8/16 bits) + +This field is used to advertise the NodeID that will be checked if it is stored in the controller failed NodeID list. + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.116 .](04.04.03.06-is-node-failed-command.md#4436-is-node-failed-command) + +Table 4.116: Is Failed Node Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x62 | | | | | | | | +| 5 | FailedNodeID presence | | | | | | | | + +FailedNodeID presence (8 bits) + +This field is used to advertise the presence of a given NodeID in controller failed NodeID list. This field MUST be encoded as follow: + +• The field value MUST be 0x00, if the NodeID is not stored in the controller failed NodeID list. + +• The field value MUST be 0x01, if the NodeID is stored in the controller failed NodeID list. 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.07-remove-failed-node-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.07-remove-failed-node-command.md new file mode 100644 index 0000000..33a453c --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.07-remove-failed-node-command.md @@ -0,0 +1,90 @@ + +# 4.4.3.7 Remove Failed Node Command + +This command is used to request a non-responding node removal operation from the controller routing table. When a node is non-responding, its’ NodeID shall be included in the failed NodeID list. If the node responding again it shall be removed from the failed NodeID list. A failed node MUST only be removed if the NodeID is in the failed NodeID list and extra precaution shall be considered before the failed node is removed. A responding node MUST NOT be removed. The Remove Failed Node Command Identifier is 0x61. + +Note that this command MUST only be used by Primary Controller and an Inclusion Controller. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.117 to trigger a failed node removal](04.04.03.07-remove-failed-node-command.md#4437-remove-failed-node-command) from the controller routing table. + +Table 4.117: Remove Failed Node Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x61 | | | | | | | | +| 5/5..6 | NodeID | | | | | | | | +| 6/7 | Session identifier | | | | | | | | + +NodeID (8/16 bits) + +This field is used to advertise the NodeID of a failed node that will be removed from the routing table. [This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[Session identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.118 .](04.04.03.07-remove-failed-node-command.md#4437-remove-failed-node-command) + +Table 4.118: Remove Failed Node Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x61 | | | | | | | | +| 5 | Remove Failed Node Response Status | | | | | | | | + +Remove Failed Node Response Status (8 bits) + +This field is used to indicate the Z-Wave module response regarding the remove failed node request. [This field MUST be encoded according to Table 4.119 .](04.04.03.07-remove-failed-node-command.md#4437-remove-failed-node-command) + +Table 4.119: Remove Failed Node Response Status value encoding + +| Value | Flag and description | +| --- | --- | +| 0x00 | ZW FAILED NODE REMOVE STARTED _ _ _ _ The failed node removing process started successfully. | +| 0x01 | ZW NOT PRIMARY CONTROLLER _ _ _ The removing process was aborted because the controller is not the Primary Controller. | +| 0x02 | ZW NO CALLBACK FUNCTION _ _ _ The removing process was aborted because no Session identifier is used. | +| 0x03 | ZW FAILED NODE NOT FOUND _ _ _ _ The requested process failed. The NodeID was not found in the controller list of failed NodeID list. | +| 0x04 | ZW FAILED NODE REMOVE PROCESS BUSY _ _ _ _ _ The Z-Wave Protocol is busy. | +| 0x05 | ZW FAILED NODE REMOVE FAIL _ _ _ _ The removing process request is failed. This can happen if the controller is busy or the node is responding. | +| 0x6..0xFF | Reserved Reserved values MUST NOT be used. | + +3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.120 to notify the appli-](04.04.03.07-remove-failed-node-command.md#4437-remove-failed-node-command) cation regarding the failed node removal operation status. + +Table 4.120: Remove Failed Node Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x61 | | | | | | | | +| 5 | Session identifier | | | | | | | | +| 6 | Remove Failed Node Operation Status | | | | | | | | + +Session identifier (8 bits) + +[Refer to Response status (8 bits) .](../04.02-generic-command-elements.md#425-response-status-8-bits) + +Remove Failed Node Operation Status (8 bits) + +This field is used to notify the status of failed node removal operation. This field MUST be encoded [according to Table 4.121 .](04.04.03.07-remove-failed-node-command.md#4437-remove-failed-node-command) Table 4.121: Remove Failed Node Operation Status value encod- ing + +| Value | Flag and description | +| --- | --- | +| 0x00 | ZW NODE OK _ _ The node is working properly and it is a responding node. The NodeID of the node MUST be removed from the failed NodeID list. | +| 0x01 | ZW FAILED NODE REMOVED _ _ _ The failed node was removed from the routing table and failed nodes list. | +| 0x02 | ZW FAILED NODE NOT REMOVED _ _ _ _ The failed node was not removed because the removing process cannot be com- pleted. | +| 0x3..0xFF | Reserved Reserved values MUST NOT be used. | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.08-replace-failed-node-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.08-replace-failed-node-command.md new file mode 100644 index 0000000..e6b0759 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.08-replace-failed-node-command.md @@ -0,0 +1,98 @@ + +# 4.4.3.8 Replace Failed Node Command + +This command is used to replace a non-responding node with a new node. Responding nodes MUST NOT be replaced. The Replace Failed Node Command Identifier is 0x63. + +Note that this command MUST only be used by Primary Controller and an Inclusion Controller. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) + +[Figure 4.14 shows an example of a successful failed node replacement.](04.04.03.08-replace-failed-node-command.md#4438-replace-failed-node-command) + +![Figure 4.14: Replace Failed Node Success Example](assets/img-e8d90d038c.png) + +[Figure 4.15 shows an example of an unsuccessful failed node replacement.](04.04.03.08-replace-failed-node-command.md#4438-replace-failed-node-command) + +![Figure 4.15: Replace Failed Node Example](assets/img-c666cce873.png) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.122 to replace a failed node with a new](04.04.03.08-replace-failed-node-command.md#4438-replace-failed-node-command) node. + +Table 4.122: Replace Failed Node Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x63 | | | | | | | | +| 5/5..6 | NodeID | | | | | | | | +| 6 | Session identifier | | | | | | | | + +NodeID (8/16 bits) + +[This field is used to advertise the NodeID of a failed node that will be assigned to a new node.](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[Session identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.123 .](04.04.03.08-replace-failed-node-command.md#4438-replace-failed-node-command) Table 4.123: Replace Failed Node Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x63 | | | | | | | | +| 5 | Replace Failed Node Response Status | | | | | | | | + +Replace Failed Node Response Status (8 bits) + +This field is used to indicate the Z-Wave module response regarding the replace failed node request. [This field MUST be encoded according to Table 4.124 .](04.04.03.08-replace-failed-node-command.md#4438-replace-failed-node-command) + +Table 4.124: Remove Failed Node Response Status value encoding + +| Value | Flag and description | +| --- | --- | +| 0x00 | ZW FAILED NODE REMOVE STARTED _ _ _ _ The failed node replacing process started successfully. | +| 0x01 | ZW NOT PRIMARY CONTROLLER _ _ _ The replacing process was aborted because the controller is not the Primary Con- troller. | +| 0x02 | ZW NO CALLBACK FUNCTION _ _ _ The replacing process was aborted because no Session identifier is used. | +| 0x03 | ZW FAILED NODE NOT FOUND _ _ _ _ The requested process failed. The NodeID was not found in the controller list of failed NodeID list. | +| 0x04 | ZW FAILED NODE REMOVE PROCESS BUSY _ _ _ _ _ The Z-Wave API module is busy and cannot carry the operation. | +| 0x05 | ZW FAILED NODE REMOVE FAIL _ _ _ _ The replacing process request has failed. This can happen if the Z-Wave API module is busy or the node is responding. | +| 0x6..0xFF | Reserved Reserved values MUST NOT be used. | + +3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.125](04.04.03.08-replace-failed-node-command.md#4438-replace-failed-node-command) + +Table 4.125: Replace Failed Node Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x63 | | | | | | | | +| 5 | Session identifier | | | | | | | | +| 6 | Replace Failed Node Operation Status | | | | | | | | + +[Session identifier (8 bits)](../04.02-generic-command-elements.md#425-response-status-8-bits) + +[Refer to Response status (8 bits) .](../04.02-generic-command-elements.md#425-response-status-8-bits) + +Replace Failed Node Operation Status (8 bits) This field is used to notify the status of replace failed node operation. This field MUST be encoded [according to Table 4.126 .](04.04.03.08-replace-failed-node-command.md#4438-replace-failed-node-command) Table 4.126: Replace Failed Node Operation Status value encod- ing + +| Value | Flag and description | +| --- | --- | +| 0x00 | ZW NODE OK _ _ The node is working properly and it is a responding node. The NodeID of the node shall be removed from the failed NodeID list. It also indicates that replace process is stopped. | +| 0x1..0x02 | Reserved Reserved values MUST NOT be used. | +| 0x03 | ZW FAILED NODE REPLACE _ _ _ The failed node is ready to be replaced and controller is ready to add new node with the NodeID of the failed node. | +| 0x04 | ZW FAILED NODE REPLACE DONE _ _ _ _ The failed node has been replaced. | +| 0x05 | ZW FAILED NODE REPLACE FAILED _ _ _ _ The failed node has not been replaced. | +| 0x06..0xFF | Reserved Reserved values MUST NOT be used. | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.09-delete-return-route-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.09-delete-return-route-command.md new file mode 100644 index 0000000..16143dc --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.09-delete-return-route-command.md @@ -0,0 +1,73 @@ + +# 4.4.3.9 Delete Return Route Command + +This command is used to request the deletion of the static return routes. The Delete Return Route Command Identifier is 0x47. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.127 .](04.04.03.09-delete-return-route-command.md#4439-delete-return-route-command) + +Table 4.127: Delete Return Route Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x47 | | | | | | | | +| 5/5..6 | NodeID | | | | | | | | +| 6/7 | Session identifier | | | | | | | | + +NodeID (8/16 bits) + +[This field is used to indicates the NodeID for which the static return routes is requested to be deleted.](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[Session identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.128 .](04.04.03.09-delete-return-route-command.md#4439-delete-return-route-command) + +Table 4.128: Delete Return Route Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x47 | | | | | | | | +| 5 | Delete Return Route Response | | | | | | | | + +Delete Return Route Response (8 bits) + +This field is used to advertise the response of the Z-Wave module regarding the acceptance of the Delete Return Route Command Initial data frame. This field MUST be encoded as follow: + +• If delete return route operation is started, this field value MUST be set to 0x01. • If an “assign/delete return route” operation is already active, this field value MUST be set to 0x00. + +3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.129 .](04.04.03.09-delete-return-route-command.md#4439-delete-return-route-command) + +Table 4.129: Delete Return Route Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x47 | | | | | | | | +| 5 | Session identifier | | | | | | | | +| 6 | Tx Status | | | | | | | | + +Session identifier (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +Tx Status (8 bits) + +[Refer to Tx Status (8 bits) .](../04.02-generic-command-elements.md#423-tx-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.10-assign-return-route-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.10-assign-return-route-command.md new file mode 100644 index 0000000..7348dca --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.10-assign-return-route-command.md @@ -0,0 +1,80 @@ + +# 4.4.3.10 Assign Return Route Command + +[This command is used to assign return routes to end nodes in a network. Refer to [ zwave_nwk_spec ]](../../05-references.md#5-references) for details. The Assign Return Route Command Identifier is 0x46. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.130 .](04.04.03.10-assign-return-route-command.md#44310-assign-return-route-command) + +Table 4.130: Assign Return Route Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x46 | | | | | | | | +| 5/5..6 | NodeID | | | | | | | | +| 6/7..8 | Destination NodeID | | | | | | | | +| 7/9 | Session Identifier | | | | | | | | + +NodeID (8 bits/16 bits) + +This field is used to indicate the NodeID for which the return route for the destination must be assigned by the Z-Wave API Module. + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Destination NodeID (8 bits/16 bits) + +This field is used to indicate the Destination NodeID for which the return route must be assigned by the Z-Wave API Module. + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[Session identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.131](04.04.03.10-assign-return-route-command.md#44310-assign-return-route-command) + +Table 4.131: Assign Return Route Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | + +| 4 | Z-Wave API Command ID = 0x46 | +| --- | --- | +| 5 | Response Status | + +Response status (8 bits) + +[Refer to Response status (8 bits) .](../04.02-generic-command-elements.md#425-response-status-8-bits) + +3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.132](04.04.03.10-assign-return-route-command.md#44310-assign-return-route-command) + +Table 4.132: Assign Return Route Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x46 | | | | | | | | +| 5 | Session Identifier | | | | | | | | +| 6 | Tx Status | | | | | | | | + +[Session Identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Tx Status (8 bits)](../04.02-generic-command-elements.md#423-tx-status-8-bits) + +[Refer to Tx Status (8 bits) .](../04.02-generic-command-elements.md#423-tx-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.11-assign-suc-return-route-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.11-assign-suc-return-route-command.md new file mode 100644 index 0000000..f4e920d --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.11-assign-suc-return-route-command.md @@ -0,0 +1,71 @@ + +# 4.4.3.11 Assign SUC Return Route Command + +This command is used to Assign a Return Route to the SUC NodeID. + +The Assign SUC Return Route Command Identifier is 0x51 + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.133](04.04.03.11-assign-suc-return-route-command.md#44311-assign-suc-return-route-command) + +Table 4.133: Assign SUC Return Route Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x51 | | | | | | | | +| 5/5..6 | NodeID | | | | | | | | +| 6/7 | Session Identifier | | | | | | | | + +NodeID (8 bits/16 bits) + +This field is used to indicate the NodeID for which the return route for the SUC must be assigned by the Z-Wave API Module. + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[Session identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.134](04.04.03.11-assign-suc-return-route-command.md#44311-assign-suc-return-route-command) + +Table 4.134: Assign SUC Return Route Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x51 | | | | | | | | +| 5/5..6 | Response Status | | | | | | | | + +[Response status (8 bits)](../04.02-generic-command-elements.md#425-response-status-8-bits) + +[Refer to Response status (8 bits) .](../04.02-generic-command-elements.md#425-response-status-8-bits) 3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.135](04.04.03.11-assign-suc-return-route-command.md#44311-assign-suc-return-route-command) + +Table 4.135: Assign SUC Return Route Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x51 | | | | | | | | +| 5 | Session Identifier | | | | | | | | +| 6 | Tx Status | | | | | | | | + +[Session Identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Tx Status (8 bits)](../04.02-generic-command-elements.md#423-tx-status-8-bits) + +[Refer to Tx Status (8 bits) .](../04.02-generic-command-elements.md#423-tx-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.12-assign-priority-return-route-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.12-assign-priority-return-route-command.md new file mode 100644 index 0000000..8921c20 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.12-assign-priority-return-route-command.md @@ -0,0 +1,93 @@ + +# 4.4.3.12 Assign Priority Return Route Command + +This command is used to assign priority route to end nodes. An end node MUST always use the priority [route for the first transmission attempt. Refer to [ zwave_nwk_spec ] for details. The Assign Priority](../../05-references.md#5-references) Return Route Command Identifier is 0x4F. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.136 .](04.04.03.12-assign-priority-return-route-command.md#44312-assign-priority-return-route-command) + +Table 4.136: Assign Priority Return Route Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x4F | | | | | | | | +| 5/5..6 | NodeID | | | | | | | | +| 6/7..8 | Route Destination NodeID | | | | | | | | +| 7/9 | Repeater 0 | | | | | | | | +| 8/10 | Repeater 1 | | | | | | | | +| 9/11 | Repeater 2 | | | | | | | | +| 10/12 | Repeater 3 | | | | | | | | +| 11/13 | Route Speed | | | | | | | | +| 12/14 | Session Identifier | | | | | | | | + +NodeID (8/16 bits) + +[This field is used to advertise the NodeID of the end node which shall receive defined priority route.](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Route Destination NodeID (8/16 bits) + +This field is used to indicate the destination NodeID which the end node shall use the defined priority route while transmitting a packet to it. + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[Repeater (4 bytes)](../04.02-generic-command-elements.md#4212-repeater-4-bytes) + +[Refer to Repeater (4 bytes) .](../04.02-generic-command-elements.md#4212-repeater-4-bytes) + +[Route Speed (8 bits)](../04.02-generic-command-elements.md#4211-route-speed-8-bits) + +[Refer to Route Speed (8 bits) .](../04.02-generic-command-elements.md#4211-route-speed-8-bits) [Session identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.137 .](04.04.03.12-assign-priority-return-route-command.md#44312-assign-priority-return-route-command) + +Table 4.137: Assign Priority Return Route Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x4F | | | | | | | | +| 5 | Assign Priority Route Response | | | | | | | | + +Assign Priority Route Response (8 bits) + +This field is used to advertise the response of the Z-Wave API module regarding the acceptance of the Assign Priority Return Route Command Initial data frame. This field MUST be encoded as follow: + +• If assign priority return route operation is started, this field value MUST be set to 0x01. + +• If an “assign/delete return route” operation is already active, this field value MUST be set to 0x00. + +3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.138 .](04.04.03.12-assign-priority-return-route-command.md#44312-assign-priority-return-route-command) + +Table 4.138: Assign Priority Return Route Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x4F | | | | | | | | +| 5 | Session Identifier | | | | | | | | +| 6 | Tx Status | | | | | | | | + +[Session identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Tx Status (8 bits)](../04.02-generic-command-elements.md#423-tx-status-8-bits) + +[Refer to Tx Status (8 bits) .](../04.02-generic-command-elements.md#423-tx-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.13-assign-priority-suc-return-route-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.13-assign-priority-suc-return-route-command.md new file mode 100644 index 0000000..4e66aba --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.13-assign-priority-suc-return-route-command.md @@ -0,0 +1,86 @@ + +# 4.4.3.13 Assign Priority SUC Return Route Command + +This command is used to assign a priority return route to reach the SUC NodeID. The Assign Priority SUC Return Route Command Identifier is 0x58. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.139 .](04.04.03.13-assign-priority-suc-return-route-command.md#44313-assign-priority-suc-return-route-command) + +Table 4.139: Assign Priority SUC Return Route Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x58 | | | | | | | | +| 5/5..6 | NodeID | | | | | | | | +| 6/7 | Repeater 0 | | | | | | | | +| 7/8 | Repeater 1 | | | | | | | | +| 8/10 | Repeater 2 | | | | | | | | +| 9/11 | Repeater 3 | | | | | | | | +| 10/12 | Route Speed | | | | | | | | +| 11/13 | Session Identifier | | | | | | | | + +NodeID (8/16 bits) + +This field is used to advertise the NodeID of the end node which shall receive defined priority route to reach SUC/SIS. + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[Repeater (4 bytes)](../04.02-generic-command-elements.md#4212-repeater-4-bytes) + +[Refer to Repeater (4 bytes) .](../04.02-generic-command-elements.md#4212-repeater-4-bytes) + +[Route Speed (8 bits)](../04.02-generic-command-elements.md#4211-route-speed-8-bits) + +[Refer to Route Speed (8 bits) .](../04.02-generic-command-elements.md#4211-route-speed-8-bits) + +[Session identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.140 .](04.04.03.13-assign-priority-suc-return-route-command.md#44313-assign-priority-suc-return-route-command) Table 4.140: Assign Priority SUC Return Route Command - Re- sponse data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x58 | | | | | | | | +| 5 | Assign Priority SUC Route Response | | | | | | | | + +Assign Priority SUC Route Response (8 bits) + +This field is used to advertise the response of the Z-Wave API module regarding the acceptance of the Assign Priority SUC Return Route Command Initial data frame. This field MUST be encoded as follow: + +• If assign priority SUC return route operation is started, this field value MUST be set to 0x01. + +• If an “assign/delete return route” operation is already active, this field value MUST be set to 0x00. + +3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.141 .](04.04.03.13-assign-priority-suc-return-route-command.md#44313-assign-priority-suc-return-route-command) + +Table 4.141: Assign Priority SUC Return Route Command - Call- back data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x58 | | | | | | | | +| 5 | Session Identifier | | | | | | | | +| 6 | Tx Status | | | | | | | | + +Session identifier (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Tx Status (8 bits)](../04.02-generic-command-elements.md#423-tx-status-8-bits) + +[Refer to Tx Status (8 bits) .](../04.02-generic-command-elements.md#423-tx-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.14-set-priority-route-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.14-set-priority-route-command.md new file mode 100644 index 0000000..ccea1f5 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.14-set-priority-route-command.md @@ -0,0 +1,61 @@ + +# 4.4.3.14 Set Priority Route Command + +This command is used to set the Priority Route for a destination node. The Priority Route is the route that shall be used as the first routing attempt by the Z-Wave protocol when transmitting to a node. The Priority Route is expected to be stored in NVM of the Z-Wave module. The Set Priority Route Command Identifier is 0x93. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.142 to set the Priority Route.](04.04.03.14-set-priority-route-command.md#44314-set-priority-route-command) + +Table 4.142: Set Priority Route Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x93 | | | | | | | | +| 5/5..6 | NodeID | | | | | | | | +| 6/7 | Repeater 0 | | | | | | | | +| 7/8 | Repeater 1 | | | | | | | | +| 8/9 | Repeater 2 | | | | | | | | +| 9/10 | Repeater 3 | | | | | | | | +| 10/11 | Route Speed | | | | | | | | + +NodeID (8/16 bits) + +[This field is used to indicate the destination NodeID for which the Priority Route is set to.](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Repeater (4 bytes) + +[Refer to Repeater (4 bytes) .](../04.02-generic-command-elements.md#4212-repeater-4-bytes) + +[Route Speed (8 bits)](../04.02-generic-command-elements.md#4211-route-speed-8-bits) + +[Refer to Route Speed (8 bits) .](../04.02-generic-command-elements.md#4211-route-speed-8-bits) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.143 .](04.04.03.14-set-priority-route-command.md#44314-set-priority-route-command) Table 4.143: Set Priority Route Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x93 | | | | | | | | +| 5 | Command Status | | | | | | | | + +Command Status (8 bits) + +[Refer to Command Status (8 bits) .](../04.02-generic-command-elements.md#426-command-status-8-bits) + +3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.15-get-priority-route-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.15-get-priority-route-command.md new file mode 100644 index 0000000..c1c3165 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.15-get-priority-route-command.md @@ -0,0 +1,61 @@ + +# 4.4.3.15 Get Priority Route Command + +This command is used to request the priority route that is defined in the Z-Wave API module. If a route [has been set to the module using Set Priority Route Command , the module MUST provide the priority](04.04.03.14-set-priority-route-command.md#44314-set-priority-route-command) [route using Get Priority Route Command Response frame. If no priority route has been set in the module, the Get Priority Route Command Response frame MUST contain either the Last Working Route](04.04.03.15-get-priority-route-command.md#44315-get-priority-route-command) (LWR) or the Next to Last Working Route (NLWR). The Get Priority Route Command Identifier is 0x92. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.144 .](04.04.03.15-get-priority-route-command.md#44315-get-priority-route-command) + +Table 4.144: Get Priority Route Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x92 | | | | | | | | +| 5/5..6 | NodeID | | | | | | | | + +NodeID (8/16 bits) + +[This field is used to indicate the destination NodeID for which the Priority Route is requested for.](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.145 .](04.04.03.15-get-priority-route-command.md#44315-get-priority-route-command) + +Table 4.145: Get Priority Route Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x92 | | | | | | | | +| 5/5..6 | NodeID | | | | | | | | +| 6/7 | Repeater 0 | | | | | | | | +| 7/8 | Repeater 1 | | | | | | | | +| 8/9 | Repeater 2 | | | | | | | | +| 9/10 | Repeater 3 | | | | | | | | +| 10/11 | Route Speed | | | | | | | | + +NodeID (8/16 bits) This field is used to indicate the destination NodeID for which the Priority Route corresponds to. + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) Repeater (4 bytes) + +[Refer to Repeater (4 bytes) .](../04.02-generic-command-elements.md#4212-repeater-4-bytes) + +Route Speed (8 bits) + +[Refer to Route Speed (8 bits) .](../04.02-generic-command-elements.md#4211-route-speed-8-bits) + +3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.16-lock-unlock-last-route-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.16-lock-unlock-last-route-command.md new file mode 100644 index 0000000..0a07e16 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.16-lock-unlock-last-route-command.md @@ -0,0 +1,41 @@ + +# 4.4.3.16 Lock Unlock Last Route Command + +This command is used to lock or unlock all last working route. The Lock Unlock Last Route Command Identifier is 0x90. + +Frame flow + +[The frame flow for this command is an Acknowledged frame .](../../03-interface-communication/03.03-command-frame-flows.md#332-acknowledged-frame) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.146 .](04.04.03.16-lock-unlock-last-route-command.md#44316-lock-unlock-last-route-command) + +Table 4.146: Lock Unlock Last Route Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x90 | | | | | | | | +| 5 | Lock mode | | | | | | | | + +Lock mode (8 bits) + +This command is used to indicate if the last working routes MUST be saved in the Z-Wave API module. This field value MUST be encoded as follows: + +• The value MUST be set to 0x01, if the last working routes MUST be saved in the Z-Wave API module. + +• The value MUST be set to 0x00, if the last working routes MUST NOT be saved in the Z-Wave API module. + +2. Response data frame (Z-Wave Module → host) + +None. + +3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.17-set-suc-nodeid-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.17-set-suc-nodeid-command.md new file mode 100644 index 0000000..a453f6e --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.17-set-suc-nodeid-command.md @@ -0,0 +1,103 @@ + +# 4.4.3.17 Set SUC NodeID Command + +This command is used to configure a static/bridge controller to be a SUC/SIS node or not. The Primary Controller should use this function to set a static/bridge controller to be the SUC/SIS node. The Set SUC NodeID Command Identifier is 0x54. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.147 .](04.04.03.17-set-suc-nodeid-command.md#44317-set-suc-nodeid-command) + +Table 4.147: Set SUC NodeID Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x54 | | | | | | | | +| 5/5..6 | NodeID | | | | | | | | +| 6/7 | SUC state | | | | | | | | +| 7/8 | Tx Option | | | | | | | | +| 8/9 | Capabilities | | | | | | | | +| 9/10 | Session identifier | | | | | | | | + +NodeID (8/16 bits) + +[This field is used to advertise the NodeID of the controller node that MUST take the SUC/SIS node.](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +SUC state (8 bits) + +This field is used to enable/disable the SUC/SIS functionalities. The field MUST be encoded as follow: + +• If the static/bridge controller are targeted to be a SUC/SIS node, the field value MUST be set to 0x01. + +• If the static/bridge controller should not be a SUC/SIS node, the field value MUST be set to 0x00. + +[Tx Options (8 bits)](../04.02-generic-command-elements.md#428-tx-options-8-bits) + +[Refer to Tx Options (8 bits) .](../04.02-generic-command-elements.md#428-tx-options-8-bits) + +Capabilities (8 bits) + +This field is used to advertise the SUC capabilities that can be enabled on the Z-Wave API module. This field [MUST be encoded according to Table 4.148 .](04.04.03.17-set-suc-nodeid-command.md#44317-set-suc-nodeid-command) Table 4.148: Set SUC NodeID Capabilities Value encoding + +| Value | Description | +| --- | --- | +| 0x00 | Reserved This reserved value MUST NOT be used. | +| 0x01 | ZW SUC FUNC NODEID SERVER _ _ _ _ This flag is used to enable the NodeID server functionality to become a SIS. | +| 0x02..0xFF | Reserved Reserved values MUST NOT be used. | + +[Session identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.149 .](04.04.03.17-set-suc-nodeid-command.md#44317-set-suc-nodeid-command) + +Table 4.149: Set SUC NodeID Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x54 | | | | | | | | +| 5 | Command Status | | | | | | | | + +Command Status (8 bits) + +[Refer to Command Status (8 bits) .](../04.02-generic-command-elements.md#426-command-status-8-bits) + +3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.150 .](04.04.03.17-set-suc-nodeid-command.md#44317-set-suc-nodeid-command) + +Table 4.150: Set SUC NodeID Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x54 | | | | | | | | +| 5 | Session identifier | | | | | | | | +| 6 | Set SUC Status | | | | | | | | + +[Session identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +Set SUC Status (8 bits) + +This field is used to indicate the statue regarding the configuration of a static/bridge controller to be [SUC/SIS node. This field MUST be encoded according to Table 4.151 .](04.04.03.17-set-suc-nodeid-command.md#44317-set-suc-nodeid-command) Table 4.151: Set SUC NodeID Status Value encoding + +| Value | Flag | Description | +| --- | --- | --- | +| 0x00..0x04 | Reserved | Reserved values MUST NOT be used. | +| 0x05 | ZW SUC SET SUCCEEDED _ _ _ | the process of configuring the static/bridge con- troller is ended successfully. | +| 0x06 | ZW SUC SET FAILED _ _ _ | the process of configuring the static/bridge con- troller is failed. | +| 0x07..0xFF | Reserved | Reserved values MUST NOT be used.. | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.18-delete-suc-return-route-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.18-delete-suc-return-route-command.md new file mode 100644 index 0000000..20ebf47 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.18-delete-suc-return-route-command.md @@ -0,0 +1,73 @@ + +# 4.4.3.18 Delete SUC Return Route Command + +This command is used to request the deletion of the SUC/SIS return routes. The Delete Return Route Command Command Identifier is 0x55. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.152 .](04.04.03.18-delete-suc-return-route-command.md#44318-delete-suc-return-route-command) + +Table 4.152: Delete SUC Return Route Command Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x55 | | | | | | | | +| 5/5..6 | NodeID | | | | | | | | +| 6/7 | Session identifier | | | | | | | | + +NodeID (8/16 bits) + +[This field is used to indicates the NodeID for which the SUC return routes is requested to be deleted.](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[Session identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.153 .](04.04.03.18-delete-suc-return-route-command.md#44318-delete-suc-return-route-command) + +Table 4.153: Delete SUC Return Route Command Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x55 | | | | | | | | +| 5 | Delete SUC Return Route Response | | | | | | | | + +Delete SUC Return Route Response (8 bits) + +This field is used to advertise the response of the Z-Wave module regarding the acceptance of the Delete SUC Return Route Command Initial data frame. This field MUST be encoded as follow: • If delete SUC return route operation is started, this field value MUST be set to 0x01. + +• If an “assign/delete return route” operation is already active, this field value MUST be set to 0x00. + +Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.154 .](04.04.03.18-delete-suc-return-route-command.md#44318-delete-suc-return-route-command) + +Table 4.154: Delete SUC Return Route Command Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x55 | | | | | | | | +| 5 | Session identifier | | | | | | | | +| 6 | Tx Status | | | | | | | | + +Session identifier (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +Tx Status (8 bits) + +[Refer to Tx Status (8 bits) .](../04.02-generic-command-elements.md#423-tx-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.19-send-suc-nodeid-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.19-send-suc-nodeid-command.md new file mode 100644 index 0000000..aa0be30 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.19-send-suc-nodeid-command.md @@ -0,0 +1,74 @@ + +# 4.4.3.19 Send SUC NodeID Command + +This command is used to trigger the transfer of SUC/SIS NodeID from Primary/Static controller to a given controller NodeID. The Send SUC NodeID Command Identifier is 0x57. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.155 .](04.04.03.19-send-suc-nodeid-command.md#44319-send-suc-nodeid-command) + +Table 4.155: Send SUC NodeID Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x57 | | | | | | | | +| 5/5..6 | NodeID | | | | | | | | +| 6/7 | Tx Options | | | | | | | | +| 7/8 | Session identifier | | | | | | | | + +NodeID (8/16 bits) + +[This field is used to advertise the NodeID of a controller that will receive the current SUC/SIS NodeID.](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[Tx Options (8 bits)](../04.02-generic-command-elements.md#428-tx-options-8-bits) + +[Refer to Tx Options (8 bits) .](../04.02-generic-command-elements.md#428-tx-options-8-bits) + +[Session identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.156](04.04.03.19-send-suc-nodeid-command.md#44319-send-suc-nodeid-command) + +Table 4.156: Send SUC NodeID Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x57 | | | | | | | | +| 5 | Command Status | | | | | | | | + +[Command Status (8 bits)](../04.02-generic-command-elements.md#426-command-status-8-bits) + +[Refer to Command Status (8 bits) .](../04.02-generic-command-elements.md#426-command-status-8-bits) 3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.157 .](04.04.03.19-send-suc-nodeid-command.md#44319-send-suc-nodeid-command) + +Table 4.157: Send SUC NodeID Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x57 | | | | | | | | +| 5 | Session identifier | | | | | | | | +| 6 | Tx Status | | | | | | | | + +Session identifier(8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Tx Status (8 bits)](../04.02-generic-command-elements.md#423-tx-status-8-bits) + +[Refer to Tx Status (8 bits) .](../04.02-generic-command-elements.md#423-tx-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.20-request-node-neighbor-discovery-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.20-request-node-neighbor-discovery-command.md new file mode 100644 index 0000000..321db0d --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.20-request-node-neighbor-discovery-command.md @@ -0,0 +1,73 @@ + +# 4.4.3.20 Request Node Neighbor Discovery Command + +This command is used to request a node to perform a new neighbor discovery and receive the updated list of neighbors. The Request Node Neighbor Discovery Command Identifier is 0x48. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with callback .](../../03-interface-communication/03.03-command-frame-flows.md#334-acknowledged-frame-with-callback) + +[This command may trigger several callback frames. Examples are given in Figure 4.16 and Figure 4.17](04.04.03.20-request-node-neighbor-discovery-command.md#44320-request-node-neighbor-discovery-command) + +![Figure 4.16: Request Node Neighbor Discovery Command Success Example](assets/img-1c1d0e8a10.png) + +![Figure 4.17: Request Node Neighbor Discovery Command Fail Example](assets/img-3662dedfb5.png) + +Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.158](04.04.03.20-request-node-neighbor-discovery-command.md#44320-request-node-neighbor-discovery-command) + +Table 4.158: Request Node Neighbor Discovery Command - Ini- tial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x48 | | | | | | | | +| 5/5..6 | NodeID | | | | | | | | +| 7/8 | Session Identifier | | | | | | | | + +NodeID (8/16 bits) + +This field indicates the NodeID that must perform a new discovery of its neighbors. + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[Session Identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +1. Response data frame (Z-Wave Module → host) + +None + +2. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.159](04.04.03.20-request-node-neighbor-discovery-command.md#44320-request-node-neighbor-discovery-command) Table 4.159: Request Node Neighbor Discovery Command - Call- back data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x48 | | | | | | | | +| 5 | Session Identifier | | | | | | | | +| 6 | Neighbor Discovery Status | | | | | | | | + +Session Identifier (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +Neighbor Discovery Status (8 bits) + +This field is used to indicate the current status of the Neighbor Discovery Process. Refer to [[ zwave_nwk_spec ] for details about the Neighbor Discovery Process.](../../05-references.md#5-references) + +[This field MUST be encoded as a bitmask and according to Table 4.160](04.04.03.20-request-node-neighbor-discovery-command.md#44320-request-node-neighbor-discovery-command) Table 4.160: Request Node Neighbor Discovery Command - Neighbor Discovery Status encoding + +| Value | Description | +| --- | --- | +| 0x21 | Neighbor Discovery Started This value is used to indicate that the Neighbor Discovery Process has started. | +| 0x22 | Neighbor Discovery Completed This value is used to indicate that the Neighbor Discovery Process has been completed successfully. | +| 0x23 | Neighbor Discovery Failed This value is used to indicate that the Neighbor Discovery Process failed. | +| 0xFF | Neighbor Discovery Not Supported This value is used to indicate that the functionality is not supported by one of the nodes. | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.21-request-network-update-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.21-request-network-update-command.md new file mode 100644 index 0000000..3768e20 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.21-request-network-update-command.md @@ -0,0 +1,81 @@ + +# 4.4.3.21 Request Network Update Command + +This command is used to instruct the Z-Wave API Module to request an Automatic Controller Update to the SUC. The Request Network Update Command Identifier is 0x53. + +A host application SHOULD use this command only if there is a SUC in the current network. + +A Z-Wave API Module receiving Node information updates during the Automatic Controller Update [process MUST issue unsolicited Application Update Command to the host application.](../04.07-unsolicited-z-wave-api-commands.md#473-application-update-command) + +Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) + +This command MAY trigger additional unsolicited frames from the Z-Wave API Module. An example [of the expected frame flow is shown in Figure 4.18](04.04.03.21-request-network-update-command.md#44321-request-network-update-command) + +![Figure 4.18: Request Network Update Command Example](assets/img-6bf1dd3f94.png) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.161 .](04.04.03.21-request-network-update-command.md#44321-request-network-update-command) + +Table 4.161: Request Network Update Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x53 | | | | | | | | +| 5 | Session identifier | | | | | | | | + +Session identifier (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.162 .](04.04.03.21-request-network-update-command.md#44321-request-network-update-command) + +Table 4.162: Request Network Update Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x53 | | | | | | | | +| 5 | Command Status | | | | | | | | + +[Command Status (8 bits)](../04.02-generic-command-elements.md#426-command-status-8-bits) + +[Refer to Command Status (8 bits) .](../04.02-generic-command-elements.md#426-command-status-8-bits) + +3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.163](04.04.03.21-request-network-update-command.md#44321-request-network-update-command) + +Table 4.163: Z-Wave API Setup Set NodeID Base Type Sub Com- mand - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x53 | | | | | | | | +| 5 | Session identifier | | | | | | | | +| 6 | Network Update Status | | | | | | | | + +[Session identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +Network Update Status (8 bits) + +This field is used to advertise the outcome of the network update request. This field MUST be encoded [according to Table 4.164 .](04.04.03.21-request-network-update-command.md#44321-request-network-update-command) Table 4.164: Network Update Status Value encoding + +| Value | Flag | Description | +| --- | --- | --- | +| 0x00 | ZW SUC UPDATE DONE _ _ _ | The network update process succeeded. | +| 0x01 | ZW SUC UPDATE ABORT _ _ _ | The network update process aborted be- cause of an error. | +| 0x02 | ZW SUC UPDATE WAIT _ _ _ | The SUC node is busy. | +| 0x03 | ZW SUC UPDATE DISABLED _ _ _ | The SUC functionality is disabled. | +| 0x04 | ZW SUC UPDATE OVERFLOW _ _ _ | The controller requested an update after more than 64 changes have occurred in the network. The update information is then out of date in respect to that con- troller. In this situation the controller have to make a replication (copy) before trying to request any new network up- dates. | +| 0x05..0xFF | Reserved | These options are reserved, and the re- served values MUST NOT be used. | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.22-set-virtual-node-to-learn-mode-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.22-set-virtual-node-to-learn-mode-command.md new file mode 100644 index 0000000..6f0c89e --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.22-set-virtual-node-to-learn-mode-command.md @@ -0,0 +1,111 @@ + +# 4.4.3.22 Set Virtual Node To Learn Mode Command + +This command is used to enable or disable a virtual end node to Learn Mode operation that facilitates the node to be included or removed to/from a Z-Wave Network. The Set Virtual Node Learn Mode Command Identifier is 0xA4. + +This command MUST only be supported by nodes implementing a Bridge Controller library type (refer [to Table 4.36 ).](../04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) + +NOTE: A Learn Mode should only be enabled on a virtual end node when necessary, and it should always be disabled again as quickly as possible. It is recommended that the Learn Mode should not enabled for more than 1 second on a virtual end node. + +Frame flow + +[The frame flow for this command is an Acknowledged frame with callback .](../../03-interface-communication/03.03-command-frame-flows.md#334-acknowledged-frame-with-callback) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.165 .](04.04.03.22-set-virtual-node-to-learn-mode-command.md#44322-set-virtual-node-to-learn-mode-command) + +Table 4.165: Set Virtual Node To Learn Mode Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xA4 | | | | | | | | +| 5 | NodeID | | | | | | | | +| 6 | Mode | | | | | | | | +| 7 | Session identifier | | | | | | | | + +NodeID (8 bits) + +This field is used to advertise the virtual NodeID that is set to Learn Mode. + +[This field MUST be encoded using 8 bits regardless of the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Mode (8 bits) + +This field is used to indicate the Learn Mode [intent. This field MUST be encoded according to Table 4.166 .](04.04.03.22-set-virtual-node-to-learn-mode-command.md#44322-set-virtual-node-to-learn-mode-command) Table 4.166: Virtual End Node Learn Mode Encoding + +| Value | Flag and description | +| --- | --- | +| 0x00 | VIRTUAL END NODE LEARN MODE DISABLE. _ _ _ _ _ This option is used to disable the Learn Mode operation on virtual end node. | +| 0x01 | VIRTUAL END NODE LEARN MODE ENABLE. _ _ _ _ _ This option is used to enable the Learn Mode operation on virtual end node. | + +| | 0x02 | VIRTUAL END NODE LEARN MODE ADD. _ _ _ _ _ This option is used to create locally a virtual end node and add it to the Z-Wave network (this will only be possible bridge controller node is a Primary/Inclusion Con- troller). | | +| --- | --- | --- | --- | +| | 0x03 | VIRTUAL END NODE LEARN MODE REMOVE. _ _ _ _ _ This option is used to remove locally present virtual end node from the Z-Wave net- work (this will only be possible bridge node controller is a Primary/Inclusion Con- troller). | | +| | 0x04..0xFF | Reserved These options are reserved, and reserved values MUST not be used. | | + +Session identifier (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.167 .](04.04.03.22-set-virtual-node-to-learn-mode-command.md#44322-set-virtual-node-to-learn-mode-command) + +Table 4.167: Set Virtual Node To Learn Mode Command - Re- sponse data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xA4 | | | | | | | | +| 5 | Response status | | | | | | | | + +[Response status (8 bits)](../04.02-generic-command-elements.md#425-response-status-8-bits) + +[Refer to Response status (8 bits) .](../04.02-generic-command-elements.md#425-response-status-8-bits) + +3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.168 to notify the status](04.04.03.22-set-virtual-node-to-learn-mode-command.md#44322-set-virtual-node-to-learn-mode-command) of the Learn Mode operation. + +Table 4.168: Set Virtual Node To Learn Mode Command - Call- back data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xA4 | | | | | | | | +| 5 | Session identifier | | | | | | | | +| 6 | Status | | | | | | | | +| 7 | Original NodeID | | | | | | | | +| 8 | New NodeID | | | | | | | | + +[Session identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) Status (8 bits) + +This field is used to indicate the status of the Learn Mode process. This field MUST be encoded accord- [ing to Table 4.169 .](04.04.03.22-set-virtual-node-to-learn-mode-command.md#44322-set-virtual-node-to-learn-mode-command) + +Table 4.169: Virtual End Node Learn Mode Status Encoding + +| Value | Flag and description | +| --- | --- | +| 0x00 | ASSIGN COMPLETE _ This option is used to indicate the Learn Mode is enabled and assignment process is done. | +| 0x01 | ASSIGN NODEID DONE _ _ This option is used to indicate the NodeID has been assigned. | +| 0x02 | ASSIGN RANGE INFO UPDATE _ _ _ This option is used to indicate the node is doing neighbour discovery. The application should not attempt to send any frames during this time. | +| 0x03..0xFF | Reserved These options are reserved, and reserved values MUST not be used. | + +Original NodeID (8 bits) + +This field is used to advertise the original NodeID of the virtual end node when it was set to Learn Mode operation. + +[This field MUST be encoded using 8 bits regardless of the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +New NodeID (8 bits) + +This field is used to advertise the new assigned NodeID. If the virtual end node is deleted, this field MUST be set to 0x00. + +[This field MUST be encoded using 8 bits regardless of the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.23-virtual-node-send-node-information-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.23-virtual-node-send-node-information-command.md new file mode 100644 index 0000000..22485eb --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.23-virtual-node-send-node-information-command.md @@ -0,0 +1,79 @@ + +# 4.4.3.23 Virtual Node Send Node Information Command + +This command is used to create and transmit a virtual end node Node Information Frame. The Virtual Node Send Node Information Command Identifier is 0xA2. + +This command MUST only be supported by nodes implementing a Bridge Controller library type (refer [to Table 4.36 ).](../04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) + +Frame flow + +[The frame flow for this command is an Acknowledged frame with callback .](../../03-interface-communication/03.03-command-frame-flows.md#334-acknowledged-frame-with-callback) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.170 .](04.04.03.23-virtual-node-send-node-information-command.md#44323-virtual-node-send-node-information-command) + +Table 4.170: Virtual Node Send Node Information Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xA2 | | | | | | | | +| 5/6 | Source NodeID | | | | | | | | +| 6/7 | Destination NodeID | | | | | | | | +| 7/8 | Tx Options | | | | | | | | +| 8/9 | Session identifier | | | | | | | | + +Source NodeID (8/16 bits) + +This field is used to indicate the virtual NodeID where the Node Information Frame is sent from. The field size could be 8 bits or 16 bits depends on employed physical layer module such as Z-Wave or Z- Wave Long Range, respectively. + +Destination NodeID (8/16 bits) + +This field is used to indicate the destination NodeID where the Node Information Frame will be sent to. The field size could be 8 bits or 16 bits depends on employed physical layer module such as Z-Wave or Z-Wave Long Range, respectively. + +[Tx Options (8 bits)](../04.02-generic-command-elements.md#428-tx-options-8-bits) + +[Refer to Tx Options (8 bits) .](../04.02-generic-command-elements.md#428-tx-options-8-bits) + +[Session identifier(8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.171 .](04.04.03.23-virtual-node-send-node-information-command.md#44323-virtual-node-send-node-information-command) Table 4.171: Virtual Node Send Node Information Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xA2 | | | | | | | | +| 5 | Response status | | | | | | | | + +Response status (8 bits) + +[Refer to Response status (8 bits) .](../04.02-generic-command-elements.md#425-response-status-8-bits) + +3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.172 after the](04.04.03.23-virtual-node-send-node-information-command.md#44323-virtual-node-send-node-information-command) Node Information Frame transmission is performed. + +Table 4.172: Virtual Node Send Node Information Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xA2 | | | | | | | | +| 5 | Session identifier | | | | | | | | +| 6 | Tx Status | | | | | | | | + +[Session identifier(8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Tx Status (8 bits)](../04.02-generic-command-elements.md#423-tx-status-8-bits) + +[Refer to Tx Status (8 bits) .](../04.02-generic-command-elements.md#423-tx-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.24-set-virtual-nodes-application-node-information-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.24-set-virtual-nodes-application-node-information-command.md new file mode 100644 index 0000000..76fd3ee --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.24-set-virtual-nodes-application-node-information-command.md @@ -0,0 +1,69 @@ + +# 4.4.3.24 Set Virtual Nodes Application Node Information Command + +This command is used to configure the Node Information Data for the Virtual nodes own by the Z-Wave API Module. The Set Virtual Node Application Node Information Command Identifier is 0xA0. + +This command MUST only be supported by nodes implementing a Bridge Controller library type (refer [to Table 4.36 ). The frame flow for this command is an](../04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) [Acknowledged frame .](../../03-interface-communication/03.03-command-frame-flows.md#332-acknowledged-frame) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.173](04.04.03.24-set-virtual-nodes-application-node-information-command.md#44324-set-virtual-nodes-application-node-information-command) + +Table 4.173: Set Virtual Nodes Application Node Information Command + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xA0 | | | | | | | | +| 5 | Virtual NodeID | | | | | | | | +| 6 | Device Option Mask | | | | | | | | +| 7 | Generic Device Type | | | | | | | | +| 8 | Specific Device Type | | | | | | | | +| 9 | Node Parameter Length | | | | | | | | +| 9+1 | Node Parameter 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 9+N | Node Parameter N | | | | | | | | + +Virtual NodeID (8 bits) + +This field is used to indicate the virtual NodeID for which the Node information frame data must be configured. + +[This field MUST be encoded using 8 bits regardless of the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Device Option Mask (8 bits) + +The device option mask is a bitmask where Listening and Optional functionality flags MUST be set [accordingly to the nodes capabilities. This field MUST comply with the format indicated in Table 4.174 .](04.04.03.24-set-virtual-nodes-application-node-information-command.md#44324-set-virtual-nodes-application-node-information-command) + +Table 4.174: Set Application Node Information Command - De- vice Option Mask encoding + +| Bit | Flags | Description | +| --- | --- | --- | +| 0..6 | Reserved | Reserved | +| 7 | Listening flag | This bit indicates if the node should be an Always Listening Node. (AL Node) The value 0 MUST indicate that the node MUST NOT be AL (either NL or FL) The value 1 MUST indicate that the node MUST be an AL node. | + +Generic Device Type (8 bits) The Generic Device Class field contains an identifier that identifies what Generic Device Class the Z- Wave node MUST advertise and MUST be set by the application. For a detailed description of all [available Generic Device Classes, refer to [ device_class_spec ] for Z-Wave devices, [ device_type_spec ] for Z-Wave Plus devices, and [ device_type_spec_v2 ] for Z-Wave Plus v2 devices.](../../05-references.md#5-references) + +Specific Device Type (8 bits) + +The Specific Device Class field contains an identifier that identifies what Specific Device Class the Z- Wave node MUST advertise and MUST be set by the application. For a detailed description of all [available Generic Device Classes, refer to [ device_class_spec ] for Z-Wave devices, [ device_type_spec ] for Z-Wave Plus devices, and [ device_type_spec_v2 ] for Z-Wave Plus v2 devices.](../../05-references.md#5-references) + +Node Parameter length (8 bits) + +This field MUST specify the length of the Node Parameter field in bytes. + +Node Parameter (N bytes) + +This field is used to advertise the list of supported Command Classes by the node. + +2. Response data frame (Z-Wave Module → host) + +None + +3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.25-set-z-wave-long-range-shadow-nodeids-commmand.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.25-set-z-wave-long-range-shadow-nodeids-commmand.md new file mode 100644 index 0000000..bcf023a --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/04.04.03.25-set-z-wave-long-range-shadow-nodeids-commmand.md @@ -0,0 +1,51 @@ + +# 4.4.3.25 Set Z-Wave Long Range Shadow NodeIDs Commmand + +This command is used to enable the use of Shadow NodeIDs in the Long Range capable controller. The command will enable the controller to use more NodeIDs than its native NodeID to transmit and receive frames. The shadow NodeID is assigned outside of the normal NodeID range for Z-Wave Long Range nodes. + +The Set Z-Wave Long Range Shadow NodeIDs Commmand Identifier is 0xDD. + +This command MUST only be supported by Z-Wave API Module using the Controller Bridge library [types (refer to Table 4.36 ).](../04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) + +Frame flow + +[The frame flow for this command is an Acknowledged frame .](../../03-interface-communication/03.03-command-frame-flows.md#332-acknowledged-frame) + +1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.175](04.04.03.25-set-z-wave-long-range-shadow-nodeids-commmand.md#44325-set-z-wave-long-range-shadow-nodeids-commmand) + +Table 4.175: Set Z-Wave Long Range Shadow NodeIDs Com- mand - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xDD | | | | | | | | +| 5 | Z-Wave Long Range Shadow NodeIDs bitmask | | | | | | | | + +Z-Wave Long Range Shadow NodeIDs bitmask (8 bits) + +This field is used to indicate which shadow NodeIDs must be enabled by the Z-Wave API Module. + +This field MUST encoded as a bitmask and interpreted as follow: + +• bit 0 MUST represent NodeID 2002. + +• bit 1 MUST represent NodeID 2003. + +• bit 2 MUST represent NodeID 2004. + +• bit 3 MUST represent NodeID 2005. + +• bit 4..7 are reserved. + +2. Response data frame (Z-Wave Module → host) + +None + +3. Callback data frame (Z-Wave Module → host) None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/index.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/index.md new file mode 100644 index 0000000..9f6ee4c --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.04-z-wave-api-network-management-commands/index.md @@ -0,0 +1,54 @@ + +# 4.4 Z-Wave API Network Management Commands + +[This section describes Z-Wave API Commands that are used to perform Z-Wave Network Management.](../index.md#4-z-wave-api-commands) + +## Contents + +- [4.4.1 Common Network Management Commands](04.04.01-common-network-management-commands.md) +- [4.4.1.1 Send NOP Command](04.04.01.01-send-nop-command.md) +- [4.4.1.2 Get Node Information Protocol Data Command](04.04.01.02-get-node-information-protocol-data-command.md) +- [4.4.1.3 Send Node Information Command](04.04.01.03-send-node-information-command.md) +- [4.4.1.4 Request Node Information Command](04.04.01.04-request-node-information-command.md) +- [4.4.1.5 Set Learn Mode Command](04.04.01.05-set-learn-mode-command.md) +- [4.4.1.6 Get SUC NodeID Command](04.04.01.06-get-suc-nodeid-command.md) +- [4.4.1.7 Set SmartStart Inclusion Request Maximum Interval Command](04.04.01.07-set-smartstart-inclusion-request-maximum-interval-command.md) +- [4.4.1.8 Explore Request Inclusion Command](04.04.01.08-explore-request-inclusion-command.md) +- [4.4.1.9 Explore Request Exclusion Command](04.04.01.09-explore-request-exclusion-command.md) +- [4.4.2 End Nodes Network Management](04.04.02-end-nodes-network-management.md) +- [4.4.2.1 Request New Route Destinations Command](04.04.02.01-request-new-route-destinations-command.md) +- [4.4.2.2 Is Node Within Direct Range Command](04.04.02.02-is-node-within-direct-range-command.md) +- [4.4.2.3 Get Network Statistics Command](04.04.02.03-get-network-statistics-command.md) +- [4.4.2.4 Clear Network Statistics Command](04.04.02.04-clear-network-statistics-command.md) +- [4.4.3 Controller Nodes Network Management](04.04.03-controller-nodes-network-management.md) +- [4.4.3.1 Add Node To Network Command](04.04.03.01-add-node-to-network-command.md) +- [4.4.3.2 Add Controller And Assign Primary Controller Role Command](04.04.03.02-add-controller-and-assign-primary-controller-role-command.md) +- [4.4.3.3 Add Primary Controller Command](04.04.03.03-add-primary-controller-command.md) +- [4.4.3.4 Remove Node From Network Command](04.04.03.04-remove-node-from-network-command.md) +- [4.4.3.5 Remove Specific Node From Network Command](04.04.03.05-remove-specific-node-from-network-command.md) +- [4.4.3.6 Is Node Failed Command](04.04.03.06-is-node-failed-command.md) +- [4.4.3.7 Remove Failed Node Command](04.04.03.07-remove-failed-node-command.md) +- [4.4.3.8 Replace Failed Node Command](04.04.03.08-replace-failed-node-command.md) +- [4.4.3.9 Delete Return Route Command](04.04.03.09-delete-return-route-command.md) +- [4.4.3.10 Assign Return Route Command](04.04.03.10-assign-return-route-command.md) +- [4.4.3.11 Assign SUC Return Route Command](04.04.03.11-assign-suc-return-route-command.md) +- [4.4.3.12 Assign Priority Return Route Command](04.04.03.12-assign-priority-return-route-command.md) +- [4.4.3.13 Assign Priority SUC Return Route Command](04.04.03.13-assign-priority-suc-return-route-command.md) +- [4.4.3.14 Set Priority Route Command](04.04.03.14-set-priority-route-command.md) +- [4.4.3.15 Get Priority Route Command](04.04.03.15-get-priority-route-command.md) +- [4.4.3.16 Lock Unlock Last Route Command](04.04.03.16-lock-unlock-last-route-command.md) +- [4.4.3.17 Set SUC NodeID Command](04.04.03.17-set-suc-nodeid-command.md) +- [4.4.3.18 Delete SUC Return Route Command](04.04.03.18-delete-suc-return-route-command.md) +- [4.4.3.19 Send SUC NodeID Command](04.04.03.19-send-suc-nodeid-command.md) +- [4.4.3.20 Request Node Neighbor Discovery Command](04.04.03.20-request-node-neighbor-discovery-command.md) +- [4.4.3.21 Request Network Update Command](04.04.03.21-request-network-update-command.md) +- [4.4.3.22 Set Virtual Node To Learn Mode Command](04.04.03.22-set-virtual-node-to-learn-mode-command.md) +- [4.4.3.23 Virtual Node Send Node Information Command](04.04.03.23-virtual-node-send-node-information-command.md) +- [4.4.3.24 Set Virtual Nodes Application Node Information Command](04.04.03.24-set-virtual-nodes-application-node-information-command.md) +- [4.4.3.25 Set Z-Wave Long Range Shadow NodeIDs Commmand](04.04.03.25-set-z-wave-long-range-shadow-nodeids-commmand.md) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.05-z-wave-api-memory-commands.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.05-z-wave-api-memory-commands.md new file mode 100644 index 0000000..716df66 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.05-z-wave-api-memory-commands.md @@ -0,0 +1,55 @@ + +# 4.5 Z-Wave API Memory Commands + +[This section describes Z-Wave API Commands that are used to interact with the Z-Wave Module memory](index.md#4-z-wave-api-commands) or storage. + +## 4.5.1 Get Network IDs from Memory Command + +This command is used to get the HomeID and NodeID from the Z-Wave Module. The Get Network IDs from Memory Command Identifier is 0x20. + +## 4.5.1.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +## 4.5.1.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.176](04.05-z-wave-api-memory-commands.md#4512-1-initial-data-frame-host-z-wave-module) + +Table 4.176: Get Network IDs from Memory Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x20 | | | | | | | | + +## 4.5.1.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.177](04.05-z-wave-api-memory-commands.md#4513-2-response-data-frame-z-wave-module-host) + +Table 4.177: Get Network IDs from Memory Command - Re- sponse data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x20 | | | | | | | | +| 5 | HomeID 1 | | | | | | | | +| 6 | HomeID 2 | | | | | | | | +| 7 | HomeID 3 | | | | | | | | +| 8 | HomeID 4 | | | | | | | | +| 9/9..10 | NodeID | | | | | | | | + +HomeID (4 bytes) + +This field is used to advertise the current HomeID of the Z-Wave API Module. + +NodeID (8 bits/16 bits) + +This field is used to indicate the NodeID currently assigned to the Z-Wave API Module. [This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +## 4.5.1.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.06-z-wave-api-firmware-update-commands.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.06-z-wave-api-firmware-update-commands.md new file mode 100644 index 0000000..fce7684 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.06-z-wave-api-firmware-update-commands.md @@ -0,0 +1,135 @@ + +# 4.6 Z-Wave API Firmware Update Commands + +[This section describes Z-Wave API Commands that are used to perform firmware update operations.](index.md#4-z-wave-api-commands) + +## 4.6.1 NVM Operations Command + +This command is used to read and write the firmware data of the Z-Wave API Module. The NVM Operations Command Identifier is 0x2E. + +## 4.6.1.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +This command has sub-commands that allow either read or write operations. + +[The recommended frame flow for reading the firmware data of a Z-Wave API module is shown in Figure 4.19](04.06-z-wave-api-firmware-update-commands.md#4611-frame-flow) + +![Figure 4.19: NVM Read Operation](assets/img-c778299cc1.png) + +[The recommended frame flow for writing firmware data to a Z-Wave API module is shown in Figure 4.20 . The host application MUST send a](04.06-z-wave-api-firmware-update-commands.md#4611-frame-flow) [Soft Reset Command in order to activate the new firmware.](04.03-z-wave-capability-api-commands/04.03.12-soft-reset-command.md#4312-soft-reset-command) + +![Figure 4.20: NVM Write Operation](assets/img-556a6b8e9e.png) + +## 4.6.1.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.178](04.06-z-wave-api-firmware-update-commands.md#4612-1-initial-data-frame-host-z-wave-module) + +Table 4.178: NVM Operations Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x2E | | | | | | | | +| 5 | NVM Operation sub-command | | | | | | | | +| 6 | Firmware Data Length | | | | | | | | + +| | 7 | Address Offset (MSB) | | +| --- | --- | --- | --- | +| | 8 | Address Offset (LSB) | | +| | 8+1 | Firmware Data 1 | | +| | . . . | . . . | | +| | 8+N | Firmware Data N | | + +NVM Operation sub-command (8 bits) + +This field is used to indicate which operation to perform. This field MUST be encoded according to [Table 4.179](04.06-z-wave-api-firmware-update-commands.md#4612-1-initial-data-frame-host-z-wave-module) + +Table 4.179: NVM Operations Command - NVM Operation sub- command encoding + +| Value | Description | +| --- | --- | +| 0x00 | Open This value is used to open the NVM for a subsequent read or write operation. | +| 0x01 | Read This value is used to read the NVM contents. | +| 0x02 | Write This value is used to write data to the NVM contents. | +| 0x03 | Close This value is used to close the NVM when the read/write operation is completed. | + +Firmware Data Length (8 bits) + +This field is used to specify the length of the data that should be read/written from/to the Z-Wave API firmware data. + +This field SHOULD be omitted for if the NVM Operation sub-command is set to Open (0x00) or Close (0x03). + +If the NVM Operation sub-command is set to Write (0x02), this field MUST indicate the length of the Firmware Data field, in bytes. + +Address Offset (16 bits) + +This field is used to specify a memory address offset for read/write operations. + +This field SHOULD be omitted for if the NVM Operation sub-command is set to Open (0x00) or Close (0x03). + +If the NVM Operation sub-command is set to Read (0x01) or Write (0x02), this field MUST indicate the address offset for which the data must be read/written. + +Firmware Data (N bytes) + +This field is used to specify data to write to the Z-Wave API Module firmware memory. + +This field SHOULD be omitted for if the NVM Operation sub-command is set to a different value than Write (0x02). The Z-Wave API Module MUST write the data indicated in this field starting at the address offset indicated by the Address Offset field. + +## 4.6.1.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.180](04.06-z-wave-api-firmware-update-commands.md#4613-2-response-data-frame-z-wave-module-host) + +Table 4.180: NVM Operations Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x2E | | | | | | | | +| 5 | NVM Operation sub-command status | | | | | | | | +| 6 | Firmware Data Length | | | | | | | | +| 7 | Address Offset / NVM Size (MSB) | | | | | | | | +| 8 | Address Offset / NVM Size (LSB) | | | | | | | | +| 8+1 | Firmware Data 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 8+N | Firmware Data N | | | | | | | | + +NVM Operation sub-command status (8 bits) + +This field is used to indicate the status of the requested operation in the initial data frame. This field [MUST be encoded according to Table 4.181](04.06-z-wave-api-firmware-update-commands.md#4613-2-response-data-frame-z-wave-module-host) + +Table 4.181: NVM Operations Command - NVM Operation sub- command status encoding + +| Value | Description | +| --- | --- | +| 0x00 | OK This value is used to indicate that the requested operation was successful. | +| 0x01 | Error This value is used to indicate that an error occurred. | +| 0x02 | Error: Operation Mismatch This value is used to indicate that the wrong operation was requested (e.g. write in the middle of a read operation or vice-versa) | +| 0x03 | Error: Operation interference This value is used to indicate that the read operation cannot be performed or trusted due to another process writing in the Firmware Data. | +| 0xFF | End Of File This value is used to indicate that the read/write operation has reached the end of the file/memory area. The host application SHOULD issue a Close sub- command when receiving this value. | + +Firmware Data Length (8 bits) + +This field is used to specify the length of the data that is present in the Firmware Data field. + +This field will be different than 0 only for Read (0x01) operation responses. Address Offset / NVM Size (16 bits) + +This field is used to specify a memory address offset for read/write operations. This field SHOULD be ignored for if the NVM Operation sub-command is set to Write (0x02) or Close (0x03). + +If the NVM Operation sub-command was set to Read (0x01) in the 1. Initial Data Frame, this field MUST indicate the address offset for which the data is being read. + +If the NVM Operation sub-command was set to Open (0x00) in the 1. Initial Data Frame, this field MUST indicate the total size of the Firmware Memory, in bytes. + +Firmware Data (N bytes) + +This field is used to adverties the read data from the Z-Wave API Module firmware memory. + +This field SHOULD be ignored for if the NVM Operation sub-command was set not to Read (0x01) in the 1. Initial Data Frame. + +## 4.6.1.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.07-unsolicited-z-wave-api-commands.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.07-unsolicited-z-wave-api-commands.md new file mode 100644 index 0000000..cdeaff7 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.07-unsolicited-z-wave-api-commands.md @@ -0,0 +1,455 @@ + +# 4.7 Unsolicited Z-Wave API commands + +[This section describes Z-Wave API Commands that are used to intialize and configure the Z-Wave mod-](index.md#4-z-wave-api-commands) ule. It also comprises commands that are used to read the supported functionality of the Z-Wave API module. + +## 4.7.1 Application Command Handler Command + +This command is used by a Z-Wave module to notify a host application that a Z-Wave frame has been received. The Application Command Handler Command Identifier is 0x04 + +## 4.7.1.1 Frame flow + +[The frame flow for this command is an Unsolicited frame .](../03-interface-communication/03.03-command-frame-flows.md#336-unsolicited-frame) + +## 4.7.1.2 1. Initial data frame (host → Z-Wave Module) + +None + +## 4.7.1.3 2. Response data frame (Z-Wave Module → host) + +None + +## 4.7.1.4 3. Callback data frame (Z-Wave Module → host) + +None + +## 4.7.1.5 4. Unsolicited frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue an unsolicited frame formatted according to Table 4.182](04.07-unsolicited-z-wave-api-commands.md#4715-4-unsolicited-frame-z-wave-module-host) + +Table 4.182: Application Command Handler Command - Unso- licited data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x04 | | | | | | | | +| 5 | Rx Status | | | | | | | | +| 6/6..7 | Source NodeID (8/16 bits) | | | | | | | | +| 7/8 | Payload Length | | | | | | | | +| 8/9 | Payload 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 8/9+N | Payload N | | | | | | | | +| 9/10+N | Rx RSSI Value | | | | | | | | + +Rx Status (8 bits) + +This field is used to advertise additional information about how the Z-Wave frame was received. + +[This field MUST be treated as a bitmask and encoded according to Table 4.1 .](../01-introduction/01.04-terminology-and-abbreviations.md#14-terminology-and-abbreviations) + +Source NodeID (8/16 bits) + +This field is used to advertise the NodeID from which the Z-Wave Command was received. [This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Payload Length (8 bits) + +This field is used to advertise the length in bytes of the Payload field. + +Payload (N bytes) + +This field is used to report the payload that was received from the Source NodeID. + +Rx RSSI Value (8 bits) + +This field is used to report the measured RSSI value for the received Z-Wave frame. This field MUST [be encoded according to Table 4.3 .](../03-interface-communication/03.02-frame-types.md#321-data-frame) + +## 4.7.2 Z-Wave API Started Command + +This command is used by the Z-Wave Module to indicate that it is ready to be operated after a reboot or reset operation. + +The Z-Wave API Started Command Command Identifier is 0x0A + +## 4.7.2.1 Frame flow + +[The frame flow for this command is an Unsolicited frame .](../03-interface-communication/03.03-command-frame-flows.md#336-unsolicited-frame) + +## 4.7.2.2 1. Initial data frame (host → Z-Wave Module) + +None + +## 4.7.2.3 2. Response data frame (Z-Wave Module → host) + +None + +## 4.7.2.4 3. Callback data frame (Z-Wave Module → host) + +None + +## 4.7.2.5 4. Unsolicited frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue an unsolicited frame formatted according to Table 4.183](04.07-unsolicited-z-wave-api-commands.md#4725-4-unsolicited-frame-z-wave-module-host) + +Table 4.183: Z-Wave API Started Command - Unsolicited data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0A | | | | | | | | +| 5 | Wake Up Reason | | | | | | | | +| 6 | Watchdog Started | | | | | | | | +| 7 | Device Option Mask | | | | | | | | +| 8 | Generic Device Type | | | | | | | | +| 9 | Specific Device Type | | | | | | | | +| 10 | Command Class List Length | | | | | | | | +| 11 | Command Class List 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 11+N | Command Class List N | | | | | | | | +| 11+N+1 | Supported Protocols | | | | | | | | + +Wake Up Reason (8 bits) + +This field is used to advertise the event that caused the Z-Wave API module to start. It MUST be encoded [according to Table 4.184 .](04.07-unsolicited-z-wave-api-commands.md#4725-4-unsolicited-frame-z-wave-module-host) Table 4.184: Z-Wave API Started - Wake Up Reason encoding + +| Value | Description | +| --- | --- | +| 0x00 | Reset The Z-Wave API Module has been woken up by reset or external interrupt. | +| 0x01 | Wake Up Timer The Z-Wave API Module has been woken up by a timer. | +| 0x02 | Wake Up Beam The Z-Wave API Module has been woken up by a Wake Up Beam. | +| 0x03 | Watchdog reset The Z-Wave API Module has been woken up by a reset triggered by the watch- dog. | +| 0x04 | External interrupt The Z-Wave API Module has been woken up by an external interrupt. | +| 0x05 | Power Up The Z-Wave API Module has been woken up by a powering up. | +| 0x06 | USB Suspend The Z-Wave API Module has been woken up by USB Suspend. | +| 0x07 | Software reset The Z-Wave API Module has been woken up by a reset triggered by software. | +| 0x08 | Emergency Watchdog Reset The Z-Wave API Module has been woken up by an emergency watchdog reset. | +| 0x09 | Brownout circuit The Z-Wave API Module has been woken up by a reset triggered by brownout circuit. | +| 0x0A..0xFE | Reserved values MUST NOT be used and MUST be ignored by a receiving inter- face | +| 0xFF | Unknown The Z-Wave API Module has been woken up by an unknown reason. | + +Watchdog Started (8 bits) + +This field is used to advertise if the Watchdog is enabled. + +The value 0x00 MUST indicate that thw watchdog is disabled. The value 0x01 MUST indicate that thw watchdog is enabled. + +Device Option Mask (8 bits) + +This field is used to advertise the currently configured listening capabilities configured for the Z-Wave API Module. + +[The host application MAY change this using the Set Application Node Information Command .](04.03-z-wave-capability-api-commands/04.03.02-set-application-node-information-command.md#432-set-application-node-information-command) + +Generic Device Type (8 bits) + +This field is used to advertise the currently configured Generic Device Type. [The host application MAY change this using the Set Application Node Information Command .](04.03-z-wave-capability-api-commands/04.03.02-set-application-node-information-command.md#432-set-application-node-information-command) + +Specific Device Type (8 bits) + +[This field is used to advertise the currently configured Specific Device Type.](04.03-z-wave-capability-api-commands/04.03.02-set-application-node-information-command.md#432-set-application-node-information-command) + +[The host application MAY change this using the Set Application Node Information Command .](04.03-z-wave-capability-api-commands/04.03.02-set-application-node-information-command.md#432-set-application-node-information-command) + +Command Class List Length (8 bits) This field is used to advertise the length of the Command Class List in bytes. + +Command Class List (N bytes) + +This field is used to advertise the list of supported Command Classes advertised by the Z-Wave API Module upon request. + +[The host application MAY change this using the Set Application Node Information Command .](04.03-z-wave-capability-api-commands/04.03.02-set-application-node-information-command.md#432-set-application-node-information-command) + +Supported Protocols (8 bits) + +This field is used to advertise additional supported protocols by the Z-Wave API module. This field [MUST be encoded as a bitmask and MUST be encoded according to Table 4.185 .](04.07-unsolicited-z-wave-api-commands.md#4725-4-unsolicited-frame-z-wave-module-host) + +Table 4.185: Z-Wave API Started Command - Supported Protocols encoding + +| Bit | Flag | Description | +| --- | --- | --- | +| 0 | Z-Wave Long Range | This bit indicates if the Z-Wave API module supports Z-Wave Long range. • The value 0 MUST indicate that the Z-Wave API module does not support Z-Wave Long Range • The value 1 MUST indicate that the Z-Wave API module does supports Z-Wave Long Range | +| 1..7 | Reserved | These bits are reserved. Reserved bits MUST NOT be used and MUST be ignored by a receiving interface. | + +## 4.7.3 Application Update Command + +This command is used to update node information data structures and to control SmartStart inclusion. The Application Update Command Identifier is 0x49. + +This command is used by during the following conditions: + +[If the Z-Wave API Module runs an End Node library type (refer to Table 4.36 ), it MUST send this](04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) command to the host application when: + +• It received a Node Information Frame Command. + +[If the Z-Wave API Module runs an Controller node library type (refer to Table 4.36 ), it MUST send this](04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) command to the host application when: + +• It received a Node Information Frame Command. + +• It received a SmartStart Prime Command and it is in SmartStart Add Mode. + +• It received an Included Node Info Frame Command and it is in SmartStart Add Mode. + +• It has the SIS Role and a node is added or excluded from the network by a controller (Primary or Inclusion controller). + +• It has received a change in the Node Information Frame data for a node during network topology update process (either Automatic Controller Update or Controller Replication). + +[Refer to [ zwave_nwk_spec ] for details.](../05-references.md#5-references) + +## 4.7.3.1 Frame flow + +[The frame flow for this command is an Unsolicited frame .](../03-interface-communication/03.03-command-frame-flows.md#336-unsolicited-frame) + +## 4.7.3.2 1. Initial data frame (host → Z-Wave Module) + +None. + +## 4.7.3.3 2. Response data frame (Z-Wave Module → host) + +None. + +## 4.7.3.4 3. Callback data frame (Z-Wave Module → host) + +None. + +## 4.7.3.5 4. Unsolicited frame (Z-Wave Module → host) + +The Z-Wave module issues several unsolicited Application Update request frames corresponding to the information it receives over the Z-Wave media. 4.a. Unsolicited Application Update Command generic format + +A Z-Wave API module MUST issue this unsolicited frame to the host application when one of the events described in the event field happened. + +A Z-Wave API module implementing a Controller Node [library type (refer to Table 4.36 ) MUST also](04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) issue this unsolicited frame when it receives a Node Information Frame as part of a network inclusion or when a node has been excluded from the network. + +[A Z-Wave module MUST issue this unsolicited frame formatted according to Table 4.186 .](04.07-unsolicited-z-wave-api-commands.md#4735-4-unsolicited-frame-z-wave-module-host) + +Table 4.186: Application Update Command - Unsolicited data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x49 | | | | | | | | +| 5 | Event | | | | | | | | +| 6/6..7 | Remote NodeID | | | | | | | | +| 7/8 | Supported Command Class List Length | | | | | | | | +| 8/9 | Basic Device Class | | | | | | | | +| 8/10 | Generic Device Type | | | | | | | | +| 10/11 | Specific Device Type | | | | | | | | +| (10/11)+1 | Supported Command Class List 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| (11/12)+N | Supported Command Class List N | | | | | | | | + +Event (8 bits) + +This field is used indicate which event has triggered the transmission of this command. This field MUST [be encoded according to Table 4.187](04.07-unsolicited-z-wave-api-commands.md#4735-4-unsolicited-frame-z-wave-module-host) Table 4.187: Application Update Command - Event encoding + +| Value | Description | +| --- | --- | +| 0x10 | UPDATE STATE SUC ID _ _ _ The SIS NodeID has been updated. | +| 0x20 | UPDATE STATE DELETE DONE _ _ _ A node has been deleted from the network. | +| 0x40 | UPDATE STATE NEW ID ASSIGNED _ _ _ _ A new node has been added to the network. | +| 0x40 | UPDATE STATE NEW ID ASSIGNED _ _ _ _ A new node has been added to the network. | +| 0x80 | UPDATE STATE ROUTING PENDING _ _ _ Another node in the network has requested the Z-Wave API Module to perform a neighbor discovery. | +| 0x81 | UPDATE STATE NODE INFO REQ FAILED _ _ _ _ _ The issued Request Node Information Command has not been acknowledged by the destination. | + +| | 0x82 | UPDATE STATE NODE INFO REQ DONE _ _ _ _ _ The issued Request Node Information Command has been acknowledged by the des- tination. | | +| --- | --- | --- | --- | +| | 0x83 | UPDATE STATE NOP POWER RECEIVED _ _ _ _ Another node sent a NOP Power Command to the Z-Wave API Module. The host application SHOULD NOT power down the Z-Wave API Module. | | +| | 0x84 | UPDATE STATE NODE INFO RECEIVED _ _ _ _ A Node Information Frame has been received as unsolicited frame or in response to a Request Node Information Command. | | +| | 0x85 | UPDATE STATE NODE INFO SMARTSTART HOMEID RECEIVED _ _ _ _ _ _ A SmartStart Prime Command has been received using the Z-Wave protocol. | | +| | 0x86 | UPDATE STATE INCLUDED NODE INFO RECEIVED _ _ _ _ _ A SmartStart Included Node Information Frame has been received (using either Z- Wave or Z-Wave Long Range protocol). | | +| | 0x87 | UPDATE STATE NODE INFO SMARTSTART HOMEID RECEIVED LR _ _ _ _ _ _ _ A SmartStart Prime Command has been received using the Z-Wave Long Range pro- tocol. | | + +[Values that are not listed in Table 4.187 are reserved and MUST NOT be used.](04.07-unsolicited-z-wave-api-commands.md#4735-4-unsolicited-frame-z-wave-module-host) + +Remote NodeID (8/16 bits) + +This field is used to advertise the NodeID of the remote node for/with which the event occurred. + +Supported Command Class List Length (8 bits) + +This field is used to indicates the length of the Supported Command Class List field in bytes. + +[Basic Device Class (8 bits)](04.02-generic-command-elements.md#427-basic-device-class-8-bits) + +[Refer to Basic Device Class (8 bits) .](04.02-generic-command-elements.md#427-basic-device-class-8-bits) + +Generic Device Type (8 bits) + +This field is used to advertise the Generic Device Type [of the remote NodeID.](../05-references.md#5-references) + +[For a detailed description of all available Generic Device Classes, refer to [ device_class_spec ] for Z- Wave devices, [ device_type_spec ] for Z-Wave Plus devices, and [ device_type_spec_v2 ] for Z-Wave](../05-references.md#5-references) Plus v2 devices. + +Specific Device Type (8 bits) + +This field is used to advertise the Specific Device Type [of the remote NodeID.](../05-references.md#5-references) + +[For a detailed description of all available Specific Device Classes, refer to [ device_class_spec ] for Z- Wave devices, [ device_type_spec ] for Z-Wave Plus devices, and [ device_type_spec_v2 ] for Z-Wave](../05-references.md#5-references) Plus v2 devices. + +Supported Command Class List (N bytes) + +This field is used to advertise the list of non-secure supported Command Classes by the remote node. + +4.b. Unsolicited Application Update Command with SmartStart Prime events A Z-Wave API module implementing a Controller Node [library type (refer to Table 4.36 ) MUST is-](04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) [sue a unsolicited frame formatted according to Table 4.188 to the host application when it receives a](04.07-unsolicited-z-wave-api-commands.md#4735-4-unsolicited-frame-z-wave-module-host) SmartStart Prime Command or a SmartStart Inclusion Node Information Frame. + +Table 4.188: Application Update Command - SmartStart Prime data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x49 | | | | | | | | +| 5 | Event | | | | | | | | +| 6/6..7 | Remote NodeID | | | | | | | | +| 7/8 | Rx Status | | | | | | | | +| 8/9 | NWI HomeID 1 | | | | | | | | +| 9/10 \| NWI HomeID 2 | | | | | | | | | +| 10/11 | NWI HomeID 3 | | | | | | | | +| 11/12 | NWI HomeID 4 | | | | | | | | +| 12/13 | Supported Command Class List Length | | | | | | | | +| 13/14 | Basic Device Class | | | | | | | | +| 14/15 | Generic Device Type | | | | | | | | +| 15/16 | Specific Device Type | | | | | | | | +| 16/17 | Supported Command Class List 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 17/18+N | Supported Command Class List N | | | | | | | | + +[Refer to 4.a. Unsolicited Application Update Command generic format for fields that are not described](04.07-unsolicited-z-wave-api-commands.md#4735-4-unsolicited-frame-z-wave-module-host) below. + +Event (8 bits) + +This field is used to inform the host application that a SmartStart Prime frame has been received. + +This field MUST be set to one of the following values: + +• UPDATE_STATE_NODE_INFO_SMARTSTART_HOMEID_RECEIVED (0x85) (if received using the Z-Wave Protocol + +• UPDATE_STATE_NODE_INFO_SMARTSTART_HOMEID_RECEIVED_LR (0x87) if re- ceived using the Z-Wave Long Range Protocol [Refer to Application Update Command - Event encoding for details about these values.](04.07-unsolicited-z-wave-api-commands.md#4735-4-unsolicited-frame-z-wave-module-host) + +[Rx Status (8 bits)](04.02-generic-command-elements.md#422-rx-status-8-bits) + +[Refer to Rx Status (8 bits)](04.02-generic-command-elements.md#422-rx-status-8-bits) + +NWI HomeID (4 bytes) + +This field is used to advertise the NWI HomeID on which the SmartStart Prime Command was received. + +4.c. Unsolicited Application Update Command with Include Node Information event A Z-Wave API module implementing a Controller Node [library type (refer to Table 4.36 ) MUST is-](04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) [sue a unsolicited frame formatted according to Table 4.189 to the host application when it receives a](04.07-unsolicited-z-wave-api-commands.md#4735-4-unsolicited-frame-z-wave-module-host) SmartStart Prime Command or a SmartStart Inclusion Node Information Frame. + +Table 4.189: Application Update Command - SmartStart INIF data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x49 | | | | | | | | +| 5 | Event | | | | | | | | +| 6/6..7 | Remote NodeID | | | | | | | | +| 7/8 | Reserved | | | | | | | | +| 8/9 | Rx Status | | | | | | | | +| 9/10 | NWI HomeID 1 | | | | | | | | +| 10/11 | NWI HomeID 2 | | | | | | | | +| 11/12 | NWI HomeID 3 | | | | | | | | +| 12/13 | NWI HomeID 4 | | | | | | | | + +[Refer to 4.a. Unsolicited Application Update Command generic format for fields that are not described](04.07-unsolicited-z-wave-api-commands.md#4735-4-unsolicited-frame-z-wave-module-host) below. + +Event (8 bits) + +This field is used to inform the host application that a SmartStart Included Node Information frame has been received. This field MUST be set to UPDATE_STATE_INCLUDED_NODE_INFO_RECEIVED (0x86). + +[Refer to Application Update Command - Event encoding for defailts about these values.](04.07-unsolicited-z-wave-api-commands.md#4735-4-unsolicited-frame-z-wave-module-host) + +Reserved (8 bits) + +This field is obsoleted. + +It SHOULD be set to 0 by a Z-Wave API Module and ignored by a Host Application. + +[Rx Status (8 bits)](04.02-generic-command-elements.md#422-rx-status-8-bits) + +[Refer to Rx Status (8 bits)](04.02-generic-command-elements.md#422-rx-status-8-bits) + +NWI HomeID (4 bytes) + +This field is used to advertise the NWI HomeID for which the SmartStart Inclusion Node Information Frame was received. + +## 4.7.4 Bridge Application Command Handler Command + +This command is used by a Z-Wave module to notify a host application that a Z-Wave frame has been received. The Bridge Application Command Handler Command Identifier is 0xA8. + +This command MUST only be supported by Z-Wave API Modules implementing a Bridge Controller library [(refer to Table 4.36 ). Z-Wave API Modules with another library type MUST use the](04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) [Application Command Handler Command instead.](04.07-unsolicited-z-wave-api-commands.md#471-application-command-handler-command) + +## 4.7.4.1 Frame flow + +[The frame flow for this command is an Unsolicited frame .](../03-interface-communication/03.03-command-frame-flows.md#336-unsolicited-frame) + +## 4.7.4.2 1. Initial data frame (host → Z-Wave Module) + +None. + +## 4.7.4.3 2. Response data frame (Z-Wave Module → host) + +None. + +## 4.7.4.4 3. Callback data frame (Z-Wave Module → host) + +None. + +## 4.7.4.5 4. Unsolicited frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue an unsolicited frame formatted according to Table 4.190 .](04.07-unsolicited-z-wave-api-commands.md#4745-4-unsolicited-frame-z-wave-module-host) + +Table 4.190: Bridge Application Command Handler Command - Unsolicited data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xA8 | | | | | | | | +| 5 | Rx Status | | | | | | | | +| 6/6..7 | Destination NodeID | | | | | | | | +| 7/8..9 | Source NodeID | | | | | | | | +| 8/10 | Payload Length | | | | | | | | +| (8/10)+1 | Payload 1 | | | | | | | | +| .. | . . . | | | | | | | | +| (9/10)+N | Payload N | | | | | | | | +| 10/11+N | Multicast Destination Node Mask Length | | | | | | | | +| 11/12+N | Multicast Destination Node Mask 1 | | | | | | | | +| .. | . . . | | | | | | | | + +| 11/12+N+M | Multicast Destination Node Mask M | +| --- | --- | +| 12/13+N+M | Received RSSI | + +Rx Status (8 bits) + +[Refer to Rx Status (8 bits) .](04.02-generic-command-elements.md#422-rx-status-8-bits) + +Destination NodeID (8/16 bits) + +[This field is used to advertise the NodeID to which the Z-Wave Command is addressed.](04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +If received frame is a multicast frame, the Destination NodeID is not valid. + +Source NodeID (8/16 bits) + +[This field is used to advertise the NodeID from which the Z-Wave Command was received.](04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Payload Length (8 bits) + +This field is used to indicate the length of the Payload field in bytes. + +Payload (N bytes) + +This field is used to advertise payload of the received Z-Wave frame. The very first byte will be a Command Class identifier. + +The length of this field, in bytes, MUST be according to the Payload Length field. + +Multicast Destination Node Mask Length (8 bits) + +This field is used to indicate the length of the Multicast Destination Node Mask field in bytes. + +Multicast Destination Node Mask (M bytes) + +This field is used to indicate the destination nodes IDs using multicast addressing. + +The length of this field, in bytes, MUST be according to the Multicast Destination Node Mask Length field. + +Received RSSI (8 bits) + +This field is used to indicate the received frame RSSI value. This field value MUST be encoded accord- [ing to Table 4.3 .](../03-interface-communication/03.02-frame-types.md#321-data-frame) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.01-clear-tx-timers-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.01-clear-tx-timers-command.md new file mode 100644 index 0000000..21535aa --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.01-clear-tx-timers-command.md @@ -0,0 +1,10 @@ + +# 4.8.1 Clear Tx Timers Command + +This command is used to clear/reset the Z-Wave Module internal Tx timers. The Tx timers are updated by the module when a frame is sent. The Clear Tx Timers Command Identifier is 0x37 diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.01.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.01.01-frame-flow.md new file mode 100644 index 0000000..eac50e2 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.01.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.8.1.1 Frame flow + +[The frame flow for this command is an Acknowledged frame .](../../03-interface-communication/03.03-command-frame-flows.md#332-acknowledged-frame) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.01.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.01.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..fe67719 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.01.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,16 @@ + +# 4.8.1.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.191](04.08.01.02-1-initial-data-frame-host-z-wave-module.md#4812-1-initial-data-frame-host-z-wave-module) + +Table 4.191: Clear Tx Timers Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x37 | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.01.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.01.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..1d20387 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.01.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.1.3 2. Response data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.01.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.01.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..d9cc76d --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.01.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.1.4 3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.02-get-background-rssi-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.02-get-background-rssi-command.md new file mode 100644 index 0000000..064be99 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.02-get-background-rssi-command.md @@ -0,0 +1,12 @@ + +# 4.8.2 Get Background RSSI Command + +This command is used to request the most recent background RSSI levels detected. The Get Background RSSI Command Identifier is 0x3B. + +NOTE: The RSSI shall only be measured when the radio is in receive mode. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.02.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.02.01-frame-flow.md new file mode 100644 index 0000000..83bc4ac --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.02.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.8.2.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.02.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.02.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..8aa4ed2 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.02.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,16 @@ + +# 4.8.2.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.192](04.08.02.02-1-initial-data-frame-host-z-wave-module.md#4822-1-initial-data-frame-host-z-wave-module) + +Table 4.192: Get Background RSSI Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x3B | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.02.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.02.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..5fef46a --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.02.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,29 @@ + +# 4.8.2.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.193](04.08.02.03-2-response-data-frame-z-wave-module-host.md#4823-2-response-data-frame-z-wave-module-host) + +Table 4.193: Get Background RSSI Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x3B | | | | | | | | +| 5 | RSSI CH0 | | | | | | | | +| 6 | RSSI CH1 | | | | | | | | +| 7 | RSSI CH2 | | | | | | | | + +RSSI (2 or 3 bytes) + +The RSSI fields are used to indicate the measured RSSI. + +If the Z-Wave Module operates on a 2 channel RF Profile, RSSI CH0, and RSSI CH1 field MUSTTt contain the RSSI values of the first and second channel. + +If the Z-Wave Module operates on a 3 channel RF profile, all three RSSI fields MUST contain RSSI values. + +[All RSSI measurements MUST be encoded according to Table 4.3](../../03-interface-communication/03.02-frame-types.md#321-data-frame) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.02.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.02.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..87b57f5 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.02.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.2.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.03-get-tx-timer-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.03-get-tx-timer-command.md new file mode 100644 index 0000000..fc3ab5b --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.03-get-tx-timer-command.md @@ -0,0 +1,10 @@ + +# 4.8.3 Get Tx Timer Command + +This command is used to request the Z-Wave Module internal Tx timer. When the module receives this command, it MUST return the Tx timer for each channels. The Get Tx Timer Command Identifier is 0x38. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.03.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.03.01-frame-flow.md new file mode 100644 index 0000000..c4b77b7 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.03.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.8.3.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.03.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.03.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..015dcc3 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.03.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,16 @@ + +# 4.8.3.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.194](04.08.03.02-1-initial-data-frame-host-z-wave-module.md#4832-1-initial-data-frame-host-z-wave-module) + +Table 4.194: Get Tx Timer Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x38 | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.03.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.03.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..60d32b5 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.03.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,31 @@ + +# 4.8.3.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.195](04.08.03.03-2-response-data-frame-z-wave-module-host.md#4833-2-response-data-frame-z-wave-module-host) + +Table 4.195: Get Tx Timer Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x38 | | | | | | | | +| 5 | Tx Timer Channel 0 | | | | | | | | +| 6 | Tx Timer Channel 1 | | | | | | | | +| 7 | Tx Timer Channel 2 | | | | | | | | + +Tx Timer Channel 0 (8 bits) + +This field is used to advertise time [in miliseconds] the tranmistter has been active on channel 0 since the last reset. + +Tx Timer Channel 1 (8 bits) + +This field is used to advertise time [in miliseconds] the tranmistter has been active on channel 1 since the last reset. + +Tx Timer Channel 2 (8 bits) + +This field is used to advertise time [in miliseconds] the tranmistter has been active on channel 2 since the last reset. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.03.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.03.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..8591f6d --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.03.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.3.4 3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.04-get-virtual-nodes-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.04-get-virtual-nodes-command.md new file mode 100644 index 0000000..b8be2ac --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.04-get-virtual-nodes-command.md @@ -0,0 +1,10 @@ + +# 4.8.4 Get Virtual Nodes Command + +This command is used to request available Virtual End Nodes in a Z-Wave Network. The Get Virtual Nodes Command Identifier is 0xA5. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.04.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.04.01-frame-flow.md new file mode 100644 index 0000000..5754061 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.04.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.8.4.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.04.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.04.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..eeccb0c --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.04.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,16 @@ + +# 4.8.4.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.196 .](04.08.04.02-1-initial-data-frame-host-z-wave-module.md#4842-1-initial-data-frame-host-z-wave-module) + +Table 4.196: Get Virtual Nodes Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xA5 | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.04.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.04.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..b3ed0ba --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.04.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,25 @@ + +# 4.8.4.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.197 to notify the](04.08.04.03-2-response-data-frame-z-wave-module-host.md#4843-2-response-data-frame-z-wave-module-host) available Virtual End Nodes to the application that requests the list of virtual node using Get Virtual Nodes Command request frame. + +Table 4.197: Get Virtual Nodes Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xA5 | | | | | | | | +| 5 | NodeMask | | | | | | | | + +NodeMask(N bytes) + +This field is used to indicate the bit mask of the virtual end NodeIDs in a Z-Wave network. The field value MUST be encoded according to: + +• If bit ‘n’ in the NodeMask byte ‘i’ is 1, it indicates that node (i*8)+n+1 is a virtual end node. + +• If bit ‘n’ in the NodeMask byte ‘i’ is 0, it indicates that node (i*8)+n+1 is not a virtual end node. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.04.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.04.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..1db68b4 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.04.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.4.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.05-get-z-wave-module-protocol-status-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.05-get-z-wave-module-protocol-status-command.md new file mode 100644 index 0000000..5aea086 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.05-get-z-wave-module-protocol-status-command.md @@ -0,0 +1,10 @@ + +# 4.8.5 Get Z-Wave Module Protocol Status Command + +This command is used to request the current status of the protocol runs on the Z-Wave module. The Get Z-Wave Module Protocol Status Command Identifier is 0xBF. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.05.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.05.01-frame-flow.md new file mode 100644 index 0000000..19e3618 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.05.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.8.5.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.05.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.05.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..8e55679 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.05.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,16 @@ + +# 4.8.5.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.198 to request the protocol status.](04.08.05.02-1-initial-data-frame-host-z-wave-module.md#4852-1-initial-data-frame-host-z-wave-module) + +Table 4.198: Get Z-Wave Module Protocol Status Command - Ini- tial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xBF | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.05.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.05.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..e88c6f2 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.05.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,30 @@ + +# 4.8.5.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.199 for notifying the](04.08.05.03-2-response-data-frame-z-wave-module-host.md#4853-2-response-data-frame-z-wave-module-host) current status of the Z-Wave protocol to the host application. + +Table 4.199: Get Z-Wave Module Protocol Status Command - Re- sponse data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xBF | | | | | | | | +| 5 | Status | | | | | | | | + +Status (8 bits) + +This field is used to advertise the current status of the protocol runs on the Z-Wave module. This field [MUST be encoded according to Table 4.200](04.08.05.03-2-response-data-frame-z-wave-module-host.md#4853-2-response-data-frame-z-wave-module-host) + +Table 4.200: Z-Wave protocol status encoding + +| Value | Flag | Description | +| --- | --- | --- | +| 0x00 | IDLE | Protocol is idle. | +| 0x01 | ZW PROTOCOL STATUS ROUTING _ _ _ | Protocol is analyzing the routing table. | +| 0x02 | ZW PROTOCOL STATUS SUC _ _ _ | SIS sends pending updates. | +| 0x03..0xFF | Reserved | Reserved values MUST NOT be used. | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.05.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.05.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..57bd565 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.05.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.5.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.06-is-virtual-node-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.06-is-virtual-node-command.md new file mode 100644 index 0000000..8c9a037 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.06-is-virtual-node-command.md @@ -0,0 +1,10 @@ + +# 4.8.6 Is Virtual Node Command + +This command is used to check if a given NodeID is a virtual end node. The Is Virtual Node Command Identifier is 0xA6. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.06.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.06.01-frame-flow.md new file mode 100644 index 0000000..6c88260 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.06.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.8.6.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.06.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.06.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..ffdad33 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.06.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,23 @@ + +# 4.8.6.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.201 .](04.08.06.02-1-initial-data-frame-host-z-wave-module.md#4862-1-initial-data-frame-host-z-wave-module) + +Table 4.201: Is Virtual Node Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xA6 | | | | | | | | +| 5 | NodeID | | | | | | | | + +NodeID (8 bits) + +This field is used to indicate the NodeID on node for which virtual node status is requested. + +[This field MUST be encoded using 8 bits regardless of the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.06.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.06.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..e47babf --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.06.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,25 @@ + +# 4.8.6.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.202 .](04.08.06.03-2-response-data-frame-z-wave-module-host.md#4863-2-response-data-frame-z-wave-module-host) + +Table 4.202: Is Virtual Node Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xA6 | | | | | | | | +| 5 | Virtual node characteristic | | | | | | | | + +Virtual node characteristic (8 bits) + +This field is used to advertise characteristic of the request NodeID. This field MUST be encoded as follow: + +• If the NodeID is a virtual node, this field MUST be set to 0x01. + +• If the NodeID is not a virtual node. this field MUST be set to 0x00. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.06.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.06.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..3bb3eb3 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.06.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.6.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.07-set-listen-before-talk-threshold-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.07-set-listen-before-talk-threshold-command.md new file mode 100644 index 0000000..e2a9e4b --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.07-set-listen-before-talk-threshold-command.md @@ -0,0 +1,10 @@ + +# 4.8.7 Set Listen Before Talk Threshold Command + +This command is used to to set the “Listen Before Talk” RSSI threshold that controls at what RSSI level a Z-Wave node will refuse to transmit because of noise. The default threshold value is set to a value corresponding to the RF regulatory requirements in the specific country. The Set Listen Before Talk Threshold Command Identifier is 0x3C. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.07.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.07.01-frame-flow.md new file mode 100644 index 0000000..df1d184 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.07.01-frame-flow.md @@ -0,0 +1,12 @@ + +# 4.8.7.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +This command SHOULD be used once for each channel configured by the Host Application. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.07.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.07.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..b76968e --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.07.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,32 @@ + +# 4.8.7.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.203](04.08.07.02-1-initial-data-frame-host-z-wave-module.md#4872-1-initial-data-frame-host-z-wave-module) + +Table 4.203: Set Listen Before Talk Threshold Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x3C | | | | | | | | +| 5 | Channel | | | | | | | | +| 6 | RSSI Threshold | | | | | | | | + +Channel (8 bits) + +This field is used to indicate the channel number where the RSSI threshold shall be set for. Valid channel numbers are 0, 1, 2 and 3. + +Channel values 0..2 MUST indicate the Z-Wave channel number. Channel value 3 MUST indicate the Z-Wave Long Range Channel. + +A Z-Wave API Module without Z-Wave Long Range support will ignore the channel value 3. + +RSSI Threshold (8 bits) + +This field is used to indicate the RSSI threshold that MUST be used by the Z-Wave API Module to detect the channel availability. + +[This field MUST be encoded according to This field MUST be encoded according to RSSI Measurements (8 bits) and](../04.02-generic-command-elements.md#424-rssi-measurements-8-bits) [Table 4.3 . The values 125, 126 and 127 MUST NOT be used by a Host Application in this](../../03-interface-communication/03.02-frame-types.md#321-data-frame) command and MUST be ignored by a Z-Wave API Module if received. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.07.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.07.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..f72d2f7 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.07.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,23 @@ + +# 4.8.7.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.204](04.08.07.03-2-response-data-frame-z-wave-module-host.md#4873-2-response-data-frame-z-wave-module-host) Table 4.204: Set Listen Before Talk Threshold Command - Re- sponse data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x3C | | | | | | | | +| 5 | Status | | | | | | | | + +Status (8 bits) + +This field is used to indicate status regarding the Set Listen Before Talk Threshold request command. + +• If the Listen Before Talk Threshold value is accepted by the Z-Wave Module, the field value MUST be set to 0x01. + +• If the Listen Before Talk Threshold value is not accepted, the field value MUST be set to 0x00. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.07.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.07.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..7fd4085 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.07.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.7.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.08-set-rf-receive-mode-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.08-set-rf-receive-mode-command.md new file mode 100644 index 0000000..92c43b4 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.08-set-rf-receive-mode-command.md @@ -0,0 +1,12 @@ + +# 4.8.8 Set RF Receive Mode Command + +This command is used to to power down the RF when not in use e.g., expects nothing to be received. It can also be used to set the RF into receive mode. This functionality is useful in battery powered Z-Wave nodes. The RF is automatic powered up when transmitting data. + +The Set RF Receive Mode Command Identifier is 0x10. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.08.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.08.01-frame-flow.md new file mode 100644 index 0000000..d24c48a --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.08.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.8.8.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.08.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.08.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..30f3805 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.08.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,28 @@ + +# 4.8.8.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.205](04.08.08.02-1-initial-data-frame-host-z-wave-module.md#4882-1-initial-data-frame-host-z-wave-module) + +Table 4.205: Set RF Receive Mode Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x10 | | | | | | | | +| 5 | Mode | | | | | | | | + +Mode (8 bits) + +This field is used to advertise information about the Set RF Receive Mode operation mode. The feild [MUST encoded with the format indicated in Table 4.206 .](04.08.08.02-1-initial-data-frame-host-z-wave-module.md#4882-1-initial-data-frame-host-z-wave-module) + +Table 4.206: Set RF Receive Mode Command - Mode encoding + +| Value | Flags | Description | +| --- | --- | --- | +| 0x01 | On | Set the RF in receive mode and starts the receive data sampling | +| 0x00 | Off | Set the RF in power down mode (for battery power save). | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.08.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.08.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..190051a --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.08.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,29 @@ + +# 4.8.8.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.207](04.08.08.03-2-response-data-frame-z-wave-module-host.md#4883-2-response-data-frame-z-wave-module-host) + +Table 4.207: Set Rf Receive Mode Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x10 | | | | | | | | +| 5 | Status | | | | | | | | + +Status (8 bits) + +This field is used to advertise information about the status of the Set RF Receive Mode operation. The feild MUST encoded according to: + +• 0x01, If the operation was successfull. + +• 0x00, If the operation was not successfull. + +3. Callback data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.09-set-rf-power-level-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.09-set-rf-power-level-command.md new file mode 100644 index 0000000..d845eda --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.09-set-rf-power-level-command.md @@ -0,0 +1,12 @@ + +# 4.8.9 Set RF Power Level Command + +This command is used to set the power level used for RF transmission. The Set RF Power Level Com- mand Identifier is 0x17. + +NOTE: This command should only be used in an install/test link situation and the power level should always be set back to normal Power when the testing is done. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.09.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.09.01-frame-flow.md new file mode 100644 index 0000000..fe1d17c --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.09.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.8.9.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.09.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.09.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..8315c10 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.09.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,36 @@ + +# 4.8.9.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.208](04.08.09.02-1-initial-data-frame-host-z-wave-module.md#4892-1-initial-data-frame-host-z-wave-module) + +Table 4.208: Set RF Power Level Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x17 | | | | | | | | +| 5 | PowerLevel | | | | | | | | + +Powerlevel (8 bits) + +This field is used to indicate the power level that shall be used for the RF transmission. This field MUST [comply with the format indicated in Table 4.209 .](04.08.09.02-1-initial-data-frame-host-z-wave-module.md#4892-1-initial-data-frame-host-z-wave-module) + +Table 4.209: Set RF Power Level Command - Power Level encod- ing + +| Value | Description | +| --- | --- | +| NormalPower | Normal transmit power configured on the device. | +| -1dB | NormalPower - 1dB | +| -2dB | NormalPower - 2dB | +| -3dB | NormalPower - 3dB | +| -4dB | NormalPower - 4dB | +| -5dB | NormalPower - 5dB | +| -6dB | NormalPower - 6dB | +| -7dB | NormalPower - 7dB | +| -8dB | NormalPower - 8dB | +| -9dB | NormalPower - 9dB | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.09.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.09.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..0e15de0 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.09.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,19 @@ + +# 4.8.9.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.210](04.08.09.03-2-response-data-frame-z-wave-module-host.md#4893-2-response-data-frame-z-wave-module-host) Table 4.210: Set RF Power Level Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x17 | | | | | | | | +| 5 | Powerlevel | | | | | | | | + +Powerlevel (8 bits) + +This field is used to indicate the actual RF power level that can used for transmitting a given test frame. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.09.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.09.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..9474f40 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.09.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.9.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.10-set-maximum-routing-attempts-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.10-set-maximum-routing-attempts-command.md new file mode 100644 index 0000000..168b301 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.10-set-maximum-routing-attempts-command.md @@ -0,0 +1,10 @@ + +# 4.8.10 Set Maximum Routing Attempts Command + +This command is used to set the maximum number of source routing attempts based on the routing table lookups, and this shall be used before the Z-Wave protocol layer starts the dynamic route resolution. The Set Maximum Routing Retries Command Identifier is 0xD4. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.10.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.10.01-frame-flow.md new file mode 100644 index 0000000..9305d39 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.10.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.8.10.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.10.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.10.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..86dd532 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.10.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,21 @@ + +# 4.8.10.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.211 for setting the maximum source](04.08.10.02-1-initial-data-frame-host-z-wave-module.md#48102-1-initial-data-frame-host-z-wave-module) routing attempts. + +Table 4.211: Set Maximum Routing Attempts Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xD4 | | | | | | | | +| 5 | Max Routing Retries | | | | | | | | + +Max Routing Retries (8 bits) + +This field is used to indicate the maximum source routing attempts that can be used before the Z-Wave module triggers dynamic route resolution. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.10.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.10.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..3630779 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.10.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,21 @@ + +# 4.8.10.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.212 when it is asked](04.08.10.03-2-response-data-frame-z-wave-module-host.md#48103-2-response-data-frame-z-wave-module-host) to set the maximum source routing attempts. + +Table 4.212: Set Maximum Routing Attempts Command - Re- sponse data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xD4 | | | | | | | | +| 5 | Command Status | | | | | | | | + +[Command Status (8 bits)](../04.02-generic-command-elements.md#426-command-status-8-bits) + +[Refer Command Status (8 bits) .](../04.02-generic-command-elements.md#426-command-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.10.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.10.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..5b909e7 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.10.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.10.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.11-set-rf-power-level-rediscovery-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.11-set-rf-power-level-rediscovery-command.md new file mode 100644 index 0000000..7f0f53b --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.11-set-rf-power-level-rediscovery-command.md @@ -0,0 +1,10 @@ + +# 4.8.11 Set RF Power Level Rediscovery Command + +This command is used to set the power level to RF Module that can be used for finding neighboring nodes. The Set RF Power Level Rediscovery Command Identifier is 0x1E. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.11.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.11.01-frame-flow.md new file mode 100644 index 0000000..6ccb579 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.11.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.8.11.1 Frame flow + +[The frame flow for this command is an Acknowledged frame .](../../03-interface-communication/03.03-command-frame-flows.md#332-acknowledged-frame) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.11.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.11.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..f014892 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.11.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,23 @@ + +# 4.8.11.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.213](04.08.11.02-1-initial-data-frame-host-z-wave-module.md#48112-1-initial-data-frame-host-z-wave-module) + +Table 4.213: Set RF Power Level Rediscovery Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x1E | | | | | | | | +| 5 | PowerLevel | | | | | | | | + +Powerlevel (8 bits) + +This field is used to indicate the power level that MUST be used by the node when performing the neighbor discovery process. + +[This field MUST comply with the format indicated in Table 4.210 .](04.08.09.03-2-response-data-frame-z-wave-module-host.md#4893-2-response-data-frame-z-wave-module-host) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.11.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.11.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..da4955c --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.11.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.11.3 2. Response data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.11.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.11.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..8c23e76 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.11.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.11.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.12-start-watchdog-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.12-start-watchdog-command.md new file mode 100644 index 0000000..8c6b25f --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.12-start-watchdog-command.md @@ -0,0 +1,10 @@ + +# 4.8.12 Start Watchdog Command + +This command is used to start Watchdog functionality on Z-Wave module. The Start Watchdog Com- mand Identifier is 0xD2. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.12.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.12.01-frame-flow.md new file mode 100644 index 0000000..0f6b461 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.12.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.8.12.1 Frame flow + +[The frame flow for this command is an Unacknowledged frame .](../../03-interface-communication/03.03-command-frame-flows.md#331-unacknowledged-frame) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.12.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.12.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..5670837 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.12.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,16 @@ + +# 4.8.12.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.214 for triggering the Watchdog func-](04.08.12.02-1-initial-data-frame-host-z-wave-module.md#48122-1-initial-data-frame-host-z-wave-module) tionality on a Z-Wave module. + +Table 4.214: Start Watchdog Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xD2 | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.12.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.12.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..f88be0a --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.12.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.12.3 2. Response data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.12.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.12.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..e28b61c --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.12.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.12.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.13-stop-watchdog-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.13-stop-watchdog-command.md new file mode 100644 index 0000000..f0eaba3 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.13-stop-watchdog-command.md @@ -0,0 +1,10 @@ + +# 4.8.13 Stop Watchdog Command + +This command is used to stop Watchdog functionality on Z-Wave module. The Start Watchdog Com- mand Identifier is 0xD3. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.13.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.13.01-frame-flow.md new file mode 100644 index 0000000..d97de9d --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.13.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.8.13.1 Frame flow + +[The frame flow for this command is an Unacknowledged frame .](../../03-interface-communication/03.03-command-frame-flows.md#331-unacknowledged-frame) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.13.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.13.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..a5df537 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.13.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,16 @@ + +# 4.8.13.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.215 for stopping the Watchdog func-](04.08.13.02-1-initial-data-frame-host-z-wave-module.md#48132-1-initial-data-frame-host-z-wave-module) tionality on a Z-Wave module. + +Table 4.215: Stop Watchdog Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xD3 | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.13.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.13.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..b1c833b --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.13.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.13.3 2. Response data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.13.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.13.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..b6952c3 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.13.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.13.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.14-set-timeouts-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.14-set-timeouts-command.md new file mode 100644 index 0000000..fd20ba6 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.14-set-timeouts-command.md @@ -0,0 +1,10 @@ + +# 4.8.14 Set Timeouts Command + +This command is used to set timeouts with 10ms ticks. The Set Timeouts Command Identifier is 0x06. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.14.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.14.01-frame-flow.md new file mode 100644 index 0000000..79ccc99 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.14.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.8.14.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.14.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.14.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..059228f --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.14.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,26 @@ + +# 4.8.14.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.216 .](04.08.14.02-1-initial-data-frame-host-z-wave-module.md#48142-1-initial-data-frame-host-z-wave-module) + +Table 4.216: Set Timeouts Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x06 | | | | | | | | +| 5 | Rx ACK Timeout | | | | | | | | +| 6 | Rx BYTE Timeout | | | | | | | | + +Rx ACK Timeout (8 bits) + +This field is used to indicate the maximum time to wait for ACK after frame transmission, in 10ms ticks. + +Rx BYTE Timeout (8 bits) + +This field is used to indicate the maximum time to wait for next byte when receiving a new frame, in 10ms ticks. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.14.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.14.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..c91946c --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.14.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,26 @@ + +# 4.8.14.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.217 .](04.08.14.03-2-response-data-frame-z-wave-module-host.md#48143-2-response-data-frame-z-wave-module-host) + +Table 4.217: Set Timeouts Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x06 | | | | | | | | +| 5 | Previous Rx ACK Timeout | | | | | | | | +| 6 | Previous Rx BYTE Timeout | | | | | | | | + +Previous Rx ACK Timeout (8 bits) + +This field is used to indicate previous Rx ACK timeout setting, in 10ms ticks. + +Previous Rx BYTE Timeout (8 bits) + +This field is used to indicate previous Rx BYTE timeout setting, in 10ms ticks. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.14.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.14.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..a5914eb --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.14.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.14.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.15-initiate-shutdown-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.15-initiate-shutdown-command.md new file mode 100644 index 0000000..5a7a013 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.15-initiate-shutdown-command.md @@ -0,0 +1,10 @@ + +# 4.8.15 Initiate Shutdown Command + +This command is used to instruct the Z-Wave API to go to sleep in order to remove the power. The Initiate Shutdown Command Identifier is 0xD9. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.15.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.15.01-frame-flow.md new file mode 100644 index 0000000..2bd7f22 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.15.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.8.15.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.15.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.15.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..29730d4 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.15.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,16 @@ + +# 4.8.15.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.218](04.08.15.02-1-initial-data-frame-host-z-wave-module.md#48152-1-initial-data-frame-host-z-wave-module) + +Table 4.218: Initiate Shutdown Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xD9 | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.15.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.15.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..dfd9226 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.15.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,21 @@ + +# 4.8.15.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.219](04.08.15.03-2-response-data-frame-z-wave-module-host.md#48153-2-response-data-frame-z-wave-module-host) + +Table 4.219: Initiate Shutdown Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xD9 | | | | | | | | +| 5 | Command Status | | | | | | | | + +[Command Status (8 bits)](../04.02-generic-command-elements.md#426-command-status-8-bits) + +[Refer to Command Status (8 bits) .](../04.02-generic-command-elements.md#426-command-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.15.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.15.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..cd1e32f --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/04.08.15.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.8.15.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/index.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/index.md new file mode 100644 index 0000000..c7c6b73 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.08-z-wave-api-miscellaneous-commands/index.md @@ -0,0 +1,87 @@ + +# 4.8 Z-Wave API Miscellaneous Commands + +[This section describes Z-Wave API Commands that do not belong in any of the other categories.](../index.md#4-z-wave-api-commands) + +## Contents + +- [4.8.1 Clear Tx Timers Command](04.08.01-clear-tx-timers-command.md) +- [4.8.1.1 Frame flow](04.08.01.01-frame-flow.md) +- [4.8.1.2 1. Initial data frame (host → Z-Wave Module)](04.08.01.02-1-initial-data-frame-host-z-wave-module.md) +- [4.8.1.3 2. Response data frame (Z-Wave Module → host)](04.08.01.03-2-response-data-frame-z-wave-module-host.md) +- [4.8.1.4 3. Callback data frame (Z-Wave Module → host)](04.08.01.04-3-callback-data-frame-z-wave-module-host.md) +- [4.8.2 Get Background RSSI Command](04.08.02-get-background-rssi-command.md) +- [4.8.2.1 Frame flow](04.08.02.01-frame-flow.md) +- [4.8.2.2 1. Initial data frame (host → Z-Wave Module)](04.08.02.02-1-initial-data-frame-host-z-wave-module.md) +- [4.8.2.3 2. Response data frame (Z-Wave Module → host)](04.08.02.03-2-response-data-frame-z-wave-module-host.md) +- [4.8.2.4 3. Callback data frame (Z-Wave Module → host)](04.08.02.04-3-callback-data-frame-z-wave-module-host.md) +- [4.8.3 Get Tx Timer Command](04.08.03-get-tx-timer-command.md) +- [4.8.3.1 Frame flow](04.08.03.01-frame-flow.md) +- [4.8.3.2 1. Initial data frame (host → Z-Wave Module)](04.08.03.02-1-initial-data-frame-host-z-wave-module.md) +- [4.8.3.3 2. Response data frame (Z-Wave Module → host)](04.08.03.03-2-response-data-frame-z-wave-module-host.md) +- [4.8.3.4 3. Callback data frame (Z-Wave Module → host)](04.08.03.04-3-callback-data-frame-z-wave-module-host.md) +- [4.8.4 Get Virtual Nodes Command](04.08.04-get-virtual-nodes-command.md) +- [4.8.4.1 Frame flow](04.08.04.01-frame-flow.md) +- [4.8.4.2 1. Initial data frame (host → Z-Wave Module)](04.08.04.02-1-initial-data-frame-host-z-wave-module.md) +- [4.8.4.3 2. Response data frame (Z-Wave Module → host)](04.08.04.03-2-response-data-frame-z-wave-module-host.md) +- [4.8.4.4 3. Callback data frame (Z-Wave Module → host)](04.08.04.04-3-callback-data-frame-z-wave-module-host.md) +- [4.8.5 Get Z-Wave Module Protocol Status Command](04.08.05-get-z-wave-module-protocol-status-command.md) +- [4.8.5.1 Frame flow](04.08.05.01-frame-flow.md) +- [4.8.5.2 1. Initial data frame (host → Z-Wave Module)](04.08.05.02-1-initial-data-frame-host-z-wave-module.md) +- [4.8.5.3 2. Response data frame (Z-Wave Module → host)](04.08.05.03-2-response-data-frame-z-wave-module-host.md) +- [4.8.5.4 3. Callback data frame (Z-Wave Module → host)](04.08.05.04-3-callback-data-frame-z-wave-module-host.md) +- [4.8.6 Is Virtual Node Command](04.08.06-is-virtual-node-command.md) +- [4.8.6.1 Frame flow](04.08.06.01-frame-flow.md) +- [4.8.6.2 1. Initial data frame (host → Z-Wave Module)](04.08.06.02-1-initial-data-frame-host-z-wave-module.md) +- [4.8.6.3 2. Response data frame (Z-Wave Module → host)](04.08.06.03-2-response-data-frame-z-wave-module-host.md) +- [4.8.6.4 3. Callback data frame (Z-Wave Module → host)](04.08.06.04-3-callback-data-frame-z-wave-module-host.md) +- [4.8.7 Set Listen Before Talk Threshold Command](04.08.07-set-listen-before-talk-threshold-command.md) +- [4.8.7.1 Frame flow](04.08.07.01-frame-flow.md) +- [4.8.7.2 1. Initial data frame (host → Z-Wave Module)](04.08.07.02-1-initial-data-frame-host-z-wave-module.md) +- [4.8.7.3 2. Response data frame (Z-Wave Module → host)](04.08.07.03-2-response-data-frame-z-wave-module-host.md) +- [4.8.7.4 3. Callback data frame (Z-Wave Module → host)](04.08.07.04-3-callback-data-frame-z-wave-module-host.md) +- [4.8.8 Set RF Receive Mode Command](04.08.08-set-rf-receive-mode-command.md) +- [4.8.8.1 Frame flow](04.08.08.01-frame-flow.md) +- [4.8.8.2 1. Initial data frame (host → Z-Wave Module)](04.08.08.02-1-initial-data-frame-host-z-wave-module.md) +- [4.8.8.3 2. Response data frame (Z-Wave Module → host)](04.08.08.03-2-response-data-frame-z-wave-module-host.md) +- [4.8.9 Set RF Power Level Command](04.08.09-set-rf-power-level-command.md) +- [4.8.9.1 Frame flow](04.08.09.01-frame-flow.md) +- [4.8.9.2 1. Initial data frame (host → Z-Wave Module)](04.08.09.02-1-initial-data-frame-host-z-wave-module.md) +- [4.8.9.3 2. Response data frame (Z-Wave Module → host)](04.08.09.03-2-response-data-frame-z-wave-module-host.md) +- [4.8.9.4 3. Callback data frame (Z-Wave Module → host)](04.08.09.04-3-callback-data-frame-z-wave-module-host.md) +- [4.8.10 Set Maximum Routing Attempts Command](04.08.10-set-maximum-routing-attempts-command.md) +- [4.8.10.1 Frame flow](04.08.10.01-frame-flow.md) +- [4.8.10.2 1. Initial data frame (host → Z-Wave Module)](04.08.10.02-1-initial-data-frame-host-z-wave-module.md) +- [4.8.10.3 2. Response data frame (Z-Wave Module → host)](04.08.10.03-2-response-data-frame-z-wave-module-host.md) +- [4.8.10.4 3. Callback data frame (Z-Wave Module → host)](04.08.10.04-3-callback-data-frame-z-wave-module-host.md) +- [4.8.11 Set RF Power Level Rediscovery Command](04.08.11-set-rf-power-level-rediscovery-command.md) +- [4.8.11.1 Frame flow](04.08.11.01-frame-flow.md) +- [4.8.11.2 1. Initial data frame (host → Z-Wave Module)](04.08.11.02-1-initial-data-frame-host-z-wave-module.md) +- [4.8.11.3 2. Response data frame (Z-Wave Module → host)](04.08.11.03-2-response-data-frame-z-wave-module-host.md) +- [4.8.11.4 3. Callback data frame (Z-Wave Module → host)](04.08.11.04-3-callback-data-frame-z-wave-module-host.md) +- [4.8.12 Start Watchdog Command](04.08.12-start-watchdog-command.md) +- [4.8.12.1 Frame flow](04.08.12.01-frame-flow.md) +- [4.8.12.2 1. Initial data frame (host → Z-Wave Module)](04.08.12.02-1-initial-data-frame-host-z-wave-module.md) +- [4.8.12.3 2. Response data frame (Z-Wave Module → host)](04.08.12.03-2-response-data-frame-z-wave-module-host.md) +- [4.8.12.4 3. Callback data frame (Z-Wave Module → host)](04.08.12.04-3-callback-data-frame-z-wave-module-host.md) +- [4.8.13 Stop Watchdog Command](04.08.13-stop-watchdog-command.md) +- [4.8.13.1 Frame flow](04.08.13.01-frame-flow.md) +- [4.8.13.2 1. Initial data frame (host → Z-Wave Module)](04.08.13.02-1-initial-data-frame-host-z-wave-module.md) +- [4.8.13.3 2. Response data frame (Z-Wave Module → host)](04.08.13.03-2-response-data-frame-z-wave-module-host.md) +- [4.8.13.4 3. Callback data frame (Z-Wave Module → host)](04.08.13.04-3-callback-data-frame-z-wave-module-host.md) +- [4.8.14 Set Timeouts Command](04.08.14-set-timeouts-command.md) +- [4.8.14.1 Frame flow](04.08.14.01-frame-flow.md) +- [4.8.14.2 1. Initial data frame (host → Z-Wave Module)](04.08.14.02-1-initial-data-frame-host-z-wave-module.md) +- [4.8.14.3 2. Response data frame (Z-Wave Module → host)](04.08.14.03-2-response-data-frame-z-wave-module-host.md) +- [4.8.14.4 3. Callback data frame (Z-Wave Module → host)](04.08.14.04-3-callback-data-frame-z-wave-module-host.md) +- [4.8.15 Initiate Shutdown Command](04.08.15-initiate-shutdown-command.md) +- [4.8.15.1 Frame flow](04.08.15.01-frame-flow.md) +- [4.8.15.2 1. Initial data frame (host → Z-Wave Module)](04.08.15.02-1-initial-data-frame-host-z-wave-module.md) +- [4.8.15.3 2. Response data frame (Z-Wave Module → host)](04.08.15.03-2-response-data-frame-z-wave-module-host.md) +- [4.8.15.4 3. Callback data frame (Z-Wave Module → host)](04.08.15.04-3-callback-data-frame-z-wave-module-host.md) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.01-controller-node-send-data-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.01-controller-node-send-data-command.md new file mode 100644 index 0000000..33ca59f --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.01-controller-node-send-data-command.md @@ -0,0 +1,12 @@ + +# 4.9.1 Controller Node Send Data Command + +This command is used to transmit contents of a data buffer to a single node or all nodes (broadcast). The Controller Node Send Data Command Identifier is 0x13. + +[This command MUST only be supported by controller Z-Wave library types (refer to Table 4.36 ).](../04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.01.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.01.01-frame-flow.md new file mode 100644 index 0000000..c3ae48c --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.01.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.9.1.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.01.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.01.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..f717f81 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.01.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,45 @@ + +# 4.9.1.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.220](04.09.01.02-1-initial-data-frame-host-z-wave-module.md#4912-1-initial-data-frame-host-z-wave-module) + +Table 4.220: Controller Node Send Data Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x13 | | | | | | | | +| 5/(5..6) | Destination NodeID | | | | | | | | +| 6/7 | Data Length | | | | | | | | +| 7/8 | Data 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 7+N/8+N | Data N | | | | | | | | +| 8+N/9+N | Tx Options | | | | | | | | +| 9+N/10+N | Session identifier | | | | | | | | + +Destination NodeID (8/16 bits) + +This field is used to indicate the destination NodeID to send the Z-Wave Frame to. + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Data Length (8 bits) + +This field is used to indicate the length in bytes of the Data field. This field MUST be set to a value greater than 0. + +Data (N bytes) + +This field is used to advertise the data payload that MUST be transmited on the Z-Wave radio to the destination NodeID. + +The length of this field, in bytes, MUST be according to the Data Length field. Tx Options (8 bits) + +[Refer to Tx Options (8 bits) .](../04.02-generic-command-elements.md#428-tx-options-8-bits) + +[Session Identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.01.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.01.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..89ef4c4 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.01.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,21 @@ + +# 4.9.1.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.221](04.09.01.03-2-response-data-frame-z-wave-module-host.md#4913-2-response-data-frame-z-wave-module-host) + +Table 4.221: Send Data Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x13 | | | | | | | | +| 5 | Response status | | | | | | | | + +[Response status (8 bits)](../04.02-generic-command-elements.md#425-response-status-8-bits) + +[Refer to Response status (8 bits) .](../04.02-generic-command-elements.md#425-response-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.01.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.01.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..33427ec --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.01.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,35 @@ + +# 4.9.1.4 3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.222](04.09.01.04-3-callback-data-frame-z-wave-module-host.md#4914-3-callback-data-frame-z-wave-module-host) + +Table 4.222: Send Data Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x13 | | | | | | | | +| 5 | Session identifier | | | | | | | | +| 6 | Tx Status | | | | | | | | +| 7 | Tx Status Report 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 7+N | Tx Status Report N | | | | | | | | + +[Session Identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Tx Status (8 bits)](../04.02-generic-command-elements.md#423-tx-status-8-bits) + +[Refer to Tx Status (8 bits) .](../04.02-generic-command-elements.md#423-tx-status-8-bits) + +Tx Status Report (N bytes) + +This field is used to report detailed information about the Z-Wave frame transmission. This field MUST [be omitted if the Z-Wave API module is not configured to enable Tx Status Reports in the Z-Wave API Setup Set Tx Status Report Sub Command .](../04.03-z-wave-capability-api-commands/04.03.15.02-z-wave-api-setup-set-tx-status-report-sub-command.md#43152-z-wave-api-setup-set-tx-status-report-sub-command) + +[For field description, refer to Tx Status Report (N bytes) .](../04.02-generic-command-elements.md#4210-tx-status-report-n-bytes) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.02-controller-node-send-data-multicast-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.02-controller-node-send-data-multicast-command.md new file mode 100644 index 0000000..4a47ff8 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.02-controller-node-send-data-multicast-command.md @@ -0,0 +1,12 @@ + +# 4.9.2 Controller Node Send Data Multicast Command + +This command is used to transmit a data buffer to a list of Z-Wave nodes (i.e., Multicast frame). The Controller Node Send Data Multicast Command Identifier is 0x14. + +[This command MUST only be supported by Controller Z-Wave library types (refer to Table 4.36 ). Z-](../04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) [Wave API Module supporting an End Node library MUST use End Node Send Data Multicast Command](04.09.04-end-node-send-data-multicast-command.md#494-end-node-send-data-multicast-command) instead. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.02.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.02.01-frame-flow.md new file mode 100644 index 0000000..df6f0e3 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.02.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.9.2.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.02.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.02.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..4da9437 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.02.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,54 @@ + +# 4.9.2.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.223](04.09.02.02-1-initial-data-frame-host-z-wave-module.md#4922-1-initial-data-frame-host-z-wave-module) + +Table 4.223: Send Data Multicast Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x14 | | | | | | | | +| 5 | NodeID Count | | | | | | | | +| 5+1 | NodeID List 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 5+N | NodeID List N | | | | | | | | +| 6+N | Data Length | | | | | | | | +| 6+N+1 | Data 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 6+N+M | Data M | | | | | | | | +| 7+N+M | Tx Options | | | | | | | | +| 8+N+M | Session identifier | | | | | | | | + +NodeID Count (8 bits) + +This field is used to advertise the number of NodeIDs contained in the NodeID List field. + +For example, if there are 2 NodeIDs encoded in 4 bytes in the NodeID List field, this field MUST be set to 2. + +NodeID List (N bytes) + +This field is used to advertise the list of destination NodeID’s. + +Each 8 bits/16 bits groups in this field MUST represent a NodeID. + +All NodeIDs in this field MUST be encoded according to the configured NodeID base Type. Refer to [Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Data Length (8 bits) This field is used to indicate the length in bytes of the Data field. This field MUST be set to a value greater than 0. + +Data (M bytes) This field is used to advertise the data payload that MUST be transmited on the Z-Wave radio to the destination NodeIDs. + +The length of this field, in bytes, MUST be according to the Data Length field. + +Tx Options (8 bits) + +[Refer to Tx Options (8 bits) .](../04.02-generic-command-elements.md#428-tx-options-8-bits) + +Session Identifier (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.02.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.02.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..9a9b216 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.02.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,21 @@ + +# 4.9.2.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.224](04.09.02.03-2-response-data-frame-z-wave-module-host.md#4923-2-response-data-frame-z-wave-module-host) + +Table 4.224: Send Data Multicast Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x14 | | | | | | | | +| 5 | Response status | | | | | | | | + +[Response status (8 bits)](../04.02-generic-command-elements.md#425-response-status-8-bits) + +[Refer to Response status (8 bits) .](../04.02-generic-command-elements.md#425-response-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.02.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.02.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..bbabfef --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.02.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,26 @@ + +# 4.9.2.4 3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.225](04.09.02.04-3-callback-data-frame-z-wave-module-host.md#4924-3-callback-data-frame-z-wave-module-host) + +Table 4.225: Send Data Multicast Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x14 | | | | | | | | +| 5 | Session identifier | | | | | | | | +| 6 | Tx Status | | | | | | | | + +[Session Identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Tx Status (8 bits)](../04.02-generic-command-elements.md#423-tx-status-8-bits) + +[Refer to Tx Status (8 bits) .](../04.02-generic-command-elements.md#423-tx-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.03-end-node-send-data-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.03-end-node-send-data-command.md new file mode 100644 index 0000000..df83fa1 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.03-end-node-send-data-command.md @@ -0,0 +1,10 @@ + +# 4.9.3 End Node Send Data Command + +This command is used to transmit contents of a data buffer to a single node or all nodes (broadcast). The End Node Send Data Command Identifier is 0x0E. This command MUST only be supported by End [node library types (refer to Table 4.36 ).](../04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.03.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.03.01-frame-flow.md new file mode 100644 index 0000000..64690f5 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.03.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.9.3.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.03.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.03.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..377279e --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.03.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,84 @@ + +# 4.9.3.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.226](04.09.03.02-1-initial-data-frame-host-z-wave-module.md#4932-1-initial-data-frame-host-z-wave-module) + +Table 4.226: End Node Send Data Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0E | | | | | | | | +| 5/(5..6) | Destination NodeID | | | | | | | | +| 6/7 | Data Length | | | | | | | | +| 7/8 | Data 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 7/8+N | Data N | | | | | | | | +| 7/8+N | Tx Options | | | | | | | | +| 7/8+N | Tx Security Options | | | | | | | | +| 7/8+N | Security Keys | | | | | | | | +| 7/8+N | Tx Options 2 | | | | | | | | +| 7/8+N | Session identifier | | | | | | | | + +Destination NodeID (8/16 bits) + +This field is used to indicate the Destination NodeID. + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Data Length (8 bits) + +This field is used to indicate the length in bytes of the Data field. This field MUST be set to a value greater than 0. + +Data (N bytes) + +This field is used to advertise the data payload that MUST be transmited on the Z-Wave radio to the destination NodeID. + +This field MUST represent the unencrypted data payload. + +The length of this field, in bytes, MUST be according to the Data Length field. Tx Options (8 bits) + +[Refer to Tx Options (8 bits) .](../04.02-generic-command-elements.md#428-tx-options-8-bits) + +Tx Security Options (8 bits) This field is used to indicate the security 2 specific options. This field MUST be encoded according to [Table 4.227](04.09.03.02-1-initial-data-frame-host-z-wave-module.md#4932-1-initial-data-frame-host-z-wave-module) + +Table 4.227: End Node Send Data - Tx Security Options encoding + +| Value | Flag | Description | +| --- | --- | --- | +| 0x01 | S2 TXOPTION VERIFY DELIVERY. _ _ _ | This flag will activate frame de- livery verification. | +| 0x02 | S2 TXOPTION SINGLECAST FOLLOWUP. _ _ _ | This flag must be present on all single cast followup messages to a multicast transmission. | +| 0x04 | S2 TXOPTION FIRST SINGLECAST FOLLOWUP _ _ _ _ | . This flag must be present on the first, and only the first singlecast followup message in a multicast transmission. | + +Other Tx Security Options values are reserved. Reserved values MUST NOT be used and MUST be ignored by a receiving interface. + +[The Singlecast follow-up frames will reuse the Multicast GroupID received in the last End Node Send Data Multicast Command .](04.09.04-end-node-send-data-multicast-command.md#494-end-node-send-data-multicast-command) + +Security Keys (8 bits) + +This field is used to advertise the security key for the transmission. This field MUST be encoded ac- [cording to Table 4.228](04.09.03.02-1-initial-data-frame-host-z-wave-module.md#4932-1-initial-data-frame-host-z-wave-module) + +Table 4.228: End Node Send Data - Tx Security key encoding + +| Value | Flag | Description | +| --- | --- | --- | +| 0x00 | SECURITY KEY NONE. _ _ | Nonsecure transmission. | +| 0x01 | SECURITY KEY S2 UNAUTHENTICATED. _ _ _ | Use S2 Unauthenticated key. | +| 0x02 | SECURITY KEY S2 AUTHENTICATED. _ _ _ | Use S2 Authenticated key. | +| 0x03 | SECURITY KEY S2 ACCESS. _ _ _ | Use S2 Access key. | +| 0x04 | SECURITY KEY S0. _ _ | Use Security Scheme 0 key. | + +Other Tx Security key values are reserved. Reserved values MUST NOT be used and MUST be ignored by a receiving interface. + +Tx Options 2 (8 bits) + +This field is used to indicate more transmission options flags. It is reserved for future use. It MUST be set to 0x00. + +[Session Identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.03.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.03.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..e83c3cd --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.03.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,19 @@ + +# 4.9.3.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.229](04.09.03.03-2-response-data-frame-z-wave-module-host.md#4933-2-response-data-frame-z-wave-module-host) Table 4.229: End Node Send Data Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0E | | | | | | | | +| 5 | Response status | | | | | | | | + +Response status (8 bits) + +[Refer to Response status (8 bits) .](../04.02-generic-command-elements.md#425-response-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.03.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.03.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..3425df8 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.03.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,35 @@ + +# 4.9.3.4 3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.230](04.09.03.04-3-callback-data-frame-z-wave-module-host.md#4934-3-callback-data-frame-z-wave-module-host) + +Table 4.230: End Node Send Data Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0E | | | | | | | | +| 5 | Session identifier | | | | | | | | +| 6 | Tx Status | | | | | | | | +| 7 | Tx Status Report 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 7+N | Tx Status Report N | | | | | | | | + +[Session Identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Tx Status (8 bits)](../04.02-generic-command-elements.md#423-tx-status-8-bits) + +[Refer to Tx Status (8 bits) .](../04.02-generic-command-elements.md#423-tx-status-8-bits) + +Tx Status Report (N bytes) + +This field is used to report detailed information about the Z-Wave frame transmission. This field MUST [be omitted if the Z-Wave API module is not configured to enable Tx Status Reports in the Z-Wave API Setup Set Tx Status Report Sub Command .](../04.03-z-wave-capability-api-commands/04.03.15.02-z-wave-api-setup-set-tx-status-report-sub-command.md#43152-z-wave-api-setup-set-tx-status-report-sub-command) + +[For field description, refer to Tx Status Report (N bytes) .](../04.02-generic-command-elements.md#4210-tx-status-report-n-bytes) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.04-end-node-send-data-multicast-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.04-end-node-send-data-multicast-command.md new file mode 100644 index 0000000..c8d2371 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.04-end-node-send-data-multicast-command.md @@ -0,0 +1,12 @@ + +# 4.9.4 End Node Send Data Multicast Command + +This command is used to transmit a data buffer to a list of Z-Wave nodes (i.e., S2 Multicast frame). + +The End Node Send Data Multicast Command Identifier is 0x0F. This command shall only be supported [by End Node library types (refer to Table 4.36 ).](../04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.04.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.04.01-frame-flow.md new file mode 100644 index 0000000..53230cf --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.04.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.9.4.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.04.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.04.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..243f242 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.04.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,44 @@ + +# 4.9.4.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.231](04.09.04.02-1-initial-data-frame-host-z-wave-module.md#4942-1-initial-data-frame-host-z-wave-module) + +Table 4.231: End Node Send Data Multicast Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0F | | | | | | | | +| 5 | Data Length | | | | | | | | +| 6 | Data 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 6+N | Data N | | | | | | | | +| 7+N | Tx Options | | | | | | | | +| 8+N | Security Keys | | | | | | | | +| 9+N | Multicast group ID | | | | | | | | +| 10+N | Session identifier | | | | | | | | + +Data Length (8 bits) + +This field is used to indicate the length in bytes of the Data field. This field MUST be set to a value greater than 0. + +Data (N bytes) + +This field is used to advertise the data payload that MUST be transmited on the Z-Wave radio to the destination NodeIDs. + +The length of this field, in bytes, MUST be according to the Data Length field. + +Multicast group ID (8 bits) + +[This field is used to indicate the destination GroupID assigned to the current Security 2 Multicast frame.](../../05-references.md#5-references) + +[This GroupID will be used in the S2 MGRP extension. Refer to [ zwave_encapsulation_cc_spec ] for the](../../05-references.md#5-references) S2 MGRP extension. + +[Session Identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.04.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.04.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..3e88566 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.04.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,21 @@ + +# 4.9.4.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.232](04.09.04.03-2-response-data-frame-z-wave-module-host.md#4943-2-response-data-frame-z-wave-module-host) + +Table 4.232: End Node Send Data Multicast Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0F | | | | | | | | +| 5 | Response status | | | | | | | | + +Response status (8 bits) + +[Refer to Response status (8 bits) .](../04.02-generic-command-elements.md#425-response-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.04.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.04.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..85e2d6a --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.04.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,26 @@ + +# 4.9.4.4 3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.233](04.09.04.04-3-callback-data-frame-z-wave-module-host.md#4944-3-callback-data-frame-z-wave-module-host) + +Table 4.233: End Node Send Data Multicast Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x0F | | | | | | | | +| 5 | Session Identifier | | | | | | | | +| 6 | Tx Status | | | | | | | | + +[Session Identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Tx Status (8 bits)](../04.02-generic-command-elements.md#423-tx-status-8-bits) + +[Refer to Tx Status (8 bits) .](../04.02-generic-command-elements.md#423-tx-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.05-bridge-controller-node-send-data-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.05-bridge-controller-node-send-data-command.md new file mode 100644 index 0000000..9d1c829 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.05-bridge-controller-node-send-data-command.md @@ -0,0 +1,12 @@ + +# 4.9.5 Bridge Controller Node Send Data Command + +This command is used to transmit contents of a data buffer to a single node or all nodes (broadcast). The Bridge Controller Node Send Data Command Identifier is 0xA9. + +This command MUST only be supported by nodes implementing a Bridge Controller library type (refer [to Table 4.36 ).](../04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.05.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.05.01-frame-flow.md new file mode 100644 index 0000000..094ac54 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.05.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.9.5.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.05.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.05.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..4a9c013 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.05.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,57 @@ + +# 4.9.5.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.234](04.09.05.02-1-initial-data-frame-host-z-wave-module.md#4952-1-initial-data-frame-host-z-wave-module) + +Table 4.234: Bridge Controller Node Send Data Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xA9 | | | | | | | | +| 5/(5..6) | Source NodeID | | | | | | | | +| 6/(7..8) | Destination NodeID | | | | | | | | +| 7/9 | Data Length | | | | | | | | +| 8/9 | Data 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 8+N/9+N | Data N | | | | | | | | +| 9+N/10+N | Tx Options | | | | | | | | +| 10+N/11+N | Route | | | | | | | | +| 11+N/12+N | Session identifier | | | | | | | | + +Source NodeID (8 bits / 16 bits) + +[This field is used to indicate the Source NodeID from which the Z-Wave Frame must be issued.](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Setting Source NodeID to 0xFF/0xFFF will cause the protocol to automatically use the controllers native NodeID + +Destination NodeID (8 bits / 16 bits) + +This field is used to indicate the destination NodeID. + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Data Length (8 bits) This field is used to indicate the length in bytes of the Data field. This field MUST be set to a value greater than 0. + +Data (N bytes) This field is used to advertise the data payload that MUST be transmited on the Z-Wave radio to the destination NodeID. + +The length of this field, in bytes, MUST be according to the Data Length field. + +Tx Options (8 bits) + +[Refer to Tx Options (8 bits) .](../04.02-generic-command-elements.md#428-tx-options-8-bits) + +Route (4 bytes) + +This feild is used to indicate the priority route to be used for tranmiting a frame. If there are not any route, the feild MUST set to zero. + +Session identifier (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.05.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.05.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..628d9b5 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.05.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,21 @@ + +# 4.9.5.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.235](04.09.05.03-2-response-data-frame-z-wave-module-host.md#4953-2-response-data-frame-z-wave-module-host) + +Table 4.235: Bridge Controller Node Send Data Command - Re- sponse data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xA9 | | | | | | | | +| 5 | Response status | | | | | | | | + +[Response status (8 bits)](../04.02-generic-command-elements.md#425-response-status-8-bits) + +[Refer to Response status (8 bits) .](../04.02-generic-command-elements.md#425-response-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.05.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.05.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..fb4c916 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.05.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,35 @@ + +# 4.9.5.4 3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.236](04.09.05.04-3-callback-data-frame-z-wave-module-host.md#4954-3-callback-data-frame-z-wave-module-host) + +Table 4.236: Bridge Controller Node Send Data Command - Call- back data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xA9 | | | | | | | | +| 5 | Session identifier | | | | | | | | +| 6 | Tx Status | | | | | | | | +| 7 | Tx Status Report 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| 7+N | Tx Status Report N | | | | | | | | + +[Session Identifier (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Tx Status (8 bits)](../04.02-generic-command-elements.md#423-tx-status-8-bits) + +[Refer to Tx Status (8 bits) .](../04.02-generic-command-elements.md#423-tx-status-8-bits) + +Tx Status Report (N bytes) + +This field is used to report detailed information about the Z-Wave frame transmission. This field MUST [be omitted if the Z-Wave API module is not configured to enable Tx Status Reports in the Z-Wave API Setup Set Tx Status Report Sub Command .](../04.03-z-wave-capability-api-commands/04.03.15.02-z-wave-api-setup-set-tx-status-report-sub-command.md#43152-z-wave-api-setup-set-tx-status-report-sub-command) + +[For field description, refer to Tx Status Report (N bytes) .](../04.02-generic-command-elements.md#4210-tx-status-report-n-bytes) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.06-bridge-controller-node-send-data-multicast-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.06-bridge-controller-node-send-data-multicast-command.md new file mode 100644 index 0000000..e96784f --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.06-bridge-controller-node-send-data-multicast-command.md @@ -0,0 +1,12 @@ + +# 4.9.6 Bridge Controller Node Send Data Multicast Command + +This command is used to transmit a data buffer to a list of Z-Wave nodes (i.e., Multicast frame). The Bridge Controller Node Send Data Multicast Command Identifier is 0xAB. + +This command MUST only be supported by Z-Wave API Module using the Controller Bridge library [types (refer to Table 4.36 ).](../04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.06.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.06.01-frame-flow.md new file mode 100644 index 0000000..16f19e3 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.06.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.9.6.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.06.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.06.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..1ce467a --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.06.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,63 @@ + +# 4.9.6.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.237](04.09.06.02-1-initial-data-frame-host-z-wave-module.md#4962-1-initial-data-frame-host-z-wave-module) + +Table 4.237: Bridge Controller Node Send Data Multicast Com- mand - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xAB | | | | | | | | +| 5/5..6 | Source NodeID | | | | | | | | +| 6/7 | NodeID Count | | | | | | | | +| (6/7)+1 | NodeID List 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| (6/7)+N | NodeID List N | | | | | | | | +| (7/8)+N | Data Length | | | | | | | | +| (8/9)+N+1 | Data 1 | | | | | | | | +| . . . | . . . | | | | | | | | +| (8/9)+N+M | Data M | | | | | | | | +| (9/10)+N+M | Tx Options | | | | | | | | +| (10/11)+N+M | Session identifier | | | | | | | | + +Source NodeID (8/16 bits) + +[This field is used to indicate the Source NodeID from which the Z-Wave Frame MUST be issued.](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Setting Source NodeID to 0xFF/0xFFF will cause the protocol to automatically use the controllers native NodeID + +NodeID Count (8 bits) + +This field is used to advertise the number of NodeIDs contained in the NodeID List field. + +For example, if there are 2 NodeIDs encoded in 4 bytes in the NodeID List field, this field MUST be set to 2. NodeID List (N bytes) + +This field is used to advertise a list of NodeID destinations. Each 8 bits/16 bits groups in this field MUST represent a NodeID. + +All NodeIDs in this field MUST be encoded according to the configured NodeID base Type. Refer to [Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Data Length (8 bits) + +This field is used to indicate the length in bytes of the Data field. This field MUST be set to a value greater than 0. + +Data (M bytes) + +This field is used to advertise the data payload that MUST be transmited on the Z-Wave radio to the destination NodeIDs. + +The length of this field, in bytes, MUST be according to the Data Length field. + +[Tx Options (8 bits)](../04.02-generic-command-elements.md#428-tx-options-8-bits) + +[Refer to Tx Options (8 bits) .](../04.02-generic-command-elements.md#428-tx-options-8-bits) + +Session Identifier (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.06.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.06.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..5c77944 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.06.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,21 @@ + +# 4.9.6.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.238](04.09.06.03-2-response-data-frame-z-wave-module-host.md#4963-2-response-data-frame-z-wave-module-host) + +Table 4.238: Bridge Controller Node Send Data Multicast Com- mand - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xAB | | | | | | | | +| 5 | Response status | | | | | | | | + +[Response status (8 bits)](../04.02-generic-command-elements.md#425-response-status-8-bits) + +[Refer to Response status (8 bits) .](../04.02-generic-command-elements.md#425-response-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.06.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.06.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..d4e7e9a --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.06.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,26 @@ + +# 4.9.6.4 3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.239](04.09.06.04-3-callback-data-frame-z-wave-module-host.md#4964-3-callback-data-frame-z-wave-module-host) + +Table 4.239: Bridge Controller Node Send Data Multicast Com- mand - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xAB | | | | | | | | +| 5 | Session identifier | | | | | | | | + +| 6 | Tx Status | +| --- | --- | + +Session Identifier (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +Tx Status (8 bits) [Refer to Tx Status (8 bits) .](../04.02-generic-command-elements.md#423-tx-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.07-send-data-abort-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.07-send-data-abort-command.md new file mode 100644 index 0000000..eda1433 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.07-send-data-abort-command.md @@ -0,0 +1,26 @@ + +# 4.9.7 Send Data Abort Command + +This command is used to instruct the Z-Wave Module to abort an ongoing transmission started with any of the following commands: + +• [Bridge Controller Node Send Data Command](04.09.05-bridge-controller-node-send-data-command.md#495-bridge-controller-node-send-data-command) + +• [Bridge Controller Node Send Data Multicast Command](04.09.06-bridge-controller-node-send-data-multicast-command.md#496-bridge-controller-node-send-data-multicast-command) + +• [End Node Send Data Command](04.09.03-end-node-send-data-command.md#493-end-node-send-data-command) + +• [End Node Send Data Multicast Command](04.09.04-end-node-send-data-multicast-command.md#494-end-node-send-data-multicast-command) + +• [Controller Node Send Data Command](04.09.01-controller-node-send-data-command.md#491-controller-node-send-data-command) + +• [Controller Node Send Data Multicast Command](04.09.02-controller-node-send-data-multicast-command.md#492-controller-node-send-data-multicast-command) + +• Send NOP Command + +The Send Data Abort Command Identifier is 0x16. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.07.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.07.01-frame-flow.md new file mode 100644 index 0000000..b510565 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.07.01-frame-flow.md @@ -0,0 +1,14 @@ + +# 4.9.7.1 Frame flow + +[The frame flow for this command is an Acknowledged frame .](../../03-interface-communication/03.03-command-frame-flows.md#332-acknowledged-frame) + +If a host application aborts an ongoing transmission, the Z-Wave API Module MUST still issue a 3. [callback data frame for the ongoing transmission. This is illustrated in Figure 4.21 . A Z-Wave API](04.09.07.01-frame-flow.md#4971-frame-flow) Module MUST ignore this command if it is received when no transmission is ongoing. + +![Figure 4.21: Send Data Abort Command Example](assets/img-822d78b6e6.png) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.07.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.07.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..35f8d50 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.07.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,16 @@ + +# 4.9.7.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.240](04.09.07.02-1-initial-data-frame-host-z-wave-module.md#4972-1-initial-data-frame-host-z-wave-module) + +[Table 4.240: Send Data Abort Command - Initial data frame](04.09.07.02-1-initial-data-frame-host-z-wave-module.md#4972-1-initial-data-frame-host-z-wave-module) + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x16 | | | | | | | | diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.07.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.07.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..38a07ba --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.07.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.9.7.3 2. Response data frame (Z-Wave Module → host) + +None diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.07.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.07.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..d699605 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.07.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,10 @@ + +# 4.9.7.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.08-send-test-frame-command.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.08-send-test-frame-command.md new file mode 100644 index 0000000..9da0d39 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.08-send-test-frame-command.md @@ -0,0 +1,12 @@ + +# 4.9.8 Send Test Frame Command + +This command is used to send a test frame directly to a given node without any routing. The Send Test Frame Command Identifier is 0xBE. + +Note that this command shall only be used during installation and testing the wireless communication link path. And the test will be done using 9600 kbit/s transmission rate. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.08.01-frame-flow.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.08.01-frame-flow.md new file mode 100644 index 0000000..3df29d6 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.08.01-frame-flow.md @@ -0,0 +1,10 @@ + +# 4.9.8.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response and callback .](../../03-interface-communication/03.03-command-frame-flows.md#335-acknowledged-frame-with-response-and-callback) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.08.02-1-initial-data-frame-host-z-wave-module.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.08.02-1-initial-data-frame-host-z-wave-module.md new file mode 100644 index 0000000..ca96714 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.08.02-1-initial-data-frame-host-z-wave-module.md @@ -0,0 +1,33 @@ + +# 4.9.8.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.241 .](04.09.08.02-1-initial-data-frame-host-z-wave-module.md#4982-1-initial-data-frame-host-z-wave-module) + +Table 4.241: Send Test Frame Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xBE | | | | | | | | +| 5/5..6 | NodeID | | | | | | | | +| 6/7 | Powerlevel | | | | | | | | +| 7/8 | Session identifier | | | | | | | | + +NodeID (8/16 bits) + +[This field is used to advertise the NodeID of the node where the test frame is sent to.](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +[This field MUST be encoded according to the configured NodeID base Type. Refer to Z-Wave API Setup Set NodeID Base Type Sub Command and Table 4.64 .](../04.03-z-wave-capability-api-commands/04.03.15.09-z-wave-api-setup-set-nodeid-base-type-sub-command.md#43159-z-wave-api-setup-set-nodeid-base-type-sub-command) + +Powerlevel (8 bits) + +This field is used to advertise the power level which the Z-Wave module shall use for the RF transmission of [the test frame. This field MUST comply with the format indicated in Set RF Power Level Command](../04.08-z-wave-api-miscellaneous-commands/04.08.09-set-rf-power-level-command.md#489-set-rf-power-level-command) initial data frame section. + +[Session identifer (8 bits)](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.08.03-2-response-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.08.03-2-response-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..2bfa346 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.08.03-2-response-data-frame-z-wave-module-host.md @@ -0,0 +1,21 @@ + +# 4.9.8.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.242 when the Send](04.09.08.03-2-response-data-frame-z-wave-module-host.md#4983-2-response-data-frame-z-wave-module-host) Test Frame Command data is received by the Z-Wave Module. + +Table 4.242: Send Test Frame Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | + +| 4 | Z-Wave API Command ID = 0xBE | +| --- | --- | +| 5 | Response status | + +Response status (8 bits) [Refer to Response status (8 bits) .](../04.02-generic-command-elements.md#425-response-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.08.04-3-callback-data-frame-z-wave-module-host.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.08.04-3-callback-data-frame-z-wave-module-host.md new file mode 100644 index 0000000..f2f4710 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/04.09.08.04-3-callback-data-frame-z-wave-module-host.md @@ -0,0 +1,26 @@ + +# 4.9.8.4 3. Callback data frame (Z-Wave Module → host) + +[A Z-Wave module MUST issue a callback frame formatted according to Table 4.243 when the transmis-](04.09.08.04-3-callback-data-frame-z-wave-module-host.md#4984-3-callback-data-frame-z-wave-module-host) sion of the test frame is executed. + +Table 4.243: Send Test Frame Command - Callback data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0xBE | | | | | | | | +| 5 | Session identifier | | | | | | | | +| 6 | Tx Status | | | | | | | | + +Session identifer (8 bits) + +[Refer to Session identifier (8 bits) .](../04.02-generic-command-elements.md#421-session-identifier-8-bits) + +Tx Status (8 bits) + +[Refer to Tx Status (8 bits) .](../04.02-generic-command-elements.md#423-tx-status-8-bits) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/index.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/index.md new file mode 100644 index 0000000..f9b8bde --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.09-z-wave-api-transport-commands/index.md @@ -0,0 +1,53 @@ + +# 4.9 Z-Wave API Transport Commands + +[This section describes Z-Wave API Commands that are used to perform transport operations.](../index.md#4-z-wave-api-commands) + +## Contents + +- [4.9.1 Controller Node Send Data Command](04.09.01-controller-node-send-data-command.md) +- [4.9.1.1 Frame flow](04.09.01.01-frame-flow.md) +- [4.9.1.2 1. Initial data frame (host → Z-Wave Module)](04.09.01.02-1-initial-data-frame-host-z-wave-module.md) +- [4.9.1.3 2. Response data frame (Z-Wave Module → host)](04.09.01.03-2-response-data-frame-z-wave-module-host.md) +- [4.9.1.4 3. Callback data frame (Z-Wave Module → host)](04.09.01.04-3-callback-data-frame-z-wave-module-host.md) +- [4.9.2 Controller Node Send Data Multicast Command](04.09.02-controller-node-send-data-multicast-command.md) +- [4.9.2.1 Frame flow](04.09.02.01-frame-flow.md) +- [4.9.2.2 1. Initial data frame (host → Z-Wave Module)](04.09.02.02-1-initial-data-frame-host-z-wave-module.md) +- [4.9.2.3 2. Response data frame (Z-Wave Module → host)](04.09.02.03-2-response-data-frame-z-wave-module-host.md) +- [4.9.2.4 3. Callback data frame (Z-Wave Module → host)](04.09.02.04-3-callback-data-frame-z-wave-module-host.md) +- [4.9.3 End Node Send Data Command](04.09.03-end-node-send-data-command.md) +- [4.9.3.1 Frame flow](04.09.03.01-frame-flow.md) +- [4.9.3.2 1. Initial data frame (host → Z-Wave Module)](04.09.03.02-1-initial-data-frame-host-z-wave-module.md) +- [4.9.3.3 2. Response data frame (Z-Wave Module → host)](04.09.03.03-2-response-data-frame-z-wave-module-host.md) +- [4.9.3.4 3. Callback data frame (Z-Wave Module → host)](04.09.03.04-3-callback-data-frame-z-wave-module-host.md) +- [4.9.4 End Node Send Data Multicast Command](04.09.04-end-node-send-data-multicast-command.md) +- [4.9.4.1 Frame flow](04.09.04.01-frame-flow.md) +- [4.9.4.2 1. Initial data frame (host → Z-Wave Module)](04.09.04.02-1-initial-data-frame-host-z-wave-module.md) +- [4.9.4.3 2. Response data frame (Z-Wave Module → host)](04.09.04.03-2-response-data-frame-z-wave-module-host.md) +- [4.9.4.4 3. Callback data frame (Z-Wave Module → host)](04.09.04.04-3-callback-data-frame-z-wave-module-host.md) +- [4.9.5 Bridge Controller Node Send Data Command](04.09.05-bridge-controller-node-send-data-command.md) +- [4.9.5.1 Frame flow](04.09.05.01-frame-flow.md) +- [4.9.5.2 1. Initial data frame (host → Z-Wave Module)](04.09.05.02-1-initial-data-frame-host-z-wave-module.md) +- [4.9.5.3 2. Response data frame (Z-Wave Module → host)](04.09.05.03-2-response-data-frame-z-wave-module-host.md) +- [4.9.5.4 3. Callback data frame (Z-Wave Module → host)](04.09.05.04-3-callback-data-frame-z-wave-module-host.md) +- [4.9.6 Bridge Controller Node Send Data Multicast Command](04.09.06-bridge-controller-node-send-data-multicast-command.md) +- [4.9.6.1 Frame flow](04.09.06.01-frame-flow.md) +- [4.9.6.2 1. Initial data frame (host → Z-Wave Module)](04.09.06.02-1-initial-data-frame-host-z-wave-module.md) +- [4.9.6.3 2. Response data frame (Z-Wave Module → host)](04.09.06.03-2-response-data-frame-z-wave-module-host.md) +- [4.9.6.4 3. Callback data frame (Z-Wave Module → host)](04.09.06.04-3-callback-data-frame-z-wave-module-host.md) +- [4.9.7 Send Data Abort Command](04.09.07-send-data-abort-command.md) +- [4.9.7.1 Frame flow](04.09.07.01-frame-flow.md) +- [4.9.7.2 1. Initial data frame (host → Z-Wave Module)](04.09.07.02-1-initial-data-frame-host-z-wave-module.md) +- [4.9.7.3 2. Response data frame (Z-Wave Module → host)](04.09.07.03-2-response-data-frame-z-wave-module-host.md) +- [4.9.7.4 3. Callback data frame (Z-Wave Module → host)](04.09.07.04-3-callback-data-frame-z-wave-module-host.md) +- [4.9.8 Send Test Frame Command](04.09.08-send-test-frame-command.md) +- [4.9.8.1 Frame flow](04.09.08.01-frame-flow.md) +- [4.9.8.2 1. Initial data frame (host → Z-Wave Module)](04.09.08.02-1-initial-data-frame-host-z-wave-module.md) +- [4.9.8.3 2. Response data frame (Z-Wave Module → host)](04.09.08.03-2-response-data-frame-z-wave-module-host.md) +- [4.9.8.4 3. Callback data frame (Z-Wave Module → host)](04.09.08.04-3-callback-data-frame-z-wave-module-host.md) diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.10-z-wave-api-security-commands.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.10-z-wave-api-security-commands.md new file mode 100644 index 0000000..74ac641 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/04.10-z-wave-api-security-commands.md @@ -0,0 +1,175 @@ + +# 4.10 Z-Wave API Security Commands + +[This section describes Z-Wave API Commands that are used to perform security bootstrapping opera-](index.md#4-z-wave-api-commands) tions. + +## 4.10.1 Security Setup Command + +This command is used to set the Requested Security Keys and Requested Authentication method prior to inclusion (add). The Requested Security Keys and Authentication is requested by the protocol during S2 inclusion. The Security Setup Command Identifier is 0x9C. + +This command MUST only be supported by Z-Wave API Module implementing an End Node library type (e.g. End Node library, Enhanced 232 End Node Library* or Routing End Node library). Refer to [Table 4.36 ).](04.03-z-wave-capability-api-commands/04.03.10.03-2-response-data-frame-z-wave-module-host.md#43103-2-response-data-frame-z-wave-module-host) + +## 4.10.1.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +## 4.10.1.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.244 .](04.10-z-wave-api-security-commands.md#41012-1-initial-data-frame-host-z-wave-module) + +Table 4.244: Security Setup Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x9C | | | | | | | | +| 5 | Security Mode | | | | | | | | +| 6 | Parameter Length | | | | | | | | +| 7 | Parameter 1 | | | | | | | | +| .. | . . . | | | | | | | | +| 7+N | Parameter N | | | | | | | | + +Security Mode (8 bits) + +This field is used to indicate the mode that represents the requested security functionalities. This field [MUST be encoded according to Table 4.245](04.10-z-wave-api-security-commands.md#41012-1-initial-data-frame-host-z-wave-module) Table 4.245: The security mode value encoding + +| Value | Identifier and description | +| --- | --- | +| 0x00 | GET SECURITY KEYS _ _ This value used to request the security keys. If this value is used, the Security Setup Command - Initial data frame MUST NOT contain Parameter Length and Parameter fields. | +| 0x01 | Obsoleted This value is obsoleted and MUST NOT be used. | + +| | 0x02 | GET SECURITY 2 PUBLIC DSK _ _ _ _ This value is used to request the public DSK. If this value is used the Security Setup Command - Initial data frame MUST NOT contain Parameter Length* and Parameter fields. | | +| --- | --- | --- | --- | +| | 0x03..0x04 | Obsoleted These values are obsoleted and MUST NOT be used. | | +| | 0x05 | SET SECURITY INCLUSION REQUESTED KEYS _ _ _ _ This value is used to set Requested Security Inclusion Keys. | | +| | 0x06 | Obsoleted This value is obsoleted and MUST NOT be used. | | +| | 0x07..0xFD | Reserved These values are reserved and MUST NOT be used. | | +| | 0xFE | GET SECURITY CAPABILITIES _ _ This value is used to request the supported Security Modes values by the Z-Wave API Module. | | + +Parameter Length (8 bits) + +This field is used to indicate the length in bytes of the Parameter field. This field MUST be set to a value greater than 0. + +Parameter (N bytes) + +This field is used to advertise additional parameters required for the value specified in the Security Mode field. The length of this field, in bytes, MUST be according to the Parameter Length field. This field [MUST be encoded according to Table 4.246](04.10-z-wave-api-security-commands.md#41012-1-initial-data-frame-host-z-wave-module) Table 4.246: Security Setup Command - Initial Frame Parameter Field Encoding + +| Security Mode field | Parameter field | +| --- | --- | +| 0x00 Get Security Keys | Omitted. | +| 0x01 Obsoleted | This value is obsoleted and MUST NOT be used. | +| 0x02 Get Security 2 Authenti- cated Learn Mode DSK | Omitted. | +| 0x03..0x04 Obsoleted | These values are obsoleted and MUST NOT be used. | +| 0x05 Set requested network keys | The Parameter field MUST contain Requested Security Classes dur- ing Security Bootstrapping. | +| 0x06 Obsoleted | This value is obsoleted and MUST NOT be used. | +| 0x07..0xFD Reserved | These values are reserved and MUST NOT be used. | +| 0xFE Get Security Capabilities | Omitted. | + +| | 0xFF Unknown Security Modes | N/A This value MUST only be used by a Z-Wave API Module in a 2. Re- sponse data frame in order to indicate that the received Security Mode in the 1. Initial data frame is unknown or not supported | | +| --- | --- | --- | --- | + +## 4.10.1.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.247 .](04.10-z-wave-api-security-commands.md#41013-2-response-data-frame-z-wave-module-host) + +Table 4.247: Security Setup Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x9C | | | | | | | | +| 5 | Security Mode | | | | | | | | +| 6 | Parameter Length | | | | | | | | +| 7 | Parameter 1 | | | | | | | | +| .. | . . . | | | | | | | | +| 7+N | Parameter N | | | | | | | | + +Refer Security Setup Command - Initial data frame field descriptions for the fields that are not described below. + +Parameter (N bytes) + +This field is used to advertise parameters corresponds to the security mode flag used in Security Mode field. The length of this field, in bytes, MUST be according to the Parameter Length field. This field [MUST be encoded according to Table 4.248](04.10-z-wave-api-security-commands.md#41013-2-response-data-frame-z-wave-module-host) Table 4.248: Security Setup Command Response Frame Parameter Field Encoding + +| Security Mode field | Parameter field | +| --- | --- | +| 0x00 Get Security Keys | The Parameter field MUST contain the bitmask that represents the security keys the Z-Wave module poses. The bitmask field MUST be encoded according to Table 4.249 | +| 0x01 Obsoleted. | This value is obsoleted and MUST NOT be used. | +| 0x02 Get Security 2 Authenti- cated Learn Mode DSK | The Parameter field MUST describe if the Security 2 DSK. (De- rived from the Learn Mode Authenticated ECDH key pair) Refer to [zwave encapsulation cc spec] for details about the DSK. _ _ _ | +| 0x03 Obsoleted | This value is obsoleted and MUST NOT be used. | +| 0x04 Obsoleted | This value is obsoleted and MUST NOT be used. | +| 0x05 Set requested network keys | The Parameter field MUST describe if the Requested Security Inclu- sion Keys is accepted or not via the Z-Wave module. The field MUST be encoded according to Command Status (8 bits). | +| 0x06 Obsoleted | This value is obsoleted and MUST NOT be used. | + +| 0x07..0xFD Reserved | These values are reserved and MUST NOT be used. | +| --- | --- | +| 0xFE Get Security Capabilities | The Parameter field MUST be encoded as a bitmask representing the supported Security Modes. • Bit 0 in Byte 1 MUST represent mode 0x00 • Bit 1 in Byte 1 MUST represent mode 0x01 • Bit 2 in Byte 1 MUST represent mode 0x02 • etc. A bit set to 1 MUST indicate that the corresponding Security Mode is supported. A bit set to 0 MUST indicate that the corresponding Security Mode is not supported. The field MUST be encoded according to Command Status (8 bits). | +| 0xFF Unknown Security Modes | The Parameter field MUST be set to the unknown / unsupported Se- curity Mode value that was received in the 1. Initial data frame. | + +Table 4.249: The security keys bitmask value encoding + +| Bit mask | Flag and description | +| --- | --- | +| 0x00 | SECURITY KEY NONE MASK _ _ _ No network key. | +| 0x01 | SECURITY KEY S2 UNAUTHENTICATED BIT _ _ _ _ S2 Unauthenticated network key. | +| 0x02 | SECURITY KEY S2 AUTHENTICATED BIT _ _ _ _ S2 Authenticated network key. | +| 0x04 | SECURITY KEY S2 ACCESS BIT _ _ _ _ S2 Access Control network key. | +| 0x80 | SECURITY KEY S0 BIT _ _ _ Security 0 network key. | + +## 4.9.1.1 3. Callback data frame (Z-Wave Module → host) + +None. + +## 4.9.2 Encrypt Data With AES Command + +This command is used to request the Z-Wave API module to encrypt a Z-Wave frame payload using AES-128 Electronic CookBook mode. The Encrypt Data With AES Command Identifier is 0x67. + +## 4.9.2.1 Frame flow + +[The frame flow for this command is an Acknowledged frame with response .](../03-interface-communication/03.03-command-frame-flows.md#333-acknowledged-frame-with-response) + +## 4.9.2.2 1. Initial data frame (host → Z-Wave Module) + +[The initial data frame MUST be formatted according to Table 4.250 .](04.10-z-wave-api-security-commands.md#4922-1-initial-data-frame-host-z-wave-module) + +Table 4.250: Encrypt Data With AES Command - Initial data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x67 | | | | | | | | +| 5 | Keys 1 | | | | | | | | +| .. | . . . | | | | | | | | +| 20 | keys 16 | | | | | | | | +| 21 | Input Data 1 | | | | | | | | +| .. | . . . | | | | | | | | +| 36 | Input Data 16 | | | | | | | | + +Keys (16 bytes) + +This field is used to advertise the encryption key. + +Input Data (16 bytes) + +This field is used to indicate the data to be encrypted. + +## 4.9.2.3 2. Response data frame (Z-Wave Module → host) + +[A Z-Wave module MUST return a response frame formatted according to Table 4.251 .](04.10-z-wave-api-security-commands.md#4923-2-response-data-frame-z-wave-module-host) + +Table 4.251: Encrypt Data With AES Command - Response data frame + +| byte\bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 4 | Z-Wave API Command ID = 0x67 | | | | | | | | +| 5 | Output Data 1 | | | | | | | | +| .. | . . . | | | | | | | | +| 20 | Output Data 16 | | | | | | | | + +Output Data (16 bytes) This field is used to advertise the encrypted data. + +## 4.9.2.4 3. Callback data frame (Z-Wave Module → host) + +None. diff --git a/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/index.md b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/index.md new file mode 100644 index 0000000..f34cc79 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/04-z-wave-api-commands/index.md @@ -0,0 +1,65 @@ + +# 4 Z-Wave API Commands + +This section lists all defined Z-Wave API commands. Note that all commands are not always supported by a Z-Wave API Module. + +[The Command format details common features and fields shared among several commands.](04.01-command-format.md#41-command-format) + +The subsequent sections are grouping the Z-Wave API Commands in categories. + +• [Z-Wave Capability API commands :](04.03-z-wave-capability-api-commands/index.md#43-z-wave-capability-api-commands) + +This subsection groups all the Z-Wave API commands to read the Z-Wave API Module capabili- ties and perform initialization and setup. + +• [Z-Wave API Network Management Commands :](04.04-z-wave-api-network-management-commands/index.md#44-z-wave-api-network-management-commands) + +This subsection groups all the Z-Wave API commands allowing to perform Network Management [operations. Most of these operations are defined in [ zwave_nwk_spec ] for details. It is split into](../05-references.md#5-references) 3 subsubsections: + +– [Commands available for all nodes: Common Network Management Commands](04.04-z-wave-api-network-management-commands/04.04.01-common-network-management-commands.md#441-common-network-management-commands) + +– [Commands for controller nodes only: Controller Nodes Network Management](04.04-z-wave-api-network-management-commands/04.04.03-controller-nodes-network-management.md#443-controller-nodes-network-management) + +[–](04.09-z-wave-api-transport-commands/index.md#49-z-wave-api-transport-commands) [Commands for end nodes only: End Nodes Network Management](04.04-z-wave-api-network-management-commands/04.04.02-end-nodes-network-management.md#442-end-nodes-network-management) + +• [Z-Wave API Transport Commands :](04.09-z-wave-api-transport-commands/index.md#49-z-wave-api-transport-commands) + +This subsection groups all the Z-Wave API commands that can be used to transmit application payloads. + +• [Z-Wave API Firmware Update Commands :](04.06-z-wave-api-firmware-update-commands.md#46-z-wave-api-firmware-update-commands) + +This subsection groups all the Z-Wave API commands that can be used to read and write the firmware of the Z-Wave API module. + +• [Z-Wave API Security Commands :](04.10-z-wave-api-security-commands.md#410-z-wave-api-security-commands) + +This subsection groups all the Z-Wave API commands related to security functionalities provided by the Z-Wave API Module. + +• [Z-Wave API Memory Commands :](04.05-z-wave-api-memory-commands.md#45-z-wave-api-memory-commands) + +This subsection groups all the Z-Wave API commands that can be used to read data that has been saved by the Z-Wave API Module in its persistent memory. + +• [Unsolicited Z-Wave API commands :](04.07-unsolicited-z-wave-api-commands.md#47-unsolicited-z-wave-api-commands) + +[This subsection groups all the Z-Wave API commands that are sent as unsolicited frames (refer to Data Frame and](../03-interface-communication/03.02-frame-types.md#321-data-frame) [Unsolicited frame ) by the Z-Wave API Module.](../03-interface-communication/03.03-command-frame-flows.md#336-unsolicited-frame) + +• [Z-Wave API Miscellaneous Commands :](04.08-z-wave-api-miscellaneous-commands/index.md#48-z-wave-api-miscellaneous-commands) + +This subsection groups all the Z-Wave API commands that do not fit in any of the other categories. + +## Contents + +- [4.1 Command format](04.01-command-format.md) +- [4.2 Generic command elements](04.02-generic-command-elements.md) +- [4.3 Z-Wave Capability API commands](04.03-z-wave-capability-api-commands/index.md) +- [4.4 Z-Wave API Network Management Commands](04.04-z-wave-api-network-management-commands/index.md) +- [4.5 Z-Wave API Memory Commands](04.05-z-wave-api-memory-commands.md) +- [4.6 Z-Wave API Firmware Update Commands](04.06-z-wave-api-firmware-update-commands.md) +- [4.7 Unsolicited Z-Wave API commands](04.07-unsolicited-z-wave-api-commands.md) +- [4.8 Z-Wave API Miscellaneous Commands](04.08-z-wave-api-miscellaneous-commands/index.md) +- [4.9 Z-Wave API Transport Commands](04.09-z-wave-api-transport-commands/index.md) +- [4.10 Z-Wave API Security Commands](04.10-z-wave-api-security-commands.md) diff --git a/docs/specs/zwave-host-api-specification/05-references.md b/docs/specs/zwave-host-api-specification/05-references.md new file mode 100644 index 0000000..a3f5d13 --- /dev/null +++ b/docs/specs/zwave-host-api-specification/05-references.md @@ -0,0 +1,17 @@ + +# 5 References + +| [device type spec v2] | Z-Wave Alliance, Z-Wave Plus v2 Device Type Specification | +| --- | --- | +| _ _ _ [device type spec] | Z-Wave Alliance, Z-Wave Plus Device Type Specification | +| _ _ [device class spec] | Z-Wave Alliance, Z-Wave Device Class Specification | +| _ _ [zwave nwk spec] _ _ | Z-Wave Alliance, ZWA Z-Wave and Z-Wave Long Range _ Network Layer Specifi- cation SPE | +| [zwave manufacturer ids] | _ Z-Wave Alliance, List of defined Manufacturer IDs | +| _ _ [zwave management cc spec] _ _ _ | Z-Wave Alliance, Z-Wave Management Command Class Specification | +| [zwave encapsulation cc spec] _ _ _ | Z-Wave Alliance, Z-Wave Transport-Encapsulation Command Class Specification | diff --git a/docs/specs/zwave-host-api-specification/assets/img-1758be6e77.png b/docs/specs/zwave-host-api-specification/assets/img-1758be6e77.png new file mode 100644 index 0000000..40e32cc Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-1758be6e77.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-1c1d0e8a10.png b/docs/specs/zwave-host-api-specification/assets/img-1c1d0e8a10.png new file mode 100644 index 0000000..28cc342 Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-1c1d0e8a10.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-235bf0f9d5.png b/docs/specs/zwave-host-api-specification/assets/img-235bf0f9d5.png new file mode 100644 index 0000000..572d2e4 Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-235bf0f9d5.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-3662dedfb5.png b/docs/specs/zwave-host-api-specification/assets/img-3662dedfb5.png new file mode 100644 index 0000000..e43c285 Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-3662dedfb5.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-37140f1865.png b/docs/specs/zwave-host-api-specification/assets/img-37140f1865.png new file mode 100644 index 0000000..1a24dcd Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-37140f1865.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-404dc40fa3.png b/docs/specs/zwave-host-api-specification/assets/img-404dc40fa3.png new file mode 100644 index 0000000..7d61490 Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-404dc40fa3.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-54e22386da.png b/docs/specs/zwave-host-api-specification/assets/img-54e22386da.png new file mode 100644 index 0000000..459b12b Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-54e22386da.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-556a6b8e9e.png b/docs/specs/zwave-host-api-specification/assets/img-556a6b8e9e.png new file mode 100644 index 0000000..8d60e45 Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-556a6b8e9e.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-587ad5ef6a.png b/docs/specs/zwave-host-api-specification/assets/img-587ad5ef6a.png new file mode 100644 index 0000000..1090263 Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-587ad5ef6a.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-61cdc0dbcd.png b/docs/specs/zwave-host-api-specification/assets/img-61cdc0dbcd.png new file mode 100644 index 0000000..244cca5 Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-61cdc0dbcd.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-61f2baadba.png b/docs/specs/zwave-host-api-specification/assets/img-61f2baadba.png new file mode 100644 index 0000000..5d6097d Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-61f2baadba.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-6bf1dd3f94.png b/docs/specs/zwave-host-api-specification/assets/img-6bf1dd3f94.png new file mode 100644 index 0000000..6f82ad1 Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-6bf1dd3f94.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-6f86d7178e.png b/docs/specs/zwave-host-api-specification/assets/img-6f86d7178e.png new file mode 100644 index 0000000..61778ff Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-6f86d7178e.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-81e1157643.png b/docs/specs/zwave-host-api-specification/assets/img-81e1157643.png new file mode 100644 index 0000000..493d37b Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-81e1157643.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-822d78b6e6.png b/docs/specs/zwave-host-api-specification/assets/img-822d78b6e6.png new file mode 100644 index 0000000..5997164 Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-822d78b6e6.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-875c4ec825.png b/docs/specs/zwave-host-api-specification/assets/img-875c4ec825.png new file mode 100644 index 0000000..78c5cd2 Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-875c4ec825.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-8eb49a5e62.png b/docs/specs/zwave-host-api-specification/assets/img-8eb49a5e62.png new file mode 100644 index 0000000..867ce12 Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-8eb49a5e62.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-8faf52e1c6.png b/docs/specs/zwave-host-api-specification/assets/img-8faf52e1c6.png new file mode 100644 index 0000000..aaffc5c Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-8faf52e1c6.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-94bdf55e26.png b/docs/specs/zwave-host-api-specification/assets/img-94bdf55e26.png new file mode 100644 index 0000000..52c49df Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-94bdf55e26.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-97e08b257c.png b/docs/specs/zwave-host-api-specification/assets/img-97e08b257c.png new file mode 100644 index 0000000..53b755c Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-97e08b257c.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-aef129fd85.png b/docs/specs/zwave-host-api-specification/assets/img-aef129fd85.png new file mode 100644 index 0000000..1374636 Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-aef129fd85.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-b5c6569539.png b/docs/specs/zwave-host-api-specification/assets/img-b5c6569539.png new file mode 100644 index 0000000..628d17b Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-b5c6569539.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-bc3d7ce577.png b/docs/specs/zwave-host-api-specification/assets/img-bc3d7ce577.png new file mode 100644 index 0000000..26bf40c Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-bc3d7ce577.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-c06357978d.png b/docs/specs/zwave-host-api-specification/assets/img-c06357978d.png new file mode 100644 index 0000000..0ef8b01 Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-c06357978d.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-c1c5f5444f.png b/docs/specs/zwave-host-api-specification/assets/img-c1c5f5444f.png new file mode 100644 index 0000000..528ddbd Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-c1c5f5444f.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-c666cce873.png b/docs/specs/zwave-host-api-specification/assets/img-c666cce873.png new file mode 100644 index 0000000..d7f98eb Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-c666cce873.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-c778299cc1.png b/docs/specs/zwave-host-api-specification/assets/img-c778299cc1.png new file mode 100644 index 0000000..7ba9582 Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-c778299cc1.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-d946ff712a.png b/docs/specs/zwave-host-api-specification/assets/img-d946ff712a.png new file mode 100644 index 0000000..7b84ddb Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-d946ff712a.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-df71f5c43a.png b/docs/specs/zwave-host-api-specification/assets/img-df71f5c43a.png new file mode 100644 index 0000000..3d556b5 Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-df71f5c43a.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-e76bf6450b.png b/docs/specs/zwave-host-api-specification/assets/img-e76bf6450b.png new file mode 100644 index 0000000..df18776 Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-e76bf6450b.png differ diff --git a/docs/specs/zwave-host-api-specification/assets/img-e8d90d038c.png b/docs/specs/zwave-host-api-specification/assets/img-e8d90d038c.png new file mode 100644 index 0000000..8ebfac4 Binary files /dev/null and b/docs/specs/zwave-host-api-specification/assets/img-e8d90d038c.png differ diff --git a/docs/specs/zwave-host-api-specification/index.md b/docs/specs/zwave-host-api-specification/index.md new file mode 100644 index 0000000..11b5caf --- /dev/null +++ b/docs/specs/zwave-host-api-specification/index.md @@ -0,0 +1,21 @@ + + +# Z-Wave Host API Specification + +*Source:* [Z-Wave Host API Specification.pdf](../sources/Z-Wave Host API Specification.pdf) +*Version:* 0.7.2 +*Pages:* 263 +*Generated by:* `tools/pdf2md/convert.py` (PyMuPDF 1.27.1) + + +## Chapters + +- [1 Introduction](01-introduction/index.md) +- [2 Overview](02-overview.md) +- [3 Interface communication](03-interface-communication/index.md) +- [4 Z-Wave API Commands](04-z-wave-api-commands/index.md) +- [5 References](05-references.md) diff --git a/tools/pdf2md/README.md b/tools/pdf2md/README.md new file mode 100644 index 0000000..cc3f402 --- /dev/null +++ b/tools/pdf2md/README.md @@ -0,0 +1,57 @@ +# pdf2md — Z-Wave spec PDF → Markdown + +Converts a Z-Wave Alliance specification PDF into a tree of small, topic-scoped +Markdown files with per-directory `index.md` pages, designed for progressive +disclosure (easy navigation for humans and AI agents). + +## Requirements + +- Python 3.10+ +- PyMuPDF — `pip install -r requirements.txt` +- Git LFS only matters for *storing* the source PDFs, not for running this tool. + +## Usage + +Convert a single PDF: + +```powershell +python convert.py -o docs/specs -s +``` + +Convert all three Z-Wave specs (the default workflow): + +```powershell +pwsh convert.ps1 +``` + +Options: + +| Flag | Default | Meaning | +| --- | --- | --- | +| `-o / --out` | `docs/specs` | Output root directory | +| `-s / --slug` | derived from filename | Output folder name | +| `--max-pages` | `15` | Split a section into its own files when it spans more pages than this | +| `--max-chars` | `60000` | Split a section when its text exceeds this many characters | +| `--no-images` | off | Skip extracting figures | + +## How it works + +1. Reads the PDF **outline** (bookmarks) as the section tree. +2. Rebuilds **visual lines** per page (spans sharing a y are merged, so a heading + whose number and title are separate objects becomes one line). +3. Binds each *numbered* bookmark to its real heading line. Non-numbered bookmarks + (field / table-row anchors in the frame-format tables) are not headings. +4. Detects **tables** (`find_tables`) and **figures** (embedded images, deduped). +5. Splits the section tree into size-bounded files. +6. Emits each file, resolving **internal links** to a concrete `file.md#anchor` + and keeping **external links** as-is. + +## Output conventions + +- A section becomes a **directory + `index.md`** when it has subsections and + exceeds the size bound; otherwise it is a single `.md` file. +- Heading depth maps to `#`..`####`. +- Every generated file has a leading HTML comment with provenance: + `generated-by`, `pymupdf` version, `source`, `section`, and `pages`. +- The top-level `index.md` links back to the source PDF in `../sources/`. +- Filenames use zero-padded section numbers (`04.01-...`) so they sort in order. diff --git a/tools/pdf2md/convert.ps1 b/tools/pdf2md/convert.ps1 new file mode 100644 index 0000000..04f1d70 --- /dev/null +++ b/tools/pdf2md/convert.ps1 @@ -0,0 +1,39 @@ +# Requires Python 3.10+ and PyMuPDF (see requirements.txt). +# Reads every listed source PDF and writes the matching folder under docs/specs. +# Re-running is idempotent: each output folder is regenerated from scratch. + +param( + [int]$MaxPages = 15, + [int]$MaxChars = 60000 +) + +$ErrorActionPreference = "Stop" +$env:PYTHONIOENCODING = "utf-8" + +$root = Split-Path -Parent (Split-Path -Parent -Path $PSScriptRoot) +$Sources = Join-Path $root "docs/specs/sources" +$Out = Join-Path $root "docs/specs" +$Convert = Join-Path $PSScriptRoot "convert.py" + +if (-not (Get-Command python -ErrorAction SilentlyContinue)) { + throw "Python was not found on PATH. Install Python 3.10+ and 'pip install -r $PSScriptRoot\requirements.txt'." +} + +# source filename -> output folder name. +$Docs = [ordered]@{ + "INS13954-Instruction-Z-Wave-500-Series-Appl-Programmers-Guide-v6_8x_0x.pdf" = "zwave-500-series-programmers-guide" + "SDS13781-4 Z-Wave Application Command Class Specification.pdf" = "command-class-specification" + "Z-Wave Host API Specification.pdf" = "zwave-host-api-specification" +} + +foreach ($name in $Docs.Keys) { + $pdf = Join-Path $Sources $name + if (-not (Test-Path $pdf)) { + throw "Missing source PDF: $pdf (place it in docs/specs/sources/)" + } + Write-Host "==> $name" + python $Convert $pdf -o $Out -s $Docs[$name] --max-pages $MaxPages --max-chars $MaxChars + if ($LASTEXITCODE -ne 0) { throw "convert.py failed for $name (exit $LASTEXITCODE)" } +} + +Write-Host "Done. Output under: $Out" diff --git a/tools/pdf2md/convert.py b/tools/pdf2md/convert.py new file mode 100644 index 0000000..60ac576 --- /dev/null +++ b/tools/pdf2md/convert.py @@ -0,0 +1,719 @@ +#!/usr/bin/env python3 +"""Convert a Z-Wave specification PDF into progressive-disclosure Markdown. + +The output is a folder tree of many small, topic-scoped ``.md`` files plus an +``index.md`` per directory, so an AI agent (or human) can navigate cheaply. + +Pipeline (deterministic, two passes): + 1. Read the PDF outline (bookmarks) -> the section tree. + 2. Rebuild "visual lines" per page (spans sharing a y are merged, so a heading + whose number and title are separate objects becomes one line). + 3. Bind each bookmark to a real heading line in the body (numbered headings by + number-prefix, others by position). Bookmarks that point *into* a table are + treated as in-table anchors, not headings. + 4. Detect tables (``find_tables``) and figures (embedded images) per page. + 5. Partition the section tree into files using a page/char size bound. + 6. Emit every file, resolving internal (GoTo) links to a concrete + ``file.md#anchor`` and keeping external (URI) links as-is. + +Run: python convert.py INPUT.pdf -o OUTDIR -s SLUG +""" + +import argparse +import hashlib +import posixpath +import re +import shutil +import sys +import unicodedata +from pathlib import Path + +import fitz # PyMuPDF + + +def pymupdf_version() -> str: + v = getattr(fitz, "version", None) + if isinstance(v, (list, tuple)) and v: + return str(v[0]) + if isinstance(v, str) and v: + return v + m = re.search(r"PyMuPDF\s+([\d.]+)", fitz.__doc__ or "") + return m.group(1) if m else "unknown" + + +# --------------------------------------------------------------------------- # +# Helpers +# --------------------------------------------------------------------------- # + +def write_text(path: Path, text: str) -> None: + path.parent.mkdir(parents=True, exist_ok=True) + with open(path, "w", encoding="utf-8", newline="\n") as fh: + fh.write(text) + + +def p2posix(p) -> str: + return str(p).replace("\\", "/") + + +def rel_posix(file_path, base) -> str: + return posixpath.normpath(posixpath.relpath(p2posix(file_path), p2posix(base))) + + +def escape_md_cell(cell) -> str: + if cell is None: + return "" + s = str(cell).replace("\n", " ").replace("\r", " ") + s = s.replace("|", "\\|") + return re.sub(r"\s+", " ", s).strip() + + +def slugify(text: str) -> str: + t = unicodedata.normalize("NFC", text.strip().lower()) + t = re.sub(r"[^\w\s-]", "", t, flags=re.UNICODE) + t = re.sub(r"\s+", "-", t) + t = re.sub(r"-+", "-", t).strip("-") + return t or "section" + + +def numkey(number: str) -> str: + if not number: + return "00" + return ".".join(f"{int(part):02d}" for part in number.split(".")) + + +def number_prefix_match(text: str, number: str) -> bool: + """True if text starts with `number` as a full dotted token (4.1 != 4.11).""" + m = re.match(r"^" + re.escape(number) + r"(?!\d)", text) + return bool(m) + + +_CTRL_RE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]") + + +def clean_title(text: str) -> str: + """Normalize a TOC/section title so emitted headings, anchors and links stay + clean. Some PDFs put a record-separator byte (\\x1e) where a hyphen belongs + ('Z\\x1eWave' -> 'Z-Wave') and tab-separate the number from the name; both + are collapsed here and any remaining C0/C1 control bytes are dropped.""" + t = text.replace("\x1e", "-") + t = t.replace("\t", " ") + t = _CTRL_RE.sub("", t) + return re.sub(r"\s+", " ", t).strip() + + +FOOTER_RE = re.compile( + r"(may only be copied|All Rights Reserved|Copyright|Z-Wave Alliance|" + r"^\d{4}/\d{2}/\d{2}$|^\d{1,4}$)", re.IGNORECASE) + +MIN_IMAGE_PT = 22 # figures smaller than this on any side are logos/bullets + +# Running headers/footers (page numbers, vendor ads, copyright lines) live in a +# narrow band at the very bottom of the page. Real body text in these specs never +# comes closer than ~77pt to the bottom edge, so anything small sitting lower than +# this is chrome and is dropped. +BOTTOM_BAND_PT = 70 + + +# --------------------------------------------------------------------------- # +# Data model +# --------------------------------------------------------------------------- # + +class Section: + __slots__ = ( + "level", "title", "number", "name", "page", "y", + "parent", "children", "bound", "is_real", + "stream_start", "stream_end", "page_span", "char_span", + "is_directory", "dir", "file", "render_file", "anchor", "owns_file", + "_real_children", + ) + + def __init__(self, level, title, number, name, page, y): + self.level = level + self.title = title + self.number = number + self.name = name + self.page = page + self.y = y + self.parent = None + self.children = [] + self.bound = None + self.is_real = False + self.stream_start = 0 + self.stream_end = 0 + self.page_span = 1 + self.char_span = 0 + self.is_directory = False + self.dir = None + self.file = None + self.render_file = None + self.anchor = "" + self.owns_file = False + self._real_children = [] + + +class VisualLine: + __slots__ = ("page", "y0", "y1", "x0", "x1", "text", "bold", "size", + "in_table", "spans", "section") + + def __init__(self, page, y0, y1, x0, x1, text, bold, size, in_table): + self.page = page + self.y0 = y0 + self.y1 = y1 + self.x0 = x0 + self.x1 = x1 + self.text = text + self.bold = bold + self.size = size + self.in_table = in_table + self.spans = [] # list of (text, linkref) + self.section = None + + +# --------------------------------------------------------------------------- # +# Per-page extraction +# --------------------------------------------------------------------------- # + +def extract_tables(page): + """Return a list of (rect, markdown) tuples.""" + try: + found = page.find_tables() + except Exception: + return [] + out = [] + for tab in found.tables: + try: + rows = tab.extract() + except Exception: + continue + if not rows: + continue + md = [] + for i, row in enumerate(rows): + md.append("| " + " | ".join(escape_md_cell(c) for c in row) + " |") + if i == 0: + md.append("| " + " | ".join("---" for _ in row) + " |") + out.append((fitz.Rect(tab.bbox), "\n".join(md))) + return out + + +def extract_images(doc, page, page_index, doc_root: Path, image_cache: dict): + """Return a list of (rect, relpath). Extracts non-trivial images to assets/.""" + out = [] + try: + infos = page.get_image_info(xrefs=True) + except Exception: + return out + for info in infos: + xref = info.get("xref") + bbox = info.get("bbox") + if not xref or not bbox: + continue + rect = fitz.Rect(bbox) + if rect.width < MIN_IMAGE_PT or rect.height < MIN_IMAGE_PT: + continue + try: + img = doc.extract_image(xref) + except Exception: + continue + data = img.get("image") or b"" + if not data: + continue + h = hashlib.sha1(data).hexdigest()[:10] + ext = img.get("ext") or "png" + relpath = f"assets/img-{h}.{ext}" + if relpath not in image_cache: + dest = doc_root / relpath + dest.parent.mkdir(parents=True, exist_ok=True) + dest.write_bytes(data) + image_cache[relpath] = True + out.append((rect, relpath)) + return out + + +def build_visual_lines(doc, page_index, tables_rects, links): + """Build merged visual lines for one page, attaching link refs per span.""" + page = doc[page_index] + d = page.get_text("dict") + + groups = {} + for block in d.get("blocks", []): + for line in block.get("lines", []): + for span in line.get("spans", []): + txt = span.get("text", "") + if txt is None or not txt.strip(): + continue + key = round(line["bbox"][1] / 2.0) + g = groups.get(key) + if g is None: + g = {"y0": line["bbox"][1], "y1": line["bbox"][3], "spans": []} + groups[key] = g + g["y0"] = min(g["y0"], line["bbox"][1]) + g["y1"] = max(g["y1"], line["bbox"][3]) + g["spans"].append(span) + + def in_table(x, y): + return any(r.contains(fitz.Point(x + 1, y + 1)) for r in tables_rects) + + vlines = [] + for g in sorted(groups.values(), key=lambda g: g["y0"]): + g["spans"].sort(key=lambda s: (round(s["bbox"][1]), s["bbox"][0])) + text = " ".join(s.get("text", "").strip() for s in g["spans"] if s.get("text", "").strip()) + text = re.sub(r"\s+", " ", text).strip() + if not text: + continue + bold = any("Bold" in (s.get("font") or "") for s in g["spans"]) + size = max(s.get("size", 0) for s in g["spans"]) + x0 = min(s["bbox"][0] for s in g["spans"]) + x1 = max(s["bbox"][2] for s in g["spans"]) + vl = VisualLine(page_index, g["y0"], g["y1"], x0, x1, text, bold, size, + in_table(x0, g["y0"])) + for s in g["spans"]: + stxt = s.get("text", "").strip() + if not stxt: + continue + linkref = None + srect = fitz.Rect(s["bbox"]) + for l in links: + f = l.get("from") + if f is None: + continue + if srect.intersects(f): + kind = l.get("kind") + if kind == 2: + linkref = ("uri", l.get("uri", "")) + elif kind == 1: + linkref = ("goto", l.get("page", 0), l.get("to").y) + break + vl.spans.append((stxt, linkref)) + vlines.append(vl) + vlines.sort(key=lambda v: (v.y0, v.x0)) + return vlines + + +# --------------------------------------------------------------------------- # +# Converter +# --------------------------------------------------------------------------- # + +class Converter: + def __init__(self, pdf_path, out_root, slug, max_pages, max_chars, do_images, + verbose): + self.pdf_path = Path(pdf_path) + self.doc_root = Path(out_root) / slug + self.slug = slug + self.max_pages = max_pages + self.max_chars = max_chars + self.do_images = do_images + self.verbose = verbose + self.doc = None + self.sections = [] + self.real_sections = [] + self.stream = [] + self.page_lines = {} + self.page_tables = {} + self.page_images = {} + self.image_cache = {} + self.first_body_page = 0 + self.version = "" + self.anchor_index = [] + self._current_file = None + self._used_captions = set() + + def run(self): + # regenerate from scratch (idempotent): clean before extracting assets + if self.doc_root.exists(): + shutil.rmtree(self.doc_root) + self.doc_root.mkdir(parents=True, exist_ok=True) + self.doc = fitz.open(str(self.pdf_path)) + first = None + for level, _t, pg in self.doc.get_toc(): + if level == 1: + first = pg + break + self.first_body_page = (first - 1) if first else 0 + self.version = self._scrape_version() + + self._build_sections() + self._build_pages() + self._bind_headings() + self._build_stream() + self._compute_ranges() + self._partition() + self._assign_anchors() + self._emit_all() + stats = self._stats() + self.doc.close() + return stats + + def _scrape_version(self): + try: + txt = self.doc[0].get_text() + except Exception: + return "" + m = re.search(r"[Vv]ersion[:\s]+([0-9][0-9A-Za-z.\-_x]*)", txt) + return m.group(1).strip() if m else "" + + # ---- sections ---- + def _build_sections(self): + stack = [] + for level, title, _pg, dest in self.doc.get_toc(simple=False): + title = clean_title(title) + m = re.match(r"^(\d+(?:\.\d+)*)\s+(.*\S)\s*$", title) + if m: + number, name = m.group(1), m.group(2).strip() + else: + number, name = None, title.strip() + sec = Section(level, title.strip(), number, name, dest["page"], dest["to"].y) + while stack and stack[-1].level >= level: + stack.pop() + if stack: + stack[-1].children.append(sec) + sec.parent = stack[-1] + stack.append(sec) + self.sections.append(sec) + + # ---- pages ---- + def _build_pages(self): + for pi in range(self.first_body_page, self.doc.page_count): + page = self.doc[pi] + links = page.get_links() + self.page_tables[pi] = extract_tables(page) + trects = [r for r, _ in self.page_tables[pi]] + self.page_images[pi] = (extract_images(self.doc, page, pi, self.doc_root, + self.image_cache) + if self.do_images else []) + self.page_lines[pi] = build_visual_lines(self.doc, pi, trects, links) + + # ---- bind headings ---- + def _bind_headings(self): + for sec in self.sections: + vlines = self.page_lines.get(sec.page, []) + if not vlines: + continue + dy = sec.y + boldc = [v for v in vlines if v.bold and 9.5 <= v.size <= 16 and not v.in_table] + # Only *numbered* sections are real headings. Non-numbered bookmarks are + # field/table-row anchors (they point into frame-format tables) and are + # not rendered as headings. + if not sec.number: + continue + bynum = [v for v in boldc if number_prefix_match(v.text, sec.number)] + if not bynum: + continue + inband = [v for v in bynum if dy <= v.y0 <= dy + 18] + pick = min(inband or bynum, key=lambda v: abs(v.y0 - (dy + 8))) + sec.bound = pick + pick.section = sec + sec.is_real = True + + # ---- global stream ---- + def _build_stream(self): + self.stream = [] + self._used_captions = set() + for pi in range(self.first_body_page, self.doc.page_count): + vlines = self.page_lines[pi] + page_h = self.doc[pi].rect.height + captions = [v for v in vlines if re.match(r"^(Figure|Table|Listing)\b", + v.text, re.I)] + for rect, relpath in self.page_images.get(pi, []): + alt = "" + for c in captions: + if re.match(r"^Figure\b", c.text, re.I) and \ + abs(c.y0 - (rect.y1 + 6)) < 40: + alt = c.text + self._used_captions.add(id(c)) + break + self.stream.append({"page": pi, "sorty": rect.y0, "kind": "image", + "image": (relpath, alt or f"figure p{pi + 1}")}) + for rect, tmd in self.page_tables.get(pi, []): + self.stream.append({"page": pi, "sorty": rect.y0, "kind": "table", + "table_md": tmd}) + for v in vlines: + if v.in_table or v.size < 8.5 or id(v) in self._used_captions: + continue + if FOOTER_RE.search(v.text) and v.size < 9.5: + continue + if v.size < 10.5 and v.y1 > page_h - BOTTOM_BAND_PT: + continue + if v.section is not None and v.section.is_real: + self.stream.append({"page": pi, "sorty": v.y0, "kind": "heading", + "section": v.section, "vl": v}) + else: + self.stream.append({"page": pi, "sorty": v.y0, "kind": "text", "vl": v}) + self.stream.sort(key=lambda it: (it["page"], it["sorty"], it["kind"] == "text")) + + # ---- ranges ---- + def _compute_ranges(self): + self.real_sections = [s for s in self.sections if s.is_real] + index_of = {} + for i, it in enumerate(self.stream): + if it["kind"] == "heading": + index_of.setdefault((it["page"], round(it["sorty"], 1)), i) + for sec in self.real_sections: + sec.stream_start = index_of.get((sec.page, round(sec.bound.y0, 1)), 0) + for i, sec in enumerate(self.real_sections): + end = len(self.stream) + for j in range(i + 1, len(self.real_sections)): + if self.real_sections[j].level <= sec.level: + end = self.real_sections[j].stream_start + break + sec.stream_end = end + if sec.stream_start < sec.stream_end: + first = self.stream[sec.stream_start] + last = self.stream[sec.stream_end - 1] + sec.page_span = last["page"] - first["page"] + 1 + sec.char_span = sum(self._item_len(it) for it in + self.stream[sec.stream_start:sec.stream_end]) + + @staticmethod + def _item_len(it): + if it["kind"] == "table": + return len(it.get("table_md", "")) + if it["kind"] == "image": + return 0 + vl = it.get("vl") + return len(vl.text) if vl else 0 + + # ---- partition ---- + def _partition(self): + for sec in self.real_sections: + sec._real_children = [] + for sec in self.real_sections[1:]: + par = None + for cand in reversed(self.real_sections[:self.real_sections.index(sec)]): + if cand.level < sec.level: + par = cand + break + if par: + par._real_children.append(sec) + for ch in [s for s in self.real_sections if s.level == 1]: + self._walk(ch, self.doc_root) + + def _walk(self, node, base_dir): + has_children = len(node._real_children) > 0 + too_big = node.page_span > self.max_pages or node.char_span > self.max_chars + node.is_directory = has_children and (too_big or node.level == 1) + node.owns_file = True + if node.is_directory: + node.dir = Path(base_dir) / f"{numkey(node.number or '0')}-{slugify(node.name)}" + node.file = node.dir / "index.md" + node.render_file = node.file + for ch in node._real_children: + self._walk(ch, node.dir) + else: + node.file = Path(base_dir) / f"{numkey(node.number or '0')}-{slugify(node.name)}.md" + node.render_file = node.file + for ch in node._real_children: + self._mark_headings(ch, node.file) + + def _mark_headings(self, node, file): + node.render_file = file + for ch in node._real_children: + self._mark_headings(ch, file) + + # ---- anchors ---- + def _assign_anchors(self): + file_headings = {} + for sec in self.real_sections: + file_headings.setdefault(sec.render_file, []).append(sec) + for fpath, secs in file_headings.items(): + seen = {} + for sec in secs: + base = slugify(sec.title) + n = seen.get(base, 0) + seen[base] = n + 1 + sec.anchor = base if n == 0 else f"{base}-{n + 1}" + + for sec in self.real_sections: + if sec.bound is None: + continue + self.anchor_index.append( + (sec.page, sec.bound.y0, rel_posix(sec.render_file, self.doc_root), sec.anchor)) + self.anchor_index.sort(key=lambda t: (t[0], t[1])) + + def resolve_goto(self, page, y): + best = None + for (ap, ay, fp, anc) in self.anchor_index: + if ap < page or (ap == page and ay <= y + 12): + best = (fp, anc) + else: + break + if best is None and self.anchor_index: + best = (self.anchor_index[0][2], self.anchor_index[0][3]) + return best + + # ---- emit ---- + def _emit_all(self): + for sec in self.real_sections: + if not sec.owns_file: + continue + self._current_file = sec.file + end = self._content_end(sec) + items = self.stream[sec.stream_start:end] + body = self._render_body(items, sec) + header = self._provenance_header(sec) + rel = rel_posix(sec.file, self.doc_root) + write_text(self.doc_root / rel, header + body) + + self._write_contents() + self._write_root_index() + + def _content_end(self, sec): + if sec.is_directory and sec._real_children: + return sec._real_children[0].stream_start + return sec.stream_end + + def _provenance_header(self, sec): + if sec.file.name == "index.md" and rel_posix(sec.file, self.doc_root) == "index.md": + return "" + last_page = self.stream[min(sec.stream_end, len(self.stream) - 1)]["page"] + return (f"\n") + + def _append_block(self, path, block): + text = path.read_text(encoding="utf-8") if path.exists() else "" + write_text(path, text.rstrip("\n") + block) + + def _write_contents(self): + for sec in self.real_sections: + if not sec.is_directory or not sec._real_children: + continue + lines = ["", "", "## Contents", ""] + base = sec.file.parent # links are relative to this index.md's directory + for ch in sec._real_children: + link = rel_posix(ch.file, base) + lines.append(f"- [{ch.title.strip()}]({link})") + self._append_block(self.doc_root / rel_posix(sec.file, self.doc_root), + "\n".join(lines) + "\n") + + def _write_root_index(self): + chapters = [s for s in self.real_sections if s.level == 1] + lines = ["", "", "## Chapters", ""] + for ch in chapters: + lines.append(f"- [{ch.title.strip()}]({rel_posix(ch.file, self.doc_root)})") + root_index = self.doc_root / "index.md" + if root_index.exists(): + self._append_block(root_index, "\n".join(lines) + "\n") + else: + write_text(root_index, self._root_index_text() + "\n".join(lines) + "\n") + + def _root_index_text(self): + prov = (f"\n\n") + head = (f"# {self.pdf_path.stem}\n\n" + f"*Source:* [{self.pdf_path.name}](../sources/{self.pdf_path.name})\n") + if self.version: + head += f"*Version:* {self.version}\n" + head += (f"*Pages:* {self.doc.page_count}\n" + f"*Generated by:* `tools/pdf2md/convert.py` (PyMuPDF {pymupdf_version()})\n") + return prov + head + + # ---- body rendering ---- + def _render_body(self, items, root_sec): + out = [] + buf = [] + root_level = root_sec.level + + def flush(): + if buf: + out.append(self._render_paragraph(buf)) + buf.clear() + + prev = None + for it in items: + kind = it["kind"] + if kind == "heading": + flush() + sec = it["section"] + lvl = max(1, min(6, 1 + (sec.level - root_level))) + out.append("#" * lvl + " " + sec.title.strip()) + prev = it + elif kind == "table": + flush() + out.append(it["table_md"]) + prev = it + elif kind == "image": + flush() + rel, alt = it["image"] + out.append(f"![{alt}]({rel})") + prev = it + else: + vl = it["vl"] + if prev is not None and prev["kind"] == "text" and prev["page"] == vl.page: + if it["sorty"] - prev["sorty"] > vl.size * 1.7: + flush() + buf.append(vl) + prev = it + flush() + text = "\n\n".join(x for x in out if x) + return re.sub(r"\n{3,}", "\n\n", text).rstrip() + "\n" + + def _render_paragraph(self, vlines): + tokens = [] + for vl in vlines: + for txt, ref in vl.spans: + if not txt: + continue + target = None + if ref and ref[0] == "uri": + target = ref[1] + elif ref and ref[0] == "goto": + r = self.resolve_goto(ref[1], ref[2]) + if r: + cur_dir = posixpath.dirname(rel_posix(self._current_file, self.doc_root)) + target = posixpath.relpath(r[0], cur_dir or ".") + "#" + r[1] + tokens.append((txt, target)) + merged = [] + for txt, tgt in tokens: + if merged and merged[-1][1] is not None and merged[-1][1] == tgt: + merged[-1] = (merged[-1][0] + " " + txt, tgt) + else: + merged.append((txt, tgt)) + parts = [] + for txt, tgt in merged: + parts.append(f"[{txt}]({tgt})" if tgt else txt) + result = "" + for part in parts: + if not result: + result = part + elif part[0] in ".,;:)?!>%\"'" or result[-1] in "([": + result += part + else: + result += " " + part + return re.sub(r"\s+", " ", result).strip() + + def _stats(self): + n_files = sum(1 for _ in self.doc_root.rglob("*.md")) + n_img = sum(1 for _ in self.doc_root.rglob("assets/*")) + return {"doc": self.slug, "pages": self.doc.page_count, + "sections": len(self.sections), "real_headings": len(self.real_sections), + "md_files": n_files, "images": n_img} + + +def main(argv=None): + ap = argparse.ArgumentParser(description="Convert a Z-Wave spec PDF to Markdown.") + ap.add_argument("pdf", help="Input PDF path") + ap.add_argument("-o", "--out", default="docs/specs") + ap.add_argument("-s", "--slug", default=None) + ap.add_argument("--max-pages", type=int, default=15) + ap.add_argument("--max-chars", type=int, default=60000) + ap.add_argument("--no-images", action="store_true") + args = ap.parse_args(argv) + + pdf = Path(args.pdf) + if not pdf.exists(): + sys.exit(f"error: input not found: {pdf}") + slug = args.slug or slugify(pdf.stem) + conv = Converter(pdf, Path(args.out), slug, args.max_pages, args.max_chars, + not args.no_images, verbose=False) + stats = conv.run() + print(f"[{stats['doc']}] pages={stats['pages']} sections={stats['sections']} " + f"headings={stats['real_headings']} md_files={stats['md_files']} " + f"images={stats['images']} -> {conv.doc_root}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tools/pdf2md/requirements.txt b/tools/pdf2md/requirements.txt new file mode 100644 index 0000000..92103fa --- /dev/null +++ b/tools/pdf2md/requirements.txt @@ -0,0 +1 @@ +PyMuPDF==1.27.1 diff --git a/tools/pdf2md/verify.py b/tools/pdf2md/verify.py new file mode 100644 index 0000000..3590039 --- /dev/null +++ b/tools/pdf2md/verify.py @@ -0,0 +1,85 @@ +#!/usr/bin/env python3 +"""Verify internal Markdown links across a docs/specs tree. + +Checks that every relative ``.md`` link points to a file that exists and, when an +anchor is present, that the anchor matches a heading in the target file (anchors +are recomputed with the same slugify + de-dup rules used by convert.py). + +Run: python verify.py [docs-root] (default: docs/specs) +""" + +import posixpath +import re +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent)) +from convert import slugify # noqa: E402 + +HEADING_RE = re.compile(r"^(#{1,6})\s+(.*\S)\s*$") +LINK_RE = re.compile(r"\]\(([^)\s]+\.md)(?:#([^)\s]+))?\)") + + +def heading_anchors(path: Path): + anchors = {} + seen = {} + for line in path.read_text(encoding="utf-8").splitlines(): + m = HEADING_RE.match(line) + if not m: + continue + base = slugify(m.group(2)) + n = seen.get(base, 0) + seen[base] = n + 1 + anchors[base if n == 0 else f"{base}-{n + 1}"] = True + return anchors + + +def main(root="docs/specs"): + root = Path(root) + if not root.exists(): + sys.exit(f"error: no such directory: {root}") + md_files = list(root.rglob("*.md")) + anchor_cache = {} + + def anchors_for(p: Path): + if p not in anchor_cache: + anchor_cache[p] = heading_anchors(p) + return anchor_cache[p] + + checked = 0 + missing_file = [] + missing_anchor = [] + for f in md_files: + text = f.read_text(encoding="utf-8") + for m in LINK_RE.finditer(text): + target, anchor = m.group(1), m.group(2) + # only relative links (ignore http/https and absolute) + if re.match(r"^[a-zA-Z][a-zA-Z0-9+.-]*:", target): + continue + tp = (f.parent / target).resolve() + checked += 1 + if not tp.exists(): + missing_file.append((rel(f, root), target)) + continue + if anchor and anchor not in anchors_for(tp): + missing_anchor.append((rel(f, root), target, anchor)) + + print(f"docs-root: {root}") + print(f"md files: {len(md_files)} internal links checked: {checked}") + print(f"missing target files: {len(missing_file)}") + for src, tgt in missing_file[:30]: + print(f" [file] {src} -> {tgt}") + print(f"missing anchors: {len(missing_anchor)}") + for src, tgt, anc in missing_anchor[:30]: + print(f" [anchor] {src} -> {tgt}#{anc}") + if missing_file or missing_anchor: + sys.exit(1) + print("OK: all internal links resolve.") + + +def rel(p: Path, root: Path) -> str: + return posixpath.relpath(str(p), str(root)).replace("\\", "/") + + +if __name__ == "__main__": + main(sys.argv[1] if len(sys.argv) > 1 else "docs/specs")