MQTT tutorial done; move connect() into begin()

adjust the examples to use a lambda for `on_connect` callback.

add username and password settings into example's secrets.py module.

modify seealso admonition for less ambiguity with generic admonitions.

openHAB tutorial started (far from done though).

Author: 2bndy5

README.rst

@@ -12,7 +12,7 @@ Introduction
     :target: https://codecov.io/gh/2bndy5/CircuitPython_Homie
     :alt: Test Code Coverage
 
-Homie specifications for MQTT implemented in CircuitPython
+Homie v4 specifications for MQTT implemented in CircuitPython
 
 .. image:: https://homieiot.github.io/img/works-with-homie.svg
     :alt: Works with MQTT Homie

circuitpython_homie/__init__.py

@@ -323,12 +323,6 @@ def __init__(self, client: MQTT, name: str, device_id: str):
 
         device_id = validate_id(device_id)
         self.topic = "/".join([self.base_topic, device_id])
-        try:
-            self.client.disconnect()
-        except MMQTTException:  # pragma: no cover
-            pass  # this exception meant the client was disconnected.
-        self.client.will_set(self.topic + "/$state", "lost")
-        self.client.connect(keep_alive=5)
 
     def _publish_topic(self, topic: str, value, retain: bool = True):
         """A helper to publish topics arbitrarily."""
@@ -345,9 +339,21 @@ def _publish_topic(self, topic: str, value, retain: bool = True):
             pub_val = str(pub_val)
         self.client.publish(topic, pub_val, retain=retain, qos=1)
 
-    def begin(self):
-        """Register this Homie device with the MQTT broker."""
-        assert self.client.is_connected()
+    def begin(self, **mqtt_settings):
+        """Register this Homie device with the MQTT broker.
+
+        :param mqtt_settings: All keyword arguments are used as parameters that get
+            passed to :meth:`~adafruit_minimqtt.adafruit_minimqtt.MQTT.connect()`.
+        """
+        # set the will and testament (requires being disconnected first)
+        try:
+            if self.client.is_connected():
+                self.client.disconnect()
+        except MMQTTException:  # pragma: no cover
+            pass  # this exception meant the client was disconnected.
+        self.client.will_set(self.topic + "/$state", "lost")
+        self.client.connect(**mqtt_settings)
+
         # publish default/required attributes
         for attr in ("homie", "name", "extensions", "implementation", "nodes", "fw"):
             self._publish_topic(self.topic + "/$" + attr, getattr(self, attr))
@@ -377,9 +383,9 @@ def begin(self):
                     self.client.add_topic_callback(prop_topic + "/set", prop.callback)
                     self.client.subscribe(prop_topic + "/set", qos=1)
                 self._publish_topic(prop_topic, prop.value, retain=retained)
-        self._publish_topic(self.topic + "/$state", "ready")
         if self.enable_broadcast:
             self.client.subscribe(self.base_topic + "/$broadcast/#", qos=1)
+        self._publish_topic(self.topic + "/$state", "ready")
 
     def set_state(self, state: str):
         """Set the device's :homie-attr:`state` attribute on the MQTT broker.

docs/_static/extra_css.css

@@ -24,3 +24,21 @@
 .topic-list li::marker {
   content: "/";
 }
+
+*:root {
+  --md-admonition-seealso-color: hsl(278, 100%, 63%);
+  --md-eye--icon: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 0 24 24" width="24px"><path d="M0 0h24v24H0z" fill="none"/><path d="M12 4.5C7 4.5 2.73 7.61 1 12c1.73 4.39 6 7.5 11 7.5s9.27-3.11 11-7.5c-1.73-4.39-6-7.5-11-7.5zM12 17c-2.76 0-5-2.24-5-5s2.24-5 5-5 5 2.24 5 5-2.24 5-5 5zm0-8c-1.66 0-3 1.34-3 3s1.34 3 3 3 3-1.34 3-3-1.34-3-3-3z"/></svg>');
+}
+
+.admonition.seealso .admonition-title {
+  background-color: hsla(278, 100%, 63%, 0.1);
+}
+
+.admonition.seealso {
+  border: 0 solid var(--md-admonition-seealso-color);
+}
+
+.md-typeset .admonition.seealso :is(.admonition-title, summary)::before {
+  background-color: var(--md-admonition-seealso-color);
+  mask-image: var(--md-eye--icon);
+}

docs/conf.py

@@ -158,6 +158,16 @@
         },
     ],
     "toc_title_is_page_title": True,
+    "social": [
+        dict(
+            icon="fontawesome/brands/github",
+            link="https://github.com/2bndy5/CircuitPython_Homie",
+        ),
+        dict(
+            icon="fontawesome/brands/python",
+            link="https://pypi.org/project/circuitpython-homie/",
+        ),
+    ],
 }
 
 object_description_options = [

docs/examples.rst

@@ -26,8 +26,12 @@ In this secrets module should be 2 `dict`\ s:
     mqtt_settings = dict(
         broker="openhabian",  # the broker's hostname or IP address
         port=1883,  # the broker's port
+        username="user_name",
+        password="user_password",
     )
 
+The MQTT username and password may not be required if you skipped :ref:`mqtt_user_password`.
+
 Dependencies
 ************
 

docs/index.rst

@@ -21,9 +21,8 @@
 
 .. toctree::
     :hidden:
-    :caption: Tutorials
 
-    tutorials/openhab
+    tutorials/intro
 
 .. toctree::
     :hidden:

docs/tutorials/intro.rst

@@ -0,0 +1,63 @@
+Tutorials
+=========
+
+To aid with user setup, these docs are complete with tutorials about
+
+.. toctree::
+    :maxdepth: 1
+
+    mosquitto
+    openhab
+
+Controlling a system service in Linux (``systemctl``)
+-----------------------------------------------------
+
+These are some common commands  for ``systemctl`` on Linux that may be helpful, all of which
+should require root permission (``sudo``) to execute successfully.
+
+.. program:: systemctl
+
+.. option:: enable
+
+    This command is used to make a service start when the machine boots up. To enable Mosquitto
+    broker (as a system service) to start on boot up:
+
+    .. code-block:: shell
+
+        sudo systemctl enable mosquitto
+
+.. option:: status
+
+    This command is used to print the status of a running mosquitto broker. It can be useful because
+    it will show if there was any errors in running the process.
+
+    .. code-block:: shell
+
+        sudo systemctl status mosquitto
+
+    .. hint::
+        If there were any errors, then this will tell you what file in which the logs were saved.
+
+.. option:: restart
+
+    This command is useful if you need to restart your broker after making changes to the
+    configuration.
+
+    .. code-block:: shell
+
+        sudo systemctl restart mosquitto
+
+.. option:: start
+
+    The command to start the broker as a service (as opposed to directly running the ``mosquitto``
+    or ``openhab`` binary executables). This is really only useful if you don't want the broker
+    service to start on boot (ie. doing tests configurations).
+
+    .. code-block:: shell
+
+        sudo systemctl start openhab
+
+.. option:: stop
+
+    The command to stop any running system service. This is mentioned for completeness
+    because it is the opposite of :std:option:`start`.

docs/tutorials/mosquitto.rst

@@ -0,0 +1,144 @@
+Setting Up an MQTT broker (Mosquitto)
+=====================================
+
+`Mosquitto <https://mosquitto.org/>`_ is a popular choice and is available for most platforms.
+`Download/install instructions <https://mosquitto.org/download/>`_ are pretty straight forward.
+
+.. admonition:: Installing Mosquitto on Linux
+    :class: todo
+
+    .. code-block:: shell
+
+        sudo apt-get install mosquitto
+
+Configuring Mosquitto
+---------------------
+
+You may have to change the default configuration used by the Mosquitto broker to allow other
+network devices to connect. For me (using v2.0.11 on Ubuntu), this meant editing the file
+located at **/etc/mosquitto/mosquitto.conf**.
+
+Open the file with root permission from the terminal (or via SSH client):
+
+.. code-block:: shell
+
+    sudo nano /etc/mosquitto/mosquitto.conf
+
+Make sure a ``listener`` is bound to a port (typically ``1883`` by default) with the domain
+``0.0.0.0`` (the server machine's ``localhost``). If you want to skip
+mqtt_user_password_, then add a line that sets ``allow_anonymous`` to ``true``.
+It should end up looking like this:
+
+.. code-block:: pacmanconf
+    :caption: /etc/mosquitto/mosquitto.conf
+
+    listener 1883 0.0.0.0
+
+    # to bypass username and password configuration
+    allow_anonymous true
+
+Save and close the file, then :std:option:`systemctl restart` the broker.
+
+Checking the Mosquitto broker logs
+**********************************
+
+By default, the logs for mosquitto are saved to **/var/log/mosquitto/mosquitto.log**. This can be
+changed with the ``log_dest file`` value in the configuration:
+
+.. code-block:: text
+    :caption: Default Log Destination in **/etc/mosquitto/mosquitto.conf**
+
+    log_dest file /var/log/mosquitto/mosquitto.log
+
+If the broker fails to understand a given configuration, then these logs will point to what
+configuration option was erroneous.
+
+.. code-block:: shell
+    :caption: Print Logs in the terminal (requires root permission)
+
+    sudo cat /var/log/mosquitto/mosquitto.log
+
+.. _mqtt_user_password:
+
+Setting a username and password
+-------------------------------
+
+It is recommended that your MQTT broker's access be secured via a username and password.
+The Mosquitto broker uses a password file to store these values securely.
+
+1. .. code-block:: shell
+       :caption: Create the password file for a user
+
+       mosquitto_passwd -c pswd.txt username
+
+   The above command creates a password file named ``pswd.txt`` for a user named ``username``.
+
+   .. details:: Adding another user
+       :class: info
+
+       Use the ``-b`` switch to add more users:
+
+       .. code-block:: shell
+
+           mosquitto_passwd -b pswd.txt other_username user_password
+   .. details:: Removing a user
+       :class: error
+
+       Use the ``-D`` switch to remove a user:
+
+       .. code-block:: shell
+
+           mosquitto_passwd -D pswd.txt other_username user_password
+   .. note::
+       If you inspect the password file  after creation, you will notice that the password
+       associated with usernames is not what you entered. This is because ``mosquitto_passwd``
+       encrypts the password using a SHA512 scheme.
+2. .. code-block:: shell
+       :caption: Move the password file to the broker's configuration path
+
+       sudo mv pswd.txt /etc/mosquitto/
+
+   The **pswd.txt** file you created should now be next to you broker's configuration file
+   (**/etc/mosquitto/mosquitto.conf**).
+3. Add the following lines to the broker's configuration file.
+
+   .. details:: Open your broker's configuration file
+       :class: faq
+
+       .. code-block:: shell
+
+           sudo nano /etc/mosquitto/mosquitto.conf
+
+   .. code-block:: text
+       :caption: add the password file's path to the configuration
+
+       per_listener_settings true
+
+       listener 1883 0.0.0.0
+       allow_anonymous false
+       password_file /etc/mosquitto/pswd.txt
+
+   - ``per_listener_settings`` is required to assign the password file to a listener.
+   - ``alow_anonymous`` should be disabled if you want to prohibit non-authenticated access to
+     your broker.
+   - ``password_file`` is the path to the password file created with encrypted passwords.
+
+4. :std:option:`systemctl restart` (or :std:option:`systemctl start`) to force the broker to use
+   the updated configuration.
+
+.. admonition:: Enabling SSL
+    :class: check
+
+    If desired, you can enable SSL support in your broker for additional security and
+    anti-corruption of data. Since this is all rather technical and a bit more involved, I would
+    recommend following `Steve's Internet Guide <http://www.steves-internet-guide.com/mosquitto-tls/>`_.
+
+MQTT Explorer
+-------------
+
+To verify that this library is publishing and subscribing topics with your MQTT broker, I
+recommend using the `MQTT Explorer app <https://mqtt-explorer.com/>`_ (which works well
+on my Windows PC).
+`Downloads are available <https://github.com/thomasnordquist/MQTT-Explorer/releases/latest>`_
+for most platforms. There's even a stable release deployed in the Windows App Store and the
+Snap Store for Linux.