Version 2.10 (2017-02-08)

Features

New implementation for the Thing Event API now includes publishing

The Thing Event API provides real time data to and from the MQTT broker, to and from users with appropriate permissions. This is the mechanism that allows e.g. “live” resource updates in dashboards (subscribing) and enables setting of resources from the Cloud API or App Board (publishing). In release 2.10, the underlying components for the publishing functionality and API have been replaced to improve efficiency and reliability.

Authenticated API clients now have a way of interacting directly with Things, i.e. subscribing or publishing to Thing topics, that are aware of the domain of the logged in user.

Clients of a specific Thing can subscribe to a topic of the form sub/domainPath/thingName, e.g. sub/domain1/domain2/my-thing, to receive new events as they occur in real time.

When a client wants to publish to the Thing is does so on a similar structure as the subscription topic, but the prefix will be pub instead, i.e. pub/domainPath/thingName. The Cloud API will only route messages published on this topic to the Thing if three criteria are met:

  1. The payload is a state desired document: {"state": {"desired" : { ... }}}
  2. The topic domain path exists in the domain tree
  3. The domain of the Thing matches the domain path

The old implementation of Thing Event API with socket.io is considered deprecated and will be discontinued in coming releases (preliminary from version 2.13).

Topic Policies

The pub and sub topics are backed up by topic policies that reflect the domain structure of the domain tree and give privilege to interact with the topics. The domain path topic can have a maximum of 7 slashes (/). On login the correct topic policy is attached to the user.

The pub and sub topics together with the topic policies makes sure that only a user with the right privilege can access a topic and thus interact with the Thing.

Minor improvements and corrections

Numerous minor enhancements and bug fixes are delivered by the new release, including:

  • Increased expiry time to 1 week for links sent via email when the user is created by an administrator.
  • Enabled configuration of email texts sent by user management (sign up, recover password, etc) – these text can be configured by Telenor per instance.
  • Fixed issue with browser caching resulting in users sometimes having problems logging in.
  • Now validating so Domain ID only contains characters [a-zA-Z0-9_.,@/:#-]. The Domain Name can contain other characters too.
  • Changes in domain tree structure. We now allow maximum 8 levels in the domain tree (root + 7 sub domains). Only 7 slashes (/) are allowed for the domain path in a MQTT topic, causing this limitation. In the domain path topic we now make “root” implicit: what used to be e.g. events/root/a/b/c/ now becomes events/a/b/c/. This allows for a domain tree of root + 7 sub domains.