Skip to content

Commit

Permalink
docs: Update MQTT example doc
Browse files Browse the repository at this point in the history 
Update MQTT example doc for Levski release

Close edgexfoundry#64

Signed-off-by: bruce <[email protected]>
  • Loading branch information
@weichou1229
weichou1229 committed Aug 15, 2022
1 parent 6249b0d commit 9acf1b9
Showing 1 changed file with 94 additions and 97 deletions.
191 changes: 94 additions & 97 deletions docs_src/examples/Ch-ExamplesAddingMQTTDevice.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# MQTT

EdgeX - Jakarta Release
EdgeX - Levski Release

## Overview

Expand Down Expand Up @@ -119,13 +119,14 @@ deviceCommands:
1. Clone edgex-compose
```
$ git clone [email protected]:edgexfoundry/edgex-compose.git
$ cd edgex-compose
$ git checkout main
```
!!! note
Use **main** branch until **jakarta** is released.
Use **main** branch until **levski** is released.
2. Generate the docker-compose.yml file (notice this includes mqtt-broker)
```
$ cd edgex-compose/compose-builder
$ cd compose-builder
$ make gen ds-mqtt mqtt-broker no-secty ui
```
3. Check the generated file
Expand All @@ -136,21 +137,20 @@ deviceCommands:
### Mount the custom-config
Open the `edgex-compose/compose-builder/docker-compose.yml` file and then add volumes path and environment as shown below:
Create a docker-compose file `docker-compose.override.yml` [to extend the compose file](https://docs.docker.com/compose/extends/#multiple-compose-files) which generated by the compose-builder. In this file, we add volume path and environment variables as shown below:
```yaml
# docker-compose.yml
# docker-compose.override.yml
device-mqtt:
...
environment:
DEVICE_DEVICESDIR: /custom-config/devices
DEVICE_PROFILESDIR: /custom-config/profiles
...
volumes:
- /path/to/custom-config:/custom-config
...
version: '3.7'
services:
device-mqtt:
environment:
DEVICE_DEVICESDIR: /custom-config/devices
DEVICE_PROFILESDIR: /custom-config/profiles
volumes:
- /path/to/custom-config:/custom-config
```

!!! note
Expand All @@ -163,10 +163,10 @@ topics, make the following changes in the device service configuration files:

1. There are two ways to set the environment variables for multi-level topics.

1. If the code is built with compose builder, modify the docker-compose.yml file in edgex-compose/compose-builder:
1. If the code is built with compose builder, modify the docker-compose.override.yml file:

```yaml
# docker-compose.yml
# docker-compose.override.yml

device-mqtt:
...
Expand Down Expand Up @@ -217,7 +217,7 @@ Deploy EdgeX using the following commands:
```
$ cd edgex-compose/compose-builder
$ docker-compose pull
$ docker-compose up -d
$ docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d
```

## Using a MQTT Device Simulator
Expand Down Expand Up @@ -419,13 +419,20 @@ To run the device simulator, enter the commands shown below with the
following changes:
```
$ mv mock-device.js /path/to/mqtt-scripts
$ docker run -d --restart=always --name=mqtt-scripts \
-v /path/to/mqtt-scripts:/scripts \
dersimn/mqtt-scripts --url mqtt://172.17.0.1 --dir /scripts
$ docker run --rm --name=mqtt-scripts \
-v /path/to/mqtt-scripts:/scripts --network host \
dersimn/mqtt-scripts --dir /scripts
```
!!! note
Replace the `/path/to/mqtt-scripts` in the example mv command with the correct path

Then the mqtt-scripts show logs as below:
```
2022-08-12 09:52:42.086 <info> mqtt-scripts 1.2.2 starting
2022-08-12 09:52:42.227 <info> mqtt connected mqtt://127.0.0.1
2022-08-12 09:52:42.733 <info> /scripts/mock-device.js loading
```

## Execute Commands

Now we're ready to run some commands.
Expand Down Expand Up @@ -516,31 +523,28 @@ Execute a GET command as follows:
$ curl http://localhost:59882/api/v2/device/name/my-custom-device/message | json_pp
{
"event" : {
"origin" : 1624417689920618131,
"readings" : [
"apiVersion":"v2",
"event":{
"apiVersion":"v2",
"deviceName":"my-custom-device",
"id":"13164041-2e6c-4454-9bc3-8e8987e85311",
"origin":1660298227470009014,
"profileName":"my-custom-device-profile",
"readings":[
{
"resourceName" : "message",
"binaryValue" : null,
"profileName" : "my-custom-device-profile",
"deviceName" : "my-custom-device",
"id" : "a3bb78c5-e76f-49a2-ad9d-b220a86c3e36",
"value" : "Hello!",
"valueType" : "String",
"origin" : 1624417689920615828,
"mediaType" : ""
"deviceName":"my-custom-device",
"id":"c58e65b4-62f0-4e41-b368-645993ec0bfd",
"origin":1660298227470005426,
"profileName":"my-custom-device-profile",
"resourceName":"message",
"value":"Hello!",
"valueType":"String"
}
],
"sourceName" : "message",
"deviceName" : "my-custom-device",
"apiVersion" : "v2",
"profileName" : "my-custom-device-profile",
"id" : "e0b29735-8b39-44d1-8f68-4d7252e14cc7"
"sourceName":"message"
},
"apiVersion" : "v2",
"statusCode" : 200
"statusCode":200
}
```

## Schedule Job
Expand All @@ -567,17 +571,13 @@ $ curl http://localhost:59880/api/v2/reading/resourceName/message | json_pp
{
"value" : "test-message",
"id" : "e91b8ca6-c5c4-4509-bb61-bd4b09fe835c",
"mediaType" : "",
"binaryValue" : null,
"resourceName" : "message",
"origin" : 1624418361324331392,
"profileName" : "my-custom-device-profile",
"deviceName" : "my-custom-device",
"valueType" : "String"
},
{
"mediaType" : "",
"binaryValue" : null,
"resourceName" : "message",
"value" : "test-message",
"id" : "1da58cb7-2bf4-47f0-bbb8-9519797149a2",
Expand Down Expand Up @@ -611,31 +611,27 @@ The following results show that the mock device sent the reading every
$ curl http://localhost:59880/api/v2/reading/resourceName/randnum | json_pp

{
"readings" : [
{
"origin" : 1624418475007110946,
"valueType" : "Float32",
"deviceName" : "my-custom-device",
"id" : "9b3d337e-8a8a-4a6c-8018-b4908b57abb8",
"binaryValue" : null,
"resourceName" : "randnum",
"profileName" : "my-custom-device-profile",
"mediaType" : "",
"value" : "2.630000e+01"
},
{
"deviceName" : "my-custom-device",
"valueType" : "Float32",
"id" : "06918cbb-ada0-4752-8877-0ef8488620f6",
"origin" : 1624418460007833720,
"mediaType" : "",
"profileName" : "my-custom-device-profile",
"value" : "2.570000e+01",
"resourceName" : "randnum",
"binaryValue" : null
},
...
],
"readings" : [
{
"origin" : 1624418475007110946,
"valueType" : "Float32",
"deviceName" : "my-custom-device",
"id" : "9b3d337e-8a8a-4a6c-8018-b4908b57abb8",
"resourceName" : "randnum",
"profileName" : "my-custom-device-profile",
"value" : "2.630000e+01"
},
{
"deviceName" : "my-custom-device",
"valueType" : "Float32",
"id" : "06918cbb-ada0-4752-8877-0ef8488620f6",
"origin" : 1624418460007833720,
"profileName" : "my-custom-device-profile",
"value" : "2.570000e+01",
"resourceName" : "randnum",
},
...
],
"statusCode" : 200,
"apiVersion" : "v2"
}
Expand All @@ -645,24 +641,24 @@ $ curl http://localhost:59880/api/v2/reading/resourceName/randnum | json_pp

MQTT Device Service has the following configurations to implement the MQTT protocol.

| Configuration | Default Value | Description |
| ------------------------------------ | ------------- | ------------------------------------------------------------ |
| MQTTBrokerInfo.Schema | tcp | The URL schema |
| MQTTBrokerInfo.Host | 0.0.0.0 | The URL host |
| MQTTBrokerInfo.Port | 1883 | The URL port |
| MQTTBrokerInfo.Qos | 0 | Quality of Service 0 (At most once), 1 (At least once) or 2 (Exactly once) |
| MQTTBrokerInfo.KeepAlive | 3600 | Seconds between client ping when no active data flowing to avoid client being disconnected. Must be greater then 2 |
| MQTTBrokerInfo.ClientId | device-mqtt | ClientId to connect to the broker with |
| MQTTBrokerInfo.CredentialsRetryTime | 120 | The retry times to get the credential |
| MQTTBrokerInfo.CredentialsRetryWait | 1 | The wait time(seconds) when retry to get the credential |
| MQTTBrokerInfo.ConnEstablishingRetry | 10 | The retry times to establish the MQTT connection |
| MQTTBrokerInfo.ConnRetryWaitTime | 5 | The wait time(seconds) when retry to establish the MQTT connection |
| MQTTBrokerInfo.AuthMode | none | Indicates what to use when connecting to the broker. Must be one of "none" , "usernamepassword" |
| MQTTBrokerInfo.CredentialsPath | credentials | Name of the path in secret provider to retrieve your secrets. Must be non-blank. |
| MQTTBrokerInfo.IncomingTopic | DataTopic (incoming/data/#) | IncomingTopic is used to receive the async value |
| MQTTBrokerInfo.ResponseTopic | ResponseTopic (command/response/#) | ResponseTopic is used to receive the command response from the device |
| MQTTBrokerInfo.UseTopicLevels | false (true) | Boolean setting to use multi-level topics |
| MQTTBrokerInfo.Writable.ResponseFetchInterval | 500 | ResponseFetchInterval specifies the retry interval(milliseconds) to fetch the command response from the MQTT broker |
| Configuration | Default Value | Description |
|-----------------------------------------------|------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| MQTTBrokerInfo.Schema | tcp | The URL schema |
| MQTTBrokerInfo.Host | localhost | The URL host |
| MQTTBrokerInfo.Port | 1883 | The URL port |
| MQTTBrokerInfo.Qos | 0 | Quality of Service 0 (At most once), 1 (At least once) or 2 (Exactly once) |
| MQTTBrokerInfo.KeepAlive | 3600 | Seconds between client ping when no active data flowing to avoid client being disconnected. Must be greater then 2 |
| MQTTBrokerInfo.ClientId | device-mqtt | ClientId to connect to the broker with |
| MQTTBrokerInfo.CredentialsRetryTime | 120 | The retry times to get the credential |
| MQTTBrokerInfo.CredentialsRetryWait | 1 | The wait time(seconds) when retry to get the credential |
| MQTTBrokerInfo.ConnEstablishingRetry | 10 | The retry times to establish the MQTT connection |
| MQTTBrokerInfo.ConnRetryWaitTime | 5 | The wait time(seconds) when retry to establish the MQTT connection |
| MQTTBrokerInfo.AuthMode | none | Indicates what to use when connecting to the broker. Must be one of "none" , "usernamepassword" |
| MQTTBrokerInfo.CredentialsPath | credentials | Name of the path in secret provider to retrieve your secrets. Must be non-blank. |
| MQTTBrokerInfo.IncomingTopic | DataTopic (incoming/data/#) | IncomingTopic is used to receive the async value |
| MQTTBrokerInfo.ResponseTopic | ResponseTopic (command/response/#) | ResponseTopic is used to receive the command response from the device |
| MQTTBrokerInfo.UseTopicLevels | false (true) | Boolean setting to use multi-level topics |
| MQTTBrokerInfo.Writable.ResponseFetchInterval | 500 | ResponseFetchInterval specifies the retry interval(milliseconds) to fetch the command response from the MQTT broker |

!!! note
**Using Multi-level Topic:** Remember to change the defaults in parentheses in the table above.
Expand All @@ -672,14 +668,15 @@ MQTT Device Service has the following configurations to implement the MQTT proto
The user can override any of the above configurations using `environment:` variables to meet their requirement, for example:

```yaml
# docker-compose.yml

device-mqtt:
. . .
environment:
MQTTBROKERINFO_CLIENTID: "my-device-mqtt"
MQTTBROKERINFO_CONNRETRYWAITTIME: "10"
MQTTBROKERINFO_USETOPICLEVELS: "false"
...
# docker-compose.override.yml

version: '3.7'

services:
device-mqtt:
environment:
MQTTBROKERINFO_CLIENTID: "my-device-mqtt"
MQTTBROKERINFO_CONNRETRYWAITTIME: "10"
MQTTBROKERINFO_USETOPICLEVELS: "false"
```

0 comments on commit 9acf1b9

Please sign in to comment.