-
-

Device types

-

Device type represents a single entity in the Home Assistant panel. -It can be a sensor, lock, camera or anything that’s listed in the table below.

-

Your physical device (for example ESP-01 board) can have multiple device types assigned. -They will be displayed as child entities in the HA panel.

+
+

Device types (entities)

+

Device type represents a single entity within the Home Assistant panel, which could be a sensor, lock, camera, or any other item listed in the table below.

+

Your physical device, such as an ESP-01 board, can have multiple device types assigned to it. +These types will then appear as child entities in the Home Assistant panel.

+
+

Identifiers

+

Home Assistant utilizes three distinct identifiers, which might initially appear confusing. +Grasping the purpose of each is crucial for a clear understanding of the library’s API.

+
+

Entity ID

+

Home Assistant automatically generates an entity ID for each device type registered by your device. +This ID is primarily utilized by dashboards and automations within Home Assistant.

+

When the entity is discovered by Home Assistant for the first time, the name field is automatically employed to generate the entity ID. +Once registered, you can modify it to any desired value using the Home Assistant User Interface.

+

Home Assistant internally relies on the unique ID, so changing the entity ID or name in the Home Assistant UI does not break the integration between your device and Home Assistant.

+
+
+

Object ID

+

The object ID is an optional identifier that you can assign to the device type. +Its sole purpose is for generating the entity ID described above.

+

By default, Home Assistant generates the entity ID based on the entity’s name. +However, when the object ID is provided, Home Assistant uses it to generate the entity ID.

+

Consequently, you can use the entity’s name as a user-friendly label and the object ID as an internal identifier.

+
+
+

Unique ID

+

The unique ID serves as an internal identifier for the entity within the Home Assistant instance. +Once the entity with a specific unique ID is created, it cannot be altered, as this identifier is not accessible through the user interface.

+

Home Assistant utilizes this identifier internally to store the parameters of the entity in the database. +Given that the unique ID must be unique across the entire Home Assistant instance. +Multiple devices cannot expose entities with the same unique ID.

+

By default, the library uses the unique ID provided in the device type’s constructor. +However, when you reuse the same codebase on multiple devices, conflicts may arise. +To address this issue, you can enable the extended unique ID feature in the HADevice instance. +This feature incorporates the device’s unique ID as a prefix for the device type’s ID.

+
+
Default behavior
+
#include <Ethernet.h>
+#include <ArduinoHA.h>
+
+byte mac[] = {0x00, 0x10, 0xFA, 0x6E, 0x38, 0x4A};
+
+EthernetClient client;
+HADevice device(mac, sizeof(mac)); // the unique ID of the device will be 0010fa6e384a
+HAMqtt mqtt(client, device);
+
+// "myValve" is unique ID of the sensor. You should define your own ID.
+HASensor valve("myValve");
+
+void setup() {
+    // ...
+
+    valve.setIcon("mdi:home");
+    valve.setName("Water valve");
+
+    // the unique ID of the valve in HA will be "myValve"
+
+    // ...
+}
+
+void loop() {
+    // ...
+}
+
+
+
+
+
Extended unique IDs
+
#include <Ethernet.h>
+#include <ArduinoHA.h>
+
+byte mac[] = {0x00, 0x10, 0xFA, 0x6E, 0x38, 0x4A};
+
+EthernetClient client;
+HADevice device(mac, sizeof(mac)); // the unique ID of the device will be 0010fa6e384a
+HAMqtt mqtt(client, device);
+
+// "myValve" is unique ID of the sensor. You should define your own ID.
+HASensor valve("myValve");
+
+void setup() {
+    // ...
+
+    device.enableExtendedUniqueIds(); // <------------ enables extended unique IDs
+    valve.setIcon("mdi:home");
+    valve.setName("Water valve");
+
+    // the unique ID of the valve in HA will be "0010fa6e384a_myValve"
+
+    // ...
+}
+
+void loop() {
+    // ...
+}
+
+
+
+
+

Limitations

-

Registering a new device type requires some flash and RAM memory to be utilized. -On less powerful units like Arduino Uno, you may quickly hit the limit of resources, so keeping the device simple is recommended. -Hitting the resource limit will result in random reboots of the device.

-

By default, the maximum number of device types is 6. +

Registering a new device type involves utilizing a certain amount of flash and RAM memory. +On less powerful units, such as the Arduino Uno, you may rapidly reach the resource limit. +Therefore, it is advisable to keep the device simple to avoid hitting the resource limit, which could lead to random reboots of the device.

+

By default, devices utilizing ATmega328P or ATmega168 processors are limited to a maximum of 6 device types, while other platforms can support up to 24 device types. You can increase the limit using the HAMqtt class constructor as follows:

#include <Ethernet.h>
 #include <ArduinoHA.h>
@@ -165,7 +261,7 @@ You can increase the limit using the byte mac[] = {0x00, 0x10, 0xFA, 0x6E, 0x38, 0x4A};
 EthernetClient client;
 HADevice device(mac, sizeof(mac));
-HAMqtt mqtt(client, device, 12); // <------------ 12 is a new limit of device types
+HAMqtt mqtt(client, device, 40); // <------------ 40 is a new limit of device types
 
 void setup() {
     Ethernet.begin(mac);
@@ -198,30 +294,38 @@ You can increase the limit using the 
Binary sensor

+
Alarm control panel

+
❌

+
–

+
+
Binary sensor

 
✅

 
HABinarySensor

 
-
Button

+
Button

 
✅

 
HAButton

 
-
Camera

+
Camera

 
✅

 
HACamera

 
-
Cover

+
Cover

 
✅

 
HACover

 
-
Device tracker

+
Device tracker

 
✅

 
HADeviceTracker

 
-
Device trigger

+
Device trigger

 
✅

 
HADeviceTrigger

 
+
Event

+
❌

+
–

+
 
Fan

 
✅

 
HAFan

@@ -234,52 +338,76 @@ You can increase the limit using the HAHVAC

 
-
Light

+
Lawn mower

+
❌

+
–

+
+
Light

 
✅

 
HALight

 
-
Lock

+
Lock

 
✅

 
HALock

 
-
Number

+
Number

 
✅

 
HANumber

 
-
Scene

+
Scene

 
✅

 
HAScene

 
-
Select

+
Select

 
✅

 
HASelect

 
-

+

 
Sensor (text)

 

 
 
✅

 
HASensor

 
-

+

 
Sensor (number)

 

 
 
✅

 
HASensorNumber

 
+
Siren

+
❌

+
–

+
 
Switch

 
✅

 
HASwitch

 
-
Tag scanner

+
Update

+
❌

+
–

+
+
Tag scanner

 
✅

 
HATagScanner

 
+
Text

+
❌

+
–

+
 
Vacuum

 
❌

 
–

 
+
Valve

+
❌

+
–

+
+
Water heater

+
❌

+
–

+
diff --git a/docs/documents/library/discovery.html b/docs/documents/library/discovery.html index 93dacab..d057935 100644 --- a/docs/documents/library/discovery.html +++ b/docs/documents/library/discovery.html @@ -24,7 +24,7 @@ - + @@ -102,7 +102,7 @@
  • Availability reporting
  • Connection parameters
  • Discovery
    • -
  • Device types
    • +
  • Device types (entities)
  • MQTT security
  • MQTT advanced features
  • Compiler macros
    • @@ -114,6 +114,7 @@
  • Utils API
    • +
  • Sponsor