In addition to Agents, a project can contain Reusable Node Group files. This not only cuts down on duplicate node structures, but more importantly makes your programs easier to read and understand.

View discussion page on forum

Node Groups are a feature in Embrio that both helps you to reuse pieces of your program, as well as keep your program cleaner and easier to maintain.

Consider this small agent that encapsulates a button, as discussed in the button example project. It reads the activation from a digital input pin, then uses an Above Or Below node to capture a trigger event when the pin goes from low to high, then uses a Timer node to add a cool down period to limit how fast the button can fire.

There are two things about this that can be improved. First, for every button in the project, we’ll need a copy of both of these nodes. This isn’t so bad for something simple like this with only two nodes, but if this process had several nodes it would be very unideal to have to have multiple copies of the same group of nodes.

The other issue is readability. The intention of this group of nodes is not readily apparent. The “started” output on the timer represents a trigger that fires when the button is pressed, which is based on the input Activation on the Above Or Below node. And the Duration input on the timer acts as a cool down period. The rest of the inputs and outputs on these nodes are not really related to this and only clutter up the screen making it difficult to understand.

A Node Group is another kind of node screen that lets you define a group of nodes once, then use that group multiple times in your project. Select the Above or Below and Timer nodes and copy them. In the project tree, right click and select “New Node Group”. A new file is created and a blank node screen opens up. First I’ll rename the group to make its purpose clear, I’ll call this one “button trigger with cooldown”. Next I’ll paste the copied nodes into the node screen.

Next I want to make the needed inputs and output external, so that when this group is exposed by a single node, the relevant inputs and outputs are accessible. Do this by clicking on the icon that looks like a plug. When you click this button, the input or output is given a red outline, indicating that other node screens can connect to it.

The inputs to this group are the activation on the Above or Below node, and the Duration on the timer. You also want to rename inputs and outputs so that their meaning is clear. I’ll leave the Activation input alone, but I’ll rename Duration to Cooldown. The only output that this group will expose is the Started trigger on the timer, which fires when the input activation goes above the threshold, and the timer is not already running. I’ll rename this output “Clicked” to better describe what it means, and make it externally available.

On the bottom right of the node screen you’re used to seeing a refresh rate drop down. Node groups are different than agents though. While each agent only exists once in the project and is always running, a node group can exist multiple times in a project, and they will refresh at whatever rate is set on the Agent that they are added to. Instead there are a save and cancel button. The exposed nodes don’t update in real time while you work, if they did connection could get messed up. For example say a node group has an exposed input called “Activation” and you have copies of that node group in your project connected to other nodes. But imagine you want to change which input on the node group is exposed as the Activation. You can unexposed the current activation, and expose a new one, and then when you save the node group, the connections will connect to the newly exposed input instead of the connections being severed when you first unexposed the existing input. When you are done making changes to a node group, click on the save button and all of the copies of this group will update.

Now that the node group is defined, I’ll add a copy of it to the original agent. Do this by simply dragging the node group from the project tree onto the node screen editor. Now there is a nice logical encapsulation of the original nodes. There’s a name on the node that describes what it does and the inputs and outputs are named appropriately. I’ll delete the original nodes, connect the controller input activation to the new node’s input activation, and set the cool-down period. Even by replacing just two nodes I’ve made my program much easier to understand at a glance. You can have as many instances of a node group as you need, each one contains its own copy of all of the nodes in the group.

I’ll go back to the node group editor to say a few last words about node groups and contrast them to Agents. First, node groups cannot contain input or output nodes. Connecting to a pin on your Arduino must be done on an Agent. If input and output nodes were allowed on Node Groups, then every instance of a node group would have a connection to the same pin, which would be problematic. Also, because when you add a node group to a node screen, it makes a copy of all of the nodes in that group, you can’t add a group to another node group that would cause an infinite loop. For example you can’t add a node group to its self.

So to sum up, node groups are a great tool for both reusing common structures of nodes in a project, and just as importantly they make a program easier to understand by making the intention of a piece of your program clearer to a human reader.

View discussion page on forum