Directory
The Directory component is designed to help applications, users, and other components find the devices and services they require. By monitoring Sparkplug birth and death messages, it keeps a comprehensive registry of devices and services, including their current status, schemas, and endpoints, making it easier for consuming applications to locate them. Instructions on how consuming applications should locate and connect to the Directory is outlined in the examples section.
ACS Directory Component
Overview
As described in the Factory+ Schemas specification, every device participating in the Factory+ architecture, including those nested within a physical device, is assigned a persistent Instance_UUID for identification purposes. This UUID is positioned alongside the Schema_UUID at all birth certificate levels, allowing devices to establish their identity and the schemas that they are conforming to. The Directory component monitors the namespace for birth certificates issued by devices and uses this information to track schema usage and the current Sparkplug topic (group, node, device) on which devices are publishing, allowing clients to locate specific devices or devices conforming to specific schemas. By maintaining the link between Instance_UUIDs and Sparkplug topics, devices can be physically moved, altering their Sparkplug address, whilst preserving their identity throughout the architecture.
Devices lacking an Instance_UUID in their birth certificate will be unable to publish their own UUID. In such cases, the Directory will allocate a UUID to the device and associate it with the Sparkplug address. Subsequent usage of the same Sparkplug address will result in the assignment of the same UUID. However, providing a Factory+ compliant birth certificate with an Instance_UUID will override this behaviour.
MQTT Interface
The Directory component Sparkplug interface MUST use the well-known address [ORGANISATION]-Service-DIR-Directory/Directory, where [ORGANISATION]-Service-DIR-Directory/Directory is the group name and Directory is the node name. This allows the Directory to be located over MQTT without using the HTTP API.
To conform with the Component Specification, the Directory component MUST publish the following metrics:
| Metric | Type | Description |
|---|---|---|
Schema_UUID | UUID | Identifies this as a service provider |
Instance_UUID | UUID | The UUID of this device |
Service_UUID | UUID | The well-known UUID of the directory service function |
Service_URL | string | The URL of the HTTP API |
Last_Changed | folder | A folder of change-notify metrics, containing metrics which are published to every time something relevant changes on the network. By subscribing to the Directory and watching the values of these metrics applications can avoid polling the HTTP API. |
Device_UUID | UUID | Published when a device has come online or gone offline |
Device_Address | string | Published when a device has come online or gone offline |
Schema_Usage | UUID | Published when the list of devices advertising a schema has changed |
Service | UUID | Published when the list of devices advertising a service has changed |
HTTP Interface
Except for the /ping endpoint, all endpoints for the Directory component are located under the /v1 path to allow for forwards compatibility. All endpoints are GET-only and all responses are JSON.
Authentication
All requests must supply HTTP authentication; the following mechanisms are supported:
| Mechanism | Authentication info required |
|---|---|
| Negotiate | A Kerberos GSSAPI token. |
| Basic | Username and password for a password-based Kerberos principal. |
| Bearer | A token from the /token endpoint. |
Specification
Well-Known UUIDs
These well-known UUIDs are part of the core framework and all MUST to be registered with the Configuration Store component under the appropriate classes.
Identity
Permission Groups
This group must be created in the Authorisation Component containing the permission UUIDs listed below.
Permissions
This grants permission for a given account to advertise the given service.
This grants the principal account (normally an administrator account, or an operator account performing this specific function) permission to advertise services for the target, which also represents an account. This allows use of the /v1/service/{service}/advertisment/{owner} endpoint.
In addition to the principal account having this permission on the target account, either
- The
targetaccount must haveAdvertise Service, or - The
principalaccount must haveOverride Service Advertisment Permissions
on the service function UUID being advertised.
This grants an account permission to advertise services on behalf of another account that the other account cannot advertise on its own behalf. The target of the permission is the service function UUID being advertised.
Metric Schemas
If a Sparkplug device includes this schema in its Birth Certificate, the Directory will recognise it as a service advertisement and publish the supplied URL over HTTP.
Examples
Listing All Devices
A list of all known devices can be obtained by making a GET request to /v1/device, which returns an array of device UUIDs.
Finding a Device via its Instance_UUID
If the Instance_UUID of a device is known then it can be queried with a /v1/device/{Instance_UUID} request to the Directory. This returns a JSON
object with the following properties:
| Property | Description |
|---|---|
uuid | The device's top-level Instance_UUID |
group_id | The Sparkplug Group ID this device last used |
node_id | The Sparkplug Edge Node ID this device last used |
device_id | The Sparkplug Device ID this device last used |
online | A boolean indicating if this device is currently online |
last_change | The time this device last went on or offline |
schemas | An array of the schemas supported by this device |
top_schema | The top-level schema this device advertises |
If the device_id property is missing or is an empty string then the device is a Sparkplug Node device that uses NBIRTH, NDATA, NDEATH topics. Otherwise it is a Sparkplug Device and uses DBIRTH, DDATA, DDEATH topics. A particular device may change from being to a Node to a Device or vice versa, depending on operational changes.
The schemas reported are those present in the device's most recent birth certificate. If the device does not publish a Schema_UUID at the top of its metric tree, then top_schema will be reported as null.
Finding a Device via its Sparkplug Address
If the Sparkplug address of a device is known (group_id, node_id, device_id) then it can be queried with request to the Directory as outlined below.
GET /v1/address/{group_id}/{node_id}
GET /v1/address/{group_id}/{node_id}/{device_id}
This returns a JSON object with the following properties:
| Property | Description |
|---|---|
address | The address queries, as a single string |
uuid | The UUID of the most recent device to use this address |
children | An array of the Devices seen under this node |
The children array is only present for a request containing no devices (/v1/address/{group_id}/{node_id}) and contains the device_id for every device ever seen under that Node.
Finding Devices that use a Schema
A GET request can be made to the /v1/schema endpoint that returns a JSON array listing all the Schema_UUIDs the Directory has ever seen.
Given a particular Schema_UUID, a GET request to /v1/schema/{Schema_UUID}/devices returns a JSON array listing the Device_UUIDs of all devices that reported that schema in their most recent birth certificate.
Discovering Services
A GET request to /v1/service returns a JSON array listing all Service_UUIDs that Directory knows about.
Once a Service_UUID is obtained, a GET request to /v1/service/{Service_UUID} returns a JSON array of objects, one for each device providing the given service. Each object has the following properties:
| Property | Description |
|---|---|
service | The service UUID queried |
device | The device UUID of a device providing this service |
url | A URL on which the device provides additional service |
Known Issues
- In the absence of a reliability mechanism (specifically, no STATE support), the directory service's view of the network begins to deviate from the actual state when it becomes unavailable. This can lead to significant repercussions, particularly in the case of missed death certificates which cannot be identified and will only be rectified upon the eventual reconnection of the affected device.
- If bad data is received via Sparkplug it will be recorded and returned. In the event of two devices simultaneously publishing on the same Sparkplug address, the data returned from the directory will be highly ambiguous.