2.5. Information Management through Publish/Subscribe (Push Model)

The Push Model describes a publish and subscribe model that enables an information provider to initiate the supply of information when the information is available (publish) to an information consumer who is interested in this information (subscribe).

This methodology enables an asynchronous management of the information on the client application side. Client applications often use an asynchronous architecture to manage their user interface and this methodology enables an asynchronous management of the information as well where they react to a new state of an entity instead of having to periodically check if the state has changed or not.

The following diagram provides a quick overview of the Push Model ecosystem

2.5.1. Definitions

Common definitions

Object model definitions

2.5.1.1. Asynchronous Communication

Asynchronous Architecture

A type of architecture that decouples and removes any dependencies between the information provider to the information consumer, in which the information can be provided and consumed at different times.

The soap dispenser manufacturer provided the latest filling level asynchronously as soon as available. The janitor accessed the information later when starting the afternoon shift

Publish

The action to provide the information to authorized consumers without waiting or expecting for an acknowledgement

The trash bin manufacturer published an alert when the bin was full

Subscribe

The action to access and process the information that was previously published

The supervisor subscribed to be notified when a bin was full

2.5.2. Supported technologies

FDS tries to decouple the specifications from the implementation technology to the extent possible. In the case of publish/subscribe infrastructure, there are a significant number of implementation technologies proposed compared to the pull model where everybody uses the Web API model.

FDS will document how the specifications apply to the two prevailing technologies used by industries managing IoT devices:

• MQTT (Message Queuing Telemetry Transport)

  • An overview of MQTT can be found at https://mqtt.org/

• Webhooks (Web Posts)

  • Webhooks use the Web API technology (HTTP requests) to push the information to the client application and requires the client application to implement a web server and support POST requests. An overview of Webhooks can be found at

    • Working with Webhooks

    • What are Webhooks? Easy Explanation & Tutorial

MQTT is based on a broker that dispatches between the sender (information provider) and the rightful receiver (information consumer/client application). In the FDS context, the broker can be implemented in different places in the ecosystem:

• The Broker can be implemented on the information consumer infrastructure

• The Broker can be implemented on the information provider infrastructure

Implementing the FDS push model specifications requires the parties involved in a business relationship to agree on the underlying technology. Because multiple parties are involved in a typical facility environment (a consumer of information get information from multiple entity providers), and information providers operate in several facility environments (supply information to multiple information consumers), this can lead to complex implementation environments, especially if one of the information consumers or providers does not support one of the technologies.

The following table defines a decision matrix in which case the implementation of the FDS push model specifications is possible.

Note

It is expected that the implementation complexity of a push model will lead the industry to converge toward one broadly accepted technology. When that happens, FDS will update the specifications to require this accepted technology, whatever it is.

Setting up and initializing the communication protocol between parties will require human interaction to decide and configure the system and is currently out-of-scope of the FDS specifications.

Note

FDS will work on handshake and infrastructure metadata information exchange specifications in a future version to simplify and streamline the communication setup between consumers and providers of information.

2.5.3. FDS compliance requirements

This section provides the FDS compliance requirements when implementing a publish/subscribe model.

To be agnostic to the underlying technology, the term ‘destination’ is used to define where to publish and subscribe for the information.

• Destination is referred as “topic” in the MQTT world

• Destination is referred as “endpoint” in the Webhooks world

2.5.3.1. Where to publish and subscribe

• The information provider must publish information about single known entities per destination

• The information consumer must subscribe to the same destination in order to receive information about an already known entity

• The destination format must comply to:

fds/v2/<subscriber_id>/<tag_id>/<entity_type>/<entity_id>/<message_category>/<message_code>

• The destination must identify the resource owner through the subscriber ID provided by the information provider

• The destination must contain a tag that identifies a grouping of entities that the information provider will publish information about.

  • The information provider must only publish information about devices that are associated to a tag

• The destination must contain the type of the entity (device type or space type)

• The destination must contain the ID of the entity (device ID or space ID)

• The destination must contain a message category

  • The message category must be one of

    • “status” when publishing information about a new state of the entity

    • “diagnostic” when publishing a new prognostic about an entity

    • “alert” when publishing an alert event

    • “notification” when publishing a notification event

• The destination must contain a message code

  • The possible message codes are defined at the entity type and event level

• A special destination must be defined to publish special announcements such as when new devices are available to a resource owner

• The announcement destination format must comply to:

fds/v2/<subscriber_id>/announcement/<anmouncement_type>

• The announcement type must be “new_devices”

2.5.3.2. What to publish

• The payload for information about a single known entity must be a message object

• The payload for a new device announcement must be a specifications object

  • The specifications object must only contain the data property

  • The data array must contain specifications for a least one device

2.5.3.3. When to publish and subscribe

• The client application must know the ID of an entity prior to subscribing for information about this entity

• An entity must be associated to a tag before the information provider publishes information about the entity

• The client application must inform the information provider when it can start publishing information about an entity

  • The publish_flag property in the tag object must be set to true

2.5.4. Workflow

This section provides a guideline and recommendations to implement the push model for the prevailing MQTT and Webhooks technologies.

2.5.4.1. MQTT Workflow

2.5.4.1.1. Initialization

As previously mentioned, a human-to-human negotiation between the information consumer and all the information providers must take place first to agree on where the MQTT Broker is located and how to access it. In all cases, the Broker administrator needs to provide to both the client application and the information provider

• The hostname of the Broker

• a Client ID that uniquely identifies who connects to the broker (either as a publisher or subscriber)

• A X.509 certificate for authentication (see the Security chapter)

Besides the Broker-related information, the information provider must also provide the subscription ID for the resource owner. This information is critical in order to subscribe to a destination (topic in this case)

The next step is for each of the broker clients to connect to the broker.

Then, the information consumer must inform each information provider for which entities it will subscribe to get information from

• It is assumed that the client application already knows the ID of the entities

• The client application defines one or multiple tags, assigns the entities to them

• When ready to subscribe for information, the client application supplies the tag(s) information to the information provider with the publish_flag property set to true

Finally

• The client application subscribes to all destinations (topics) of interest

• When information becomes available for an entity associated with a tag, the information provider publishes the information on the specific destination

The following diagram provides the description of this recommended sequence

2.5.4.1.2. New Devices available

The client application can get the specifications of new devices acquired by the resource owner through the push model using the special announcement destination.

Anytime after the connection to the Broker is established, the client application subscribes to the announcement destination (topic).

When the information provider has setup one or multiple devices for the resource owner (represented by the subscription ID), it publishes the specifications object to the announcement topic.

The client application stores the devices specifications locally and assigns them to the appropriate tag(s). Note that this workflow assumes that the devices are associated to existing tag(s) for simplicity, but nothing would prevent the client application to create new tags at this point.

• The client application updates the tag on the information provider’s side so it can publish information for this device

The following diagram provides the description of this recommended workflow to manage new devices

2.5.4.2. Webhooks workflow

2.5.4.2.1. Initialization

In the Webhooks model, the client application implements a web server that exposes the destination endpoints. How this web server is implemented and when it is available to the information provider is out of scope of this workflow and it is assumed it is accessible.

It is also assumed that the information how to access the Webhooks has been supplied from the information consumer to the information provider.

The information provider must also provide the subscription ID for the resource owner. This information is critical in order to subscribe to a destination (endpoint in this case).

The information consumer must inform each information provider for which entities it will subscribe to get information from

• It is assumed that the client application already knows the ID of the entities

• The client application defines one or multiple tags, assigns the entities to them

• When ready to subscribe for information, the client application supplies the tag(s) information to the information provider with the publish_flag property set to true

Finally

• When information becomes available for an entity associated with a tag, the information provider publish the information through a POST request to the specific endpoint

The following diagram provides the description of this recommended sequence

2.5.4.2.2. New Devices available

The client application can get the specifications of new devices acquired by the resource owner through the push model by exposing the special announcement destination (endpoint).

When the information provider has setup one or multiple devices for the resource owner (represented by the subscription ID), it publishes the specifications object through a POST request to the announcement endpoint.

The client application stores the devices specifications locally and assigns them to the appropriate tag(s).

• The client application updates the tag on the information provider’s side so it can publish information for this device

The following diagram provides the description of this recommended workflow to manage new devices

2.5.5. Use case example

Note

Join FDS to get access to examples and use cases.