Skip to content

Commit

Permalink
feat(adr): address comments/issues from tonyespy review of 4/22/22
Browse files Browse the repository at this point in the history
Signed-off-by: jpwhitemn <jpwhite_mn@yahoo.com>
  • Loading branch information
jpwhitemn committed Apr 26, 2022
1 parent db95495 commit 19b473f
Showing 1 changed file with 12 additions and 18 deletions.
30 changes: 12 additions & 18 deletions docs_src/design/adr/0023-North-South-Messaging.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,6 @@ When using messaging to make the "queries" the response message must return info
{
"name": "coolingpoint1",
"topic": "/edgex/command/request/testDevice1/coolingpoint/get",
"url": "broker.address:1883",
"parameters": [
{
"resourceName": "resource1",
Expand All @@ -86,7 +85,6 @@ When using messaging to make the "queries" the response message must return info
{
"name": "coolingpoint1",
"topic": "/edgex/command/request/testDevice1/coolingpoint1/set",
"url": "broker.address:1883",
"parameters": [
{
"resourceName": "resource1",
Expand All @@ -99,6 +97,9 @@ When using messaging to make the "queries" the response message must return info
!!! Note
Per Core WG meeting of 4/7/22 - the JSON above serves as a general example. The implementation will have to address get/set (or read/write) differentiation, but this is considered an implementation detail to be resolved by the developers.

!!! Note
The query response does not contain a URL since it is assumed that the broker address must already be known in order to make the query.

### Message Structure

In REST based command requests (and responses), the HTTP request line contains important information such as the path or target of the request, and the HTTP method type (indicating a GET or PUT request). The HTTP status line provides the information such as the response code (ex: 200 for OK). The body or payload of the HTTP message contains the request details (such as parameters to a device PUT call) or response information (such as events and associated readings from a GET call).
Expand Down Expand Up @@ -134,6 +135,9 @@ Command requests in HTTP may also contain ds-pushevent and ds-returnevent query
}
```

!!! Note
As with REST requests, if the ds-returnvent was `no`, then a message with envelope would be returned but with no payload as there would be no events to return.

#### Command Message Payload

The **request** message `payload` to the command service and those relayed to the device service would mimic their HTTP/REST request body alternatives. The `payload` provides details needed in executing the command at the south side.
Expand All @@ -149,9 +153,6 @@ In the example GET and PUT messages below, note the `envelope` wraps or encases
"ds-pushevent":"yes",
"ds-returnevent":"yes",
}
"payload":
{
}
}

{
Expand All @@ -170,6 +171,10 @@ In the example GET and PUT messages below, note the `envelope` wraps or encases
}
```

!!! Note
Payload could be empty and therefore optional in the message structure - and exemplified in the top example here.


The **response** message `payload` would contain the response from the south side, which is typically EdgeX event/reading objects (in the case of GET requests) but would also include any error message details.

Example response messages for a GET and PUT request are shown below. Again, note that the message `envelope` wraps the response `payload`.
Expand Down Expand Up @@ -248,22 +253,14 @@ In the example query to get all commands below, note the `envelope` wraps or enc
"offset":0,
"limit":20,
}
"payload":
{
}
}

In the example query to get commands for a specific device by name, the device name would be in the topic, so the query message would be without information.
In the example query to get commands for a specific device by name, the device name would be in the topic, so the query message would be without information (and removed from the message as queryParams will be optional).

{
"Correlation-ID": "14a42ea6-c394-41c3-8bcd-a29b9f5e6835",
"apiVersion": "v2",
"requestId": "e6e8a2f4-eb14-4649-9e2b-175247911369",
"queryParams": {
}
"payload":
{
}
}

```
Expand Down Expand Up @@ -334,7 +331,7 @@ An example response message is shown below. Again, note that the message `envel

#### 3rd party system topics

The 3rd party system or application must publish command requests messages to its own MQTT topic (**external message bus**) and subscribe to responses from the same. Messages topics should follow a standard such as:
The 3rd party system or application must publish command requests messages to an EdgeX specified MQTT topic (**external message bus**) and subscribe to responses from the same. Messages topics should follow the following pattern:

- Publishing command request topic: `/edgex/command/request/<device-name>/<command-name>/<method>`
- Subscribing command response topic: `/edgex/command/response/#`
Expand All @@ -357,9 +354,6 @@ For queries, the following topics are used:
- Subscribing to 3rd party command query request topics: `edgex/commandquery/request`
- Publishing to 3rd party command query response topic: `edgex/commandquery/response`

!!! Note
Because EdgeX can suggest but not dictate the naming standard for 3rd party MQTT topics, the 3rd party topic names are representative for clarity.

#### device service topics

The device services must subscribe to the EdgeX command request topic (**internal message bus**) and publish response messages to an EdgeX command response topic. The following naming standard will be applied to these topic names:
Expand Down

0 comments on commit 19b473f

Please sign in to comment.