Edge-agent scouting design spec #423
Conversation
|
|
||
| If Scout mode is enabled, the Edge Agent will trigger the scouting method for each supported connection type (OPC UA, MQTT, etc.). Once the list of addresses is received, the Edge Agent will send it to the ACS Config Service to be stored within a new object. | ||
|
|
||
|  |
There was a problem hiding this comment.
This image URL should be relative ./assets/.... Otherwise it breaks when the PR is merged.
|
|
||
| The challenge with this approach is that the addresses must be known in advance, typically provided by manufacturers per device. However, these addresses can be incorrect or vary between devices. | ||
|
|
||
| The goal of this new feature is to develop an MVP to explore whether this manual process can be reversed. Instead of predefining addresses, the Edge Agent would run in scout mode, actively requesting devices to provide their actual list of available addresses. This functionality would need to be implemented for each supported communication protocol, such as OPC UA, MQTT, and others. |
There was a problem hiding this comment.
This is going into the ACS docs as the documentation of the scouting feature, so it should be written as though the feature has been implemented and merged into ACS. 'The scouting feature allows this manual process to be reversed' etc.
| ## Implementation | ||
| ### Translator Class (Changes for Scouting Feature) | ||
| The scouting feature is embedded into the Edge Agent's Translator class. | ||
| - The Translator class checks if the connection configuration includes a scout entry. |
There was a problem hiding this comment.
There is no spec anywhere for this scout property. I know that it's a property of one of the deviceConnections in the Edge Agent config ConfigDB entry, but someone new to ACS reading this document won't know that.
The format of the value of the scout property also needs documenting; there should be a general comment 'the value of this property depends on the driver' and then driver-specific documentation below. If there is a Scout-specific section and a driver-specific section then the Scout parts can be documented in detail here.
| The scouting feature is embedded into the Edge Agent's Translator class. | ||
| - The Translator class checks if the connection configuration includes a scout entry. | ||
| - If the current connection is configured to run in scout mode, the Translator creates an instance of the Scout class for this connection, passing the DeviceConnection instance and scoutConfig as arguments to the constructor: | ||
| `constructor(deviceConnection: DeviceConnection, scoutConfig: any)` |
There was a problem hiding this comment.
Is this scoutConfig the whole of the value of the scout property or only part of it?
|
|
||
| ### Scout Class (New Component) | ||
| - The Scout class receives the DeviceConnection instance and scoutConfig. | ||
| - The Scout class understands the expected configuration format for each type of DeviceConnection and converts it accordingly (e.g., MQTT, OPC UA, etc.). |
There was a problem hiding this comment.
The Scout class should not be performing validation of the driver-specific part of the scout config. This will be impossible with external drivers. If validation of the scout config is needed this should be another (async) method on the Device.
There was a problem hiding this comment.
Just to note: it's important the validation method is async, as for an external driver the Edge Agent code will need to communicate with the driver to perform the validation.
| - The Scout class understands the expected configuration format for each type of DeviceConnection and converts it accordingly (e.g., MQTT, OPC UA, etc.). | ||
| - The `performScouting()` method invokes the relevant method of the DeviceConnection to perform scouting. | ||
| - Once the DeviceConnection completes scouting, `performScouting()` receives a list of discovered addresses. | ||
| - Finally, the method triggers the **scoutComplete** event with the list of discovered addresses. |
There was a problem hiding this comment.
This is not important for MVP, but eventually I think it will be helpful to re-run the scouting every N minutes, or to allow the Device to support continuous scouting with a stream of scoutComplete events. So:
- It might be better to call the event
scoutResults. - It might be easier to have the Device emit the event, and the Scout push the results up to the ConfigDB.
- You definitely want a the
scoutConfigto be in two pieces, one for the Device and one for the Scout class itself.
| - The `scoutAddresses` method for MQTTConnection retrieves the topic and duration from its configuration. | ||
| These parameters define: | ||
| - Topic: The topic to listen to (e.g., #). | ||
| - Duration: The length of time to listen (e.g., 5 minutes). |
There was a problem hiding this comment.
This is the information that is needed in the spec for the scoutConfig for MQTT, but it needs to be precise. For example: is the property called Topic or topic? A JSON schema for the MQTT-specific configuration might be helpful, or just a table Property/Type/Meaning as elsewhere in the ACS docs.
| - Shuts down the MQTT client after scouting is complete. | ||
|
|
||
| ### OPCUAConnection (Changes for Scouting Feature) | ||
| OPCUAConnection implements the `public async scoutAddresses(scoutDetails: ScoutDetails): Promise<string[]>` of its superclass DeviceConnection. |
There was a problem hiding this comment.
Does OPCUA need any configuration for scouting or is there no choice about what to do here?
| ## Architecture | ||
| This feature will extend the existing Edge Agent source code. The ACS Config Service configuration will be updated to specify whether the Edge Agent should run in Scout mode and may include additional connection-specific configurations if needed. | ||
|
|
||
| If Scout mode is enabled, the Edge Agent will trigger the scouting method for each supported connection type (OPC UA, MQTT, etc.). Once the list of addresses is received, the Edge Agent will send it to the ACS Config Service to be stored within a new object. |
There was a problem hiding this comment.
The discovered addresses want to be stored using a new Application called something like Edge scout results against the UUID of the Connection. The Connections should be pre-registered in the ConfigDB by the time you get to this point, and their UUIDs should be in the Edge Agent config so you know what they are, but we haven't got there yet:
- Migrate Connections into the ConfigDB #406 migrates existing connection information out of the Manager database and into the ConfigDB. This handles upgrading existing ACS installations.
- However the existing (v3) Manager hasn't been changed to keep these up to date when new connections are created, because we're getting rid of it.
- The Manager should also be updated to include the UUID for each Connection in the Edge Agent config, but it also doesn't do that yet, for the same reason.
- The new version of the Manager will hopefully do both these things but won't be usable for a while yet.
When you get to the point of implementing this we will need to work out how to move forward. I would allocate the Application UUID now and document it here.
Design spec for edge agent scouting with implementations for MQTT and OPC UA connections.