4. Home API

The Home API handles everything related to the home automation and the hub itself.

Key features:

  • Execute Actions (e.g. switch a device)
  • CRUD for Devices
  • xRUx for Capabilities
  • CRUD of Products (Products can be understood as device drivers and services)
  • CRUD of Interactions and Rules between devices
  • CRUD for Locations (aka. rooms)
  • xRUD of Messages
  • CRUD of Notification Subscriptions
  • Checking and redeeming SmartCodes (used to add/update buyable Products)

Create of CRUD relates to “add to the system” in these cases

Details to all Home API endpoints & entities can be found in the Home API Reference.

Home API Domain Model

The Home API makes use of multiple Object Entities that can be added, retrieved, updated or added (CRUD). These objects are described in the Home API Domain Model. The Object Entities transport the runtime data like state values of devices, functions or individual configurations. The following diagram show some relation between the different entities.

image

Main Entities

The table below provides a high-level description of the entities contained in the generic domain model:

Main Entity Description
Product A product describes an add-in module, which can be enabled for the system. It will introduce new instances of other domain model objects to the system like new device types with their capabilities.
Device The device contains all relevant information regarding the physical device, e.g. its firmware version, type, manufacturer.
Capability The capability represents a function of a device. It contains the attributes like state of a switch or the current temperature.
Event An event transports information about system changes like state or configuration change of a capability or device discovery. These are send via the WebSocket connection. Details for the Event entity can be found in the WebSocket section .
Action An action exposes product/device/capability specific functions, which can be triggered directly or used as building blocks for rules.
Message A message is a standalone entity, which contains either system wide information or is associated to any of the other main entities like a battery low warning.
Interaction Defines the interaction or relationship between two or more devices. It contains one or more rules.
Location The location represents an entity, which allows the assignment of a device or capability to a certain location in the home.
Subscription The subscription represents an entity used to manage notifications received from the system.
Status This entity is represents aggregated information about various components and states like API version, gateway general information, etc.
ClientStorage The ClientStorage represents an entity used to offer a client a static blob storage.
UserStorage The UserStorage represents an entity used to offer a blob within the user scope. It can be used to store e.g. favorites or sortings.
SmartCode This entity represents SmartCode that can be used to provision/update buyable Products.

Sub Entities

In addition, some generic sub entities exist which are used within the main entities containing further data, descriptions or links between the main entities. The following sub entities are part of the model:

Sub Entity Description
Property The property entity is to transport the runtime data within a main entity. In addition, it is also used in the meta data to describe the content of the runtime data for a given entity.
Container A main entity can have multiple named containers, which include a list of sub entities of the same type, e.g. list of links to capabilities of a device.
Rule A rule describes the details of the relationship between two or more devices. A rule consists of triggers, constraints and device actions.
Trigger A Trigger is used in rules and defines the triggering event for evaluating a rule on the controller.
Condition A Condition is a logical expression, which constrains the execution of an action defined in the rule.
Function A Function is used in the definition of rules, to define the desired behaviour in triggers, in conditions and actions for a rule.
Parameter Parameters are used in functions to specify additional input for the execution of a function or actions.