Weave Data Management

Now that you understand the main components of Weave, let's take a look at how some of its functionality is handled at a high level.

Almost all functionality in the Nest ecosystem for everyday operation is mapped onto resources and traits as part of the Weave schema. The Data Management profile manages all requests for traits using a publish-subscribe model. These requests are messages specific to the Data Management profile.

In this type of model, a publisher advertises traits (data to watch) and a subscriber reacts to changes in those published traits (data being watched). This function is called real-time trait management.

The Data Management profile is the workhorse of Weave, and is generally referred to as Weave Data Management (WDM).

Requests

Requests are a key element of WDM's real-time trait management. Requests are standard requests for action of a trait, with an expected response. These are different than a trait's commands in that they are not and cannot be defined in schema and are not specific to any trait.

There are three types of standard requests:

  • Notify Standard request that informs a subscriber of the state of a trait property, or of a specific event related to that trait.
  • Update Standard request to change the state of a trait property.
  • View Standard request to view the properties of a trait.

Protocol roles

There are two types of WDM protocol roles: publisher and subscriber. These roles are assigned at the trait level.

Publisher

The WDM publisher role produces and serves versioned instances of one or more schemas to one or more subscribers, and sends notifications on a change to the schema to interested subscribers. These notifications are the notify standard requests.

For example, suppose Trait A is published by Resource 1 and subscribed to by Resource 2. As shown in Figure 1, if Trait A changes:

  1. WDM sends a notify request from Resource 1 to all subscribers of Trait A, informing them of the change.
  2. Each subscriber updates their instance of Trait A accordingly.
WDM Publisher notify request
Figure 1 - WDM publisher requests

The same thing happens for other traits in the schema. For example, if Resource 2 publishes Trait B, Resource 1 subscribes to Trait B, and Trait B changes:

  1. WDM sends a notify request from Resource 2 to all subscribers of Trait B, informing them of the change.
  2. Each subscriber updates their instance of Trait B accordingly.

Subscriber

The WDM subscriber role views and consumes versioned instances of one or more externally-published schemas. It can change the versioned instance of a published schema with an update request, or issue an application-specific command.

For example, suppose Resource 2 wants to change Trait A, which is published by Resource 1. As shown in Figure 2, to change Trait A:

  1. WDM sends an update request from Resource 2 to Resource 1, to request a change to Trait A.
  2. Trait A on Resource 1 is changed.
  3. WDM sends a notify request from Resource 1 to all subscribers of Trait A, informing them of the change.
  4. Each subscriber updates their instance of Trait A accordingly.
WDM Subscriber view and update
Figure 2 - WDM subscriber requests

Subscribers may also send a view request to a trait's publisher, to view the properties of that trait and keep their own instances of the traits in sync with the publisher.

Subscription types

There are two types of WDM subscriptions. Subscriptions are established with a subscribe request. Figure 3 illustrates the basic message flow to establish a one-way subscription.

WDM one-way subscription
Figure 3 - WDM one-way subscription

One-way

One-way subscriptions involve a request from a subscriber to a publisher for one or more trait instances. For example, a mobile device retrieving the state of the home (structure) from a service.

Mutual

Mutual subscriptions are when resources subscribe to each other, and each act as both publisher and subscriber. An example of this is the Nest Guard and Nest Detect, which are part of the Nest Secure system. A mutual subscription allows both resources to manage the published schema and maintain the health and liveness of their subscription in a more efficient manner than two one-way subscriptions.

Example

Let's look at a simple example of how WDM handles a change to a device's locale using a mobile app.

There are three resources and two traits involved in this example, as shown in Figure 4:

  • Device (subscriber)
  • Service (publisher)
  • Mobile App (subscriber)
  • Locale Capabilities trait Available Locales property
  • Locale Settings trait Active Locale property

Both traits are published by the Service resource and subscribed to by the Device and Mobile App resources. Each subscriber functions as a one-way subscription to the trait publishers on the Service resource.

All resources in this example are part of the same Weave fabric .

WDM example
Figure 4 - WDM example

Update flow

Let's say the user uses their Mobile App to change the locale for the Device from en_US to fr_FR, using a connected Mobile App. As shown in Figure 5, the update flow within WDM is:

  1. The Mobile App resource (subscriber) sends an update request to the Service resource (publisher) to change the Active Locale property of the Locale Settings trait to fr_FR, one of the valid values of the Available Locales property of the Locale Capabilities trait.
  2. The Service resource changes the Active Locale property of the Locale Settings trait in its copy of the schema.
  3. The Service resource sends a notify request about the change to any subscribers of the Locale Settings trait.
  4. The Device and Mobile App resources (subscribers) both receive the Service resource's notify request and update the Active Locale property of the Locale Settings trait in their copies of the schema.
WDM update flow sequence
Figure 5 - WDM update flow

The benefits of WDM

This may seem very complicated when all you want to do is change the locale on your device from a mobile app. But by wrapping the versioned schema, publish-subscribe pattern, and requests together into the WDM profile, Weave ensures data integrity across all resources.

It also ensures liveness, so when a device is restarted, it immediately notifies all subscribers of the state of its published traits, observes the state of subscribed traits, and reflects all those states in its copy of the schema without loss of functionality.

Beyond subscriptions

If a resource unsubscribes from a trait, it retains a copy of the last-known version of the trait. It no longer receives notify requests from the publisher for that trait, but can still send update requests to that publisher.

Even resources that were never subscribed to a trait publisher can send requests to them. For example, a resource may not need to know about the state of a trait, but may want to send update requests to change the state of that trait in response to an external event.

Recap

What you learned:

  • Weave Data Management (WDM) is the Weave profile for real-time trait management and ensures liveness and data integrity across all resources
  • Requests are standard requests for action of a trait, with an expected response
  • WDM features two protocol roles:
    • Publisher — The source of truth for a particular trait, sends notify requests
    • Subscriber — Observes the published schema, sends view , update , or command requests
  • WDM features two subscription models:
    • One-way — Requests flow from subscriber to publisher
    • Mutual — Devices subscribe to each other
  • Subscriptions are established by subscribe requests
  • Resources can send WDM messages to traits even if they aren't subscribed to them

For more in-depth information, see:

Previous
Schema