How to Get a Volunteer Visa in Bosnia and Herzegovina

So you want to get a Volunteer Visa in Bosnia and Herzegovina? Well, as you are going to find out Bosnia and Herzegovina does not particularly care for that.

The process of obtaining a “Volunteer Visa” can be pretty daunting but it is more well defined than some of the other bureaucratic wonders of this beautiful country. With a bit of forethought and planning some of the pain can be averted. But still, there will be pain. There will be pain for you, the organisation that you will volunteer for, and anyone who has the audacity to help you on this journey. Previously I went in to quite a lot of detail with How to Get a White Card in Bosnia and Herzegovina, however due to the complicated nature of obtaining visa’s in Bosnia, I will try to keep this post more concise.

So let’s talk a bit the background on the Volunteer Visa and how you can go about getting one.

What is a Volunteer Visa?

A Volunteer Visa, or the much less sexy sounding “Temporary Residence Grounded On Volunteering” is a residence permit that allows an individual to stay in Bosnia and Herzegovina for no more than one year on the basis of volunteering for a registered agency, institution, humanitarian organisation, association or foundation.

The permit may be extended if required, and allows the participant to receive “costs of subsistence, accommodation, health insurance and return [to country of origin]”. It does not give an individual working rights in Bosnia and Herzegovina.

When Do You Need to Get a Volunteer Visa?

If you are volunteering in any organisation within Bosnia and Herzegovina for any period of time, you will require a Volunteer Visa. Visa-free entries (sometimes referred to as Tourist Visas) do not allow individuals to volunteer.

What Happens If You Need a Volunteer Visa and Do Not Get One?

As per Article 105 on Law on Aliens, you leave yourself open to deportation, fines, and a lengthy entry ban from Bosnia and Herzegovina.

Generally speaking the risk of being caught for volunteering in Bosnia and Herzegovina without a Volunteer Visa is considered low provided you are legally allowed to be in the country. But times are changing. If you plan on volunteering in Bosnia and wish to return to Bosnia in the future, it is worth getting a Volunteer Visa.

How To Get a Volunteer Visa

Take a deep breath. We are going to dive head first into this. If you have successfully avoided having a panic attack after reading through this once over, read it again. This is doable.

First thing is first. Get the required documents. The full list of required documents for a Volunteer Visa application are listed in a document called “PB-2.5”. It can be found via the Department of Foreigner’s Affairs (SPS) website in English here and in BHS here.

Much of the steps I outline will be based off this document, however I will also include my own insights having successfully applied for the Volunteer Visa in the past.

Before I go into explaining what the required documents for the visa are and how to get them, I should mention that you will be required to get “verified copies” of many documents. You can get verified copies of your documents at various Općina offices around Bosnia. I will leave it to you to ask your token Bosnian how to do this as any attempt to explain it here will probably leave you scratching your head. Ask the organisation you will be volunteering for to assist you with the verification of your documents.

The Requirements

There are several things that should be stressed upon before going through the entire list of requirements.

  • First, get a police check from your country of origin. You will need to get it translated to BHS once in Bosnia and Herzegovina, and this can take time.
  • Second, tell the organisation that you will be volunteering for that you will need their cooperation. They will be required to provide a number of documents that may not be necessarily be easy to acquire, and will need to provide you with a volunteering contract that fulfils a number of requirements. If you do not have a token Bosnian friend who can spare some time to help you, make sure the organisation can provide someone to come to the Foreigner’s Office with you at the end to submit the application.
  • Third, do not wait. if possible start collecting documents before you arrive in Bosnia. The process of obtaining all the documents is probably going to take you at least a week once you enter Bosnia if you have the full cooperation of the organisation you are volunteering for. For me, the process took two full weeks the first time I completed it just to submit the application.
  • Fourth, All documents must be either in BHS, or translated to BHS. Translations cost money and take time, so do as much as you can in BHS. Below I have some comments on how to make this possible.
  • Finally, GET A WHITE CARD. Do it within 48 hours of entering Bosnia and Herzegovina. If you did not get one, leave Bosnia and return immediately so you can get one within the confines of the law on aliens.

A short summary of all the requirements from the PB-2.5 document are as follows:

  1. Application Form: A filled out “REQUEST FOR APPROVAL/ RENEWAL OF TEMPORARY RESIDENT PERMIT” application Form. This can be found on the Department of Foreigner’s Affairs (SPS) website here.
  2. Administrative Payment Receipt: Receipt from 150KM administrative fee for processing temporary residence applications. This can be done using a payslip at any post office and account information found on the Department of Foreigner’s Affairs (SPS) website here. An example payslip that I completed for my volunteer visa application without identifying information can be found below.
  3. Recent Photo: A 35x45mm photo. This can be taken anywhere, but a passport compliant photo print would be wise. I often go to Foto Žunić at BBI centar in Sarajevo to get this done.
  4. Passport Copy: 1 certified copy, and 1 uncertified copy of your passport that includes the image page, the page containing the passport validity, visa sticker if you are not a part of the visa free regime in Bosnia and Herzegovina, and the page with the stamp from your last entry in to Bosnia and Herzegovina.
  5. White Card Copy: 1 certified copy, and 1 uncertified copy of the White Card I told you to get earlier. Detailed steps on this painful process are outlined here.
  6. Previous Temporary Residence Stickers: 1 certified copy, and 1 uncertified copy of previous temporary residence stickers from Bosnia and Herzegovina. If you have never gained temporary residence in Bosnia before, this step is not required.
  7. Volunteering Contract: A volunteering contract from the organisation that you will be volunteering for. This should contain a specific article which I will comment on in a moment. A copy should be provided in BHS and a language you understand. The organisation you are volunteering for should provide this.
  8. Certificate From Organiser: A Certificate from “the organiser” detailing the volunteers name, position, and description of the jobs and tasks that will be performed on the relevant project. It must also include information on how the volunteers work will be conducted, organised, supervised, relevant working times, and the time frame for the entire project. This should be an official document with the organisation’s magic stamp and letterhead. The organisation you are volunteering for should provide this.
  9. Document From Organiser: A document from “the organiser” detailing information on the project as a whole. This should be an official document with the organisation’s magic stamp and letterhead. The organisation you are volunteering for should provide this.
  10. Organiser Project License: If “the organiser” is a “humanitarian organisation”, a verified copy is required of the license for the realisation of the project issued by the competent authority in BiH. The organisation you are volunteering for should provide this.
  11. Organiser Registration Document: Verified copy of the registration document from the organisation. The organisation you are volunteering for should provide this.
  12. Organiser Solvency Document: Evidence of solvency of the organisation. This can usually be provided by the organisation’s bank. The organisation you are volunteering for should provide this.
  13. Volunteer Insurance Policy: Insurance policy that has been taken out to cover “consequences of accident for alien” for their duration of the volunteering period. I personally obtained this insurance in less than 30 minutes by walking in to Vienna Osiguranje in Sarajevo with my organiser and explaining what the insurance was for. The cost was around 35KM for a 6 month period. The organisation you are volunteering for should provide this.
  14. Volunteer Costs Evidence: Evidence that “the organisation” will be responsible for the volunteers costs during the volunteering period. This includes costs for “subsistence, accommodation, food, medical treatment, health insurance and return, as well as costs of placing under surveillance, voluntarily leaving and forcible removal, and other costs which may incur during the stay of alien in BiH”. In my experience this requirement can be satisfied by the inclusion of an article in the volunteering contract. Below is an example article that proved satisfactory for my application.
  15. Consent of Engagement: If you are volunteering for a church or religious community, you are required to provide a “consent of engagement”. I have no experience with this and will not provide advice. If you are not volunteering for a church or religious community, forget about this requirement.
  16. Evidence of Means For Subsistence: The easiest way to provide this is to print out a bank statement that shows you have a minimum of 400KM per month for the volunteering period. The bank statement does not need to be official, and can even be a screenshot of your online bank account in my experience.
  17. Medical Attestation: It is best to do this in Bosnia as it will be in BHS, cheap, and quick. The easiest way to do this is to go to Poliklinika SaNaSa in Sarajevo and say “I need a health check and insurance for a visa application”. The insurance is required for the next requirement. They will immediately take your blood and urine, give you a rudimentary examination and tell you to return the next day. You will be out the door in 45 minutes flat. When you return, they will give you examination results, blood work, and urine analysis that will satisfy this criteria. They test for HIV, HEP C, and some other things involving blood cell count. They do not test for any kind of drugs. The health check and insurance will cost around 100KM.
  18. Evidence on Secured Health Insurance in BiH: The insurance available at Poliklinika SaNaSa satisfies this criteria.
  19. Police Check: From your country of origin. It must prove that that no criminal proceedings and penalty for criminal acts have been imposed against you and be no more than 6 months old. It must be translated to BHS. The translation must be done by a certified translator. I can highly recommend Sudski tumac Sarajevo. They are fast, prompt, and affordable.
  20. Evidence on secured accommodation in BiH: A lease agreement, or verified statutory declaration from a property deed holder will satisfy this criteria. I have also found it worthwhile to also get verified copies of the landlords/deed holders ID card and CIPS document for this step. This is required when obtaining a White Card regardless, so just make sure to get extra copies.

Submitting the Documents for the Volunteer Visa

To submit the documents for the Volunteer Visa, make a trip to the Foreigner’s Office with someone who speaks BHS and can represent you. Generally speaking, the folks at the Foreigner’s Office will not want to speak English with you, so this is important! In Sarajevo, this is located in the not so convenient location near the airport. You can find the exact location on the Department of Foreigner’s Affairs website.

Once inside the building it is not so clear what exactly you should do. Find a door and open it, ask for the person responsible for temporary residence on the basis of volunteering. They will probably will send you to a colleague in the neighbouring room, who will then return you to the original worker, who will then send you to a third room that will contain the correct worker. Save your panic attack for later. This is normal. Smile. Be confident. Avoid direct eye contact, they do not like that. You will do fine.


At this point, the workers at the Foreigner’s Office have probably sent you away with your application for having a minor error in one or more of the various documents. You return later that day with the correction and a strong suspicion of collusion between Department of Foreigner’s Affairs and Sarajevo Taxi due to your increasing spend on trips to and from the office. They accept your application. They tell you they will contact you when they are done processing the application. You never hear from them again.

As the great guide reminds us, DON’T PANIC.

Useful Links

How to Get a White Card in Bosnia and Herzegovina

Getting a White Card in Bosnia and Herzegovina is a right of passage. It is your gentle introduction into the wonders of Bosnian bureaucracy. You will be confused. You will be frustrated. You will not get any sympathy from your Bosnian friends who have been dealing with this kind of thing all their lives, and view you only as the token foreigner that you are.

But I digress…

Now that you know your place, let’s talk about what a White Card is, when you need to get a White Card, and how to go about getting one. There is a tendency to resort to anecdotes and informal advice when discussing this kind of stuff in Bosnia and Herzegovina, so I will try to back up my description of the process with links to the corresponding legal mumbo jumbo when possible and available online. But also keep in mind, I ain’t no lawyer. Just a guy who has done this numerous times and is getting pretty good at it.

What is a White Card?

An example of a blank White Card

A White Card is a white piece of card (Shock! Horror!) that lets the Bosnian Department of Foreigner’s Affairs (SPS) know where you are staying. It is a way for foreigners to register the address of where they will be residing while in Bosnia and Herzegovina. Pretty simple right? Similar reporting procedures exist throughout the region although each country tends to have a different way that allows you to obtain this magical piece of card.

When Do You Need to Get a White Card?

The Simple Explanation

Officially, If you plan on staying in Bosnia and Herzegovina for more 3 days and will not be staying at a business that provides accommodation services (including hotels and hostels), you are required to obtain a White Card within 48 hours of entering Bosnia and Herzegovina.

Unofficially, if you plan on eventually getting a temporary residence permit at some point during your stay in Bosnia and Herzegovina for whatever reason, you will require a White Card regardless as it is a requirement for the majority of temporary residence permit applications.

The Mumbo Jumbo Explanation

Article 103, clause 3 of the “Laws on Aliens” stipulates the following:

“An Alien who does not use accommodation services… is required to report the stay of the alien in BiH to the competent organizational unit of the Service or the police within 48 hours from the entry of the alien to BiH for any stay of the alien which is longer that three days.”

Note that the law details no specifics about how in practise this law is enforced. But essentially the “report the stay of the alien in BiH” is achieved by obtaining a “White Card”. The “competent organizational unit of the Service” is the Department of Foreigner’s Affairs (SPS).

In practise the ability to report your stay to “the police” does not seem possible. Personally I attempted this at the Novo Sarajevo police station, and they responded in a confused manner and told us to report to the Foreigner’s office. It would appear there is no mechanism yet in place to report your stay to the police at the very least in Sarajevo Kanton.

If you stay at official accommodation providers with Bosnia and Herzegovina, you are not required to register your address with the Department of Foreigner’s Affairs. This is due to Article 103, clause 1 of the “Laws on Aliens” which stipulates the following:

“Legal and physical entities that provide accommodation services are obliged to report a temporary residence of an alien to competent organizational unit of the Service or police no later than 12 hours after providing accommodation to an alien.”

You can find an English translation of the “Laws on Aliens” from the Ministry of Security of Bosnia and Herzegovina website in which this information was derived from here. There is also informal details about the requirement of the “registration of residence” on the Ministry of Security of Bosnia and Herzegovina website here. Finally, the Department of Foreigner’s Affairs also provides informal information on the “OBLIGATION TO REGISTER TEMPORARY AND PERMANENT RESIDENCE OF AN ALIEN” here, and here. All of this informal advice pretty much says the same thing, but the links are provided here for completeness.

What Happens If You Need a White Card and Do Not Get One?

Article 134, clause 5 of the “Laws on Aliens” stipulates the following:

“Fine in the amount from 100 BAM to 500 BAM shall be imposed on an alien not using the accommodation services of a legal or physical entity nor visiting a physical entity but failing to register his/her stay under Article 103”

In addition to this, you will be unable to apply for temporary residence if you do not obtain a White Card without exiting and entering Bosnia and Herzegovina again. It is generally accepted that the risk of being asked for a White Card when exiting Bosnia and Herzegovina is low. This is most likely a result of problems in implementing the law due to the complexities involved with obtaining a White Card, inconsistencies with accommodation providers registering guest information with the police, and poor data sharing arrangements between government departments in Bosnia and Herzegovina.

For a long period of time the borders of Bosnia have been poorly regulated. But times are changing, and more and more people are being punished for not obtaining White Cards when they are required to do so. If you plan on staying in Bosnia for a couple of months and wish to return to Bosnia in the future, it is worth investing the time and effort required in obtaining a White Card.

How To Get a White Card

Congratulations! You have made it this far and you are now ready to fulfil your legal obligations as a responsible member of the international community. “Good for you!”, your token Bosnian will say to you sarcastically. But do not react, you will need them for this next bit.

No official information currently exists online about how to obtain a White Card. In fact no official information exists online about the existence of the White Card, which one might argue makes obtaining one pretty difficult. But fret not, there is one document sticky taped to the back of an office door in the Foreigner’s Office located in Sarajevo detailing the requirements for obtaining a White Card. This is not a joke. Below is a photographed version of the document. A google translated version of the document along with original text that I transcribed can be found here.

Document outlining White Card requirements

The Requirements

A short summary of this document outlines the following requirements:

  1. The personal ID of your landlord (or person who has the deed to the property you are staying in).
  2. The CIPS document of your landlord or property deed holder.
  3. A “Guarantee Declaration” by the landlord/deed holder stating it is okay for you to stay at the property OR a lease agreement between you and the landlord/deed holder.
  4. A photocopy of your identity document (passport) that includes the image page, the page containing the passport validity, visa sticker if you are not a part of the visa free regime in Bosnia and Herzegovina, and the page with the stamp from your last entry in to Bosnia and Herzegovina.
  5. Receipt from the payment of the “tourist tax”.

Before I go into explaining how to obtain each one of these documents, I should mention that if you cannot bring the originals of the documents to the Foreigner’s Office (which there is a good chance of this happening), you should get “verified copies” of the documents. You can get verified copies of your documents at various Općina offices around Bosnia. I will leave it to you to ask your token Bosnian how to do this.

The Landlords Identification Card

This one is pretty simple. Almost every individual has an identification card in Bosnia, including your landlord. If the landlord will not come with you to the Foreigner’s Office, simply ask them to get a a “verified copy” of there ID card from an Općina office.

The Landlords CIPS Document

If you did not annoy your landlord by asking them for a copy of their ID, you have definitely annoyed them now that you have asked for their CIPS Document. Their eyes have most likely widened, they have repaid your request with a long breathless silence, and they are considering getting a new tenant. Either way, again, if the landlord will not come with you to the Foreigner’s Office, simply ask them to get a a “verified copy” of there CIPS document from an Općina office.

Guarantee Declaration From the Landlord

A guarantee declaration is similar to a statutory declaration. If you do not have a lease agreement or you are staying somewhere as a guest for free, it is best to get one of these declarations. By going to your nearest Općina office, you can get a declaration form and get it “verified”. The declaration form should state your full name, the full name of the landlord, and explain that you may stay in their household for a particular period as a guest.

If you do have a lease agreement, this document will suffice. Again, get a verified copy from a Općina office if you cannot bring it with you to the Foreigner’s Office.

Photocopy of Passport

This one is pretty self explanatory. A photo copy with the identification page, and the page containing the stamp from your last entry into Bosnia and Herzegovina. It is usually best to verify the photocopy of the passport at an Općina office.

Paying the Tourist Tax

The easiest way of paying the tourist tax is by going to a local post office and asking for a payment slip. You can then fill out the payment slip exactly as provided below. I received this information from the Department of Foreigner’s Affairs website after a lot of research, but the details are also available on that infamous piece of paper that is sticky taped to the back of a door in the Foreigner’s Office. The tourist tax is 10KM, but you will pay 11KM at the post office. You will be given back two stamped copies of the payment slip once you make the transaction, of which you will give one copy to the Foreigner’s Office.

An example payslip to pay the “tourist tax”

Submitting the Documents for the White Card

To submit the documents for the White Card, make a trip to the Foreigner’s Office with your token Bosnian I mentioned a little earlier. Generally speaking, the folks at the Foreigner’s Office will not want to speak English with you, so this is important! In Sarajevo, this is located in the not so convenient location near the airport. You can find the exact location on the Department of Foreigner’s Affairs website. Once inside the building it is not so clear what exactly you should do. Find the door with information regarding “Bijeli Karton”, knock, enter, smile, and you should exit with this most sacred of papers.


By now your relationship with your landlord is destroyed, the friendship with your token Bosnian is irrevocably damaged, and you are 11 marks poorer.

Good for you!

Useful Links

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:


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


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.


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.


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 “”. 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 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 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.


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.

Nodel at ACMI Part 1: Basic Concepts

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. It was originally developed by Lumicom as commissioned by Museums Victoria in response to a 2010 review and subsequent white paper in to the organisations digital media control requirements, and was first used in the First Peoples and Think Ahead exhibition located at at Melbourne Museum and Scienceworks which opened in 2013. It is released as an open source project hosted on GitHub where an installation guide and Wiki can be found.

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 Concepts, Implementing a Simple Nodel System, Nodel System Design, and Coding Tips.

Basic Concepts, is the first of the write ups that will discuss Nodel. This post will describe Nodel in a more abstract sense. Some information will be closely regurgitated from the available GitHub Wiki page and white paper, but is never-the-less included here for completeness. It is highly recommended that you read the white paper and museum and gallery implementation before reading through these posts. Each post will be targeted towards the implementation of Nodel in museums and galleries.

Nodel Architecture


The architecture of Nodel is based on individual ‘nodes’ that each perform a specific task. Each node has the ability to do something using “Local Actions”. A Local Action can be “called”, and this then performs the action. An action can literally be anything you can code. A node also has the ability to display information to the user using “Local Events”, or as they are sometimes labeled as, “Signals”. The difference between Local Events and Signals is labeling, they are the same thing, so henceforth I will only describe them as Local Events. A Local Event can be “emitted”, and this updates the displayed parameters of the Local Event. A node may have as many Local Actions or Local Events as needed.

Figure 1 – A simple representation of two nodes, Local Actions, and Local Events/Signals.

While this is a good way to look at nodes in a broad sense, the way these Local Actions and Local Events are called and emitted are a little more complex. Figure 2 shows how some of these interactions occur. Local Actions trigger internal node functions​. Emitted Local Events update data that can be seen when viewing a node. But in order for nodes to interact with each other, Remote Actions and Remote Events also exist separately to their local counterparts.

Figure 2 – A more complex representation of a single node.

While some of these concepts may seem a little confusing to non-software engineering types now, they are important topics to grasp if you wish to design your own Nodel systems in a way you can troubleshoot yourself.

Communication Between Nodes

Figure 3 – An example of inter-node control and communication.

Nodes have ways of communicating with and influencing each others behavior. One way to do this is through “Remote Actions”. One node can call another nodes Local Action by creating a Remote Action and providing details such as the target node name and target Local Action name. Once a Remote Action is created, the Remote Action “binds” with the target nodes target Local Action and this allows the Local Action to be called “remotely” from a different node. Another way is to create “Remote Events”, which work in a similar way to Remote Actions. A Remote Event can be created using details such as the target node name and target Local Event. After it’s creation, it binds to the target nodes target Local Event. Now every time the Local Event is emitted, the data it emits is passed to the bound Remote Event in addition to being available locally on the target node.

These control and communication techniques are integral, as they allow not only control between nodes, but allow information sharing between nodes which is particularly important when performance monitoring of specific nodes is required.

Hierarchy Between Nodes 

All nodes are born equal as clean slates. They have all the same properties, abilities, and potential. Despite this they can be configured in a way that enforces a hierarchy of nodes. By using the control and communication methods explained above, it is possible to group nodes. A good way of describing this is by defining the functionality of each node in to two categories, Management Nodes and Device Nodes.

Figure 4 – An example of Management Nodes and Device Nodes enforcing a hierarchy of nodes. Local Events propagate upwards using Remote Events, while Remote Actions propagate downwards using Local Actions.

A Device Node controls something directly. This might be hardware, software, or some other kind of system. It uses local actions as a form of control, and sends messages to Management nodes that might include important information about what it is doing or it’s status.

A Management Node groups multiple nodes together. Local Actions on multiple nodes can be called at once using management nodes, and Local Event messages from multiple nodes can be aggregated at one management node. This makes controlling complex systems simpler to control and monitor. Management Nodes might manage a series of Device Nodes, a series of Management Nodes, or a mix of Device and Management Nodes. There really are no rules in that regard.

Figure 5 – A complex representation of how a Management node controls and communicates with a single Device Node.


All these examples and information about the guts of individual nodes is all well and good, but obviously a lot of choice exists with how you can actually implement nodes, how they communicate, and how they control each other. So now we have a bit of knowledge, let’s breakdown the core methods using some fun stick figures and a situation where we require a TV  and a DVD player to be turned on and an acknowledgement from the TV and DVD player that both devices have been turned on. By observing Figure 6, It should be clear that in this case Node 1 should be a Management Node while Node 2 and Node 3 should be Device Nodes. With that being said, we can configure the three nodes in the following manner. There are two main ways to implement the Control aspect of this use case, while there is one way to implement the communication.

Figure 6 – Use case for design problem

Control with Remote Actions

Figure 7 – Use case control solution using Remote Actions.

To control the Device Nodes, The Node 1 Management Node will have a Local Action called “TurnOn”, A Remote Action with a target node of “Node 2 TV” called “TurnOn”, and A Remote Action with a target node of “Node 3 DVD” called “TurnOn”. Inside the Local Action function tied to this “TurnOn” Local Action, the two Remote Actions will be called, thus triggering the Device Node Local Actions further down the hierarchy.

The Node 2 TV Device Node will have a Local Action called “TurnOn”, and the Node 3 DVD Device Node will also have a Local Action called “TurnOn”. By configuring these nodes this way, when the Node 1 Management Node Calls it’s “TurnOn” Local Action, these two Local Actions will be triggered through the bound Remote Actions. The code encapsulated within these Device Node Local Action functions should do what is required to turn on the respective devices.

It should be noted how Actions should almost always propagate downwards in a hierarchical Nodel system

Control with Remote Events

Figure 8 -Use case control solution using Remote Events.

It is also possible to control the Device Nodes using Remote Events, although the setup is slightly more convoluted.

The Node 1 Management Node will have a Local Action called “TurnOn”, A Local cvent Called “Node 2 TV TurnOn”, and A Local Event called “Node 3 DVD TurnOn”. Inside the Local Action function tied to this “TurnOn” Local Action, the two Local Events will be emitted.

The Node 2 TV Device Node will have a Local Action called “TurnOn”, and the Node 3 DVD Device Node will also have a Local Action called “TurnOn”. The Node 2 TV Device Node will have a Remote Event with a target node of “Node 1 Management” and a target Local Event of “Node 2 TV TurnOn”. The handler function that this Remote Event points to will call the Node 2 TV Device Local Action “TurnOn”. The Node 3 DVD Device Node will have a Remote Event with a target node of “Node 1 Management” and a target Local Event of “Node 3 DVD TurnOn”. The handler function that this Remote Event points to will call the Node 3 TV Device Local Action “TurnOn”. Like in the previous example, The code encapsulated within these Device Node Local Action functions should do what is required to turn on the respective devices.

It should be noted how Local Events propagate downwards in a hierarchical Nodel system when used for control purposes.


Figure 9 – Use case control and communication using Remote Actions.

To allow the two Device Nodes to report back whether the respective devices have indeed turned on The Node 1 Management Node is required to have a channel for communication in the form of a Remote Event. The Node 1 Management node will have a Remote Event with a target node of “Node 2 TV” and a target Local Event of “TV Status”, and a Remote Event with a target node of “Node 3 DVD” and a target Local Event of “DVD Status”. In order to actually see the data that is emitted to these remote events, two Local Events should also exist. These Local Events will be called “Node 2 TV Status”, and “Node 2 DVD Status”. When one of these Remote Events is emitted from one of the Device Nodes, a handler function will emit the relevant Management Local Event.

Now that the Management Node has a communication channel, The Device nodes need to bind to it. To achieve this, a Local Event should be created on the Node 2 TV Device Node called “TV Status”, and also created on the Node 3 DVD Device Node called “DVD Status”. Now every time one of these Local Events emits, The message will propagate upwards to the Management Node. In this case study, it would be wise to check if the device is on and emit these Local Events every time the Local Action “TurnOn” is called.

Finally, it can be a good idea to also aggregate messages with Management Nodes so multiple messages can essentially be condensed down to “OK”, or “NOT OK”. To do this the Node 1 Management node should have a third Local Event called “Overall Status”. Each time the Remote Events is emitted from one of the Device Nodes, the handler functions should aggregate the existing messages, and also emit this “Overall Status” Local Event with the aggregated messages as the data.

Figure 10 – Use case control and communication using Remote Events.


By now it should be apparent just how flexible Nodel is in regards to building complex control systems. This flexibility can be a blessing in that almost anything is possible! But this comes at the cost of implementation complexity. Developing complex Nodel Systems can take time to design and test. But fret not, Nodel Recipes make this process a whole lot easier and introduce reusable elements to this design Process. This is something I will cover in the next post, Implementing a Simple Nodel System, where it will be shown how the use case used in this post can be implemented in real life!

A High Speed High Current LED Driver; Refurbishing ACMI’s Zoetrope

One of the more popular exhibits in Screen Worlds at the ACMI is The Zoetrope. Like all exhibits inside of Screen Worlds, the Zoetrope has not aged gracefully due to over 9 years of active service! With the original design utilising xenon based strobe lights, the maintenance cost of this exhibit in man hours and replacement lamps was significant. Eventually it was decided to refurbish The Zoetrope with a new LED based lighting system to reduce these costs, which was easier said than done! At the conclusion of the refurbishment a custom high speed, high current LED driver circuit and PCB was designed. Many were assembled and custom LED bars driven by these LED drivers replaced the old xenon strobe lights resulting in significant cost savings!

The Zoetrope Throughout Time

The Zoetrope. Source: ACMI

Zoetrope type devices were originally created in the 18th Century, however the technology used to produce a zoetrope like effect in modern museums has evolved significantly. By utilising an electric motor, 3D printed models, and strobing xenon based lights, a 3D real life animation like effect is realised!

However this mix of technology proved to be problematic. Due to the 8 hour a day, 7 day a week running schedule, at least one xenon lamp blew every week or two.  On average, replacing one these lamps took a technician 30 minutes to complete due to accessibility issues. Now 10+ years ago xenon strobe lighting was all the rage, however the ability to buy replacement lamps for these lighting devices has become increasing difficult due to the rise of the LED.

The Specifications

The control signal that drove the xenon strobe lights was a simple pulse, with a high value indicating the strobe light should be on, and a low value indicating the light should be off. This control signal came from a microprocessor with a series of connected sensors and these sensors detected when a lighting pulse should occur. The voltage output of this signal was approximately 10V peak-to-peak, an odd value that was likely chosen due to the internal circuitry of the xenon strobe lights used in the exhibit.

This control signal pulse had an on time of 4ms, and an off time of 54ms. This meant that the total cycle time was around 17.2Hz, with a duty cycle of around 6.8%. Now these requirements might not sound that stringent, with many LED strobes on the market being able to fulfill this criteria. However due to the type of control signal being used, the exhibit’s necessity on absolute synchronisation of the various elements, and the fact that DMX based lighting having a refresh period of only 44Hz (compared to what would be a minimum refresh period of 250Hz due to the 4ms on time), an off-the-shelf strobe lighting solution was quickly disregarded.

Due to this, whatever LED driver circuitry that was chosen had to be able to handle a 10V control signal, be able to sink over 1 amp of current for small periods of time, and have a rise time significantly less than 4ms. A variety of off-the-shelve Luxdrive LED drivers initially looked promising such as the FlexBlock series due to their ability to handle 10V strobed control signals and sink significant current, however when tested the output rise time of <2ms proved problematic. Dim output was observed and this option was also discarded. It was then decided to design a custom LED driver and LED Bar.

The Custom LED Bars

One of 12 constructed LED Bars.

To ensure enough light was produced, each custom LED bar consisted of six Cree XP-E2 LED stars for a total of eighteen individual LEDs. Pairs of LED stars are wired in series. Due to the forward voltage of roughly 2.9V, each series pair was driven with a 24V power supply. Each Pair of LED stars required it’s own driver box. In total 72 individual Cree XP-E2 LED stars were attached to 12 separate bars with thermal glue. A frosted optic was also used to focus the light with a tight beam pattern on the exhibit.

It should be noted that the LED bars did not have sufficient heat sinking capacity to to remain illuminated for a significant period of time and get truly hot when left on without pulsing!

The Custom LED Driver

The LED Driver circuit schematic.

The LED driver circuit was heavily influenced off the circuit found here. A 4N25M optocoupler was used to isolate the driver circuit from the control circuit, to buffer the control signal, and to provide the MOSFET with a sufficient input signal to fully turn the MOSFET on. The 1 ohm sense resistors connected in parallel were of the high wattage variety (5W+), as quite a lot of current is dissipated through them, making this not the most efficient design.  An output current of approximately 900mA was observed in series with the connected LEDs when the optocoupler was driven with a 10V input signal. Although if you decide to build this yourself, be sure to test this as small component variances may lead to an output current that destroys your LEDs!

One of the contructed LED driver boxes.

A custom PCB for the circuit was also designed and manufactured. It was found that no heat sinking of the MOSFET was required provided the duty cycle remained less than 10% with a cycle frequency of 17.2%. While this does not protect the driver from a control signal failure, it was deemed that this was unlikely to occur within the exhibit.

The Installation

The Zoetrope lighting before refurbishment. Source: here

The Zoetrope after refurbishment.

The LED bars were hung from the roof of the exhibit, and the LED driver boxes were connected to there respective LED bars. The control signal was wired in parallel to all driver boxes.

Setup diagram for LED bars and LED drivers.


While the challenge of refurbishing The Zoetrope was somewhat niche, the resulting design for a isolated high speed, high current LED driver is a useful one to have created. While the driver boxes are not the most efficient devices, they can never the less sink a lot of current with a very short rise time. This solution is something that is difficult to find off-the-shelf, and the relative simplicity of the circuit makes it something that is easy to construct in small runs for many applications.


The Parametric Digital Transducer Array Loudspeaker

For my capstone project that I completed at RMIT University I conducted a bunch of research into experimental loudspeaker designs such as Digital and Parametric Loudspeaker Arrays. As a result of this project I conceptalised a design for the Parametric Digital Transducer Array Loudspeaker, built a prototype, and validated the design by performing a variety of measurements on it that time and resources would allow.

In the spirit of Open Source, I decided to write up this casual, albeit somewhat tech heavy post explaining the basics of true digital loudspeakers, Parametric Loudspeaker Arrays, and the Parametric Digital Transducer Array Loudspeaker design in contrast to the more conventional loudspeaker designs. If you are really interested in a more comprehensive look at this topic, the final report, materials list, images, data, references, and associated code used in the project can be found here.

What is a "Conventional" Loudspeaker?

A moving-coil type loudspeaker with a cone based diaphragm. Source

A conventional loudspeaker is very much like the type of loudspeakers you find in everyday life. They usually utilise various implementations of a moving-coil type design, however also commonly use piezoelectric bimorphs. These designs all achieve the same goal with varying efficiency, frequency response, and total harmonic distortion (THD) levels through the conversion of electrical audio signals into acoustic waves by pushing a diaphragm backwards and forwards.

What is a "Digital" Loudspeaker?

Direct Acoustic Digital-to-Analog Conversion

A digital loudspeaker is a loudspeaker that is capable of performing Direct Acoustic Digital-to-Analog Conversion, or DADAC in its mildly more manageable acronym. DADAC is the process of creating an acoustically decoded sound pressure signal by driving and emitting digital streams through a loudspeaker array, with conversion taking place via acoustic summation. Quite a mouthful, that's for sure! So what does one of these loudspeakers look like, and how exactly is DADAC performed in practice?

Digital Transducer Array Loudspeaker

A few examples of DADAC capable loudspeakers. Source: Direct Acoustic Digital-to-analog Conversion with Digital Transducer Array Loudspeakers

DADAC capable digital loudspeakers come in a variety of topologies, shapes, and sizes, but for relative simplicity's sake I will only detail the One-bit Per Transducer Digital Transducer Array Loudspeaker design, or DTAL.

A visual representation of an eight bit One-bit Per Transducer DTAL performing DADAC.

The One-bit Per Transducer DTAL design works on the principle that each weighted bit in a digital signal is represented by one transducer element. Each transducer element is driven by a signal proportional to its bit weight. This loudspeaker requires an array of transducers that is defined by the bit depth of the digital signal being used. Once these digital pulses are output from the individual transducer elements within the array they recombine in air, reproducing the original digital signal and performing DADAC. This process is made possible by the usage of a bit-spilling operation that converts a digital signal in to multiple one-bit weighted digital signals.

Bit spilled signal example. Top: Double-sided 2 bit signal. Middle: LSB spilled signal. Bottom: MSB spilled signal

Advantages of a "Digital" Loudspeaker?

Compact and thin examples of DADAC capable loudspeakers. Source: Digital sound reconstruction using arrays of CMOS-MEMS microspeakers, Development and Characterization of a Piezoelectrically Actuated MEMS Digital Loudspeaker

It might not look like it from the earlier pictures, but devices that can perform DADAC have the possibility to be smaller, thinner, and more efficient than their conventional counterparts. Due to the arrayed nature of the design, digital loudspeakers have the intrinsic ability to perform beamforming and can potentially steer the direction in which audio is output from the loudspeaker. This beamforming is possible for the entire frequency range of the loudspeaker, not just small segments of the frequency spectrum which is commonly the case when using similar methods in other applications such as cardioid subwoofers.

Disadvantages of a "Digital" Loudspeaker?

Due to the listening path differences that exist between transducer elements, it is impossible to get a perfect summation of all the emitted signals in most listening positions. This results in significant distortion at many listening positions. There are various methods that can be used to reduce this distortion, although without reducing the size of each transducer to sub-centimetre levels, the level of distortion produced struggles to reach the relatively low levels of distortion produced by high quality conventional loudspeakers. One company, Audio Pixels, is currently working on a low cost MEMS digital loudspeaker that is attempting to do just this.

What is a Parametric Loudspeaker Array?

A Parametric Loudspeaker Array, or PLA, is a highly directive loudspeaker that consists of an array of ultrasonic transducers that exploit the nonlinear properties of air to self-demodulate modulated ultrasonic signals with the aim of creating audible sound waves.

Parametric Loudspeaker Array utilising digital processing.

In practice this can be achieved by performing amplitude modulation on an audio signal, and driving transducers directly with the resulting signal. Once the emitted ultrasonic sound waves are a little bit away from the array, they will demodulate and produce a secondary sound beam. This secondary beam will predominantly contain the original audio signal.

This technology has been successfully adopted by companies such as Holosonics, HyperSound, Ultrasonic Audio, and a funded Kickstarter campaign called Sound Lazer.

Advantages of a Parametric Loudspeaker?

Ultrasonic devices such as ultrasonic piezo transducers tend to have narrow directivity patterns, effectively emitting sound waves in well-defined beams. By designing PLAs with such transducers, audio can be output in very precise manner. By using these properties even further, it is possible to produce devices that use beamforming to directly control the direction and dispersion of audio, much in the same way that a DADAC capable loudspeaker can do this.

Disadvantages of a "Parametric" Loudspeaker?

Generally speaker, PLAs produce higher amounts of THD than conventional speakers due to the same non-linear properties of air that allow demodulation in the first place. The amount of THD a PLA produces is highly dependent on the type of modulation scheme that is used. They also suffer from low sound pressure level output, poor efficiency, and poor low frequency response making music playback difficult.

What is a Parametric Digital Transducer Array Loudspeaker?

A Parametric Digital Transducer Array Loudspeaker, or PDTAL, is simply an amalgamation of DTAL and PLA type designs.

Parametric Digital Transducer Array Loudspeaker with beamforming capability diagram.

An digital audio signal is amplitude modulated before being bit-spilled in to different weighted bit streams. These bit streams are then amplified by amplifiers that are weighted according to each bit stream weight. The resulting signals then drive individual or groups of transducers. The digital pulses emitted from these transducers sum in air, reproducing the original amplitude modulated digital signal and performing DADAC. This acoustic wave then demodulates and produce a secondary sound beam which predominantly contains the original audio signal as per the previous PLA design.

Advantages of a Parametric Digital Transducer Array Loudspeaker?

For the same reasons you might want to was a PLA.  Narrow directivity patterns and beamforming capabilities. However there are several advantages of using a PDTAL type design over a PLA design. This includes the usage of digital amplifiers in the amplification stage allowing the elimination of digital-to-analog converters (DACs) in the circuit design, as well as simplified driver amplifier designs. This is significant as a beamforming capable PLA usually requires many DACs and more complicated driving amplifiers. Overall, this reduces system complexity and cost.

Another great benefit of the PDTAL design is the improved low frequency response of the loudspeaker, which I will explain a little further on.

With this being said, the PDTAL suffers some of the same issues as PLA and DTAL type designs. This includes higher THD when compared to conventional loudspeakers which may be considered an acceptable compromise for having a narrow beam pattern with digital steering capability and all digital loudspeaker design.

The Parametric Digital Transducer Array Loudspeaker Prototype

Prototype hardware block diagram.

The design for the constructed prototype had an 8 bit resolution, and a sampling frequency of 97.65625KHz, It utilised an Opal Kelly XEM6010-LX45 FPGA board for signal processing, 4 Texas Instruments LM293D H-bridge amplifiers for amplification, and a 28 element Murata MA40S4S ultrasonic transducer array. 7 groups of 4 transducers were wired in parallel in an attempt to increase the sound pressure level output of the prototype. The weighting of each amplifier was implemented using pulse width modulation and varying duty cycles

Signal flow diagram of prototype system.

Prototype Measurement Techniques

Measurement setup for the PDTAL prototype.

A series of acoustics measurements were conducted in a quiet, but non-anechoic room 30cm away from the loudspeaker using sinusoidal signals with frequencies of 50Hz, 100Hz, 200Hz, 400Hz, 800Hz, 1600Hz, 3200Hz, and 6400Hz. Frequency response, THD, and signal-to-noise ratio (SNR) data was calculated from these measurements when possible. Due to the excessive ambient noise conditions in the room where the measurements took place, as well as the low sound pressure level emitted from the PDTAL prototype, accurate polar pattern measurements were not possible.

Measurement Results

Measured frequency response of the measured prototype.

The above figure shows the frequency response of the prototype as taken over a number of measurements. The 6dB per octave low pass filter with a 900Hz roll off frequency can be observed.

The next figure shows THD against output frequency of the prototype. THD generally decreases as output frequency increases except for frequencies above 6KHz.

Measured THD against frequency of the PDTAL prototype.

Measurement Discussion

The prototype has a flat frequency response up until until 900Hz where a 6dB per octave slope can be observed. This slope is due to the narrow frequency response of the MA40S4S piezo transducer. To extend the high frequency performance of the PDTAL design, a transducer with an extended frequency response could be used. The design appears to be able to produce low frequency signals with frequencies as low as 50Hz with a narrow directivity pattern. This can be considered an excellent attribute seeing as the reproduction of signals bellow 500Hz in PLA type designs is usually very difficult without drastic equalisation. The ability of the PDTAL design to reproduce these low frequencies can be considered a positive design attribute over conventional PLA designs.

The PDTAL Prototype produced similar amounts of THD to that of PLA design that utilise double-sideband modulation with a high modulation indexes. With that being said, It is highly likely that switching to single-sideband modulation would reduce the THD of the PDTAL design to acceptable levels.

But What Does it Sound Like?


Digital and Parametric Loudspeaker Arrays have quite a way to go before they are more widely adopted in the audio world due to their high levels of THD, and poor frequency response. The PDTAL design potentially solves the issue of poor low frequency performance of parametric speakers, and also potentially reduces the excessive THD distortion produced in off-axis positions with digital loudspeakers. All the while the design reduces system complexity when used in beamforming applications.

As mentioned earlier, this post only scratches the surface on the methods of Digital and Parametric Loudspeaker Arrays. More complete information can be found online via the shared project materials.


A Magnavox Odyssey Pong Clone Using Arduino

The Australian Centre for the Moving Image, or ACMI as it is more commonly called was home to the permanent exhibition Screen Worlds before it’s recent refurbishment took place. The exhibition was first opened all the way back in 2009, and has a large range of exhibits that showcase different technologies and trends in film, television, and digital culture that date back more than 100 years. Now when screen worlds opened, I was only just graduating high school myself, but after joining the ACMI AV department as an AV Technician for the first time in 2013 I had the opportunity to get well acquainted with the individual exhibits by performing maintenance and making sure they stay up and running for as long as possible despite using equipment and technology that is now almost 10 years old!

This is easier said than done. Sometimes we are talking about maintaining 40 year old gaming consoles that run 24 hours a day! A reoccurring victim of this ambitious operating schedule was the legendary Magnavox Odyssey that ran a copy of the original Pong. ACMI burnt through quite a few Magnavox Odysseys through the years which is not particularly surprising seeing as the console was released in 1972. Original functional Magnavox Odysseys have become increasingly rare, and with the exhibit closed for some time the ACMI AV department decided to commission a rebuild of Pong that would try to emulate the original as closely as possible. Seeing an opportunity to do something cool, I put my hand up to attempt building a clone.

JAMMA Boards and Emulation

So how do you attempt a clone of something like Pong? There are lots of different pre-existing solutions out there that will do the job, but what are they and how faithful are they to the original?

Unbranded and branded so called “multicade JAMMA boards” are available from a variety of online sources that usually contain one or more versions of Pong, although versions of Pong that emulate the Magnavox are rare. Perhaps the most well known branded multicade boards are the Pandora’s Box series. But don’t go rushing to find a website with information on these boards, they are mostly illegal. They use MAME emulators in conjunction with illegal game ROMs that have annoyed companies such as Nintendo for years. If you know someone who has an arcade machine with these old classics and it didn’t cost several thousands of dollars, it is almost certainly illegal! Because of this using any kind of emulation or third party board was out of the question. This includes the use of any kind of computer that uses emulation software to play illegally downloaded ROMs. While various linux distributions such as the widely popular RetroPi are not illegal, legal ROMs of Pong are not available for purchase.

Coding a Clone

In contrast to emulated ROMs, coding a clone from scratch that is devoid of any particular trademarks is perfectly legal, hence why so many Pong derivatives have existed over the years. With this being the case, I decided to give a go at coding one these. The easiest solution would have been to make a reasonably accurate clone that can run on a PC or Raspberry Pi, but after doing some quick googling I noticed quite a few people had tried to code Pong games using the Arduino Uno and the TVout library. This library makes it possible to create composite signals using a couple of resistors and a couple of GPIO pins. The graphics it produces are pretty rudimentary, but perfect for something like a pong clone. Composite type signals are often imperfect, which actually helps create a retro type effect in applications such as this! It also has a simple audio tone generator which can produce some pretty convincing 1 bit audio signals.

The Hardware

The existing controllers were custom made to resemble the old school Magnavox controllers, and had two potentiometers each, as well as one momentary push button. One potentiometer acts as the spin control for once the ball has been hit, and one acts as the paddle position control. The push button puts the ball back in to play. The potentiometers are connected to various ADC channels on the Arduino, and the pushbutton is connected to a GPIO pin.

Existing Magnavox clone controllers

A GPIO pin was also reserved for connecting to an RCA jack that acts as the audio output. Two resistors are used for the composite output as per the write up done on the TVout library reference.

Schematic of project showing where everything was connected.

The Code

The code for this project is available here and is licensed under GPL 3.0, so by all means go ahead and use this yourself! I won’t go in to the details of the code itself as it is pretty sufficiently commented, but if everything is wired up correctly this should work straight out of the box using Sketch.

This Pong clone is closer to the version released for the Magnavox Odyssey 300 rather than the original Magnavox Odyssey. Hopefully the kids in Screen Worlds don’t notice! Some bugs appeared after installing this at ACMI which I didn’t have the chance to fix. If the ball is going fast enough sometimes it will go straight through a paddle and win a point for the opponent. The spin control was a little difficult implement, and harder still seeing as I never got a chance to play Pong on an actual Magnavox. One of the tougher things to get right with the TVout library is to make sure the game and graphics have been sufficiently updated before TVout tries to bit bang the output. This can actually add a visual retro effect to the game, but is not ideal and highlights how even a simple Pong game can push an AVR Atmega microcontroller to it’s limit.

With the ACMI renewal taking place Screen Worlds is no longer open, so you cannot any longer play this clone in the real world. However you can build it yourself using these resources and keep Pong alive well in to the future!

University Portfolio

Throughout my degree I conducted a variety of assignments as assessments for various courses at RMIT. As a kind of portfolio, I decided to share some of the work here. Do keep in mind a lot of the work shown here was done through group assignments, so not all the work is mine alone. Code and documents are attributed as such when appropriate.

Introduction to Embedded Systems:

  • Sun Tracking unit. A dual axis servo sun tracking unit controlled by an Atmel Atmega32 with code written in assembler,

Wireless Sensor Networks:

Real Time Systems:

Capstone Project:


Attempting to Influence the Bosnian Election

Update 10/06/2020: has been down for sometime due to me not wanting to pay the domain name fees while the elections are not on. But fret not, it will return!

I am not going to lie, Bosnian elections make me excited. To all the Bosnians reading this, go ahead and roll your eyes, I am well used to a good eye rolling from a Bosnian. But please, let me get others up to speed before I continue to explain what the hell I got up to.

The Background

The Bosnian political system is one of the most complex in the world. With three presidents elected along ethnic lines, four tiers of governance all of which hardly function, the country barely functions in the normal sense that people in Western Europe or even Australia have become accustomed to. With that being said my jokes about Bosnia’s political system functioning better than Australia’s due to the latter having six prime minsters in ten years with the former having only three have never gone down well amongst the local populace to my extreme disappointment.

But enough of my nonsense. There are plenty of articles about the Bosnian elections that include all the details on corruption, blatant vote buying, and rhetoric that includes threats of secession and on a good day, war. So what is this election influencing all about?

Around April of this year, a local released El-Bake and Flappy Fahro. Not only did the games prove popular and go viral quickly, the act of releasing them was a pretty interesting way to get a point across about what the young people of Bosnia think of their political leaders. These games featured none other than current member of the Bosnian tri-presidency Bakir Izetbegović and the Bosnian businessman, party leader, and presidential hopeful Fahrudin Radončić. The word on the street was that Bakir himself was not too pleased about the game, and the fact the creator decided to remain anonymous is probably a little telling as to the risk that activism like this incurs in Bosnia.

Bakir i Prijatelji

Over the course of a few weeks with the help of some other talented individuals and mentors, I conjured up my own version of Bosnian political activism. Bakir i Prijatelji, or Bakir and Friends for you English speaking type folk, was born.

The aim of Bakir i Prijatelji is simple. Shoot your political enemies with your laser eyes, all the while making sure you do not hit political allies. It’s something that is universal among countries. Politics suck. Metaphors reign. And what better metaphor for Bosnian politics than the main players chasing each other down with their laser eyes.

Now obviously I am not Bosnian. I cannot vote in the Bosnian elections and have no right to tell any Bosnian who they should vote for in their election even if they would listen. I know how much Bosnian’s love it when western types come to their country for a few months and get to hear from them how they can make their country a better place. This was not my intention. I thought long and hard about developing a concept that worked along these principles.

The aim of creating Bakir i Prijatelji was to tap in to that brilliant political satire of El-Bake and Flappy Fahro. Political satire is universal and Bosnia is particularly ripe for it. It crosses borders and is shared among cultures. I hope that some people can get some respite from the elections by playing the game, or even just some laughs.

At the time of the elections Bakir i Prijatelji could be found at However it is currently down. But fret not, it will return!