Add Z-Wave spec PDFs and Markdown conversion tooling

.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

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

README.md

@@ -40,6 +40,10 @@ var binarySwitch = driver.Controller.Nodes[2].GetCommandClass<BinarySwitchComman
 await binarySwitch.SetAsync(targetValue: true, duration: null, CancellationToken.None);
 ```
 
+## Specification Reference
+
+Markdown versions of the Z-Wave Host API, Command Class, and 500-series programmer's guide specifications live in [`docs/specs/`](docs/specs/README.md).
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development details.

docs/specs/README.md

@@ -0,0 +1,52 @@
+# Z-Wave Specification (Markdown)
+
+Markdown converted from the Z-Wave Alliance specification PDFs, structured for
+progressive disclosure so that both humans and AI agents can navigate it
+efficiently.
+
+Each specification is a folder of many small, topic-scoped `.md` files plus an
+`index.md` per directory. Every generated file carries provenance (source PDF,
+section, page range, generator, PyMuPDF version) in a leading HTML comment.
+
+The source PDFs are stored via [Git LFS](https://git-lfs.com) under `sources/`.
+
+## Layout
+
+```
+docs/specs/
+  sources/                          # source PDFs (Git LFS)
+  zwave-500-series-programmers-guide/
+    index.md                        # provenance + chapter list
+    assets/                         # extracted figures
+    01-abbreviations.md
+    03-zwave-software-architecture/ # a chapter = a directory
+      index.md
+      03-1-zwave-system-startup-code.md
+      ...
+  command-class-specification/      # one file per command class / major section
+  zwave-host-api-specification/
+```
+
+- **Heading depth** in a file maps to `#`..`####`. Deeper sections that fit are
+  rendered as headings inside their parent file; larger sections are split into
+  their own files (and sub-`index.md`).
+- **Internal links** point to a specific `file.md#anchor`. **External links**
+  keep their original URL.
+- **Figures** are extracted to `assets/` and embedded in place.
+
+## Regenerating
+
+The generator lives in [`tools/pdf2md/`](../../tools/pdf2md/).
+
+1. Make sure Python 3 and PyMuPDF are installed (`pip install -r tools/pdf2md/requirements.txt`).
+2. Make sure Git LFS is set up (`git lfs install`).
+3. Run:
+
+   ```powershell
+   pwsh tools/pdf2md/convert.ps1
+   ```
+
+   This converts every PDF in `docs/specs/sources/` into the matching folder
+   under `docs/specs/`. Re-running is idempotent: each output folder is fully
+   regenerated. To convert a single file, or to change a folder name, see
+   `tools/pdf2md/convert.ps1` (the `source → folder` map).

docs/specs/command-class-specification/01-abbreviations.md

@@ -0,0 +1,34 @@
+<!--
+  generated-by: tools/pdf2md/convert.py
+  pymupdf: 1.27.1
+  source: SDS13781-4 Z-Wave Application Command Class Specification.pdf
+  section: "1 Abbreviations"
+  pages: 21-22
+-->
+# 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 |  |  |

docs/specs/command-class-specification/02-introduction/02.01-precedence-of-definitions.md

@@ -0,0 +1,10 @@
+<!--
+  generated-by: tools/pdf2md/convert.py
+  pymupdf: 1.27.1
+  source: SDS13781-4 Z-Wave Application Command Class Specification.pdf
+  section: "2.1 Precedence of definitions"
+  pages: 22-22
+-->
+# 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.

docs/specs/command-class-specification/02-introduction/02.02-terms-used-in-this-document.md

@@ -0,0 +1,24 @@
+<!--
+  generated-by: tools/pdf2md/convert.py
+  pymupdf: 1.27.1
+  source: SDS13781-4 Z-Wave Application Command Class Specification.pdf
+  section: "2.2 Terms used in this document"
+  pages: 22-23
+-->
+# 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.

docs/specs/command-class-specification/02-introduction/index.md

@@ -0,0 +1,21 @@
+<!--
+  generated-by: tools/pdf2md/convert.py
+  pymupdf: 1.27.1
+  source: SDS13781-4 Z-Wave Application Command Class Specification.pdf
+  section: "2 Introduction"
+  pages: 22-23
+-->
+# 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)

docs/specs/command-class-specification/03-command-class-overview/03.01-overview.md

@@ -0,0 +1,10 @@
+<!--
+  generated-by: tools/pdf2md/convert.py
+  pymupdf: 1.27.1
+  source: SDS13781-4 Z-Wave Application Command Class Specification.pdf
+  section: "3.1 Overview"
+  pages: 23-23
+-->
+# 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.

docs/specs/command-class-specification/03-command-class-overview/03.02-command-class-format.md

@@ -0,0 +1,77 @@
+<!--
+  generated-by: tools/pdf2md/convert.py
+  pymupdf: 1.27.1
+  source: SDS13781-4 Z-Wave Application Command Class Specification.pdf
+  section: "3.2 Command class format"
+  pages: 23-25
+-->
+# 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.

docs/specs/command-class-specification/03-command-class-overview/03.03-controlled-and-supported-command-classes.md

@@ -0,0 +1,16 @@
+<!--
+  generated-by: tools/pdf2md/convert.py
+  pymupdf: 1.27.1
+  source: SDS13781-4 Z-Wave Application Command Class Specification.pdf
+  section: "3.3 Controlled and Supported Command Classes"
+  pages: 25-25
+-->
+# 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.