Skip to content

Commit eaf3edc

Browse files
EPNWDavid Gräff
EPNW
authored and
David Gräff
committed
Extension Convention (#171)
* Talk about extensions * Renamed and removed files regarding extensions, updated convention.md (#171) * Revised to meta extension
1 parent 9ac3433 commit eaf3edc

5 files changed

+329
-2
lines changed

‎convention.md

+6-2
Original file line numberDiff line numberDiff line change
@@ -314,9 +314,13 @@ Any other topic is not part of the Homie convention.
314314
This convention only covers discoverability of devices and its capabilities.
315315
The aim is to have standardized MQTT topics for all kind of complex scenarios.
316316
A Homie device may therefore support extensions, defined in separate documents.
317-
Every extension is identified by a unique ID and will be linked from this section.
317+
Every extension is identified by a unique ID.
318318

319319
The ID consists of the reverse domain name and a freely chosen suffix.
320320
The proper term `homie` is reserved and must not be used as the suffix or as part of the domain name.
321321

322-
For example, an organization `example.org` wanting to add a feature `our-feature` would choose the extension ID `org.example.our-feature`.
322+
For example, an organization `example.org` wanting to add a feature `our-feature` would choose the extension ID `org.example.our-feature`.
323+
324+
Every extension must be published using a license.
325+
The license can be chosen freely, even proprietary licenses are possible.
326+
The recommended license is the [CCA 4.0](https://homieiot.github.io/license), since this is the license Homie itself uses.

‎extensions/documents/homie_legacy _stats_extension.md

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Legacy Stats
2+
3+
Version: **<!--VERSION-->0.1.1<!--VERSION-->**
4+
Date: **<!--DATE-->12. Jul 2019<!--DATE-->**
5+
Authors: **<!--AUTHORS-->The Homie Community<!--AUTHORS-->**
6+
License: **<!--LICENSE-->[CCA 4.0](https://homieiot.github.io/license)<!--LICENSE-->**
7+
8+
## Abstract
9+
This extension adds the stats functionality of Homie `3.0.1` to Homie `4.0`.
10+
11+
Version `3.0.1` of the Homie Convention specifies, how device stats should be published.
12+
The community decided, that in subsequent versions of the convention, this feature should be optional,
13+
so it was removed from the convention and decided to offer it as extension (see [issue 102](https://github.com/homieiot/convention/issues/102)).
14+
If a device of a newer Homie version implements this extension, the stats of the device are backwards-compatible to older Homie versions.
15+
Respectively, the *$stats* attribute of an older device can be made Homie `4.0` compliant, by simply advertising this extension as implemented.
16+
By doing this, the legacy *$stats* attribute can be kept, and the device doesn't have to be altered much.
17+
In addition to this extension, a second extension, [Legacy Firmware]() exists.
18+
If this extension is implemented, too, not only the stats are backwards-compatible, but the whole device.
19+
20+
## Homie Version
21+
This extension supports Homie `4.x`.
22+
23+
## Extension Identifier
24+
The ID of this extension is `org.homie.legacy-stats`.
25+
Therefore the **$extensions entry** is `org.homie.legacy-stats:0.1.1:[4.x]`.
26+
27+
## Extension Datatypes
28+
This extension defines no new datatypes.
29+
30+
## Extension Attributes
31+
32+
### Device Attributes
33+
34+
This extension defines no direct device attributes.
35+
36+
#### Nested Device Attributes
37+
38+
This extension defines one nested device attribute.
39+
40+
##### $stats
41+
The **$stats** nesting attribute is **required**.
42+
43+
It defined **two required** nested attributes:
44+
45+
| Topic | Description | Payload type |
46+
|-----------------|-------------------------------------------------------------------------|----------------------------|
47+
| $stats/interval | Interval in seconds at which the device refreshes its `$stats/+` | Positive Integer greater 0 |
48+
| $stats/uptime | Time elapsed in seconds since the boot of the device | Positive Integer |
49+
50+
**Examples**
51+
Assuming the base topic is *homie* and device ID is *super-car* then:
52+
```java
53+
homie/super-car/$stats/interval → "60"
54+
homie/super-car/$stats/uptime → "120"
55+
```
56+
Every *$stats/interval* the device MUST publish new values for each implemented nested **$stats** attribute (except *$stats/interval* itself).
57+
This includes the required *$stats/uptime*.
58+
The following **optional** nested stats attributes exists. If they where used once, they also MUST be refreshed:
59+
60+
| Topic | Description | Payload type |
61+
|-----------------|---------------------------------------------------------------------|------------------|
62+
| $stats/signal | Signal strength in % | Integer |
63+
| $stats/cputemp | CPU Temperature in °C | Float |
64+
| $stats/cpuload | CPU Load in %. Average of last *$stats\interval* including all CPUs | Integer |
65+
| $stats/battery | Battery level in % | Integer |
66+
| $stats/freeheap | Free heap in bytes | Positive Integer |
67+
| $stats/supply | Supply Voltage in V | Float |

‎extensions/documents/homie_legacy_firmware_extension.md

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Legacy Firmware
2+
3+
Version: **<!--VERSION-->0.1.1<!--VERSION-->**
4+
Date: **<!--DATE-->12. Jul 2019<!--DATE-->**
5+
Authors: **<!--AUTHORS-->The Homie Community<!--AUTHORS-->**
6+
License: **<!--LICENSE-->[CCA 4.0](https://homieiot.github.io/license)<!--LICENSE-->**
7+
8+
## Abstract
9+
This extension adds the firmware, mac and localip device attributes of Homie `3.0.1` to Homie `4.0`.
10+
11+
Version `3.0.1` of the Homie Convention specifies some required device attributes.
12+
Newer versions on the other hand, do not specify them.
13+
If a device of a newer Homie version implements this extension, the above mentioned attributes are backwards-compatible to older Homie versions.
14+
Respectively, these attributes of an older device can be made Homie `4.0` compliant, by simply advertising this extension as implemented.
15+
By doing this, these legacy attribute can be kept, and the device doesn't have to be altered much.
16+
In addition to this extension, a second extension, [Legacy Stats]() exists.
17+
If this extension is implemented, too, not only the firmware attributes are backwards-compatible, but the whole device.
18+
19+
## Homie Version
20+
This extension supports Homie `4.x`.
21+
22+
## Extension Identifier
23+
The ID of this extension is `org.homie.legacy-firmware`.
24+
Therefore the **$extensions entry** is `org.homie.legacy-firmware:0.1.1:[4.x]`.
25+
26+
## Extension Datatypes
27+
This extension defines no new datatypes.
28+
29+
## Extension Attributes
30+
31+
### Device Attributes
32+
33+
This extension defines **no optional** and **two required** direct device attributes:
34+
35+
| Topic | Description | Payload type |
36+
|----------|-------------------------------------------------------------------------------------------------|-----------------|
37+
| $localip | IP of the device on the local network | String |
38+
| $mac | Mac address of the device network interface; The format MUST be of the type `A1:B2:C3:D4:E5:F6` | String |
39+
40+
**Examples**
41+
Assuming the base topic is *homie* and device ID is *super-car* then:
42+
```java
43+
homie/super-car/$localip → "192.168.0.10"
44+
homie/super-car/$mac → "DE:AD:BE:EF:FE:ED"
45+
```
46+
47+
#### Nested Device Attributes
48+
49+
This extension defines one nested device attribute.
50+
51+
##### $fw
52+
53+
The **$fw** nesting attribute is **required**.
54+
55+
It defines **no optional** and **two required** nested attributes:
56+
57+
| Topic | Description | Payload type |
58+
|-------------|----------------------------------------------------------------------------------------------|--------------|
59+
| $fw/name | Name of the firmware running on the device; Allowed characters are the same as the device ID | String |
60+
| $fw/version | Version of the firmware running on the device | String |
61+
62+
**Examples**
63+
Assuming the base topic is *homie* and device ID is *super-car* then:
64+
```java
65+
homie/super-car/$fw/name → "weatherstation-firmware"
66+
homie/super-car/$fw/version → "1.0.0"
67+
```

‎extensions/documents/homie_meta_extension.md

+99
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Meta
2+
3+
Version: **<!--VERSION-->1.1.0<!--VERSION-->**
4+
Date: **<!--DATE-->12. Jul 2019<!--DATE-->**
5+
Authors: **<!--AUTHORS-->[EPNW](https://epnw.eu)<!--AUTHORS-->**
6+
License: **<!--LICENSE-->[CCA 4.0](https://homieiot.github.io/license)<!--LICENSE-->**
7+
8+
## Abstract
9+
This extension defines how to add metadata and tags to devices, nodes and properties.
10+
11+
Tags are simple annotations that every device, node oder property can have.
12+
Metadata on the other hand are more complex. They allow the definition of multiple *mainkeys* and *mainvalues* for each device, node or property.
13+
Each main-key-value-pair may have nested sub-key-value-pairs.
14+
Having metadata might be useful for Homie controllers.
15+
A concrete usecase is the openHAB controller, which relies on metadata and tags to make voice assistants like Amazons Alexa or the Google Assistant able to control it.
16+
With this extension, properties are able to advertise how they want to be treated.
17+
18+
## Homie Version
19+
This extension supports Homie `3.0.1` and `4.x`.
20+
21+
## Extension Identifier
22+
The ID of this extension is `eu.epnw.meta`.
23+
Therefore the **$extensions entry** is `eu.epnw.meta:1.1.0:[3.0.1;4.x]`.
24+
25+
## Extension Datatypes
26+
This extension defines no new datatypes.
27+
28+
## Extension Attributes
29+
30+
### Extension Attributes for any kind of Items
31+
32+
The following attributes are all **optional** and may be added to any kind of item (devices, nodes or properties).
33+
34+
| Topic | Description | Payload type | Default value|
35+
|----------------------|-----------------------------|----------------------------|--------------|
36+
| $tags | List of *tags* for the item | Comma (`,`) separated list | |
37+
| $meta/$mainkey-ids | List of IDs for *mainkeys* | Comma (`,`) separated list | |
38+
39+
Since *tags* are represented by a comma separated list, a limitation is that a tag itself MUST NOT contain a comma.
40+
The elements in the `$mainkey-ids` list are **not** the names of the keys.
41+
Instead, these entries are just used for topic IDs.
42+
Therefore, the entries have to be valid topic IDs (see [the Homie convention](https://homieiot.github.io/specification/#topic-ids))!
43+
44+
**Examples**
45+
Assuming the base topic is *homie*, device ID is *super-car*, the node is *engine* and the property is *temperature* then:
46+
```java
47+
homie/super-car/engine/temperature/$meta/$mainkey-ids → "alexa,homekit"
48+
homie/super-car/engine/temperature/$tags → "Lighting,Switchable,Thermostat"
49+
```
50+
51+
For each element in the `$mainkey-ids` list, two nested attributes are **required**:
52+
53+
| Topic | Description | Payload type |
54+
|---------------------------|-----------------------------------|--------------|
55+
| $meta/*mainkey id*/$key | The *mainkey*s name | String |
56+
| $meta/*mainkey id*/$value | The *mainvalue* for the *mainkey* | String |
57+
58+
**Examples**
59+
With respect to the previous example:
60+
```java
61+
homie/super-car/engine/temperature/$meta/0/$key → "HomeKit"
62+
homie/super-car/engine/temperature/$meta/0/$value → "Fan.v2"
63+
homie/super-car/engine/temperature/$meta/1/$key → "Alexa"
64+
homie/super-car/engine/temperature/$meta/1/$value → "Fan"
65+
```
66+
67+
Notice that in this example, the *mainkey ids* are *alexa* and *homekit*, but the actual key names are *Alexa* and *HomeKit*.
68+
69+
A *mainkey* can have an arbitrary number of *subkeys*.
70+
Analogous to how *mainkeys* are advertised, each *mainkey* may have an **optional** list of *subkey ids*:
71+
72+
| Topic | Description | Payload type | Default value |
73+
|-------------------------------|--------------------------------------------|--------------|---------------|
74+
| $meta/*mainkey id*/$subkey-ids | List of IDs for *subkeys* | Comma (`,`) separated list | |
75+
76+
Again, elements in the `$subkey-ids` list are **not** the names of the keys, and have to be valid topic IDs.
77+
78+
**Examples**
79+
With respect to the previous example:
80+
```java
81+
homie/super-car/engine/temperature/$meta/alexa/$subkey-ids → "type,step-speed"
82+
```
83+
84+
For each element in the `$subkey-ids` list, two nested attributes are **required**:
85+
86+
| Topic | Description | Payload type |
87+
|---------------------------------------|--------------------------------------|--------------|
88+
| $meta/*mainkey id*/*subkey id*/$key | The *subkey*s name | String |
89+
| $meta/*mainkey id*/*subkey id*/$value | Value for the *subkey* | String |
90+
91+
92+
**Examples**
93+
With respect to the previous example:
94+
```java
95+
homie/super-car/engine/temperature/$meta/alexa/type/$key → "type"
96+
homie/super-car/engine/temperature/$meta/alexa/type/$value → "oscillating"
97+
homie/super-car/engine/temperature/$meta/alexa/step-speed/$key → "stepSpeed"
98+
homie/super-car/engine/temperature/$meta/alexa/step-speed/$value → "3"
99+
```

‎extensions/extension_template.md

+90
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Name of the Extension
2+
3+
Version: **<!--VERSION-->x.x.x<!--VERSION-->**
4+
Date: **<!--DATE-->01. Jan 2000<!--DATE-->**
5+
Authors: **<!--AUTHORS-->Your Name or Organization<!--AUTHORS-->**
6+
License: **<!--LICENSE-->[CCA 4.0](https://homieiot.github.io/license)<!--LICENSE-->**
7+
8+
## Abstract
9+
The abstract of an extension document should consist of two paragraphs.
10+
11+
The first one should be very short, only one or two sentences and serves as a short description of the extension.
12+
The second paragraph should be longer and should explain the intention of an extension.
13+
This is the extension template document.
14+
It is used to create an extension according to the [Homie Extension Convention]().
15+
"A Homie device may therefore support extensions, defined in separate documents. Every extension is identified by a unique ID and will be linked from this section"<sup>\[1\]</sup>.
16+
The above was a quote from the Homie Convention to illustrate the usage of the [Attribution](#Attribution) section.
17+
18+
## Homie Version
19+
This extension supports Homie `3.0.1` and `4.x`.
20+
21+
## Extension Identifier
22+
The ID of this extension is `org.example.our-feature`.
23+
Therefore the **$extensions entry** is `org.example.our-feature:x.x.x:[3.0.1;4.x]`.
24+
25+
## Extension Datatypes
26+
This extension defines one new datatype.
27+
28+
### Vector
29+
- Vector payload validity varies depending on the property format definition
30+
- Vector types are represented in format (f<sub>1</sub>,...,f<sub>n</sub>) where f<sub>1</sub> to f<sub>n</sub> are string literal representations of 64-bit signed floating point numbers
31+
- Vector entries range from 2<sup>-1074</sup> to (2-2<sup>-52</sup>)&ast;2<sup>1023</sup>
32+
- An empty string ("") is not a valid payload
33+
34+
#### Vector format
35+
- The format of a Vector type specifies its mathematical dimension `n`
36+
- Therefor the format has to be a natrual number greater then 0
37+
38+
## Extension Attributes
39+
40+
### Device Attributes
41+
42+
This extension defines no device attributes.
43+
44+
### Node Attributes
45+
This extension defines no direct node attributes.
46+
47+
#### Nested Node Attributes
48+
49+
This extension defines one nested node attribute.
50+
51+
##### $coordinate-system
52+
53+
The **$coordinate-system** nesting attribute is **optional**.
54+
If its used, it defines one **required** nested attribute:
55+
56+
| Topic | Description | Payload type |
57+
|---------------------------------------|---------------------------------------------------|------------------------------------|
58+
| $coordinate-system/$handedness | Handedness of the coordinate system. | Enum: \[left_handed,right_handed\] |
59+
60+
**Examples**
61+
Assuming the base topic is *homie*, device ID is *super-car* and node is *wheels* then:
62+
```java
63+
homie/super-car/wheels/$coordinate-system/$handedness → "left_handed"
64+
```
65+
66+
If the **$coordinate-system** nesting attribute is used, following nested attributes are **optional**.
67+
Not that the following table has a `Default value` row. Only tables for **optional** attributes have this row.
68+
69+
| Topic | Description | Payload type | Default value|
70+
|---------------------------------------|---------------------------------------------------|------------------------------------|--------------|
71+
| $coordinate-system/$first-axis-name | Name of the first axis of the coordinate system. | String | "x-Axis" |
72+
| $coordinate-system/$second-axis-name | Name of the second axis of the coordinate system. | String | "y-Axis" |
73+
| $coordinate-system/$third-axis-name | Name of the third axis of the coordinate system. | String | "z-Axis" |
74+
| $coordinate-system/$axis-unit | The unit of the coordinate axis | String | |
75+
76+
**Examples**
77+
Assuming the base topic is *homie*, device ID is *super-car* and node is *wheels* then:
78+
```java
79+
homie/super-car/wheels/$coordinate-system/$first-axis-name → "Pitch"
80+
homie/super-car/wheels/$coordinate-system/$second-axis-name → "Yaw"
81+
homie/super-car/wheels/$coordinate-system/$third-axis-name → "Roll"
82+
homie/super-car/wheels/$coordinate-system/$axis-unit → "meter"
83+
```
84+
85+
### Property Attributes
86+
87+
This extension defines no property attributes.
88+
89+
## Attribution
90+
- <sup>\[1\]</sup>: [The Homie Convention](https://homieiot.github.io/specification/#), [CCA 4.0](https://homieiot.github.io/license)

0 commit comments

Comments
 (0)