-
Notifications
You must be signed in to change notification settings - Fork 24
Conventions
As the HomA framework is designed to incorporate a large number of heterogenous components, there are several assumptions to which these components have to adhere.
Each component is identified by a unique SystemId.
The SystemId is relevant in two cases. The first is, to store component settings in the /sys branch. In this case the SystemId acts as a namespace for settings keys. The second case where the SystemId is of importance is when creating a component that shows controls in an interface. Here the SystemId acts as a namespace for controls so that changes to a control's value are received by the corresponding component only.
Currently, SystemIds consist of six random numbers, followed by a dash and the component's name. Following this schema, a SystemId for the demo component would be 293723-demo.
Generally, there is nothing that enforces SystemIds to be generated according to the preceding recommendation, or the usage of unique SystemIds at all. When using any of the official components, it's probably save to assume that the default SystemId that each component uses is unique however when developing own components or running multiple instances of a component it's the developer's job to configure working SystemIds to be able to distinguish between the individual components.
To ease starting components and minimize locations where data is stored, only the broker host, broker port and SystemId should provided through command-line arguments while configuration files should avoided whenever possible. The gist is that once a component can connect to the broker, it can publish and subscribe to additional settings below the topic tree that is defined by it's SystemId at /sys/$SystemId/.
Thus, when starting two components with the same SystemId, they will share the same settings. Respectively, will have access to two individual settings namespaces once they have different SystemIds. For example, to observe two different Google Calendars, the calendar component has to be started twice with two different SystemIds, so that two different values for the config parameter calendarId can be stored at /sys/$SystemId1/calendarId and /sys/$SystemId2/calendarId.
Generally, data of a component that should be displayed to the user, such as the temperature reading of a sensor, is tailored to the control of a device such as a weather station. Thereby, each device might have an unlimited number of controls. Depending on the type of a control it's value is represented by a different interface element.
The basic building blocks for any interface are devices that can house 1-n controls. Controls live under the topic tree /devices/$SystemId/controls/$DeviceUniqueControlId/. Thereby, a the SystemId maps the controls to a component. In any interface, the component is thus represented as a device with an id that matches the component's SystemId. While each device takes the SystemId as a default name, of course a canonical, non-unique name can be set.
As there is no dedicated database from which interfaces might fetch their data, the topics below have to be published with an MQTT retained flag so that interfaces can receive their initial value once they connect to the system.
- Canonical device name
/devices/$SystemId/meta/name - Device room
/devices/$SystemId/meta/room - Control value (Component->Interface)
/devices/$SystemId/controls/$deviceUniqueControlId/on - Control value (Interface->Component)
/devices/$SystemId/controls/$deviceUniqueControlId - Control type
/devices/$SystemId/controls/$deviceUniqueControlId/meta/type - Control order
/devices/$SystemId/controls/$deviceUniqueControlId/meta/order - Control maximum value
/devices/$SystemId/controls/$deviceUniqueControlId/meta/max - Control unit
/devices/$SystemId/controls/$deviceUniqueControlId/meta/unit
Generally, interfaces subscribe to the topic /devices/$SystemId/controls/$deviceUniqueControlId to receive new values of a device's control. Triggered by a user interaction they publish new values of a control to the topic /devices/$SystemId/controls/$deviceUniqueControlId/on to which the control is subscribed.
It is the obligation of the component that should handle the change of topic values to publish the changed value back to /devices/$SystemId/controls/$deviceUniqueControlId so all other connected interfaces can reflect the change and the recent value is persisted for future clients. The reason for this is to prevent any interface or actor from receiving an echo of their own publish and to just display a changed value if it has been handled successfully by an component.
An control's ordering can be changed by publishing an arbitrary integer value to /devices/$SystemId/controls/$deviceUniqueControlId/meta/order. A device's controls are sorted by the order meta attribute from low to high, while the default order value is 0.
An optional unit can be set for control values to /devices/$SystemId/controls/$deviceUniqueControlId/meta/unit, e.g. " °C". Default is empty.
As a rule of thumb interfaces subscribe to the following topics to receive required information
- Device meta information (room, name, etc.)
/devices/+/meta/# - Control meta information (type, max, etc.)
/devices/+/controls/+/meta/# - Control values
/devices/+/controls/+
The meta topic /devices/$SystemId/controls/$deviceUniqueControlId/meta/type defines different types of controls that decide which interface is shown to the user.
A read-only control that displays it's value as text.
- Meta topic value: text
- Possible values: Anything
A control that toggles it's value when pressed by the user.
- Meta topic value: switch
- Possible values: 0 or 1
A range slider that takes integer values between 0 and any other integer that is greater 1
- Meta topic value: range
- Possible values: 0 - max
- Default max: 255
Different values can be set by publishing an arbitrary integer that is greater than 1 to
/devices/$SystemId/controls/$deviceUniqueControlId/meta/max.
Current events, such as the scanning of an NFC tag or the change of the suns position that should trigger actions e.g. through the rules component should be published at the topic tree /events/$eventName with a value such as the name of the scanned tag.