Custom Nodes

Video Transcript

Embrio lets you easily create your own nodes. In fact all of the built in nodes were created right in Embrio. To see the inner workings of a node simply click on the “Toggle Node Editing” icon in the top right of a node.

By default you cannot edit built in node definitions. To change this open the application options tab and check the “Can save built in definitions” box and press the Save button. You will have to close and re-open an open node for the change to take effect.

To create a new node definition, right click on any node toolbar, except for the library, and select New Node Definition. Node definitions added to any of the built in tabs will be available to all of your projects, nodes in the project tab will only be available to the project you are working on. In most cases you will want to add your nodes to the project toolbar. After creating the node definition, rename it by either middle clicking on the node definition or using the right click menu.

To edit the node, drag it onto a node screen editor to create an instance, then open it for editing with the Toggle Node Editing button.

The Add Input and Add Output rows of buttons allow you to add inputs and outputs to the node. You can use the arrows on the side to reorder the inputs and outputs. To delete an input or output click on the red cross out icon next to it. To rename an input or output either middle click or use the right click menu.

The middle section is where you write the code that runs the node. More information about writing code is in another video in this section. The drop down box lets you pick which update condition’s code to edit.

The Declarations section is where you add variables and functions accessible from any code in the node.

Code in the Startup section fires when the node starts running. In a compiled Arduino program this runs when the Arduino first gets powered on. In the Embrio UI this happens when a project is loaded, when a new instance of a node is added to a node screen, or when the definition of a node on a node screen is manually saved.

Code in the Every Update section gets called every time the Agent the node is on gets refreshed, based on the Refresh Rate for that Agent.

The Shutdown section is almost never used. It is not used at all in a compiled Arduino program as the program just stops running when the power is turned off, the Embrio program has no way to know to shut down. The only time this could be used is in a node that will run either in the editor or in a compiled Form application. You could use it to close any connections or free up any resources, but that would be rare.

A node can have multiple On Change events, these fire only when one or more of the inputs configured to the event change value. It is smart to use On Change events as much as possible instead of an Every Update event to save Arduino resources as the code will fire less often. To add an On Change event, click the Plus icon next to the drop down. The new On Change event is added to the drop down and automatically selected. When an On Change event is selected for editing a checkbox is added next to all inputs. Check the box next to all inputs that should cause this block of code to run when their value changes.

On top of the code editor is an icon with 2 red arrows. When this icon is red, it means that the code written needs to be valid C# code to run in the Embrio UI and Forms applications, as well as valid C++ Arduino code to run in a compiled Arduino program. If you need to write different code for the two targets, click on the arrows to deactivate this option and show one tab for C# code and one for Arduino code. If the node will interact with Arduino pins, it should have no C# implementation. In this case click on the “touches physical pin” check box to leave just the Arduino code tab. Most Embrio nodes have the red arrows option on. For an example of a node with only an Arduino implementation, open up the Analog Input node. On Every Update, the Arduino analogRead function is called and the value is transformed to an output Activation. This node will never run in the Embrio UI, to get values from this node you have to start an Arduino connection so that the node can be compiled and uploaded to an Arduino, where it will execute and send data back to your computer for display in the node.

A more complex example of a node with 2 code implementations is the Timer node. In C# timing is done with the System.Diagnostics.Stopwatch class. This class is of course not available to an Arduino program. Instead the Arduino implementation uses the Arduino micros() function. Note that the red arrows icon works for the whole node, not just individual update conditions, so even if some conditions have the same code you need to copy that code to both targets.

The IO Set and Show HTML Canvas check boxes will be covered in their own videos in this section.

By default when you manipulate the values and options of an input while a node is in edit mode, you are changing the values of the instance of the node you are dealing with. If you want to set default values you first need to click on the “Edit I/O Default Values” button to highlight it red. For example if we want to make an Activation input default to a value of 0.5 and a blend mode of multiply, we press the button, change the values, then press the button again. Save the definition, and confirm the change by dragging a new instance of the node definition onto the editor.

To add an icon to the node, right click on the icon in the top right of the node and click Load Icon Image. Pick an image file from your computer to assign that icon to the node.