EMQX

https://docs.emqx.com/en
Admin
EMQX is a cloud-native MQTT messaging platform and broker for IoT that enables real-time data...
Tokens:1,306,209
Snippets:16,185
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and Start Commands

Source: https://docs.emqx.com/en/device-agent/latest/device-access/sdk-generation/nodejs.html

Standard shell commands to initialize environment variables, install dependencies, and start the device agent.

```bash
cp .env.example .env
npm install
npm run start
```

--------------------------------

### Start Deployment Response

Source: https://docs.emqx.com/en/cloud/latest/api/deployment_manage.html

Example JSON response returned after a successful start request.

```json
{
    "deploymentID": "w41b11c0",
    "deploymentName": "deployment-w41b11c0",
    "operation": "starting"
}
```

--------------------------------

### Install SDK

Source: https://docs.emqx.com/en/neuronex/latest/dev-guide/sdk-tutorial/sdk-tutorial.html

Example commands to navigate to the SDK directory and install the SDK.

```bash
# take version 2.3.0 as an example
$ cd neuron-sdk-2.3.0
# install sdk
$ sudo ./sdk-install.sh
```

--------------------------------

### Start Example with Docker Compose

Source: https://docs.emqx.com/en/emqx/latest/deploy/cluster/lb-haproxy.html

Starts the EMQX and HAProxy example using Docker Compose.

```bash
docker compose up -d
```

--------------------------------

### Clone and Navigate to Example Repository

Source: https://docs.emqx.com/en/emqx/latest/deploy/cluster/lb-nginx.html

Initial setup commands to retrieve the EMQX usage examples and enter the NGINX load balancing directory.

```bash
git clone https://github.com/emqx/emqx-usage-example
cd emqx-usage-example/mqtt-lb-nginx
```

--------------------------------

### Start 1000 Connections

Source: https://docs.emqx.com/en/emqx/latest/performance/benchmark-emqtt-bench.html

Example command to start 1000 connections to an EMQX server.

```bash
./emqtt_bench conn -h emqx-server -c 1000
```

--------------------------------

### Start Node-RED

Source: https://docs.emqx.com/en/emqx/latest/connect-emqx/node-red.html

Command to start the Node-RED server after installation.

```bash
node-red
```

--------------------------------

### Install Flask

Source: https://docs.emqx.com/en/cloud/latest/data_hub/schema-registry-example-external-http.html

Ensure Flask is installed.

```sh
pip install Flask==3.1.0
```

--------------------------------

### Install dependencies and start the HTTP server

Source: https://docs.emqx.com/en/emqx/latest/data-integration/data-bridge-webhook.html

Commands to install the required Flask library and execute the HTTP server script.

```shell
pip install flask

python3 http_server.py
```

--------------------------------

### Cluster Link Resource Metrics Warning Example

Source: https://docs.emqx.com/en/emqx/latest/changes/changes-ee-v6.html

Example of the warning message previously emitted when enabling or disabling an active Cluster Link.

```text
[warning] tag: RESOURCE, msg: handle_resource_metrics_failed, reason: {badkey, matched}, event: matched, ...
```

--------------------------------

### Cluster Link Disconnect Log Example

Source: https://docs.emqx.com/en/emqx/latest/changes/changes-ee-v6.html

Example of the previously cryptic error-level log message for Cluster Link disconnect events that has been replaced with more user-friendly messaging.

```text
2026-05-06T03:00:48.738654+00:00 [error] [PoolWorker] unexpected info: {disconnected,141,#{}}
```

--------------------------------

### Configure Rule Engine Base64 Encoding

Source: https://docs.emqx.com/en/emqx/latest/changes/changes-ee-v6.html

Examples of using base64_encode in rule engine SQL with optional parameters for padding and URL-safe encoding.

```sql
SELECT base64_encode(payload, 'no_padding') as encoded FROM "t/#"
```

```sql
SELECT base64_encode(payload, 'urlsafe') as encoded FROM "t/#"
```

```sql
SELECT base64_encode(payload, 'no_padding', 'urlsafe') as encoded FROM "t/#"
```

--------------------------------

### Rule Engine Error Log Example

Source: https://docs.emqx.com/en/emqx/latest/changes/changes-ee-v6.html

Example of a cryptic error log generated by the rule engine under race conditions prior to the fix.

```text
2026-02-03T13:53:54.576326+00:00 [error] Generic server <0.11323236.0> terminating. Reason: {{badkey,'actions.success'},[{erlang,map_get,['actions.success',#{}],[{error_info,#{module => erl_erts_errors}}]},{emqx_metrics_worker,idx_metric,4,[{file,"emqx_metrics_worker.erl"},{line,683}]},{emqx_metrics_worker,inc,4,[{file,"emqx_metrics_worker.erl"},{line,322}]},{emqx_rule_runtime,do_eval_action_reply_t...
```

--------------------------------

### WebSocket Connection Crash Log

Source: https://docs.emqx.com/en/emqx/latest/changes/changes-ee-v6.html

Example of a crash log observed when WebSocket connections fail after peer closure.

```text
crasher: initial call: cowboy_tls:connection_process/4,
error: {{case_clause,{error,closed}},[
{cowboy_websocket_linger,websocket_send_close,2,[{file,"cowboy_websocket_linger.erl"},{line,752}]},
{cowboy_websocket_linger,websocket_close,3,[{file,"cowboy_websocket_linger.erl"},{line,743}]},
{proc_lib,wake_up,3,[{file,"proc_lib.erl"},{line,340}]}
]}
messages: [
{ssl,{sslsocket,{gen_tcp,#Port<...>,...},[...]},<<130,130,27,93,145,101,251,93>>},
{ssl_closed,{sslsocket,{gen_tcp,#Port<...>,...},[...]}}
], ...
```

--------------------------------

### Protobuf encoding error log

Source: https://docs.emqx.com/en/emqx/latest/changes/changes-ee-v6.html

Example of the error log generated when Protobuf encoding failed due to map field issues.

```text
2025-06-17T06:59:22.725785+00:00 [warning] tag: RULE_SQL_EXEC, clientid: c_emqx, msg: SELECT_clause_exception, reason: {error,{gpb_type_error,{bad_unicode_string,[{value,env},{path,"test.args.key"}]}},[{'$schema_parser_xxx',mk_type_error,3,[{file,"$schema_parser_xxx.erl"},{line,437}]},{'$schema_parser_xxx','-v_map<string,string>/3-lc$^0/1-0-',3,[{file,"$schema_parser_xxx.erl"},{line,429}]},{'$schema_parser_xxx','v_map<string,string>',3,[{file,"$schema_parser_xxx.erl"},{line,429}]},{'$schema_parser_xxx',v_msg_test,3,[{file,"$schema_parser_xxx.erl"},{line,404}]},{'$schema_parser_xxx',encode_msg,3,[{file,"$schema_parser_xxx.erl"},{line,73}]},{emqx_schema_registry_serde,with_serde,2,[{file,"emqx_schema_registry_serde.erl"},{line,212}]}...
```

--------------------------------

### Define Protobuf schema with map fields

Source: https://docs.emqx.com/en/emqx/latest/changes/changes-ee-v6.html

Example schema definition for Protobuf using map fields, which previously encountered encoding issues.

```protobuf
syntax = "proto3";

message test {
map<string, string> args = 1;
}
```

--------------------------------

### Base64 Encoding and Decoding in Rule Engine SQL

Source: https://docs.emqx.com/en/emqx/latest/changes/changes-ee-v6.html

Examples of using base64_encode and base64_decode functions with padding and URL-safe options in Rule Engine SQL queries.

```sql
SELECT base64_encode(payload, 'no_padding') as encoded FROM "t/#"
```

```sql
SELECT base64_encode(payload, 'urlsafe') as encoded FROM "t/#"
```

```sql
SELECT base64_encode(payload, 'no_padding', 'urlsafe') as encoded FROM "t/#"
```

```sql
SELECT base64_decode(payload, 'urlsafe') as decoded FROM "t/#"
```

```sql
SELECT base64_decode(payload, 'urlsafe', 'no_padding') as decoded FROM "t/#"
```

--------------------------------

### Socket Connection Error Log

Source: https://docs.emqx.com/en/emqx/latest/changes/changes-ee-v6.html

Example of the error log generated when a socket-backed TCP listener experiences an unexpected disconnection under high load.

```text
[error] crasher: initial call: emqx_socket_connection:init/4, ..., error: {{case_clause,{select,{select_info,recv,#Ref<...>}}},[{emqx_socket_connection,handle_msg,2,[{file,"emqx_socket_connection.erl"},{line,827}]}, ...]
```

--------------------------------

### RSA Signature Verification Error Log

Source: https://docs.emqx.com/en/emqx/latest/changes/changes-ee-v6.html

Example of the log message generated when RSA signature verification fails due to missing default configurations.

```text
{sign_unsupported,[[{rsa_padding,rsa_pkcs1_padding}]]}, [{jose_jwa_unsupported,verify,5,[{file,"src/jwa/jose_jwa_unsupported.erl"},{line,55}]}
```

--------------------------------

### Example JSON payload for Protobuf encoding

Source: https://docs.emqx.com/en/emqx/latest/changes/changes-ee-v6.html

JSON payload structure that previously failed to encode when using map fields in Protobuf schemas.

```json
{
"args": {
"env": "stag"
}
}
```

--------------------------------

### Snowflake Streaming Action Error Log

Source: https://docs.emqx.com/en/emqx/latest/changes/changes-ee-v6.html

Example of the error message encountered when Snowflake Streaming Actions fail due to a stale continuation token.

```text
{unrecoverable_error,#{body => <<"{\"code\":\"STALE_CONTINUATION_TOKEN_SEQUENCER\",\"message\":\"Channel sequencer in the continuation token is stale. Please reopen the channel\"}">>,...}
```

--------------------------------

### Normalize Sparkplug B Data with spb_zip_kvs

Source: https://docs.emqx.com/en/emqx/latest/changes/changes-ee-v6.html

The spb_zip_kvs function merges keys and values arrays into a unified map for easier processing. The following examples show the input structure and the resulting transformed output.

```json
{
  "metrics": [
    {
      "properties": {
        "values": [
          {"int_value": 99},
          {
            "propertyset_value": {
              "values": [{"int_value": 999}],
              "keys": ["inner"]
            }
          },
          {
            "propertysets_value": {
              "propertyset": [
                {
                  "values": [{"int_value": 1}],
                  "keys": ["inner1"]
                },
                {
                  "values": [{"int_value": 2}],
                  "keys": ["inner2"]
                }
              ]
            }
          }
        ],
        "keys": [
          "leaf",
          "nested_prop",
          "nested_prop_list"
        ]
      }
    },
    {
      "dataset_value": {
        "num_of_columns": 2,
        "types": [7, 12],
        "rows": [
          {
            "elements": [
              {"int_value": 3},
              {"string_value": "3"}
            ]
          },
          {
            "elements": [
              {"int_value": 4},
              {"string_value": "4"}
            ]
          }
        ],
        "columns": ["col1", "col2"]
      }
    }
  ]
}
```

```json
{
  "metrics": [
    {
      "properties": {
        "nested_prop_list": {
          "propertysets_value": [
            {"inner1": {"int_value": 1}},
            {"inner2": {"int_value": 2}}
          ]
        },
        "nested_prop": {
          "propertyset_value": {"inner": {"int_value": 999}}
        },
        "leaf": {"int_value": 99}
      }
    },
    {
      "dataset_value": {
        "col2": {"elements": [{"int_value": 4}, {"string_value": "4"}]},
        "col1": {"elements": [{"int_value": 3}, {"string_value": "3"}]}
      }
    }
  ]
}
```

--------------------------------

### Manual RPM package installation failure example

Source: https://docs.emqx.com/en/emqx/latest/faq/deployment.html

Example of an error encountered when manually installing an RPM package due to a missing libatomic dependency.

```bash
$ rpm -ivh emqx-5.7.0-el8-amd64.rpm
error: Failed dependencies:
	libatomic is needed by emqx-5.7.0-el8-amd64.rpm
```

--------------------------------

### Clone and Navigate to Example Repository

Source: https://docs.emqx.com/en/emqx/latest/gateway/exproto.html

Clone the EMQX extension examples repository and enter the Python server directory.

```bash
git clone https://github.com/emqx/emqx-extension-examples
cd exproto-svr-python
```

--------------------------------

### sublist Function Examples (Start, Length)

Source: https://docs.emqx.com/en/cloud/latest/data_integration/rule-sql-builtin-functions.html

Examples showing the sublist function with start and length parameters to extract a subarray from a specific position.

```sql
sublist(2, 10, [1,2,3,4]) = [2,3,4]
```

--------------------------------

### Set up emqx-ft Client Environment

Source: https://docs.emqx.com/en/emqx/latest/file-transfer/quick-start.html

Download and set up the `emqx-ft` command-line tool and its Python virtual environment.

```bash
git clone https://github.com/emqx/emqx-ft.git
cd emqx-ft
python3 -m venv .venv
source .venv/bin/activate
pip install .
```

--------------------------------

### Clone and Run Electron Quick Start Project

Source: https://docs.emqx.com/en/cloud/latest/connect_to_deployments/electron_sdk.html

Instructions to clone the official Electron quick start repository, install dependencies, and run the application.

```shell
# Clone this repository
git clone https://github.com/electron/electron-quick-start
# Go into the repository
cd electron-quick-start
# Install dependencies
npm install
# Run the app
npm start
```

--------------------------------

### Install Python MQTT dependencies

Source: https://docs.emqx.com/en/cloud/latest/best_practices/enhance_traceability.html

Setup a virtual environment and install the paho-mqtt library.

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install paho-mqtt
```

--------------------------------

### Start EMQX Edge

Source: https://docs.emqx.com/en/emqx-edge/latest/tutorial/webhook.html

Start EMQX Edge with your configuration.

```bash
$ emqx-edge start --conf path/to/nanomq.conf
```

--------------------------------

### Quick Install Script for EMQX

Source: https://docs.emqx.com/en/device-agent/latest/operate-reference/configuration/mqtt-broker.html

Install and start EMQX using a quick install script.

```bash
curl -fsSL emqx.sh | bash
emqx start
```

--------------------------------

### Sample install.sh

Source: https://docs.emqx.com/en/neuronex/latest/api/api-docs.html

An example install.sh script for installing a sample SDK lib.

```bash
dir=/usr/local/mysdk
cur=$(dirname "$0")
echo "Base path $cur"
if [ -d "$dir" ]; then
    echo "SDK path $dir exists."
else
    echo "Creating SDK path $dir"
    mkdir -p $dir
    echo "Created SDK path $dir"
fi

apt install --no-upgrade unzip
if [ -d "$dir/lib" ]; then
    echo "SDK lib path $dir/lib exists."
else
    echo "Unzip SDK lib to path $dir"
    unzip $cur/mysdk.zip -d $dir
    echo "Unzipped SDK lib to path $dir"
fi

if [ -f "/etc/ld.so.conf.d/myconfig.conf" ]; then
    echo "/etc/ld.so.conf.d/myconfig.conf exists"
else
    echo "Copy conf file"
    cp $cur/myconfig.conf /etc/ld.so.conf.d/
    echo "Copied conf file"
fi
ldconfig
echo "Done"

```

--------------------------------

### Base Configuration Example

Source: https://docs.emqx.com/en/emqx/latest/configuration/configuration.html

Recommended structure for base.hocon to manage baseline configurations.

```bash
# base.hocon
listeners.tcp.default {
  bind = "0.0.0.0:1883"
  max_connections = 1024000
}

log.console {
  enable = true
  level = warning
}

authentication = [
  {
    mechanism = password_based
    backend = built_in_database
    user_id_type = username
  }
]
```

--------------------------------

### Start the Python SDK Application

Source: https://docs.emqx.com/en/device-agent/latest/device-access/sdk-generation/python.html

Commands to initialize the environment and execute the device agent.

```bash
cp .env.example .env
uv run device-agent-toolkit
```

```bash
uv run python src/main.py
```

--------------------------------

### Start EMQX in foreground

Source: https://docs.emqx.com/en/emqx/latest/deploy/install-debian.html

Starts the EMQX process in the foreground, typically used after installing from a tar.gz archive.

```bash
./emqx/bin/emqx foreground
```

--------------------------------

### Minimal Startup Environment Variables

Source: https://docs.emqx.com/en/device-agent/latest/operate-reference/configuration.html

Example of essential environment variables for configuring MQTT, LLM providers, and gateway network settings.

```bash
MQTT_BROKER_URL=mqtt://broker.example.com:1883
MQTT_USERNAME=your-username
MQTT_PASSWORD=your-password
VITE_MQTT_WS_URL=wss://broker.example.com:8084/mqtt

LLM_PROVIDER=openai
LLM_MODEL=gpt-5.5
OPENAI_API_KEY=sk-...

AGENT_GATEWAY_HTTP_HOST=127.0.0.1
AGENT_GATEWAY_HTTP_PORT=3000
```

--------------------------------

### Start EMQX as a systemd service

Source: https://docs.emqx.com/en/emqx/latest/deploy/install-debian.html

Use this command to start the EMQX service after a deb package installation.

```bash
sudo systemctl start emqx
```

--------------------------------

### Start NeuronEX

Source: https://docs.emqx.com/en/neuronex/latest/installation/targz.html

Execute the startup script located in the bin directory.

```bash
$ ./bin/neuronex start
```

--------------------------------

### Install and Start EMQX Neuron

Source: https://docs.emqx.com/en/neuronex/latest/best-practise/master-backup.html

Commands to download, install, and enable the EMQX Neuron service on Linux.

```shell
wget https://www.emqx.com/zh/downloads/neuronex/3.4.3/neuronex-3.4.3-linux-amd64.deb

# Install EMQX Neuron
sudo dpkg -i neuronex-3.4.3-linux-amd64.deb

# Start EMQX Neuron
sudo systemctl start neuronex

# Set to start automatically on boot
sudo systemctl enable neuronex
```

--------------------------------

### Get rule metrics response example

Source: https://docs.emqx.com/en/cloud/latest/api/dedicated.html

Example JSON response structure for the rule metrics endpoint.

```json
{
  "id": "293fb66f",
  "metrics": {
    "actions.discarded": 0,
    "actions.failed": 0,
    "actions.failed.out_of_service": 0,
    "actions.failed.unknown": 0,
    "actions.success": 0,
    "actions.total": 0,
    "failed": 0,
    "failed.exception": 0,
    "failed.unknown": 0,
    "matched": 0,
    "matched.rate": 0,
    "matched.rate.last5m": 0,
    "matched.rate.max": 0,
    "passed": 0
},
  "node_metrics": [
    {
      "actions.discarded": 0,
      "actions.failed": 0,
      "actions.failed.out_of_service": 0,
      "actions.failed.unknown": 0,
      "actions.success": 0,
      "actions.total": 0,
      "failed": 0,
      "failed.exception": 0,
      "failed.unknown": 0,
      "matched": 0,
      "matched.rate": 0,
      "matched.rate.last5m": 0,
      "matched.rate.max": 0,
      "node": "emqx@127.0.0.1",
      "passed": 0
}
]

}
```

--------------------------------

### Set up a Simple HTTP Service

Source: https://docs.emqx.com/en/cloud/latest/data_integration/http_server.html

Initializes and starts a basic HTTP server using Python's standard library.

```python
httpd = HTTPServer(('0.0.0.0', 8080), SimpleHTTPRequestHandler)
httpd.serve_forever()
```

--------------------------------

### Setup Function

Source: https://docs.emqx.com/en/cloud/latest/connect_to_deployments/esp32.html

Initialize serial communication, connect to WiFi, set MQTT broker details, and establish connection to the MQTT broker.

```c++
void setup() {
    Serial.begin(115200);
    connectToWiFi();
    mqtt_client.setServer(mqtt_broker, mqtt_port);
    mqtt_client.setKeepAlive(60);
    mqtt_client.setCallback(mqttCallback); // Corrected callback function name
    connectToMQTT();
}

void connectToWiFi() {
    WiFi.begin(ssid, password);
    Serial.print("Connecting to WiFi");
    while (WiFi.status() != WL_CONNECTED) {
        delay(500);
        Serial.print(".");
    }
    Serial.println("\nConnected to WiFi");
}
```

--------------------------------

### Install Python gRPC Dependencies

Source: https://docs.emqx.com/en/emqx/latest/gateway/exproto.html

Install the necessary grpcio and grpcio-tools packages to run the example gRPC server.

```bash
python -m pip install grpcio
python -m pip install grpcio-tools
```

--------------------------------

### Compile and Install NGINX

Source: https://docs.emqx.com/en/emqx/latest/deploy/cluster/lb-nginx.html

Build the NGINX binary and install it to the system path.

```bash
make
```

```bash
sudo make install
sudo ln -s /usr/local/nginx/sbin/nginx /usr/local/bin/nginx
```

--------------------------------

### GET /api/v5/plugins

Source: https://docs.emqx.com/en/emqx/latest/extensions/plugin-management.html

Lists all installed plugins.

```APIDOC
## GET /api/v5/plugins

### Description
Retrieves a list of all installed plugins.

### Method
GET

### Endpoint
/api/v5/plugins
```

--------------------------------

### Start the EMQX-Edge service

Source: https://docs.emqx.com/en/emqx-edge/latest/installation/windows.html

This command starts the EMQX Edge Windows service.

```shell
net start EMQX-Edge
```

--------------------------------

### Install Datalayers using Docker

Source: https://docs.emqx.com/en/emqx/latest/data-integration/data-bridge-datalayers.html

This command installs and starts Datalayers using Docker.

```bash
docker run -d -p 8080:8080 -p 5432:5432 -p 9092:9092 --name datalayers datalayers/datalayers:latest
```

--------------------------------

### Extract and navigate to the installation directory

Source: https://docs.emqx.com/en/neuronex/latest/installation/targz.html

Decompress the downloaded archive and enter the resulting directory.

```bash
$ tar -zxvf neuronex-3.9.2-linux-amd64.tar.gz
$ cd neuronex-3.9.2-linux-amd64
```

--------------------------------

### Get Version Response Sample

Source: https://docs.emqx.com/en/neuronex/latest/api/api-docs.html

Example JSON response for getting the Neuron version.

```json
{
  "build_date": "2022-06-01",
  "revision": "99e2184+dirty",
  "version": "2.4.0"

}
```

--------------------------------

### Start plugin

Source: https://docs.emqx.com/en/emqx/latest/admin/cli.html

Starts a specified plugin.

```bash
emqx ctl plugins start emqx_auth_mnesia-3.0.1
```
Tokens:
Raw