Stack Environment Properties
When a blueprint is used in multiple Stacks, it is often useful to have a number of stack customization properties whose values can be easily edited and used in the blueprint.You will see a new entry in the “Projects” palette called “Unnamed Project”. To rename it, click in the text area and edit the name. To open the new project, double click in the rectangular box containing its name. You are now free to compose your blueprint.
Using properties in Stackbuilder
Every Blueprint in Stackbuilder provides a Property mechanism to configure and control the behavior of that Blueprint. In a modular, hierarchical building blocks architecture as seen in Stackbuilder, these Property namespaces of individual Blueprint blocks can be organized in a flexible way to allow the parent namespace to affect the underlying child blocks when the child block’s Properties are “exposed” up to the parent.
Recall that each row in the Property table of a blueprint has three columns, where the third column exposes (and renames if different) the property name (first column) to its parent. The property editor is always present in the bottom right of Stackbuilder. Selecting the background of the blueprint or an individual block, causes the property editor to display its contents for the selection.
Ultimately, this hierarchical Property namespace tops out at the Stack level as the Stack Environment for each individual Stack, wherein the specified properties and their values are global to that entire Stack. To access the Stack Environment of any given stack, connect the stack via USB to Stackbuilder and click on the “Stack Info” tab at the bottom of the screen.
On the tab view for “Stack Info”, with the Base selected( default) on the left panel, the right panel has a table labeled “Properties of Stack Environment” that provides a way to add, edit and remove properties and their values similar to that of the Properties section on the bottom right for Blueprints.
Why use the Stack Environment?
Other than the already mentioned value of a “global” property space to be used by underlying blocks for ease of use, the Stack Environment provides three important management functions.
Independent data store of sensitive information
Rather than revealing sensitive information such as account names, passwords, cloud credential information and other protected data directly in the code (which is highly discouraged) Or as properties of Blocks (say the WiFi block’s network router SSID and password), such information should be made available in the Stack Environment. This approach allows for building Blueprints that are “pure” code that is easily transportable across multiple stacks doing the same or similar function and avoids the security aspects of leaking user credentials when the blueprints are shared with non-vetted users.
Device management information
When deploying multiple stacks that are functionally the same save for certain identifying attributes such as device id, tag name(s), device location and other identifiers that match up with their digital twins in the cloud, Stack Environment provides the mechanism to keep the functional Blueprints generic and common to all the stacks and to apply the device specific information for each stack via the Stack Environment. This reduces the developer’s need to manage multiple Blueprints, one for each stack, thereby improving usability and reducing potential conflicts.
In-field property update
It’s likely that some properties of the Stack may not be available at the time of creating the Blueprints for the stack and even if so, there may be a need to update them at a later point in time. For example, the Wifi SSID and password will need to be updated when either the router information is changed or if the stack is moved to a different location with different router access information. In such cases, updating the Stack Environment properties at run time is vastly more convenient than updating the Blueprints with the new information
Sample use case
In this Project Blueprint “Stack Environment Example” we have an I/O module sending two sensor data values to the cloud via HTTP API using Wifi.
In this Blueprint, instead of setting the WiFi Block’s ‘network_name’ and ‘password’ property directly on the block, let’s expose (and rename) them to be made available to the parent.
Clicking on the Wifi Block to display its properties in the properties area on the bottom right and update as shown above so that:
- ‘network_name’ is exposed as “network.name”
- “password” is exposed as “network.password”
As shown below, there are no default values set here, therefore the Blueprint does not contain sensitive information.
To make these two properties of the WiFi Block inherit from the Stack Environment, they need to be exposed on all intermediate parent blocks. In this example, that would include the Project Blueprint “Stack Environment Example” [Note: At each level, the parent’s property space includes the exposed properties of ALL of its child blocks].
We can follow the same procedure to expose the two properties (with the same name mapping this time) for the Project Blueprint such that “network.name” is exposed as “network.name” [ no default value] “network.password” is exposed as “network.password” [ no default value].
Note to Advanced Users: There is a handy shortcut for exposing ALL the properties of a given block up one level, which is done by defining the “*…” property and exposing it as “*…”. Although convenient, one should use caution in using this in situations where properties of other blocks which also share the same property namespace can cause unintended consequences to the underlying blocks making use of this shortcut.
Here’s an example of this shortcut being used on the Project Blueprint.
At this point, the Wifi block’s two properties are exposed all the way to the top of the stack. To set their values in the Stack Environment, connect the stack via USB, click on Stack Info, and fill out the two properties with the values to be used by this specific stack as shown below.
Once done, clicking on the “send to stack” button will load the “pure” blueprint and the specific Stack Environment of this stack to the connected stack. If you were to connect a different stack and then click on the Stack Info tab, the Stack Environment for this new stack will be different (or empty if never set before) from the one we just set even if we were to re-use the same blueprint on the second stack.
To extend the example, let’s say we want to include device specific information as part of the HTTP data sent to the cloud. The “Send device sensor data to the cloud” block has a property named “device.id” which identifies a particular device, say by a unique string. If we were to deploy the same Blueprint on multiple stacks, it is obvious that we should not be setting this value directly on this block and should instead be using the Stack Environment for managing the device identity. Following the similar steps as the Wifi Block, we can expose the “device.id” property on the “Send device sensor data to the cloud” block and the parent Project Blueprint and finally update the Stack Environment of the connected stack to include the specific device id as shown below.
The above example demonstrates the use of the Stack Environment to deal with device specific information, and to secure sensitive data from being exposed in general purpose blueprints.