Device Normalization
Overview
Device Normalization is the process by which the Zipato platform transforms heterogeneous physical devices from different manufacturers and protocols into a unified, consistent representation. Rather than exposing protocol-specific peculiarities to the rest of the platform, device normalization provides a single abstraction layer that allows devices from Z-Wave, Zigbee, KNX, Modbus, MQTT, and many other protocols to be managed through a common interface.
The normalization system ensures that:
- A Z-Wave light switch behaves the same way as a KNX switch in rules and automations
- Device capabilities are discovered and exposed consistently regardless of protocol
- Firmware versions, manufacturers, and models are properly tracked
- UI widgets and controls work uniformly across all device types
Why Device Normalization Matters
The Zipato platform supports 15+ hardware protocols and communication standards — Z-Wave, Zigbee, Matter, KNX, Modbus, MQTT, EnOcean, and more. Without normalization, every application, rule engine, and UI component would need protocol-specific logic to handle each device type.
Device normalization solves this by establishing a single source of truth for how devices are represented:
- Unified Data Model: All devices conform to a standard Endpoint/Cluster/Attribute hierarchy, regardless of their underlying protocol.
- Consistent Capabilities: Device features are exposed through the same Attribute and Action mechanisms.
- Protocol Transparency: Rules, automations, and integrations work the same way across all protocols.
- Extensibility: New protocols and device types can be added without modifying existing application code.
Architecture: The Normalization Flow
When a physical device is discovered by a protocol adapter, it goes through this four-step normalization pipeline:
Step 1: Protocol Adapter Discovery
Each protocol (Z-Wave, Zigbee, KNX, etc.) has a dedicated adapter that discovers devices and reports their properties:
- Device Identification: Manufacturer, model number, serial number, firmware version
- Hardware Characteristics: Energy mode (battery, mains, or hybrid), physical endpoints it exposes
- Connection Metadata: Signal strength, last seen timestamp, network address
Step 2: Descriptor Matching
The platform searches its descriptor library for a schema that matches this device type. Descriptors use intelligent matching rules that can handle device variants—for example:
- "Any Philips Hue light with model XYZ"
- "Any Z-Wave device from manufacturer ABC in this version range"
- Multiple device variants can match the same descriptor if they have identical capabilities
Step 3: Apply Descriptor
Once a matching descriptor is found, the platform applies it to the device. This operation creates:
- Cluster Endpoints: Associate a Cluster definition with a specific Endpoint, representing the concrete availability of that capability on that part of the device (e.g., OnOff cluster on Endpoint 0 for on/off control, LevelControl cluster on Endpoint 0 for brightness)
- Attribute Value Definitions: Concrete addressable data points for each Cluster Endpoint — configure units, TTL, and whether values are reported to the cloud (e.g., PowerState, BrightnessLevel, Color)
- UI Widgets: How the device should appear and be controlled in applications and dashboards
Step 4: Platform Integration
After normalization, the device is fully integrated:
- Rules and automations can reference it using standard attribute names
- The UI renders device controls consistently regardless of protocol
- The REST API exposes its capabilities through a uniform schema
- Third-party integrations can interact with it using the standard interface
Device Hierarchy and Data Organization
All devices in the Zipato platform follow a consistent hierarchical structure:
Structure Explained
| Level | Purpose | Examples |
|---|---|---|
| Hub | Central gateway that connects to all networks and the cloud | Your Zipato Box, Zipabox, or cloud instance |
| Network | Communication protocol and its devices | Z-Wave network, Zigbee network, virtual network |
| Device | Physical or virtual device connected to a network | Light switch, thermostat, motion sensor, virtual alarm |
| Endpoint | Logical, addressable part of a device. May correspond to a native protocol endpoint or be created internally by the platform | Z-Wave endpoint #0, Zigbee endpoint #1, KNX group 1/2/3 |
| Cluster Endpoint | Associates a Cluster definition with a specific Endpoint — represents the concrete availability of that capability on that part of the device | OnOff cluster on Endpoint 0 (on/off control), LevelControl cluster on Endpoint 0 (brightness) |
| Cluster | Global schema definition — what attributes and actions a capability type supports | OnOff cluster defines PowerState; LevelControl defines BrightnessLevel |
| AttributeValueDefinition | Concrete addressable data point for a specific device — holds runtime configuration (TTL, unit, reported flag, hidden flag) | BrightnessLevel value configuration for this specific device |
Understanding the Hierarchy
The key insight is that Endpoints, Cluster Endpoints, Clusters, Attributes, and Attribute Value Definitions are five separate layers that coexist — normalization does not replace Endpoints, it adds Cluster Endpoints beneath them:
-
Endpoint — logical, addressable part of a device reported by the adapter. Stays in the data model permanently; normalization adds things beneath it, never replaces it.
- Z-Wave uses numbered endpoints (0–255)
- Zigbee uses endpoint IDs (1–254)
- KNX uses group addresses
-
Cluster Endpoint — associates a Cluster definition with a specific Endpoint, created by the descriptor system. Represents the concrete availability of that capability on that part of the device. A single Endpoint can have multiple Cluster Endpoints (e.g., OnOff + LevelControl both on Endpoint 0).
-
Cluster — a global schema (not per-device) that defines which Attributes and Actions a capability type supports. The OnOff Cluster defines PowerState; LevelControl defines BrightnessLevel.
-
Attribute — the schema definition of a single property on a Cluster (name, data type, readable/writable/reportable flags). Shared globally — it is not a value holder.
-
AttributeValueDefinition — a concrete addressable data point for a specific device. Holds configuration (TTL, unit, whether the value is reported to the cloud) and is scoped to a specific hub and endpoint.
Example with a Z-Wave smart dimmer:
Key Insight: Endpoints are permanent protocol-level containers. Cluster Endpoints are created by the descriptor system and placed under them — each one represents the concrete availability of a normalized capability on that part of the device. Attribute is only a schema definition — the runtime configuration lives in AttributeValueDefinition.
Device Properties
After normalization, every device is tracked with consistent information:
| Property | Purpose | Example |
|---|---|---|
| Device Type | What the device is | Smart light, door lock, thermostat |
| Manufacturer | Who made it | Philips, Aeotec, Honeywell |
| Model Number | Specific product model | Hue Bridge, ZW096 Smart Dimmer |
| Serial Number | Unique identifier | AB:CD:EF:12:34:56 |
| Firmware Version | Software version running on device | 1.2.5, 3.5.8 |
| Power Source | How it's powered | Battery, mains, both, passive |
| Location | Where it's physically installed | Living Room, Master Bedroom, Kitchen |
| Status | Current state | Active, inactive, disabled |
All devices, regardless of protocol, expose their capabilities through this uniform structure.
Device UI and User Experience
Each device descriptor defines not just the device's capabilities, but also how it appears and is controlled in user applications.
Widget Templates
A widget is the visual representation of a device capability in a dashboard, mobile app, or control panel:
Each device capability can have a custom widget that defines:
- Control Type: Toggle switch, slider, color picker, text input, etc.
- Display Style: Icon, label, color coding
- Grouping: How related controls are organized together
Device Branding and Organization
The platform tracks comprehensive information about device manufacturers and models to support filtering, searching, and user guidance.
Manufacturer Information
For each manufacturer, the system stores:
- Brand Name: Display name (e.g., "Philips", "Aeotec")
- Logo Assets: Multiple sizes for different UI contexts
- Category: Device type classification
Device Models
For each model within a manufacturer, the system tracks:
- Product Name: Human-readable model name (e.g., "Hue Bridge Gen 3")
- SKU: Stock keeping unit for ordering
- Photos: Product images in multiple sizes
- Tags: Keywords for search and categorization
- Descriptors: Which device descriptors apply to this model
Search and Discovery
This organization enables:
- Filtering by Manufacturer: "Show me all Philips devices"
- Search by Model: "Find a Z-Wave lock"
- Brand-Based Recommendations: "Philips Hue is supported"
- Product Browsing: Display device catalogs in the UI