Category Archives: Arduino

The Arduino Nano 33 BLE Sense Sensor Library You Have Been Waiting For

Quick Links

UPDATE 21/03/2023

Nano33BLESensor has a new release with version 1.1.0 now available. It solves some issues related to MbedOS and dependency version issues.

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.

Previously in The Hacky Super Loop Arduino Nano 33 BLE Sense Example You Have Been Waiting For I attempted to address the lack of meaningful working examples for this board. The interfaces for each sensor are not always ideal, and no concrete examples are widely available that enable uses to utilise Mbed OS to gather sensor values.

The ability to use Mbed OS with Arduino is a real step up for Arduino. Finally, a reasonably performant and relatively deterministic way of arranging our more complex Arduino projects! In attempt to simplify the collection of sensor data and at the same time utilise the power of Mbed OS, Nano33BLESensor was born.

The Nano33BLESensor Library

Nano33BLESensor leverages Mbed OS to automatically place sensor measurements in a ring buffer that can be integrated into programs in a simple manner. This means Nano33BLESensor takes care of placing measurements in to the buffer “in the background”, and your program can retrieve them from the buffer at a later time when your program has time. 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.

Nano33BLESensor Features

  • Class implementation with common interface for the following sensor measurements
    • 3-axis Accelerometer
    • 3-axis Gyroscope
    • 3-axis Magnetic
    • RMS Microphone
    • Barometric Pressure
    • Temperature (with humidity)
    • Proximity
    • RGBC Colour
    • Gesture
  • Mbed OS usage, allowing easy integration with programs.
  • Ring buffer usage, allowing the softening of time constraints in regard to the reading sensor measurements.
  • Excellent examples for all sensors designed for BLE and Serial Plotter that help you to get started.

In the end, the result of this is:

  • Super simple initialisation of on board sensors.
  • No code required beyond initialisation for collection of sensor data.
  • Super simple usage of sensor data.
  • Common interface among different sensors.
  • Using Mbed OS effectively makes the reading of sensor measurements happen “in the background”, and keeps it out of the main program loop.

Nano33BLESensor Examples

The Nano33BLESensor Library comes with a series of powerful examples that include sensor measurement data output using both Serial and Bluetooth. It is possible to view this data at the same time using Arduino’s Serial Plotter and a Bluetooth packet analysis tool such as Bluetooth LE Explorer. Some of the examples available on the GitHub repository are as follows:

Below are the results of a few of those examples.

Accelerometer Example

Gyroscope Example

Entire IMU Sensor Example

In order to view the data in a visually acceptable way, Bluetooth LE Explorer must be configured in a specific way. The below animation shows this setup.

How Nano33BLESensor Simplifies Sensor Usage

Here are a couple of examples of how Nano33BLESensor simplifies the collection of sensor data with the Nano 33 BLE Sense. For the full API, you can checkout the GitHub repository.

Initialising the on board accelerometer, reading data, and printing it.

Arduino_LSM9DS1

#include <Arduino_LSM9DS1.h>

float accelerometerX, accelerometerY, accelerometerZ;
void setup()
{
  IMU.begin()
}

void loop()
{
  if(IMU.accelerationAvailable())
  {
    IMU.readAcceleration(accelerometerX, accelerometerY, accelerometerZ);
    Serial.printf("%f,%f,%f\r\n", accelerometerX, accelerometerY, accelerometerZ);
  }
}

Nano33BLESensor

#include "Nano33BLEAccelerometer.h"

Nano33BLEAccelerometerData accelerometerData;
void setup()
{
  Accelerometer.begin()
}

void loop()
{ 
  if(Accelerometer.pop(accelerometerData))
  {
     Serial.printf("%f,%f,%f\r\n", accelerometerData.x, accelerometerData.y, accelerometerData.z);
  }
}

Initialising the on board colour sensor, reading data, and printing it.

Arduino_APDS9960

#include <Arduino_APDS9960.h>

int colourR, colourG, colourB, colourC;
void setup()
{
  APDS.setGestureSensitivity(50);
  APDS.begin();
  APDS.setLEDBoost(0);
}
void loop()
{
  if (APDS.colorAvailable())
  {
    APDS.readColor(colourR, colourG, colourB, colourC);
    Serial.printf("%d,%d,%d,%d\r\n", colourR, colourG, colourB, colourC);
  }
  delay(1000);
}

Nano33BLESensor

#include "Nano33BLEColour.h"

Nano33BLEColourData colourData;
void setup()
{
  Colour.begin()
}

void loop()
{ 
  if(Colour.pop(colourData))
  {
    Serial.printf( "%d,%d,%d,%d\r\n", colourData.r, colourData.g, colourData.b, colourData.c);
  }
}

Initialising the on board temperature sensor, reading data, and printing it

Arduino_HTS221

#include <Arduino_HTS221.h>

float temperature, humidity;
void setup()
{
  HTS.begin();
}
void loop()
{
  temperature = HTS.readTemperature();
  humidity = HTS.readHumidity();
  Serial.printf("%f, %f\r\n", temperature, humidity);
  delay(1000);
}

Arduino33BLESensor

#include "Nano33BLETemperature.h"

Nano33BLETemperatureData temperatureData;
void setup()
{
  Temperature.begin()
}

void loop()
{ 
  if(Temperature.pop(temperatureData))
  {
    Serial.printf("%f,%f\r\n", temperatureData.temperatureCelsius, temperatureData.humidity);
  }
}

Conclusion

Nano33BLESensor enables some interesting possibilities with the Nano 33 BLE. It simplifies the usage of onboard sensors by using a common interface, and leverages Mbed OS to allow the softening of time constraints in regard to the reading sensor measurements. It is hoped that this library will be useful to someone down the track!

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

Update: For even better examples of the non-hacky variety, check out the Nano33BLESensor Library in The Arduino Nano 33 BLE Sense Sensor Library You Have Been Waiting For.

Quick Links

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
Undefined
r/g/b light data
Undefined
proximity data
Undefined
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

Conclusion

The nano-33-sense-serial-example is a great way to visualise all of the onboard sensors on the Nano 33 BLE sense. Since writing this example, I have largely replicated 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. You can read about it in The Arduino Nano 33 BLE Sense Sensor Library You Have Been Waiting For.

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

Configuration

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 192.168.4.1 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 “192.168.4.1/supersecretpage” 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.

Conclusion

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

27/12/2022 UPDATE: I have finally managed to fix a few annoying bugs with this library and release a new version. Hopefully it continues to get some use out there!

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.

ESPFlash

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

SPIFFS

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

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

ESPFlash

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

SPIFFS

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;
SPIFFS.begin();  
file = SPIFFS.open("/charArrayExample", "w");
if(file)
{
  elementsSizeInBytes = sizeof(char)*sizeof(testData);
  bytesWritten = file.write((uint8_t*)testData, elementsSizeInBytes);
  if(bytesWritten == elementsSizeInBytes)
  {
    success = true;
  }
}
file.close();

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

ESPFlash

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

SPIFFS

File file;
uint32_t sizeInBytes = 0;
uint32_t sizeInElements = 0;
SPIFFS.begin();  
file = SPIFFS.open("/lengthExample", "r");
if(file)
{      
  sizeInBytes = file.size();
  sizeInElements = sizeInBytes/sizeof(double);
}
file.close();

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

ESPFlash

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

SPIFFS

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;
SPIFFS.begin();  
file = SPIFFS.open("/floatArrayExample", "r");
if(file)
{
  fileSizeInBytes = file.size();
  fileSizeInElements = fileSizeInBytes/sizeof(float);
  if(getArraySizeInElements <= fileSizeInElements)
  {
    firstElementIndex = fileSizeInBytes  - getArraySizeInBytes;
    file.seek(firstElementIndex, SeekSet);
    bytesRead = file.read((uint8_t*)testGet, getArraySizeInBytes);
    file.close();
    if(bytesRead == getArraySizeInBytes)
    {
      success = true;
    }
  }
}
file.close();

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

ESPFlash

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

SPIFFS

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

Conclusion

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("Hi!<br><br>");
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(_PAGEHEADER);
webpage.add_P(_CONTENT, "%CONTENT%", "TEST CONTENT");
webpage.add_P(_PAGEFOOTER);

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];
webpage.add_P(_PAGEHEADER);
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);
webpage.add_P(_PAGEFOOTER);

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));  
  webpage.add("Hi!");
  /* Send the webpage from SPIFFS where it is stored. */
  request->send(200, "text/html", buffer);
}
server.begin();

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.

Conclusion

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.

 

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!