ldproxy

PubSub

specdraftimplproposal

Publish feature changes via a MQTT broker

Scope

This building block publishes messages about feature changes via MQTT brokers.

The building block specifies one or more brokers (option: brokers), the unique publisher identifier in the brokers (option: publisher), and one or more types of publications (option: publications).

Publications

The topic identifiers follow the pattern ogcapi/{publisherId}/{apiId}/collections/{collectionId}/{subPath}, where publisherId is the value of the configuration option publisher, apiId is the identifier of the API and collectionId is the identifier of the collection of the new, changed or deleted feature. subPath depends on the type of publication. Two types of publications are supported.

All publication types support the following configuration options:

  • broker: the identifier of the broker to send publication messages to;
  • mqttQos: the MQTT QoS value for the messages, AT_MOST_ONCE (default), AT_LEAST_ONCE, or EXACTLY_ONCE.
  • retain: flag whether the broker should retain the message (default: `false);
  • timeout: the timeout in seconds (default: 60).

Publication type: Single topic for all feature changes in a collection

For these publications subPath is items. The message is a GeoJSON feature with three additional properties:

  • $id: a UUID for the publication;
  • $pubtime: the timestamp when the publication was created;
  • $operation: One of create, update, or delete.

In case of create or update, the feature includes the id, the geometry and the feature properties. For delete, only the id is included.

See the items publication in the example.

Publication type: One or more topics for changes of a feature property

For these publications subPath must not be items. The subPath can include multiple path elements and a path element can be a parameter in curly brackets.

The parameters configuration option in the publication maps these parameters to feature properties. The values of the properties in the instance are used to construct the topic. This allows to publish, for example, measurements by station, if one of the parameters is a station identifier.

The property configuration option identifies the property whose value is sent in the publication message. This could be, for example, the value of a measurement.

See the {wigos_station_identifier}/{observed_property} publication in the example.

Limitations

This building block is an initial version that was developed during OGC Testbed 19. Additional development and testing is required to ensure the building block supports a sufficient range of use cases.

Currently only MQTT 3.1.1 is supported.

Conformance Classes

OGC is starting to work on a standard that enables publish/subscribe functionality for resources supported by OGC API Standardsopen in new window. The work is in its early stages.

The event-driven API is described using AsyncAPI 2.6open in new window and complements the OpenAPI definition (API requests initiated by clients).

Configuration

Options

NameDefaultDescriptionTypeSince
buildingBlock
Always PUB_SUB.
string
v2.0
enabled
false
Enable the building block?
boolean
v2.0
brokers
{}
A dictionary of MQTT brokers to connect to. The key is an id of the borker. The value is a broker object with the following properties: host (the hostname of the broker), port (the port to use, default is 1883), ssl (whether to use SSL, default is true, if the port is 8883, otherwise false), username and password (optional credentials, if required by the broker).
object
v2.0
publisher
ldproxy
The unique identifier to use when connecting to the broker. Since the value must be unique in the broker, the value should be set explicitly in the configuration.
string
v2.0
publications
{}
object
v2.0

Examples


- buildingBlock: PUB_SUB
  enabled: true
  brokers:
    t19:
      host: t19.ldproxy.net
      port: 8883
  publisher: ${PUBLISHER:-t19.ldproxy.net}
  publications:
    items:
      broker: t19
      mqttQos: AT_MOST_ONCE
    '{wigos_station_identifier}/{observed_property}':
      parameters:
        wigos_station_identifier: wigos_station_identifier
        observed_property: name
      property: value
      broker: t19
      mqttQos: AT_MOST_ONCE
      retain: true
Legal NoticePrivacy Notice