Plgd hub services use NATS as an EventBus and MongoDB as an EventStore.
ownerID: The owner of the device, calculated as uuid.NewV5(uuid.NamespaceURL, value of JWT ownerClaim).deviceID: The UUID of the device.hrefID: The identifier of a resource, calculated as uuid.NewV5(uuid.NamespaceURL, href), where href is a resource path (e.g. “/oic/d”).leadResourceType: The selected resource type for resource events.leadResourceTypeID: The identifier of the selected resource type, calculated as uuid.NewV5(uuid.NamespaceURL, resourceType), where resourceType is a resource type (e.g. “oic.wk.d”).Each event is compressed by snappy and encoded in protobuf devices event envelope. The event envelope consists of Event.data containing the event and Event.event_type describing the type of the event.
plgd.owners.{ownerID}.devices.{deviceID}.resource-links.{eventType} publishes resource-links events of types resourcelinkspublished, resourcelinksunpublished, and resourcelinkssnapshottaken for device deviceID and ownerID.plgd.owners.{ownerID}.devices.{deviceID}.metadata.{eventType} publishes metadata events of types devicemetadataupdatepending, devicemetadataupdated, and devicemetadatasnapshottaken for device deviceID and ownerID.plgd.owners.{ownerID}.devices.{deviceID}.resources.{hrefID}.{eventType} publishes resource events of types resourcechanged, resourcecreated, resourcecreatepending, resourcedeleted, resourcedeletepending, resourceretrieved, resourceretrievepending, resourcestatesnapshottaken, resourceupdated, and resourceupdatepending for resource hrefID, deviceID, and ownerID.The Lead Resource Type feature in the plgd hub allows for the specification and handling of a primary resource type for resource events. It is disabled by default but can be enabled through configuration settings for both NATS publishers and subscribers.
To enable the Lead Resource Type feature, modify the YAML configuration files of your service:
Publisher Configuration:
leadResourceType:
enabled: {bool value}
regexFilter: {array of REGEX expressions}
filter: {"first", "last", or ""}
useUUID: {bool value}
Subscriber Configuration:
leadResourceType:
enabled: {bool value}
When enabled, the subject is modified based on the selected resource type. If the resource type is not empty, the subject will include the leadrt prefix and the resource type as a string. If useUUID is set to true, the resource type is encoded to a UUID string. The subject format is modified as follows:
With useUUID=false:
plgd.owners.{ownerID}.devices.{deviceID}.resources.{hrefID}.{eventType}.leadrt.{leadResourceType}
With useUUID=true:
plgd.owners.{ownerID}.devices.{deviceID}.resources.{hrefID}.{eventType}.leadrt.{leadResourceTypeID}
When the resource type is empty:
plgd.owners.{ownerID}.devices.{deviceID}.resources.{hrefID}.{eventType}.leadrt
Even when no resource type is selected, the leadrt token is added to the subject, allowing the use of the .> wildcard to subscribe to resource events with no or any lead resource type.
The lead resource type for a given resource is selected based on the following criteria:
Regex Filter:
regexFilter is an array of regex expressions used to match resource types.Filter:
filter is an enumeration of string values (“first”, “last”).regexFilter does not match any resource type, the filter property determines which resource type to use:filter is “first”, the first resource type is used.filter is “last”, the last resource type is used.The algorithm for selecting the lead resource type is as follows:
# Iterate regexFilter first
iterate resource types of given resource
iterate regexFilter expressions
if the expression matches the resource type
use the resource type
# regexFilter was empty or no resource type was matched
if filter equals "first"
use the first resource type
else if filter equals "last"
use the last resource type
else
don't use resource type
The following environmental variables can be used to configure the Lead Resource Type feature for plgd #bundle:
LEAD_RESOURCE_TYPE_ENABLED, LEAD_RESOURCE_TYPE_USE_UUID to boolean valuesLEAD_RESOURCE_TYPE_FILTER to “first”, “last” or ""LEAD_RESOURCE_TYPE_REGEX_FILTER to comma separated list of REGEX expressionsFor example:
LEAD_RESOURCE_TYPE_ENABLED=true
LEAD_RESOURCE_TYPE_FILTER="last"
LEAD_RESOURCE_TYPE_REGEX_FILTER="^oic.*,core.*"
LEAD_RESOURCE_TYPE_USE_UUID=true
docker run -it --rm -e LEAD_RESOURCE_TYPE_ENABLED=true -e LEAD_RESOURCE_TYPE_FILTER="last" -e LEAD_RESOURCE_TYPE_REGEX_FILTER="^oic.*,core.*" -e LEAD_RESOURCE_TYPE_USE_UUID=true --network=host -v `pwd`/.tmp/data:/data ghcr.io/plgd-dev/hub/bundle:latest
Each event is encoded in protobuf event envelope and then compressed by snappy.
plgd.owners.{ownerID}.registrations.{eventType} publishes owner events of types devicesregistered,devicesunregistered for ownerID.For the consumers of events, you can subscribe to:
plgd.owners.> retrieves all events of the hub.plgd.owners.{ownerId}.> retrieves all events of the owner with the ownerId.plgd.owners.*.devices.{deviceId}.> retrieves all events of the device with the deviceId.plgd.owners.*.devices.{deviceId}.resource-links.> retrieves all resource link events of the device with the deviceId.plgd.owners.*.devices.{deviceId}.resource-links.resourcelinkspublished retrieves the resourcelinkspublished event of the device with the deviceId.plgd.owners.*.devices.*.resource-links.> retrieves all resource link events of all devices.plgd.owners.{ownerId}.devices.*.resource-links.> retrieves all resource link events of all devices belonging to the owner with the ownerId.plgd.owners.*.devices.{deviceId}.metadata.> retrieves all metadata events of the device with the deviceId.plgd.owners.*.devices.{deviceId}.metadata.devicemetadataupdated retrieves the devicemetadataupdated event of the device with the deviceId.plgd.owners.*.devices.*.metadata.> retrieves all metadata events of all devices.plgd.owners.{ownerId}.devices.*.metadata.> retrieves all metadata events of all devices belonging to the owner with the ownerId.plgd.owners.*.devices.{deviceId}.resources.> retrieves all resource events of the device with the deviceId.plgd.owners.*.devices.{deviceId}.resources.{hrefId}.> retrieves all events of the resource with the hrefId for the device with the deviceId.If the Lead Resource Type feature is disabled:
plgd.owners.*.devices.{deviceId}.resources.{hrefId}.{eventType} retrieves the eventType events of the resource with the hrefId for the device with the deviceId.plgd.owners.*.devices.{deviceId}.resources.*.{eventType} retrieves the eventType events of all resources for the device with the deviceId.plgd.owners.*.devices.*.resources.*.{eventType} retrieves the eventType events of all resources for all devices.plgd.owners.*.devices.*.resources.{hrefId}.{eventType} retrieves the eventType events of the resource with the hrefId for all devices.plgd.owners.{ownerId}.devices.*.resources.*.{eventType} retrieves the eventType events of all resources for all devices belonging to the owner with the ownerId.plgd.owners.{ownerId}.devices.*.resources.{hrefId}.{eventType} retrieves the eventType events of the resource with the hrefId for all devices belonging to the owner with the ownerId.With the Lead Resource Type feature enabled, the equivalent subjects are modified to:
plgd.owners.*.devices.{deviceId}.resources.{hrefId}.{eventType}.leadrt.{leadResourceType}plgd.owners.*.devices.{deviceId}.resources.*.{eventType}.>plgd.owners.*.devices.*.resources.*.{eventType}.>plgd.owners.*.devices.*.resources.{hrefId}.{eventType}.>plgd.owners.{ownerId}.devices.*.resources.*.{eventType}.>plgd.owners.{ownerId}.devices.*.resources.{hrefId}.{eventType}.>These subscription options provide flexibility for consumers to filter events based on specific criteria, such as device ID, owner ID, and resource ID, and they also support wildcard subscriptions for broader event capture.
plgd makes it simpler to build a successful IoT initiative – to create a proof of concept, evaluate, optimize, and scale.
