docs: clarify ArduinoHA discovery guidance

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 3.2.1
+
+- Clarify discovery migration and entity documentation, including the choices
+  for new devices, existing installations, and no-device-discovery projects.
+- Refresh the canonical PlatformIO and Arduino IDE package metadata.
+
 ## 3.2.0
 
 **Discovery publication and resilience:**

README.md

@@ -57,7 +57,7 @@ Build [ESP Sensor](examples/01-esp-sensor/) for a complete ESP8266/ESP32 project
 
 ```ini
 lib_deps =
-    home-assistant-integration=https://github.com/alexhopeoconnor/arduino-home-assistant.git#v3.2.0
+    home-assistant-integration=https://github.com/alexhopeoconnor/arduino-home-assistant.git#v3.2.1
 ```
 
 PlatformIO clones the Git repository and checks out the ref after `#`; that ref is a release tag, not a GitHub Release asset. Arduino IDE is supported through the included [`library.properties`](library.properties).

docs/device-and-discovery.md

@@ -51,9 +51,19 @@ mqtt.setDataPrefix("myDataPrefix");
 
 Both formats remain supported by Home Assistant. Device discovery requires Home Assistant **2024.11.0 or newer**. Use `enableDeviceDiscovery()` only for a new device which has never published this library's single-component discovery topics.
 
+Choose the mode before connecting a device:
+
+- **New device:** call `enableDeviceDiscovery()` before connecting.
+- **Existing device using single-component discovery:** follow the migration
+  procedure below.
+- **No need for device discovery:** keep the default behavior.
+
 ### Migrating an existing device to device discovery
 
-Do not switch an existing device by calling `enableDeviceDiscovery()` alone. Home Assistant derives an entity's discovery identity from the topic, and a direct switch causes retained-topic conflicts. The migration deliberately publishes, in order:
+Do not switch an existing device by calling `enableDeviceDiscovery()` alone.
+Home Assistant derives an entity's discovery identity from the topic, and a
+direct switch causes retained-topic conflicts. The migration publishes, in
+order:
 
 1. `{"migrate_discovery":true}` to every old retained component config topic;
 2. the retained `/device/<deviceId>/config` payload; and only then

docs/entities.md

@@ -22,7 +22,9 @@ ArduinoHA supports these Home Assistant MQTT discovery entity classes. Choose th
 | Tag scanner | [tag-scanner](../examples/tag-scanner/tag-scanner.ino) |
 | Text | Use the API header; no dedicated sketch yet |
 
-The library does not currently implement alarm control panels, events, humidifiers, images, lawn mowers, sirens, updates, vacuums, valves, or water heaters. Those are deliberate unsupported surfaces, not configuration switches.
+The library does not currently implement alarm control panels, events,
+humidifiers, images, lawn mowers, sirens, updates, vacuums, valves, or water
+heaters. They cannot be enabled through configuration.
 
 ## Common lifecycle
 

docs/getting-started.md

@@ -11,7 +11,7 @@ ArduinoHA talks to Home Assistant over **MQTT** (TCP). You need an MQTT broker r
 
 ```ini
 lib_deps =
-    home-assistant-integration=https://github.com/alexhopeoconnor/arduino-home-assistant.git#v3.2.0
+    home-assistant-integration=https://github.com/alexhopeoconnor/arduino-home-assistant.git#v3.2.1
 ```
 
 **Arduino IDE:** this fork is not indexed by Library Manager. Download the

library.json

@@ -1,6 +1,6 @@
 {
   "name": "home-assistant-integration",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "description": "Maintained Home Assistant MQTT discovery and entity integration for Arduino and ESP devices.",
   "keywords": [
     "mqtt",

library.properties

@@ -1,5 +1,5 @@
 name=home-assistant-integration
-version=3.2.0
+version=3.2.1
 author=Dawid Chyrzynski <dev@chyrzynski.pl>, Alex Hope-O'Connor <alex.hope.oconnor@pomonaqld.au>
 maintainer=Alex Hope-O'Connor <alex.hope.oconnor@pomonaqld.au>
 sentence=Home Assistant MQTT integration for Arduino

src/ArduinoHADefines.h

@@ -32,7 +32,7 @@
 #endif
 
 // Current library version used in discovery origin metadata.
-#define ARDUINOHA_LIBRARY_VERSION "3.2.0"
+#define ARDUINOHA_LIBRARY_VERSION "3.2.1"
 
 #if defined(ARDUINOHA_DEBUG)
     #include <Arduino.h>