# MQTT support

The gateway serves MQTT 3.1.1 and 5.0. [Compatibility](/mq-gateway/0.4/reference/compatibility.md) lists the clients and test suites that we test the gateway with.

## Supported

| Feature                                        | 3.1.1 | 5.0 | Notes                                                                                      |
| ---------------------------------------------- | ----- | --- | ------------------------------------------------------------------------------------------ |
| QoS 0                                          | yes   | yes | Core NATS                                                                                  |
| QoS 1 and 2                                    | yes   | yes | Only on topics that a binding stores                                                       |
| Wildcard subscriptions (`+`, `#`)              | yes   | yes |                                                                                            |
| Shared subscriptions (`$share/`)               | yes   | yes | The gateway grants QoS 1 at most                                                           |
| Retained messages                              | yes   | yes | Needs a retained bucket                                                                    |
| Persistent sessions                            | yes   | yes | Needs a sessions bucket                                                                    |
| Session takeover                               | yes   | yes | Works across gateways that share the sessions bucket                                       |
| Wills                                          | yes   | yes | A QoS 1 or 2 will needs a bound topic                                                      |
| Will Delay Interval                            |       | yes |                                                                                            |
| Server-assigned client ID                      | yes   | yes |                                                                                            |
| Username and password                          | yes   | yes | The listener maps them to a NATS user                                                      |
| TLS and mutual TLS                             | yes   | yes |                                                                                            |
| WebSocket                                      | yes   | yes |                                                                                            |
| Message Expiry Interval                        |       | yes |                                                                                            |
| User Properties                                |       | yes | The gateway sends them as NATS headers                                                     |
| Content Type, Response Topic, Correlation Data |       | yes | The gateway sends them as NATS headers                                                     |
| Payload Format Indicator                       |       | yes |                                                                                            |
| Subscription Identifiers                       |       | yes |                                                                                            |
| No Local                                       |       | yes |                                                                                            |
| Retain Handling, Retain As Published           |       | yes |                                                                                            |
| Topic aliases                                  |       | yes |                                                                                            |
| Receive Maximum                                |       | yes |                                                                                            |
| Maximum Packet Size                            |       | yes |                                                                                            |
| Server Keep Alive                              |       | yes | Set it with `mqtt.server-keepalive`                                                        |
| Server Reference on shutdown                   |       | yes | Set it with `mqtt.server-reference`                                                        |
| Reason codes and reason strings                |       | yes | See [Errors](/mq-gateway/0.4/reference/errors.md)                                          |
| Sparkplug B 3.0                                | yes   | yes | See [Run Sparkplug B clients](/mq-gateway/0.4/how-to/run-sparkplug.md)                     |
| Request/Response Information                   |       | yes | See [Call NATS services from MQTT](/mq-gateway/0.4/how-to/call-nats-services-from-mqtt.md) |

## Not supported

* Enhanced authentication (the v5 AUTH packet)
* QoS 2 shared subscriptions. The gateway grants QoS 1 instead.
* The `$SYS/` broker statistics topics
* A queue of QoS 0 messages for an offline client

## Things to know

* **QoS 1 and 2 need a binding.** The gateway refuses a QoS 1 or 2 publish to a topic that no binding stores. It does not change the publish to QoS 0.
* **One consumer per session per stream.** Each session with a QoS 1 or 2 subscription holds one JetStream consumer on each stream that it reads. The `max_consumers` limit of a stream sets how many of these sessions the stream can serve. The default is 1,000. Past that limit, the gateway refuses the subscription.
* **Duplicates after a failure.** After a lost connection or a failed gateway, a QoS 1 or 2 message can arrive again. The second copy can arrive after later messages. If a client must not process a message twice, the client should discard duplicates.
* **Topics are subjects.** The topic `a/b/c` is the NATS subject `a.b.c`. `+` is `*`, and `#` is `>`. See [MQTT mapping](/mq-gateway/0.4/reference/mapping-to-nats.md).
