Commit c0d0adb7 authored by LibinZhang's avatar LibinZhang Committed by badboy-huaqiao
Browse files

Add doc for mqtt device registration

Signed-off-by: default avatarLibinZhang <zlibin@vmware.com>

Issue #245
parent c6e90bca
main dependabot/go_modules/github.com/eclipse/paho.mqtt.golang-1.3.1 dependabot/go_modules/github.com/eclipse/paho.mqtt.golang-1.3.2 dependabot/go_modules/github.com/eclipse/paho.mqtt.golang-1.3.3 dependabot/go_modules/github.com/eclipse/paho.mqtt.golang-1.3.4 dependabot/go_modules/github.com/edgexfoundry/go-mod-configuration/v2-2.0.0 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.100 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.101 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.102 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.103 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.45 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.46 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.47 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.48 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.49 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.51 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.52 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.54 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.55 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.56 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.60 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.61 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.62 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.64 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.66 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.67 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.69 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.71 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.73 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.74 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.76 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.77 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.78 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.80 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.82 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.83 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.84 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.87 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.89 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.90 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.91 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.93 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.94 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.95 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.97 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.98 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.0.0-dev.99 dependabot/go_modules/github.com/edgexfoundry/go-mod-core-contracts/v2-2.1.0 dependabot/go_modules/github.com/edgexfoundry/go-mod-registry-0.1.27 dependabot/go_modules/github.com/edgexfoundry/go-mod-registry/v2-2.0.1-dev.5 dependabot/go_modules/github.com/edgexfoundry/go-mod-registry/v2-2.0.1-dev.6 dependabot/go_modules/github.com/edgexfoundry/go-mod-registry/v2-2.0.1-dev.7 dependabot/go_modules/github.com/edgexfoundry/go-mod-registry/v2-2.0.1-dev.8 dependabot/go_modules/github.com/edgexfoundry/go-mod-registry/v2-2.0.1-dev.9 dependabot/go_modules/github.com/edgexfoundry/go-mod-registry/v2-2.1.0 dependabot/go_modules/github.com/gorilla/mux-1.8.0 dependabot/go_modules/github.com/gorilla/websocket-1.4.2 dependabot/go_modules/github.com/pelletier/go-toml-1.8.1 dependabot/go_modules/github.com/pelletier/go-toml-1.9.0 dependabot/go_modules/github.com/pelletier/go-toml-1.9.1 dependabot/go_modules/github.com/pelletier/go-toml-1.9.2 dependabot/go_modules/github.com/pelletier/go-toml-1.9.3 dependabot/go_modules/github.com/pelletier/go-toml-1.9.4 dependabot/npm_and_yarn/web/engine.io-4.1.2 dependabot/npm_and_yarn/web/follow-redirects-1.14.7 dependabot/npm_and_yarn/web/follow-redirects-1.14.8 dependabot/npm_and_yarn/web/karma-6.3.14 dependabot/npm_and_yarn/web/karma-6.3.16 dependabot/npm_and_yarn/web/nanoid-3.2.0 dependabot/npm_and_yarn/web/url-parse-1.5.10 master v2.1.1-dev.15 v2.1.1-dev.14 v2.1.1-dev.13 v2.1.1-dev.12 v2.1.1-dev.11 v2.1.1-dev.10 v2.1.1-dev.9 v2.1.1-dev.8 v2.1.1-dev.7 v2.1.1-dev.6 v2.1.1-dev.5 v2.1.1-dev.4 v2.1.1-dev.3 v2.1.1-dev.2 v2.1.1-dev.1 v2.1.0 v2.0.1-dev.33 v2.0.1-dev.32 v2.0.1-dev.31 v2.0.1-dev.30 v2.0.1-dev.29 v2.0.1-dev.28 v2.0.1-dev.27 v2.0.1-dev.26 v2.0.1-dev.25 v2.0.1-dev.24 v2.0.1-dev.23 v2.0.1-dev.22 v2.0.1-dev.21 v2.0.1-dev.20 v2.0.1-dev.19 v2.0.1-dev.18 v2.0.1-dev.17 v2.0.1-dev.16 v2.0.1-dev.15 v2.0.1-dev.14 v2.0.1-dev.13 v2.0.1-dev.12 v2.0.1-dev.11 v2.0.1-dev.10 v2.0.1-dev.9 v2.0.1-dev.8 v2.0.1-dev.7 v2.0.1-dev.6 v2.0.1-dev.5 v2.0.1-dev.4 v2.0.1-dev.3 v2.0.1-dev.2 v2.0.1-dev.1 v2.0.0 v2.0.0-dev.87 v2.0.0-dev.86 v2.0.0-dev.85 v2.0.0-dev.84 v2.0.0-dev.83 v2.0.0-dev.82 v2.0.0-dev.81 v2.0.0-dev.80 v2.0.0-dev.79 v2.0.0-dev.78 v2.0.0-dev.77 v2.0.0-dev.76 v2.0.0-dev.75 v2.0.0-dev.74 v2.0.0-dev.73 v2.0.0-dev.72 v2.0.0-dev.71 v2.0.0-dev.70 v2.0.0-dev.69 v2.0.0-dev.68 v2.0.0-dev.67 v2.0.0-dev.66 v2.0.0-dev.65 v2.0.0-dev.64 v2.0.0-dev.63 v2.0.0-dev.62 v2.0.0-dev.61 v2.0.0-dev.60 v2.0.0-dev.59 v2.0.0-dev.58 v2.0.0-dev.57 v2.0.0-dev.56 v2.0.0-dev.55 v2.0.0-dev.54 v2.0.0-dev.53 v2.0.0-dev.52 v2.0.0-dev.51 v2.0.0-dev.50 v2.0.0-dev.49 v2.0.0-dev.48 v2.0.0-dev.47 v2.0.0-dev.46 v2.0.0-dev.45 v2.0.0-dev.44 v2.0.0-dev.43 v2.0.0-dev.42 v2.0.0-dev.41 v2.0.0-dev.40 v2.0.0-dev.39 v2.0.0-dev.38 v2.0.0-dev.37 v2.0.0-dev.36 v2.0.0-dev.35 v2.0.0-dev.34 v2.0.0-dev.33 v2.0.0-dev.32 v2.0.0-dev.31 v2.0.0-dev.30 v2.0.0-dev.29 v2.0.0-dev.28 v2.0.0-dev.27 v2.0.0-dev.26 v2.0.0-dev.25 v2.0.0-dev.24 v2.0.0-dev.23 v2.0.0-dev.22 v2.0.0-dev.21 v2.0.0-dev.20 v2.0.0-dev.19 v2.0.0-dev.18 v2.0.0-dev.17 v2.0.0-dev.16 v2.0.0-dev.15 v2.0.0-dev.14 v2.0.0-dev.13 v2.0.0-dev.12 v2.0.0-dev.11 v2.0.0-dev.10 v2.0.0-dev.9 v2.0.0-dev.8 v2.0.0-dev.7 v2.0.0-dev.6 v2.0.0-dev.5 v2.0.0-dev.4 v2.0.0-dev.3 v2.0.0-dev.2 v2.0.0-dev.1 v1.3.1-dev.2 v1.3.1-dev.1 v1.3.0 v1.2.2-dev.12 v1.2.2-dev.11 v1.2.2-dev.10 v1.2.2-dev.9 v1.2.2-dev.8 v1.2.2-dev.7 v1.2.2-dev.6 v1.2.2-dev.5 v1.2.2-dev.4 v1.2.2-dev.3
No related merge requests found
Showing with 255 additions and 1 deletion
+255 -1
......@@ -13,7 +13,11 @@
- If you want to learn how to use the UI, you can refer to the user guide [user guide](https://github.com/edgexfoundry/edgex-ui-go/blob/master/docs/UseGuide.md).
- Edgex UI operation video : [youtube](https://www.youtube.com/watch?v=FuR1g64BDE8) . [youku](https://v.youku.com/v_show/id_XNDY5NzExNjcyNA==.html).
- EdgeX UI operation video : [youtube](https://www.youtube.com/watch?v=FuR1g64BDE8) . [youku](https://v.youku.com/v_show/id_XNDY5NzExNjcyNA==.html).
- [Add MQTT Device to EdgeX](./docs/ExamplesAddingMQTTDevice/AddMQTTDeviceToEdgeX.md)
- [EdgeX Documentation](https://wiki.edgexfoundry.org/display/FA/EdgeX+Documentation)
## Install and Deploy
......
# Adding MQTT Device
## 1. Setup an MQTT Broker
If you have already an mqtt broker installed on your machine, skip this step.
```bash
$ docker run -d --name broker -p 1883:1883 eclipse-mosquitto
```
## 2. Setup EdgeX
Using the [Geneva](https://github.com/edgexfoundry/developer-scripts/blob/master/releases/geneva/compose-files/docker-compose-geneva-redis-no-secty.yml) docker version, Uncomment the device mqtt code in the docker compose file, then start edgex (at this time, the default configuration of edgx-device-mqtt can't work. It needs to use EdgeX consul to dynamically modify the configuration of edgex-device-mqtt)
- Uncomment device-mqtt code
![EdgeX-MQTT-DockerCompose](./images/UncommentMQTT.png)
- Start EdgeX
EdgeX docker compose file with no-secty suffix does not enable Edgex security components(EdgeX kong gateway).
```
docker-compose -f docker-compose-geneva-redis-no-secty.yml up -d
docker-compose -f docker-compose-geneva-ui.yml up -d
```
## 3. Modify device-mqtt Driver Configuration
- With a modern browser, navigate to http://yourhostip:8500 (EdgeX consul UI), Go to Key / Values > edgex > devices > 1.0 > edgex-device-mqtt > Driver page.
![DriverConfig](./images/DriverConfig.png)
- Modify 0.0.0.0 of incominghost and responsehost to yourhostip.
- Restart the edgex-device-mqtt docker container.
## 4. Register a New MQTT Device to EdgeX
- Login in EdgeX UI(http://yourhostip:4000), navigate to DeviceService page -> Device Profile.
- Upload mqtt device profile.
[mqtt.test.device.profile.yml](mqtt/mqtt.test.device.profile.yml)
![UploadDeviceProfile](images/NavigateToDeviceProfileUpload.png)
- Add Device
Navigate to DeviceService page -> Devices,click "+" button.
![AddDevice](images/NavigateToDevices.png)
Select or input required paramters.
![DeviceConfig](images/AddDeviceConfig.png)
## 5. Create a mock device to simulate a real device.
Use following script to simulate the MQTT device.
This simulator has three behaviors:
1. Publish random number data every 15 seconds
2. Receive the reading request, then return the response
3. Receive the put request, then change the device value
```javascript
// mock-device.js
function getRandomFloat(min, max) {
return Math.random() * (max - min) + min;
}
const deviceName = "MQ_DEVICE";
let message = "test-message";
// 1. Publish random number every 15 seconds
schedule('*/59 * * * * *', ()=>{
let body = {
"name": deviceName,
"cmd": "randfloat32",
"randfloat32": getRandomFloat(25,29).toFixed(1)
};
publish( 'DataTopic', JSON.stringify(body));
});
// 2. Receive the reading request, then return the response
// 3. Receive the put request, then change the device value
subscribe( "CommandTopic" , (topic, val) => {
console.log(topic);
console.log(val);
var data = val;
if (data.method == "set") {
message = data[data.cmd]
}else{
switch(data.cmd) {
case "ping":
data.ping = "pong";
break;
case "message":
data.message = message;
break;
case "randfloat32":
data.randfloat32 = getRandomFloat(25,29).toFixed(1);
break;
case "randfloat64":
data.randfloat64 = getRandomFloat(10,1).toFixed(5);
break;
}
}
publish( "ResponseTopic", JSON.stringify(data));
});
```
To run the device simulator, enter the commands shown below with the following changes:
1. Replace the /path/to/mqtt-scripts in the example mv command with the correct path
2. Replace the mqtt-broker-ip in the example docker run command with the correct broker IP:
```
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://mqtt-broker-ip --dir /scripts
```
## 6. Test MQTT Device
Navigate to Deviceservice page -> Devices -> (edgex-device-mqtt) -> Devices -> Commands, choose a command,then click "send" button.
![SendMQTTDevice](./images/SendMQTTCommand.png)
You can check mqtt-scripts docker logs, it will print received commands.
![MockMQTTDevice](./images/MockMqttDevice.png)
![MockMQTTDeviceLog](./images/MockMqttDeviceLog.png)
docs/ExamplesAddingMQTTDevice/images/AddDeviceConfig.png

287 KB

docs/ExamplesAddingMQTTDevice/images/DriverConfig.png

185 KB

docs/ExamplesAddingMQTTDevice/images/MockMqttDevice.png

166 KB

docs/ExamplesAddingMQTTDevice/images/MockMqttDeviceLog.png

828 KB

docs/ExamplesAddingMQTTDevice/images/NavigateToDeviceProfileUpload.png

428 KB

docs/ExamplesAddingMQTTDevice/images/NavigateToDevices.png

396 KB

docs/ExamplesAddingMQTTDevice/images/SendMQTTCommand.png

370 KB

docs/ExamplesAddingMQTTDevice/images/UncommentMQTT.png

483 KB

# mqtt.test.device.profile.yml
name: "Test.Device.MQTT.Profile"
manufacturer: "Dell"
model: "MQTT-2"
labels:
- "test"
description: "Test device profile"
deviceResources:
- name: randfloat32
description: "device random number with Base64 encoding"
properties:
value:
{ type: "Float32", size: "4", readWrite: "R", defaultValue: "0.00", minimum: "100.00", maximum: "0.00", floatEncoding: "Base64" }
units:
{ type: "String", readWrite: "R", defaultValue: "" }
- name: randfloat64
description: "device random number with e notion"
properties:
value:
{ type: "Float64", size: "4", readWrite: "R", defaultValue: "0.00", minimum: "100.00", maximum: "0.00", floatEncoding: "eNotation" }
units:
{ type: "String", readWrite: "R", defaultValue: "" }
-
name: ping
description: "device awake"
properties:
value:
{ type: "String", size: "0", readWrite: "R", defaultValue: "oops" }
units:
{ type: "String", readWrite: "R", defaultValue: "" }
-
name: message
description: "device notification message"
properties:
value:
{ type: "String", size: "0", readWrite: "W" ,scale: "", offset: "", base: "" }
units:
{ type: "String", readWrite: "R", defaultValue: "" }
deviceCommands:
- name: testrandfloat32
get:
- { index: "1", operation: "get", deviceResource: "randfloat32"}
- name: testrandfloat64
get:
- { index: "1", operation: "get", deviceResource: "randfloat64"}
-
name: testping
get:
- { index: "1", operation: "get", deviceResource: "ping"}
-
name: testmessage
get:
- { index: "1", operation: "get", deviceResource: "message"}
set:
- { index: "1", operation: "set", deviceResource: "message"}
coreCommands:
- name: testrandfloat32
get:
path: "/api/v1/device/{deviceId}/testrandfloat32"
responses:
-
code: "200"
description: "get the random float32 value"
expectedValues: ["randfloat32"]
- code: "500"
description: "internal server error"
expectedValues: []
- name: testrandfloat64
get:
path: "/api/v1/device/{deviceId}/testrandfloat64"
responses:
- code: "200"
description: "get the random float64 value"
expectedValues: ["randfloat64"]
- code: "500"
description: "internal server error"
expectedValues: []
-
name: testping
get:
path: "/api/v1/device/{deviceId}/testping"
responses:
-
code: "200"
description: "ping the device"
expectedValues: ["ping"]
- code: "500"
description: "internal server error"
expectedValues: []
-
name: testmessage
get:
path: "/api/v1/device/{deviceId}/testmessage"
responses:
-
code: "200"
description: "get the message"
expectedValues: ["message"]
- code: "500"
description: "internal server error"
expectedValues: []
put:
path: "/api/v1/device/{deviceId}/testmessage"
parameterNames: ["message"]
responses:
-
code: "204"
description: "set the message."
expectedValues: []
- code: "500"
description: "internal server error"
expectedValues: []
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment