After completing this lesson, you will be able to do the following:
You should have already completed the following lessons:
Pico Engine Quickstart lesson. (Be able to register and install rulesets)
Events and Queries Lesson. (Be able to create channels and understand how events are raised on channels)
Pico-Based Systems Lesson. (Be able to manage the pico lifecycle using UI and programmatically)
Subscriptions play an important role in building systems of picos. In Pico-Based Systems Lesson, you created child picos. If the parent-child relationship were the only one that existed, we could create hierarchies of picos, but not peer-to-peer systems of picos. Subscriptions allow us to establish relationships between any two picos.
A subscription represents a relationship between two picos. It has a name and two channels, one from each pico participating in the subscription to the other. Each side in the subscription can be given a role to further identify the purpose of the subscription.
Wrangler provides functions, actions, and rules for managing subscriptions from within your KRL code.
In this section, we'll use a simple example. Here the owner pico has three child picos, as shown by the familiar black parent-child edges. However, let's say the "Mischief Pico" needs to communicate with the other two picos.
The subscriptions which we will create to enable this pico to pico communication are shown as dashed magenta lines. (This diagram is available at localhost:8080/?subscr )
Very soon, the ability to manage subscriptions will be built-in to every pico. Right now, you will need to install the ruleset with RID "Subscriptions" into the three picos which will participate in subscriptions. This can be done in the Rulesets tab of each pico, by clicking on the "install ruleset" button beside the dropdown when it shows "Subscriptions".
The "Subscriptions" ruleset is automatically registered in the pico engine during start-up, because it exists (in a file named "io.picolabs.subscriptions.krl") in the folder name "krl". However, it is not automatically installed in any pico. Soon, it will be.
Since most of the heavy lifting is done by the Subscriptions ruleset, it is easy to initiate, approve, and use subscriptions inside of your own rulesets.
Prepare for this section by manually creating three child picos of your owner pico.
It is possible to initiate a subscription with a rule running in a pico which already has in its possession the ECI's of the two picos which need to be related by the subscription. Once you have set up the three child picos, Mischief, Thing1, and Thing2, and installed their respective rulesets, study the code and prepare for the introductions.
The owner pico already has all three of the other ECI's in its array of children (maintained by the io.picolabs.pico aka Wrangler ruleset), but it doesn't know which is which. So we added this rule to allow it to distinguish between the Mischief pico (which identifies itself by ECI) and the Thing1 and Thing2 picos.
The ruleset for the Mischief pico sets up a button "mischief/identity" in that pico's Testing tab which will send this event to the owner pico. Navigate to the Testing tab of the Mischief pico and click the button. Doing so will send the event
mischief:who to the owner pico, and that event will trigger the rule shown above. You can check the result of this calculation by looking at the entity variables held by the
mischief.owner ruleset in the Rulesets tab of the Owner Pico.
Once the owner pico has all of the ECI's, the code to introduce the Mischief pico to each of the thing picos is straight-forward.
The ruleset also sets up a button in the owner pico's Testing tab, "mischief/subscriptions" to send the event that causes this rule to evaluate. Navigate to the Testing tab for the Owner Pico to click on this button.
The final step is that a rule selecting on
wrangler/inbound_pending_subscription_added is in each of the thing picos (the ruleset
mischief.thing), and this will complete the subscription process. You can see the results by refreshing the UI and navigating to the Subscriptions tab for any of the picos involved in one of the two subscriptions.
A pico can directly initiate a subscription. The subscription is initiated by a rule installed in the pico
wrangler:subscription event in the postlude block of one of its rules.
As in the case of introductions, the target pico must have a rule selecting on
wrangler/inbound_pending_subscription_added which will complete the subscription process by raising the
Suppose that we wanted the Mischief pico to respond to a
mischief/hat_lifted event and send the same event to all of the thing picos that it controls. Assuming that you have arranged to use Subscriptions as a module in the meta block, as in
a rule like this one would accomplish this:
Notice that the rule evaluates for each of the subscriptions. It only acts for those subscriptions with a
subscriber_role of "thing", and is able to reach that pico through the
outbound_eci which was established when the subscription was accepted.
Very soon, Wrangler will fully integrate subscriptions, so that when you delete a child pico any subscriptions it participates in will also be deleted. In the meantime, you may wish to programmatically delete such subscriptions before requesting the deletion of the child pico.
To delete a subscription, either of the picos which participate in the subscription would
raise the event
wrangler/subscription_cancellation including an attribute named "subscription_name" whose value is the subscription
name_space concatenated with a colon and the subscription
name. For example, if the Thing2 pico wanted to cancel its subscription, it might include this code in the postlude of one of its rules.
The raised event triggers a rule in the
Subscriptions ruleset. This rule takes care of deleting both sides of the subscription.
We showed above how to write KRL code to initiate a subscription. Here, we will create a subscription manually (using a RESTful interface such as the Postman REST client, or
curl, or the browser–in this example we'll use the browser).
Prepare a URL like this one in your browser (the line breaks shown here are for readability–your URL will not contain line breaks):
Your URL will be different because the ECI to which the event is sent (in the example,
cj0dea39q0001khpqy4su0ru3) needs to be replaced by the main ECI of your Mischief Pico, and the
subscriber_eci parameter needs to indicate the ECI of your Thing1 Pico.
A subscription has a
name within a
name_space, and we indicate the role that the picos involved in the subscription will each play (
When you visit this URL, the
wrangler/subscription event will be sent to the Mischief Pico and the subscription will be created. This will result in each of the two picos involved having a subscription. Each of them will also have a new channel, especially created for use with the subscription. Here is the new channel created for the Thing1 pico:
Repeat the process for the Thing2 pico.
If we were now to query the Mischief Pico to see its subscriptions, using a URL like
we would see that it participates in two subscriptions:
Similarly, the Thing1 Pico participates in just one subscription. Doing the same
sky/cloud query to its ECI will show something like this:
There is one step remaining in the subscription process. Just because one pico offers a subscription to another pico doesn't mean that target pico is forced to accept it. This is manifest by the "status" of the subscriptions. For the originating pico, the status is "outbound" (short for outbound, pending), and for the other pico, the status is "inbound" (i.e. inbound, pending).
In fact, after the pending subscriptions were created, the Subscriptions rule for
wrangler/subscription raises the wrangler event "inbound_pending_subscription_added" passing along all of the attributes. It is up to your pico to react by either accepting or rejecting. This cookbook example shows how to write a rule that auto-approves subscriptions.
This shows the event attributes associated with the event
Generally, promiscuously approving pending subscriptions is a security risk, so most auto-approvals take place where something about the subscription requestor can be verified. For example, a child might be programmed to automatically approve subscription requests from its parent, after checking that the invitation came in on a channel that can be verified as being from the parent.
For now, to complete the manual process, we will send this event to the Thing1 pico (line break added for readability–your URL will be all in one line):
Checking the Thing1 pico again, you will see that its one subscription now has the the status of "subscribed". At the same time, that subscription in the Mischief pico also now has the status of "subscribed".
You can cancel a subscription manually by sending an event to either of the picos involved in the subscription, in this example, the Thing1 pico.
This page is inspired by (and often copied verbatim from) the original fourth lesson, (Classic) Lesson: Pico to Pico Subscriptions.