# openzwave/open-zwave architecture

> Architecture diagram of the GitHub repository openzwave/open-zwave, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openzwave/open-zwave
- Repository: https://github.com/openzwave/open-zwave

## Overview

##### Main Components
- Core Library: This is found in the /cpp directory. It includes the core source files (/cpp/src), which implement the main functionality – for example, the Manager, Node, Notification, and Value classes. It is responsible for orchestrating communications between the Z‑Wave controller hardware and the software using the protocol.
- Command Classes: Within /cpp/src/command_classes, there is a dense collection of files that implement support for various Z‑Wave command classes (e.g., Basic, SensorBinary, SwitchMultilevel, etc.). This layer abstracts the protocol commands and interprets device-specific messages.
- Platform/Abstraction Layer: The library has different platform implementations (found in /cpp/src/platform) for handling operating system–specific details such as DNS, file operations, logging, threading, and serial communications. There are specialized subdirectories for Unix, Windows, winRT, and others.
- Device Configuration and Database: The /config folder holds numerous XML files representing device configuration data. This forms the device database that allows OpenZWave to correctly recognize and interface with a wide range of Z‑Wave devices.
- Examples & Wrappers: The project includes example applications (e.g., MinOZW in /cpp/examples and Windows versions) as well as community–developed language wrappers. These show how external applications integrate with the library.
- Testing and Build Infrastructure: With directories like /cpp/test, /debian for packaging, and build scripts (Makefile, BSDmakefile, config files, GitHub workflows, etc.), you must capture the supporting elements that demonstrate how the library is built, tested, and maintained across platforms.

##### Relationships and Interactions
- The Core Library acts as the “brain” connecting to the Z‑Wave controller hardware. It uses platform-specific implementations (via the Platform Abstraction Layer) to communicate with the underlying operating system.
- The Command Classes provide a modular way to implement and extend support for various Z‑Wave functions. They interact with the Core Library to process incoming messages and send commands through the controller.
- The device configuration subsystem (drawing from the /config folder) supplies the library with pre-defined XML data about supported devices, ensuring that the library and its applications can recognize and properly configure Z‑Wave devices.
- API Wrappers / Example Applications use the Core Library as the backend, often by linking to it, and are interfaced via defined APIs (with build configuration files and sln project files showing integration on Windows, etc.).
- Testing components leverage both unit tests in /cpp/test and integration tests (e.g., using the built sample application MinOZW) to validate changes in the library.

##### Architectural Patterns and Design Principles
- Cross-Platform Design: Given the platform directories (for Unix, Windows, winRT, etc.), it’s important to note that the library’s architecture uses abstraction to enable portability.
- Plugin/Extension Points: The extensive set of XML configuration files in /config shows that the library is designed to be easily extended with new devices and command classes by simply adding configuration files, without needing to modify core logic.

##### Relevant Technologies/Tools
- Programming Language: C++.
- Build Infrastructure: Makefiles, BSDmakefile, Visual Studio solutions for Windows (in /cpp/build/windows and /cpp/examples/windows) and other build scripts.
- Testing: Unit tests (gtest in /cpp/test) and cross-platform integration tests.
- Documentation: Doxygen-based documentation and online Developer documentation, as noted in the README.
- CI Support: GitHub workflows (under .github/workflows) which help automate tasks like configuration verification and tests.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Platform Layer
    subgraph "Platform Abstraction Layer"
        PL["Platform Abstraction Layer (cpp/src/platform)"]:::platform
    end

    %% Core Library & Modules
    subgraph "Core Library & Modules"
        CL["Core Library (cpp/src)"]:::core
        CC["Command Classes Module (cpp/src/command_classes)"]:::module
        DC["Device Configuration (config)"]:::config
        EA1["Example Applications (MinOZW)"]:::external
        EA2["Windows Example Applications"]:::external
    end

    %% Testing & Build Infrastructure
    subgraph "Testing & Build Infrastructure"
        TB1["Unit Testing (cpp/test)"]:::support
        TB2["Build Infrastructure (BSDmakefile, Makefile, debian, .github/workflows)"]:::support
    end

    %% Relationships
    PL -->|"providesOSservices"| CL
    DC -->|"suppliesDeviceInfo"| CL
    CL -->|"processesZWaveCommands"| CC
    EA1 -->|"integratesViaAPI"| CL
    EA2 -->|"integratesViaAPI"| CL
    TB1 -->|"validatesCore"| CL
    TB2 -->|"buildsAndMaintains"| CL

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef platform fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef module fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef config fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef external fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef support fill:#F08080,stroke:#000,stroke-width:2px;

    %% Click Events
    click CL "https://github.com/openzwave/open-zwave/tree/master/cpp/src"
    click CC "https://github.com/openzwave/open-zwave/tree/master/cpp/src/command_classes"
    click PL "https://github.com/openzwave/open-zwave/tree/master/cpp/src/platform"
    click DC "https://github.com/openzwave/open-zwave/tree/master/config"
    click EA1 "https://github.com/openzwave/open-zwave/tree/master/cpp/examples"
    click EA2 "https://github.com/openzwave/open-zwave/tree/master/cpp/examples/windows"
    click TB1 "https://github.com/openzwave/open-zwave/tree/master/cpp/test"
    click TB2 "https://github.com/openzwave/open-zwave/tree/master/BSDmakefile"
```
