net: mqtt-sn: Add Gateway Advertisement and Discovery process support

Fixes: #78010
This commit implements the "Gateway Advertisement and Discovery" process
defined in section 6.1 of the MQTT-SN specification.
This includes breaking changes to the transport interface and the default
included UDP interface implementation as support for UDP multicast
messages is added as implemented by the Paho MQTT-SN Gateway.

Signed-off-by: Kenneth Witham <[email protected]>

Author: SpontaneousDuck

doc/connectivity/networking/api/mqtt_sn.rst

@@ -84,17 +84,33 @@ used. An example configuration for UDP transport is shown below:
 
    mqtt_sn_client_init(&client, &client_id, &tp.tp, evt_cb, tx_buf, sizeof(tx_buf), rx_buf, sizeof(rx_buf));
 
-After the configuration is set up, the MQTT-SN client can connect to the gateway.
-While the MQTT-SN protocol offers functionality to discover gateways through an
-advertisement mechanism, this is not implemented yet in the library.
-
-Call the ``mqtt_sn_connect`` function, which will send a ``CONNECT`` message.
-The application should periodically call the ``mqtt_sn_input`` function to process
-the response received. The application does not have to call ``mqtt_sn_input`` if it
-knows that no data has been received (e.g. when using Bluetooth). Note that
-``mqtt_sn_input`` is a non-blocking function, if the transport struct contains a
-``poll`` compatible function pointer.
-If the connection was successful, ``MQTT_SN_EVT_CONNECTED`` will be notified to the
+After the configuration is set up, the network address for the gateway to
+connect to must be defined. The MQTT-SN protocol offers functionality to
+discover gateways through an advertisement or a search mechanism. A user
+should do at least one of the following steps to define a Gateway for the library:
+
+* Call the :c:func:`mqtt_sn_add_gw` function to manually define a Gateway address.
+* Wait for an :c:enumerator:`MQTT_SN_EVT_ADVERTISE`.
+* Call the :c:func:`mqtt_sn_search` function and wait for an :c:enumerator:`MQTT_SN_EVT_GWINFO` callback.
+  Make sure to call the :c:func:`mqtt_sn_input` function periodically to process incoming messages.
+
+Example :c:func:`mqtt_sn_search` function call:
+
+.. code-block:: c
+
+	err = mqtt_sn_search(&mqtt_client, 1);
+	k_sleep(K_SECONDS(10));
+	err = mqtt_sn_input(&mqtt_client);
+	__ASSERT(err == 0, "mqtt_sn_search() failed %d", err);
+
+After the Gateway address has been defined or found, the MQTT-SN client can
+connect to the gateway. Call the :c:func:`mqtt_sn_connect` function, which will send a
+``CONNECT`` MQTT-SN message. The application should periodically call the :c:func:`mqtt_sn_input`
+function to process the response received. The application does not have to call
+:c:func:`mqtt_sn_input` if it knows that no data has been received (e.g. when using Bluetooth).
+Note that :c:func:`mqtt_sn_input` is a non-blocking function, if the transport struct contains a
+:c:func:`poll` compatible function pointer.
+If the connection was successful, :c:enumerator:`MQTT_SN_EVT_CONNECTED` will be notified to the
 application through the callback function.
 
 .. code-block:: c
@@ -110,19 +126,19 @@ application through the callback function.
 		k_sleep(K_MSEC(500));
 	}
 
-In the above code snippet, the event handler function should set the ``connected``
-flag upon a successful connection. If the connection fails at the MQTT level
-or a timeout occurs, the connection will be aborted.
+In the above code snippet, the gateway is connected to before publishing messages.
+If the connection fails at the MQTT level or a timeout occurs, the connection will be aborted and
+an error returned.
 
-After the connection is established, an application needs to call ``mqtt_input``
+After the connection is established, an application needs to call :c:func:`mqtt_input`
 function periodically to process incoming data. Connection upkeep, on the other hand,
 is done automatically using a k_work item.
 If a MQTT message is received, an MQTT callback function will be called and an
 appropriate event notified.
 
-The connection can be closed by calling the ``mqtt_sn_disconnect`` function. This
+The connection can be closed by calling the :c:func:`mqtt_sn_disconnect` function. This
 has no effect on the transport, however. If you want to close the transport (e.g.
-the socket), call ``mqtt_sn_client_deinit``, which will deinit the transport as well.
+the socket), call :c:func:`mqtt_sn_client_deinit`, which will deinit the transport as well.
 
 Zephyr provides sample code utilizing the MQTT-SN client API. See
 :zephyr:code-sample:`mqtt-sn-publisher` for more information.
@@ -134,7 +150,6 @@ Certain parts of the protocol are not yet supported in the library.
 
 * Pre-defined topic IDs
 * QoS -1 - it's most useful with predefined topics
-* Gateway discovery using ADVERTISE, SEARCHGW and GWINFO messages.
 * Setting the will topic and message after the initial connect
 * Forwarder Encapsulation
 

include/zephyr/net/mqtt_sn.h

@@ -75,16 +75,16 @@ enum mqtt_sn_topic_type {
  * MQTT-SN return codes.
  */
 enum mqtt_sn_return_code {
-	MQTT_SN_CODE_ACCEPTED = 0x00, /**< Accepted */
+	MQTT_SN_CODE_ACCEPTED = 0x00,            /**< Accepted */
 	MQTT_SN_CODE_REJECTED_CONGESTION = 0x01, /**< Rejected: congestion */
-	MQTT_SN_CODE_REJECTED_TOPIC_ID = 0x02, /**< Rejected: Invalid Topic ID */
-	MQTT_SN_CODE_REJECTED_NOTSUP = 0x03, /**< Rejected: Not Supported */
+	MQTT_SN_CODE_REJECTED_TOPIC_ID = 0x02,   /**< Rejected: Invalid Topic ID */
+	MQTT_SN_CODE_REJECTED_NOTSUP = 0x03,     /**< Rejected: Not Supported */
 };
 
 /** @brief Abstracts memory buffers. */
 struct mqtt_sn_data {
 	const uint8_t *data; /**< Pointer to data. */
-	uint16_t size;	     /**< Size of data, in bytes. */
+	size_t size;         /**< Size of data, in bytes. */
 };
 
 /**
@@ -105,19 +105,22 @@ struct mqtt_sn_data {
  *
  * struct mqtt_sn_data data = MQTT_SN_DATA_BYTES(0x13, 0x37);
  */
-#define MQTT_SN_DATA_BYTES(...) \
-	((struct mqtt_sn_data) { (uint8_t[]){ __VA_ARGS__ }, sizeof((uint8_t[]){ __VA_ARGS__ })})
+#define MQTT_SN_DATA_BYTES(...)                                                                    \
+	((struct mqtt_sn_data){(uint8_t[]){__VA_ARGS__}, sizeof((uint8_t[]){__VA_ARGS__})})
 
 /**
  * Event types that can be emitted by the library.
  */
 enum mqtt_sn_evt_type {
-	MQTT_SN_EVT_CONNECTED,	  /**< Connected to a gateway */
+	MQTT_SN_EVT_CONNECTED,    /**< Connected to a gateway */
 	MQTT_SN_EVT_DISCONNECTED, /**< Disconnected */
-	MQTT_SN_EVT_ASLEEP,	  /**< Entered ASLEEP state */
-	MQTT_SN_EVT_AWAKE,	  /**< Entered AWAKE state */
-	MQTT_SN_EVT_PUBLISH,	  /**< Received a PUBLISH message */
-	MQTT_SN_EVT_PINGRESP	  /**< Received a PINGRESP */
+	MQTT_SN_EVT_ASLEEP,       /**< Entered ASLEEP state */
+	MQTT_SN_EVT_AWAKE,        /**< Entered AWAKE state */
+	MQTT_SN_EVT_PUBLISH,      /**< Received a PUBLISH message */
+	MQTT_SN_EVT_PINGRESP,     /**< Received a PINGRESP */
+	MQTT_SN_EVT_ADVERTISE,    /**< Received a ADVERTISE */
+	MQTT_SN_EVT_GWINFO,       /**< Received a GWINFO */
+	MQTT_SN_EVT_SEARCHGW      /**< Received a SEARCHGW */
 };
 
 /**
@@ -180,16 +183,27 @@ struct mqtt_sn_transport {
 	void (*deinit)(struct mqtt_sn_transport *transport);
 
 	/**
-	 * Will be called by the library when it wants to send a message.
+	 * @brief Will be called by the library when it wants to send a message.
+	 *
+	 * Implementations should follow sendto conventions with exceptions.
+	 * When dest_addr == NULL, message should be broadcast with addrlen being
+	 * the broadcast radius. This should also handle setting up/destroying
+	 * connections as required when the address changes.
+	 *
+	 * @return ENOERR on connection+transmission success, Negative values
+	 *		signal errors.
 	 */
-	int (*msg_send)(struct mqtt_sn_client *client, void *buf, size_t sz);
+	int (*sendto)(struct mqtt_sn_client *client, void *buf, size_t sz, const void *dest_addr,
+		      size_t addrlen);
 
 	/**
 	 * @brief Will be called by the library when it wants to receive a message.
 	 *
-	 * Implementations should follow recv conventions.
+	 * Implementations should follow recvfrom conventions with the exception
+	 * of a NULL src_addr being a broadcast message.
 	 */
-	ssize_t (*recv)(struct mqtt_sn_client *client, void *buffer, size_t length);
+	ssize_t (*recvfrom)(struct mqtt_sn_client *client, void *rx_buf, size_t rx_len,
+			    void *src_addr, size_t *addrlen);
 
 	/**
 	 * @brief Check if incoming data is available.
@@ -215,9 +229,9 @@ struct mqtt_sn_transport_udp {
 	/** Socket FD */
 	int sock;
 
-	/** Address of the gateway */
-	struct sockaddr gwaddr;
-	socklen_t gwaddrlen;
+	/** Address of broadcasts */
+	struct sockaddr bcaddr;
+	socklen_t bcaddrlen;
 };
 
 #define UDP_TRANSPORT(transport) CONTAINER_OF(transport, struct mqtt_sn_transport_udp, tp)
@@ -265,6 +279,9 @@ struct mqtt_sn_client {
 	/** Buffer for incoming data */
 	struct net_buf_simple rx;
 
+	/** Buffer for incoming data sender address */
+	struct net_buf_simple rx_addr;
+
 	/** Event callback */
 	mqtt_sn_evt_cb_t evt_cb;
 
@@ -277,6 +294,9 @@ struct mqtt_sn_client {
 	/** List of registered topics */
 	sys_slist_t topic;
 
+	/** List of found gateways */
+	sys_slist_t gateway;
+
 	/** Current state of the MQTT-SN client */
 	int state;
 
@@ -286,6 +306,15 @@ struct mqtt_sn_client {
 	/** Number of retries for failed ping attempts */
 	uint8_t ping_retries;
 
+	/** Timestamp of the next SEARCHGW transmission */
+	int64_t ts_searchgw;
+
+	/** Timestamp of the next GWINFO transmission */
+	int64_t ts_gwinfo;
+
+	/** Radius of the next GWINFO transmission */
+	int64_t radius_gwinfo;
+
 	/** Delayable work structure for processing MQTT-SN events */
 	struct k_work_delayable process_work;
 };
@@ -317,6 +346,29 @@ int mqtt_sn_client_init(struct mqtt_sn_client *client, const struct mqtt_sn_data
  */
 void mqtt_sn_client_deinit(struct mqtt_sn_client *client);
 
+/**
+ * @brief Manually add a Gateway, bypasing the normal search process.
+ *
+ * This function manually creates a gateway that is stored internal to the library.
+ *
+ * @param client      The MQTT-SN client to connect.
+ * @param gw_id       Single byte Gateway Identifier
+ * @param gw_addr     Address data structure to be used by the transport layer.
+ *
+ * @return 0 or a negative error code (errno.h) indicating reason of failure.
+ */
+int mqtt_sn_add_gw(struct mqtt_sn_client *client, uint8_t gw_id, struct mqtt_sn_data gw_addr);
+
+/**
+ * @brief Initiate the MQTT-SN GW Search process.
+ *
+ * @param client     The MQTT-SN client to connect.
+ * @param radius     Broadcast radius for the search message.
+ *
+ * @return 0 or a negative error code (errno.h) indicating reason of failure.
+ */
+int mqtt_sn_search(struct mqtt_sn_client *client, uint8_t radius);
+
 /**
  * @brief Connect the client.
  *

subsys/net/lib/mqtt_sn/Kconfig

@@ -14,26 +14,51 @@ if MQTT_SN_LIB
 config MQTT_SN_LIB_MAX_PAYLOAD_SIZE
 	int "Maximum payload size of an MQTT-SN message"
 	default $(UINT8_MAX)
+	range $(UINT8_MAX) $(UINT16_MAX)
 
 config MQTT_SN_LIB_MAX_MSGS
 	int "Number of preallocated messages"
 	default 10
+	range 1 $(UINT8_MAX)
 
 config MQTT_SN_LIB_MAX_TOPICS
 	int "Number of topics that can be managed"
 	default 20
+	range 1 $(UINT8_MAX)
 
 config MQTT_SN_LIB_MAX_TOPIC_SIZE
 	int "Maximum topic length"
 	default 64
+	range 1 $(UINT16_MAX)
+
+config MQTT_SN_LIB_MAX_GATEWAYS
+	int "Maximum number of gateways to store internally"
+	default 2
+	range 1 $(UINT8_MAX)
+
+config MQTT_SN_LIB_MAX_ADDR_SIZE
+	int "Maximum address size for the transport"
+	default 21
+	range 1 $(UINT8_MAX)
+	help
+		The MQTT_SN library stores addresses internally and thus
+		needs to know how long your addresses are. Set this to the maximum
+		length in bytes of the address data structure for your implemented transport.
+
+config MQTT_SN_LIB_BROADCAST_RADIUS
+	int "Radius for broadcast messages"
+	default 1
+	range 1 $(UINT8_MAX)
 
 config MQTT_SN_LIB_MAX_PUBLISH
 	int "Number of publishes that can be in-flight at the same time"
 	default 5
+	range 1 $(UINT8_MAX)
 
 config MQTT_SN_KEEPALIVE
 	int "Maximum number of clients Keep alive time for MQTT-SN (in seconds)"
 	default 60
+	range 1 $(UINT8_MAX)
 	help
 	  Keep alive time for MQTT-SN (in seconds). Sending of Ping Requests to
 	  keep the connection alive are governed by this value.
@@ -50,6 +75,22 @@ config MQTT_SN_LIB_N_RETRY
 config MQTT_SN_LIB_T_RETRY
 	int "Time (seconds) to wait for responses"
 	default 10
+	range 0 $(UINT8_MAX)
+
+config MQTT_SN_LIB_T_SEARCHGW
+	int "Max time (seconds) to wait before sending SEARCHGW"
+	default 10
+	range 0 $(UINT8_MAX)
+
+config MQTT_SN_LIB_T_GWINFO
+	int "Max time (seconds) to wait before sending GWINFO"
+	default 10
+	range 0 $(UINT8_MAX)
+
+config MQTT_SN_LIB_N_ADV
+	int "Number of missed Advertise messages before considering GW lost"
+	default 2
+	range 1 $(UINT8_MAX)
 
 module=MQTT_SN
 module-dep=NET_LOG