From 7448e28e7c3178171c17c3ee03aa34b7bc4a1e3b Mon Sep 17 00:00:00 2001 From: Iain Anderson Date: Tue, 7 Dec 2021 14:41:40 +0000 Subject: [PATCH] feat: Device functions ADR Specify asynchronous operation via MessageBus rather than synchronous REST Signed-off-by: Iain Anderson --- .../device-service/0020-invoking-functions.md | 40 ++++++++++++++----- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/docs_src/design/adr/device-service/0020-invoking-functions.md b/docs_src/design/adr/device-service/0020-invoking-functions.md index 8a46d19212..554044f717 100644 --- a/docs_src/design/adr/device-service/0020-invoking-functions.md +++ b/docs_src/design/adr/device-service/0020-invoking-functions.md @@ -63,20 +63,38 @@ this is unintuitive. 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. The function's `name` is intended for UI and logging purposes and should not be used for actual function selection on the device. -**Add a REST endpoint to the device service for performing functions** +**Define MessageBus topics on which function call requests and replies are to be made** -`api/v2/device-funtion//` +`edgex/function-calls/device/[profile-name]/[device-name]/[function-name]` -This shold accept POST requests with parameters sent in a JSON (or CBOR) payload +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) } +} +``` -A successful invocation should return HTTP 200 with the out values in JSON -or CBOR format. +The `requestId` may be any string but UUIDs are recommended. -Returnable errors should be +`edgex/function-responses/device/[profile-name]/[device-name]/[function-name]` -* BAD REQUEST: parameters were missing, wrong type, or out-of-range -* INTERNAL SERVER ERROR: the DS implementation was unable to fulfill the request -* NOT FOUND: no such device, or no such function -* LOCKED: device or service is locked or down (adminstate, operating state) +The device service will provide responses to function calls on this topic. The payload will be + +``` +{ + requestId: "184b894f-a7b7-4d6c-b400-99961d462419", + returnValues: { (a map of return values keyed by value name) } +} +``` + +or if a call fails + +``` +{ + requestId: "184b894f-a7b7-4d6c-b400-99961d462419", + errorMessage "Message indicating the nature of the failure" +} +``` -**Add a REST endpoint to core-command for performing functions** +** The device SDKs will provide an API for the service implementations to implement these operations **