From 7ab819470d35725c95a9fa0a28584a45c71a9def Mon Sep 17 00:00:00 2001 From: Iain Anderson Date: Mon, 17 Jan 2022 12:10:15 +0000 Subject: [PATCH] feat: Device functions ADR Align with north-south messaging ADR (#23) Signed-off-by: Iain Anderson --- .../device-service/0021-invoking-functions.md | 58 ++++++++++++++----- 1 file changed, 42 insertions(+), 16 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 index 9b1b2b0287..b9a95c658f 100644 --- a/docs_src/design/adr/device-service/0021-invoking-functions.md +++ b/docs_src/design/adr/device-service/0021-invoking-functions.md @@ -62,27 +62,37 @@ 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" + } } ``` @@ -90,9 +100,13 @@ 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)