feat: Device functions ADR

Align with north-south messaging ADR (#23) Signed-off-by: Iain Anderson <[email protected]>
edgexfoundry · Jan 17, 2022 · 8f0ee4b · 8f0ee4b
1 parent 0d6d03b
commit 8f0ee4b
Showing 1 changed file with 47 additions and 19 deletions.
diff --git a/docs_src/design/adr/device-service/0021-invoking-functions.md b/docs_src/design/adr/device-service/0021-invoking-functions.md
@@ -39,7 +39,7 @@ this is unintuitive.
         {
           "name": "Parameter name",
           "description": "(optional) description of what the parameter controls",
-          "type": "Any of the usual EdgeX data types",
+          "type": "Any of the existing EdgeX data types",
           "defaultValue": "(optional) value to use if param is not supplied",
           "maximum": "(optional) for numerics, maximum allowed value",
           "minimum": "(optional) for numerics, minimum allowed value"
@@ -50,49 +50,65 @@ this is unintuitive.
         {
           "name": "Name of returned value",
           "description": "(optional) description of what the value indicates",
-          "type": "Any of the usual EdgeX data types"
+          "type": "Any of the existing EdgeX data types"
         }
       ]
     }
   ]
 }
 ```
 
-Note: the `attributes` structure is analagous to `attributes` in a `deviceResource`. Each device service should document and implement a scheme of required attributes that will allow for selection of the relevant funtion.
+Note: the `attributes` structure is analagous to `attributes` in a `deviceResource`. Each device service should document and implement a scheme of required attributes that will allow for selection of the relevant function.
 
 **Define MessageBus topics on which function call requests and replies are to be made**
 
-`edgex/function-calls/device/[profile-name]/[device-name]/[function-name]`
+These follow the style of messagebus usage set out in the North-South messaging ADR.
+
+`edgex/request/function/[device-service-name]/[device-name]`
 
 The payload for messages on these topics should be of the form
 ```
 {
-  requestId: "184b894f-a7b7-4d6c-b400-99961d462419",
-  parameters: { (a map of parameter values keyed by parameter name) }
+  "correlation-id": "1dbbd344-c9f6-4714-8c89-91c1d5b11a90",
+  "deviceName": "device1",
+  "function": "functionname",
+  "request":
+  {
+    "requestId": "184b894f-a7b7-4d6c-b400-99961d462419",
+    "parameter1": "37",
+    "parameter2": "0"
+  }
 }
-```
 
-The `requestId` may be any string but UUIDs are recommended.
+```
 
-`edgex/function-responses/device/[profile-name]/[device-name]/[function-name]`
+`edgex/response/function/[device-service-name]/[device-name]`
 
 The device service will provide responses to function calls on this topic. The payload will be
 
 ```
 {
-  requestId: "184b894f-a7b7-4d6c-b400-99961d462419",
-  status: 0,
-  returnValues: { (a map of return values keyed by value name) }
+  "correlation-id": "1dbbd344-c9f6-4714-8c89-91c1d5b11a90",
+  "response":
+  {
+    "requestId": "184b894f-a7b7-4d6c-b400-99961d462419",
+    "statusCode": 0,
+    "returnVal1": "true"
+  }
 }
 ```
 
 or if a call fails
 
 ```
 {
-  requestId: "184b894f-a7b7-4d6c-b400-99961d462419",
-  status: (nonzero),
-  errorMessage "Message indicating the nature of the failure"
+  "correlation-id": "1dbbd344-c9f6-4714-8c89-91c1d5b11a90",
+  "response":
+  {
+    "requestId": "184b894f-a7b7-4d6c-b400-99961d462419",
+    "statusCode": (nonzero),
+    "message": "Message indicating the nature of the failure"
+  }
 }
 ```
 
@@ -101,12 +117,24 @@ or if a call fails
 | Status | Meaning
 |--------|--------
 | 0      | The operation was successful
-| 1      | Parameters were missing, out of range or non-parsable
-| 2      | The Device is DOWN or DISABLED (OperatingState / AdminState)
-| 3      | No such device or function
+| 1      | Request message format error
+| 2      | Parameters were missing, out of range or non-parsable
+| 3      | The Device is DOWN or DISABLED (OperatingState / AdminState)
+| 4      | No such device or function
 | 100+   | Implementation-specific errors, defined for each Device Service
 
-** Device SDK enhancement **
+*Configuration*
+
+The topic prefixes `edgex/request/function` and `edgex/response/function` will be configurable in the device services.
+
+**Device SDK enhancement**
 
 The device SDKs will handle the messagebus communcations and parameter marshalling. The generic errors defined above may be detected in this SDK code. The SDKs will define APIs for the individual device services to implement the function invocations.
 
+**Command service enhancement**
+
+The core-command service to be extended to provide access to device functions as it does for device readings and settings.
+
+## References
+
+* [ADR 0023-North-South-Messaging](https://github.com/edgexfoundry/edgex-docs/blob/master/docs_src/design/adr/0023-North-South-Messaging.md)