HAMqtt improvements (#224)

* added setBufferSize method to the HAMqtt class

* added getState method to the HAMqtt class

* update docs

* update changelog

* changelog

* update mocks

* change data type in the PubSubClientMock

* update docs and changelog

* add more callbacks to the HAMqtt class

* improve handling of the disconnected state

* minor fixes in state handling

docsrc/source/documents/library/introduction.rst

@@ -1,18 +1,16 @@
 Introduction
 ============
 
-Before implementing the business logic of your application you will need to
-add a few necessary pieces of code to your project.
-Basically, everything comes up to a few basic rules:
+Prior to implementing the business logic of your application, you'll need to incorporate several essential pieces of code into your project.
+Essentially, everything boils down to a few fundamental rules:
 
 1) :doc:`HADevice </documents/api/core/ha-device>` and :doc:`HAMqtt </documents/api/core/ha-mqtt>` instances need to be initialized once globally or as a part of another global object.
-2) :doc:`HAMqtt::begin </documents/api/core/ha-mqtt>` needs to be called at the end of setup logic. It provides MQTT broker credentials that will be used for a connection.
+2) :doc:`HAMqtt::begin </documents/api/core/ha-mqtt>` needs to be called at the end of Arduino's setup logic. It lets you provide the MQTT broker's IP address and credentials.
 3) :doc:`HAMqtt::loop </documents/api/core/ha-mqtt>` method needs to be called periodically (it doesn't need to be called on each tick).
 4) Device types need to be initialized after :doc:`HAMqtt </documents/api/core/ha-mqtt>` class (it will be described later in the documentation).
 
-Here are the minimal boilerplates that you can start with.
-Don't worry if you have no idea what's going on here.
-Everything will be covered in the following chapters.
+Here are the minimal boilerplate examples to get you started.
+Don't worry if you have no idea what's happening here; everything will be explained in detail in the following chapters.
 
 Arduino Boilerplate
 -------------------

docsrc/source/documents/library/mqtt-advanced.rst

@@ -25,11 +25,23 @@ Please take a look at the example below.
         // this method will be called when connection to MQTT broker is established
     }
 
+    void onDisconnected() {
+        // this method will be called when connection to MQTT broker is lost
+    }
+
+    void onStateChanged(HAMqtt::ConnectionState state) {
+        // this method will be called each time the state of the MQTT connection changes
+    }
+
     void setup() {
         Ethernet.begin(mac);
 
         mqtt.onMessage(onMessage);
         mqtt.onConnected(onConnected);
+        mqtt.onDisconnected(onDisconnected);
+        mqtt.onStateChanged(onStateChanged);
+        mqtt.setBufferSize(512); // set the buffer size to 512 bytes, default is 256 bytes
+        mqtt.setKeepAlive(60); // set the keep alive interval to 60 seconds, default is 15 seconds
         mqtt.begin("192.168.1.50", "username", "password");
     }
 

docsrc/source/documents/library/mqtt-security.rst

@@ -1,15 +1,15 @@
 MQTT security
 =============
 
-The library allows you to use credentials for acquiring a TCP connection with the MQTT broker.
-By default you can use the same credentials you use for login in the Home Assistant panel but you can also configure custom credentials in the Mosquitto broker.
+The library enables you to utilize credentials to establish a TCP connection with the MQTT broker.
+By default, you can employ the same credentials utilized for logging into the Home Assistant panel.
+However, it's also possible to configure custom credentials within the Mosquitto broker.
 
 .. DANGER::
 
-    This solution is not 100% secure because communication between Arduino and Home Assistant is not encrypted.
-    Username and password can be easily discovered by analyzing your local network traffic.
-    However, that's fine as long as your local network is secured against unattended access.
-    On more powerful devices (like ESP), you should consider using TLS/SSL connection.
+    This solution may not provide comprehensive security as the communication between Arduino and Home Assistant lacks encryption.
+    Consequently, username and password could be vulnerable to discovery through analysis of local network traffic.
+    However, this may not pose a significant risk if your local network is properly secured against unauthorized access.
 
 ::
 
@@ -31,10 +31,3 @@ By default you can use the same credentials you use for login in the Home Assist
     void loop() {
         // ...
     }
-
-
-SSL connection
---------------
-
-On ESP32/ESP8266 you can use ``WiFiClientSecure`` client to establish encrypted connection between your device and Home Assistant.
-Please take a look at :example:`this example <mqtt-with-ssl/mqtt-with-ssl.ino>`.