Skip to content

WebSocket example

The WebSocket Device Service is intended to work with third-party services, allowing these services to input data into Edge Xpert.

Start the WebSocket Device Service

To start the WebSocket Device Service, enter the following command: 

edgexpert up device-websocket

Device Onboarding

Once the WebSocket Device Service has been started, devices can be onboarded to Edge Xpert using either the Edge Xpert Manager UI or through Edge Xpert REST API commands. Instructions on how to use both methods are described below.

Device Onboarding with the Edge Xpert Manager UI

Note

Please refer to the Edge Xpert Manager UI Device Management capability for full details.

  1. Ensure the Edge Xpert Manager UI is started, for example: 

    edgexpert up xpert-manager

  2. Open a browser and go to localhost:9090. The default username and password is admin

  3. Using the device profile upload capability, upload the provided example device profile at /usr/share/edgexpert/examples/device-services/websocket/sample-data.yaml

  4. Onboard the WebSocket device using the device onboarding capability. The following values can be used to provision the example WebSocket device.

    Field Example Value Description Required
    Name sample-subscriber Unique name used to identify device Required
    Description WebSocket connection that subscribes to sample data Additional information about the device Optional
    Label websocket Additional information about the device Optional
    Protocol WebSocket The name of the protocol Required
    Scheme ws The scheme of the WebSocket server URL, must be either ws or wss Required
    Host 192.168.56.10 The host address of the WebSocket server URL Required
    Port 9999 The port of the WebSocket server URL Optional
    Path /sample The path of the WebSocket server URL Required
    Self Signed Leave unchecked (false) Indicates the WSS server is CA-signed or self-signed. If true, a server certificate needs to be specified Optional
    Device Profile sample-data The name of the device profile uploaded above Required
    Device Service device-websocket The name of the appropriate device service Required

Device Onboarding with the Edge Xpert REST API

  1. Upload the provided WebSocket example device profile: 

    curl http://localhost:59881/api/v2/deviceprofile/uploadfile -F "file=@/usr/share/edgexpert/examples/device-services/websocket/sample-data.yaml"

  2. Onboard the device using similar values as explained above: 

    curl -X 'POST' \
  'http://localhost:59881/api/v2/device' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "apiVersion": "v2",
    "device": {
      "name": "sample-subscriber",
      "description": "WebSocket connection that subscribes sample data",
      "adminState": "UNLOCKED",
      "operatingState": "UP",
      "labels": [
        "websocket"
      ],
      "serviceName": "device-websocket",
      "profileName": "sample-data",
      "protocolName": "websocket",
      "protocols": {
        "ws": {
          "scheme": "ws",
          "host": "192.168.56.10",
          "port": "9999",
          "path": "/sample"
        }
      }
    }
  }
]'

Parsing and uploading incoming data

Each device represents a WebSocket connection from WebSocket Device Service to a WebSocket server. In the above example, WebSocket Device Service should have established a connection to ws://192.168.56.10:9999/sample. The server should periodically return data similar to the following: 

{
  "Payload": {
    "Int": 100,
    "Float": 123.456,
    "String": "Hello World"
  }
}

Based on the definition of sample-data profile, WebSocket Device Service is able to parse Int, Float, and String values from the JSON payload correctly.

You can verify the data is correctly parsed and being received by Edge Xpert with the following command: 

curl localhost:59880/api/v2/event/device/name/sample-subscriber?limit=1

For example, this might return the following data: 

{
    "apiVersion": "v2",
    "statusCode": 200,
    "totalCount": 42,
    "events": [
        {
            "apiVersion": "v2",
            "id": "c0f2a64b-2963-4548-a4e7-2a248613f2ef",
            "deviceName": "sample-subscriber",
            "profileName": "sample-data",
            "sourceName": "Sample",
            "origin": 1648180423326064902,
            "readings": [
                {
                    "id": "0d9e704a-a62e-43f1-a758-da6f69b8b677",
                    "origin": 1648180423326064902,
                    "deviceName": "sample-subscriber",
                    "resourceName": "Int",
                    "profileName": "sample-data",
                    "valueType": "Int64",
                    "value": "100"
                },
                {
                    "id": "05d8a2ae-9259-4f62-b9be-f723327d13b7",
                    "origin": 1648180423326064902,
                    "deviceName": "sample-subscriber",
                    "resourceName": "Float",
                    "profileName": "sample-data",
                    "valueType": "Float64",
                    "value": "1.234560e+02"
                },
                {
                    "id": "283a91ab-2aac-4da1-ac78-24a5cee373ab",
                    "origin": 1648180423326064902,
                    "deviceName": "sample-subscriber",
                    "resourceName": "String",
                    "profileName": "sample-data",
                    "valueType": "String",
                    "value": "Hello World"
                }
            ]
        }
    ]
}

Back to top