Monthly Archives: March 2019

Nodel at ACMI Part 3: Nodel System Design

Nodel is an open source digital media control system for museums and galleries, although there are many valid uses for Nodel outside of this scope where device control, monitoring, and scheduling is required.

In response to the pending renewal at the Australia Centre for the Moving Image, the technical services team decided to trial Nodel to assess it’s suitability as the control system for future exhibits and installations. I put my hand up to build a small Nodel implementation example, and write some documentation on the lessons learnt that would help future employees deploy Nodel around the organisation. This documentation will come in the form of four posts; Basic ConceptsImplementing a Simple Nodel SystemNodel System Design, and Coding Tips.

Nodel System Design, is the third of the write ups that will discuss Nodel. This post will describe a methodology on how to approach designing a more complex system, with ACMI’s very own Cleverman Exhibition used as an example use case. It is highly recommended that you read Basic Concepts and Implementing a Simple Nodel System before going ahead and consuming this post.

Before explaining the steps required to design a Nodel System in a methodical way two things should be briefly touched upon as they have not been mentioned, the Scheduler Node, and the ACMI Management Node Recipe.

The Scheduler Node

Figure 1 – Example implementation of a Scheduler Node.

In almost every system things are going to have to be scheduled. Whether it is to preserve equipment lifetime, ensure the correct content is presented, or to save power, some form of scheduling will be required. This is where the Scheduler Node comes into play.

The Scheduler Node can be defined as a Management Node. Using a variety of different techniques it schedules the emitting of Local Events at specific intervals or one off dates. As explained in Basic Concepts: Control With Remote Events, Remote Events within Management Nodes can be triggered by the emission of another nodes Local Event. This Management Node Remote Event can then call a Local Action from the Management Node in a Remote Event handler function. This is how a Scheduler Node can trigger the calling of various Actions within a Management Node.

A variety of Scheduler Node recipes exist within the Museum Victoria’s Nodel Recipe Repository with varying levels of complexity. This includes the scheduler recipe, the advscheduler recipe, and the Microsoft Exchange Schedule Retriever which if implemented correctly can use a Microsoft exchange calendar as a scheduler. The ACMI Scheduler, a derivative of the advscheduler recipe is a particular easy scheduler to implement.

The ACMI Management Node Recipe

Using the techniques described in Basic Concepts and Implementing a Simple Nodel System, the ACMI Management Node Recipe was created. Using Parameters, it features a simple user interface that allows a user to create Local Actions, Local Events, and integrate “Member Nodes” without writing a single line of code. When adding Member Nodes a series of Local Events, Remote Actions, Remote Events and handler functions are automatically created and wired. In addition, triggering the ACMI Management Nodes Local Actions with the emission of another Nodes Local Event is possible using the “Remote Events Triggering” Parameter which is often required when integrating a Scheduler Node in a system.

Animation 1 shows the setup of a Management Node using the ACMI Management Node Recipe to control two of the Device Nodes used in Implementing a Simple Nodel System.

Animation 1 – An example implementation of a Management Node using the ACMI Management Node recipe. Click to Enlarge.

Animation 2 shows the setup of a Scheduler Node using the ACMI Scheduler Recipe to schedule the calling of a Local Action in this Management Node.

Animation 2 – An example implementation of a Scheduler Node using the ACMI Scheduler Node recipe. Click to Enlarge.

The code for these Recipes can be found here. With these two concepts out of the way, we can now move on to Nodel System Design.

Nodel System Design Scope

Designing a Nodel System can be done in a methodical way with a simple scope that will ensure the system remains functional, adaptable, and understandable to a wide range of people. This scope can be defined as the following:

  1. To control, schedule, and monitor a specific use case in the most simple way possible.
  2. To reduce the development time of the control, scheduling, and monitoring system.
  3. To develop a control, scheduling, and monitoring system that can be altered and adapted to changing requirements in a quick and simple manner.
  4. To develop a control, scheduling, and monitoring system that can altered, adapted, maintained, and operated by individuals with differing skill sets (i.e. individuals who are not software engineers).

These goals should always be kept in mind when designing a Nodel system.

Nodel System Design Steps

If it is known Nodel is going to be used for control and monitoring, keep this in mind when deciding which technology is going to be used in the exhibit. Ideally the technology used in each exhibit will have the ability to have a variety of parameters controlled and monitored via a network. With this being said, the following steps are a good guideline:

  1. Develop a naming convention for individual nodes: This might include the type of node, the technology the node uses, the area a node exists in a physical sense, or other identifying features.
  2. Define a control requirements list and accompanying control naming convention: This will include the the control attributes required for various nodes throughout the system.
  3. Develop a Node System Table: This table details all nodes as well as the Node Name as defined by the naming convention, Node Type (management/device), Parent Node Name (if a member of a Management Node), Area Name (location of hardware that is being controlled by the node), Control Attributes which are required by the node, and Technical Notes which should include implementation details and controlled hardware details in the case of Device Nodes.
  4. Develop a Scheduler Node Recipe: This Recipe will most likely be chosen from existing recipes rather than being developed from scratch.
  5. Develop a Management Node Recipe: While a custom Recipe can be developed, the ACMI Management Node recipe should be able to do everything a Management Node needs to do.
  6. Develop the required Device Node Recipes: These recipes should directly control hardware or software that is external to Nodel. Based on the Device Nodes defined within the Node System Table, it should be clear what Device Node Recipes need to be created. Ideally, this is the only time code development should be required.
  7. Create system using Nodel Interface: All the information required to create the system should be accessible from the Node System Table, making the system creation a relatively straight forward task.
  8. Test system: The system should be tested in the real world to ensure each Node is functioning correctly.

To show how following these steps can result in the quick implementation of a Nodel System in a real world setting, ACMI’s Cleverman exhibition will be used as an example use case for designing a Nodel System.

Nodel System Design For Cleverman

In the case of this example, Cleverman: The Exhibition located in ACMI’s Gallery 2 space had already been installed before designing this Nodel System. Cleverman consists of several exhibits that have multiple pieces of playback and display technology. Due to the small size of the Exhibition these exhibits were not separated in to areas. The main method of playback was through BrightSign players, while a variety of screens were used to display the content. Unfortunately none of these screens were connected to the network, however by toggling the HDMI output the screen automatically powered on and off respectively. Due to this, no screens in the exhibit where treated as Nodes.

The initial control software used for the exhibition was the BrightSign App, which had a variety of control features such as Reboot (reboots the player), audio mute/unmute, display off/on (turns off HDMI output), and pause/resume content playback. Status of the screens and BrightSign players was not available, although through the app it was possible to see if the player was “Online” or “Offline”. When designing the Nodel System it was decided that at a minimum these features should be replicated. You might ask yourself what benefits to be had by using Nodel in this case seeing as most the control is being conducted by BrightSign players. By implementing a Nodel System, it because possible to integrate other pieces of technology to the system in the future.

The following table was available at the time of designing to give an idea of individual pieces of technology being used. Using all the information it is possible to move forward with the design of the Nodel System.

Step 1: Develop a Naming Convention for Individual Nodes

Based on the available information a naming convention was developed that would allow both easy identification and quick identification of a Device Node’s associated technology. For management type nodes, the naming convention would be the following:

<SPACE NAME>_<NODE NAME>

For device type nodes the naming convention would be the following:

<SPACE NAME>_<PARENT NODE NAME>_<ADDITIONAL IDENTIFIER>_<DEVICE NAME>_<CODE>

Step 2: Define a Control Requirements List and Accompanying Control Naming Convention

After consulting with various stakeholders and reviewing the existing control system the following Control Requirements List and accompanying naming convention was developed. This list was heavily influenced by the way each BrightSign player was configured at the time of installation to accept UDP commands as a way of controlling various parameters.

Step 3: Define a Node System Table

With the information obtained from the initial research and steps 1 and 2, the following Node System Table was created.

Step 4: Develop a Scheduler Node Recipe

For the purposes of this example, the ACMI Scheduler recipe will be used so a new recipe does not need to be developed. While this recipe provides a rudimentary interface for scheduling Nodel Events, it is usually quite sufficient for small Nodel Systems and is very quick and simple to setup.

Step 5: Develop a Management Node Recipe

For the purposes of this example, the ACMI Management Node Recipe will be used so a new recipe does not need to be developed. This recipe generally provides all the functionality a Management Node requires with a simple to use interface.

Step 6: Develop the required Device Node Recipes

As defined in Step 3, the only two devices that require direct control and monitoring are the BrightSign LS442, and the BrightSign HD1023 as the Robosonics MP3 Trigger boards were unable to be controlled via a network. Due to the way BrightSign players are configured, only one Device Node recipe needs to be developed for these BrightSign players.

The ACMI Brightsign Recipe was developed for this purpose. Once a node is created using the Recipe, a port and IP address needs to be entered as a parameter. These parameters will be used to send UDP commands to a BrightSign player when told to do so by the calling of Local Actions. The UDP command strings are as defined in the Control Requirements List.

Step 7: Create system using Nodel Interface

Animation 2 – The created Nodel System.

Animation 2 shows the result of creating the Nodel System using the Nodel Interface using the Node System Table as a reference. The animation shows all the created Nodes as well as some of the Local Events and Actions created in certain nodes.  All up implementing this Nodel System took around 45 minutes which included some rudimentary testing.

Step 8: Test system

Finally, the entire should be tested in the real world in the physical presence of the hardware that is controlled by the Device Nodes. Notes should be made on control failures, and these issues should be fixed.

Conclusion

This post has broadly touched on how to go about creating larger Nodel systems in a methodical way using the example of ACMI’s Cleverman exhibition. Techniques described in Basic Concepts, and Implementing a Simple Nodel System have been used to create a Nodel System in a relatively short amount of time. Some Recipes created at ACMI have been shown as good tools to use when designing Nodel Systems that are quick to implement, and flexible enough to update in a easy manner without having to resort to developing new code. It was also shown that planning Nodel Systems in a methodical way is in general a good idea that can save time in the future.

Coding Tips will be the final post in this Nodel series. General advice about coding with Nodel will be explained that will give a leg up when coding Device Node Recipes for the first time.

 

Nodel at ACMI Part 2: Implementing a Simple Nodel System

Nodel is an open source digital media control system for museums and galleries, although there are many valid uses for Nodel outside of this scope where device control, monitoring, and scheduling is required.

In response to the pending renewal at the Australia Centre for the Moving Image, the technical services team decided to trial Nodel to assess it’s suitability as the control system for future exhibits and installations. I put my hand up to build a small Nodel implementation example, and write some documentation on the lessons learnt that would help future employees deploy Nodel around the organisation. This documentation will come in the form of four posts; Basic ConceptsImplementing a Simple Nodel System, Nodel System Design, and Coding Tips.

Implementing a Simple Nodel System, is the second of the write ups that will discuss Nodel. This post will describe how to implement the use case describe in the first post, Basic Concepts, introduce how to work with the Nodel Interface to create nodes, how to customise Nodes using python code, and how to use Nodel Recipes. It is highly recommended that you read Basic Concepts before going ahead and digesting this post.

Foreword

If you are trying to learn how to work with Nodel for the first time, It is completely recommended to follow each step in this post and using it as a guide to build your first Nodel system. However, there are a few things that will not be covered to keep the post as concise as possible. This includes a how-to on the installation and starting up of a Nodel session. There is already great documentation written about how to do this on Nodel’s wiki for every common operating system (and some more obscure ones to boot!). And while this post will briefly discuss the Nodel scripting toolkit reference, It will not teach you how to code in Python. Fortunately Python is widely known as one of the easiest programming languages to pick up, and if you want to take a primer in the language I recommend you take a look at Learn Python’s free interactive online tutorial which will teach you all you need to know to code with Nodel.

One cool thing about Nodel is that you can design, implement, and test a large part of a system on your laptop/personal computer before migrating it over to the hardware that will be actually be running the system afterwards. We will be exploiting this feature during this tutorial, so try and run the instance of Nodel on the computer your are working with during the tutorial.

The Nodel Scripting Toolkit Reference

Animation 1 – Accessing the Nodel scripting toolkit reference. Click to enlarge.

The Nodel scripting toolkit reference describes all the key functions that are available for us to use once we eventually do get around to coding, so obviously it is something we are going to want to take a look at. It can be accessed within Nodel by going to the Nodel homepage at localhost:8085, clicking on the Nodel logo, and then clicking on the scripting toolkit reference hyperlink. Alternatively you can access it in your browser using http://localhost:8085/toolkit.htm. If you are having trouble with this already, it is probably because your do not have a Nodel session running.

The key functions that we will be using  in this post are related to the creation and looking up of Local Actions, Local Events, Remote Actions, Remote Events, and the yet to be discussed Parameters.

The Use Case

Figure 1 – Use case for design problem

In Basic Concepts, we defined a use case involving a TV and a DVD player that needed to be turned on, and a acknowledgment from the TV and DVD player that confirmed the devices had indeed turned on when they were told to do so. Based on this use case, we came up with a Nodel design defining Node 1 as a Management Node, and Nodes 2 and 3 as Device nodes. Two separate implementations were designed, one using Remote Actions for control, and one using Remote Events for control. Believe it or not, defining these designs means half the battle of implementation is already won! We already know the exact nodes that need creating, and the Local Actions, Local Events, Remote Actions, and Remote Events that each node requires. These are shown in Table 1 and Table 2 for clarity. We will now go about implementing both these designs using the Nodel Interface. In order to keep this post a suitable length only the Remote Action control design will be laid out step-by-step, but after following these steps it should become straight forward enough to also implement the Remote Event control design by yourself!

The Nodel Interface

Accessing the Nodel Interface

Once a Nodel session is running, the Nodel interface will be accessible via any modern browser by typing in the IP address of your computer into the browser, and specify the port 8085. A more simple way of doing this would be by using localhost:8085 as shown in Animation 1.

Adding The Nodes

First thing’s first, we need to create our nodes. To do this we click the add node button, enter our node name, and select “add blank”. In the future, we will uses recipes to speed up the development process. But for now we will be creating our nodes from a blank canvas. After creating the nodes, we should be able to see that they are available from the Nodel Interface.

Animation 2 – Creating new nodes. Click to enlarge.

Nodes can be deleted by selecting the node from the Nodel interface, clicking on the Node title, and clicking the delete button. An example of this process is shown in Animation 3. It should be noted that sometimes the Nodel must be restarted for the deletion to be reflected in the interface.

Animation 3 – Deleting a Node. Click to enlarge.

Creating Actions and Events for Device Nodes

Each node once created contains a file entitled “script.py”. This file is where all the magic happens in regards to what a specific nodes Local Actions, Local Events, Remote Actions, Remote Events, and Parameters. It will also contain the functions that actually do something for device nodes. The Nodel interface provides an easy way to edit and update this file as changes are made. Once selecting the Nodel2Tv node from the Nodel home page, click the “enable” check box under the “advanced mode” label, then click the “display editor” checkbox. This will open an editing window where changes to the script.py file for this particular node can be made. For now, select all the sample code within this file, delete it and click the save button. You will be able to observe that once you have saved the changes, the node will automatically refresh the page, and the available Actions and Events (labeled Signals) now appear empty.

Animation 3 – Editing python code with the nodel interface. Click to enlarge.

Using the functions that we had a look at previously it is relatively easy to write the code necessary to create the required Actions, Events, and Functions. The Actions and Events are created in the main function. The handler function called “TurnOn” handles the turning on of the TV, but for simulation purposes it simply prints that the function has been called. A handler function called “UpdateStatus” handles the emitting of the local status event. Again this function is a placeholder for simulation purposes and will randomly emit “ok” or “not ok”. It is called every time the TurnOn placeholder function is called.

By copying and pasting the above code into the Nodel2Tv node’s editor and saving, it should be possible to observe the creation of all of the required Actions and Events. This step is demonstrated in Animation 4. This completes all that is required to configure the Node2Tv node.

Animation 4 – Coding for Node2Tv to create Actions and Events using the above code. Click to enlarge.

By making some minor changes to the names in the previous code, we can also finish up with the Node3Dvd Device node. The following code demonstrates this. Go to the Nodel home page, click on the Node3Dvd node, paste the code in, and observe the creation of the required Actions and Events. Also note how Device Nodes are implemented in a similar way, which will make the use of Nodel Recipes much clearer when described later on.

Animation 5 – Coding for Node3Dvd to create Actions and Events using the above code. Click to enlarge.

Creating Actions and Events for Management Node

Following the same procedure as before, the Management node can be completed. The Actions and Events are created in the main function. A handler function called “TurnOn” handles the calling of the TV and DVD node remote actions and this function is called every time a use clicks on the “TurnOn” Action button. A handler function called “UpdateStatus” handles the aggregation of the TV and DVD node status messages and emits the Management Nodes local status Event. It is called every time a status is reported (Local Actions from the Device Nodes are Emitted) from the TV or DVD nodes.

By copying and pasting the above code into the Node1Management node’s editor and saving, it should be possible to observe the creation of all of the required Actions, Events, and Bindings required. After clicking the save button under the bindings section, the Remote Actions and Remove Events will become “Wired”. This can be observed by looking for the green arrows in the binding section. This step is demonstrated in Animation 5. Believe it or not, this completes all that is required to configure the Management Node. We can now move on to testing.

Animation 6 – Coding for Node1Management to create Actions and Events using the above code. Click to enlarge.

Testing the System

A good way of testing the the system is by placing each node in a different browser tab and observing all the interactions. Animation 7 shows the result of calling the Node1Management nodes TurnOn local action. It calls both Device Nodes “TurnOn” Local Actions and emits the status Local Events. We can conclude after observing this that the system is working as intended!

Animation 7 – Testing the system by clicking the TurnOn local action on the Node1Management node and observing the result. Click to enlarge.

Nodel Recipes

While this was a good exercise, It should be apparent now that it is undesirable to have to write code for each individual node in a system. This would take a large amount of time and for the most part Management Nodes have very similar coding requirements. To solve this issue, we can use Recipes.

A Recipe is a template for a node. It is simply a script.py file. Museums Victoria has a Github Repository that contains official Nodel Recipes that can used for a wide range of Device and Management Nodes. Recipes should be stored in the Recipes directory (/nodel/recipes/), and will become available for use as node templates if stored in this directory. Animation 8 shows the availability of using Recipes as a node templates when they have been put in to this directory. In this case, a BrightSign player Recipe is used as a template for the creation of a new node.

Animation 8 – Using a Recipe as a template for a node. Click to enlarge.

Creating a Management Node Recipe Using Parameters

Figure 2 – An example of a Parameter from an node created using the official BrightSign recipe.

To unleash the full potential of Recipes we must use Parameters. Parameters allow user input. This user input can be used for many purposes. It could define a target node and target Local Action for a Remote Action, or it could define an IP address for when creating a device node. The format of the Parameter might be a string, an integer, a dropdown box, or an array including a combination of any of the three. The following code provides an example of different kinds of parameters used in a node, how they are created, and how the entered values can be used. In this case the values are printed inside the console window. Animation 9 shows the result.

Animation 9 -Example of the different kind of Parameter input methods. Click to enlarge.

Now we know what Parameters are let’s recreate the Node1Management node using Parameter inputs. To do this we will create a generic Management Node Recipe, and use it to configure the Node1Management node with a user input instead of hard coding the target nodes, Actions, and Events. The following code shows the resulting recipe. Animation 10 shows how the recipe is used to create a node, and configure the necessary bindings to Node2Tv and Node3Dvd.

Animation 10 – Using a Management Node Recipe. Click to enlarge.

 Conclusion

Hopefully following this tutorial has demystified some of the abstract concepts covered in the first post, Basic Concepts. We have covered the Nodel interface and how to actualise the abstract system design using code. We have also covered what Parameters and Recipes are,  and how they can be used to speed up the implementation process. it should be apparent by now that limiting the amount of time designers are coding is key to Nodel being practical in the real world. Just how to approach Nodel design with minimal coding is explained in the next post, Nodel System Design, where it will be shown how to design a large Nodel system and how to design Recipes that allow non-software engineering types to design and implement Nodel systems.