ElixirForge/arduino-home-assistant
1
0
Fork 0
mirror of https://github.com/alexhopeoconnor/arduino-home-assistant.git synced 2026-10-04 02:48:13 +10:00
Code Releases Activity

Add support for extended unique IDs (#217)

Browse Source 
* implement unique ID serialization as flag

* finished extended unique IDs feature

* add tests

* update docs

* add funding.yml
This commit is contained in:
Dawid Chyrzyński
2024-02-05 16:20:40 +01:00
committed by GitHub
parent ab46939903
commit 80ae7ae592
51 changed files with 647 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/FUNDING.yml
+1
View File
@@ -0,0 +1 @@
github: dawidchyrzynski
CHANGELOG.md
+1
View File
@@ -5,6 +5,7 @@
**New features:**
* Added support for setting MQTT's keep alive ([https://github.com/dawidchyrzynski/arduino-home-assistant/issues/153](#153))
* Added support for the `state_class` property in the `HASensor` ([#179](https://github.com/dawidchyrzynski/arduino-home-assistant/pull/179) by [@https://github.com/Starzu])
* Implemented extended unique ID support for all device types. This allows you to prefix each device type's unique ID with the device ID, ensuring smooth deployment of identical code on multiple devices without encountering unique ID conflicts [#212](https://github.com/dawidchyrzynski/arduino-home-assistant/issues/212#issuecomment-1919832684)
**Fixes:**
* Fixed a bug with the maximum number of device types ([#190](https://github.com/dawidchyrzynski/arduino-home-assistant/issues/190) by [@martaisty](https://github.com/martaisty))
docs/_static/custom.css
Vendored
+4
View File
@@ -41,6 +41,10 @@ table.examples-table tbody td + td {
.searchbox .caption-text {
display: none
}
.code-block-caption {
margin-top: 30px;
font-weight: bold;
}
form {
display: flex;
flex-direction: row;
docs/_static/documentation_options.js
Vendored
+1 -1
View File
@@ -1,6 +1,6 @@
var DOCUMENTATION_OPTIONS = {
URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
VERSION: '2.0.0',
VERSION: '2.1.0',
LANGUAGE: 'None',
COLLAPSE_INDEX: false,
BUILDER: 'html',
docs/documents/api/core/ha-device.html
+18
View File
@@ -216,6 +216,12 @@
<dd><p>Returns true if the shared availability is enabled for the device. </p>
</dd></dl>
<dl class="cpp function">
<dt class="sig sig-object cpp" id="_CPPv4NK8HADevice26isExtendedUniqueIdsEnabledEv">
<span id="_CPPv3NK8HADevice26isExtendedUniqueIdsEnabledEv"></span><span id="_CPPv2NK8HADevice26isExtendedUniqueIdsEnabledEv"></span><span id="HADevice::isExtendedUniqueIdsEnabledC"></span><span class="target" id="class_h_a_device_1ad7e1673506833aa7072b4b604b20ecda"></span><span class="k"><span class="pre">inline</span></span><span class="w"> </span><span class="kt"><span class="pre">bool</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">isExtendedUniqueIdsEnabled</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><span class="w"> </span><span class="k"><span class="pre">const</span></span><a class="headerlink" href="#_CPPv4NK8HADevice26isExtendedUniqueIdsEnabledEv" title="Permalink to this definition"></a><br /></dt>
<dd><p>Returns true if the extended unique IDs feature is enabled for the device. </p>
</dd></dl>
<dl class="cpp function">
<dt class="sig sig-object cpp" id="_CPPv4NK8HADevice20getAvailabilityTopicEv">
<span id="_CPPv3NK8HADevice20getAvailabilityTopicEv"></span><span id="_CPPv2NK8HADevice20getAvailabilityTopicEv"></span><span id="HADevice::getAvailabilityTopicC"></span><span class="target" id="class_h_a_device_1ab508af42eb1fc0573a89afa3b92645fe"></span><span class="k"><span class="pre">inline</span></span><span class="w"> </span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">getAvailabilityTopic</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><span class="w"> </span><span class="k"><span class="pre">const</span></span><a class="headerlink" href="#_CPPv4NK8HADevice20getAvailabilityTopicEv" title="Permalink to this definition"></a><br /></dt>
@@ -228,6 +234,12 @@
<dd><p>Returns online/offline state of the device. </p>
</dd></dl>
<dl class="cpp function">
<dt class="sig sig-object cpp" id="_CPPv4N8HADevice23enableExtendedUniqueIdsEv">
<span id="_CPPv3N8HADevice23enableExtendedUniqueIdsEv"></span><span id="_CPPv2N8HADevice23enableExtendedUniqueIdsEv"></span><span id="HADevice::enableExtendedUniqueIds"></span><span class="target" id="class_h_a_device_1ad5634185083f02113ea68a357c16d228"></span><span class="k"><span class="pre">inline</span></span><span class="w"> </span><span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">enableExtendedUniqueIds</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N8HADevice23enableExtendedUniqueIdsEv" title="Permalink to this definition"></a><br /></dt>
<dd><p>Enables the use of extended unique IDs for all registered device types. The unique ID of each device type will be prefixed with the device’s ID once enabled. </p>
</dd></dl>
<dl class="cpp function">
<dt class="sig sig-object cpp" id="_CPPv4N8HADevice11setUniqueIdEPK4byteK8uint16_t">
<span id="_CPPv3N8HADevice11setUniqueIdEPK4byteK8uint16_t"></span><span id="_CPPv2N8HADevice11setUniqueIdEPK4byteK8uint16_t"></span><span id="HADevice::setUniqueId__byteCP.uint16_tC"></span><span class="target" id="class_h_a_device_1a8d10a57aa14007643ccdecd7c1a372a5"></span><span class="kt"><span class="pre">bool</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">setUniqueId</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">byte</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n sig-param"><span class="pre">uniqueId</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">uint16_t</span></span><span class="w"> </span><span class="n sig-param"><span class="pre">length</span></span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N8HADevice11setUniqueIdEPK4byteK8uint16_t" title="Permalink to this definition"></a><br /></dt>
@@ -358,6 +370,12 @@
<dd><p>Specifies whether the device is available (online / offline). </p>
</dd></dl>
<dl class="cpp var">
<dt class="sig sig-object cpp" id="_CPPv4N8HADevice18_extendedUniqueIdsE">
<span id="_CPPv3N8HADevice18_extendedUniqueIdsE"></span><span id="_CPPv2N8HADevice18_extendedUniqueIdsE"></span><span id="HADevice::_extendedUniqueIds__b"></span><span class="target" id="class_h_a_device_1ad330d3098dd3741669b09c6e98fa8a2c"></span><span class="kt"><span class="pre">bool</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">_extendedUniqueIds</span></span></span><a class="headerlink" href="#_CPPv4N8HADevice18_extendedUniqueIdsE" title="Permalink to this definition"></a><br /></dt>
<dd><p>Specifies whether extended unique IDs feature is enabled. </p>
</dd></dl>
</div>
</dd></dl>
docs/documents/api/utils/ha-serializer.html
+5
View File
@@ -199,6 +199,11 @@
<span id="_CPPv3N12HASerializer8FlagType16WithAvailabilityE"></span><span id="_CPPv2N12HASerializer8FlagType16WithAvailabilityE"></span><span class="target" id="class_h_a_serializer_1af48ac87d6107bdf5682c2f847fcc1c20ab6eb2bc6b231c4a431cd7124c4f3d9d8"></span><span class="k"><span class="pre">enumerator</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">WithAvailability</span></span></span><a class="headerlink" href="#_CPPv4N12HASerializer8FlagType16WithAvailabilityE" title="Permalink to this definition"></a><br /></dt>
<dd></dd></dl>
<dl class="cpp enumerator">
<dt class="sig sig-object cpp" id="_CPPv4N12HASerializer8FlagType12WithUniqueIdE">
<span id="_CPPv3N12HASerializer8FlagType12WithUniqueIdE"></span><span id="_CPPv2N12HASerializer8FlagType12WithUniqueIdE"></span><span class="target" id="class_h_a_serializer_1af48ac87d6107bdf5682c2f847fcc1c20a811d30832022e782d1d5a39fd48bd851"></span><span class="k"><span class="pre">enumerator</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">WithUniqueId</span></span></span><a class="headerlink" href="#_CPPv4N12HASerializer8FlagType12WithUniqueIdE" title="Permalink to this definition"></a><br /></dt>
<dd></dd></dl>
</dd></dl>
<dl class="cpp enum">
docs/documents/library/device-configuration.html
+11 -10
View File
@@ -149,11 +149,11 @@
<section id="device-configuration">
<h1>Device configuration<a class="headerlink" href="#device-configuration" title="Permalink to this headline"></a></h1>
<p><a class="reference internal" href="../api/core/ha-device.html"><span class="doc">HADevice</span></a> represents the physical device where the library is installed.
Logically it’s a group of types like sensors, switches, lights and so on.
In the Home Assistant, it’s listed with properties that may be configured using the library’s API.</p>
<p>Each property except the unique ID is optional.
Setting optional properties increases flash and RAM usage so it’s not recommended to set them on lower-spec MCUs.</p>
<p><a class="reference internal" href="../api/core/ha-device.html"><span class="doc">HADevice</span></a> represents the physical device on which the library is used.
Essentially, it’s a group of types such as sensors, switches, lights, and more.
Within Home Assistant, it appears with properties that can be configured using the library’s API.</p>
<p>Every property, except for the unique ID, is optional.
Enabling optional properties can lead to increased flash and RAM usage, therefore it is not advisable to set them on lower-spec MCUs.</p>
<p>The supported properties are:</p>
<ul class="simple">
<li><p>unique ID*</p></li>
@@ -164,10 +164,11 @@ Setting optional properties increases flash and RAM usage so it’s not recommen
</ul>
<section id="unique-id">
<h2>Unique ID<a class="headerlink" href="#unique-id" title="Permalink to this headline"></a></h2>
<p>The ID of a device needs to be unique in a scope of a Home Assistant instance.
The safest solution is to use the MAC address of an Ethernet or Wi-Fi chip but you can also implement your own solution.</p>
<p>There are three different ways to set the ID of the device.
You can pick one depending on your needs.</p>
<p>The unique ID serves as an internal identifier for devices within Home Assistant.
With this ID, Home Assistant can monitor the device’s parameters and the entities it exposes.
The unique ID must be distinct within the scope of the Home Assistant instance.
The recommended approach is to use the MAC address of an Ethernet or Wi-Fi chip.</p>
<p>There are three distinct methods for setting the device ID, allowing you to choose the one that best suits your requirements.</p>
<section id="providing-string-const-char-to-the-hadevice-constructor">
<h3>1) Providing string (const char*) to the <a class="reference internal" href="../api/core/ha-device.html"><span class="doc">HADevice</span></a> constructor<a class="headerlink" href="#providing-string-const-char-to-the-hadevice-constructor" title="Permalink to this headline"></a></h3>
<p>Try to keep the ID simple (alphanumeric characters) and short.</p>
@@ -227,7 +228,7 @@ You can pick one depending on your needs.</p>
<section id="device-properties">
<h2>Device properties<a class="headerlink" href="#device-properties" title="Permalink to this headline"></a></h2>
<p>Each property has its corresponding setter method in the <a class="reference internal" href="../api/core/ha-device.html"><span class="doc">HADevice</span></a> class.
Please note that all these methods accept const char pointer whose <strong>content is not copied</strong>.</p>
Please note that all of these methods accept a const char pointer whose <strong>content is not copied</strong>.</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;ArduinoHA.h&gt;</span><span class="cp"></span>
<span class="n">HADevice</span><span class="w"> </span><span class="nf">device</span><span class="p">(</span><span class="s">&quot;myUniqueId&quot;</span><span class="p">);</span><span class="w"></span>
docs/documents/library/device-types.html
+102 -7
View File
@@ -149,15 +149,110 @@
<section id="device-types">
<h1>Device types<a class="headerlink" href="#device-types" title="Permalink to this headline"></a></h1>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<section id="identifiers">
<h2>Identifiers<a class="headerlink" href="#identifiers" title="Permalink to this headline"></a></h2>
<p>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.</p>
<section id="entity-id">
<h3>Entity ID<a class="headerlink" href="#entity-id" title="Permalink to this headline"></a></h3>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</section>
<section id="object-id">
<h3>Object ID<a class="headerlink" href="#object-id" title="Permalink to this headline"></a></h3>
<p>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.</p>
<p>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.</p>
<p>Consequently, you can use the entity’s name as a user-friendly label and the object ID as an internal identifier.</p>
</section>
<section id="unique-id">
<h3>Unique ID<a class="headerlink" href="#unique-id" title="Permalink to this headline"></a></h3>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<div class="literal-block-wrapper docutils container" id="id1">
<div class="code-block-caption"><span class="caption-text">Default behavior</span><a class="headerlink" href="#id1" title="Permalink to this code"></a></div>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;Ethernet.h&gt;</span><span class="cp"></span>
<span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;ArduinoHA.h&gt;</span><span class="cp"></span>
<span class="n">byte</span><span class="w"> </span><span class="n">mac</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="mh">0x00</span><span class="p">,</span><span class="w"> </span><span class="mh">0x10</span><span class="p">,</span><span class="w"> </span><span class="mh">0xFA</span><span class="p">,</span><span class="w"> </span><span class="mh">0x6E</span><span class="p">,</span><span class="w"> </span><span class="mh">0x38</span><span class="p">,</span><span class="w"> </span><span class="mh">0x4A</span><span class="p">};</span><span class="w"></span>
<span class="n">EthernetClient</span><span class="w"> </span><span class="n">client</span><span class="p">;</span><span class="w"></span>
<span class="n">HADevice</span><span class="w"> </span><span class="nf">device</span><span class="p">(</span><span class="n">mac</span><span class="p">,</span><span class="w"> </span><span class="k">sizeof</span><span class="p">(</span><span class="n">mac</span><span class="p">));</span><span class="w"> </span><span class="c1">// the unique ID of the device will be 0010fa6e384a</span>
<span class="n">HAMqtt</span><span class="w"> </span><span class="nf">mqtt</span><span class="p">(</span><span class="n">client</span><span class="p">,</span><span class="w"> </span><span class="n">device</span><span class="p">);</span><span class="w"></span>
<span class="c1">// &quot;myValve&quot; is unique ID of the sensor. You should define your own ID.</span>
<span class="n">HASensor</span><span class="w"> </span><span class="nf">valve</span><span class="p">(</span><span class="s">&quot;myValve&quot;</span><span class="p">);</span><span class="w"></span>
<span class="kt">void</span><span class="w"> </span><span class="nf">setup</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="c1">// ...</span>
<span class="w"> </span><span class="n">valve</span><span class="p">.</span><span class="n">setIcon</span><span class="p">(</span><span class="s">&quot;mdi:home&quot;</span><span class="p">);</span><span class="w"></span>
<span class="w"> </span><span class="n">valve</span><span class="p">.</span><span class="n">setName</span><span class="p">(</span><span class="s">&quot;Water valve&quot;</span><span class="p">);</span><span class="w"></span>
<span class="w"> </span><span class="c1">// the unique ID of the valve in HA will be &quot;myValve&quot;</span>
<span class="w"> </span><span class="c1">// ...</span>
<span class="p">}</span><span class="w"></span>
<span class="kt">void</span><span class="w"> </span><span class="nf">loop</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="c1">// ...</span>
<span class="p">}</span><span class="w"></span>
</pre></div>
</div>
</div>
<div class="literal-block-wrapper docutils container" id="id2">
<div class="code-block-caption"><span class="caption-text">Extended unique IDs</span><a class="headerlink" href="#id2" title="Permalink to this code"></a></div>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;Ethernet.h&gt;</span><span class="cp"></span>
<span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;ArduinoHA.h&gt;</span><span class="cp"></span>
<span class="n">byte</span><span class="w"> </span><span class="n">mac</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="mh">0x00</span><span class="p">,</span><span class="w"> </span><span class="mh">0x10</span><span class="p">,</span><span class="w"> </span><span class="mh">0xFA</span><span class="p">,</span><span class="w"> </span><span class="mh">0x6E</span><span class="p">,</span><span class="w"> </span><span class="mh">0x38</span><span class="p">,</span><span class="w"> </span><span class="mh">0x4A</span><span class="p">};</span><span class="w"></span>
<span class="n">EthernetClient</span><span class="w"> </span><span class="n">client</span><span class="p">;</span><span class="w"></span>
<span class="n">HADevice</span><span class="w"> </span><span class="nf">device</span><span class="p">(</span><span class="n">mac</span><span class="p">,</span><span class="w"> </span><span class="k">sizeof</span><span class="p">(</span><span class="n">mac</span><span class="p">));</span><span class="w"> </span><span class="c1">// the unique ID of the device will be 0010fa6e384a</span>
<span class="n">HAMqtt</span><span class="w"> </span><span class="nf">mqtt</span><span class="p">(</span><span class="n">client</span><span class="p">,</span><span class="w"> </span><span class="n">device</span><span class="p">);</span><span class="w"></span>
<span class="c1">// &quot;myValve&quot; is unique ID of the sensor. You should define your own ID.</span>
<span class="n">HASensor</span><span class="w"> </span><span class="nf">valve</span><span class="p">(</span><span class="s">&quot;myValve&quot;</span><span class="p">);</span><span class="w"></span>
<span class="kt">void</span><span class="w"> </span><span class="nf">setup</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="c1">// ...</span>
<span class="w"> </span><span class="n">device</span><span class="p">.</span><span class="n">enableExtendedUniqueIds</span><span class="p">();</span><span class="w"> </span><span class="c1">// &lt;------------ enables extended unique IDs</span>
<span class="w"> </span><span class="n">valve</span><span class="p">.</span><span class="n">setIcon</span><span class="p">(</span><span class="s">&quot;mdi:home&quot;</span><span class="p">);</span><span class="w"></span>
<span class="w"> </span><span class="n">valve</span><span class="p">.</span><span class="n">setName</span><span class="p">(</span><span class="s">&quot;Water valve&quot;</span><span class="p">);</span><span class="w"></span>
<span class="w"> </span><span class="c1">// the unique ID of the valve in HA will be &quot;0010fa6e384a_myValve&quot;</span>
<span class="w"> </span><span class="c1">// ...</span>
<span class="p">}</span><span class="w"></span>
<span class="kt">void</span><span class="w"> </span><span class="nf">loop</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="c1">// ...</span>
<span class="p">}</span><span class="w"></span>
</pre></div>
</div>
</div>
</section>
</section>
<section id="limitations">
<h2>Limitations<a class="headerlink" href="#limitations" title="Permalink to this headline"></a></h2>
<p>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.</p>
<p>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.</p>
<p>By default, the maximum number of device types is 6.
You can increase the limit using the <a class="reference internal" href="../api/core/ha-mqtt.html"><span class="doc">HAMqtt</span></a> class constructor as follows:</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;Ethernet.h&gt;</span><span class="cp"></span>
docs/documents/library/index.html
+1
View File
@@ -173,6 +173,7 @@ Solid understanding of foundations will allow you to utilize full potential of t
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="device-types.html">Device types</a><ul>
<li class="toctree-l2"><a class="reference internal" href="device-types.html#identifiers">Identifiers</a></li>
<li class="toctree-l2"><a class="reference internal" href="device-types.html#limitations">Limitations</a></li>
<li class="toctree-l2"><a class="reference internal" href="device-types.html#supported-device-types">Supported device types</a></li>
</ul>
docs/genindex.html
+10 -2
View File
@@ -376,6 +376,8 @@
<li><a href="documents/api/core/ha-device.html#_CPPv4N8HADevice18_availabilityTopicE">HADevice::_availabilityTopic (C++ member)</a>
</li>
<li><a href="documents/api/core/ha-device.html#_CPPv4N8HADevice10_availableE">HADevice::_available (C++ member)</a>
</li>
<li><a href="documents/api/core/ha-device.html#_CPPv4N8HADevice18_extendedUniqueIdsE">HADevice::_extendedUniqueIds (C++ member)</a>
</li>
<li><a href="documents/api/core/ha-device.html#_CPPv4N8HADevice13_ownsUniqueIdE">HADevice::_ownsUniqueId (C++ member)</a>
</li>
@@ -384,6 +386,8 @@
<li><a href="documents/api/core/ha-device.html#_CPPv4N8HADevice19_sharedAvailabilityE">HADevice::_sharedAvailability (C++ member)</a>
</li>
<li><a href="documents/api/core/ha-device.html#_CPPv4N8HADevice9_uniqueIdE">HADevice::_uniqueId (C++ member)</a>
</li>
<li><a href="documents/api/core/ha-device.html#_CPPv4N8HADevice23enableExtendedUniqueIdsEv">HADevice::enableExtendedUniqueIds (C++ function)</a>
</li>
<li><a href="documents/api/core/ha-device.html#_CPPv4N8HADevice14enableLastWillEv">HADevice::enableLastWill (C++ function)</a>
</li>
@@ -398,6 +402,8 @@
<li><a href="documents/api/core/ha-device.html#_CPPv4N8HADevice8HADeviceEPK4byteK8uint16_t">HADevice::HADevice (C++ function)</a>, <a href="documents/api/core/ha-device.html#_CPPv4N8HADevice8HADeviceEPKc">[1]</a>, <a href="documents/api/core/ha-device.html#_CPPv4N8HADevice8HADeviceEv">[2]</a>
</li>
<li><a href="documents/api/core/ha-device.html#_CPPv4NK8HADevice11isAvailableEv">HADevice::isAvailable (C++ function)</a>
</li>
<li><a href="documents/api/core/ha-device.html#_CPPv4NK8HADevice26isExtendedUniqueIdsEnabledEv">HADevice::isExtendedUniqueIdsEnabled (C++ function)</a>
</li>
<li><a href="documents/api/core/ha-device.html#_CPPv4NK8HADevice27isSharedAvailabilityEnabledEv">HADevice::isSharedAvailabilityEnabled (C++ function)</a>
</li>
@@ -860,11 +866,11 @@
<li><a href="documents/api/device-types/ha-hvac.html#_CPPv4N6HAHVAC15TemperatureUnit11DefaultUnitE">HAHVAC::TemperatureUnit::DefaultUnit (C++ enumerator)</a>
</li>
<li><a href="documents/api/device-types/ha-hvac.html#_CPPv4N6HAHVAC15TemperatureUnit14FahrenheitUnitE">HAHVAC::TemperatureUnit::FahrenheitUnit (C++ enumerator)</a>
</li>
<li><a href="documents/api/device-types/ha-hvac.html#_CPPv4N6HAHVACD0Ev">HAHVAC::~HAHVAC (C++ function)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="documents/api/device-types/ha-hvac.html#_CPPv4N6HAHVACD0Ev">HAHVAC::~HAHVAC (C++ function)</a>
</li>
<li><a href="documents/api/device-types/ha-light.html#_CPPv47HALight">HALight (C++ class)</a>
</li>
<li><a href="documents/api/device-types/ha-light.html#_CPPv4N7HALight19_brightnessCallbackE">HALight::_brightnessCallback (C++ member)</a>
@@ -1442,6 +1448,8 @@
<li><a href="documents/api/utils/ha-serializer.html#_CPPv4N12HASerializer8FlagType16WithAvailabilityE">HASerializer::FlagType::WithAvailability (C++ enumerator)</a>
</li>
<li><a href="documents/api/utils/ha-serializer.html#_CPPv4N12HASerializer8FlagType10WithDeviceE">HASerializer::FlagType::WithDevice (C++ enumerator)</a>
</li>
<li><a href="documents/api/utils/ha-serializer.html#_CPPv4N12HASerializer8FlagType12WithUniqueIdE">HASerializer::FlagType::WithUniqueId (C++ enumerator)</a>
</li>
<li><a href="documents/api/utils/ha-serializer.html#_CPPv4NK12HASerializer5flushEv">HASerializer::flush (C++ function)</a>
</li>
docs/index.html
+1
View File
@@ -195,6 +195,7 @@ but I successfully use it on ESP8266/ESP8255 boards in my projects.</p>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="documents/library/device-types.html">Device types</a><ul>
<li class="toctree-l3"><a class="reference internal" href="documents/library/device-types.html#identifiers">Identifiers</a></li>
<li class="toctree-l3"><a class="reference internal" href="documents/library/device-types.html#limitations">Limitations</a></li>
<li class="toctree-l3"><a class="reference internal" href="documents/library/device-types.html#supported-device-types">Supported device types</a></li>
</ul>
docs/objects.inv
BIN
View File
Binary file not shown.
docs/searchindex.js
+1 -1
View File
File diff suppressed because one or more lines are too long
docsrc/README.md
+2 -5
View File
@@ -29,11 +29,8 @@ This solution forces `lxml` to be built from the sources.
## Generating the documentation
1. Open terminal in the `docsrc` directory
2. Run the Doxygen command `doxygen`
3. Open the Pipenv shell `pipenv shell`
4. Run the build `make html`
The generated documentation will be available in the `docsrc/build/html` directory.
2. Open the Pipenv shell `pipenv shell`
3. Run the build `make github`
## Github pages
docsrc/source/conf.py
+1 -1
View File
@@ -21,7 +21,7 @@ copyright = '2022, Dawid Chyrzynski'
author = 'Dawid Chyrzynski'
# The full version, including alpha/beta/rc tags
release = '2.0.0'
release = '2.1.0'
# -- General configuration ---------------------------------------------------
docsrc/source/documents/library/device-configuration.rst
+11 -10
View File
@@ -1,12 +1,12 @@
Device configuration
====================
:doc:`HADevice </documents/api/core/ha-device>` represents the physical device where the library is installed.
Logically it's a group of types like sensors, switches, lights and so on.
In the Home Assistant, it's listed with properties that may be configured using the library's API.
:doc:`HADevice </documents/api/core/ha-device>` represents the physical device on which the library is used.
Essentially, it's a group of types such as sensors, switches, lights, and more.
Within Home Assistant, it appears with properties that can be configured using the library's API.
Each property except the unique ID is optional.
Setting optional properties increases flash and RAM usage so it's not recommended to set them on lower-spec MCUs.
Every property, except for the unique ID, is optional.
Enabling optional properties can lead to increased flash and RAM usage, therefore it is not advisable to set them on lower-spec MCUs.
The supported properties are:
@@ -19,11 +19,12 @@ The supported properties are:
Unique ID
---------
The ID of a device needs to be unique in a scope of a Home Assistant instance.
The safest solution is to use the MAC address of an Ethernet or Wi-Fi chip but you can also implement your own solution.
The unique ID serves as an internal identifier for devices within Home Assistant.
With this ID, Home Assistant can monitor the device's parameters and the entities it exposes.
The unique ID must be distinct within the scope of the Home Assistant instance.
The recommended approach is to use the MAC address of an Ethernet or Wi-Fi chip.
There are three different ways to set the ID of the device.
You can pick one depending on your needs.
There are three distinct methods for setting the device ID, allowing you to choose the one that best suits your requirements.
1) Providing string (const char*) to the :doc:`HADevice </documents/api/core/ha-device>` constructor
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -88,7 +89,7 @@ Device properties
-----------------
Each property has its corresponding setter method in the :doc:`HADevice </documents/api/core/ha-device>` class.
Please note that all these methods accept const char pointer whose **content is not copied**.
Please note that all of these methods accept a const char pointer whose **content is not copied**.
::
docsrc/source/documents/library/device-types.rst
+110 -7
View File
@@ -2,18 +2,121 @@
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.
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 (for example ESP-01 board) can have multiple device types assigned.
They will be displayed as child entities in the HA panel.
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.
.. code-block:: cpp
:caption: 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() {
// ...
}
.. code-block:: cpp
:caption: 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.
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, the maximum number of device types is 6.
You can increase the limit using the :doc:`HAMqtt </documents/api/core/ha-mqtt>` class constructor as follows:
docsrc/source/static/custom.css
+4
View File
@@ -41,6 +41,10 @@ table.examples-table tbody td + td {
.searchbox .caption-text {
display: none
}
.code-block-caption {
margin-top: 30px;
font-weight: bold;
}
form {
display: flex;
flex-direction: row;
src/HADevice.cpp
+2 -1
View File
@@ -9,7 +9,8 @@
_serializer(new HASerializer(nullptr, 5)), \
_availabilityTopic(nullptr), \
_sharedAvailability(false), \
_available(true) // device will be available by default
_available(true), \
_extendedUniqueIds(false)
HADevice::HADevice() :
_uniqueId(nullptr),
src/HADevice.h
+16
View File
@@ -60,6 +60,12 @@ public:
inline bool isSharedAvailabilityEnabled() const
{ return _sharedAvailability; }
/**
* Returns true if the extended unique IDs feature is enabled for the device.
*/
inline bool isExtendedUniqueIdsEnabled() const
{ return _extendedUniqueIds; }
/**
* Returns availability topic generated by the HADevice::enableSharedAvailability method.
* It can be nullptr if the shared availability is not enabled.
@@ -73,6 +79,13 @@ public:
inline bool isAvailable() const
{ return _available; }
/**
* Enables the use of extended unique IDs for all registered device types.
* The unique ID of each device type will be prefixed with the device's ID once enabled.
*/
inline void enableExtendedUniqueIds()
{ _extendedUniqueIds = true; }
/**
* Sets unique ID of the device based on the given byte array.
* Each byte is converted into a hex string representation, so the final length of the unique ID will be twice as given.
@@ -155,6 +168,9 @@ private:
/// Specifies whether the device is available (online / offline).
bool _available;
/// Specifies whether extended unique IDs feature is enabled.
bool _extendedUniqueIds;
};
#endif
src/device-types/HABinarySensor.cpp
+1 -1
View File
@@ -35,7 +35,7 @@ void HABinarySensor::buildSerializer()
_serializer = new HASerializer(this, 7); // 7 - max properties nb
_serializer->set(AHATOFSTR(HANameProperty), _name);
_serializer->set(AHATOFSTR(HAUniqueIdProperty), _uniqueId);
_serializer->set(HASerializer::WithUniqueId);
_serializer->set(AHATOFSTR(HADeviceClassProperty), _class);
_serializer->set(AHATOFSTR(HAIconProperty), _icon);
_serializer->set(HASerializer::WithDevice);
src/device-types/HAButton.cpp
+1 -1
View File
@@ -22,7 +22,7 @@ void HAButton::buildSerializer()
_serializer = new HASerializer(this, 8); // 8 - max properties nb
_serializer->set(AHATOFSTR(HANameProperty), _name);
_serializer->set(AHATOFSTR(HAUniqueIdProperty), _uniqueId);
_serializer->set(HASerializer::WithUniqueId);
_serializer->set(AHATOFSTR(HADeviceClassProperty), _class);
_serializer->set(AHATOFSTR(HAIconProperty), _icon);
src/device-types/HACamera.cpp
+1 -1
View File
@@ -29,7 +29,7 @@ void HACamera::buildSerializer()
_serializer = new HASerializer(this, 7); // 7 - max properties nb
_serializer->set(AHATOFSTR(HANameProperty), _name);
_serializer->set(AHATOFSTR(HAUniqueIdProperty), _uniqueId);
_serializer->set(HASerializer::WithUniqueId);
_serializer->set(AHATOFSTR(HAIconProperty), _icon);
_serializer->set(
AHATOFSTR(HAEncodingProperty),
src/device-types/HACover.cpp
+1 -1
View File
@@ -56,7 +56,7 @@ void HACover::buildSerializer()
_serializer = new HASerializer(this, 11); // 11 - max properties nb
_serializer->set(AHATOFSTR(HANameProperty), _name);
_serializer->set(AHATOFSTR(HAUniqueIdProperty), _uniqueId);
_serializer->set(HASerializer::WithUniqueId);
_serializer->set(AHATOFSTR(HADeviceClassProperty), _class);
_serializer->set(AHATOFSTR(HAIconProperty), _icon);
src/device-types/HADeviceTracker.cpp
+1 -1
View File
@@ -35,7 +35,7 @@ void HADeviceTracker::buildSerializer()
_serializer = new HASerializer(this, 7); // 7 - max properties nb
_serializer->set(AHATOFSTR(HANameProperty), _name);
_serializer->set(AHATOFSTR(HAUniqueIdProperty), _uniqueId);
_serializer->set(HASerializer::WithUniqueId);
_serializer->set(AHATOFSTR(HAIconProperty), _icon);
_serializer->set(
AHATOFSTR(HASourceTypeProperty),
src/device-types/HAFan.cpp
+1 -1
View File
@@ -57,7 +57,7 @@ void HAFan::buildSerializer()
_serializer = new HASerializer(this, 13); // 13 - max properties nb
_serializer->set(AHATOFSTR(HANameProperty), _name);
_serializer->set(AHATOFSTR(HAUniqueIdProperty), _uniqueId);
_serializer->set(HASerializer::WithUniqueId);
_serializer->set(AHATOFSTR(HAIconProperty), _icon);
if (_retain) {
src/device-types/HAHVAC.cpp
+1 -1
View File
@@ -185,7 +185,7 @@ void HAHVAC::buildSerializer()
_serializer = new HASerializer(this, 27); // 27 - max properties nb
_serializer->set(AHATOFSTR(HANameProperty), _name);
_serializer->set(AHATOFSTR(HAUniqueIdProperty), _uniqueId);
_serializer->set(HASerializer::WithUniqueId);
_serializer->set(AHATOFSTR(HAIconProperty), _icon);
if (_retain) {
src/device-types/HALight.cpp
+1 -1
View File
@@ -130,7 +130,7 @@ void HALight::buildSerializer()
_serializer = new HASerializer(this, 18); // 18 - max properties nb
_serializer->set(AHATOFSTR(HANameProperty), _name);
_serializer->set(AHATOFSTR(HAUniqueIdProperty), _uniqueId);
_serializer->set(HASerializer::WithUniqueId);
_serializer->set(AHATOFSTR(HAIconProperty), _icon);
if (_retain) {
src/device-types/HALock.cpp
+1 -1
View File
@@ -37,7 +37,7 @@ void HALock::buildSerializer()
_serializer = new HASerializer(this, 9); // 9 - max properties nb
_serializer->set(AHATOFSTR(HANameProperty), _name);
_serializer->set(AHATOFSTR(HAUniqueIdProperty), _uniqueId);
_serializer->set(HASerializer::WithUniqueId);
_serializer->set(AHATOFSTR(HAIconProperty), _icon);
if (_retain) {
src/device-types/HANumber.cpp
+1 -1
View File
@@ -45,7 +45,7 @@ void HANumber::buildSerializer()
_serializer = new HASerializer(this, 15); // 15 - max properties nb
_serializer->set(AHATOFSTR(HANameProperty), _name);
_serializer->set(AHATOFSTR(HAUniqueIdProperty), _uniqueId);
_serializer->set(HASerializer::WithUniqueId);
_serializer->set(AHATOFSTR(HADeviceClassProperty), _class);
_serializer->set(AHATOFSTR(HAIconProperty), _icon);
_serializer->set(AHATOFSTR(HAUnitOfMeasurementProperty), _unitOfMeasurement);
src/device-types/HAScene.cpp
+1 -1
View File
@@ -21,7 +21,7 @@ void HAScene::buildSerializer()
_serializer = new HASerializer(this, 7); // 7 - max properties nb
_serializer->set(AHATOFSTR(HANameProperty), _name);
_serializer->set(AHATOFSTR(HAUniqueIdProperty), _uniqueId);
_serializer->set(HASerializer::WithUniqueId);
_serializer->set(AHATOFSTR(HAIconProperty), _icon);
// optional property
src/device-types/HASelect.cpp
+1 -1
View File
@@ -93,7 +93,7 @@ void HASelect::buildSerializer()
_serializer = new HASerializer(this, 10); // 10 - max properties nb
_serializer->set(AHATOFSTR(HANameProperty), _name);
_serializer->set(AHATOFSTR(HAUniqueIdProperty), _uniqueId);
_serializer->set(HASerializer::WithUniqueId);
_serializer->set(AHATOFSTR(HAIconProperty), _icon);
_serializer->set(
AHATOFSTR(HAOptionsProperty),
src/device-types/HASensor.cpp
+1 -1
View File
@@ -28,7 +28,7 @@ void HASensor::buildSerializer()
_serializer = new HASerializer(this, 10); // 10 - max properties nb
_serializer->set(AHATOFSTR(HANameProperty), _name);
_serializer->set(AHATOFSTR(HAUniqueIdProperty), _uniqueId);
_serializer->set(HASerializer::WithUniqueId);
_serializer->set(AHATOFSTR(HADeviceClassProperty), _deviceClass);
_serializer->set(AHATOFSTR(HAStateClassProperty), _stateClass);
_serializer->set(AHATOFSTR(HAIconProperty), _icon);
src/device-types/HASwitch.cpp
+1 -1
View File
@@ -38,7 +38,7 @@ void HASwitch::buildSerializer()
_serializer = new HASerializer(this, 10); // 10 - max properties nb
_serializer->set(AHATOFSTR(HANameProperty), _name);
_serializer->set(AHATOFSTR(HAUniqueIdProperty), _uniqueId);
_serializer->set(HASerializer::WithUniqueId);
_serializer->set(AHATOFSTR(HADeviceClassProperty), _class);
_serializer->set(AHATOFSTR(HAIconProperty), _icon);
src/utils/HASerializer.cpp
+39 -2
View File
@@ -189,10 +189,10 @@ void HASerializer::set(
void HASerializer::set(const FlagType flag)
{
if (flag == WithDevice) {
if (flag == WithDevice || flag == WithUniqueId) {
SerializerEntry* entry = addEntry();
entry->type = FlagEntryType;
entry->subtype = static_cast<uint8_t>(WithDevice);
entry->subtype = static_cast<uint8_t>(flag);
entry->property = nullptr;
entry->value = nullptr;
} else if (flag == WithAvailability) {
@@ -348,6 +348,21 @@ uint16_t HASerializer::calculateFlagSize(const FlagType flag) const
strlen_P(HADeviceProperty) +
strlen_P(HASerializerJsonPropertySuffix) +
deviceLength;
} else if (flag == WithUniqueId && _deviceType) {
uint16_t uniqueIdLength = strlen(_deviceType->uniqueId());
if (device->isExtendedUniqueIdsEnabled()) {
uniqueIdLength += strlen(device->getUniqueId()) + 1; // with separator
}
return
// property name
strlen_P(HASerializerJsonPropertyPrefix) +
strlen_P(HAUniqueIdProperty) +
strlen_P(HASerializerJsonPropertySuffix) +
// property value
2 * strlen_P(HASerializerJsonEscapeChar) +
uniqueIdLength;
}
return 0;
@@ -515,11 +530,33 @@ bool HASerializer::flushFlag(const SerializerEntry* entry) const
const FlagType flag = static_cast<FlagType>(entry->subtype);
if (flag == WithDevice && device) {
// property name
mqtt->writePayload(AHATOFSTR(HASerializerJsonPropertyPrefix));
mqtt->writePayload(AHATOFSTR(HADeviceProperty));
mqtt->writePayload(AHATOFSTR(HASerializerJsonPropertySuffix));
// property value
return device->getSerializer()->flush();
} else if (flag == WithUniqueId && _deviceType) {
// property name
mqtt->writePayload(AHATOFSTR(HASerializerJsonPropertyPrefix));
mqtt->writePayload(AHATOFSTR(HAUniqueIdProperty));
mqtt->writePayload(AHATOFSTR(HASerializerJsonPropertySuffix));
// value
const char* uniqueId = _deviceType->uniqueId();
mqtt->writePayload(AHATOFSTR(HASerializerJsonEscapeChar));
if (device->isExtendedUniqueIdsEnabled()) {
const char* deviceUniqueId = device->getUniqueId();
mqtt->writePayload(deviceUniqueId, strlen(deviceUniqueId));
mqtt->writePayload(AHATOFSTR(HASerializerUnderscore));
}
mqtt->writePayload(uniqueId, strlen(uniqueId));
mqtt->writePayload(AHATOFSTR(HASerializerJsonEscapeChar));
return true;
}
return false;
src/utils/HASerializer.h
+2 -1
View File
@@ -29,7 +29,8 @@ public:
/// The type of a flag for a FlagEntryType.
enum FlagType {
WithDevice = 1,
WithAvailability
WithAvailability,
WithUniqueId
};
/// Available data types of entries.
tests/BinarySensorTest/BinarySensorTest.ino
+18
View File
@@ -36,6 +36,24 @@ AHA_TEST(BinarySensorTest, default_params) {
)
}
AHA_TEST(BinarySensorTest, extended_unique_id) {
initMqttTest(testDeviceId)
device.enableExtendedUniqueIds();
HABinarySensor sensor(testUniqueId);
assertEntityConfig(
mock,
sensor,
(
"{"
"\"uniq_id\":\"testDevice_uniqueSensor\","
"\"dev\":{\"ids\":\"testDevice\"},"
"\"stat_t\":\"testData/testDevice/uniqueSensor/stat_t\""
"}"
)
)
}
AHA_TEST(BinarySensorTest, availability) {
initMqttTest(testDeviceId)
tests/ButtonTest/ButtonTest.ino
+18
View File
@@ -65,6 +65,24 @@ AHA_TEST(ButtonTest, default_params) {
)
}
AHA_TEST(ButtonTest, extended_unique_id) {
prepareTest
device.enableExtendedUniqueIds();
HAButton button(testUniqueId);
assertEntityConfig(
mock,
button,
(
"{"
"\"uniq_id\":\"testDevice_uniqueButton\","
"\"dev\":{\"ids\":\"testDevice\"},"
"\"cmd_t\":\"testData/testDevice/uniqueButton/cmd_t\""
"}"
)
)
}
AHA_TEST(ButtonTest, command_subscription) {
prepareTest
tests/CameraTest/CameraTest.ino
+18
View File
@@ -36,6 +36,24 @@ AHA_TEST(CameraTest, default_params) {
)
}
AHA_TEST(CameraTest, extended_unique_id) {
initMqttTest(testDeviceId)
device.enableExtendedUniqueIds();
HACamera camera(testUniqueId);
assertEntityConfig(
mock,
camera,
(
"{"
"\"uniq_id\":\"testDevice_uniqueCamera\","
"\"dev\":{\"ids\":\"testDevice\"},"
"\"t\":\"testData/testDevice/uniqueCamera/t\""
"}"
)
)
}
AHA_TEST(CameraTest, availability) {
initMqttTest(testDeviceId)
tests/CoverTest/CoverTest.ino
+21 -1
View File
@@ -72,6 +72,26 @@ AHA_TEST(CoverTest, default_params) {
assertEqual(1, mock->getFlushedMessagesNb()); // only config should be pushed
}
AHA_TEST(CoverTest, extended_unique_id) {
prepareTest
device.enableExtendedUniqueIds();
HACover cover(testUniqueId);
assertEntityConfig(
mock,
cover,
(
"{"
"\"uniq_id\":\"testDevice_uniqueCover\","
"\"dev\":{\"ids\":\"testDevice\"},"
"\"stat_t\":\"testData/testDevice/uniqueCover/stat_t\","
"\"cmd_t\":\"testData/testDevice/uniqueCover/cmd_t\""
"}"
)
)
assertEqual(1, mock->getFlushedMessagesNb()); // only config should be pushed
}
AHA_TEST(CoverTest, default_params_with_position) {
prepareTest
@@ -295,7 +315,7 @@ AHA_TEST(CoverTest, publish_state_closing) {
mock->connectDummy();
HACover cover(testUniqueId);
assertTrue(cover.setState(HACover::StateClosing));
assertSingleMqttMessage(AHATOFSTR(StateTopic), "closing", true)
}
tests/DeviceTest/DeviceTest.ino
+16 -1
View File
@@ -260,6 +260,21 @@ AHA_TEST(DeviceTest, availability_publish_online) {
assertSingleMqttMessage(AHATOFSTR(AvailabilityTopic), "online", true)
}
AHA_TEST(DeviceTest, extended_unique_ids_disabled) {
prepareMqttTest
assertFalse(device.isExtendedUniqueIdsEnabled());
}
AHA_TEST(DeviceTest, enable_extended_unique_ids) {
prepareMqttTest
device.enableExtendedUniqueIds();
assertTrue(device.isExtendedUniqueIdsEnabled());
assertNoMqttMessage()
}
AHA_TEST(DeviceTest, lwt_disabled) {
prepareMqttTest
@@ -281,7 +296,7 @@ AHA_TEST(DeviceTest, lwt_enabled) {
AHA_TEST(DeviceTest, full_serialization) {
initMqttTest("myDeviceId");
device.setManufacturer("myManufacturer");
device.setModel("myModel");
device.setName("myName");
tests/DeviceTrackerTest/DeviceTrackerTest.ino
+18
View File
@@ -38,6 +38,24 @@ AHA_TEST(DeviceTrackerTest, default_params) {
)
}
AHA_TEST(DeviceTrackerTest, extended_unique_id) {
initMqttTest(testDeviceId)
device.enableExtendedUniqueIds();
HADeviceTracker tracker(testUniqueId);
assertEntityConfig(
mock,
tracker,
(
"{"
"\"uniq_id\":\"testDevice_uniqueTracker\","
"\"dev\":{\"ids\":\"testDevice\"},"
"\"stat_t\":\"testData/testDevice/uniqueTracker/stat_t\""
"}"
)
)
}
AHA_TEST(DeviceTrackerTest, source_type_gps) {
initMqttTest(testDeviceId)
tests/FanTest/FanTest.ino
+20
View File
@@ -102,6 +102,26 @@ AHA_TEST(FanTest, default_params) {
assertEqual(2, mock->getFlushedMessagesNb()); // config + default state
}
AHA_TEST(FanTest, extended_unique_id) {
prepareTest
device.enableExtendedUniqueIds();
HAFan fan(testUniqueId);
assertEntityConfig(
mock,
fan,
(
"{"
"\"uniq_id\":\"testDevice_uniqueFan\","
"\"dev\":{\"ids\":\"testDevice\"},"
"\"stat_t\":\"testData/testDevice/uniqueFan/stat_t\","
"\"cmd_t\":\"testData/testDevice/uniqueFan/cmd_t\""
"}"
)
)
assertEqual(2, mock->getFlushedMessagesNb()); // config + default state
}
AHA_TEST(FanTest, default_params_with_speed) {
prepareTest
tests/HVACTest/HVACTest.ino
+19
View File
@@ -226,6 +226,25 @@ AHA_TEST(HVACTest, default_params) {
assertEqual(1, mock->getFlushedMessagesNb()); // config
}
AHA_TEST(HVACTest, extended_unique_id) {
prepareTest
device.enableExtendedUniqueIds();
HAHVAC hvac(testUniqueId);
assertEntityConfig(
mock,
hvac,
(
"{"
"\"uniq_id\":\"testDevice_uniqueHVAC\","
"\"curr_temp_t\":\"testData/testDevice/uniqueHVAC/curr_temp_t\","
"\"dev\":{\"ids\":\"testDevice\"}"
"}"
)
)
assertEqual(1, mock->getFlushedMessagesNb()); // config
}
AHA_TEST(HVACTest, config_with_action) {
prepareTest
tests/LightTest/LightTest.ino
+20
View File
@@ -165,6 +165,26 @@ AHA_TEST(LightTest, default_params) {
assertEqual(2, mock->getFlushedMessagesNb()); // config + default state
}
AHA_TEST(LightTest, extended_unique_id) {
prepareTest
device.enableExtendedUniqueIds();
HALight light(testUniqueId);
assertEntityConfig(
mock,
light,
(
"{"
"\"uniq_id\":\"testDevice_uniqueLight\","
"\"dev\":{\"ids\":\"testDevice\"},"
"\"stat_t\":\"testData/testDevice/uniqueLight/stat_t\","
"\"cmd_t\":\"testData/testDevice/uniqueLight/cmd_t\""
"}"
)
)
assertEqual(2, mock->getFlushedMessagesNb()); // config + default state
}
AHA_TEST(LightTest, default_params_with_brightness) {
prepareTest
tests/LockTest/LockTest.ino
+21 -1
View File
@@ -71,6 +71,26 @@ AHA_TEST(LockTest, default_params) {
assertEqual(1, mock->getFlushedMessagesNb()); // only config should be pushed
}
AHA_TEST(LockTest, extended_unique_id) {
prepareTest
device.enableExtendedUniqueIds();
HALock lock(testUniqueId);
assertEntityConfig(
mock,
lock,
(
"{"
"\"uniq_id\":\"testDevice_uniqueLock\","
"\"dev\":{\"ids\":\"testDevice\"},"
"\"stat_t\":\"testData/testDevice/uniqueLock/stat_t\","
"\"cmd_t\":\"testData/testDevice/uniqueLock/cmd_t\""
"}"
)
)
assertEqual(1, mock->getFlushedMessagesNb()); // only config should be pushed
}
AHA_TEST(LockTest, command_subscription) {
prepareTest
@@ -220,7 +240,7 @@ AHA_TEST(LockTest, publish_state_locked) {
HALock lock(testUniqueId);
assertTrue(lock.setState(HALock::StateLocked));
assertSingleMqttMessage(AHATOFSTR(StateTopic), "LOCKED", true)
assertSingleMqttMessage(AHATOFSTR(StateTopic), "LOCKED", true)
}
AHA_TEST(LockTest, publish_state_unlocked) {
tests/NumberTest/NumberTest.ino
+20
View File
@@ -71,6 +71,26 @@ AHA_TEST(NumberTest, default_params) {
assertEqual(2, mock->getFlushedMessagesNb()); // config + default state
}
AHA_TEST(NumberTest, extended_unique_id) {
prepareTest
device.enableExtendedUniqueIds();
HANumber number(testUniqueId);
assertEntityConfig(
mock,
number,
(
"{"
"\"uniq_id\":\"testDevice_uniqueNumber\","
"\"dev\":{\"ids\":\"testDevice\"},"
"\"stat_t\":\"testData/testDevice/uniqueNumber/stat_t\","
"\"cmd_t\":\"testData/testDevice/uniqueNumber/cmd_t\""
"}"
)
)
assertEqual(2, mock->getFlushedMessagesNb()); // config + default state
}
AHA_TEST(NumberTest, command_subscription) {
prepareTest
tests/SceneTest/SceneTest.ino
+18
View File
@@ -65,6 +65,24 @@ AHA_TEST(SceneTest, default_params) {
)
}
AHA_TEST(SceneTest, extended_unique_id) {
prepareTest
device.enableExtendedUniqueIds();
HAScene scene(testUniqueId);
assertEntityConfig(
mock,
scene,
(
"{"
"\"uniq_id\":\"testDevice_uniqueScene\","
"\"pl_on\":\"ON\","
"\"cmd_t\":\"testData/testDevice/uniqueScene/cmd_t\""
"}"
)
)
}
AHA_TEST(SceneTest, command_subscription) {
prepareTest
tests/SelectTest/SelectTest.ino
+24
View File
@@ -87,6 +87,30 @@ AHA_TEST(SelectTest, invalid_options_empty) {
assertTrue(select.getOptions() == nullptr);
}
AHA_TEST(SelectTest, extended_unique_id) {
prepareTest
device.enableExtendedUniqueIds();
HASelect select(testUniqueId);
select.setOptions("Option A");
assertEqual(1, select.getOptions()->getItemsNb());
assertEntityConfig(
mock,
select,
(
"{"
"\"uniq_id\":\"testDevice_uniqueSelect\","
"\"options\":[\"Option A\"],"
"\"dev\":{\"ids\":\"testDevice\"},"
"\"stat_t\":\"testData/testDevice/uniqueSelect/stat_t\","
"\"cmd_t\":\"testData/testDevice/uniqueSelect/cmd_t\""
"}"
)
)
assertEqual(1, mock->getFlushedMessagesNb()); // only config should be pushed
}
AHA_TEST(SelectTest, single_option) {
prepareTest
tests/SensorTest/SensorTest.ino
+18
View File
@@ -36,6 +36,24 @@ AHA_TEST(SensorTest, default_params) {
)
}
AHA_TEST(SensorTest, extended_unique_id) {
initMqttTest(testDeviceId)
device.enableExtendedUniqueIds();
HASensor sensor(testUniqueId);
assertEntityConfig(
mock,
sensor,
(
"{"
"\"uniq_id\":\"testDevice_uniqueSensor\","
"\"dev\":{\"ids\":\"testDevice\"},"
"\"stat_t\":\"testData/testDevice/uniqueSensor/stat_t\""
"}"
)
)
}
AHA_TEST(SensorTest, availability) {
initMqttTest(testDeviceId)
tests/SwitchTest/SwitchTest.ino
+21 -1
View File
@@ -71,6 +71,26 @@ AHA_TEST(SwitchTest, default_params) {
assertEqual(2, mock->getFlushedMessagesNb());
}
AHA_TEST(SwitchTest, extended_unique_id) {
prepareTest
device.enableExtendedUniqueIds();
HASwitch testSwitch(testUniqueId);
assertEntityConfig(
mock,
testSwitch,
(
"{"
"\"uniq_id\":\"testDevice_uniqueSwitch\","
"\"dev\":{\"ids\":\"testDevice\"},"
"\"stat_t\":\"testData/testDevice/uniqueSwitch/stat_t\","
"\"cmd_t\":\"testData/testDevice/uniqueSwitch/cmd_t\""
"}"
)
)
assertEqual(2, mock->getFlushedMessagesNb());
}
AHA_TEST(SwitchTest, command_subscription) {
prepareTest
@@ -241,7 +261,7 @@ AHA_TEST(SwitchTest, publish_state_on) {
HASwitch testSwitch(testUniqueId);
assertTrue(testSwitch.setState(true));
assertSingleMqttMessage(AHATOFSTR(StateTopic), "ON", true)
assertSingleMqttMessage(AHATOFSTR(StateTopic), "ON", true)
}
AHA_TEST(SwitchTest, publish_state_off) {