diff --git a/docs_src/examples/Ch-ExamplesAddingMQTTDevice.md b/docs_src/examples/Ch-ExamplesAddingMQTTDevice.md index 8e1a293a17..189a00d1e9 100644 --- a/docs_src/examples/Ch-ExamplesAddingMQTTDevice.md +++ b/docs_src/examples/Ch-ExamplesAddingMQTTDevice.md @@ -1,6 +1,6 @@ # MQTT -EdgeX - Jakarta Release +EdgeX - Levski Release ## Overview @@ -119,13 +119,14 @@ deviceCommands: 1. Clone edgex-compose ``` $ git clone git@github.com: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 @@ -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/#understanding-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 @@ -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: ... @@ -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 @@ -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 mqtt-scripts 1.2.2 starting +2022-08-12 09:52:42.227 mqtt connected mqtt://127.0.0.1 +2022-08-12 09:52:42.733 /scripts/mock-device.js loading +``` + ## Execute Commands Now we're ready to run some commands. @@ -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 @@ -567,8 +571,6 @@ $ 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", @@ -576,8 +578,6 @@ $ curl http://localhost:59880/api/v2/reading/resourceName/message | json_pp "valueType" : "String" }, { - "mediaType" : "", - "binaryValue" : null, "resourceName" : "message", "value" : "test-message", "id" : "1da58cb7-2bf4-47f0-bbb8-9519797149a2", @@ -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" } @@ -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. @@ -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" ```