PubSub

Applications communicate with each other through publish/subscribe (PubSub), an asynchronous messaging service that decouples services that produces messages from the services processing them.

An application can publish serializable data on a topic which is then sent to all subscribers. Applications can also subscribe to a topic to receive all the publications on this topic.

PubSub can be used internally on devices through the PubSub library and externally using the PubSub GRPC API.

Concepts

  • topic: A named resource which is used when messages are published.

    • Device topic: A topic that enables intra-communication on the device. These topics will be prefixed with: device:

    • Cloud topic: A topic that enables inter-communication between devices and external systems. These topics will be prefixed with: cloud:

  • subscription: an identifier of a stream of messages from a specific topic. Note that it is possible to do concurrent reads on one subscription. When doing so, the concurrent reads will receive different batches of the same data set, making it easier to make ingestion concurrent.

  • message: the combination of the data from the publisher and an identification of the sender.

See some examples of PubSub communication between apps in the Tutorials section.

Cloud based PubSub subscriptions

Go to the Data section in the Toit console, choose the PubSub tab, and click the Create Subscription button. Provide a name to the topic, which is prefixed with cloud: as in cloud:topic-name. You can provide a name to the subscription, in order to give a description of the topic or in which scenario it is used.

Once you have created a PubSub subscription, you can view the number of unacknowledged messages for that subscription, as well as the age of the oldest unacknowledged message for a specific time interval in two graphs, by clicking the subscription.

Delete a subscription with the bin icon.

Use the CLI commands to acknowledge messages for a subscription.

Additional PubSub features

PubSub messages can be sent from the cloud to one specific device only by providing the device-id in the command:

toit pubsub write cloud:<topic-name>?device-id=<id> <name> -- <write a message>

It is also possible to create server-side PubSub subscriptions across multiple topics as long as they share a common prefix.

For example, create a subscription for the topics cloud:foo/bar and cloud:foo/baz with

toit pubsub subscription create "cloud:foo/*" subscription-name