# MQTT Topic Structure ### Device-Specific Topics Topics prefixed with a unique device identifier (``, e.g., device ID) for one-to-one communication: | Topic Format | Purpose | Message Flow | |-------------------------------|-------------------------------------------------------------------------|-----------------------| | `/rpc/subscribe` | Device subscribes to receive Remote Procedure Call (RPC) commands | Client → Device | | `/rpc/publish` | Device publishes RPC responses or proactive status reports | Device → Client | | `/notify` | Device pushes real-time status change notifications (e.g., switch state) | Device → Client | | `/online` | Device reports online status (heartbeat) or clients monitor connectivity | Bidirectional | ### Global Topics Topics prefixed with `refoss` for one-to-many communication, accessible to all Refoss devices configured with MQTT: | Topic Format | Purpose | Message Flow | |-------------------------------|-------------------------------------------------------------------------|-----------------------------| | `refoss/command/subscribe` | Devices subscribe to receive global commands (e.g., bulk upgrades) | Server/Client → Device | | `refoss/command/publish` | Clients publish global commands routed to subscribed devices | Client → Server/Device | # Mqtt.Config.Get ### Function Description Retrieve the configuration of the MQTT service on the device, including connection parameters, security settings, and topic configurations. ### Request | Attribute | Type | Description | Required | |-----------|--------|----------------------|----------| | *None* | - | No parameters required. | - | ### Response **Attributes in the result:** | Attribute | Type | Description | Required | |-----------------|-----------|-----------------------------------------------------------------------------|----------| | enable | bool | `true` if MQTT connection is enabled; `false` otherwise. | Y | | server | string | Hostname of the MQTT server (format: `host:port`). `null` if not configured. | N | | client_id | string | Unique client identifier for the MQTT broker. `null` means the device ID is used. | N | | user | string | Username for MQTT authentication. `null` if not set. | N | | topic_prefix | string | Prefix for device-specific MQTT topics (max 300 characters).
- Cannot start with `$` or `#`, and must not contain `+`, `%`, or `?`.
`null` means the device ID is used. | N | | rpc_ntf | bool | Enables RPC notifications (default: `true`). | N | | enable_ctrl | bool | Enables MQTT control functionality (default: `false`). | N | | ssl_ca | string | TLS/SSL configuration:
- `null`: Plain TCP connection.
- `*`: TLS with certificate validation disabled.
- `user_ca.pem`: TLS with user-provided CA certificate.
- `ca.pem`: TLS with built-in CA bundle validation.
- `use_client_cert`: TLS with mutual authentication (client certificate). | N | | use_client_cert | bool | Indicates whether client certificate authentication is enabled for TLS. | N | | enable_rpc | bool | Enables RPC over MQTT (default: `true`). | N | ### Usage Examples #### 1. API Direct Request (WEB-Suitable) **Request:** ```json { "id": 0, "src": "9c1887b8-0418-4f71-b40a-f5631f5a8cab", "method": "Mqtt.Config.Get", "params": {} } ``` **Response:** ```json { "id": 0, "src": "refoss-r11-34298f1f4680", "dst": "9c1887b8-0418-4f71-b40a-f5631f5a8cab", "result": { "enable": true, "server": "mqtt.refoss.com:1883", "client_id": "refoss-r11-34298f1f4680", "user": "admin", "topic_prefix": "r11-34298f1f4680", "rpc_ntf": true, "enable_ctrl": true, "ssl_ca": "ca.pem", "use_client_cert": false, "enable_rpc": true } } ``` #### 2. HTTP GET Request **Request:** ```url http://10.10.10.1/rpc/Mqtt.Config.Get ``` **Response:** ```json { "enable": false, "server": null, "user": null, "ssl_ca": null, "topic_prefix": "r11-14csae7c49f1", "rpc_ntf": true, "enable_ctrl": false, "use_client_cert": false, "enable_rpc": true } ``` # Mqtt.Config.Set ### Function Description This protocol is used to configure the MQTT service on the device, allowing settings for connection status, server address, client ID, and other parameters. ### Request config: | Parameter | Details | |-----------|---------| | `enable` | Boolean. `true` to enable MQTT connection, `false` to disable. This is a required field. | | `server` | String or `null`. Hostname of the MQTT server in the format `host:port`. | | `client_id` | String or `null`. Unique identifier for the MQTT client. If `null`, the device ID is used as the `client_id`. | | `user` | String or `null`. Username for authentication. | | `topic_prefix` | String or `null`. Prefix for device publish/subscribe topics (max 300 characters). Cannot start with `$` or `#`, and must not contain `+`, `%`, or `?`. If `null`, the device ID is used as the topic prefix. | | `rpc_ntf` | Boolean. Enables RPC notifications (default: `true`). | | `enable_ctrl` | Boolean. Enables remote control (default: `false`). | | `ssl_ca` | String or `null`. Configures security settings for the connection:
- `null`: Plain TCP connection
- `*`: TLS with certificate validation disabled
- `user_ca.pem`: TLS with user-provided CA certificate validation
- `ca.pem`: TLS with built-in CA bundle validation
- `use_client_cert`: TLS with mutual authentication (client certificate) | ### Response | Attribute | Type | Description | Required | |--------------------|---------|----------------------------------------------|----------| | `restart_required` | bool | Indicates whether the device needs to restart to apply the new configuration. | Y | ### Usage Examples #### 1. API Direct Request (WEB-Suitable) **Request:** ```json { "id": 0, "src": "9c1887b8-0418-4f71-b40a-f5631f5a8cab", "method": "Mqtt.Config.Set", "params": { "config": { "enable": true, "server": "broker.hivemq.com:1883" } } } ``` **Response:** ```json { "id": 0, "src": "refoss-r11-34298f1f4680", "dst": "9c1887b8-0418-4f71-b40a-f5631f5a8cab", "result": { "restart_required": true } } ``` #### 2. HTTP GET Request **Request:** ```plaintext http://10.10.10.1/rpc/Mqtt.Config.Set?config={"enable":true,"server":"broker.hivemq.com:1883"} ``` **Response:** ```json { "restart_required": true } ``` # Mqtt.Status.Get ### Function Description This protocol is used to obtain the status of the MQTT service. ### Request No parameters are required for this request. ### Response The attributes in the result are as follows: | Attribute | Type | Description | Required | | --- | --- | --- | --- | | connected | bool | `true` if the device is connected to the MQTT service; `false` otherwise. | Y | ### Usage Examples #### 1. API Direct Request (Suitable for WEB) **Request**: ```json { "id": 0, "src": "9c1887b8-0418-4f71-b40a-f5631f5a8cab", "method": "Mqtt.Status.Get", "params": {} } ``` **Response**: ```json { "id": 0, "src": "refoss-r11-34298f1f4680", "dst": "9c1887b8-0418-4f71-b40a-f5631f5a8cab", "result": { "connected": false } } ``` #### 2. HTTP GET Request **Request**: ```plaintext http://10.10.10.1/rpc/Mqtt.Status.Get ``` **Response**: ```json { "connected": false } ```