Defining your device

A device profile can be thought of as a template or as a type or classification of device. General characteristics about the type of device, the data theses devices provide, and how to command them is all provided in a device profile. Other pages within this document set provide more details about a device profile and its purpose (see core metadata to start). It is typical that as part of the reference information setup sequence, the device service provides the device profiles for the types of devices it manages.

Device Profile

See core metadata API for more details.

Our fictitious device service will manage only the human/dog counting camera, so it only needs to make one POST request to create the monitoring camera device profile. Since device profiles are often represented in YAML, you make a multi-part form-data POST with the device profile file (find the example profile here) to create the Camera Monitor profile.

If you explore the sample profile, you will see that the profile begins with some general information.

  name: "camera-monitor-profile"
  manufacturer: "IOTech"
  model: "Cam12345"
  labels: 
  - "camera"
  description: "Human and canine camera monitor profile"

Each profile has a unique name along with a description, manufacturer, model and collection of labels to assist in queries for particular profiles. These are relatively straightforward attributes of a profile.

EdgeX 2.0

As of Ireland/V2, device profile names may only contain unreserved characters which are ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_~

Resources and Commands

The device profile defines how to communicate with any device that abides by the profile. In particular, it defines the deviceResources and deviceCommands used to send requests to the device (via the device service). See the Device Profile documentation for more background on each of these.

Understanding Device Resources

The device profile describes the elements of data that can be obtained from the device or sensor and how to change a setting on a device or sensor. The data that can be obtained or the setting that can be changed are called resources or more precisely they are referred to as device resources in Edgex. Learn more about deviceReources in the Device Profile documentation.

In this walkthrough example, there are two pieces of data we want to be able to get or read from the camera: dog and human counts. Therefore, both are represented as device resources in the device profile. Additionally, we want to be able to set two settings on the camera: the scan depth and snapshot duration. These are also represented as device resources in the device profile.

  deviceResources:
  -
    name: "HumanCount"
    isHidden: false  #is hidden is false by default so this is just making it explicit for purpose of the walkthrough demonstration
    description: "Number of people on camera"
    properties:
      valueType:  "Int16"
      readWrite: "R"  #designates that this property can only be read and not set
      defaultValue: "0"
  -
    name: "CanineCount"
    isHidden: false
    description: "Number of dogs on camera"
    properties:
      valueType:  "Int16"
      readWrite: "R"  #designates that this property can only be read and not set
      defaultValue: "0"
  -
    name: "ScanDepth"
    isHidden: false
    description: "Get/set the scan depth"
    properties:
      valueType:  "Int16"
      readWrite: "RW"  #designates that this property can be read or set
      defaultValue: "0"

  -
    name: "SnapshotDuration"
    isHidden: false
    description: "Get the snaphot duration"
    properties:
      valueType:  "Int16"
      readWrite: "RW"  #designates that this property can be read or set
      defaultValue: "0"

Understanding Device Commands

Command or more precisely device commands specify access to reads and writes for multiple simultaneous device resources. In other words, device commands allow you to ask for multiple pieces of data from a sensor at one time (or set multiple settings at one time). In this example, we can request both human and dog counts in one request by establishing a device command that specifies the request for both. Get more details on deviceCommands in the Device Profile documentation.

  deviceCommands:
  -
    name: "Counts"
    readWrite: "R"
    isHidden: false
    resourceOperations:
    - { deviceResource: "HumanCount" }
    - { deviceResource: "CanineCount" }

EdgeX 2.0

As of the Ireland release, device commands are automatically created by EdgeX for any device resource that are not specified as hidden (that is where isHidden is set to false or is simply left off the device resource) in the profile. Therefore, you would not define a device command to provide access to a single device resource unless you need to restrict the read/write access to that device resource.

Walkthrough - Device Profile

Use either the Postman or Curl tab below to walkthrough uploading the device profile.

Download the Device Profile

Click on the link below to download and save the device profile (YAML) to your system.

EdgeX_CameraMonitorProfile.yml

Note

Device profiles are stored in core metadata. Therefore, note that the calls in the walkthrough are to the metadata service, which defaults to port 59881.

Upload the Device Profile to EdgeX

PostmanCurl

Make a POST request to http://localhost:59881/api/v2/deviceprofile/uploadfile. The request should not include any additional headers (leave the defaults). In the Body, make sure "form-data" is selected and set the Key to file and then select the device profile file where you saved it (as shown below).

If your API call is successful, you will get a generated id for your new DeviceProfile in the response area.

Make a curl POST request as shown below.

curl -X POST -F 'file=@/path/to/your/profile/here/EdgeX_CameraMonitorProfile.yml' http://localhost:59881/api/v2/deviceprofile/uploadfile

If your API call is successful, you will get a generated id for your new DeviceProfile in the response area.

Warning

Note that the file location in the curl command above needs to be replaced with your actual file location path. Also, if you do not save the device profile file to EdgeX_CameraMonitorProfile.yml, then you will need to replace the file name as well.

Test the GET API

If you make a GET call to the http://localhost:59881/api/v2/deviceprofile/all URL (with Postman or curl) you will get a listing (in JSON) of all the device profiles (and all of its associated deviceResource and deviceCommand) currently defined in your instance of EdgeX, including the one you just added.