Changes

Changes from v4.0.0 to develop

Commits

Commit title	Date	Hash
fix(step): add calculations for step rounding (#313)	2024-12-09 07:54:48 +0100	c782375
fix(json): default should be an escaped json string (#308)	2024-11-19 13:04:17 +0100	f029eca
change(version): remove ‘higher’ constraint (#304)	2024-10-27 19:32:53 +0100	db70d60
minor clarification in the base-topic (#303)	2024-10-17 10:22:43 +0200	063301d
fix(enum): no duplicates (#302)	2024-10-13 01:27:34 +0200	aee10f3
chor(node/prop): make ’name’ optional (#300)	2024-09-07 13:33:16 +0200	7cfd0b5
fix: color encoding and brightness (#298)	2024-09-04 22:17:02 +0200	86f35d9
chore(convention): minor cleanup and consistency updates	2024-07-06 14:23:54 +0200	0d7baf5
Trigger website deployment on convention changes (#293)	2024-07-04 10:25:15 +0200	ce4f54a
fix(logging): one level up in doc structure	2024-07-03 14:54:46 +0200	ce5e371
chore(headings): move some headings	2024-06-30 11:05:43 +0200	63f21bd
Correct topic pattern for empty string payload (#288)	2024-02-17 18:20:16 +0200	133c6b8
homie5(alerts): replace ‘alert’ state with alert-topic (#283)	2023-11-15 23:38:52 +0100	eb0b437
fix(target): equality of received commands (#277)	2023-11-13 11:23:55 +0100	3715512
homie5(type): add type field for device and node (#282)	2023-11-05 12:12:29 +0100	11f0378
chore(state): add some more details around state management (#272)	2023-11-05 10:59:14 +0100	b314544
fix(broadcast): broadcasted messages should be non-retained (#280)	2023-11-05 10:48:22 +0100	ed50bc6
feat(unit): add ‘rpm’ (revolutions per minute) (#279)	2023-11-05 10:47:22 +0100	1331fcc
Added information about unpublishing/removing a device (#278)	2023-11-05 10:45:02 +0100	250d31a
fix(log): clarify all messages must be non-retained (#276)	2023-07-26 13:52:23 +0200	c8201c8
feat(color): allow to set a preferred format (#275)	2023-07-06 11:07:52 +0200	6eb4639
feat(json-type): add a JSON data type (#273)	2023-06-25 20:01:12 +0200	566a2d6
feat(log): change “alert” state, add logging (#262)	2023-06-25 15:13:31 +0200	adc710e
feat(property): add an optional $target property (#263)	2023-06-25 14:29:22 +0200	611ec27
clarify(enum): clarify that whitesapce is significant (#268)	2023-06-25 10:00:24 +0200	4bb1287
chore(id): simplify ID checks (#261)	2023-06-24 12:08:34 +0200	da23e1f
change(description): change arrays to objects (#270)	2023-06-24 12:08:17 +0200	015b328
feat(format): add color format ‘xyz’ (#274)	2023-06-24 12:07:55 +0200	1c15005
fix(validation): specify float/int validation order (#269)	2023-06-18 20:06:37 +0200	13e241e
fix(hierarchy): root device should not have root (#271)	2023-06-18 20:05:06 +0200	d6b4ad8
chore(properties): align the 3 property tables in the spec (#267)	2023-06-16 11:28:17 +0200	35837c2
chore(format): reformat table (flip-axis) for readability (#266)	2023-06-16 09:28:16 +0200	dbff282
fix(example): no description update in ‘ready’ state (#265)	2023-06-15 09:32:00 +0200	06446c0
fix(format): properly format the integer format template (#264)	2023-06-15 00:23:36 +0200	c1a58ce
chore(spec): spelling corrections (#260)	2023-06-15 00:13:04 +0200	9fa98ce
fix(base-topic): some occurences of homie/5/ were missing (#259)	2023-03-19 13:58:20 +0100	6afa235
feat(formats): add step size to integer/float formats (#257)	2023-03-17 13:45:02 +0100	953a1e2
feat(units): add airquality units; ppm (co2 / co)	2023-03-12 13:20:46 +0100	da5f1b4
feat(units): add windspeed units; m/s + knots	2023-03-07 11:10:07 +0100	ce7a3ee
fix(utf8): more explicit encoding details	2023-03-07 11:01:06 +0100	edf94b1
change(description-doc): relax language about omitting defaults (#258)	2023-03-17 13:42:05 +0100	67e0ad7
feat(units): add recommended units (#254)	2023-03-04 15:29:08 +0100	2fe6f7a
change(QoS) clarify QoS settings and switch to 2 (#253)	2023-01-26 10:32:56 +0100	063578d
refactor(mqtt) relocate all info wrt retained and qos (#252)	2023-01-26 10:30:50 +0100	c3f03bf
fix(strings) use 0x00 instead of 0x00 (#251)	2023-01-19 07:46:58 +0100	158b873
fix(version) device example missing required attribute (#250)	2023-01-18 23:20:50 +0100	d59d163
feat(version) add version to description document	2023-01-18 00:12:25 +0100	4accccd
feat(versioning) add improved versioning and compatibility	2023-01-17 23:29:52 +0100	4d10316
fix(property) handling empty-string values (#239)	2023-01-17 23:39:16 +0100	734d6ff
change(formats) float-colors, improved numbers, add booleans	2023-01-17 07:46:27 +0100	7e50cb1
feat(units) add kW, kWh and m3 as units	2023-01-17 06:50:42 +0100	0f8439f
readability(retained) reorder more logically (#245)	2023-01-17 09:11:35 +0100	1f73c11
fix(device) be more specific about empty attributes (#242)	2023-01-16 23:24:07 +0100	f974349
describe parent-child hierarchy and handling (#240)	2023-01-16 23:23:29 +0100	11dc08a
fix(percent) drop the percent type (#243)	2023-01-16 23:21:58 +0100	0155f38
drop node.$type field (#238)	2023-01-16 20:12:34 +0100	1c39612
format required for enum and color types	2023-01-15 22:06:14 +0100	e2e8ce7
drop separate v5 version	2023-01-15 21:18:09 +0100	5a34283
readability; move long payload list to bottom of MQTT chapter	2023-01-15 19:40:58 +0100	9641bd0
minor description-size improvements	2023-01-15 02:08:15 +0100	80f1772
implement single description topic (JSON)	2022-11-27 21:44:27 +0100	c97eea9
added 4.0 as the new 5.0 basis document	2022-11-27 20:22:51 +0100	1e0ec36
fix(device) be more specific about empty attributes (#241)	2023-01-16 23:22:30 +0100	451c995
chore(*) add design principles (#234)	2023-01-15 19:20:56 +0100	c0ba283
clarify $format being required for enum and color (#224)	2023-01-15 19:13:51 +0100	bb5efc7
chore(LICENSE): rename to get markdown rendering (#230)	2022-10-06 18:36:48 +0200	fd95584
Update logo link	2022-10-06 15:58:44 +0200	84c1c13
Fix: Added negative values to the valid range specification for floats	2021-01-25 04:17:45 -0500	fc643d6
Add datetime and duration to datatype enum.	2020-06-28 12:42:22 +0200	1b3efa4
Update convention.md	2020-05-11 07:38:16 -0500	dd6ee8e
Update convention.md	2020-05-11 07:31:26 -0500	449d952
Add implementation details and other things (#200)	2020-05-06 13:21:50 +0200	6d852df
clarify broadcast topics	2020-05-05 12:50:47 -0500	d68076d
added duration property	2020-05-05 12:34:17 -0500	9905706
clarify percentage values	2020-05-04 11:14:07 -0500	8824393
ready state clarification	2020-04-28 13:20:44 -0500	2c41d72
added datetime payload	2020-04-28 13:10:21 -0500	b813a15
clarification on allowed characters in topic ID	2020-04-26 11:09:58 -0500	2c28a5e
Fix: Grammar fix (#187)	2020-01-03 03:26:12 -0600	6f3f98a

Differences

	v4.0.0			develop
n	3	version: v4.0.0	n	3	version: develop
	4	releasedate: 27. August 2019		4	releasedate: 09. December 2024
n	18	A topic level ID MAY contain lowercase letters from `a` to `z`, numbers from `0` to `9` as well as the hyphen character (`-`).	n	18	A topic level ID MAY ONLY contain lowercase letters from `a` to `z`, numbers from `0` to `9` as well as the hyphen character (`-`).
n	20	A topic level ID MUST NOT start or end with a hyphen (`-`).	n
n			n	22	### QoS and retained messages
				23
				24	The recommended QoS level is **Exactly once (QoS 2)** (except for non-retained, see below).
				25
				26	* All messages MUST be sent as **retained**, UNLESS stated otherwise.
				27	* Controllers setting values for device properties publish to the Property `set` topic with **non-retained** messages only.
				28	* Controllers setting values for **non-retained** device properties should publish to the Property `/set` topic with a QoS of **At most once (QoS 0)**.
				29	* Devices publishing values for their **non-retained** properties must use **non-retained** messages, with a QoS of **At most once (QoS 0)**.
				30
				31	For QoS details see [the explanation](#qos-choices-explained).
				32
				33	### Last Will
				34
				35	Homie requires the last will (LWT) to set the `homie` / `5` / `[device ID]` / `$state` attribute to the value **`lost`**, see [Device Lifecycle](#device-lifecycle).
				36	MQTT only allows one last will message per connection, but since a device can have children, the LWT message MUST be set on the
				37	root device (the device at the root of the parent-child tree).
				38
				39	### Empty string values
				40
				41	MQTT will treat an empty string payload as a "delete" instruction for the topic, therefor an
				42	empty string value is represented by a 1-character string containing a single byte value 0 (Hex: `0x00`, Dec: `0`).
				43
				44	The empty string (passed as an MQTT payload) can only occur in 3 places;
				45
				46	- `homie` / `5` / `[device ID]` / `[node ID]` / `[property ID]`; reported property values (for string types)
				47	- `homie` / `5` / `[device ID]` / `[node ID]` / `[property ID]` / `set`; the topic to set properties (of string types)
				48	- `homie` / `5` / `[device ID]` / `[node ID]` / `[property ID]` / `$target`; the target property value (for string types)
				49
				50	This convention specifies no way to represent an actual value of a 1-character string with a single byte 0. If a device
				51	needs this, then it should provide an escape mechanism on the application level.
				52
	23	### Payload		53	## Payloads
n			n	56	- The message MUST NOT include the UTF-8 [BOM](https://en.wikipedia.org/wiki/Byte_order_mark)
n	28	#### String	n	59	### String
n	31	- An empty string ("") is a valid payload	n	62	- An [empty string](#empty-string-values) ("") is a valid payload
n	33	#### Integer	n	64	### Integer
n	35	- Integer types are UTF-8 encoded string literal representations of 64-bit signed whole numbers	n	66	- Integer types are string literal representations of 64-bit signed whole numbers
n	39	- An empty string ("") is not a valid payload	n	70	- An [empty string](#empty-string-values) ("") is not a valid payload
n	41	#### Float	n	72	### Float
n	43	- Float types are UTF-8 encoded string literal representations of 64-bit signed floating point numbers	n	74	- Float types are string literal representations of 64-bit signed floating point numbers
	44	- Floats range from 2<sup>-1074</sup> to (2-2<sup>-52</sup>)&ast;2<sup>1023</sup>		75	- Floats range from +/-(2^-1074) to +/-((2 - 2^-52) * 2^1023)
n	49	- An empty string ("") is not a valid payload	n	80	- An [empty string](#empty-string-values) ("") is not a valid payload
n	51	#### Boolean	n	82	### Boolean
n	55	- An empty string ("") is not a valid payload	n	86	- An [empty string](#empty-string-values) ("") is not a valid payload
n	57	#### Enum	n	88	### Enum
n	61	- Payloads should have leading and trailing whitespace removed	n	92	- Leading- and trailing-whitespace is significant, e.g. "Car" will not match " Car".
	62	- An empty string ("") is not a valid payload		93	- An [empty string](#empty-string-values) ("") is not a valid payload
n	64	#### Color	n	95	### Color
n	66	- Color payload validity varies depending on the property format definition of either "rgb" or "hsv"	n	97	- Color payload validity varies depending on the property format definition of either "rgb", "hsv", or "xyz"
	67	- Both payload types contain comma separated whole numbers of differing restricted ranges		98	- All payload types contain comma-separated data of differing restricted ranges. The first being the type, followed by numbers. The numbers must conform to the [float](#float) format
	68	- The encoded string may only contain whole numbers and the comma character ",", no other characters are permitted, including spaces (" ")		99	- The encoded string may only contain the type, the [float](#float) numbers and the comma character ",", no other characters are permitted, including spaces (" ")
	69	- Payloads for type "rgb" contains 3 comma separated values of numbers with a valid range between 0 and 255. e.g. 100,100,100		100	- Payloads for type "rgb" contain 3 comma-separated values of [floats](#float) (`r`, `g`, `b`) with a valid range between 0 and 255 (inclusive). e.g. `"rgb,100,100,100"`
	70	- Payloads for type "hsv" contains 3 comma separated values of numbers. The first number has a range of 0 to 360, the second and third numbers have a range of 0 to 100. e.g. 300,50,75		101	- Payloads for type "hsv" contain 3 comma-separated values of [floats](#float). The first number (`h`) has a range of 0 to 360 (inclusive), and the second and third numbers (`s` and `v`) have a range of 0 to 100 (inclusive). e.g. `"hsv,300,50,75"`
				102	- Payloads for type "xyz" contain 2 comma separated values of [floats](#float) (`x`, `y`) with a valid range between 0 and 1 (inclusive). The "z" value can be calculated via `z=1-x-y` and is therefore not transmitted. (see [CIE_1931_color_space](https://en.wikipedia.org/wiki/CIE_1931_color_space)). e.g. `"xyz,0.25,0.34"`
				103	- *Note*: The `rgb` and `hsv` formats encode both color and brightness, whereas `xyz` only encodes the color, so;
				104	- when brightness encoding is required: do not use `xyz`, or optionally add another property for the brightness (such that setting `hsv` and `rgb` values changes both the color property and the brightness one if required)
				105	- if color only is encoded: ignore the `v` value in `hsv`, and use the relative colors of `rgb`
				106	eg. `color_only_r = 255 * r / max(r, g, b)`, etc.
	71	- An empty string ("") is not a valid payload		107	- An [empty string](#empty-string-values) ("") is not a valid payload
	72
n	74	### QoS and retained messages	n	109	### DateTime
n	76	The nature of the Homie convention makes it safe about duplicate messages, so the recommended QoS for reliability is **QoS 1**.	n	111	- DateTime payloads must use the ISO [8601 format](https://en.wikipedia.org/wiki/ISO_8601).
	77	All messages MUST be sent as **retained**, UNLESS stated otherwise.		112	- An [empty string](#empty-string-values) ("") is not a valid payload
n	79	### Last will	n	114	### Duration
n	81	MQTT only allows one last will message per connection.	n	116	- Duration payloads must use the [ISO 8601 duration format](https://en.wikipedia.org/wiki/ISO_8601#Durations)
	82	Homie requires the last will (LWT) to set the `homie` / `device ID` / `$state` attribute to the value **`lost`**, see [Device Lifecycle](#device-lifecycle).		117	- The format is `PTxHxMxS`, where:
	83	As a consequence a new MQTT connection to the broker is required per published device.		118	`P`: Indicates a period/duration (required).
				119	`T`: Indicates a time (required).
				120	`xH`: Hours, where `x` represents the number of hours (optional).
				121	`xM`: Minutes, where `x` represents the number of minutes (optional).
				122	`xS`: Seconds, where `x` represents the number of seconds (optional).
				123	- Examples: `PT12H5M46S` (12 hours, 5 minutes, 46 seconds), `PT5M` (5 minutes)
				124	- An [empty string](#empty-string-values) ("") is not a valid payload
n	85	## Base Topic	n	126	### JSON
n	87	The root topic in this document is `homie/`.	n	128	- Contains a JSON string for transporting complex data formats that cannot be exposed as single value attributes.
	88	If this root topic does not suit your needs (in case of, e.g., a public broker or because of branding),		129	- The payload MUST be either a JSON-Array or JSON-Object type, for other types the standard Homie types should be used.
	89	you can choose another.
n			n	131	## Domain and Root Topic
				132
				133	The root topic in this convention is `"homie/5/"`. It consists of 2 segments, the first being the homie-domain,
				134	and the second indicating the major version number of this convention.
				135	The homie-domain must be a single segment and defaults to `"homie"`. If it does not suit your needs (in case of,
				136	e.g., a public broker or because of branding), you can change the domain part. The second segment, containing the version, may not be customized. This allows controllers to subscribe to only the devices they are compatible with.
				137
				138	## Auto-Discovery
				139
	91	Homie controllers must by default perform auto-discovery on the wildcard topic "+/+/$homie".		140	Homie 5 controllers must by default perform auto-discovery on the wildcard topic `"+/5/+/$state"`.
	92	Controllers are free to restrict discovery to a specific root topic, configurable by the user.		141	Controllers are free to restrict discovery to a specific homie-domain, configurable by the user.
				142	A zero length payload published on the `$state` topic indicates a device removal, see [device lifecycle](#device-lifecycle).
n	94	## Topology	n	144	## Topology and structure
n	98	For example, a car, an Arduino/ESP8266 or a coffee machine.	n	148	For example, a car, an Arduino/ESP8266, or a coffee machine.
				149	Within the convention devices can be modelled to have children. For example, bridge
				150	devices; a zwave bridge device (the parent) exposes many child devices (the
				151	zwave devices). There is no depth limit set on additionally nested children.
n	103	For example, a car might expose a `wheels` node, an `engine` node and a `lights` node.	n	156	For example, a car might expose a `wheels` node, an `engine` node, and a `lights` node.
n	108	For example the `wheels` node might expose an `angle` property.	n	161	For example, the `wheels` node might expose an `angle` property.
	109	The `engine` node might expose a `speed`, `direction` and `temperature` property.		162	The `engine` node might expose a `speed`, `direction`, and `temperature` property.
n	114	Attributes are represented by topic identifier starting with `$`.	n	167	Attributes are represented by a topic identifier starting with `$`.
n	121	* `homie` / **`device ID`**: this is the base topic of a device.	n	174	* `homie` / `5` / **`[device ID]`**: this is the base topic of a device.
	122	Each device must have a unique device ID which adhere to the [ID format](#topic-ids).		175	Each device must have a unique device ID that adheres to the [ID format](#topic-ids).
n			n	179	The following topic structure will be used to expose the device attributes:
				180
	126	* `homie` / `device ID` / **`$device-attribute`**:		181	* `homie` / `5` / `[device ID]` / **`[$device-attribute]`**:
n	128	The following device attributes are mandatory and MUST be send, even if it is just an empty string.	n	183	Devices have the following attributes:
n	130	| Topic | Description |	n	185	| Attribute | Required | Description |
	131	|-------------|--------------------------------------------------------------------------:|		186	|-------------|----------|----------------------------------------------------------------|
	132	| $homie | The implemented Homie convention version |		187	| `$state` | yes | Reflects the current state of the device. See [Device Lifecycle](#device-lifecycle) |
	133	| $name | Friendly name of the device |		188	| `$description`| yes | The description document (JSON), describing the device, nodes, and properties of this device. **Important**: this value may only change when the device `$state` is either `init`, `disconnected`, or `lost`. |
	134	| $state | See [Device Lifecycle](#device-lifecycle) |		189	| `$log` | no | A topic that allows devices to log messages. See [Logging](#logging) |
	135	| $nodes | [Nodes](#nodes) the device exposes, separated by `,` for multiple ones. |
	136	| $extensions | Supported extensions, separated by `,` for multiple ones. |
n	138	Optional topics include:	n	191	The JSON description document is a JSON object with the following fields;
n	140	| Topic | Description |	n	193	| Field | Type | Required | Default | Nullable | Description |
	141	|-----------------|-------------------------------|		194	|-----------|--------------|----------|---------|----------|-------------|
	142	| $implementation | An identifier for the Homie implementation (example "esp8266") |		195	| `homie` |string | yes | | no | The implemented Homie convention version, without the "patch" level. So the format is `"5.x"`, where the `'x'` is the minor version. |
				196	| `version` | integer | yes | | no | The version of the description document. Whenever the document changes, a new version must be assigned. This does not need to be sequential, eg. a timestamp or a random number could be used. |
				197	| `nodes` |object | no | `{}` | no | The [Nodes](#nodes) the device exposes. An object containing the [Nodes](#nodes), indexed by their [ID](#topic-ids). Defaults to an empty object.|
				198	| `name` |string | no | [device-id] | no | Friendly name of the device. Defaults to the [ID](#topic-ids) of the device. |
				199	| `type` |string | no | | no | Type of Device. Please ensure proper namespacing to prevent naming collisions. |
				200	| `children` |array-strings | no | `[]` | no | Array of [ID](#topic-ids)'s of child devices. Defaults to an empty array.|
				201	| `root` |string | yes/no | | no | [ID](#topic-ids) of the root parent device. **Required** if the device is NOT the root device, MUST be omitted otherwise. |
				202	| `parent` |string | yes/no | same as `root`| no | [ID](#topic-ids) of the parent device. **Required** if the parent is NOT the root device. Defaults to the value of the `root` property. |
				203	| `extensions`|array-strings | no | `[]` | no | Array of supported extensions. Defaults to an empty array.|
n	144	For example, a device with an ID of `super-car` that comprises of a `wheels`, `engine` and a `lights` node would send:	n	205	For example, a device with an ID of `super-car` that comprises of a `wheels`, `engine`, and a `lights` node would send:
	145
n	147	homie/super-car/$homie → "2.1.0"	n
	148	homie/super-car/$name → "Super car"
	149	homie/super-car/$nodes → "wheels,engine,lights"
	150	homie/super-car/$implementation → "esp8266"
	151	homie/super-car/$state → "ready"		207	homie/5/super-car/$state → "init"
				208	homie/5/super-car/$description → following JSON document;
n			n	210	```json
				211	{
				212	"homie": "5.0",
				213	"name": "Supercar",
				214	"version": 7,
				215	"nodes": {
				216	"wheels": { ... },
				217	"engine": { ... },
				218	"lights": { ... }
				219	}
				220	}
				221	```
				222
				223	#### Device hierarchy
				224
				225	Devices can be organized in parent-child relationships. These are expressed via the device
				226	attributes `root`, `parent`, and `children`. In any parent-child tree, there is only one
				227	"root" device, which is the top-level device that has no parent, but only children.
				228
				229	Example: a ZWave bridge (`id = "bridge"`), which exposes a ZWave device with a dual-relay (`id = "dualrelay"`),
				230	which respectively control Light1 (`id = "light1"`) and Light2 (`id = "light2"`). So there are 4 devices in total.
				231	Then these are the attribute values:
				232
				233	| | id | children | root | parent |
				234	|--------------|-------------|----------------------|----------|-------------|
				235	| Zwave bridge | "bridge" | ["dualrelay"] | | |
				236	| Zwave relay | "dualrelay" | ["light1", "light2"] | "bridge" | |
				237	| First light | "light1" | | "bridge" | "dualrelay" |
				238	| Second light | "light2" | | "bridge" | "dualrelay" |
				239
				240	To monitor the state of child devices in this tree 2 topic subscriptions are needed. The `$state` attribute of the device itself, as well as the `$state` attribute of its root device.
				241	Because if the root device loses its connection to the MQTT server, the last will (LWT), will set its `$state` attribute to `"lost"`, but it will not update the child-device states. Hence the need for 2 topic subscriptions.
				242
				243	The `state` of any device should be determined as follows:
				244	| has a `root` set | `root` state | device state |
				245	|------------------|--------------|--------------|
				246	| no | n.a. | device state is the `$state` attribute of the device itself
				247	| yes | not `"lost"` | device state is the `$state` attribute of the device itself
				248	| yes | `"lost"` | device state is `"lost"` (`$state` attribute of the root device)
				249
n	156	The `$state` device attribute represents the current state of the device.	n	253	The `$state` device attribute represents the current state of the device. A device exists once a valid value is set in the `$state` attribute. It doesn't mean the device is complete and valid (yet), but it does mean it exists.
	157	There are 6 different states:		254
				255	There are 5 possible state values:
n	160	This state is optional, and may be sent if the device takes a long time to initialize, but wishes to announce to consumers that it is coming online.	n	258	This state is optional and may be sent if the device takes a long time to initialize, but wishes to announce to consumers that it is coming online.
	161	* **`ready`**: this is the state the device is in when it is connected to the MQTT broker, has sent all Homie messages and is ready to operate. A Homie Controller can assume default values for all optional topics.		259	A device may fall back into this state to do some reconfiguration.
				260	* **`ready`**: this is the state the device is in when it is connected to the MQTT broker and has sent all Homie messages describing the device attributes, nodes, properties, and their values. The device has subscribed to all appropriate `/set` topics and is ready to receive messages.
n	166	* **`lost`**: this is the state the device is in when the device has been "badly" disconnected.	n	265	* **`lost`**: this is the state the device is in when the device has been "badly" disconnected. **Important**: If a root-device `$state` is `"lost"` then the state of **every child device in its tree** is also `"lost"`.
	167	You must define this message as LWT.		266	You must define this message as the last will (LWT) for root devices.
	168	* **`alert`**: this is the state the device is when connected to the MQTT broker, but something wrong is happening. E.g. a sensor is not providing data and needs human intervention.		267
	169	You have to send this message when something is wrong.		268	In order to permanently remove a device the following steps should be performed in order:
				269	1. remove the retained `$state` attribute from the broker by publishing a zero length payload message to its topic. The device will cease to exist.
				270	2. any other retained attributes or property values should be cleared via the same method afterwards.
n	173	* `homie` / `device ID` / **`node ID`**: this is the base topic of a node.	n	274	* `homie` / `5` / `[device ID]` / **`[node ID]`**: this is the base topic of a node.
	174	Each node must have a unique node ID on a per-device basis which adhere to the [ID format](#topic-ids).		275	Each node must have a unique node ID on a per-device basis which adheres to the [ID format](#topic-ids).
n	178	* `homie` / `device ID` / `node ID` / **`$node-attribute`**:	n	279	There are no node attributes in MQTT topics for this level.
n	180	All listed attributes are **required**. A node attribute MUST be one of these:	n	281	The Node object itself is described in the `homie` / `5` / `[device ID]` / `$description` JSON document. The Node object has the following fields:
n	182	| Topic | Description |	n	283	| Field | Type | Required | Default | Nullable | Description |
	183	|-------------|-------------------------------------------------------------------------------------------|		284	|-------------|--------------|----------|---------|----------|-------------|
	184	| $name | Friendly name of the Node |		285	| `name` |string | no | [node-id] | no | Friendly name of the Node. Defaults to the [ID](#topic-ids) of the node. |
	185	| $type | Type of the node |		286	| `type` |string | no | | no | Type of Node. Please ensure proper namespacing to prevent naming collisions. |
	186	| $properties | Exposed properties, separated by `,` for multiple ones. |		287	| `properties`|object | no | `{}` | no | The [Properties](#properties) the Node exposes. An object containing the [Properties](#properties), indexed by their [ID](#topic-ids). Defaults to an empty object.|
n	188	For example, our `engine` node would send:	n	289	For example, our `engine` node would look like this:
n	190	```java	n	291	```json
	191	homie/super-car/engine/$name → "Car engine"		292	...
	192	homie/super-car/engine/$type → "V8"		293	"engine": {
	193	homie/super-car/engine/$properties → "speed,direction,temperature"		294	"name": "Car engine",
				295	"properties": {
				296	"speed": { ... },
				297	"direction": { ... },
				298	"temperature": { ... }
				299	}
				300	}
				301	...
n	198	* `homie` / `device ID` / `node ID` / **`property ID`**: this is the base topic of a property.	n	306	* `homie` / `5` / `[device ID]` / `[node ID]` / **`[property ID]`**: this is the base topic of a property.
	199	Each property must have a unique property ID on a per-node basis which adhere to the [ID format](#topic-ids).		307	Each property must have a unique property ID on a per-node basis which adheres to the [ID format](#topic-ids).
	200
	201	* A property payload (e.g. a sensor reading) is directly published to the property topic, e.g.:
	202	```java
	203	homie/super-car/engine/temperature → "21.5"
	204	```
	205
	206	* Properties can be **settable**.
	207	For example, you don't want your `temperature` property to be settable in case of a temperature sensor
	208	(like the car example), but to be settable in case of a thermostat.
	209
	210	* Properties can be **retained**.
	211	A property is retained by default. A non-retained property would be useful for momentary events (door bell pressed).
	212
	213	A combination of those flags compiles into this list:
	214
	215	* **retained + non-settable**: The node publishes a property state (temperature sensor)
	216	* **retained + settable**: The node publishes a property state, and can receive commands for the property (by controller or other party) (lamp power)
	217	* **non-retained + non-settable**: The node publishes momentary events (door bell pressed)
	218	* **non-retained + settable**: The node publishes momentary events, and can receive commands for the property (by controller or other party) (brew coffee)
	219
n	223	* `homie` / `device ID` / `node ID` / `property ID` / **`$property-attribute`**:	n	311	| Attribute | Required | Description |
	224
	225	The following attributes are required:
	226
	227	| Topic | Description | Payload type |
	228	|-----------|------------------------------------------------------|---------------------------------------------|		312	|-----------|----------|----------------------------------------------------------------|
	229	| $name | Friendly name of the property. | String |		313	| | yes | A property value (e.g. a sensor reading) is directly published to the property topic, e.g.: `homie/5/super-car/engine/temperature → "21.5"` |
	230	| $datatype | The data type. See [Payloads](#payloads). | Enum: \[integer, float, boolean,string, enum, color\] |		314	| `$target` | no | Describes an intended state change. The `$target` attribute must either be used for every value update (including the initial one), or it must never be used. |
n	232	The following attributes are optional:	n	316	The Property object itself is described in the `homie` / `5` / `device ID` / `$description` JSON document. The Property object has the following fields:
n	234	| Topic | Description | Payload type |	n	318	| Field | Type | Required | Default | Nullable | Description |
	235	|-----------|------------------------------------------------------|---------------------------------------------|		319	|-----------|--------------|----------|----------|----|---------|
	236	| $format | Specifies restrictions or options for the given data type | See below |		320	| `name` | string | no | [property-id] | no | Friendly name of the Property. Defaults to the [ID](#topic-ids) of the property. |
	237	| $settable | Settable (<code>true</code>). Default is read-only (<code>false</code>) | Boolean |		321	| `datatype`| string | yes | | no | The data type. See [Payloads](#payload). Any of the following values: `"integer", "float", "boolean", "string", "enum", "color", "datetime", "duration", "json"`. |
	238	| $retained | Non-retained (<code>false</code>). Default is Retained (<code>true</code>). | Boolean |		322	| `format` | string | see [formats](#formats) | see [formats](#formats) | no | Specifies restrictions or options for the given data type. |
	239	| $unit | Optional unit of this property. See list below. | String |		323	| `settable`| boolean | no | `false` | no | Whether the Property is settable. |
				324	| `retained`| boolean | no | `true` | no | Whether the Property is retained. |
				325	| `unit` | string | no | | no | Unit of this property. See [units](#units). |
n	241	For example, our `temperature` property would send:	n
n			n	328	For example, our `temperature` property would look like this in the device/node description document:
				329
				330	```json
				331	...
				332	"temperature": {
				333	"name": "Engine temperature",
				334	"unit": "°C",
				335	"datatype": "float",
				336	"format": "-20:120"
				337	}
				338	...
				339	```
				340	And the following MQTT topic with the reported property value:
n	244	homie/super-car/engine/temperature/$name → "Engine temperature"	n
	245	homie/super-car/engine/temperature/$settable → "false"
	246	homie/super-car/engine/temperature/$unit → "°C"
	247	homie/super-car/engine/temperature/$datatype → "float"
	248	homie/super-car/engine/temperature/$format → "-20:120"
	249	homie/super-car/engine/temperature → "21.5"		342	homie/5/super-car/engine/temperature → "21.5"
n	252	Format:	n	345	#### Settable and retained properties
n	254	* For `integer` and `float`: Describes a range of payloads e.g. `10:15`	n	347	Properties can be **settable** and/or **retained**. For example, you don't want your `temperature`
	255	* For `enum`: `payload,payload,payload` for enumerating all valid payloads.		348	property to be settable in case of a temperature sensor (like the car example), but it should be
	256	* For `color`:		349	settable in the case of a thermostat setpoint.
	257	- `rgb` to provide colors in RGB format e.g. `255,255,0` for yellow.		350
	258	- `hsv` to provide colors in HSV format e.g. `60,100,100` for yellow.		351	A property is retained by default. A non-retained property would be useful for momentary events
				352	(e.g. doorbell pressed). See also [QoS settings](#qos-and-retained-messages).
				353
				354	A combination of the **settable** and **retained** flags compiles into this list:
				355
				356	| retained | settable | description |
				357	|----------|----------|-------------|
				358	| yes | yes | The node publishes a property state and can receive commands for the property (by a controller or other party) (lamp power)
				359	| yes | no | (**default**) The node publishes a property state (temperature sensor)
				360	| no | yes | The node publishes momentary events and can receive commands for the property from a controller (brew coffee)
				361	| no | no | The node publishes momentary events (doorbell pressed)
				362
				363
				364	#### Formats
				365
				366	The format attribute specifies restrictions or options for the given data type. User interfaces can derive hints from
				367	the formats for displaying values.
				368
				369	| Type | Required | Default | Description |
				370	|--------------|----------|----------|-------------|
				371	| float | no | `:` | `[min]:[max][:step]` where min and max are the respective minimum and maximum (inclusive) allowed values, both represented in the format for [float types](#float). Eg. `10.123:15.123`. If the minimum and/or maximum are missing from the format, then they are open-ended, so `0:` allows a value >= 0.<br/>The optional `step` determines the step size, eg. `2:6:2` will allow values `2`, `4`, and `6`. It must be greater than 0. See notes below this table on calculations. |
				372	| integer | no | `:` | `[min]:[max][:step]` where min and max are the respective minimum and maximum (inclusive) allowed values, both represented in the format for [integer types](#integer). Eg. `5:35`. If the minimum and/or maximum are missing from the format, then they are open-ended, so `:10` allows a value <= 10. <br/>The optional `step` determines the step size, eg. `2:6:2` will allow values `2`, `4`, and `6`. It must be greater than 0. See notes below this table on calculations. |
				373	| enum | yes | | A comma-separated list of non-quoted values. Eg. `value1,value2,value3`. Leading- and trailing whitespace is significant. Individual values can not be an empty string, hence at least 1 value must be specified in the format. Duplicates are not allowed. |
				374	| color | yes | | A comma-separated list of color formats supported; `rgb`, `hsv`, and/or `xyz`. The formats should be listed in order of preference (most preferred first, least preferred last). See the [color type](#color) for the resulting value formats. E.g. a device supporting RGB and HSV, where RGB is preferred, would have its format set to `"rgb,hsv"`. |
				375	| boolean | no | `false,true` | Identical to an enum with 2 entries. The first represents the `false` value and the second is the `true` value. Eg. `close,open` or `off,on`. If provided, then both entries must be specified. **Important**: the format does NOT specify valid payloads, they are descriptions of the valid payloads `false` and `true`. |
				376	| json | no | `{\"anyOf\": [{\"type\": \"array\"},{\"type\": \"object\"}]}` | A [JSONschema](http://json-schema.org/) definition, which is added as a string (escaped), NOT as a nested json-object. See [JSON considerations](#json-considerations), for some ideas wrt compatibility. If a client fails to parse/compile the JSONschema, then it should ignore the given schema and fall back to the default schema.
				377
				378	**Note on numeric formats and step-sizes**:
				379
				380	The base for calculating a proper value based on `step` should be `min`, `max`, or the current property value (in that order). The implementation should round property values to the nearest step (which can be outside the min/max range). The min/max validation must be done after rounding. In case of integers, the input MUST already be a valid integer, before rounding to a step.
				381
				382	There is a caveat when rounding towards a step: if the value to be rounded, is less than the base then the intermediate values might round differently since proper mathematical rounding is done "away from 0". A positive 1.5 rounds to 2 (so up), and negative -1.5 rounds to -2 (so down), but both round "away from 0". Example showing the unexpected effect:
				383
				384	input | format | result | explanation
				385	-|-|-|-
				386	`5` | `"0:10:2"` | `6` | base = 0; result = round((5-base)/stepsize) * stepsize + base = 6
				387	`5` | `":10:2"` | `4` | base = 10; result = round((5-base)/stepsize) * stepsize + base = 4
				388
				389	To mitigate this do not use `round(x)`, but use `floor(x + 0.5)` instead. Such that rounding always goes up:
				390
				391	input | format | result | explanation
				392	-|-|-|-
				393	`5` | `"0:10:2"` | `6` | base = 0; result = floor((5-base)/stepsize + 0.5) * stepsize + base = 6
				394	`5` | `":10:2"` | `6` | base = 10; result = floor((5-base)/stepsize + 0.5) * stepsize + base = 6
				395
				396
				397	#### Units
n	262	* `°C`: Degree Celsius	n	401	* `°C`: Degree Celsius (see 'Degree' for encoding)
	263	* `°F`: Degree Fahrenheit		402	* `°F`: Degree Fahrenheit (see 'Degree' for encoding)
n			n	404	* Character '°' is [Unicode: `U+00B0`](https://www.compart.com/en/unicode/U+00B0), Hex: `0xc2 0xb0`, Dec: `194 176`
n	266	* `gal`: Galon	n	406	* `gal`: Gallon
n			n	409	* `kW`: Kilowatt
				410	* `kWh`: Kilowatt-hour
n			n	412	* `Hz`: Hertz
				413	* `rpm`: Revolutions per minute
n			n	416	* `m³`: Cubic meter
				417	* Character '³' is [Unicode: `U+00B3`](https://www.compart.com/en/unicode/U+00B3), Hex: `0xc2 0xb3`, Dec: `194 179`
n			n	419	* `m/s`: Meters per Second
				420	* `kn`: Knots
n			n	423	* `ppm`: Parts Per Million
				424	* `s`: Seconds
				425	* `min`: Minutes
				426	* `h`: Hours
				427	* `lx`: Lux
				428	* `K`: Kelvin
				429	* `MK⁻¹`: Mired
				430	* Character '⁻' is [Unicode: `U+207B`](https://www.compart.com/en/unicode/U+207B), Hex: `0xe2 0x81 0xbb`, Dec: `226 129 187`
				431	* Character '¹' is [Unicode: `U+00B9`](https://www.compart.com/en/unicode/U+00B9), Hex: `0xc2 0xb9`, Dec: `194 185`
n			n	434	The non-ASCII characters are specified as Unicode codepoints and the UTF-8 byte sequence that represents them. Since the same characters can be created in many visually similar ways it is important to stick to the exact byte sequences to enable proper interoperability.
				435
n			n	438	#### Target attribute
				439
				440	The `$target` attribute for properties allows a device to communicate an intended state change of a property. This serves 2 main
				441	purposes;
				442
				443	1. closing the control loop for a controller setting a value (if the property is settable).
				444	2. feedback in case a change is not instantaneous (e.g. a light that slowly dimms over a longer period, or a
				445	motorized valve that takes several minutes to fully open)
				446
				447	If implemented, then a device must first update the `$target` attribute, then start the transition (with
				448	optional state-value updates during the transition), and when done update the property value to match the
				449	`$target` value (functional equivalent, not necessarily a byte-by-byte equality).
				450
				451	If a new target is received (and accepted) from a controller by publishing to the property's `set` topic, then the exact value received must be published to the `$target` topic (byte-by-byte equality). To allow for closing the control loop.
				452
				453	**Notes:**
				454
				455	- a controller can only assume that the command it send to the `set` topic was received and accepted. Not necessarily that it will ever reach the target state, since if another controller updates the property again, it might never reach the target state.
				456	- The same goes for possible conversions (colors), rounding (number formats), etc. it will be very hard to check functional equivalence, since the value published may have a different format. So a controller should NOT implement a retry loop checking the final value. At best they should implement retries until the value set is being accepted.
				457	- Homie devices representing remote hardware (typically when bridging) should NOT set the `$target` attribute upon receiving a change from the hardware device. This is only allowed if the hardware explicitly distinguishes between current value and target value. This is to prevent a loop; e.g. a homie controller sets 100% as target, software instructs hardware to change, intermediate updates received from hardware; 20%, 40%, etc, should NOT overwrite the `$target` value, since that still is 100.
				458
				459
n	281	* `homie` / `device ID` / `node ID` / `property ID` / **`set`**: The device must subscribe to this topic if the property is **settable** (in case of actuators for example).	n	462	* `homie` / `5` / `[device ID]` / `[node ID]` / `[property ID]` / **`set`**: The device must subscribe to this topic if the property is **settable** (in the case of actuators for example).
n	283	A Homie controller publishes to the `set` command topic with non-retained messages only.	n	464	A Homie controller publishes to the `set` command topic with non-retained messages only. See [retained messages](#qos-and-retained-messages).
n	285	The assigned and processed payload must be reflected by the Homie device in the property topic `homie` / `device ID` / `node ID` / `property ID` as soon as possible.	n	466	The assigned and processed payload must be reflected by the Homie device in the property topic `homie` / `5` / `[device ID]` / `[node ID]` / `[property ID]` or target attribute `homie` / `5` / `[device ID]` / `[node ID]` / `[property ID]` / `$target` as soon as possible.
n	288	To give an example: A `kitchen-light` device exposing the `light` node with a settable `power` property subscribes to the topic `homie/kitchen-light/light/power/set` for commands:	n	469	To give an example: A `kitchen-light` device exposing the `light` node with a settable `power` property subscribes to the topic `homie/5/kitchen-light/light/power/set` for commands:
n	291	homie/kitchen-light/light/power/set ← "true"	n	472	homie/5/kitchen-light/light/power/set ← "true"
n	294	In response the device will turn on the light and upon success update its `power` property state accordingly:	n	475	In response, the device will turn on the light and upon success update its `power` property state accordingly:
n	297	homie/kitchen-light/light/power → "true"	n	478	homie/5/kitchen-light/light/power → "true"
n	300	## Broadcast Channel	n	481	If the `light` were a dimmable light with a `brightness` property (0-100%), and it would be set to slowly dim over 5 seconds, then the `$target` attribute can be used (assuming once per second updates);
n			n	483	```java
				484	homie/5/kitchen-light/light/brightness/set ← 100
				485	homie/5/kitchen-light/light/brightness/$target → 100
				486	homie/5/kitchen-light/light/brightness → 20 (after 1 second)
				487	homie/5/kitchen-light/light/brightness → 40 (after 2 seconds)
				488	homie/5/kitchen-light/light/brightness → 60 (after 3 seconds)
				489	homie/5/kitchen-light/light/brightness → 80 (after 4 seconds)
				490	homie/5/kitchen-light/light/brightness → 100 (after 5 seconds)
				491	```
				492
				493	## Alert topic
				494
				495	Devices can raise alerts. Alerts are user facing messages that have an ID, they can be set and removed.
				496	The alert topic is defined as;
				497
				498	* `homie` / `5` / `[device ID]` / `$alert` / `[alert ID]` → "alert message"
				499
				500	A device can raise a message on a specific ID. Once the alert is no longer usefull or has been resolved, it can be removed by deleting the topic. Alerts must be send as retained messages. The alert ID must have a valid [ID format](#topic-ids), where topic ID's starting with `$` are reserved for Homie usage.
				501
				502	Examples;
				503	```java
				504	/homie/5/mydevid/$alert/childlost = "Sensor xyz in livingroom hasn't reported updates for 3 hours"
				505	/homie/5/mydevid/$alert/battery = "Battery is low, at 8%"
				506	```
				507
				508	In the examples above, once the situation is resolved (the sensor comes back to live, or the batteries are replaced), the device will delete the topics again, indicating the alerts have been handled.
				509
				510	## Broadcast Topic
				511
	302	Homie defines a broadcast channel, so a controller is able to broadcast a message to all Homie devices:		512	Homie defines a broadcast topic, so a controller can broadcast a message to all Homie devices:
n	304	* `homie` / `$broadcast` / **`level`**: `level` is an arbitrary broadcast identifier.	n	514	* `homie` / `5` / `$broadcast` / **`[subtopic]`**: where `subtopic` can be any topic with single or multiple levels. Each segement must adhere to the [ID format](#topic-ids).
	305	It must adhere to the [ID format](#topic-ids).		515
				516	The messages SHOULD be non-retained.
n	312	homie/$broadcast/alert ← "Intruder detected"	n	523	homie/5/$broadcast/alert ← "Intruder detected"
				524	homie/5/$broadcast/security/alert ← "Intruder detected"
n	315	Any other topic is not part of the Homie convention.	n	527	## Logging
				528
				529	Since devices may be resource constraint they might not have logging capabilities. Homie provides a specific
				530	topic where devices can send log messages. The topic is defined as;
				531
				532	* `homie` / `5` / `[device ID]` / `$log` / `[level]`
				533
				534	The topic-value is the logged message, no sub-topics are allowed.
				535	All log messages send should be non-retained.
				536	The `level` is set according to the following table:
				537
				538	level | description
				539	--------|------------
				540	`debug` | detailed information for troubleshooting purposes
				541	`info` | informational message, device is working as expected
				542	`warn` | something potentially harmful happened
				543	`error` | an error happened, the device will continue to operate but functionality might be impaired
				544	`fatal` | a non-recoverable error occured, operation of the device is likely suspended/stopped
				545
				546	```java
				547	homie/5/my-device/$log/warn → "battery low"
				548	homie/5/my-device/$log/error → "sensor value is out of range"
				549	```
				550
				551	Note that MQTT is not meant to be a logging solution, and hence it should be used with care. The implementation should
				552	try and limit the traffic on the MQTT bus. If devices implement messages and levels that can be "noisy", then the
				553	device should provide a configuration option to turn them off, to limit the bandwidth consumed.
n	319	This convention only covers discoverability of devices and its capabilities.	n	557	This convention only covers the discoverability of devices and their capabilities.
	320	The aim is to have standardized MQTT topics for all kind of complex scenarios.		558	The aim is to have standardized MQTT topics for all kinds of complex scenarios.
n	325	The proper term `homie` is reserved and must not be used as the suffix or as part of the domain name.	n	563	The proper term `homie` is reserved and must not be used as a suffix or as part of the domain name.
n	331	The recommended license is the [CCA 4.0](https://homieiot.github.io/license), since this is the license Homie itself uses.	n	569	The recommended license is the [CCA 4.0](https://homieiot.github.io/license) since this is the license Homie itself uses.
t			t	572	## Implementation notes
				573
				574	### Device initialization
				575
				576	Some devices require knowledge of their settable retained properties to function properly.
				577	The homie convention does not specify how to initialize/recover them e.g. after a power cycle.
				578	A few common approaches are:
				579
				580	* A device can simply load default values from some configuration file.
				581	* A device can restore its previous state from some local storage. This is the recommended way.
				582	* A device may try to restore its state using MQTT. This can be done by subscribing to the respective channels.
				583	The controller could set all properties of a device once it becomes `ready`.
				584	An alternative way is to recover the state from other MQTT channels that are external to the Homie specification.
				585	* If a property is not critical for correctly functioning, there is no need to recover it.
				586
				587	### Device reconfiguration
				588
				589	If a device wishes to modify any of its nodes or properties, it can
				590
				591	* disconnect and reconnect with other values, or
				592	* set `$state=init` and then modify any of the attributes.
				593
				594	Devices can remove old properties and nodes by deleting the respective MQTT topics by publishing an empty message
				595	to those topics (an actual empty string on MQTT level, so NOT the escaped `0x00` byte, see also [empty string values](#empty-string-values)).
				596
				597	When adding many child devices, implementations should take care of not publishing too many parent-updates, since every controller would have to parse the description again and again.
				598
				599	#### Adding children
				600
				601	The recommended way to add child device is as follows:
				602
				603	1. first publish any child-devices, as any other device
				604	1. set child-device state to `"init"`
				605	1. publish child-device details (including parent details in `root` and `parent` fields)
				606	1. set child-device state to `"ready"`
				607	1. update the parent device, as any other change
				608	1. set parent state to `"init"`
				609	1. update parent description (add any child IDs to its `children` array)
				610	1. set parent state to `"ready"`
				611
				612	Be aware that due to MQTT message ordering the consistency at any stage in this process cannot be guaranteed.
				613
				614	#### Removing children
				615
				616	The recommended way to remove child device is as follows:
				617
				618	1. update the parent device
				619	1. set parent state to `"init"`
				620	1. update parent description (remove any child IDs from its `children` array)
				621	1. set parent state to `"ready"`
				622	1. clear any child-device(s) topics, starting with the `$state` topic
				623
				624	Be aware that due to MQTT message ordering the consistency at any stage in this process cannot be guaranteed.
				625
				626	### Versioning
				627
				628	Some considerations related to versioning in this specification;
				629
				630	* compatibility is assumed to be major version only, so version 5 for this spec.
				631	* the base topic includes the major version. This allows controllers to only subscribe to devices they are
				632	compatible with.
				633
				634	#### Backward compatibility
				635
				636	* backward compatibility: a v5 controller controlling a v5 device with a smaller minor version. Eg. a v5.3
				637	controller sending commands to a v5.0 device.
				638	* Controllers should be aware of unsupported features in older major or minor versions they subscribe to because the spec for that version is known.
				639
				640	#### Forward compatibility
				641
				642	* forward compatibility: a v5 controller controlling a v5 device with a higher minor version. Eg. a v5.0
				643	controller sending commands to a v5.2 device.
				644	* Controllers should ignore unknown fields, properties, attributes, etc. within an object (device, node, or property), but keep the object itself.
				645	* Controllers should ignore the entire object (device, node, or property) if in a known field, property, or attribute an illegal value is encountered. For example;
				646	* illegal characters in a topic or name
				647	* unknown data type
				648	* unknown/illegal format
				649	* required element missing
				650
				651	### JSON considerations
				652
				653	Validation of JSON payloads is hard. The most common approach to validate JSON data is to use [JSONschema](http://json-schema.org/).
				654	Unfortunately JSONschema is not a standard, it is a long list of mostly incompatible drafts of a potential standard. And as such one
				655	has to take into account the potential differences in implementations. This is about the JSONschema specifics itself as well as its reliance on RegEx engines for string validations, which are also known to be riddled with incompatibilities (typically language/platform specific).
				656
				657	The most popular JSONschema versions over time tend to be [`draft 4`](http://json-schema.org/specification-links.html#draft-4), [`draft 7`](http://json-schema.org/specification-links.html#draft-7) and the latest (at the time of writing) [`2020-12`](http://json-schema.org/specification-links.html#2020-12).
				658
				659	General recommendations;
				660	- If possible use a library that implements the latest JSONschema version available
				661	- When writing schema's make sure they are compatible with the popular versions mentioned above
				662	- Try to avoid RegEx'es, if you have to use them, then;
				663	- restrict them to character classes and modifiers (`"+", "-", "*", "?"`)
				664	- do not use back-tracking and OR (`"|"`) constructs (the OR construct can typically be handled on the JSONschema level using an `anyOf` construct)
				665	- If a device fails to parse the JSONschema, or a RegEx, then by default it should skip validation and assume the payload is valid.
				666
				667	### QoS choices explained
				668
				669	The nature of the Homie convention makes it safe about duplicate messages, so QoS levels for reliability **At least once (QoS 1)**
				670	and **Exactly once (QoS 2)** should both be fine. The recommended level is **Exactly once (QoS 2)**, since a resend on QoS 1 might have a different order, and hence is slightly less reliable, in case another device sends a new message that lands in between the 'send' and 'resend' of the first message. However, the probability of that happening is most likely negligible.
				671
				672	Keep in mind that if you change the QoS level to **At least once (QoS 1)**, then it should be done so for the entire Homie network.
				673	Because the MQTT order will not hold if the QoS levels of messages are different. That said; anyone who accepts the lesser reliability of
				674	**At least once (QoS 1)**, will most likely also not care about the potential ordering issue of mixed QoS levels.
				675
				676	For **non-retained** properties the QoS level is **At most once (QoS 0)** to ensure that events don't arrive late or multiple times. Because the events and commands are time-sensitive. With **At most once (QoS 0)** messages will not be queued by the broker for delivery if the subscriber (a device or controller) is currently disconnected. Which effectively translates to "either you get it now, or you don't get it at all".
				677
				678