Add "MQTT Guide" pages

dir.yaml

@@ -813,6 +813,7 @@
       path: gateway/gateway
       collapsed: true
       children:
+        - gateway/nats
         - gateway/stomp
         - gateway/mqttsn
         - gateway/coap
@@ -829,12 +830,7 @@
           collapsed: true
           children:
             - gateway/jt808_data_exchange
-        - gateway/nats
-        - title_en: GB/T 32960 Gateway
-          title_cn: GB/T 32960 协议网关
-          title_ja: GB/T 32960 ゲートウェイ
-          path: gateway/gbt32960
-        #- gateway/tcp
+        - gateway/gbt32960
     - client-attributes/client-attributes
 
 - title_en: Tutorials
@@ -894,12 +890,36 @@
       title_cn: MQTT Guide
       title_ja: MQTT ガイド
       lang: en
-      path: https://www.emqx.com/en/mqtt-guide
+      path: design/mqtt-guide
+      collapsed: true
+      children:
+        - title_en: MQTT Basics
+          title_cn: MQTT Basics
+          title_ja: MQTT Basics
+          lang: en
+          path: design/mqtt-basics
+        - title_en: MQTT Advanced
+          title_cn: MQTT Advanced
+          title_ja: MQTT Advanced
+          lang: en
+          path: design/mqtt-advanced
     - title_en: MQTT Guide
       title_cn: MQTT Guide
       title_ja: MQTT ガイド
       lang: ja
-      path: https://www.emqx.com/en/mqtt-guide
+      path: design/mqtt-guide
+      collapsed: true
+      children:
+        - title_en: MQTT Basics
+          title_cn: MQTT Basics
+          title_ja: MQTT Basics
+          lang: ja
+          path: design/mqtt-basics
+        - title_en: MQTT Advanced
+          title_cn: MQTT Advanced
+          title_ja: MQTT Advanced
+          lang: ja
+          path: design/mqtt-advanced
     - title_en: MQTT 教程
       title_cn: MQTT 教程
       title_ja: MQTT チュートリアル

en_US/design/emqx-essentials.md

@@ -2,5 +2,5 @@
 
 This chapter serves as a comprehensive guide to understanding the essential components and concepts of MQTT and EMQX. In this chapter, you will learn the fundamental knowledge and practical insights about the MQTT protocol and the EMQX broker. Let's take a closer look at what you can expect to learn:
 
-- [MQTT Guide](https://www.emqx.com/en/mqtt-guide) provides all you need to learn about MQTT.
-- [Design and Implementation](../design/overview.md) introduce the design principles of some key EMQX features.
+- [MQTT Guide](./mqtt-guide.md) provides all you need to learn about MQTT, from basics to advanced.
+- [Design and Implementation](../design/overview.md) introduces the design principles of some key EMQX features.

en_US/design/mqtt-advanced.md

@@ -0,0 +1,115 @@
+# MQTT Advanced
+
+## Retained Messages
+
+MQTT Retained Messages enable brokers to store the most recent message for each topic, allowing newly connected subscribers to instantly receive the latest available data, without waiting for the next publish event. This mechanism is particularly valuable in scenarios like smart homes and industrial IoT, where real-time state awareness is essential even if data updates are infrequent.
+
+EMQX offers full support for retained messages in compliance with MQTT 5.0. It allows users to view, manage, and delete retained messages through an intuitive Dashboard or via management APIs. Users can configure storage modes (memory or disk), message expiration intervals, and maximum retained entries to align with system reliability and persistence requirements. 
+
+To try it out, simply run `docker run -d --name emqx -p 18083:18083 -p 1883:1883 emqx/emqx-enterprise` and access the built-in Dashboard to manage retained messages effortlessly. For more advanced use cases, EMQX also supports MQTT features such as session persistence, wildcard subscriptions, and message expiry, making it an ideal platform for building robust MQTT-based applications.
+
+**Read more:** [MQTT Retained Messages: Beginner's Guide with Example](https://www.emqx.com/en/blog/mqtt5-features-retain-message#mqtt-retained-messages-in-emqx) 
+
+## Will Messages
+
+The MQTT Will Message is a crucial feature for handling unexpected client disconnections, allowing for graceful actions like notifying other clients or switching backup devices. When a client connects, it can specify a Will Message, which is sent by the server if the client disconnects unexpectedly, without sending a proper DISCONNECT packet. This mechanism helps monitor client status and ensure reliability in IoT applications.
+
+In MQTT 5.0, the Will Delay Interval was introduced to delay the Will Message's publication, reducing unnecessary notifications during temporary network issues. The message is stored in the server session, and its delivery depends on whether the session expires or the delay interval is met first. EMQX supports Will Message features, including retaining the message for future subscribers and integrating with session expiry notifications for enhanced client status monitoring. This functionality is integral for building resilient, real-time IoT applications, ensuring that system operators are informed of any device or client status changes promptly.
+
+**Read more:** [MQTT Will Message (Last Will & Testament) Explained and Example | MQTT 5 Features](https://www.emqx.com/en/blog/use-of-mqtt-will-message) 
+
+## Request / Response
+
+MQTT 5.0 improves the Request/Response pattern with three key features: **Response Topic**, which allows requesters to specify a unique topic for responses, reducing conflicts; **Correlation Data**, which helps match responses to requests, even in asynchronous or multiple-responder scenarios; and **Response Information**, which facilitates topic permission management by allowing the requester to receive server-specific information for building response topics. These features ensure more reliable and organized communication, especially in complex IoT environments.
+
+**Read more:** [MQTT Request / Response Explained and Example | MQTT 5 Features](https://www.emqx.com/en/blog/mqtt5-request-response#suggestions-for-using-mqtt-request-response) 
+
+## User Properties
+
+User Properties in MQTT 5.0 enable clients to attach custom metadata to messages using key-value pairs, similar to HTTP headers. This greatly enhances protocol flexibility by supporting use cases like file transfer, resource format identification, and intelligent message routing. User Properties can be added when connecting, publishing, subscribing, or disconnecting, allowing seamless metadata exchange between clients and brokers. For instance, they can carry file info, data format, or region tags, helping servers process messages efficiently and enabling traceable, application-level routing. EMQX fully supports User Properties, offering rich compatibility in clients like MQTT.js and the upcoming MQTTX.
+
+Read more: [User Properties - MQTT 5.0 new features](https://www.emqx.com/en/blog/mqtt5-user-properties) 
+
+## Topic Alias
+
+Topic Alias allows users to reduce the possibly long and repeatedly used topic name to a 2-byte integer, so as to reduce the bandwidth consumption when publishing messages.
+
+EMQX supports Topic Alias, optimizing message sizes and improving efficiency, especially in scenarios with limited bandwidth.
+
+Read more: [Topic Alias - MQTT 5.0 new features](https://www.emqx.com/en/blog/mqtt5-topic-alias) 
+
+## Payload Format Indicator & Content Type
+
+Payload Format Indicator and Content Type are two key MQTT 5.0 properties that make message parsing more transparent. The former identifies whether the payload is binary or UTF-8 text, while the latter describes the payload format using MIME types (e.g., `application/json`).
+
+Together, they help subscribers efficiently interpret messages and allow flexible content handling without relying on topic naming conventions. EMQX supports both properties, enabling smarter payload processing in diverse IoT and messaging applications.
+
+Read more: [Introduction to MQTT Payload Format Indicator and Content Type | MQTT 5 Features](https://www.emqx.com/en/blog/mqtt5-new-features-payload-format-indicator-and-content-type) 
+
+## Shared Subscriptions
+
+Shared Subscriptions in MQTT 5.0 enable multiple clients to share the consumption of messages from a single topic, ensuring balanced load distribution and improved system scalability. EMQX fully supports this feature and even extends compatibility to MQTT 3.1.1 clients, allowing existing devices to benefit from shared consumption without code changes—just by using the `$share/{group}/{topic}` format.
+
+This mechanism enhances throughput, prevents single-client bottlenecks, and ensures high availability. With built-in support for multiple load balancing strategies like round robin, hash, and local-first, EMQX helps developers flexibly manage traffic distribution across clustered environments.
+
+Read more: [MQTT Shared Subscriptions: Practical Guidelines and Use Cases | MQTT 5 Features](https://www.emqx.com/en/blog/introduction-to-mqtt5-protocol-shared-subscription) 
+
+## Subscription Options
+
+MQTT Subscription Options empower clients to customize how they receive messages. MQTT 5.0 introduces four key options to enhance flexibility and control: QoS, No Local, Retain As Published, and Retain Handling. These options allow users to manage message quality, avoid message loops in bridging, preserve the Retain flag, and decide when to receive retained messages.
+
+EMQX fully supports all MQTT 5.0 subscription options, enabling fine-grained control over message delivery behavior. For example, it helps users prevent message storms in bridge setups with No Local, and ensures consistent retained message handling across brokers with Retain As Published.
+
+Read more: [MQTT  Subscription Options Explained and Example  | MQTT 5 Features](https://www.emqx.com/en/blog/an-introduction-to-subscription-options-in-mqtt) 
+
+## Subscription Identifier
+
+The Subscription Identifier in MQTT 5.0 assigns a unique identifier to each subscription, allowing clients to manage and track multiple subscriptions efficiently. This feature is particularly useful in complex applications with numerous subscriptions.
+
+EMQX fully supports this feature, allowing clients to accurately identify which subscription a message originates from, even in cases of wildcard or overlapping subscriptions. By including Subscription Identifiers in PUBLISH packets, EMQX eliminates the need for topic filter matching at the client side, significantly improving message processing efficiency and enabling precise callback execution. 
+
+Read more: [MQTT Subscription Identifier Explained and Example | MQTT 5 Features](https://www.emqx.com/en/blog/subscription-identifier-and-subscription-options) 
+
+## Keep Alive
+
+The MQTT Keep Alive mechanism prevents half-open TCP connections by requiring the client to send regular packets within a set interval. If no data is sent, a `PINGREQ` is used to confirm connectivity. EMQX fully supports both client-specified and server-enforced Keep Alive values, including MQTT 5.0’s Server Keep Alive feature. Through configuration fields like `server_keepalive` and `keepalive_backoff`, EMQX allows fine-grained control over connection timeouts, enhancing reliability in IoT deployments and ensuring timely Will Message delivery when clients disconnect unexpectedly.
+
+Read more: [What is the MQTT Keep Alive parameter for?](https://www.emqx.com/en/blog/mqtt-keep-alive) 
+
+## Message Expiry Interval
+
+Message Expiry Interval in MQTT 5.0 allows clients to set a time limit for how long a message should be stored by the broker if it cannot be delivered immediately. After the interval expires, the message is discarded, preventing outdated information from being sent.
+
+EMQX fully supports this feature, including decrementing the expiry interval during message forwarding or bridging, ensuring message timeliness across distributed deployments.
+
+Read more: [Introduction to MQTT Message Expiry Interval | MQTT 5 Features](https://www.emqx.com/en/blog/mqtt-message-expiry-interval) 
+
+## Maximum Packet Size
+
+The Maximum Packet Size property in MQTT 5.0 allows clients and servers to negotiate a safe upper limit for packet size, preventing resource exhaustion on constrained devices. Clients declare their receiving limit in the `CONNECT` packet, while servers respond with their limit via the `CONNACK` packet. EMQX enforces this bi-directional constraint and ensures protocol compliance, dropping oversized messages or stripping low-priority metadata (like User Properties) from response packets to maintain connection stability. In shared subscription scenarios, EMQX can redirect oversized messages to eligible group members.
+
+Read more: [MQTT Maximum Packet Size Explained and Example | MQTT 5 Features](https://www.emqx.com/en/blog/best-practices-of-maximum-packet-size-in-mqtt) 
+
+## Reason Codes
+
+MQTT 5.0 introduces a comprehensive Reason Code system that significantly enhances protocol feedback compared to MQTT 3.1.1’s limited status responses. These Reason Codes provide detailed results for connection, publish, subscribe, and other operations, enabling developers to quickly diagnose issues and optimize device management and message interactions.
+
+EMQX fully supports MQTT 5.0 Reason Codes, empowering users with precise error handling and intelligent operation management to improve IoT system stability and responsiveness.
+
+Read more: [MQTT Reason Code Introduction and Quick Reference](https://www.emqx.com/en/blog/mqtt5-new-features-reason-code-and-ack) 
+
+## Enhanced Authentication
+
+MQTT 5.0 introduces Enhanced Authentication, a more secure framework beyond simple password authentication, addressing its vulnerabilities, such as plaintext password transmission and lack of mutual identity verification. Enhanced Authentication leverages the AUTH packet to support multiple message exchanges and SASL mechanisms like DIGEST-MD5, SCRAM, and Kerberos.
+
+EMQX supports SCRAM, enabling users to choose stronger, flexible authentication methods to safeguard their IoT infrastructures. 
+
+Read more: [Leveraging Enhanced Authentication for MQTT Security](https://www.emqx.com/en/blog/leveraging-enhanced-authentication-for-mqtt-security) 
+
+## Control Packets
+
+MQTT control packets define how clients and brokers communicate, including 15 types covering operations like connecting, publishing, and subscribing. Each packet includes a Fixed Header, optional Variable Header, and optional Payload, structured for lightweight and efficient data exchange. MQTT 5.0 further enhances flexibility by introducing properties and improved authentication.
+
+Read more: [MQTT Control Packets: A Beginner's Guide](https://www.emqx.com/en/blog/introduction-to-mqtt-control-packets) 
+
+ For more information about MQTT, please visit: [MQTT Guide 2025: Beginner to Advanced](https://www.emqx.com/en/mqtt-guide) 

en_US/design/mqtt-basics.md

@@ -0,0 +1,43 @@
+# MQTT Basics
+
+## What is MQTT and Why Does It Matter
+
+MQTT (Message Queuing Telemetry Transport) is a lightweight, publish-subscribe messaging protocol optimized for high-latency or unreliable networks—perfect for IoT scenarios. It enables devices to communicate in real-time using a broker model, making it a standard for smart homes, industrial automation, and connected vehicles.
+
+**Read more:** [Mastering MQTT: The Ultimate Beginner's Guide for 2025](https://www.emqx.com/en/blog/the-easiest-guide-to-getting-started-with-mqtt) 
+
+## MQTT Publish-Subscribe Pattern
+
+The publish-subscribe pattern in MQTT decouples message producers (publishers) from consumers (subscribers). Publishers send messages to topics without knowledge of subscribers, and subscribers receive messages from topics without knowledge of publishers. This model enhances scalability and flexibility in message distribution.
+
+**Read more:** [Introduction to MQTT Publish-Subscribe Pattern](https://www.emqx.com/en/blog/mqtt-5-introduction-to-publish-subscribe-model) 
+
+## How to Establish an MQTT Connection?
+
+Establishing an MQTT connection involves a client initiating a connection to a broker, optionally providing authentication credentials, and specifying connection parameters like the keep-alive interval and clean session flag. Proper configuration ensures reliable and secure communication.
+
+**Read more:** [How to Set Parameters When Establishing an MQTT Connection?](https://www.emqx.com/en/blog/how-to-set-parameters-when-establishing-an-mqtt-connection) 
+
+## MQTT Topics and Wildcards
+
+MQTT topics define the routing structure for publish/subscribe messaging. By using hierarchical topic levels and wildcards (`+` for single-level, `#` for multi-level), developers can flexibly subscribe to entire device groups or sensor types. EMQX fully supports MQTT standard topic matching and enhances it with powerful features such as wildcard subscription management, shared subscriptions, and fine-grained access control. Understanding how topics and wildcards work is key to building scalable, secure, and efficient IoT applications with EMQX.
+
+**Read more:** [MQTT Topics and Wildcards: A Beginner's Guide](https://www.emqx.com/en/blog/advanced-features-of-mqtt-topics) 
+
+## MQTT Session
+
+MQTT sessions help maintain client context across network interruptions, addressing issues like missed messages or re-subscription overheads. Sessions store critical data such as client subscriptions and QoS messages, allowing seamless communication even after disconnections. MQTT 5.0 introduces key parameters like **Clean Start** and **Session Expiry Interval** to control session lifecycles, offering flexibility in session retention. Clean Start determines whether to reuse an existing session, while Session Expiry Interval defines how long sessions are kept after disconnections. EMQX enhances session management by providing fine-tuned control over session expiration, improving resource efficiency and system reliability, especially for IoT scenarios with intermittent connectivity.
+
+**Read more:** [Introduction to MQTT Clean Start and Session Expiry Interval | MQTT 5 Features](https://www.emqx.com/en/blog/mqtt5-new-feature-clean-start-and-session-expiry-interval) 
+
+## MQTT QoS and Protocol Flows
+
+MQTT defines three Quality of Service (QoS) levels to balance message delivery reliability and network efficiency:
+
+- QoS 0: At most once delivery
+- QoS 1: At least once delivery
+- QoS 2: Exactly once delivery
+
+Each level dictates the protocol flow between client and broker to ensure the desired delivery guarantee.
+
+**Read more:** [MQTT QoS 0, 1, 2 Explained: A Quickstart Guide](https://www.emqx.com/en/blog/introduction-to-mqtt-qos) 

en_US/design/mqtt-guide.md

@@ -0,0 +1,15 @@
+# MQTT Guide
+
+Welcome to EMQX's comprehensive MQTT Guide. Whether you're a beginner just getting started or a developer seeking deeper insights, this guide provides a clear, step-by-step journey through MQTT basic and advanced features, drawing from EMQX’s most valuable blog content. For each topic, you’ll find a link to the full article for in-depth exploration.
+
+## MQTT Basics
+
+The MQTT Basics section introduces the core concepts of MQTT, including how the protocol works, how devices connect, and how messages are exchanged. You’ll learn about topics and wildcards, session management, QoS levels, and the foundational publish/subscribe pattern. This section is ideal for developers new to MQTT or those who want a solid grounding before exploring more advanced features.
+
+Go to [MQTT Basics](./mqtt-basics.md).
+
+## MQTT Advanced
+
+The MQTT Advanced section builds on the basics and explores powerful MQTT 5.0 features such as retained and will messages, request/response communication, topic aliasing, user properties, and enhanced authentication. It’s perfect for users looking to optimize performance, scalability, and reliability in complex or large-scale deployments.
+
+Go to [MQTT Advanced](./mqtt-advanced.md).