feat: Device functions ADR

Align with north-south messaging ADR (#23)

Signed-off-by: Iain Anderson <[email protected]>

Author: iain-anderson

docs_src/design/adr/device-service/0021-invoking-functions.md

@@ -62,37 +62,51 @@ Note: the `attributes` structure is analagous to `attributes` in a `deviceResour
 
 **Define MessageBus topics on which function call requests and replies are to be made**
 
-`edgex/function-calls/device/[profile-name]/[device-name]/[function-name]`
+`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 +115,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)