Thursday, November 8, 2018

Getting Started with a Sparkfun ESP32 Thing, ESP-IDF, and Visual Studio Code

I've had a Sparkfun ESP32 Thing laying around on my desk since back in May when I met the fellow from Iron Transfer at a pinball convention, and we got to talking about IoT and his devices to remotely administrate pinball machines.  However, I spent tons of time this year planning for exhibitions, and didn't really get to do anything with it -- until now.

Before You Begin

There are a few choices you need to make up-front about which IDE you wish to use for development, plus which development framework.  I have chosen Microsoft's Visual Studio Code since it is cross-platform, feature-rich without hogging resources, free to download, and based on an open-source product similar to how Google Chrome is derived from Chromium.  It comes with extensions for language support and IntelliSense, which are must-haves when authoring code.  You are free to use an IDE of your choice; it won't really hamper your ability to enjoy the rest of this article.

The other decision lies in your development framework.  I investigated two choices -- the Arduino framework and ESP-IDF.  When doing my research, mostly back in the summer, I found several posts where people indicated running into problems with support for various pieces of the Bluetooth stack.  Plus, I decided to be closer to the bare metal and have less abstracted away for me, so I went with ESP-IDF.  Now if you don't go along with this choice, you may not find much value from the rest of this article.  But you're welcome to look at these two alternatives for what you want to write your code.

Anyway, if you choose the VS Code with ESP-IDF, then you can follow along with this Instructable that details how to set up the entire toolchain: Despite one commenter that complained loudly about the poor quality of the Instructable, I didn't find it too troublesome to follow along with.  You might just need to look up what any missing pieces are called nowadays, as some things have changed, but I can assure you I got through setup just this past weekend with mostly just that article.

Strange Things You May Encounter

After getting a good way through the setup steps, it was time to compile the code for the first time.  Unfortunately, some odd errors appeared that indicated I hadn't defined some constants and some functions.  I Googled for the missing constant name and eventually found it on GitHub, and saw that it was missing from my local copy of the header file (which leads me to believe the Instructable or the accompanying example code must be being updated).  Fortunately, it is easy to update your development library in case you end up getting an old version and finding that such library code is missing.

From the VS Code Command Palette (Ctrl+Shift+P or Cmd+Shift+P), just look for:
PlatformIO: Update All (platforms, packages, libraries)

Or, from the command line/terminal, write:
platformio update

Once I updated the library code, I was able to compile the code successfully.  However, when using the toolbar at the bottom left of the VS Code window, it is not always apparent which terminal window the command you selected from the toolbar is actually running in.  Whenever you click on the toolbar, it seems to generate a new Terminal instance that's selectable from a dropdown at the top right of that window pane.  Usually, once the command is done running, you can close that terminal instance by pressing a key, but you are always left with one PowerShell instance from within VS Code where you can run your own commands.

After uploading the binary to the Sparkfun Thing for the first time, it displayed nothing but garbage on the serial terminal and didn't show up in the list on my Android's copy of the Nordic nRF Connect BLE scanner app.  This compelled me to reinstall the PlatformIO Core and the platforms/packages/libraries again, especially since after the first time, it apparently failed to remove a file due to a "Permission denied" error.  After seeing an error about something basic being missing once more when rebuilding, I did what you do with any Microsoft product to fix it -- you restart it.  A quick restart of VS Code fixed the problem, and now I was able to rebuild the binary once again without problems.

There was another problem when building the binary: all of my directory paths involved with this project have spaces in them, and the tool did not end up putting quotation marks around some of these.  As such, I would see errors such as:

esptool write_flash: error: argument <address> <filename>: [Errno 2] No such file or directory: 'd:\\Programming\\BriteBlox'

Fortunately, a bit more Googling allowed me to find out a command that would reveal the command that caused this error:

pio run -t upload -v

Here is the command:

"c:\users\user\.platformio\penv\scripts\python.exe" "C:\\Users\\user\\.platformio\\packages\\tool-esptoolpy\\" --chip esp32 --port "COM6" --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 D:\\Programming\\BriteBlox Wearable ESP-IDF\\.pioenvs\\esp32thing\\bootloader.bin 0x8000 D:\\Programming\\BriteBlox Wearable ESP-IDF\\.pioenvs\\esp32thing\\partitions.bin 0x10000 .pioenvs\\esp32thing\\firmware.bin

Now to make the modifications, change the full path to Python at the beginning to just python (it seems to freak out with a fully-qualified path), then add quotes as needed.  Run the command in your own terminal, and the code will deploy as desired.  Meanwhile, this Github issue seems to indicate a fix might be imminent.

Alas, rebuilding the binary did not solve the problem of garbage coming through my serial monitor.  I Googled around for this some more, and found out that the Sparkfun Thing was running at the wrong frequency, or at least a different one than expected.  It runs by default at 26MHz, but the development platform expects that the device is running at 40MHz.  As such, by taking the device's baud rate of 115200, and multiplying by 26/40, I was able to find the true baud rate: 74880.  By opening up RealTerm on COM6 and entering 74880 as the baud rate, I was able to see the expected serial output from the Sparkfun Thing, instead of garbage finally:

BLE Advertise, flag_send_avail: 1, cmd_sent: 4

Now, to solve the mismatch in expected vs. actual frequency, you could either change the crystal to the correct frequency or adjust the development framework to work with the crystal on the board as it is.  In this case, I chose the latter approach.  Many people write about running make menuconfig in the root directory of your project in order to adjust the board settings, but that only seems feasible in Linux.  For Windows users, go into the sdkconfig.h file in your project, and alter the following lines:

#define CONFIG_ESP32_XTAL_FREQ_40 1
#define CONFIG_ESP32_XTAL_FREQ_40 0

(Nota Bene: I was compelled many times to write 24 in places rather than 26, which led to lots of confusion.  The baud rate if you write 24 will be 124,800.)

By changing the two lines from what is in red (on top) to what is in green (on bottom), you will be able to read serial output at the expected 115200 rate, and see the device appear in the nRF Connect app as "ESP-BLE-HELLO" if you copied the Instructable tutorial code.

Happy coding for BLE!

Thursday, November 1, 2018

The OpenBrite Turbo Controller for Vectrex

At long last, I debuted my custom turbo Vectrex controller at the Houston Arcade Expo on October 19 & 20.  This will be a milestone for Vectrex fans and collectors, as it brings about more ergonomic controls and a rate-adjustable Turbo (auto-fire) mode that can toggle per button.

Vectrex Controller Prototype, as seen in Houston last month

Why, you ask?

I acquired a Vectrex in late 2015 from a very generous individual who had several to spare.  However, it did not come with a controller, so it laid dormant until I got around to building the giant 100x NES controller.  As the guts of a cheap knock-off NES controller from Amazon went into my behemoth NES controller, I used its shell and buttons to enclose a crude perf-board controller, and cut up a cheap Sega Genesis extension cable from Amazon in order to make all the connections from my hand-soldered board into the Vectrex.  It is well-documented on how to fashion a Sega Genesis controller into a Vectrex controller, but I didn't really feel like harvesting the QuickShot knockoff because its cable was going bad.

Original homebrew Vectrex controller using a knockoff NES shell

Anyway, both things (the giant NES controller and my Vectrex) made their debut at Let's Play Gaming Expo in 2016.  I even had MuffinBros Graphics whip up a decal for me to go over the generic Nintendo-esque aesthetic and make it look more Vectrex-y.

Assembled controller with decal designed by MuffinBros Graphics (prior to reworking the screen/vector board).  Note how Select & Start have been repurposed into game buttons 1 & 2.

Ultimately, this controller didn't quite suffice because it could be flaky at times, and as an originalist, I really wanted an analog joystick -- one which neither this NES controller knockoff nor a Genesis controller would provide.  After a while, the generous donor came forward with an original Vectrex controller, and so I could study its design and try to replicate it.

However, the original Vectrex controller is not without its flaws.  It takes up an inordinate amount of space for what it is -- four buttons and a joystick.  The four buttons are in a straight line and spread far apart, forcing even someone with large hands to spread their fingers out and curl some fingers more than others to touch all the buttons.  The joystick has a tall, skinny grip, meaning you must grasp it between your thumb and forefinger rather than just mash it with your thumb.  The controller is designed to be set flat on a table to be used, not held in both hands like pretty much every other controller made.  Given all these flaws, original Vectrex controllers still fetch well over $100, with homebrew controllers appearing sparsely.  Given all this, I set out to rectify the ergonomic problems of the controller and modernize its interface, all while keeping such a cheap bill of materials that I could easily squash the market for the original controllers and still (hopefully) make some money.

Lastly, debuting it in Houston was essential because among conventions in Texas, the Houston Arcade Expo tends to have the biggest contingent of Vectrex fans coming to the convention (sometimes Vectrexes are more numerous than any other type of console).  At any other show, it would be far less noticed.

The Design Process

The main impetus for this was to have a homebrew controller that actually featured an analog joystick, since there were few if any guides elaborating how to fashion one from an existing controller.  I acquired a couple Parallax 2-axis joysticks with breadboard mounting capability to do the trick.

The Vectrex comes with a game in its ROM -- Asteroids -- thus you can play without needing a cartridge.  However, with the traditional controller, this requires lots of button-mashing since it has no auto-fire feature.  Using a 555 timer, potentiometer, and clever values within an RC circuit, I have given it the ability to auto-fire.  Not only that, but once you graduate from Asteroids, there may be other games where holding down a button to toggle something repeatedly might not be a good idea.  Thus was born the idea to have toggle switches mimicking the positions of the buttons.  These would be switchable to complete the circuit (by sending GND) just once upon the button press, or send the GND pulse from the 555 timer as long as the button is being held, depending on the position of the Turbo toggle switch for that button.  The potentiometer serves to adjust the rate of auto-fire, from less than once a second to around 7 times a second given the current values of the RC circuit.

The buttons are modeled in a diamond shape, just like Sony PlayStation or Microsoft Xbox controllers.  This allows for better agility as now all buttons to be reached with one finger, and this type of arrangement comes naturally as it has been ingrained into our brains since at least the Super Nintendo.  Playing "chords" of buttons happens rarely, if at all, in Vectrex games, so we might as well standardize the button arrangement to something more familiar but that generally accommodates only one finger at a time.

Finally, the screws to disassemble an original controller are located under the original decal.  As such, you have to pull up the original artwork/decal and risk doing severe damage to it in order to get to the screws underneath the sticker but still on the top side of the controller.


The initial breadboard was built in June 2017.  At first, I was using a jumper wire in order to complete the circuit for each button press, so it was very inconvenient to try to play the game and take a picture simultaneously, much less play the game at all.  After showing these pictures of the breadboard with auto-fire capability to people at Houston Arcade Expo in 2017, I vowed to get it produced by the 2018 show.  And, I just barely made it under the wire with the prototype.

First working breadboard version of the Turbo Vectrex Controller

As you might know, the body of the Vectrex has a clasp that can hold one controller.  Originally, I wanted to split up the controller in two so that this one spot could hold controllers for both players.  However, a controller this small would likely be unwieldy to hold, especially in larger hands.  Furthermore, this would greatly reduce the space on the breadboard available for all the desired components.  As such, I elected to model my enclosure after the original Vectrex controller enclosure.

It was quite painstaking to get the details correct on the controller.  I first attempted to trace the side profile of the controller with graph paper and then approximate it into the computer with Adobe Illustrator.  This proved tedious and with too much uncertainty as to the error, so I got clever and held the controller on its side above a flatbed scanner.  Then, not only did I have the side profile, but also I had the profile of the little groove piece where a nub on the system case guides a controller being inserted to lock it into place during transport or storage.  Furthermore, I could extrude the edge and make the object as long as needed to match the original controller width -- 199mm.

If you consider the side profile of the Vectrex controller to be a blob, I "hollowed out" the blob -- leaving a 2mm-thick ring along the inside -- in order to form the regular outer shell of the controller.  In Illustrator, I also sliced it in half so that I could lay flat both sides -- bottom and top of the controller -- in the CAD program, thus making it easier to model all the details that need to go on those respective pieces.  In particular, the bottom piece was adorned with little grooves in which the breadboard would fit.  As time was running out and component selection was not finalized, I elected not to go with a custom PCB for this implementation, but to simply use my original breadboard.  The bottom side also incorporated screw holes with recesses so that a pan-head screw would not protrude from the case.  While the diameter of these holes was set to accommodate a #6 screw shaft, as you know, 3D printing is an inexact science and, as filament deposits thickly in some areas, this ended up being a hole that nicely accommodates #4 screws instead.  (Note that these holes are on the bottom, unlike on the original.)  The top side of the case not only features further screw holes exactly aligned over the bottom screw holes, but also must have holes/slots for all the protruding buttons and joysticks coming out of the breadboard.  The top side is also angled down roughly 10.7 degrees relative to the bottom side (if aligned parallel to the horizontal), so there were a few times I had to flip things around exactly perfectly in order to verify their correctness.

Speaking of modeling, the CAD program I used for all this was TinkerCAD, with its convenient, simple, yet flexible interface.  With at least a few groups of positive and negative shapes, I can model the entire controller.

Besides the joystick, I also went out to source some interesting buttons.  I already had some clicky buttons and some mushy rubber-dome or membrane buttons, but I wanted something in between the feels of these buttons -- light to the touch, yet clicky.  I managed to find an ideal, nice-feeling button at the local electronics surplus store.  I also acquired several potentiometers and knobs, and was trying to figure out the best way to 3D print something for these too when I found a breadboard-compatible potentiometer lying around in the house.  And thank goodness I found that, because otherwise the knob would have had a very flimsy connection to the potentiometer!

The 3D printing aspect of this was tedious, as Stacy was out of town while I was trying to do all the printing.  She had the licenses to the Simplify3D slicer on machines I did not have access to, so I had to do a lot of back-and-forth of STL files and binary files with her before she finally gave me credentials into these systems.  As the bottom plate took somewhere between 6 to 8 hours to print, I decided to try to make the larger top plate print faster by cutting holes out of it in the design, especially so I could at least test the alignment and hopefully make a quick adjustment if anything was wrong.  Fortunately, the holes were indeed aligned correctly, but sadly, the 3D printer stopped working (formed a clog, apparently) and would not let me print any more items after this case and the buttons.  This was a problem because now my nice-fitting top cover was a bit less structurally sound, and it also looked super-weird.  I managed to rectify this during the show by printing out some informational blurbs as a top decal and taping it onto the top cover.  The prototype top cover also didn't have the screw holes in place, so I ended up having to hold the case together with rubber bands.

Ultimately, the slide switches never got promoted/extended up through the top cover because it was questionable as to how to stabilize such a large moving piece through the top cover.  Several times, I have sheared off the nubs of slide switches by applying too much pressure too close to the top of the switch.  You could reach in with a skinny screwdriver and change the switches, but I doubt anyone bothered or even gave it much attention.


Turbo Vectrex Controller in use -- with "traditional grip" :-P

This labor of love seems not to have gotten a whole lot of attention except from the other guy who brought a Vectrex machine, who really liked it (and was willing to  3D-print a proper top cover for me during the show).  It seems like consoles that predate the NES tend to be a little bit too obscure for people these days.  Even the Atari 2600, which was immensely popular in its time, now is generally popular only with people old enough to remember its heyday.  Of course, the Vectrex is a really obscure machine in its own right.  It came out shortly before the Video Game Crash of 1983, and it is nearly impossible to find replacement vector monitors if that part should go out.  This makes for quite an expensive collectors item nowadays, which means the owners are scattered around the country in small numbers.

I think for it to get much traction, I will have to do more than a couple tweets about it and show it at a regional show -- it probably needs to be posted on AtariAge and brought to the Portland Retro Gaming Expo in order to make a big splash.  However, before I take it to that point, it would be nice to make a proper PCB that mounts to the top cover, make the appropriate edits to the CAD model to facilitate that, finalize the bill of materials, and then make sure the whole thing fits into the slot designed for it in the system case.  After the Houston show, I thought this would take no time, but the more I think about it, the more I foresee still quite a bit more math and CAD time ahead.