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

Websocket Simulator

Edge Xpert provides a containerized testing simulator that periodically returns the sample data to ws://<websocket-server-address>/sample similar to the following:

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

Run the docker command to start the simulator or add it to your local docker-compose.yml file, and here the <websocket-server-address> is websocket-simulator:9999:

docker run -d --name websocket-simulator --network edgexpert_edgex-network iotechsys/websocket-simulator:2.2.0 -addr websocket-simulator:9999

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

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	websocket-simulator	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
   WSS Cert		Certificate of the WebSocket server if it is self-signed	Optional
   Skip Cert Verify	Leave unchecked (false)	Indicates whether to skip verifying the server's certificate chain and host name during TLS connection. If true, device-websocket accepts any certificate presented by the server and any host name in that certificate.	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": "websocket-simulator",
             "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://websocket-simulator:9999/sample.

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"
                }
            ]
        }
    ]
}