Hello, fearsome hackers and makers ! Welcome to the MCUnity project. This is the first full-scale technology mashup on Nefastor Online. Today I’m mixing Unity programming and microcontrollers, starting with the ESP8266. The result is a development tool you can use to quickly create GUI’s that let you interact with your microcontroller code from your smartphone, tablet or PC, over WiFi. How cool is that ? You have no idea yet, but you’re about to find out.
In case you’re wondering, microcontrollers are often referred to as MCU’s (MicroController Units) hence the project’s name. It also sounds like a cool stage name. I can totally picture Jay-Z going “yo, what up guys, make some noise, MC Unity is in da mother-effing house !!!”
I first wanted to call it “ESPinterface” (damn, I’m good with words) but then I realized there was no point in restricting this project to just the ESP8266. Thus I’ve designed it to be compatible with any 32-bit MCU that has a LAN interface. WiFi or Ethernet, it doesn’t matter as long as your PC or smart device can connect to it.
For this series of articles I will be showing you how to use MCUnity as part of firmware development for the ESP8266. That’s because I love this chip, and because it’s so cheap you have no excuse not to try it. Nevertheless, you are free to port the ESP8266 MCUnity library to other device families as long as you share your code with me. I’ll know if you don’t.
First, let’s take MCUnity for a spin
This is a fairly complex project about a tool that helps you do fairly complex things. I guess it’s best to give you a taste first, hook you, then jam tons of technical information and wizardry into your moist, magnificent brains.
We’re the YouTube generation, so I fully intend to add a video of MCUnity in action at some point. I have the technology. Unfortunately that technology is currently in cardboard boxes as I’m moving to a new house. For now you’ll have to make do with screenshots and, of course, with running a demonstration yourself. Takes longer, but it feels better, just like good sex. I said sex. Now you’re compelled to read on despite the lack of video. Mwah ah ah !
To replicate this demo at home, you’ll need an ESP8266 module such as the WeMos D1 Mini. You’ll also need a Windows PC and, optionally, an Android device.
You’ll need to do two things :
- Build and flash the MCUnity demo firmware into your ESP8266 module.
- Build or install, and then run, the MCUnity application on your PC or Android device.
Let’s be about it !
Flashing the firmware
If you’re new to Nefastor Online and/or ESP8266 firmware development, set aside an hour or two : you’ve got quite a few steps to go through. Just rest assured that in the end, it all works as it’s supposed to and the hero gets the girl. If you’re already an ESP8266 badass, you’ll know which parts to skip.
Follow the instructions in this article to install ESP8266 development tools. You’ll need to be able to recompile the demo firmware in order to embed your WiFi network’s name and password in it. The ESP8266 obviously can’t guess those, that would be cracking, very likely illegal and I don’t condone anything that could land you in jail.
Open the location where you installed the ESP8266 Unofficial SDK. Under “ESP8266_RTOS_SDK\include”, create a header file named “credentials.h” to hold your WiFi credentials. The contents are very short :
#ifndef _WIFI_CREDENTIALS_ #define _WIFI_CREDENTIALS_ // Everything an ESP8266 needs to connect to your WiFi #define WIFI_SSID "Your network's name" #define WIFI_PASS "Your network's encryption key" #endif // _WIFI_CREDENTIALS_
Now follow the instructions in this other article to give your development tools access to my online Git repository of ESP8266 template projects and driver libraries. On its own, well worth the trouble, I assure you.
Launch Eclipse and check-out the “MCUnity” branch of ESP8266 repository. If necessary, edit the makefile to match the COM port Windows allocated to your ESP8266 module. Now make the “Flash” target.
Building the app
First off, let me make this clear : you don’t need to. MCUnity assumes your priority is developing MCU firmware, which is why this project’s name places Unity after MCU. I don’t expect you to learn how to program Unity applications. I’ve designed MCUnity so that any customization to fit the code you are working on is done entirely firmware-side.
This leaves you with two options regarding the application : you can either grab an executable version, or you get the source code and build it yourself. What would Stallman do ?
For the second option, follow the instructions in this article, then read the rest of this section.
The MCUnity source code, along with the most recent executable builds, is available to you as a Git repo, which you’ll find right over there :
Clone this repository onto your hard drive. If you have installed Unity, launch it and open the project. You can now hit the “play” button and the MCUnity application will run. You may want to “maximize on play”. And of course you can also build the application.
If you do not have Unity on your computer, then you need to launch the executable file “MCUnity.exe”. I won’t judge.
Now let the fun begin !
Power-on your ESP8266 module (the one with the MCUnity demo firmware in Flash, obviously). It will connect to your WiFi network and wait for the application to start and advertise its presence.
Now run the application’s executable. You’ll be greeted by the Unity Player setup dialog :
This is what Unity gives programmers who don’t have time (yet) to program a pretty in-app setup menu. I’ll get around to it eventually but that’s obviously not a priority.
I recommend you select a resolution of 1440 x 900 and tick “Windowed” so you can easily switch between MCUnity and your firmware development tools.
Now hit “Play“.
The app and the ESP8266 will find each other within a second, and you’ll see this :
But you could also see this sad, empty GUI :
That’s what you’ll get if your ESP8266 isn’t running at the time you launch the application. That’s not a problem : simply, no ESP8266 has yet told the application what GUI it should create. You can remedy that in two ways :
- From the application, hit the only button in sight, which I cleverly labeled “Setup“. Unless your ESP8266 is really dead or has failed to connect to your WiFi network, the application will send it a packet to request it setup its GUI. Which it will do.
- Or you can reset the ESP8266 itself. Power-cycle or reset button, doesn’t matter as long as it forces your firmware to initialize itself again.
Whatever you do, you’ll end-up with a serviceable GUI.
What it do ?
The demo firmware in your ESP8266 sets-up a remote GUI through the network, courtesy of the MCUnity app. The demo shows two things you can currently do with MCUnity :
- You can mess with global integer variables of your firmware, while it is running. You can read and set their value as with a good old JTAG-based debugger. Except it’s over WiFi and you can do it with your smartphone.
- You can call functions of your firmware. Those can be functions you write specifically to test something using MCUnity.
Try it. The integer variables can be set to new values using the text entry field next to their “Set” button. These entry field keep their value, which is useful if you need to reset a variable later on.
The “Increment” button calls a function on the ESP8266 that increments the third global variable.
The “LED Toggle” button calls another function that controls GPIO on the ESP8266 to, well, toggle the module’s blue LED on and off.
GUI customization and disclaimer
The application divides the screen into 256 cells that you can use to define up to 256 GUI controls, which I call “tiles”. Tiles can have different sizes and be placed anywhere on the display’s grid of 16 x 16 cells.
In the demo firmware, I set six tiles of 2 x 2 cells each. Look at the firmware’s “user_main.c” source file and you should quickly find where that bit of magic happens. I’m counting on you to try and see what happens if you change the tiles’ sizes and positions.
Here’s the thing, though : MCUnity is not at all intended for creating GUI’s for a finished product. Oh hell no ! It’s only designed to let you interact with your firmware as comfortably as possible during your development phase. That means it places the priority on low overhead, as opposed to reliability. The library won’t check your GUI layout before passing it on to the app, which means it’s up to you to be careful. You can very well create overlapping GUI controls, as well as duplicates controls.
Speaking of reliability, MCUnity uses UDP. That means network packets can get lost, however rarely, and your GUI could get wonky as a result. That’s why I put a “Setup” button on it. And of course you always have your trusty reset button.
My to-do list
As I write this, MCUnity is in its embryonic stage. Might even be that in a few months the screenshots will no longer match the actual thing. Here are a few items I already put on my to-do list :
First, I want to add more types of GUI control. Like sliders, tick boxes, radio buttons…
Second, the library supports specifying the colors of individual GUI controls, so I need to implement that feature in the app.
Third, I want to add support for connecting to multiple MCU at the same time. I’m not yet sure what that would look like, so there’s a lot of work right there.
As usual, check my repositories often for updates and remember to RTFM, since I do maintain an effing manual. As long as you use my ESP8266 template project the way you’re meant to, you’re guaranteed that no update to MCUnity will break your own code.
In the next episodes…
Today I gave you a small taste of what MCUnity can do. I also tricked you into installing everything you need to work with MCUnity.
Tomorrow (figuratively, of course, give me a break !) I’ll show you how to debug your own firmware project by creating a custom MCUnity GUI for it.
Then, I’ll get into the details of how MCUnity works. This should be useful to you as a user, to make sure your GUI disturbs your firmware-under-test as little as possible. It’s also insight you’ll want if you decide to port MCUnity to another platform or if you want to expand it.