The Hacky Super Loop Arduino Nano 33 BLE Sense Example You Have Been Waiting For

The Arduino Nano 33 BLE Sense was released in July 2019 and was a real step up for Arduino! Using the Arm Cortex-M4F based nRF52840, the Nano 33 BLE’s arrival made the days of Atmel based 8-bit microcontrollers seem numbered. With the proliferation of dirt cheap Arduino clones this was probably the result of Arduino seeing the writing on the wall that keeping it simple was probably not going to bring in the dough anymore. In the end the sheer amounts of fairly useless Arduino projects seem a bit dull these days, and with more complex offerings such as the Nano 33 series, a new era of seriously cool projects may be on the horizon.

A common complaint about the Nano 33 BLE Sense is the lack of working examples available for the board. Only a simple PDM Serial Plotter example exists when you install the board package, and this seems to have caused some confusion among users who were expecting an example to exist that uses all of the available on board sensors. In fact examples do exist for all the on board sensors, however they are available only on the individual sensor library repositories.

Below is a table including each sensor, it’s component name, a brief description, and a link to the example code.

SensorNameDescriptionExample Code Link
IMU LSM9DS1 3 acceleration channels, 3 angular rate channels, 3 magnetic field channels Arduino_LSM9DS1
Microphone MP34DT05PDM omnidirectional digital microphonePDM
IR APDS9960  Gesture, light, proximityArduino_APDS9960
Barometric Pressure LPS22HB  Barometric pressureArduino_LPS22HB
Temperature/Humidity HTS221  Temperature/Humidity Arduino_HTS221

Let’s Be Honest About What We Really Wanted

We wanted a super loop that would read all the values from the sensors and print them on the serial monitor/plotter. We wanted to be able to buy this board, fire it up, and to be able to look cool to all our friends immediately. We didn’t want to have to think. In fact we didn’t want to have to do anything. It did not matter that the actual values would probably be useless, we just wanted it to be there.

Perhaps the reason this super loop example we want is so terrible is because of the fact that the Nano 33 BLE Sense can utilise Mbed OS. Finally, a reasonably performant and relatively deterministic way of arranging our more complex Arduino projects! We can finally bid farewell to the almighty super loop!

Alas, I understand the RTOS can be a new and scary venture for some. And having just got my Nano 33 BLE sense, I decided to create a simple example program that can display all the available sensor data on serial plotter to check with the sensors are at least powered on and outputting semi-meaningful data without any of the BLE functionality.

The Example Project

The repository for nano-33-sense-serial-example can be found here. The data itself might be fairly useless for most applications, as it is mostly raw digital values pulled straight from the sensors which need to be converted to useful metrics before being meaningful. It plots the following raw data:

  • x/y/z acceleration data
  • x/y/z gyroscope data
  • x/y/z magnetic data
  • RMS microphone data
  • left/right/up/down gesture data
  • r/g/b light data
  • proximity data
  • Barometric pressure data
  • Temperature/Humidity data

Some of the difficulty in displaying this data in a coherent way is the different sampling frequencies in which sensor data is obtained. The table below shows these sampling frequencies.

Data TypeSampling Frequency
x/y/z acceleration data 109Hz
x/y/z gyroscope data 109Hz
x/y/z magnetic data 20Hz
16mS RMS microphone data 62.5Hz
left/right/up/down gesture data
r/g/b light data
proximity data
Barometric pressure data
On request (1Hz in example)
Temperature/Humidity data On request (1Hz in example)

Because of this, all data is plotted with a frequency of 20Hz in an attempt to display the data in a way where the values will somewhat correlate to each other. There are some simple macro based configuration options available to allow some control over what data is actually outputted.

What the Output Looks Like

All Sensors

IMU Sensor

Gesture/Light/Proximity Sensor

Barometric Pressure Sensor

RMS Microphone Output

Temperature/Humidity Sensor


The nano-33-sense-serial-example is a great way to visualise all of the onboard sensors on the Nano 33 BLE sense. In the future I hope to recreate this project using Mbed OS in an effort to create a simple, low power alternative that can be used as the base for many projects that use the Nano 33 BLE sense.

ESPCaptiveImagePortal: A Captive Portal That Displays Images

I hate the internet. I hate it not only because it shows us the decay of society in real-time, but also because I do not really understand it. And who can blame me? Technologically it is one giant bowl of spaghetti, and as an idiosyncratic wannabe iconoclast it is even more difficult for me to comprehend on a social level. So naturally when COVID19 hit Europe like a tonne of bricks and the internet immediately imploded I channeled this hatred hard. Now hold your horses, I am not dishing out this pseudo philosophical claptrap in a failed attempt to be topical. This has a point. Just let me get to it…

A friends birthday was coming up, and I came up with a concept for a gift that attempts to satirise not only the way people use the internet to dish out their unqualified opinion, but also the shallow way in which people deliver that opinion.

The Concept

The concept was to have a device create a WiFi access point called “CORONA VIRUS CURE INFORMATION”, and once a user connects to the access point a captive portal would automatically serve a web page that only displays a GIF telling the user to “go home”. Something a little like this, featuring yours truly.

Obviously this kind of concept could be refined to be a little more usable to the general population who are not as bitter as myself. Maybe a “CAT OF THE DAY” web portal that displays pictures of the household cats? Yes. That sounds much more palatable. Or how about including a configuration page where the user could name the access point whatever they like, and an upload page so custom images could be displayed by the captive portal? I can see it now, looking for my local public WiFi Hotspot and being inundated with “5G KILLS BABIES”, “BILL GATES KILLS BABIES”, and “LOCKDOWN KILLS BABIES”. Yes. This is it. This is what I wanted.

And so the concept for the ESPCaptiveImagePortal was born.

The Specifications

After some musing I came up with the following requirements for ESPCaptiveImagePortal:

  • Implement an WiFi access point with a web server.
  • Implement a captive portal that redirects most traffic to a web page that displays a simple image. This page should be able to display different images each time it is loaded if more than one image is available. It should also be able to display a wide range of image formats, including animated images.
  • Implement a configuration page allowing the user to upload images, delete images, and change the access point SSID. This page should have a hard coded username and password for basic authentication.
  • Implement using the ESP8266.

The ESPCaptiveImagePortal Project

The ESPCaptiveImagePortal project can be found on GitHub here. In addition to the ESP8266 arduino core it requires a few Arduino libraries to compile. This includes ESPAsyncTCP, ESPAsyncWebServer, DNSServer, ESPStringTemplate, and ESPFlash. Most of these libraries will be able to be installed using the Arduino IDE through Library Manager, but if you are having trouble, they can also be installed by downloading the code off github directly and installing them manually.

A Working Example

Here is an example of how the ESPCaptiveImagePortal works using the CAT OF THE DAY example I mentioned a little earlier.

CAT OF THE DAY example


Obviously we don’t want just anyone who has access to the access point to be able to upload images, so ESPCaptiveImagePortal relies on three forms of security:

  1. The connected user knows the ESP8266 IP address.
  2. The connected user knows the configuration page URI (/supersecretpage by default)
  3. The connected user knows the hardcoded username and password.

It’s important to note the username and password is implemented using basic HTTP authentication which is incredibly weak, and allows anyone sniffing the network to grab the credentials in plain text. Obviously from a security point of view this is not ideal, but I considered it sufficient for such a project.

To access the configuration page, you have to know the IP address of the ESP8266, which is hardcoded to by default. The URI for the configuration page is also hardcoded to “/supersecretpage” by default. So if those defaults are used, it can be accessed by using any browser with “” in the address bar.

The authentication that allows access ends up looking a bit like this. Default values are hardcoded in the project that can be changed very easily.

The below image shows the configuration page. It displays the total number of WiFi connections that have been made to the device as well as the following configuration options:

  • Ability to delete uploaded images
  • Ability to upload new images
  • Ability to change WiFi SSID

The below animation shows a sped up example from start to finish of the ESPCaptiveImagePortal configuration, including getting to the configuration page, uploading an image, changing the SSID, and observing the result all through a browser on a smartphone.

A Note On Image Upload Size and Speed

One last final note is that image upload speed is slow due to the use of internal flash memory (SPIFFS) on the ESP8266. The available space on the filesystem in which images are stored is also very constrained, although this will differ depending on the ESP8266 module that is used. It is highly recommended that the image size does not exceed 500Kb in size. If the image is a non-animated image, an image size of ~100Kb is recommended, which results in a negligible upload and download time while still rendering useful results.


It’s hoped that someone will get a kick out of this project. I had a lot of fun developing it, and learnt a lot about the ESP8266 on the way. I will follow up this post with a technical post that will discuss how I achieved all of the specified features, some thoughts on the ESP8266, and what I would do differently in the future, so watch this space!

ESPFlash: An Arduino Library for Storing Data in the ESP Filesystem

SPIFFS (or SPI Flash File System) is very cool. It is an Open Source Library intended for SPI NOR flash devices on embedded targets. Embedded targets like the ESP8266 and ESP32, which depending on the model can have upward of 3 megabytes of NOR Flash storage available. The cool thing about SPIFFS is that it makes using this flash storage more intuitive with a simple filesystem type interface where you do not have to think about the various intricacies involved.

This being said, it only reduces the complexity to a certain extent. Anyone who has spent some time using the library would have inevitably lost time with simple problems such as keeping filenames less than 32 characters in length, casting data to confine to the 8 bit nature of saving data to NOR Flash memory, and developing different SPIFFS handling functions for different kinds of arrayed data that you want to save.

It seems like a classic use case where generic programming with templates could reduce the complexity of SPIFFS usage by removing the need to constantly cast data types and provide the size of said data to store it in SPIFFS. After making this observation I was surprised to learn that no Arduino library existed that simplified SPIFFS usage, and thus the idea for ESPFlash was born.

The ESPFlash Library

ESPFlash is an abstraction layer that simplifies the storing of vectorised data in the filesystem on the ESP8266 and ESP32. It was created to make SPIFFS usage simple and easier to understand. It can be found on GitHub here. It can also be found using Arduino’s Library Manager, and available when searched for when using the Arduino IDE. Simple examples also exist to help get people started.

ESPFlash Specification

After some consideration I came up with simple specification that ESPFlash should fulfill. The specification requirements include:

  • Simple template based interface to store and retrieve generic vectorised data in flash memory using SPIFFS.
  • Automatically start SPIFFS if it has not already been started.
  • Automatically truncate filenames that are over 32 characters in length.
  • Keep running count of the number of “elements” stored in a file.
  • Ability to overwrite elements.
  • Ability to append elements.
  • Ability to get single elements.
  • Ability to get a multiple number of elements.
  • Ability to clear elements.
  • Ability to add elements that are stored in flash with PROGMEM.

In addition to this, I wanted to develop two extra modules to further simplify to common use cases. The purpose of these modules are the following:

  • Simple SPIFFS based integer counter
  • Simple SPIFFS based string storage

How ESPFlash Simplifies SPIFFS Usage

Here are a couple of examples of how ESPFlash simplifies SPIFFS usage. It does not show the full functionality of ESPFlash. For the full API, you can checkout the GitHub repository.

Creating a file with a filename of “/intExample” and storing a single integer in the file with error checking.


int testData = 10;
ESPFlash<int> intExample("/intExample")
bool success = intExample.set(10);


int testData = 10;
bool success = false; 
uint32_t bytesWritten = 0;
File file;
file ="/intExample", "w");
  int* testPointer = &testData;
  bytesWritten = file.write((uint8_t*)testPointer, sizeof(testData));
  if(bytesWritten == sizeof(int))
    success = true;

Creating a file with a filename of “/charArrayExample” and store 10 chars in the file with error checking.


char testData[10] = {'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j'};
ESPFlash<char> charExample("/charArrayExample");
bool success = charExample.setElements(testData, sizeof(testData));


char testData[10] = {'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j'};
bool success = false; 
uint32_t bytesWritten = 0;
File file;
uint32_t elementsSizeInBytes = 0;
file ="/charArrayExample", "w");
  elementsSizeInBytes = sizeof(char)*sizeof(testData);
  bytesWritten = file.write((uint8_t*)testData, elementsSizeInBytes);
  if(bytesWritten == elementsSizeInBytes)
    success = true;

Open a file with a filename of “/lengthExample” and get the number of elements stored in the file with error checking.


ESPFlash<double> lengthExample("/lengthExample");
uint32_t numberOfElements = lengthExample.length();


File file;
uint32_t sizeInBytes = 0;
uint32_t sizeInElements = 0;
file ="/lengthExample", "r");
  sizeInBytes = file.size();
  sizeInElements = sizeInBytes/sizeof(double);

Open a file with a filename of “/floatArrayExample” and get the last 5 float elements stored in the file with error checking.


float testGet[5];
ESPFlash<float> floatExample("/floatArrayExample");
bool success = floatExample.getBackElements(testGet, sizeof(testGet));


float testGet[5];
File file;
uint32_t fileSizeInBytes = 0;
uint32_t fileSizeInElements = 0;
uint32_t firstElementIndex = 0;
uint32_t bytesRead = 0;
uint32_t getArraySizeInElements = sizeof(testGet);
uint32_t getArraySizeInBytes = sizeof(float)*sizeof(testGet);
bool success = false;
file ="/floatArrayExample", "r");
  fileSizeInBytes = file.size();
  fileSizeInElements = fileSizeInBytes/sizeof(float);
  if(getArraySizeInElements <= fileSizeInElements)
    firstElementIndex = fileSizeInBytes  - getArraySizeInBytes;, SeekSet);
    bytesRead =*)testGet, getArraySizeInBytes);
    if(bytesRead == getArraySizeInBytes)
      success = true;

Truncate a filename in excess of 32 characters so it can be used with SPIFFS.


/* Filenames are automatically truncated if in excess of 32 characters */
/* The file extension is preserved */
ESPFlash<float> floatExample("/thisFilenameIsLargerThan32Characters.txt");


const char* filename = "/thisFilenameIsLargerThan32Characters.txt";
char filenameBuffer[32];
if(strlen(fileName) < 32)
  strcpy(filenameBuffer, fileName);
  strncpy(this->fileName, fileName, 27);
  char* pch = strrchr(fileName, '.');
  strcpy(filenameBuffer+27, pch);


ESPFlash is far simpler than using the SPIFFS library directly. It also reduces code footprint, and makes SPIFFS error detection easy. It is hoped that this library will be useful to someone down the track!

ESPStringTemplate: An Arduino Library for Building Web Pages

I recently began a project where I needed to build some dead simple, HTML only static web pages during runtime with the ESP8266 to represent data stored on the filesystem. Depending on the number of files located on the filesystem various buttons, forms, and text needed to be generated. In addition I needed some templating capability to replace certain “tokens” located in the web page with other substrings. Projects with similar functionality exist usually number the name of FSBrowser.

Naturally with the popularity of the ESP8266 and Arduino, some libraries that do a pretty good job of this already exist. They are:

  • The ESPAsyncWebServer contains a simple templating engine in addition to it’s web server capability. It works by “extracting placeholder names from response text and passing it to user provided function which should return actual value to be used instead of placeholder”.
  • PageBuilder is a “HTML assembly aid” that provides a way to combine “PageElements” to a build a web page which can be stored in SPIFFS. It provides templating capability by allowing “tokens” to be tied to template handling functions. It can also be bound to a web server.
  • ESPTemplateProcessor is a templating library that reads a file from SPIFFS, processes the read file with a template handling function, then sends the result to a bound web server.
  • EspHtmlTemplateProcessor is based off ESPTemplateProcessor, although it has a few extra features.

While I certainly could have managed by using one of these libraries, I soon found the implementation resulting from their usage to be difficult to read and not very flexible. I found myself having to develop upwards of ten templating handler functions to replace tokens in a very small amount of generated HTML code. I also found the libraries that bound to web servers to be restrictive in the web server based libraries that could be used.

So with these observations I made the decision to make a dead simple string templating library that would fill the niche of my application.

ESPStringTemplate Requirements

The requirements for the ESPStringTemplate library are:

  • Ability to build web pages using string “elements”.
  • Web pages should be stored in statically allocated buffers, where elements can be added to them.
  • String elements should be able to be stored in both RAM and program flash memory (PROGMEM).
  • Templating ability on string elements using simple string literals (instead of handler functions).
  • Multiple token templating ability on string elements (without the use of handler functions).

The ESPStringTemplate Library

The ESPStringTemplate Library can be found on GitHub here. It is also a part of Arduino’s Library Manager, and can be found using the Arduino IDE when it is searched for. The GitHub README gives a good outline of the usage of the library. Simple examples also exist to help get people started. I hope this library can be useful for someone else down the track!

Just as a note, there is actually nothing stopping the use of ESPStringTemplate on any microcontroller!

ESPStringTemplate Examples

These examples are taken straight from the ESPStringTemplate GitHub page, but are also included here.

Simple example – Using string literals to build a page in a statically allocated buffer.

static char buffer[200];
ESPStringTemplate webpage(buffer, sizeof(buffer));
webpage.add("This is an example of the ESPStringTemplate Library.<br><br>");
webpage.add("These strings are stored in RAM, and are added to the provided statically allocated buffer.<br><br>");

Using string literals stored in flash (program memory) to build a web page.

static char buffer[200];
ESPStringTemplate webpage(buffer, sizeof(buffer));
webpage.add_P(PSTR("This is an example of the ESPStringTemplate Library.<br><br>");
webpage.add_P(PSTR("This string is stored in flash using PROGMEM, and are added to the provided statically allocated buffer."));

Using reusable HTML elements with a simple token replacement.

static const char _PAGEHEADER[] PROGMEM = "<html><body>";
static const char _CONTENT[]    PROGMEM = "%CONTENT%";
static const char _PAGEFOOTER[] PROGMEM = "</body></html>";

static char buffer[200];
ESPStringTemplate webpage(buffer, sizeof(buffer));
webpage.add_P(_CONTENT, "%CONTENT%", "TEST CONTENT");

Using reusable HTML elements with a multiple token replacement.

static const char _PAGEHEADER[] PROGMEM = "<html><body>";
static const char _CONTENT[]   PROGMEM = "%CONTENTA% and %CONTENTB% and %CONTENTC%";
static const char _PAGEFOOTER[] PROGMEM = "</body></html>";

static char buffer[200];
ESPStringTemplate webpage(buffer, sizeof(buffer));
TokenStringPair pair[3];
pair[0].setPair("%CONTENTA%", "Replacing this token");
pair[1].setPair("%CONTENTB%", "this token");
pair[2].setPair("%CONTENTC%", "this last token as well...");
webpage.add_P(_CONTENT, pair, 3);

Using ESPAsyncWebServer to serve created webpage

static char buffer[200];
WiFi.softAP("ESPStringTemplate Example");

AsyncWebServer server(80);
server.on("/", HTTP_GET, [](AsyncWebServerRequest *request)
  ESPStringTemplate webpage(buffer, sizeof(buffer));  
  /* Send the webpage from SPIFFS where it is stored. */
  request->send(200, "text/html", buffer);

Moving DaleGi in a Slightly New Direction

How time flies!

It has been almost two years now since said “hello world” to the world, and I have had a nice time writing what I have managed to write on the blog! In this time there have almost been 3000 visitors to the site, and that has been just about enough for me to have the motivation to occasionally post about different things. Without a doubt the most popular posts have been about Bosnian Bureaucratic Wonders, however there is also a lot of interest in my post about the PMSA003 pollution sensor, as well as the Parametric Digital Transducer Loudspeaker. It has been a good creative outlet for me as someone who likes to write, but does not get much of a chance to write anything but code these days!

I have noticed lately I have struggled to find the time and motivation to write which might be due to the style I have tried to keep on the blog. This was one of a resource of information, and a portfolio for myself. I have also noticed a lack of motivation to start new personal projects outside of my day job, which really is a shame!

So with this in mind, I have decided to change things up a bit. From here on out I will try to write more in the style of articles belonging to a series. The series might be for a specific project, or maybe a topic in general. I find that this helps to motivate me not only finish projects, but also write more. I am also going to loosen up a bit with the article content and provide content more in the vein of a thought process, discussion, with the occasional bad joke.

So with this being said, here is to moving in slightly different directions!

Setup Guide for SEGGER J-Link and SystemView with STM32 Nucleo Boards

SEGGER SystemView is a very cool graphical tool for embedded systems that enables the visualisation of run-time behaviour in an application by the recording on configurable events. These events can be recorded using J-Link, IP, or UART communication. A huge plus for using SystemView is that it is totally free to use, provided that in one event recording session you do not exceed one million recorded events. This limit is actually very easy to exceed in larger applications, but still renders the free version of the software very useful.

I recently setup SystemView to work with a STM32 Nucleo based development board to debug the behaviour of FreeRTOS in a visual manner. In this setup I was also using System Workbench for STM32 with SEGGER J-Link debugging. This particular setup was pretty neat because it provided multiple methods for debugging the system, and was entirely free. The STM32 Nucleo and Discovery boards are very well suited for this use case as they contain an on-board ST-LINK programmer/debugger, and SEGGER provide a free way to convert the ST-LINK module to a J-Link module.

The entire setup was a little protracted so I kept notes on everything I did to get everything work. It is these notes that I will share in this post. It is not meant to be an exhaustive guide and will not provide any kind of in depth information about how SystemView works, but is provided here in the hope that it may save someone else time somewhere down the track.

It is assumed that you already have System Workbench for STM32 installed. Beyond that, I completed each tasks in the following order:

  1. Converting ST-LINK into J-Link
  2. GNU MCU Eclipse install
  3. SEGGER J-Link Install
  4. J-Link debug configuration setup in System Workbench
  5. SystemView Install
  6. Adding SystemView Module to System Workbench project

Converting ST-LINK into J-Link

Instructions are here.

  • Install ST-LINK USB drivers (should already be done): Download
  • Install J-Link software package V5.12b or later : Download
  • Install SEGGER STLinkReflash utility: Download
  • Start the STLinkReflash utility (STLinkReflash.exe)
    • Agree to the license terms (enter “A”)
    • Connect ST-LINK on-board to PC 
    • Select “Upgrade to J-Link” (Enter “1”)
    • Wait for operation to complete

GNU MCU Eclipse Install

Open System Workbench for STM32 (Eclipse) and do the following:

  • Open Eclipse Marketplace
  • Search for GNU MCU Eclipse and install
  • Confirm all features
  • Agree to the license terms
  • Wait for operation to complete
  • Restart Eclipse

SEGGER J-Link Install

Instructions are here.

  • Install J-Link: Download
  • Test install with connected converted J-Link board by running JLinkGDBServerCL with CMD. On my system this is located at “C:\Program Files (x86)\SEGGER\JLink\JLinkGDBServerCL.exe”. 
    • Accept the terms of use as they pop up.
    • Select the correct target device. For me it is STM32F429ZI. This will differ depending on the development board you are using.

J-Link Debug Configuration Setup in System Workbench

Instructions are here.

  • Define the path in Eclipse for J-Link folder. Window→Preferences→MCU→Global SEGGER J-Link Path
    • Create new J-Link Debug Configuration (Run→Debug Configurations→GDB SEGGER J-Link Debugging)
    • On Debugger tab add Device name (see Supported Device names for precise names). For my project it is STM32F429ZI. This will differ depending on the development board you are using.
    • On Startup tab add CPU freq and SWO freq (must be a sub-multiple of 6Mhz). On my board CPU freq is 180Mhz
    • On Common tab, change the Save as option to Shared file.
    • Add {cross_prefix} and {cross_suffix} build variables (Window→Preferences→C/C++/Build Variables)
      • cross_prefix=”arm-none-eabi-
      • cross_suffix=””
      • These may already exist, if they do not, do not added them again.

SystemView Install

  • Download installer: Download
  • Follow the prompts and install

Adding SystemView Module to System Workbench project

  • Add the SystemView module to the project (it is architecture independent). It can be found in C:\Program Files (x86)\SEGGER\SystemView_V252d on my system. It includes the following files:
    • SEGGER
      • SEGGER.h
      • SEGGER_RTT.h
      • SEGGER_SYSVIEW_ConfDefaults.h
      • SEGGER_SYSVIEW_Int.h
      • SEGGER_RTT.c
    • Config
      • Global.h
      • SEGGER_RTT_Conf.h
      • SEGGER_SYSVIEW_Conf.h
  • Inside main() function (or other startup function) add the SEGGER_SYSVIEW_Conf() initialisation function. 


If all is well, everything is ready to start debugging with J-Link, SystemView and System Workbench for STM32.


How to Live and Work in Bosnia and Herzegovina

So you want to live and work in Bosnia and Herzegovina? Great! You just spent your the summer in Sarajevo, you became a regular at Kino Bosna, gained 5 kilograms from eating Krompiršua and Ćevapi every meal, and developed an ironic attachment to turbo folk from long nights at Sloga. “Sarajevo is the new Berlin” you declare! You decide you will teach English, sell bracelets on Ferhadija, and push handmade cigarettes in Stup to make ends meet in order to fulfill your bohemian lifestyle. Armed with your new life plan, you only need to find a way to become legal. Well, buckle up. Because I do not have to be your mother to tell you “Okay honey, let me know when you run out of money and want me to buy your flight home”.

But I digress.

Now that you know your place, I will briefly delve into why this is probably not going to happen. But if you do persist, this post hopes to explain some of the options available that will allow you to live in Bosnia for an extended period of time and the process of obtaining a Work Permit in the event that you would like to work here. I will also share some interesting statistics on the demographics of those with Work Permits and some personal insights as someone who managed to successfully navigate the process for becoming a foreigner who lives and works in BiH legally.

Due to the complexity of living and working in BiH as a foreigner, this post will be more concise than my two previous posts on Bosnian Bureaucratic Wonders, How to Get a White Card in Bosnia and Herzegovina, and How to Get a Volunteer Visa in Bosnia and Herzegovina. It is also designed to give a general overview on the process of obtaining a Work Permit in BiH and provide a variety of links and resources to set you in the right direction.

How Do I legally Live in Bosnia and Herzegovina?

The BiH Service for Foreigner’s Affairs (SPS) website provides a good outline on the different types of visas and temporary residence permits available to foreigners in English. The BiH Ministry of Security (MSB) also provide basic information on the entry and stay of aliens in BiH on their website.

For nationals included in the Visa-free regime, it is possible to reside in BiH for 90 days out of every 180 days. You cannot legally volunteer or work while in BiH as a part of the Visa-free regime. To legally reside in BiH longer than the Visa-Free regime allows for, it is necessary to obtain either a temporary residence permit, or a long stay visa (visa D).

Temporary Residence Permit

A temporary residence permit is usually valid for a period no longer than 12 months, and allows an individual to stay in BiH for the validity period. A brief outline regurgitated from the SPS website on the grounds for granting temporary residence is as follows:

  • Marriage to a citizen of Bosnia and Herzegovina.
  • Extramarital community (Common Law Marriage) with a citizen Bosnia and Herzegovina
  • Family reunification
  • Education (including volunteering)
  • Employment as specified in an issued work permit
  • Work without a work permit
  • Treatment or rehabilitation
  • Stay in a nursing home
  • Stay for humanitarian reasons
  • Stay based on an international treaty to which Bosnia and Herzegovina is a party
  • Stay out of other legitimate reasons
  • Ownership of real estate in Bosnia and Herzegovina

The SPS website provides information regarding the required documents for an application in all of the above circumstances.

Long Stay Visa (Visa D)

A Long Stay Visa, or “Visa D”, is usually valid for a period of 180 days starting from the date of first entry into BiH. Information about the Long Stay Visa can be found on the BiH MSB website.  In general, the Long Stay Visa is issued to individuals who can prove that there is a valid purpose for an individual to stay in BiH a period of more than 90 days within a 6 month period.  The application for this kind of visa is usually based on a “letter of invitation” from a Bosnian citizen or organisation.

How Do I Legally Work in Bosnia and Herzegovina?

To legally work in BiH, usually you must a obtain a Work Permit.  Work Permits can be valid for a maximum of 12 months after being issued, and must be renewed after this period. They are usually obtained on the basis of receiving a job offer from a company registered in BiH.

In some exceptional cases, individuals can obtain a Temporary Residence Grounded on Work Without a Work Permit. This allows an individual to work in BiH without a Work Permit. One of these exceptional cases is being the founder of a company in BiH. You can find out if you qualify for this type of temporary residence by visiting the BiH SPS website here or reading Article 50 through 71 of the Rulebook on Entry and Stay of Aliens.

Who Has Work Permits in Bosnia and Herzegovina?

A comprehensive migration profile report was released by the Ministry of Security (MSB)  for 2016/2017 period detailing various demographic data on issued Work Permits in BiH.

The demographic data pulled from this report displays an odd situation in regard to who typically obtains Work Permits in BiH in regard to industry, age, and qualification level. Around 2500 Work Permits were issued in 2017. The majority of Work Permits in BiH are issued to citizens of Serbia, Turkey, Croatia, and China. The overwhelming majority of issued Work Permits are issued to men. Roughly half of those who receive work permits have a university level qualification. Most people who receive work permits are over 60 years old, and are commonly issued for those who work in the Wholesale/Retail, Vehicle Repair, Processing, Real Estate, Education, and Construction industries.

How Do I Obtain a Work Permit and Temporary Residence on the basis of a Job Offer?

The Foreign Investment Promotional Agency (FIPA) of BiH provide a nice guide on how to obtain Work Permits in BiH. Information on the required documentation for the Temporary Residence Grounded on Work With a Work Permit can be found on the PB-4.1 document listed on the SPS website. A brief overview of the process can also be found in the Frequently Asked Questions section of the SPS website in BHS. The following steps are outlined in these sources:

  1. Receive a job offer from a BiH company.
  2.  Work Permit application is then submitted by the future employer on behalf of the employee to the relevant government employment agency. The employee will be required to provide certified identity documents as well as a nostrification of their university degree if applicable, while the employer will have to provide registration documents as well as proof they do not have any outstanding tax obligations. The employee should be located outside of BiH while the Work Permit application is processing.
  3. Once the Work Permit is obtained, the employee may enter BiH either using their 90 day visa-waiver period (or other applicable short-stay visas) and apply for Temporary Residence Grounded on Work With a Work PermitThe employee may reside in BiH while the Temporary Residence Grounded on Work With a Work Permit application is processing.
  4. Once the Temporary Residence Grounded on Work With a Work Permit application has been processed, the employee may start working.

This entire process typically takes 3 months or more. It is recommended that if the employer does not take care of the process, the employee should hire a local lawyer. In my experience, the whole process costs around 400KM in government administrative fees, and 600KM in lawyer fees when applying in the Kanton Sarajevo.


It is hoped that this post has cleared a few things up and saved time for those thinking about living and working in BiH as a foreigner. While it may have dashed the hopes of those wishing to stave off their early life crisis by becoming professional bracelet and cigarette pushers, it is possible to navigate the visa process and do things legally in BiH when you put your mind to it. Navigating the Bosnian bureaucracy as a foreigner in practice can be stressful and frustrating, and it is recommended to hire a local lawyer when trying to apply for the various visas and permits by yourself.

Photo by @edina.sp

Useful Links


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.