From 5a58dfc3a44d485010fd447cb6213340ba8f0f44 Mon Sep 17 00:00:00 2001
From: firest <blankalupo@163.com>
Date: Mon, 10 Apr 2023 14:39:13 +0800
Subject: [PATCH] chore: update README for auto subscribe

---
 apps/emqx_auto_subscribe/README.md | 57 ++++++++++++++++++++++++++----
 1 file changed, 51 insertions(+), 6 deletions(-)

diff --git a/apps/emqx_auto_subscribe/README.md b/apps/emqx_auto_subscribe/README.md
index 96d368715..981e4cb1f 100644
--- a/apps/emqx_auto_subscribe/README.md
+++ b/apps/emqx_auto_subscribe/README.md
@@ -1,9 +1,54 @@
-emqx_auto_subscribe
-=====
+# Auto Subscribe
 
-An OTP application
+This application can help clients automatically subscribe to topics compiled from user definitions when they connect, and the clients no longer need to send the MQTT `SUBSCRIBE ` request.
 
-Build
------
+# How To Use
 
-    $ rebar3 compile
+Add the following configuration items to the `emqx.conf` file
+
+```yaml
+auto_subscribe {
+    topics = [
+        {
+            topic = "c/${clientid}"
+        },
+        {
+            topic = "client/${clientid}/username/${username}/host/${host}/port/${port}"
+            qos   = 1
+            rh    = 0
+            rap   = 0
+            nl    = 0
+        }
+    ]
+}
+```
+
+This example defines two templates, all of which will be compiled into the final topic by replacing placeholders like `${clientid}` `${port}` with the actual values when the client connects.
+
+# Configuration
+
+## Configuration Definition
+
+| Field          | Definition                    | Value Range                                                 | Default |
+| -------------- | ----------------------------- | ----------------------------------------------------------- | ------- |
+| auto_subscribe | Auto subscribe configuration  | topics                                                      | topics  |
+| topics         | Subscription Options          | Subscription configurations list. See `Subscription Option` | []      |
+
+## Subscription Option
+
+| Field | Definition                                                                                              | Value Range                                                     | Default          |
+|-------|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------|------------------|
+| topic | Required. Topic template.                                                                               | String, placeholders supported                                  | No default value |
+| qos   | Optional. Subscription QoS                                                                              | 0 or 1 or 2. Refer to the MQTT QoS definition                   | 0                |
+| rh    | Optional. MQTT version 5.0. Whether to send retain message when a subscription is created.              | 0: Not send the retain message </br>1: Send  the retain message | 0                |
+| rap   | Optional. MQTT version 5.0. When forwarding messages, Whether to send with retain flag                  | 0: Set retain 0</br>1: Keep retain flag                         | 0                |
+| nl    | Optional. MQTT version 5.0. Whether the message can be forwarded to the client when published by itself | 0: Forwarded to self</br>1: Not forwarded to self               | 0                |
+
+## Subscription Placeholders
+
+| Placeholder | Definition                             |
+| ----------- | -------------------------------------- |
+| ${clientid} | Client ID                              |
+| ${username} | Client Username                        |
+| ${ip}       | Client TCP connection local IP address |
+| ${port}     | Client TCP connection local Port       |