When I first launched “teachernerd.com” in the summer of 2019, I did what I was used to and turned to a managed hosting provider. The thing about managed hosting, however, is that “managed” is just another way of saying “locked down,” which is not the funnest setup for tinkerers like me. (Yes, I said “funnest.”) Also, all that “management” you’re supposedly paying for comes at a cost—a cost that (surprise!) tends to increase over time. At some point I got to thinking, “Why not just do this myself?” So I used a much cheaper service from that same provider to spin up a virtual machine and then proceeded to set up a classic LAMP stack.

Of course, given that I am not a cybersecurity expert, I eventually started to worry about keeping this self-managed system safe. So…I configured my virtual machine’s network gateway to close off all inbound access from the public internet. 

Blocking all ingress to your server like this is kind of a problem, though, if you’re trying to host a public website. Enter Cloudflare Zero Trust, an enterprise-oriented offering that also includes a very generous free tier. By setting up a secure tunnel, I was able to use Cloudflare’s global network of data centers as my front door (rather than a public IP address), which meant I could rely on their expertise and infrastructure to wall off all the private parts of my system.

This all kind of worked for a while, except that it also made it much more complicated for me to access everything!

I finally decided it was time to get out of the server self-management business.

The Problem

What makes WordPress (and content management systems like it) so special is that it generates pages on demand. For the most part, all of your text is stored in a database while your media lives in an uploads directory on the server. To display a particular page, the server executes a script that makes a bunch of calculations in order to insert the correct content into the correct locations within a series of templates. The actual pages seen in the browser don’t technically exist until they are requested. Thus, the content is considered dynamic.

This is a far cry from the World Wide Web of the early 90s, when what you saw in your browser was largely static. Although server-side scripting was still a thing even back then, in general, content was stored in its “final” form on the server and simply fed over the internet (that mythical series of tubes) to the end user.

We’ve come a long way since then in terms of interactivity (JavaScript!), security (encryption!) and so forth, but one of the biggest liabilities remains all the moving parts that go into serving up dynamic content. Whether powered by PHP, Node.js, or some other language/platform, websites are now essentially software, which of course leaves plenty of room for bugs—to say nothing of all the software running behind the scenes on each individual server.

In many ways, this is just progress: sophistication breeds complication. Still, wouldn’t it be nice if there were a way to get the best of both worlds? What if you could use a fancy system like WordPress to simplify content creation (rather than having to painstakingly craft every single page by hand) but still somehow serve it all from static, inherently more mundane files? Heck, what if you could eliminate all the overhead of running a web server altogether?

All of these things, it turns out, are possible thanks to the oxymoronically named concept of static site generation.

A static site generator is basically a tool that does all the stuff a CMS does (i.e. combine content, templates, and logic) but instead of delivering the results to a browser on demand, it saves every possible page in advance as static HTML files, which you can then upload to a traditional web server or, even better, one of numerous “serverless” providers that now make it possible to “abstract away” the entire web hosting concept.

There’s a catch, however. (There’s always a catch!) Some website components simply cannot be done statically, the most obvious examples being forms. With forms, you have to be able to collect the information and then do something with it—the exact opposite of remaining static!

I knew the solution to my website maintenance challenge was to migrate to a static blog, but to do so without any loss in functionality, I would eventually have to find a way to deal with not one but two contact forms as well as numerous places where a search form appears.

The Objective

For me to feel satisfied, a statically generated blog would have to meet the following criteria:

1. Be able to replicate the exact look and feel of my original WordPress blog.
2. Be able to do this repeatedly (i.e. any time I might choose to update the site).
3. Not require me to learn a new platform (at least not right now).
4. Have somewhere to live on the public internet.
5. Have some way of handling contact forms.
6. Continue to offer a search engine.
7. Be as inexpensive as possible. (Bonus points, as always, if it could be done for free!)

The Solution

Gimme, Gimme Some HTML

Let’s start with those first three goals: easy, repeatable replication without using a new platform. For this, I turned to a WordPress plugin called Simply Static. With just a modicum of configuration required, this plugin was able to save a perfect copy of the output for nearly every single page of my site to a specified directory on my web server.

Now, hold up a minute! Isn’t the goal here to avoid running a server? Well, yes, but I still want to use WordPress to generate my site. And that means I still need a server somewhere. My goal was to ditch my public web server; I don’t mind a private server on my own local machine.

A Trip to the Docks

Look, despite all my complaining, web servers are not rocket science, but they can be annoying to set up. Actually, there are lots of systems you might want to put on a computer that can get tricky real fast, especially if you want them all to play nice together. This is precisely why containerization was invented!

It’s way beyond the scope of this post to truly explain containerization, and I don’t think I’d do a very good job of it anyway. But put very simply, containers work a little bit like virtual machines in that they bundle together all of the software and configurations you need to run a particular thing (a web server, a database server, a home automation system…) while relying on resources provided by the containerization platform and host machine to actually execute it.

One of the biggest names in containerization is Docker, and one of the things that Docker is very good at is composition—that is to say, allowing you to build an entire system out of multiple pre-compiled components.

This is starting to veer into the territory of something known as infrastructure as code, but you can basically create a file that describes each of the pieces you need and how they should work together. Then, with a single terminal command, you can tell Docker to download/assemble all those bits and launch the system.

You can see my own Docker composition here. In a nutshell, what this file does is tell Docker to create a complete WordPress setup out of four pre-built application “images”: one for the WordPress core; one for the separately packaged WordPress command line tool; one for a MySQL server (for databases); and one for phpMyAdmin, a GUI for working with those databases. The file also provisions some virtual drives and makes certain folders on my computer available to the container so that I can use my own theme, plugin, and media files.

Docker allows me to start up my local WordPress server whenever I need to work on the site and instantly tear it down when I’m done, freeing up memory and CPU cycles for whatever else I might want to do on the computer. Once I’ve finished editing the content, I can use the Simply Static plugin to re-render my site so that I can upload the static files to my hosting provider.

Stuck in the Clouds

Speaking of hosting providers, let’s talk about Criterion #4: giving this site a home. There are lots of options out there, but I eventually settled on yet another solution offered by Cloudflare, largely because their platform also provided a way to deal with Criterion #5 (the contact form).

Cloudflare, you see, offers a tool called Workers. A Worker is really just a script, but rather than storing and running it on a specific machine, you just sort of, well, upload it to Cloudflare. When called upon, Cloudflare launches what is essentially a virtual machine, runs the script, and then tears it all down. It’s kind of like Docker in a way, except that everything is replicated and distributed across an array of data centers (the so-called cloud of Cloud Computing), which theoretically means that Cloudflare can select the best location for the job for any given request based on distance to the user and available resources.

That’s a cool sales pitch and all, but it’s really not what was important to me. What I liked about Workers was that in addition to executing scripts, the system can also (wait for it!) host static websites. In other words, I could use Cloudflare, which I had already been relying on for caching and security, to handle the whole shebang. And best of all, Cloudflare doesn’t charge to host (or serve) assets like HTML or reasonably sized media (Criterion #7). You can even run your Worker scripts for free—so long as your traffic is relatively light (which should not be a problem for my contact forms).

Following the Script

With all this figured out, I set about writing a script that I could run inside a Worker to process my contact form and turn each submission into an email.

Workers supports a few different languages, but plain old JavaScript felt most approachable for this. As for the script itself, it mostly involved validating inputs and then inserting the data into a message template. I used a library called MIMEText to help with that latter part, mostly because it was used in one of Cloudflare’s own tutorials. For delivery of the messages, I was able to take advantage of Cloudflare’s email routing service. (It’s not exactly designed for this use case, but it is evidently possible.) Meanwhile, Cloudflare’s CAPTCHA tool, known as Turnstile, gave me a way to protect the form from bots. (Have I put too many of my eggs in one basket at this point? Only time will tell!)

The final piece of the puzzle was the search engine, which I almost thought would thwart my plan—or force me to rely on Google (yuck!)—until I came across this thread on Stack Overflow. 

One of the replies mentioned a JavaScript-based search engine called MiniSearch.

MiniSearch is intended to be lightweight enough to run entirely in memory—and even entirely within a browser. As long as I could find a way to feed all my data into it, I could perform searches on the client side rather than having to tax my Worker and risk maxing out Cloudflare’s free service tier. My effective, albeit slightly ridiculous, solution was to create a template that outputs the full content of every single post in JSON (a structured data format that works well with JavaScript) and tell Simply Static to generate this “page” along with the rest of the site.

Next, I created a new search page for the site that uses some client-side scripting (a/k/a JavaScript in the browser, where it typically lives) to fetch that big chunk of JSON, feed it into MiniSearch to generate an index, and then query MiniSearch’s index for whatever the user has typed into the search bar. Once it finds some results, the script formats the output via a templating library called Handlebars (so-named because it makes extensive use of mustache-like curly braces), eventually presenting post previews to the user almost identically to how they would have appeared on my WordPress theme’s native results page. (Woo!)

The Outcome

I think it’s fair to say that the outcome for this project is self explanatory: you’re looking at it! You can browse every corner of this blog just like you could before the switch. Every post, page, and archive is still intact. On top of that, the contact forms are now home grown and no longer rely on a third-party plugin with aggressive upselling tactics. (This plugin shall remain nameless in protest!) This part of the project also gave me an opportunity to follow a great tutorial on progressively enhanced form validation.

Meanwhile, I’m excited to use my experience with the Workers platform to help in my day job, where we’ve recently begun to experiment with Amazon’s cloud computing tools (a/k/a Amazon Web Services, which, if you haven’t heard, basically runs everything these days).

Finally, while the search bar is definitely not the most important component of this website, I do think it’s kind of neat that it actually still works. I never thought of search as something you could do entirely on the front end until now. (It does help that this blog isn’t actually that large and you can download all the text in about a second.)

While we’re on this topic, I think for a future project I’d like to update the search interface to use either React or Vue (which I’ve written about here). These “reactive” frameworks are really good at handling interfaces that need to update frequently or respond to events (like when you perform a new search or need to switch to the next page of results). Handlebars is quite explicitly not intended for that sort of thing. (Oops!)

The Takeaway

Misapplied templating tools aside, I still think the search page is a neat hack, so here’s the full code for anyone who’s interested!

Let me begin this post by quoting the New York Times:

“Lego building is now as ubiquitous a leisure activity for adults as doing puzzles.”

Joshua Lyon, writing for “Wirecutter”

With that…clarification?…excuse to use a pull quote?…out of the way, I think I can say with near-absolute confidence that I get just as much joy out of building Lego now as I did decades ago. And while I’m not the sort of AFOL who builds MOCs or nerds out at conventions, I will still happily spend minutes/hours/days assembling a brand new set.

My favorites are the so-called Modular Building Series.

But I’ve also enjoyed putting together official Lego renditions of familiar objects such as a Fender guitar or a classic manual typewriter.

Most recently, I had the opportunity to build Item #10334, also known as the Lego Icons Retro Radio.

It’s a very cool set in its own right, but what lands it a spot here on my blog is the opportunity it provided to embark on a nifty electronics/computing project.

The Problem

Clocking in at just over 900 pieces, the Retro Radio would seem to be one of Lego’s less intense undertakings when you consider the plethora of parts and intricate techniques typically involved in, say, the Modular Buildings; at first glance, one might even argue that the model is little more than a pretentious box.

However, as it turns out, there is a surprisingly elaborate contraption under the hood made up of Lego Technic parts.

This series of axles and gears and such allows the tuning knob to really move a needle back and forth along the frequency dial. Meanwhile, the on/off knob, which features a delightfully tactile “click,” engages and disengages a secondary mechanism that repeatedly pushes a button on a “sound brick” as you move the needle. Each push of the button activates one of several randomized, pre-recorded sound clips. This adds a great “play” element to the model (in multiple senses of the word), but it also got me wondering:

Could there be a way to turn this thing into something closer to an actual radio?

Well, technically, Lego kind of already solved that problem. Removing the model’s back panel reveals a sort of spring-loaded cradle that you can clip a phone into. So all you have to do is pull up a playlist on Spotify (or Apple Music or whatever), pop in your phone, and boom! You’ve got yourself a “radio”!

That’s clever and all, but it does mean having to sacrifice access to your phone for the duration of your listening session, which is less than ideal if you want to, say, skip a song, switch to a new playlist, or send a text to your friend about your cool new toy.

The Objective

As I thought about it some more, an idea began to crystallize. What if, instead of using my phone, I could semi-permanently mount some dedicated electronics inside to handle the music playback?

I quickly came across a blog post by U.K. freelance writer Sean McManus, who did just that using a Raspberry Pi. His particular innovation was to replace the sound brick with a similarly shaped contraption built out of normal Lego pieces onto which he glued a simple push-button. He wired the button to the Pi, along with a tiny sound card and speaker, positioned the button in the exact spot the sound brick had occupied, and then wrote a Python program that played his own, personalized selection of music and sound effects each time the model’s existing button-pushing mechanism happened to do its thing.

I considered at first trying to emulate this project but ultimately decided to go my own route. While I really appreciated how McManus managed to integrate the existing Lego control knobs with the electronics, I didn’t feel like dealing with glue or a soldering iron—or trying to find the necessary Lego pieces to build my own sound brick.

Plus, what I really wanted was the ability to play any music at all, not just a predetermined collection of clips. So, what I finally set out to create was a pint-sized wireless speaker system.

As for my criteria, the system needed to be:

• Tiny enough to hide inside the Retro Radio (ideally without removing any parts)
• Easy to connect to remotely from a phone or computer for the sole purpose of streaming music or other audio
• Buildable without glue or solder
• Self-contained (no need to repeatedly open up the Lego model to access the electronics or to “log in” to any components for administrative tasks)

The Solution

Although my main goal diverged from McManus’s project, his write-up gave me a great place to start. In fact, like McManus, I chose to use a Raspberry Pi as the “brains” of the operation and an add-on board from “Maker Goods” purveyor Pimoroni to provide the audio capabilities. But where McManus opted for a full-sized Raspberry Pi and a separate speaker, I decided to go for a more compact solution.

The model of Pi I chose (the flavor, if you will) was the Zero 2 W. While the original Pi form factor is roughly the size of a credit card, the Zero line is advertised as only 65mm x 30mm (that’s approximately 2.6” x 1.2” for us Americans). In other words, it’s small!

It may not be as powerful as its larger brethren, but the Zero 2 W still includes built-in WiFi and Bluetooth, perfect for streaming music from one device to another. And because I would not need to log in and run any sort of desktop environment, I suspected I could get by just fine with the Zero’s diminutive 1Ghz processor and 512MB of RAM.

To handle the sound output, I selected the Pimoroni Pirate Audio Speaker. It’s a clever device that packs all the necessary components for audio output—a DAC, amplifier, and 1W speaker—onto a single board the exact same size as the Pi Zero.

The board also includes a 1.3” color LCD and four tactile buttons. While I wouldn’t be needing any of those for this project, I figured they could come in handy in the future (if only I hadn’t managed to break the screen less than a week after buying it).

The Pirate Audio board attaches to the Raspberry Pi via its 40-pin GPIO interface and requires only a teensy bit of configuration to get it working. (The Pi Zero typically comes without the GPIO header attached; I bought one from my local electronics shop that had it pre-soldered to the device to help meet my aforementioned specifications.)

With all the hardware in place, the last piece of the puzzle (or pie?) is the software. Ideally, I wanted to be able to connect my phone or computer to the speaker setup using Bluetooth or, since I’m an iPhone/Mac guy, the AirPlay protocol, which operates over WiFi. I experimented with this sort of thing years ago, so I already knew that there were open source tools out there for handling this. For AirPlay support, the gold standard seems to be a project called Shairport Sync, which provides a mostly all-in-one, reverse engineered implementation of Apple’s proprietary protocol. For Bluetooth, perhaps because it’s a more open standard, the options are a bit more varied, but they all ultimately require cobbling together several different utilities to get the job done. (More on this later, if you’re interested.)

Finally, because it’s what I am most familiar with, I chose to install all of this on top of the standard Raspberry Pi OS (a Debian-based Linux distribution). I went with the Lite version to keep space and resource requirements to a minimum.

The Outcome

Strangely enough, one of the most challenging parts of the operation was attaching the sound card. I expected the Pi’s GPIO pins to slide right into the sockets on the Pirate Audio board’s header. Instead, this operation required a fair bit of force, which likely contributed to my having accidentally cracked the panel (a misfortune to which I believe I alluded in an earlier parenthetical—alas!)

The only other physical task was to fit the assembled device into the Lego model, which turned out to be quite easy thanks to its small size. There’s even already a convenient gap in the back panel through which you can route the power cord. (You just have to reposition a single, structurally insignificant piece, as McManus noted, to widen the space a bit.)

The rest of the project was a not-particularly-enthralling-in-verbal-form process of downloading, compiling, installing, configuring, and testing various software components until finally, a working Bluetooth/AirPort speaker was born. (Don’t worry, I’ll share all the gory details in the next section for those who are still interested.)

The actual results were, well, pretty much what I expected. Even at maximum volume, the sound from the 1W speaker is meek at best. I would describe it as “serviceable” when playing rock and pop songs, but if you try like I did to throw something at it with a wider dynamic range, such as Dvořák’s Symphony No. 9, you may have to strain to hear the quieter sections. That said, the quality, lacking in anything resembling bass or oomph, seems somehow appropriate when emanating from what is, essentially, a toy made entirely out of plastic, so I kind of consider that to be a feature rather than a bug.

I expected to have the most trouble getting AirPlay to work, but Shairport Sync ended up working incredibly well. My fiancée encountered some hiccups with the sound periodically cutting out when she tried it from her own phone, but I think this might have been an issue with the WiFi signal in our apartment rather than a problem with any of the software.

Bluetooth playback, meanwhile, seemed to be less spotty—when we could get our devices to connect in the first place. The very first time either of us would try to pair a computer or phone to the Pi, everything would go great. But if we disconnected a device and then tried to re-connect, that’s when things started to go wrong. It’s a mild annoyance that can thankfully be solved by resetting the Pi and telling the relevant phone/computer to forget the speaker.

…Or we can just use AirPlay!

I doubt this tone- and volume-challenged Lego creation is something I’ll use as a speaker all that regularly, but I do appreciate how a model that could be a great conversation starter in its own right has had its novelty factor cranked up to 11!

The Takeaway

If you’d like to try recreating this project yourself, this section is for you! I’m not going to go into all the minutiae, but I’ll walk you through the process I followed, point out a few challenges I ran into, and link to some step-by-step guides for installing the necessary software.

To streamline this as best I can, I will assume you are already reasonably familiar with the Raspberry Pi and have spent some time on a Linux command line before.

If you’re really only here for the bird’s eye view, feel free to just move right along!

Read More…

Initial Setup

As with any Raspberry Pi project, the first step is to flash an OS to a micro-SD card. There are, of course, a number of ways to do this, but I particularly like the official Raspberry Pi Imager because it lets you do some basic setup ahead of time, including giving the Pi a hostname, configuring WiFi, and setting it up to accept SSH connections.

After the device finishes booting up for the first time, you’ll want to log in over SSH and make sure that all the latest updates are installed. (You could theoretically hook up a keyboard and monitor to access the Pi directly, but I find the remote connection to be more convenient.)

As for hardware configuration, this is just a matter of adding three lines to /boot/firmware/config.txt—one to make the audio board recognizable by the Pi’s firmware, one to turn on a GPIO pin used to activate the onboard amp, and another to turn off the Pi’s built-in audio (to avoid any issues with software choosing the wrong output device).

dtoverlay=hifiberry-dac
gpio=25=op,dh
dtparam=audio=off

(See the Pirate Audio GitHub repository for more information, but be forewarned that some of the instructions are a bit out of date, and most of them are about using the LCD screen or Pimoroni’s suggested audio playback software, neither of which are required for this project.)

It’s best to reboot the Pi after making these changes. As for me, when it was done rebooting, I took a moment to run the raspi-config tool to expand the SD card’s file system. The tool also allowed me to make sure the “snd_rpi_hifibery_dac” component was detected and set as the default audio device.

Sound Test

Once all the hardware is configured and OS maintenance is complete, you can test whether the speaker works by running the following command: speaker-test -c 1 -t wav. This, thankfully, worked for me on first try. My dog was a bit concerned about the disembodied voice proclaiming, “Left speaker…left speaker…,” on loop, but otherwise, all was good!

AirPlay Support

Now, it’s finally time to start installing some software. A lot of it needs to be compiled yourself, but the process requires fairly minimal manual effort.

As I mentioned earlier, the key to AirPlay support is an open source solution called Shairport Sync. This project is very well documented, with detailed, step by step build instructions that walk you through all the commands that need to be run. I ran into one tiny snag, which was that I needed to add `libglib2.0-dev` to the list of dependencies to install.

After that, the instructions are fairly straightforward, especially if you choose to omit support for the AirPlay 2 protocol and avoid adding any configuration flags other than the ones used in the default walkthrough.

My first time through, I went with the basic approach. For the sake of experimentation, I later went back and added all the bells and whistles, which meant compiling and installing a helper daemon called NQPTP (required for some sort of fancy timing system that is evidently integral to AirPlay 2), a library providing support for the Apple Lossless codec (totally overkill for a tone-challenged 1W speaker, but hey, why not?), and another library called libsndfile (necessary for some more very much unnecessary fanciness). Again, none of that is strictly necessary.

One configuration flag that you don’t want to leave out is --with-systemd. This ensures that the Shairport daemon can be easily started at boot time without the need for logging in or any other user intervention. All you have to do is run systemctl enable shairport-sync at the conclusion of the install process.

Once I had this all compiled and installed, within a few moments of rebooting the Raspberry Pi, “Lego” showed up as a speaker option on all of my Apple devices, all of which were able to connect without any fuss. The only real issue I encountered was that I could barely hear anything at first. I was able to resolve this, however, by—wait for it—raising the speaker’s volume via the connected device! (You may wish to spend some time, as I did, exploring the additional options available in Shairport Sync’s configuration file, but once again, based on my experience, this should not be strictly necessary.)

Bluetooth Woes—I Mean, Support

Audio

The final challenge is Bluetooth. This part is definitely a little more complicated. The most important component is a project called the Bluetooth Audio ALSA Backend (BlueALSA for short). This is probably an oversimplification, but BlueALSA is essentially a bit of glue that gets the software components that support the Bluetooth hardware to talk to the software components that support the audio hardware.

As with Shairport Sync, BlueALSA needs to be compiled from source before installing, but it too has a step-by-step walkthrough. There are a lot of configuration flags you can play with, but I ended up skipping all of them except for --enable-systemd. As with Shairport, this option makes it easy to run BlueALSA as a background service without having to be logged in.

This isn’t mentioned in the official walkthrough, but to actually enable Bluetooth audio support at startup you need to run sudo systemctl enable bluealsa followed by sudo systemctl enable bluealsa-aplay. This activates two system services that work together to forward incoming Bluetooth audio over to the sound system.

Authentication

But of course, even that’s not enough to get this all working. There also needs to be a way to handle the Bluetooth authentication process—the complicated handshake that we all know so well, mostly thanks to how often it fails. (Have you ever had to have one Bluetooth-enabled device “forget” another Bluetooth-enabled device?)

There seem to be a number of ways to handle this, but I liked the solution documented by none other than a user going by “DrFunk” on the Raspberry Pi forums. Basically, you need to install an “agent” that hangs out and waits for Bluetooth connections. Once it detects one, it automates the process of accepting/trusting that connection so that you don’t have to log into the Pi and do so manually.

My advice: just skip all the way to Step 4 and follow the instructions to install “bluez-tools” (not to be confused with a certain beloved children’s television show) and create a service to start the unsurprisingly named bt-agent at runtime. If you’d like some extra security (instead of blindly auto-trusting all connections), you can also follow Step 5 to add a PIN. I also recommend following Step 7.1, which disables a volume control protocol that could add some additional complications.

Once I did all that, I was, in fact, able to use the Pi Zero as a Bluetooth speaker in addition to an AirPort speaker—with some caveats.

Annoyance

One unfortunate complication that I never quite figured out was that I ran into trouble any time I tried to disconnect a device from the Pi and then reconnect. The only way to fix this was to have both the source device and the Pi forget one another and then re-start the pairing process, so Bluetooth on this device continues to be a work in progress.

Turning the Music Down—er, Off

Even with AirPlay working nicely and Bluetooth kinda-sorta working, there was still one final problem to overcome: the Raspberry Pi does not have an on/off switch, and even if it did, the goal is to keep the thing hidden inside an enclosed Lego model. In a perfect world, I should be able to just pull the plug like I would with a normal radio, but doing that to a running computer, which at any moment might be writing to its storage medium, could lead to data corruption and eventual system failure. 

To overcome that, I decided to use a nifty feature in the raspi-config utility that automates the process of setting up an “overlay” filesystem. This is a clever trick that makes the Pi’s memory card effectively read-only by putting a temporary RAM disk in between the fixed storage and the operating system. Any changes to the file system are written to the RAM disk instead of the underlying storage (i.e. the SD card) and are simply lost when you pull the plug. The SD card, meanwhile, theoretically remains in the exact same state during all subsequent boots as it was prior to enabling the overlay.

In addition to insulating the SD card from damage due to hard shutdowns, this also helps work around some of the Bluetooth finickiness since the Pi can now instantly forget all devices that have previously connected to it over Bluetooth as soon as the plug is pulled, preventing you (or me) from having to ever log back in to do this by hand.

Final Assembly

The last step, if you haven’t done this already, is to fit the Pi inside the Lego model.

If you route the power cord the same way McManus describes in his blog post, the tension created by the cord and the phone cradle will help keep the Pi in place. It’s not exactly a snug fit, but it’ll do. (If you’re feeling clever, you can probably whip up a more secure mechanism with your own Lego parts.)

With the Pi in place, you can put the back cover back on the model, fully enclosing the electronics and completing the illusion that this is a real A/C-powered radio.

Wrapping Up

I hope this project has inspired you to dig some old Lego sets out of your basement or just learn more about the awesome world of AFOLs and MOCs. Or perhaps you’re ready to find your own unexpected object to turn into a tiny speaker. As always, if you come up with a cool idea of your own, or you found this write-up helpful, I’d love to hear about it.

Until next time, thanks for following along! 

I’m not exactly a fan of Google having access to all our information ever, nor do I feel great about how, through its substantial dominance of the Internet, Google gets to quasi-unilaterally dictate all manner of policies regarding web standards, privacy, and security.

But even I have to give Alphabet, Inc. credit where credit is due: if you’re a user with pretty basic needs looking for a modern, easy-to-use, easy-to-maintain, and stable computing platform, there is nothing quite like Google’s ChromeOS.

When ChromeOS was first announced, the idea seemed pretty absurd. Could a platform originally designed to run just a single application—the Chrome web browser—actually be of any use? Well, over a decade later, with Chromebooks continuing to grace the shelves of big box retailers and increasingly being adopted by school systems and businesses looking for low-cost yet reliable machines, the answer is clear.

The Problem

ChromeOS has evolved over the years and can technically do more these days than just run Chrome. The latest Chromebooks support software built for Linux and Android, and enterprise users can even run Windows applications by way of virtualization. But ChromeOS’s bread and butter is the way it gives users access to all the powers and possibilities of modern web apps without all the complicated layers of configuration, software updates, and other UX distractions that might otherwise get in the way.

For all these reasons, when the computing needs of an older relative of ours recently outgrew an aging Android tablet, my fiancée and I felt pretty confident that a Chromebook would get the job done while minimizing our need to assist with long-term tech support.

There was just one catch: even though ChromeOS is fairly intuitive, it would be reasonable to assume that a brand new user might need at least a little hand holding at first. Unfortunately, while we both consider ourselves adept computer users, neither of us has had all that much experience working with Chromebooks.

The Objective

Providing support – especially over the phone – when you have no idea what the environment actually looks like is definitely no fun.

To make this work, it would be a lot easier to have a Chromebook of our own to experiment with and follow along on—if only that wouldn’t require buying a second new computer. Frankly, we already have too many computers lying around, so this whole situation would be much more palatable if we could just install ChromeOS on a machine we already own.

Because ChromeOS is actually based on an open source project called ChromiumOS, it has been theoretically possible to create a makeshift Chromebook for almost as long as real Chromebooks have been around.

Google, historically, has never made ready-to-go ChromiumOS images directly available to the public, but the source code has always been freely available. With enough skill and determination, you could compile that code yourself into working executables, add in any missing device drivers, and then figure out how to get it all onto a compatible device. This process is not exactly straightforward, but luckily, there have always been a handful of folks out there in cyberspace, including someone who goes by Arnold the Bat, willing to take on this challenge for us mere mortals.

I have successfully followed Arnold’s instructions before, so that was definitely a possible route to take here. One downside, however, is that this process has not always gone smoothly when I’ve tried it. More crucially, ChromiumOS is not an exact clone of ChromeOS; Google adds some of its own proprietary features on top of the open source core. While there are “ways” of adding back some of these missing features, my preference would be to avoid that can of worms and start with something much more closely resembling the real thing.

The Solution

Enter ChromeOS Flex. Announced in 2022, this product marked the first time that Google itself, rather than a third party, would provide a way to install not just ChromiumOS but the full-fledged (well, nearly full-fledged) ChromeOS on user’s own hardware. (Some features, such as Android app support, are still not included.)

I successfully installed Flex on an old custom-built desktop when it was first released, but this time around, for maximum “flex”-ibility, I wanted to use it on an old laptop I had dug out of my closet: a MacBook Pro “Mid-2010” model (i.e. a MacBookPro6,2 if you’re familiar with Apple’s internal nomenclature).

This is where things get tricky.

The Outcome

Google provides a pretty thorough installation guide, so I’m not going to get into all the particulars here. Suffice it to say, I followed their directions to create a bootable USB stick, plugged it into the computer, and used Apple’s OS picker (accessible by holding down the “Option” key while booting) to boot ChromeOS instead of macOS.

To my momentary delight, the ChromeOS logo appeared, and then…

Nothing. I could move a mouse cursor around the screen, but otherwise, all I could ever see was the logo.

Interestingly, at some point Google’s built-in accessibility tool kicked in and started reading the screen to me—except that the screen it was reading was definitely not there! The screen reader would even tell me about the invisible things I was evidently clicking on and the keypresses that it was evidently detecting.

Something was clearly amiss. Given that everything else seemed to be working, my hypothesis was that this was related to graphics drivers (as the weirdest computer issues so often are, in my experience).

I knew from the get-go that this computer was not on Google’s certified models list. Nevertheless, not one to be easily discouraged when someone tells me a computer can’t do something, I decided to keep digging, despite the post I found on Reddit confirming that support for NVIDIA chipsets like the graphics hardware in this computer was spotty at best.

You are much more likely to find success, the collective wisdom of the internet explained, running ChromeOS Flex on a computer with integrated graphics (i.e. when video hardware is built into a machine’s main processor rather than existing as part of a “discrete” card or chipset).

The thing is, despite that pesky NVIDIA processor my laptop was saddled with, the MacBookPro6,2 just so happens to also have Intel’s integrated graphics technology built in. It’s just that in this particular model, it plays second fiddle in order to enable, among other things, a power-saving mode. But maybe, I thought, I could find some way to force ChromeOS to use the Intel graphics and somehow ignore the NVIDIA chip.

The first thing I tried was to install a third-party boot manager called rEFInd, a powerful albeit esoteric open source project (with a website stuck in the 90s) familiar to people like myself who like to boot alternative operating systems on their Macs. I’ll spare you all the details of the Extensible Firmware Interface and boot procedures. What matters right now is that rEFInd has a feature that can trick a Mac into thinking that it’s running macOS even when it isn’t, thereby getting the firmware to enable certain components, such as the integrated graphics functionality, that it otherwise might not.

Unfortunately, this did not solve the graphics glitch.

It was therefore time for a more drastic measure. I knew from previous experience that there are sometimes ways to forcibly disable the discrete graphics chipset on Apple laptops like mine. This was known to be one of the methods, for instance, by which you could “repair” certain models when the dedicated graphics chipset began to fail.

After some more Googling, I tracked down a thread on Stack Exchange with the trick that I was pretty sure existed: namely, a near-incomprehensible terminal command (`sudo nvram fa4ce28d-b62f-4c99-9cc3-6815686e30f9:gpu-power-prefs=%01%00%00%00) that sets a variable in the system’s firmware that, in turn, tells the machine not to enable the dedicated graphics on bootup. My theory was that if I could get this to work, then maybe ChromeOS would see (and thus use) the integrated graphics instead.

So I booted the machine into recovery mode to ensure that none of Apple’s system protections could get in the way and ran the command. To my pleasant surprise, it actually worked! The next time I tried to boot off of the ChromeOS USB stick, the user interface finally displayed correctly, allowing me to finish setting things up and even try to get some work done. (I typed out my entire first draft of this blog post in Google Docs running on ChromeOS on my 14-year-old MacBook Pro.)

Wrapping Up

Truth be told, this is not a computer I have all that much interest in actually using. While I still really appreciate its form factor, with a 15” screen and spacious keyboard, the thing is heavy. I also really miss the “retina” display on Apple’s newer laptops. And most concerningly, I forgot just how hot this computer runs; it quite literally burns my legs if I try to use it on my lap for more than a few minutes.

That said, the point was for my partner and I to be able to familiarize ourselves with ChromeOS and have access to a model setup that we could use for helping our relative. And in that way, the project has been a resounding success. It took a little extra effort, but we now have exactly what we needed without having had to spend a penny more!

While I’ve mostly used this website (which, I should note, represents only my own personal opinions and not those of my employer) to talk about tech, I think I’ve made it clear that I love participating in and thinking about journalism. So today, I’d like to present the first of what I hope to be a continuing series of Media Deep Dives, where we’ll take a look together at something out there in the news sphere—an article, photograph, etc.—and consider what makes it tick or examine its broader implications for the practice of journalism.

For this inaugural installment, which I’ve decided to split into two parts, I’d like to do both while sharing a story from The Washington Post about police departments that have found ways to skirt local bans on the use of facial recognition technology. While the story initially caught my eye thanks to my interest in AI ethics, I’m going to mostly set those issues aside. Instead, I’d like to start by exploring what this article shows us about the evolving nature of headlines. Then, in part 2, we can take a look at how this story exemplifies some of the debates around objectivity in journalism.

1. Headlines in the Digital Age
2. Objectivity vs. Neutrality

While the deal—for a barely three-month-old piece of intellectual property—undoubtedly turned plenty of heads, Wordle cannot be deemed the most buzz-worthy word game in the New York Times lineup. That title, naturally, will forever belong to Spelling Bee.

A quick run-down of the rules for the uninitiated: Each day, the game features a new set of seven unique letters arranged in a honeycomb-like grid. Players must use these letters—and only these letters—to create as many words as possible, earning points based on their length. Every word has to be at least four letters long and must include the central, highlighted letter at least once. Other than that, individual letters may be used as many (or as few) times as needed.

One other interesting quirk: The solution to each Spelling Bee puzzle includes at least one word that incorporates all seven letters. These bonus words, known as “pangrams,” earn the player extra points. This is significant because the game assigns its players a series of ranks each day based on the number of points they have earned, culminating in the coveted status of “Genius.”

The Problem

Assuming the posts on this Reddit board are indicative of the typical Spelling Bee enthusiast, most players are happy to achieve Genius and move on. However, there exists one more, hidden rank reserved for the intrepid few who manage to find every word on a given day: Queen Bee.

These days, my fiancée and I play the Bee together most mornings during breakfast, trying to earn as many points as we can before heading off to work. (We’re just so wholesome!) Because we really enjoy word games and are almost guaranteed to reach Genius if we work together, our goal (though we rarely achieve it) is always Queen Bee.

The thing about pushing for Queen Bee, however, is knowing when to quit. Although the Times does not officially tell you this, we figured out a long time ago that the daily threshold for Genius is always 70% of the highest possible score.

So we’ll usually do the math at some point and then use that number as either a motivator or a reason to cut our losses before the game stops being fun anymore.

The math, of course, is easy. We just open the calculator app on one of our phones, put in the value for Genius, and divide it by 0.7. But given that this is a well-defined task with well-defined inputs that we end up having to do every single time we play, doesn’t this sound like yet another perfect opportunity for some automation?

The Objective

I understand why The New York Times does not openly publish the number of points necessary to reach Queen Bee on any given puzzle. That would make perfection seem like the goal of the game—a goal that is too hard to reach on a daily basis to keep the game fun and casual.

But because of the way my partner and I play, it would be rather useful to have this number available to us at a glance. (This is especially true because we’re always forgetting the max score and having to find it again.)

My goal for a Spelling Bee automation project would therefore be to devise a way to have the Queen Bee score injected directly into the game’s user interface without our ever having to leave the browser—and ideally without any user intervention required.

The Solution

Arbitrarily modifying the appearance of a relatively static webpage is not, in principle, very hard to accomplish.

In fact, thanks to the demise of proprietary plugins like Adobe Flash, even the sleekest looking pages are typically rendered using plain text for, well, text; HTML tags for structure; and human-readable CSS rules for appearance/presentation.

And that means there’s very little that website owners can do to stop you from altering (on your own computer) a page’s information, design, or layout.

Things get a little harder if the page uses certain components of the HTML5 standard—particularly those designed for fancy graphics, multimedia, or interactive content—that are usually controlled via JavaScript. But otherwise, go to your favorite website, open up your browser’s developer panel, and you can tweak the text, HTML, and CSS to your heart’s content!

Spelling Bee does use plenty of JavaScript code behind the scenes to do things like configure the game board or judge whether a guessed word is a valid answer. However, it turns out that a lot of the basic layout—including the scoring legend—is still handled via plain old, easily manipulatable HTML and CSS.

That’s great, but the only way to actually do this manipulation (without having to hand-edit the source code every single time) would be to write some JavaScript of my own.

With that in mind, to achieve the goals of this project, I would ultimately have to do the following:

• Figure out where Spelling Bee stores its scoring information.
• Write some JavaScript to either (a) grab the Queen Bee score from wherever it might be hiding or (b) grab the Genius score and do the math to convert it to Queen Bee.
• Write some more JavaScript to format the Queen Bee score to look like all the other ranks in the scoring legend and then insert it into the list.
• Figure out an easy/reliable way to execute all this JavaScript—preferably without user intervention.

The Outcome

The actual solution was pretty simple—around 70 lines of code, including comments and extra spaces for readability. However, there were a few interesting challenges.

For starters, even though I was able to figure out where Spelling Bee stores its answer key (something I definitely did not want to know ?), I could not find the maximum score encoded anywhere. So I would have to resort to having my code grab the Genius score and do the math. No biggie.

The second challenge, however, was that the scoring legend appears to be built dynamically whenever the user requests it. In other words, when the page is first loaded, neither the legend nor its data is anywhere to be found. And when the legend is dismissed, rather than simply making the box invisible, the underlying web app completely removes it from the page. This meant I would have to come up with a way to grab the Genius score, calculate Queen Bee, and then insert that new score each time the user opens up the legend—since then and only then is the content available for manipulation.

After doing some research, I learned that most browsers released in the past 10 years support a JavaScript feature called MutationObserver, which can trigger a block of code as soon as something about a particular element in the page structure changes. One such change is the addition of a new “child” to a container. In the case of Spelling Bee, I just had to configure a MutationObserver to watch a specific <div> element and call a function containing my code as soon as the legend appeared inside it.

The final problem to solve was the question of how to actually run this code. My first idea was something called a bookmarklet, which is essentially a bunch of JavaScript smushed into a hyperlink that you can keep in your browser’s toolbar or Bookmarks menu.

When you click or tap on a bookmarklet, the browser executes the code in the context of the current webpage. This solution worked, but it came with a major downside: I would have to manually run the bookmarklet every single time I opened the Spelling Bee—and then re-run it if the browser decided to refresh the page.

What I really needed was a way to force some code to run every time a page loads, as soon as it loads. It eventually occurred to me that this is exactly one of the problems that browser extensions are intended to solve. These days, extensions are created using HTML, CSS, and JavaScript just like websites. Google created a model API for use in its Chrome browser; Mozilla, Microsoft, and Apple all eventually followed with the same or similar implementations.

I had never tried this before, but since I already had some working JavaScript, I figured it couldn’t be too much more trouble to bundle it into an extension. So I read some of Google’s documentation and then, since I ultimately wanted this to work on my iPhone, I followed Apple’s instructions for creating a Safari Web Extension.

Lo and behold, after installing my newly minted extension and giving it permission to access The New York Times, I finally had a solution that met all of my objectives.

Now, whenever I am playing the Spelling Bee, I can open up the scoring legend and see what it will take to reach Queen Bee right at the top of the list. And in order to preserve some of the magic of the unadulterated game, my extension can even be configured to hide the maximum score until after genius has been achieved!

The Takeaway

Here’s the JavaScript for performing the necessary page manipulation. (Note: The code, as written below, will always show the Queen Bee score once it has been executed.)

// ==UserScript==
// @name        Bee Royal
// @match       *://www.nytimes.com/puzzles/spelling-bee
// @match       *://www.nytimes.com/puzzles/spelling-bee/*
// @grant       none
// @version     1.0
// @author      teacherdan
// @description Adds the number of points needed to reach \"Queen Bee\" status to the scoring legend when playing the Spelling Bee game from the New York Times.
// ==/UserScript==

// Function to add Queen Bee (e.g. total possible points) to the scoring legend
const addQueen = () => {
    // Grab the Genius score from the legend and use it to calculate Queen Bee
    const genius = document.querySelectorAll(".sb-modal-frame.ranks .sb-modal-ranks__rank-points")[1].innerText;
    const queen = Math.round(genius / 0.7);
    
    // Grab the current score from the legend and use it to calculate points-to-go
    const current = document.querySelectorAll(".sb-modal-frame.ranks .current-score")[0].innerText;
    const diff = queen - current;
    
    // Create a new table row containing the Queen Bee value
    let queenRow = document.createElement('tr');
    queenRow.innerHTML = '<td class="sb-modal-ranks__rank-marker"><div class="square"></div></td><td class="sb-modal-ranks__rank-title"><span class="current-rank">Queen Bee</span></td><td class="sb-modal-ranks__spacer hr"></td><td class="sb-modal-ranks__rank-points">' + queen + '</td>';
    
    // Insert the new row at the top of the scoring legend
    let scoreList = document.querySelector(".sb-modal-frame.ranks tbody");
    scoreList.insertBefore(queenRow, scoreList.firstChild);
    
    // Update Genius subtext
    if (playerIsGenius()) {
        let subtext = document.querySelector(".sb-modal-frame.ranks .sub-text");
        subtext.innerText = diff + " points to go!";
        subtext.style.display = "block";
    }
}

// Checks whether current player is a genius
const playerIsGenius = () => {
    return document.querySelector(".current-rank").innerText == "Genius";
}

// MutationObserver callback function that will be executed whenever
// a new modal dialog (such as scoring legend) has been added to the UI
const newModalCallback = (mutationList, observer) => {
    
    // Loop through all the mutations we've received
    for (const mutation of mutationList) {
        
        // Only respond to child list mutations
        if (mutation.type === "childList") {
    
            // Do the manipulation!
            addQueen();
        }
    }
};

// Create a MutationObserver linked to the callback function
const modalObserver = new MutationObserver(newModalCallback);

// Find the DIV used by the game for displaying modal dialogs (including the scoring legend)
// and observe it for changes to its child list (e.g. dialogs appearing/disappearing)
window.onload = () => {
    const modalWrapper = document.querySelector(".sb-modal-wrapper");
    console.log(modalWrapper);
    modalObserver.observe(modalWrapper, {
    childList: true
    });
}

And here’s that same code as a bookmarklet you can drag to your toolbar or add to your Bookmarks menu: Bee Royal. (If you’d prefer, for security reasons, to create your own bookmarklet, you can paste my code into a generator. This is the one that I used.)

Now, I wish I could share my final product—the automatically activating, configurable extension. Unfortunately, Safari extensions can only be installed from Apple’s App Store, and this is just a hobby project that I’m not prepared to officially support. (Although there are workarounds, the other major browsers have similar restrictions these days.)

There is, however, one other option. Instead of using a bookmarklet, you could install something called a user script manager, which is basically an extension that allow you to automatically run arbitrary, third-party code, either on specific webpages (what we need here) or even potentially all pages. Greasy Fork links to a few options you might consider. I can’t vouch for any of these extensions’ safety, privacy, or security practices, but I did confirm that they are able to run my JavaScript solution.

Instructions for using a script manager are beyond the scope of this article, but you are welcome to copy and paste my code into your chosen extension. I’ve even already included the necessary metadata to make sure things go as smoothly as possible!

Wrapping Up

As always, thank you for following along on this journey toward orthographic royalty. I look forward to additional automation and/or scripting projects in the future!

My fiancée and I watch very little live television. One major exception, however, is the MLB postseason—provided that either the Phillies, New York Mets, or Washington Nationals have made it to the playoffs. Truth be told, this doesn’t happen all that frequently, so even then we watch very little live TV.

But when the stars do line up just right, not only do we get to experience the excitement (yes, I said it!) of multiple games of baseball; we also get to feast our eyes, ears, and brains on that most surreal form of secondary entertainment known as commercials.

Two things stood out as I watched this year’s fare: (1) Musical numbers (some knowingly tongue-in-cheek and others missed-the-memo earnest) are apparently in vogue, and (2) smartphones—and in particular, smartphone cameras—are becoming increasingly creepy.

I’m speaking, of course, about the Pixel 8 series, which Google launched in early October, just as the Wild Card round was getting started. As the commercials were happy to inform us—backed up by cool, techno vibes—these phones are packed full of AI-enhanced photo editing features.

Cause for Alarm?

Now, I should pause for a moment and note that artificial intelligence and machine learning have played a role in digital image processing for some time now. Apple, for instance, uses “Deep Fusion” to optimize photos; Canon does something similar with “deep learning.” For the most part, we don’t dwell on the calculations our phones and cameras perform under the hood. But the thing that kept freaking me out, commercial break after commercial break, was a new user-facing feature that Google has named “Best Take.”

As demonstrated in the advertisements, the feature allows you to take several photos in short succession and then create one “perfect” image by choosing the best face for each subject. It’s a great way to correct for family members that won’t stay still or that one friend who was blinking in every photo except for the one where you’re mid-sneeze. Instagram never looked so good!

The Washington Post’s Geoffrey A. Fowler sums up my discomfort when he asks, “Is this a line we want to cross?” He explains the deeper issue like this:

As much as I enjoyed using [Best Take], there’s an uneasy casualness about letting AI edit the faces in the smartphone photos we rely on to archive our memories. It’s allowing AI to help standardize ideas about what happiness looks like—an escalation of the cultural pressure we’ve been grappling with on social media to curate smiling faces and perfect places that don’t always reflect reality.

The column goes on to grapple, somewhat ambivalently, with the question of “How fake is too fake?” Like me, Fowler considers the role that software and algorithms have long played in photography, but he also raises fair concerns about slippery slopes and sexism, ultimately wondering aloud what the purpose of a photograph should even be. Is it a “record of a moment,” as Fowler puts it, or something else?

The Classroom Perspective

As someone who has taught photojournalism to high school students for around 13 years, I could not help but let this question sit with me for a while. Why do we create and share photos, let alone publish them in newspapers?

When I pose this question to my students, the consensus they usually settle on is that photos allow us to capture the reality of a particular point in time in a way that feels somehow “more real” or, at the very least, augments the written/spoken word.

We’ll look at Pulitzer Prize-winning photos together—moments of victory, tragedy, and everything in between—and talk about how the angle, the framing, the lighting, or even just being in the right place at the right time and having the wherewithal to push the button leads to a scene packed with the kind of imagery—action and emotion—that an English major could only dream of conveying.

But therein lies the rub. These most celebrated of images are each a bundle of choices—even if the only conscious choice was to plant oneself in a particular spot on a particular day. Ultimately, as much as we like to talk about “capturing” a scene, photos are (and have always been) something we create.

In subsequent classes, I’ll teach my students about the exposure triangle—how they can use the combination of shutter speed, aperture, and sensitivity to control things like the perception of motion, how much of a scene is in focus, and how light or dark an image is. An expert photographer might adjust these settings manually. A beginner may choose to shoot on “fully automatic” mode, but that doesn’t make the choices go away. The decisions are just being delegated to the machine. (Even an old-school, disposable film camera without a single piece of electronics inside has had the exposure parameters predetermined at the time of manufacture, and those parameters will still shape the appearance of the developed photo.)

One might try to imagine a world where there are no such mechanical considerations to be made—where what you see is simply what you get. Besides the fact that even our own eyes don’t work that way, that notion quickly fades once my students and I begin to discuss composition—how photographers (deliberately or not) make use of techniques like the rule of thirds and leading lines that subtly tell viewers what to look at, how, and when. We’ll talk about how the location of the camera—things like bird’s eye and worm’s eye view—can change our perception of a person’s size or power.

I love photography, so I could go on and on. (Don’t my students know it!) The point is that even when done in the service of journalism, a pursuit for which the central conceit is the primacy of truth, photography is at its heart artificial.

Creative Visions

We haven’t even begun to talk about portraiture. From the first moment some cave dweller smudged some dirt on a wall, we humans have been creating representations of the world around us. Walk through any art museum, and you’ll see paintings created to showcase this or that aspect of a person or a scene through the choice of medium, pigments, brushstrokes, and so forth, not to mention the complete control the artist has over what we see, what we don’t see, how large to make a person’s hip, etc., etc.

Portrait photography is really not so different. Whether in a studio or at a party, the photographer’s job is to capture the essence of one or more individuals and/or the scene around them. A wedding portrait may have the couple positioned just so with the lighting just right to portray their everlasting love for one another. A photo of a bunch of kids saying, “Cheese!” at a birthday party perhaps wishes to capture how gosh darn fun it is to be 7!

So is it really such a crime to use an algorithm to blend five images together so that everyone is happily looking at the camera if the whole point is to capture not just what the moment looks like but what it feels like—or even what we may want it to feel like?

Fowler’s column lingers on the opportunities for abuse, if not of this technology then its successors. But then again, as Jay Peters at The Verge points out, we’ve been manipulating photos almost as long as there have been photos to manipulate. (AI makes it a lot easier now, but the risk has always been there.)

What is it, then, that makes “Best Take” feel so different to me? Perhaps it’s the implied act of dissemblance—this sense that rather than just passing an image through a filter, we’re being given permission to pretend that a scene that we constructed from discrete parts (much like a LEGO model) equates to what we actually remember seeing in the viewfinder. What may be entirely natural to do with paint on canvas seems, in the end, subversive in a photograph.

Or, as Matt Bai puts it in his own Washington Post column, “It matters how we portray truth.” Writing about the entire range of “fun” new AI features users have access to, Bai goes on to point out the impracticality of trying to stop this technology. However, he adds, ominously:

But to make the explicit selling point of that phone the notion that imperfect truths don’t need to exist anymore—that what’s real is both fungible and subjective—strikes me as reckless. It romanticizes the most destabilizing trend in society and invites us all to revel in it.

Any neuroscientist will tell you that memory is malleable—even fallible. If our own perception of past reality can—and likely will—change over time, then there’s a part of me (albeit small) that wonders whether achieving a level of memorial perfection in photography even matters. Physicists, meanwhile, will tell you about the “observer effect”—the notion that the very act of observing a system will inherently change it. Bai’s larger political point notwithstanding, this poses a far deeper question: is it even possible to capture an “accurate” moment in time?

Maybe, as new tech often has the potential to do, what the Pixel 8 really inspires within me and the writers I’ve cited above is just good old fear of change—combined, in my own case, with my household’s disappointment over the Phillies’ loss in Game 7 of the NLCS.

I’m still undecided (about “Best Take,” not the unfairness of the baseball universe). But it is at least comforting to remember that, in a way, artificial intelligence in visual media is nothing new. Portraiture and photography have always been rooted in artifice. For better or for worse, we creators just have a lot more tools at our disposal now.

Just a few days ago, I posted a tutorial explaining how you can use a spreadsheet app combined with Adobe InDesign to generate a slideshow based on a template.

I had previously used this technique when I had to create a presentation featuring the name and photo of 100+ students to play during a virtual induction ceremony for my school’s National Honor Society chapter.

Rather than having to create all 100+ slides by hand, I could automate the most tedious part of the job by making use of InDesign’s built-in Data Merge feature.

Similar to a mail merge in Microsoft Word, this feature allows you to create a template, import a data table from your spreadsheet, and then link each of the table’s columns to a placeholder on the template. Then, with the click of a button, InDesign can create a new file containing a page (or, in this case, a slide) for each row of the table.

The Problem

One of the coolest aspects of InDesign’s Data Merge is that it can handle image frames in addition to text boxes, so it really is perfect for my particular use case (i.e. awards slideshows).

That said, there is one major downside: as cool as I think the technique may be, it does still require Adobe InDesign—and for many people, that’s going to be a showstopper.

For those who may be unfamiliar, InDesign is a professional desktop publishing app. I’ve been using it (and teaching students how to use it) for over a decade, so the interface is second nature to me, but it can definitely be overwhelming for someone whose word processing and graphic design experience is limited to the Microsoft or Google office suites.

InDesign also requires a subscription if you want to use it beyond the seven-day free trial. Regular users have to pay $20.99 per month while students and teachers can access the entire Adobe Creative Suite for $19.99 per month. That’s actually a pretty good deal if you also need access to things like Photoshop or Lightroom, but that’s still not exactly cheap.

Meanwhile, Google Slides (along with the rest of Google’s office suite) is easy to use, ubiquitous, and essentially free for personal use. (I say “essentially” because, well, it’s Google. You’re “paying” for their services by giving up tons and tons of data and personal information…but I digress…) It’s also already being used by tons of school systems as part of a seemingly diabolical plan to…er, let’s just move on…

The Objective

I won’t quite call it the Holy Grail of slideshow automation, but I do think it would be even more cool if there were a way to auto-generate a slide deck from a spreadsheet without resorting to InDesign—bonus points if it could be done completely within the “free” Google ecosystem.

The Solution

Let’s get this out of the way right now: Google Slides does not have a built-in data merge feature. However, because Google would very much like to sell subscriptions of its non-free, enterprise-grade Google Workspace service to all the world’s businesses, they have, in fact, developed a number of powerful automation features. They’re just not particularly obvious to mere mortals.

One of these features is something called Google Apps Script, a system for writing your own sort of mini-applications that live in the cloud and can interact with the various components of the Google suite.

Solutions written in Google Apps Script are kind of like macros, automations that have long been part of Microsoft Office and similar desktop applications.

(Fun fact: Macros have picked up something of a bad reputation in recent decades since they are a prime attack vector for distributing viruses and other malware. Even though Microsoft Office now blocks them by default in files downloaded from the internet, they remain a significant tool available to power users and enterprises.)

Whereas a macro for Microsoft Word or Excel can be written in a language called Visual Basic for Applications, Google Apps Scripts are written in a language based on JavaScript. And since JavaScript is the language for front-end web development, it should be pretty easy for someone with a little bit of modern programming knowledge to jump right into Apps Script development! (Oh boy, I’m starting to sound like a salesperson. Maybe that diabolical plan is really working…)

As it turns out, I do have some prior experience using Google Apps Script to generate files from a template, so I definitely had a hunch that something similar could be done to merge data into Google Slides.

Then, while doing some research for my InDesign blog post, I came across a website called Spreadsheet Dev. Written by a guy who, much like me, identifies as both a developer and a teacher, the site’s goal is to “teach spreadsheet users to code using Google Sheets and Apps Script.” This author has written some great tutorials, but the one that really caught my eye was this: “Convert each row in Google Sheets into a slide in Google Slides using Apps Script.”

As you may be able to tell from the title, the script from this tutorial does almost exactly what I’ve set out to do here. The author also did a great job adding comments to his code so that you can understand the purpose of each line. That tutorial and all the earlier ones it links to are honestly a great way to learn about Google app automation. If you have any interest in this subject, I encourage you to take a look!

But, useful though that article may have been for my research, it was not exactly what I wanted for my solution. For one thing, I realized that all the field names were hard-coded into the example script. This meant that the script would have to be revised, based on the specific nature of the data, each time someone wanted to use it for a new project. A reference to the slideshow being used as the template was also hard-coded; a piece of the template’s URL would have to be pasted in for each new presentation. And perhaps most significantly, the script was not designed to handle a data merge with images, which meant it would not be usable for any future award ceremony slideshows.

Nevertheless, by reading that article, I now had a basic outline for how to handle data merges in Google-land. The process didn’t seem too off-the-wall, so I felt pretty confident that it would be possible to write my own script that could handle both text and images while also being flexible enough to work with all kinds of templates and data sets.

The Outcome

I spent some time reading the Google Apps Script documentation, mostly to figure out whether it’s even possible to manipulate images in Google Slides via script (it is), and subsequently, how to actually do it.

However, an interesting challenge that I ran into is that Google Slides doesn’t really allow you to add an empty image frame to a slide. I also wasn’t sure at first how I could designate a particular image to be replaced by a particular column from the spreadsheet. The solution I eventually came to was to just put a dummy image on the page and then add the field name from the spreadsheet as the image’s ALT text. (It’s a hack, but it works. See below for more info.)

I also discovered that Google Apps Script does not have a convenient, built-in way to display a document picker to the user. So in order to maintain my goal of not having any specific files or locations hard-coded into the script, I had to resort to using predictable files/folders rather than pickable files/folders. (It just means you have to give things certain names and put them in the right place. I still think that’s easier than editing the script each time.)

These small limitations notwithstanding, the script I created works almost exactly like my InDesign-based solution. You start by creating a template slide with {{placeholder}} tags wherever you need dynamic data. Then, you put all your data into a spreadsheet with column names that match those tags. Finally, you run the script and—voilà—you have a slideshow!

The Takeaway

If using custom code to get a job done feels a little unsettling, even if all you need to do is copy and paste that code without editing it, fear not: there are pre-written add-ons available in the Google Workspace Marketplace that can handle data merges and presumably do other fancy things, no coding required.

Personally, I like using my own code whenever possible because I can see exactly what it does and not have to wonder what the app/developers might be doing with my data behind the scenes. So even if there are free add-ons out there that have already been written by other people, I’m more comfortable using my home-brewed solution. And if you’d like to use it too, then I invite you to keep reading!

The Script

So, first things first, here’s the actual script I created:

// This function loops through each row of the sheet and performs the data merge
function createDeckViaDataMerge() {

  // Get the folder containing the spreadsheet
  let sheetId = SpreadsheetApp.getActive().getId()
  let parentFolder = DriveApp.getFileById(sheetId).getParents().next()
  
  // Get the template file from the folder
  let templateFile = getTemplateFile(parentFolder)

  // Exit the script if we couldn't find a template
  if (templateFile == null) {
    Logger.log("Error: Could not find template!")
    return
  }

  // Create a new file and retrieve the template slide from it
  let templateSlide = getTemplateFromNewFile(templateFile)

  // Exit the script if we couldn't retrieve a template (i.e. file contained no slides)
  if (templateSlide == null) {
    Logger.log("Error: Template is empty!")
    return
  }

  // Retrieve the contents of the spreadsheet
  let spreadsheetData = SpreadsheetApp.getActive().getDataRange().getValues()

  // Separate the column labels from the rest of the sheet
  let columnLabels = spreadsheetData.shift();

  // Reverse the order of the remaining rows so that slideshow appears in correct order
  let rows = spreadsheetData.reverse();

  // For every row, create a new slide by duplicating the template slide
  // and replace the template variables with data from that row.
  rows.forEach(function (row) {

    // Create a duplicate of the template slide at the beginning of deck
    let slide = templateSlide.duplicate();
    
    // Loop through the fields to make replacements
    columnLabels.forEach(function (fieldName, index) {
      
      // Process field based on whether its column holds text or a photo filename
      if (isPhotoField(fieldName)) {
        
        // It looks like this is a photo field, so grab the filename from this column
        // of the current row.
        let fileName = row[index]
        
        // Now, let's drop the image prefix ("#") from the field name
        let fieldNameWithoutPrefix = fieldName.substring(1)
        
        // Use the new filename and modified field name to attempt an image subsitution
        processFieldAsImage(slide, parentFolder, fieldNameWithoutPrefix, fileName)
      }

      else {
        // It looks like this is a regular text field, so grab the substitution text from this column of current row
        let newText = row[index]

        // Now use that text to perform a substitution
        processFieldAsText(slide, fieldName, newText)
      }
    })    
  });

  // Remove the template slide from the final output
  templateSlide.remove()
}

// This function finds a file named "TEMPLATE" in the given folder and returns it
function getTemplateFile(folder) {
  
  // Look for slide decks with the name "TEMPLATE"
  let templateFiles = folder.getFilesByName("TEMPLATE")
  
  // If we found any template files, use them
  if (templateFiles.hasNext()) {
    
    // Return the first found template file
    return templateFiles.next()
  }

  // Return nothing if we couldn't find a template
  else {
    return null
  }
}

// This function duplicates the given template file and returns the first
// slide (i.e. the template slide)
function getTemplateFromNewFile(templateFile) {

  // Duplicate the template file  
  let newFile = templateFile.makeCopy()
  newFile.setName("Generated Slide Deck")

  // Open the new file
  let newDeck = SlidesApp.openById(newFile.getId())

  // Get the slides from this deck
  let slides = newDeck.getSlides()
  
  // If the deck has any slides, return the first one
  if (slides.length > 0) {
    return slides[0]
  }
  else {
    return null
  }
}

// This function replaces any text on the given slide that matches the field name
function processFieldAsText(slide, fieldName, newText) {
  
  // Use the fieldname to build the placeholder text (e.g. "{{fieldName}}") that we'll look for on the slide
  let placeholderText = "{{" + fieldName + "}}"

  // Do the replacement
  slide.replaceAllText(placeholderText, newText)
}

// This function checks whether the field name is preceded by a # symbol,
// in which case that field's column will be assumed to contain the names of image files.
function isPhotoField(fieldName) {
  return fieldName.substring(0,1) == "#"
}

// This function looks for a folder alongside the spreadsheet that matches the given field,
// and if it finds one, it tries to start the image replacement process.
function processFieldAsImage(slide, parentFolder, fieldName, fileName) {
  
  // Look for a folder inside the spreadsheet's folder that matches the given field name
  let matchingImageFolders = parentFolder.getFoldersByName(fieldName)

  // Proceed ONLY if we were able to find a match
  if (matchingImageFolders.hasNext()) {
    
    // Get the first folder from the set
    let imageFolder = matchingImageFolders.next()

    // We're looking for an image whose ALT text matches "{{fieldName}}",
    // so let's create a variable to hold that search string
    let placeholderText = "{{" + fieldName + "}}"

    // Handle the image replacement
    handleImageReplacement(slide, imageFolder, placeholderText, fileName)
  }
}

// This function looks for an image on the given slide whose ALT text matches
// the given placeholder text. If it finds one, it attempts a substitution.
function handleImageReplacement(slide, imageFolder, placeholderText, fileName) {

  // Get all the images from the template slide
  let slideImages = slide.getImages()

  // Loop through each of the images we just got
  slideImages.forEach(function (image) {

    // Check whether the current image's ALT text matches the placeholder text
    if (image.getDescription() == placeholderText) {

      // We found a match, so attempt to replace it
      replaceImage(image, imageFolder, fileName)
    }
  })
}

// This function looks for an image with the given filename in the provided folder.
// If it finds one, it replaces the provided image with the new one.
function replaceImage(oldImage, newImageFolder, fileName) {
        
  // Look for a photo in the folder with the given filename
  let foundImages = newImageFolder.getFilesByName(fileName)
  
  // Check whether we actually found any images that match the fileName
  if (foundImages.hasNext()) {
    
    // We foud a match, so let's get just the first one from the set
    let newImage = foundImages.next()

    // Replace the placeholder image with the new image
    oldImage.replace(newImage)
  }
}

function addMenuToSheet() {
  let menu = SpreadsheetApp.getUi().createMenu("Data Merge")
    .addItem("Do Merge", "createDeckViaDataMerge")
    .addToUi()
}

function onOpen() {
  addMenuToSheet()
}

What to do with it…

Now, if you’d like to actually use that script, here’s how:

1. Create a folder for your project in Google Drive. Call it whatever you’d like!
2. Create a Google Slides document with just a single slide. You can use a built-in design or a third-party template. Just make sure to put the document in that folder you created. And make sure the document is named TEMPLATE. (This is case-sensitive, so make sure it’s in all-caps.)
3. When designing your slide, any elements that will look the same on every slide (logos, boilerplate text, etc.) can be added the same way you would for a normal slide.
4. To add text that will change on each slide (like a student’s name or grade), create a placeholder tag like one of these: {{Name}} or {{First}} {{Last}} or {{Grade}}. (Your column names will vary depending on what your data looks like. Just make sure to include those curly braces.)
5. To add a photo or other image that will change on every slide, start by adding literally any image you want to the slide to serve as a dummy/placeholder. Just make sure to crop it to the actual shape/size you want on the final slides. (You could use one of your actual photos if you want to be certain the dimensions are correct.)
   • Now click on that image and choose “Format Options” from the toolbar. A sidebar should appear on the right side of the window. At the very bottom is a section labeled “Alt Text,” and in that section is a box labeled “Description.” Type a placeholder tag (e.g. {{Photo}} or {{Portrait}} or some other relevant name) into that box. Be sure to include the curly braces!
   • Next, create a folder in Google Drive with the same name as the placeholder tag (e.g. Photo or Portrait—but this time no curly braces). Make sure this folder is in the same parent folder as the template. Then, add, move, or upload the relevant images into that folder. (You can create more than one folder if you have multiple placeholders.)
6. If you already have a data spreadsheet, upload it or move it into the folder. Otherwise, create a new one. Make sure the column names for any dynamic text, like student names or grades, match your placeholder tags exactly (but without the curly braces).
7. If your template includes any placeholders for images, make sure they each have a column in your spreadsheet.
   • For the column name, use a pound sign (#) followed by the name of the folder you added the relevant images to. So, for example, if I had a placeholder in my presentation labeled {{Photo}}, then I would upload the images to a folder named Photo and make sure to have a column in my spreadsheet labeled #Photo.
   • For your rows in this column, all you need are the file names for those images, e.g. 123456.jpg. (You do NOT need the paths/locations.) Make sure the names appear exactly as they do in Google Drive.
8. When your table is all set up, click on the “Extensions” menu and choose “Apps Script.” A new tab should open containing an editor interface.
9. Delete the default script from the editor and paste in the one from the box above. Then, click the “Save” button in the toolbar. (It looks like an old floppy disk because everyone in 2023 knows what one of those is for…)
10. Go back to the tab with your spreadsheet and refresh the page. A few seconds after it’s done reloading, you should see a new item labeled “Data Merge” appear in the Google Sheets menu bar.
11. Click on that new “Data Merge” menu and then select “Do Merge.” A status notification will appear at the top of your window. Wait for it to indicate that the script has finished. (The longer your spreadsheet, the longer this will take.)
12. Go back to your folder on Google Drive. You should see a new slideshow named “Generated Slide Deck.” Open it up. If all went well, you will see a slide for each row of the spreadsheet. Each of your placeholders should have been filled in with the appropriate text or image!

Wrapping Up

Thanks for following along on my Google Apps scripting adventure. Hopefully, you’ve enjoyed the opportunity to learn about this powerful automation tool, and perhaps you’ll even find a way to incorporate my slideshow generator into your own workflow!

Some NHS inductions (like the one I experienced as a teenager) involve an elaborate candle-lighting ritual. Our school opted for a streamlined approach.

Each of the society’s officers would deliver some prepared remarks, a guest speaker would give an inspirational keynote, and we’d announce each inductee’s name as if it were a graduation. We’d conclude the event with a recitation of the NHS pledge and then wish all the proud families a good night. All told, it took about 90 minutes.

Normally, when announcing the names, we’d invite each student up onto the auditorium stage to receive a certificate. But then…the pandemic happened.

Like everything else, the ceremony went virtual. But let’s face it: no one comes to the NHS induction for the speeches (even though we did continue including them in the ceremony). What the parents in attendance really want is to hear their kids’ names and see them walk across that stage. The solution? An induction slideshow!

Sharing a slideshow over Zoom is easy enough, but you know what I did not want to do? Create all those slides, each with a student’s name and photo, by hand. This wouldn’t be a big deal for, say, a dozen students, but our chapter inducted over 100 each year!

After some investigation, I determined that this problem could be solved with two tech tools I already used quite frequently in my journalism classroom: Microsoft Excel and Adobe InDesign.

Objective

In the following tutorial, I’ll walk you through how to create an awards slideshow suitable for a graduation, induction ceremony, or other event where you want to individually project each recognized individual’s name and face. These same techniques could also be used for other resources, like certificates or photo directories, that require merging text and images from a list into a pre-made template.

Materials

This tutorial should work on any Mac or Windows-powered PC capable of running Adobe InDesign.

To follow along, you’ll need the following tools:

• Adobe InDesign: This desktop publishing app may not be your first thought when trying to create a slideshow. In fact, there are dedicated apps like Keynote, Google Slides, and PowerPoint that are far more suited to the task, but none of them has built-in data-merge capabilities. InDesign does! This tutorial assumes you are already familiar with creating a document and adding simple elements like text boxes and image frames to the page.
• Adobe Acrobat Reader: The easiest way, in my opinion, to share the finished slideshow is as a PDF, and Adobe Reader makes it very easy to display the PDF like a slideshow. But really, any PDF viewer that can display single pages in full-screen format will do the trick.
• Microsoft Excel or Google Sheets: You’ll need to use your favorite spreadsheet app to do some basic data manipulation and create the info file necessary for InDesign to do its magic. I’ll mostly be using Excel for my examples, but Google Sheets works just as well. Plus, any formula that works in one app will usually also work in the other.
• List of student information: The list can be in any format that you can easily open, import, or paste into your spreadsheet app. (You can either create this yourself or obtain it from your school’s student information system.) At minimum, you’ll want columns for each student’s name. If there is any additional information you want to include on the slide, such as the student’s grade or teacher, you’ll want to have columns for those things, too. And if there are any details (e.g. an ID number) that might help you match a student’s name to the relevant photo, it would be helpful to include that information as well.
• A folder of student images: For this to work as efficiently as possible, the images need to have a predictable naming format. Something like [lastName]_[firstName].jpg or [idNumber].jpg would be ideal. If that’s not possible, you can still follow this procedure with randomly named files. You’ll just have to manually enter each of the filenames into the spreadsheet, which of course, does somewhat defeat the purpose of automation.

Step 1: Gather and Format Your Data

If you’re working with an existing Excel file or Google Sheets document, go ahead and open it in whichever app you are using. Otherwise, do what you need to do to import or paste the data into a new document.

Once you’ve gotten your data in front of you, delete any columns you don’t need and perform any manipulations necessary to clean up the data.

For example, let’s say my initial spreadsheet, which has been exported from the student information system, looks something like this:

I don’t need grades, addresses, or teacher names for my slideshow, so I’m going to delete those three columns. I also like to have the ID number at the very beginning. So now my spreadsheet looks like this:

This is closer to what I need. Unfortunately, my school’s student information system often exports names in “Last, First” format, but I want the names in the slideshow to look like “First Last.” So I’m going to use the text-to-columns feature that I described here to split up the names into two columns. (I’m also going to rename the ID column because things are always a bit easier, in my experience, when field names are just a single word.)

Now my data looks like this:

This is just what I need to be able to put each student’s name on a slide.

Step 2: Add the Image Filenames

Rather than somehow try to put the images themselves into your spreadsheet, all you need to do is add the filenames. You can type or paste each of those filenames in manually if needed. However, ideally, as long as the filenames follow a predictable pattern, you can generate them automatically using a formula.

For example, when you export the photos from the student information system, let’s say the filenames look something like this: “HENDERSON_KAITLYN.JPG”

That’s a predictable format; it’s always the last name, followed by an underscore, followed by the first name, a period, and the file extension. Oh, and let’s not forget that everything is in all-caps!

I can recreate this filename in an empty cell at the end of Kaitlyn’s row using the following formula:

=UPPER(B2 & "_" & C2 & ".jpg")

If you need a refresher on Excel formulas, here’s a quick breakdown:

• The equals sign tells Excel that this is a formula and not a piece of data.
• UPPER() is a function that converts any text you give it into uppercase.
• The letters and numbers (e.g. B2) refer to a particular cell by row and column, respectively.
• Anything in quotation marks (like “_” and “.jpg”) is interpreted as a “string” of arbitrary text.
• The ampersands are used to concatenate (or stick together) two pieces of text.

So if you type all that into a cell and hit the Enter key, it should immediately display HENDERSON_KAITLYN.JPG

Now, what if the image filenames follow a different pattern? For instance, my school’s photography vendor would label the photos by student ID number. This was actually really convenient for us because it made it very easy to import the images into our student information system. And because I already have the ID number for every student, it’s also very easy for me to add these filenames to the spreadsheet. Here’s the formula for the first row:

=A2 & ".jpg"

This is just a simple concatenation, which gives us the following result: 123456.jpg

I’ll leave it as an exercise to the reader to figure out how to calculate the appropriate filenames for different schools and situations. Hopefully, these two examples serve as a useful starting point.

Assuming you’ve gotten this far, there is still a minor problem here. The issue is that although we have successfully generated a filename, for this to work in the end we also need to know the location of the image in the computer’s file system. This means we need to adjust the formula to also indicate the file’s “path.”

To take care of this on your end, you’ll need to follow either Step 3a or Step 3b below, depending on which operating system you’re using.

Step 3a: Add the Full Path to the Image (Windows)

First, make sure all your images are in the same folder.

Then, if you’re using Windows, you can get that folder’s location by selecting one of the images in the computer’s file browser, right-clicking on that file, and choosing “Properties” from the context menu.

In the Properties window that should appear, look for the “Location” field. In the example above, the location is displayed as C:\Users\dan\Desktop\students. You should be able to highlight this location with your pointer, right-click, and select “Copy.” Then, you can temporarily paste it somewhere in your spreadsheet or another document to refer to later.

One you’ve pasted that location somewhere, you’ll need to add an additional backslash to the very end. Now, it should look something like this: C:\Users\dan\Desktop\students\

Now that you have properly formatted the location, you can use it to update the image formula in your spreadsheet. For example, when using Windows, my own updated formula looks like this:

="C:\Users\dan\Desktop\students\" & A2 & ".jpg"

And when I hit Enter, the result will look like this: C:\Users\dan\Desktop\students\123456.jpg

Step 3b: Add the Full Path to the Image (macOS)

First, make sure all your images are in the same folder.

Then, if you’re using a Mac, browse to that folder in the Finder. Next, click on any image from that folder, hold down the Option key, and select “Copy [filename] as Pathname” from the Edit menu. This will store the path to the image on the macOS clipboard. In order to use this stored path, you’ll need to temporarily paste it somewhere in your spreadsheet or another document.

In my case, when I paste the path from the clipboard, it looks like this: /Users/dan/Desktop/students/123456.jpg.

This is actually more information than we need, and for it to work in InDesign, the formatting needs to be adjusted. To get this cleaned up, start by removing the filename (e.g. “123456.jpg”) from the end of the line. Then, remove the slash from the very beginning of the line. Finally, change all the remaining slashes into colons. In my example, the end result would look like this: Users:dan:Desktop:students:

If you’ve done it correctly, there will always be a colon at the end of the line!

Now that you have properly formatted the location, you can use it to update the image formula in your spreadsheet. For example, when using macOS, my own updated formula looks like this:

="Users:dan:Desktop:students:" & A2 & ".jpg"

And when I hit Enter, the result will look like this: Users:dan:Desktop:students:123456.jpg

Step 4: “Auto-Fill” the Image Formula

Okay, sorry for the bifurcation of Step 3. From here on out, the steps are all the same, regardless of your computer.

So the next thing we need to do is take that formula we just created for our first row of data and copy it into the rest of the rows. To do that, just double-click the little box that appears in the bottom-right corner of the cell. (I’ve circled it in the screenshot below.)

You can do the same thing in Google Sheets, but instead of a square, you’ll be double-clicking a little circle in the corner:

This convenient operation is called “Auto Fill,” and the end result should look something like this:

Step 5: Give the Photo Column a “Special” Title

If you’re paying close attention, you may have wondered whether I “forgot” to label the column with my file paths. The truth is I decided to make this its own step because you need to do something a bit unusual here.

In order for InDesign to recognize a column as a list of image file paths (rather than ordinary text), the column’s label needs to begin with an “at sign” (e.g. “@Photos”). So in theory, our spreadsheet would need to look like this:

Google Sheets will have no problem with this, but Excel will get upset and pop up an error message if you try to do that.

The problem is that the @ symbol has a special purpose in Excel. Thankfully, we can get around this by adding a single apostrophe to the very beginning of our entry: '@Photos. This apostrophe tells Excel to treat the entire cell as ordinary text. After you press Enter, the apostrophe will be hidden, and you’ll just see @Photos. At this point, your spreadsheet should resemble the example above.

Step 6: Export Your Data

Now that the data is all set up, we need to save it in a format readable by InDesign.

Unfortunately, InDesign can’t read native Excel files. So we’ll need to use something more generic: CSV, which stands for “Comma-Separated Values.” A CSV is just a plain text file representing a table of data where each row appears on its own line and each column is—you guessed it!—separated by a comma. The first row of a CSV typically includes the names for each column. And that’s really all there is to it.

Because this is such a basic file format, it’s actually rather easy to create a CSV using Excel or Google Sheets. In Excel, go to the File menu and choose Save As. The Save dialog will look a little different depending on what operating system you are using and what version of Excel you have. But somewhere in there, you should see an option to choose the file format.

What you see in the list of options may also vary, but one of them should be named something like “Comma Separated Values (.csv)” or “CSV (Comma delimited)” depending on your operating system, Excel version, and which type of Save As dialog you’re looking at. (As you’ll see in a moment, Microsoft’s conventions are remarkably inconsistent.)

Note: Don’t choose any option that looks like “CSV UTF-8 (Comma delimited) (.csv)”—even if it appears higher up in the list or is labeled a “Common Format.” It won’t work! InDesign can only read a standard, “old school” CSV file. And yes, I learned this the hard way.

Here’s what the selector—and the proper choice—looks like in Excel on my Mac:

And in Windows, it may look like either of the following:

Regardless of what your Save As dialog looks like, give the file a name, make sure CSV is selected, and click “Save.”

If you’re using Google Slides, the process is a little more straightforward. First, go to the File menu. (Make sure you’re using the Google Sheets app’s File menu—the one that appears at the top left of the webpage itself—rather than your browser’s File menu. If you don’t see it, it’s possible that your menus are hidden. In that case, try clicking the little down arrow that appears at the end of the Google Sheets toolbar, or you can press Ctrl+Shift+F to toggle between hidden and unhidden states.)

With the File menu open, hover over Download and choose Comma Separated Values (.csv). Depending on your web browser, the file should begin downloading right away, or you may be asked what you want to do with it. I trust that you know how downloads work in your browser, so do what you need to do.

Step 7: Find or Create a Design for Your Slides

We’re done with data and formulae. Now, it’s time to get creative! This step is all about figuring out the background for your slide. You don’t have to put any student information or photos on the slide yet; you just need to add any colors, designs, or boilerplate text (i.e. static information, like the school or organization name) that you want to appear in the same spot on every slide.

You can create your slide from scratch directly in InDesign, or you can use a pre-made design.

For example, when I created my NHS induction slideshow, I really wanted to use this template from Slidesgo since I had used it for some previous NHS presentations. Unfortunately, Slidesgo templates only work in Google Slides and PowerPoint. My solution was to use the template to create a single slide in Google Slides with nothing on it except for the background design. Then, I downloaded that otherwise “blank” slide from Google Slides as a PDF. Finally, I created an InDesign file with the same dimensions as the PDF (10 × 5.63 in.) and just placed the PDF right onto the canvas.

Note: If you decide to do something like this, double-check the template’s license agreement to make sure you’re allowed to use the content in that way, and be sure to follow the content creator’s rules for attribution. For instance, Slidesgo requires non-paying users to include their provided “Credits” slide at the end of the presentation.

Whether you create your own or start with someone else’s design, make sure (for now) that your InDesign file has only a single page. (If you need to add an attribution slide, you can do that later.)

For argument’s sake, let’s say that you decided to create your slide from scratch and that it looks something like the following…er…masterpiece:

In this example, I want the blue-ish background, the star with the organization’s initials, and the event name to appear on every slide. So I’ve created a single-page InDesign document with just those details.

Step 8: Import the Data into InDesign

We’re getting pretty close to the end here, but before we can go any further, we need to import the spreadsheet data that we exported earlier. To do this, go to InDesign’s Window menu. Then, hover over Utilities and choose Data Merge. An unassumingly small—but powerful—panel should pop up. On my machine, it looks like this:

The panel pretty much tells you exactly what you need to do. But for now, let’s just follow Step 1: “Choose Select Data Source from the panel menu.” What it’s actually asking you to do is to click the button with the horizontal lines (sometimes referred to as a “hamburger menu”) in the top right corner of the panel. Then, you should see a menu option labeled “Select Data Source…” Choose that option. A file browser should appear. Use it to find the CSV file you created earlier, and finally click the “Open” button.

If the data was properly exported, the Data Merge panel should now look something like this:

You should see a row for each of your fields. The “T” icon indicates a text field and the photo icon indicates, of course, a photo!

Step 9: Turn Your Slide into a Template

Back in Step 5, we took care of the static data—the stuff that appears on every slide without changing. Now, we need to add placeholders for dynamic data—the stuff (like student names and photos) that change on each slide.

To do this, you have to start by creating a text box for any piece of textual data you want to include. In my example, I only have one piece of textual data (the student’s name), so I’m just going to create a single text box. For the moment, you don’t need to put anything in your text boxes. They just need to exist.

Now, go back to the Data Merge panel, and use your mouse to click-and-drag each of your desired fields (i.e. each piece of dynamic data) into the appropriate text box.

I’m going to start by dragging the filed labeled “First” into the box. As soon as I let go of the mouse, it shows up inside the box as <<First>>. I also need to include the student’s last name in that box, so I’m going to drag in the “Last” field as well. Now, I have <<First>><<Last>>. The final step (for me) is to add a space between these two fields so that the name isn’t all jumbled together. The result looks like this: <<First>> <<Last>>.

Note: Even though what you see on the screen may look like ordinary letters and angle brackets, you can’t just type in your field names. As Adobe explains in their own tutorial, you must drag the fields into the box.

After you’ve added your text fields, you can apply any formatting you’d like. I, for one, need to make the text much larger than the default font size and apply the proper color. You can do this the same way you’d style any other text in InDesign. One thing to keep in mind is to make the text box as wide as you think it will need to be to accommodate the longest names on your list.

Here’s what my text box looks like with the fields added and the appropriate formatting applied.

Once the text has been taken care of, you can add any photos you need to include. In my case, I just want to have a single image (the student’s portrait) on each slide.

Similar to before, the first step is to add an empty frame to the document.

And again, just like before, you’ll drag your photo field from the Data Merge panel right into the frame.

One thing to be aware of is that if you are editing the document in InDesign’s “Preview” screen mode, you won’t get much obvious visual feedback to confirm that you’ve successfully linked the field to the frame. However, if you switch back to “Normal” mode, you should see the name of your field (e.g. <<Photos>>) appear inside the frame.

Also, regardless of which mode you’re using, a little “1” will appear next to the field name in the Data Merge panel to indicate that something on Page 1 has been linked to it.

So feel free to look for either of those indicators to confirm that the photo field has been appropriately linked.

Step 10: Preview the Dynamic Data

Okay, time for the moment of truth. Let’s see if all of this worked!

Go back to the Data Merge panel and click the “Preview” checkbox in the bottom left corner. If all has gone according to plan, the placeholders on your slide should now show the actual text for the first person on your list. You should also, hopefully, see that person’s photo in your image frame.

You can use the forward and back arrows in the Data Merge panel to browse additional entries. This is a good way to make sure all the data fits correctly and that the correct photos have been associated with each name.

If it looks like one or more of the boxes are too small, you can make some adjustments right on the preview. (Note: If you’d rather not make a change to everyone’s slide, you can edit just that student’s slide when the whole process is complete. I’ll mention this later!)

If something doesn’t seem right (e.g. the data is mis-matched or the images don’t work), go back to your spreadsheet and see if you can figure out what went wrong. If you make any changes, just save the data as a CSV again using the same filename as before. Then, go back to InDesign, click on the hamburger menu in the Data Merge panel, choose “Update Data Source,” and see if everything links up correctly this time.

Step 11: Generate the Slides from Your Template

If you’re liking how things look in your preview, then it’s time to generate your slides.

You can start this process in either of two ways:

• Click on the hamburger menu in the Data Merge panel and choose “Create Merged Document…”
• Click the button (with the little arrow and some squares) that appears right below the hamburger menu. (If you hover your cursor over the button before clicking, you should see a tooltip that says, “Create Merged Document.”)

Regardless of which way you do it, a new dialog box should pop up.

I was able to use the default settings. But just in case, make sure your settings look like the example above. Specifically, start by making sure the “Records” tab is selected at the very top. Next, under “Records To Merge,” make sure that “All Records” is selected. It is also vital that “Records per Document Page” be set to “Single Record.” (This setting is the one that ensures that we end up with a separate slide for each student.)

It’s not strictly necessary, but I also recommend checking the boxes labeled “Generate Overset Text Report with Document Creation” and “Alert When Images Are Missing.” These options will help you figure out if any of your slides will need some manual fixes (i.e. to remove overset text or deal with a missing photo).

Note: If you click on the “Options” tab, you can access a few additional settings concerning things like image placement, how to handle empty fields, and whether to limit the number of records per document. I stuck with the defaults for all of these, but you may want to take a look at the options just in case they’re relevant to your use case.

Once that’s all set up, go ahead and click “OK.” If you checked those two boxes I mentioned earlier, you might see a popup about missing images or overset text. Otherwise, when all is said and done, InDesign should have opened a new document, and each page of that document should be an individual student’s slide. Congratulations! You’ve generated your slideshow!

Step 12: Clean Things Up and Export to PDF

At this point, we’re basically done. However, you may need to make some individual adjustments to slides. For example, maybe you still have a student or two with a long name that got cut off. Now that you’ve generated the full slide deck, you can tweak those individual students’ slides without affecting the others. Or perhaps you chose to use a commercially available template that requires an attribution slide at the end. Now would be a good time to add that in.

When everything looks good and the slideshow is ready to be shared, the last step is to export it to PDF. This way, you can still display it even if the computer connected to the projector (or to a Zoom call) doesn’t have InDesign. (It would, however, be very helpful if that computer has a copy of Adobe Acrobat Reader, though other PDF-compatible applications may also work.)

So anyhow, to export to PDF, you’ll click on the File menu, hover over Adobe PDF Presets, and choose High Quality Print. (If you have some other preset that you’d prefer to use, that’s totally fine.) Choose a filename and location when asked. If you chose “High Quality Print,” you probably don’t need to change any settings when the options dialog appears. But feel free to look things over to ensure they make sense for your use case.

When you’re ready, click the “Export” button.

Wrapping Up

While a dozen steps, complete with copy/pasted file paths and awkward Excel formulae may seem like a lot of work, this pales (in my personal opinion) in comparison to the drudgery that would otherwise be required to create each individual slide, copy over the template for each student, type out or paste in each student’s name, find each student’s photo, and finally drop each of those photos onto the appropriate slides—especially as the group gets larger and larger. (Remember, my NHS induction included over 100 kids!)

When the time comes to present your slideshow, I think the easiest thing to do is to open the PDF in Adobe Acrobat Reader. In the View menu, make sure that Page Display is set to “Single Page View.” Then, in the View menu again, select Full Screen Mode. (Alternatively, you can press Cmd+L on a Mac or Ctrl+L in Windows.)

Now, you should be able to page through the slideshow the same way you would in Google Slides, PowerPoint, or Keynote: just tap the spacebar, use the arrow keys, or click the mouse. Hopefully, whoever is in your audience will be super impressed by all the work you obviously must have done to create 100 carefully personalized slides!

Postscript

While doing some research for this blog post, I came across a Microsoft support page noting the existence of “two known add-ins for PowerPoint that can help you merge data from an Excel workbook into a presentation file.” That support page leads to a forum post from 2017 that ultimately links to the following two plugins:

• Simple Merge, available for $19.99
• PPT Merge, available for $69.95

I can’t vouch for either of these tools or the people/companies that appear to be selling them. They both come from websites that look to be super-outdated, and it’s a little unclear from some of the information provided as to whether these plugins still work in the latest versions of PowerPoint or on the latest Windows operating systems. (One thing that’s clear is that neither of them work on a Mac.) But since Microsoft itself made a reference to them, I thought I should include them here in the interest of completeness.

Additionally, I also found a trio of blog posts on a site called Spreadsheet Dev that discuss how to use Google Apps Script to merge data from Google Sheets into presentations in Google Slides. These solutions require some actual coding, so they’re definitely not for everybody. It also looks like they’re only designed to work with text, not images. That said, I fully intend to try out this guy’s techniques and then see if I can tack on the ability to handle images. I’ll report back on this project in a future blog post.

Until then, may you merge merily!

When Apple announced that it was transitioning its computers to “Apple Silicon” processors, there was a lot of angst in the tech community over what this meant for virtualization on the Mac.

Because Apple Silicon processors (such as the M1 and M2 series) are based on the ARM architecture, it’s impossible to run software compiled for the x86 processors like those Intel and AMD are generally known for today. When Apple started releasing their new computers, this meant that retail versions of Windows, many Linux distributions, and other “legacy” operating systems could neither be installed natively on those machines via Boot Camp nor run via virtualization software such as Parallels.

The situation has improved somewhat since then. For one thing, the latest version of Parallels can automatically install a compatible version of Windows 11.

Meanwhile, an open source project called Asahi Linux has devised a method for natively booting an Arch Linux-based distribution on M1 and M2 Macs.

Over the past few months, I’ve successfully tested both of these solutions, but during this time, I also began to get curious about a seemingly less popular workaround to the virtualization problem: emulation.

Whereas virtualization allows multiple guest machines to share the hardware of the same host machine, emulation uses software to mimic a completely different set of hardware. This makes it possible to run x86 software, for instance, on a computer with an ARM processor—albeit with a notable performance cost.

The Problem

My first experiment with emulation on an M1-based Mac was an attempt to run MS-DOS using an app called UTM, which is essentially a graphical front end for the venerable QEMU emulator.

I documented this successful project in a tutorial and was even eventually able to run an old game, SimCity 2000, with fully functional sound and graphics.

After letting that project sit for a while, I decided to come back to it and try installing Windows 3.11 on top of DOS in the same emulated environment.

As I expected, this worked just fine, but it got me wondering about what other fun blasts from the past I might be able to run on Apple Silicon via emulation.

For instance, is it still possible to run the “classic” MacOS, an operating system that runs on yet another processor architecture—namely, PowerPC?

I had accomplished this once or twice before on an older Mac using a purpose-built emulator called SheepShaver, but until now had not investigated whether the tools exist to do it on a newer machine.

The Objective

At bare minimum, for this project to be successful, I wanted to be able to boot some version of the classic Mac operating system. My preference would be a release from the MacOS 9.2.x series since these are the final and essentially most “complete” standalone editions of the software. (This is the same reason I went with MS-DOS 6.22 for my previous project.) That said, anything from the 9.x series would be acceptable.

Now, installing an operating system is useless if you can’t do anything with it. And while there’s plenty of abandoned Mac software available on the internet if you go searching for it, finding anything ultimately requires, well, the internet! So a secondary goal would be to actually be able to browse the web using this emulated machine.

The Solution

Path #1: SheepShaver

It turns out that not only is SheepShaver still around, but there’s actually a version out there compiled for Apple Silicon!

There’s really a community for just about anything out there somewhere on the internet, and classic MacOS emulation is apparently one of them. In this case, it’s E-Maculation, a wiki and forum “dedicated to emulation of the classic Macintosh computer in MacOSX/macOS, Windows and Linux.”

The E-Maculation site hosts versions of SheepShaver built for “modern” editions of the Mac operating system dating back to version 10.4 and for all the different processor architectures these have ever worked on (i.e. PowerPC, x86, x86_64, and of course ARM64).

The latest builds are all linked to this forum post. (Here’s a direct link for the version I used.) That post also links to this wiki page with instructions on how to set it up, which is a bit more complicated than one might expect.

For instance, in addition to downloading the application, you also must download a copy of the SheepShaver folder. (This is mentioned on the form post, but I missed it the first time.) Then, you have to put into that folder a copy of the SheepShaver application as well as a ROM file (i.e. an extracted copy of the firmware for an actual Mac compatible with whatever version of MacOS you are trying to run). Neither the forum nor the wiki provide links to download a ROM due to legal concerns, but the wiki page does provide some pretty clear instructions on where you are likely to find one. Finally—and this should be fairly obvious—you need a disk image for an actual MacOS installation disk. They don’t tell you where to find one of those either, but there are a number of websites that specialize in archiving old software. I’ve learned a lot about what’s out there via a site called WinWorld. Just sayin’…

One significant limitation of SheepShaver is that—at least according to all the documentation I’ve seen—it only works for versions of MacOS up to and including 9.0.4. I couldn’t get the emulator to boot from a 9.2.1 install image, so I’ll take that as confirmation.

However, as you’ll see in just a moment, it is possible run later versions of MacOS, such as the 9.2.x series, via a different emulator.

Path #2: UTM

Despite the way I’ve laid out this article, I actually looked into UTM first, mostly because I had already spent a lot of time playing around with it while trying to install MS-DOS.

As I mentioned earlier, UTM is basically a wrapper for QEMU, which would otherwise need to be configured using complicated and sketchily documented command line arguments. (I also understand, based on my research, that the UTM developers incorporate some tweaks/patches to QEMU itself when they feel it’s appropriate.)

The nice thing about QEMU is that it can emulate a ton of different hardware, with plenty of architectures, processors, computer types, and peripheral models to choose from. I had never seen anything before about using QEMU to emulate old, PowerPC-based Macs, but apparently it does have this trick up its sleeve. A quick web search, in fact, brought me to this blog post, which provides a pretty thorough tutorial for how to configure UTM (and thus QEMU) to do it.

The tutorial works, with some caveats.

First, because the post is about a year old (as of September 2022), the instructions and screenshots are based on an older version of UTM. Some of the options and configuration pages have changed. And while the screenshots accurately portray the necessary settings, some of them seem to be skipped or glossed over in the instructions, so I ended up missing a few things the first time through.

That blog, however, included a link to the E-Maculation forum (which is actually how I first found it). As the blogger himself notes, UTM has only a small presence there—just a single thread, as far as I could tell—whereas SheepShaver and QEMU itself get entire categories. Nevertheless, that single thread led me to a GitHub repository with pre-configured UTM setups for every version of MacOS dating back to 9.1. It’s way easier to just download one of these and go from there. You just double-click the file, point UTM to your MacOS disk image (have I mentioned that WinWorld is a great source of information about old operating systems?), and click the run button.

You do have to make a small adjustment to the configuration after you finish installing, but the repository maintainer has set up the config files so that the instructions for this show up right there in UTM. Very clever!

The Outcome

What I can conclude from this experiment is that there are at least two pretty viable ways to get classic MacOS to boot (inside an emulator) on a Mac powered by Apple Silicon. Thanks to the existence of pre-built configurations and the fact that you don’t need any special firmware files, UTM is a great choice, particularly if your goal is to run MacOS 9.1 or higher. Meanwhile, despite being a little finicky to set up, SheepShaver remains a reasonable option for running earlier versions.

But what about that second goal—the one about browsing the web? Well…it’s complicated.

What I learned is that whether you install MacOS 9.0.4 in SheepShaver or MacOS 9.2.1 in UTM, you will get access to ancient copies of Internet Explorer (versions 4.5 and 5.0, respectively) and even…Netscape, but neither of these gone-but-not-forgotten browsers are going to be of much use. They’re both so old that they can’t even communicate with most modern web servers. And the reason for this, interestingly enough, is security.

In the two decades or so since MacOS 9.2.1 was released, newer and better encryption protocols have been introduced to ensure that our connections to web severs remain sufficiently private. In the interest of backwards compatibility, even as server administrators adopted these newer protocols, they usually left many of the older ones in place—which could be beneficial if you happened to be using, say, a 25-year-old computer. However, now that we are firmly in the 21st century and very few people are actually still using 25-year-old computers, the oldest of those protocols are rarely still available—and many websites don’t even allow un-encrypted connections anymore!

Out of the box, both the setups I explored could connect to Google’s homepage without problems. (The rendering left something to be desired, but that’s beside the point.)

Unfortunately, most other URLs I tried to visit resulted in errors because the server could no longer communicate using the types of encryption that the ancient browsers were fluent in.

That said, there is some good news on this front. For many years, a guy by the name of Cameron Kaiser maintained a very special browser called Classilla. As you might guess from its name, Classilla is a fork of Mozilla, the open source browser that succeeded Netscape and eventually gave rise to Firefox. This fork was specifically designed to work in classic MacOS. And because it traces its roots back to a version of Mozilla originally released in 2008, it is at its core five to seven years “newer” technologically than the last compatible versions of Netscape and Internet Explorer, respectively. Plus, it continued to received functionality improvements until the project was officially retired in 2021!

That’s the good news. The bad news is that even Classilla can’t handle the encryption protocols (namely, TLS 1.2 and 1.3) that dominate the World Wide Web of 2022. However, all hope is not lost. The final version of Classilla published before the browser was mothballed includes support for a wonky workaround named Crypto Ancienne. (Yes, that’s French they’re speaking…)

The Classilla website provides setup instructions and download links for Crypto Ancienne here. But because nothing can be easy, those downloads only work in some of the oldest versions of Mac OS X or in an obscure Unix-like virtualization environment for classic MacOS called Power MachTen. I understand the reason for this—since the whole point is to be able to use this browser on really old computers—but it doesn’t help me here. Thankfully, the source code for Crypto Ancienne is available on GitHub and, I can report, can be compiled rather effortlessly on an Apple Silicon Mac.

In order to follow Classilla’s “official” instructions, I also had to track down and compile the source code for a tool called micro_inetd. The micro_inetd program runs on the host computer and listens for requests for encrypted websites coming from Classilla. It then passes those requests on to a program named “carl” (yes, carl), which does all the heavy lifting. Together, these two components act as a rudimentary proxy server—a sort of middleman that (in simplified terms) sends the request out to the desired website’s server, translates the encrypted response into plaintext, and then relays the unencrypted data back to Classilla.

This is horribly insecure, but it does get the job done.

With this monstrosity of an internet setup in place, I was finally able to surf the web unimpeded. Well, sort of…

Web standards, especially CSS (responsible for layout) and JavaScript (responsible for all kinds of client-side fanciness), have evolved so much since the days of 2008 that in a great many cases, what Classilla ultimately renders on the page is an absolute mess.

By default, Classilla attempts to masquerade as the browser built into a Nokia “flip-phone” from 2005, but even this doesn’t really help. Thanks to advances in responsive web design and the ever-increasing power of modern smartphones, it is no longer all that common for websites to serve a completely different, stripped-down version of their content to mobile users. This means that what we’re left with, no matter what browser Classilla pretends to be (and it gives you options), is quite often unrenderable gobbledegook.

So what have we learned from all this? Well, for one thing, we’ve learned that it’s definitely possible to run three different web browsers in various versions of MacOS 9 via two different emulators running on macOS 12 on an Apple Silicon-powered laptop.

We’ve also learned that it’s possible (with some effort) to use one of those browsers to contact a modern web server and actually get back a response.

And as long as you don’t expect to actually be able to read that response, surfing the web like it’s 2001 can be a thoroughly rewarding experience!

Now, suppose the epitome of 90s-era technology for you is taking a trip to your dad’s office in the big city, where his corporate computer was just better enough than the crummy one at home that you could reliably use it to play a really cool new game—namely, SimCity 2000. And finally, suppose you’d like to fulfill your craving for nostalgia by playing that game, which was designed for MS-DOS (an OS created in the 80s) on your brand new MacBook Pro (which was released in 2021).

Well, there’s a problem. Actually, a few problems (not the least of which is that I have too much time on my hands).

First, you can’t run MS-DOS on a Mac. Apple computers are designed to run macOS and macOS only. Okay, that’s not technically true. Ever since Apple switched to Intel processors, their Boot Camp tool has made it possible to run various versions of Microsoft Windows on their machines. And with a bit of finagling, you can install Linux distributions and other operating systems. Apple just doesn’t provide any support for it.

So…why not MS-DOS? The simple answer is, I’m not sure; I’ve never actually tried it. My suspicion is that it’s just too old. But even if it were possible at some point in time, it’s not anymore (at least, as we will soon see, not natively).

In 2020, Apple announced that over the next few years, they would transition their entire computer lineup away from the Intel processors the company had been using for the past decade. Instead, Macs would now be powered by a souped up version of the home-grown processors that Apple had been using in their iPhones and iPads for many years.

On the one hand, this was great news. Apple’s smartphone processors were known to be very powerful and energy efficient, and early reviews of the desktop/laptop versions confirmed that Apple’s tech was, in many ways, miles ahead of the competition. This played a big role in my decision to buy one of Apple’s new machines.

On the other hand, Apple’s decision posed a problem for oddballs like me that find it amusing to get their computers to do things they weren’t technically designed to do (like running operating systems that aren’t macOS on an Apple computer).

Here’s the problem: Intel’s modern, consumer-oriented processors (as well as those manufactured by its primary competitor, AMD) use an architecture often referred to as “x86_64.” This architecture has at its foundation the same basic instruction set, the collection of routines and commands baked into the processors’ circuitry, as the Intel processors (e.g. the 386, 486, and Pentium) used in the original “IBM-compatible” personal computers that dominated the 1980s and early 1990s—in other words, the kind of computers you can run MS-DOS on. (The The “64” in the name refers to how the architecture has been extended to support modern, 64-bit computing.)

Apple’s M-series processors, meanwhile, are built around an architecture or instruction set known as “ARM.” Trying to run software compiled for an x86-based processor (like MS-DOS or even most versions of Windows) on an ARM-based processor is like trying to drive a car on the ocean or attempting to breath without scuba gear underwater; the most basic assumptions about the environment are completely different.

Unfortunately, this incompatibility is so foundational that even popular tools for creating virtual machines, like Parallels or VMWare Fusion, won’t do the trick.

Virtualization software lets you share a singe host machine’s resources amongst several simulated client “machines,” but that only works if those clients can understand the host’s language and exist in the host’s hardware environment in the first place. So if you wanted to run, say, Windows in a virtual machine on a Mac with an M1 processor, you’d need a version of Windows that was built for ARM-based processors. This does actually exist—it’s what Microsoft uses in many of their Surface laptops and tablets—and you can install it in Parallels with just a few clicks.

But if you want to use your brand new MacBook Pro to run SimCity 2000 in MS-DOS, which is definitely not ARM-compatible, you need more than just virtualization. What you need is an emulator.

Objective

Unlike virtualization, which is used to share existing resources, emulation uses software to mimic (or pretend to be) a particular set of hardware that is not physically present.

In the following tutorial, I’m going to walk you through how to use an emulator to run MS-DOS on a Mac. (Incidentally, the same tools will also work on an Intel-based Mac.) I’ll also walk you through installing some drivers and tweaking a few settings to make it a bit more convenient to use and to ensure that you can actually install and run a fancy-shmancy late-era DOS game like SimCity 2000.

I recognize that the objective here is super niche. But it turns out it’s so niche that I actually struggled to find a good set of instructions for this. So in addition to providing an opportunity to talk a bit about processor architecture and the difference between virtualization and emulation (because, let’s face it, I’m a teacher and I love explaining things), hopefully this article can also serve as something of a definitive guide to this particular (albeit weird) task.

Materials

I tested this tutorial on my M1-based MacBook Pro. You should be able to follow it on any other M-series laptop or desktop as well. The software we’ll be using should work on Intel-based Macs too, but I haven’t explicitly tested it yet.

Besides the computer, you’ll need a few more things to get this to work:

• Emulation Software: We’ll be using UTM. This app bundles QEMU, an open source emulator that has been around forever, and extends it by providing a convenient user interface. You can buy UTM for for $9.99 on the App Store or download it for free from the developer’s website. You’re getting the same app either way; it’s just a question of whether you want to give some monetary support to the people behind it.
• MS-DOS Disk Images: The 100% most legal way to obtain these disk images is to create them from your own set of physical MS-DOS installation disks. What? You don’t have DOS installation disks lying around? Who are you?? Alright, look: I’m not going to just give you a link to pirated software. But if you’re the sort of person who figures some lawyer out in Redmond, WA is not going to come banging on your front door because you downloaded a piece of ancient software that no one is actually selling anymore, then I have one word for you: WinWorld. Do with that what you will. Oh, and if you’re trying to track down those, um, physical disks in your basement, I’ll point out that the version you really want to be on the lookout for is “MS-DOS 6.22 Plus Enhanced Tools,” and it would be mighty convenient if you used the version that comes on 3.5″ diskettes. (However, props to you if you manage to find some working 5.25″ floppies in your basement!)
• Drivers: At bare minimum, playing around with DOS will be a lot easier with a working mouse and the ability to mount CD-ROM images since so many programs and games were distributed that way. There are several drivers to choose from and a bunch of places where you can find them. I recommend going to Computer Hope and downloading oakcdrom.sys and mouse.zip. Put them somewhere safe, and I’ll explain what to do with them later!

Note: A more automated (and thus “easier”) way to run old DOS games in just about any operating system is a well-known emulator called DOSBox. I acknowledge the existence of this app and have even played with it myself. The following tutorial is for folks who want to get their hands a bit dirtier and experience the full process of installing and configuring the genuine MS-DOS operating system (plus an emulator) from scratch.

Step 1: Create a Virtual Machine

So we’re going to start by opening up the UTM app. If you’re running it for the very first time, it’ll probably look something like this:

Click on the box labeled “Create a New Virtual Machine.” Now, you should see two options: virtualize or emulate.

As we discussed earlier, for this project to work, we need to use an emulator, so go ahead and choose the “Emulate” option.

Next, it’s going to ask you what kind of operating system you want to install.

Since MS-DOS is definitely not on the list, we’re going to select “Other.”

Now, UTM should be asking us for a Boot ISO Image.

What it’s looking for is an image of a CD or DVD to install from, but we don’t have one of those. So we’re just going to click the checkbox next to “Skip ISO boot.” The screen should now look like this:

Go ahead and click “Continue.”

The next page asks about hardware.

The default settings are too modern for us, so we’re going to make a few adjustments:

• Architecture: The default is “x86_64,” which describes the architecture of modern Intel and AMD consumer processors. This might work just fine since they are theoretically backwards-compatible with their predecessors, but just to be safe, let’s change this to “i386 (x86).” This should get the emulator to more closely mimic the less fancy processor architecture from the 80s and 90s.
• System: This setting tells the emulator what kind of chipset to mimic. Essentially, we’re telling it what sort of motherboard the pretend processor is being plugged into. By default, UTM wants to use a system that is once again too modern for us. We’re going to change it something based on much older components: “Standard PC (i440FX + PIIX, 1996) (alias of pc-i440fx-7.0) (pc).”
• Memory: If we don’t change this, the emulator will try to allocate way too much memory for our virtual machine. MS-DOS 6.22 can only recognize up to 64 MB, so let’s set this number accordingly.
• CPU Cores: I assume that “Default” means just one processor core, but just to be safe, let’s manually change that to “1.”

When all is said and done, our hardware settings should look like this:

Once again, let’s click “Continue.”

The following page asks us how large a virtual hard drive we want to create.

Although the default number is actually too large for DOS to handle, we’re going to leave it alone for now. UTM uses this setting to automatically create a virtual hard drive. Unfortunately, when using some older versions of UTM, I found that this drive got corrupted every time I shut down the machine. So just to be safe, we’re going to manually create the virtual hard drive later and attempt to adjust one of the advanced settings. For now, just click “Continue.”

The next page is titled Shared Directory.

This functionality is designed to make it easier to share files between our host machine and our virtual machine, but I’m not convinced this is possible within MS-DOS. We’re just going to skip it and click “Continue.”

The final page shows us an overview of all the settings we chose.

There are two thing we should do here. First, let’s give the machine a more useful name, like “MS-DOS.” Then, we’re going to check the box labeled “Open VM Settings” because there are several more adjustments we need to make.

Once that’s done, we can click “Save.”

Step 2: Do Some Additional Configuration

We should now be looking at the virtual machine settings interface.

We’re going to use this to adjust some more “advanced” settings to ensure that our VM works as expected. Let’s start by clicking on System in the sidebar.

You’ll see some of the settings here that we chose earlier, but we’re going to make one additional adjustment. Right now, under, CPU, it should say “Default.” I’m not sure what kind of processor this machine actually defaults to, so we’re going to choose something more specific.

Let’s set the CPU to “486.”

Launched in 1989, the Intel 486 processor is the oldest piece of hardware on this list and was still in use when MS-DOS 6.22 was released in 1994.

Next, let’s click on QEMU in the sidebar.

On this page, we’re going to first uncheck the box labeled “UEFI Boot.” This will disable the more modern startup system that current computers use and force the virtual machine to use the legacy system that’s been around since the days of MS-DOS.

Then, just to be safe, we’re going to check the box for “Force PS/2 controller.” This will make extra certain that DOS is able to respond to our mouse and keyboard by ensuring that the machine emulates the PS/2 ports that these components used to plug into back before USB.

The settings should now look like this:

Everything else on this page can be left as is.

Now we’re going to go to the Input page.

On this page we need to disable USB support. I’m not sure why this makes a difference, but all I know is that every time I tried to use DOS’s built-in file editor, the program would crash as soon as I tried to open a menu to save what I was working on. For some reason, once I disabled USB support, this stopped happening.

So, next to where it says “USB Support,” go ahead and select “Off.”

The next page we’ll take a look at is Sound. I have not yet tried to get sound to work, but my guess is that we should set the Emulated Audio Card to “Creative Sound Blaster 16” since that was a pretty typical device from the era.

The last thing we need to do is set up the virtual drives. At the bottom of the sidebar, you’ll see a section labeled “Drives.” Go ahead and select the first one.

I mentioned earlier that UTM tries to automatically create a drive for us but that my testing found that this drive doesn’t work correctly. So we’re going to remove it by clicking the “Delete Drive” button.

Once we click that, the page we were looking at should disappear.

Now we need to select “New Drive” from the bottom of the menu, which should cause a little panel to pop up.

We’re going to start by creating a virtual CD-ROM drive. So check the box next to “Removable” and make sure that the interface is set to “IDE.”

Next, click “Create.”

The drive should now show up at the bottom of the menu. If you click it, you should see this:

Make sure the Image Type is set to “CD/DVD (ISO) Image” and the Interface is set to “IDE.”

Now, we’re going to create a virtual floppy disk drive for our virtual computer. Click on “New Drive” again in the sidebar, and choose the exact same settings as before. Then, be sure to click on the newly created drive (the one at the bottom of the list). Your screen should now look something like this:

In order to make this virtual drive mimic a floppy drive, we need to change a couple settings. First, we need to set the Image Type to “Disk Image.” Second, we must change the Interface to “Floppy.” Our new settings should look like this:

Notice that our drive’s entry at the bottom of the menu has changed to say “Floppy Drive.” Perfect!

We have one last virtual device to create before we can fire up this virtual machine: the hard drive. Let’s click on “New Drive” one last time. But this time, we’re going to use some different settings. We’re going to leave the “Removable” box unchecked and make sure the interface is set to “IDE.” The size should be set no larger than 2 GB because MS-DOS 6.22 cannot recognize anything bigger than that.

Finally, we’re going to check the box next to “Raw Image.” This is the key setting that prevents the corruption issue I talked about before. (By default, UTM tries to save space on the host computer by creating a relatively small file to represent the hard drive and then growing it as additional space is needed. Something about this breaks our MS-DOS installation, so by selecting the “raw” option, we create a file the actual size of the hard drive which never needs to change.) The appropriate settings should look like this:

Note: Version 2.1.6 of UTM appears to have a bug that prevents the “Raw Image” checkbox from working. (It’s possible that other versions have this bug as well; I haven’t tested this extensively.) If you can’t check the box, don’t worry about it. The original bug that led me to include this step in the first place seems to have been fixed in more recent versions. I tested a virtual machine using the default settings in Version 2.1.6, and it worked just fine!

Once you’ve got your disk image configured, go ahead and click “Create.”

Now, if we click on the new drive in the menu, it should look something like the image below. (If you were unable to create a “Raw Image” due to the bug described above, your screen will look a little different. But based on my testing, it should still work.)

We are finally finished configuring the virtual machine, so let’s click the “Save” button in the bottom right corner.

Step 3: “Insert” Your Virtual Installation Disk

We should now be on a screen that looks something like this:

(If not, make sure the virtual machine is selected in the sidebar.)

We’re just about ready to actually get DOS running, but we’ve got just one more little step: We need to virtually insert our virtual installation disk into our virtual floppy drive.

To do this, we either need to make UTM’s window bigger or scroll down to the bottom of the page so that we can see two drop-down menus. One is for our virtual CD-ROM drive, and the other is for our virtual floppy drive. I’ve circle them in the screenshot below.

Click on the drop-down that says “Removable” and choose the “Browse…” option. This will open a file browser, which you can use to find your first MS-DOS disk image. My set came with three, so I’m going to choose the file named “Disk1.img.”

Once you’ve selected your disk image, its filename will show up next to the drop-down menu. (Look at the bottom-right corner of the image below, and you’ll see that it now says “Disk1.img.”)

Step 4: Launch the Virtual Machine

Note: We’re about to start up the virtual machine. If at any time you discover that your mouse has gotten “stuck” in the virtual machine’s window, press the CTRL+ALT or CTRL+Option keys on your keyboard to “release” it.

Okay, it’s time for the moment of truth! I count three different “play” buttons you can click to start this virtual machine. Any of them will work, but let’s use the one in the toolbar at the top of the window. (It’s the one shaped like a triangle.)

After we click the button, a new window will pop up. This window is our virtual machine’s display. You should see some status messages flash across the virtual screen, and eventually, the MS-DOS installer will appear. You’ll know it’s working if you see some classic gray-white text on a blue background.

Step 5: Install MS-DOS

All we need to do now is press the Enter key, just like the instructions on the screen say, which should bring us to the following screen:

This step is telling us that we need to format the virtual hard drive. We just need to make sure “Configure unallocated disk space” is selected and press Enter again.

We’ll now see this helpful message informing us that the computer is about to reboot. (Remember: This is referring to the virtual computer.) It also says to “make sure Setup Disk 1 is in drive A.” We can feel pretty confident that this is already the case; otherwise, we would have never made it to this step!

Press Enter one more time so that the installer can do its thing.

The virtual machine should reboot, and you should soon see a progress screen while the hard drive is formatted. Eventually you’ll get to a screen asking you to confirm some settings:

Make sure the Date/Time, country, and language are correct. (Remember that you can only use the keyboard to navigate this interface, so you’ll have to use the arrow keys.) Then, select “The settings are correct” and press Enter.

Now, the installer is going to ask you where to actually install everything.

I actually find it pretty interesting that you can put your DOS files wherever you want, but for simplicity’s sake, let’s just stick with the default (“C:\DOS”). All we need to do here is press Enter.

Now, we should see a progress bar as files are copied to the virtual hard drive. Eventually, the progress will halt because we need to switch to the next install disk.

To switch the disk, we need to click the little icon in the toolbar that looks like a CD. This should pop up a drop-down menu. Hover over “Disk Image” and choose “Change.” This will open a file browser where you can find your next disk. Mine is called “Disk2.img.” Once the disk is selected, you can press Enter, and the installation should continue.

You will likely have to switch disks one more time before it’s over. Eventually, you’ll see a screen telling you to remove all floppy disks from their drives.

To eject the virtual floppy disk, go to that same menu we used to swap disks and choose the “Eject” option.

Once the disk is ejected, we can press Enter. The installer will essentially say good-bye to us and instruct us to press Enter one last time.

If we follow its directions, our virtual machine should reboot. And finally, if all has gone to plan, we should be greeted by the famous MS-DOS command prompt:

I take it all back. You really can run DOS on a Mac!

Step 6: Take a Trip Down Memory Lane

I could just end this tutorial here, now that I have sort of proved a point. But the real goal of this exercise was to be able to play a childhood computer game. So I’m going to walk you through a few more configuration steps.

We’re going to start by setting up extended memory. DOS originally could only deal with 640 kilobytes of memory, which is…not very much at all. As software applications got bigger and more complicated, and as newer hardware was developed to accommodate them, DOS needed to follow suit. However, DOS’s original memory limitations never technically went away. Microsoft and other developers basically just found ways to work around them.

Explaining DOS memory management is probably beyond the scope of this tutorial, and frankly, I don’t fully understand it myself. But you can get an idea of what I’m talking about by typing in mem at the command prompt and pressing Enter.

What this screen shows you is that DOS still only has 640K of “conventional” memory available. (It actually shows up as 639K in my VM. I’m sure that extra 1K is used for something important.)

All the rest of our memory is listed as “Extended (XMS)” memory. This memory exists because DOS 6.22 is set up by default to load a special driver, called HIMEM.SYS, that works some magic to make all this extra memory available.

Let’s take a look at where it happens by typing in edit config.sys at the command prompt and pressing Enter. This should open up the beautiful (and very blue) MS-DOS file editor.

We’re looking at a file named CONFIG.SYS that lives in the root directory of the hard drive. At some point in DOS’s boot-up sequence, it loads this configuration file and follows the instructions contained within. Lines beginning with “DEVICE=” are used to load drivers that control system functionality. One of those drivers is HIMEM.SYS, which I mentioned above.

This HIMEM.SYS does a good job at sort of opening up access to the expanded memory, but apparently, if we want to actually use that extra memory, we need to load what’s called a memory manager. Fortunately enough, Microsoft includes one with DOS; they just don’t enable it by default. So we’re going to add the following line to the file immediately after the one for HIMEM.SYS:

DEVICEHIGH=C:\DOS\EMM386.EXE ram highscan notr i=b000-b7ff

We’re heading into some serious magic code territory here. The most important piece is DEVICEHIGH=C:\DOS\EMM386.EXE. This loads the expanded memory manger into the “high” memory area enabled by HIMEM.SYS. The rest of that gobbledegook is a series of options to tweak some aspects of how the memory manager operates. I borrowed those options from this incredibly informative tutorial, so if you want to know what they actually do, I would encourage you to check it out.

Anyway, once you’ve edited the file, it should look like this:

Next, we need to save our changes and exit the editor. If you’re using a Windows/PC keyboard, you’ll press ALT+F to open the file menu. If, like me, you’re using a standard Mac keyboard, you’ll need to press Option+F instead. (Apple’s Option key always corresponds to the ALT key.)

You should see the menu pop open like so:

Now, you can use the arrow keys on your keyboard to navigate to “Save” and then press Enter. Or, you can speed things up by half a second and just press the S key. (Notice how it’s been highlighted to let you know that this is the shortcut.)

We should now open the file menu a second time (ALT+F or Option+F) and choose “Exit,” which will take us back to the command prompt.

To see if our changes worked, we need to reboot the computer. On a PC keyboard, we would press CTRL+ALT+DEL to reboot. On my full-length Mac keyboard (the kind that includes a numeric keypad all the way on the right), I can hold down CTRL+Option and then press the forward delete key (the one that appears above the arrow keys in the little cluster between the main keyboard and the numeric keypad). If you’re using a small Mac keyboard that doesn’t have a forward delete key, you’ll need to hold down CTRL+Option+Fn and then press the regular Delete key.

If you’ve properly performed the so-called “three-fingered salute” (though I guess it’s a four-fingered salute on small Mac keyboards), the virtual machine should reboot and eventually take you to a new command prompt.

We can test whether our changes worked by typing mem once again, pressing Enter, and inspecting the output:

A couple things have changed: my missing 1K of conventional memory has actually returned, and now we see this note about how EMM386 is using XMS memory to simulate EMS memory. We don’t need to worry too much about what that nonsense means, but you can read up on it in the tutorial I linked above if you want.

We’re going to make one more change now to ensure optimal memory management. We’re going to type in edit config.sys again and press Enter so that we can tweak one of the lines in the file.

Find the line that says DOS=HIGH and change it to say DOS=HIGH,UMB. (“UMB” stands for “Upper Memory Block.”)

The actual details of what that does are a little hairy, but if you save the file, reboot the virtual machine, and run the mem command again, you’ll see that we now have some “Upper” memory available, more memory available “under 1 MB,” a larger “largest executable program size,” and a “largest free upper memory block” of 27K instead of 0.

These all seem like good things, so let’s move on!

Step 7: Manage the Power

So, I had no idea about this when I was a kid fooling around with DOS, but apparently the operating system actually has some power management features built in. I don’t know much about what they do, but I did learn from the tutorial I’ve mentioned a couple times that it’s a good idea to turn them on if you’re running DOS in a virtual machine. Apparently, this will prevent the virtual machine from using more of your host machine’s processing power than it needs to.

To do do this, we’re going to—surprise!—edit the config.sys file yet again. By now, you should know how to do this. So I’m just going to tell you to add the following line right after the one for EMM386.EXE:

DEVICEHIGH=C:\DOS\POWER.EXE adv:min

The file should look like this before you save it. Once you’re back at the command prompt, go ahead and reboot the virtual machine again.

You should now see a new piece of information show up after all the status messages indicating that the Power Manager has loaded.

Although that’s all you’ll ever see on the screen, I can confirm that this does actually do something. Prior to adding this command to my CONFIG.SYS file, the virtual machine was using 100% of my processor (according to Apple’s Activity Monitor) even when I wasn’t doing anything with it. Once I saved the config file and rebooted, the number dropped to the single digits. I certainly don’t want to make my computer work harder than it needs to, so I’m glad I discovered that tip.

Step 8: Create a Virtual Floppy Disk

Okay, things are progressing nicely. We now have a functional machine with some basic memory management and even power management in place. Wouldn’t it be nice if we could actually install some programs on this thing?

Well, to do that we need a way of actually getting stuff onto the machine. The most logical method would be to mimic the way we’d do this in 1995: a blank floppy disk!

To create a blank floppy, let’s open up the Terminal app on the host machine (in my case, my MacBook Pro).

Now, we need to type in the following command:

dd bs=512 count=2880 if=/dev/zero of=/Users/[username]/Desktop/floppy.img

Note: You’ll need to replace [username] in the command above with your actual macOS user name. If you’re not sure what your name is, just type whoamiin the terminal and hit Enter.

This command basically copies a whole bunch of zeros into a file the exact size of an old 3.5″ diskette (which, incidentally, could hold 1.44 megabytes of data—something I find just wild when I think about how many gigabytes of data I can fit on one of the tiny SD flash cards we use for the cameras in my journalism classroom). The file should appear on your desktop.

This disk image we’ve created is unformatted; we can’t do anything with it yet. So let’s format it!

The first step is to insert it (virtually) into our virtual machine. Just like when we were installing DOS, we can click on that little icon in the virtual machine’s toolbar that looks like a CD, hover over “Disk Image (floppy)” and choose “Change.” This time instead of an installer, we’ll choose the floppy image that now lives on our desktop.

Before you move on, double-check that the disk was selected correctly by clicking the icon again and making sure the name of the new disk (“floppy.img”) shows up in the menu.

Now, let’s return to the DOS command prompt. We’re going to format our blank disk by issuing the following command:

format a:

After you press Enter, you should a message asking us to insert a disk. (It turns out we’re one step ahead of things.)

Press Enter one more time to begin the procedure.

The machine will churn for a bit and then ask for a label.

Call this disk whatever you’d like (as long as it fits within 11 characters), and press Enter. (I’m feeling creative, so I’m going to call it “My Disk.”)

When you see the prompt asking whether to format another disk, press N followed by Enter.

Now, we should be back at the command prompt.

Step 9: Access the Virtual Disk in macOS

Now that we have a (virtual) blank floppy disk at our disposal, we can use it to start adding some files to the virtual machine.

To place files on our virtual floppy disk, we start by double-clicking the icon on our host machine’s desktop.

This tells macOS to mount the disk contained within the image file. On my computer mounted disks show up on my desktop like this:

Depending on how you have your computer set up, you might need to locate the disk in the macOS Finder. But however you do it, go ahead and open that disk.

Step 10: Add Some Drivers to the Disk

Okay, do you remember those two drivers I had you download back in the Materials section of this tutorial? It’s time to finally do something with them!

The first file was oakcdrom.sys. Let’s find this file and add it to the empty disk.

The other thing we downloaded was mouse.zip. When we unzip this file, we get mouse.com. Let’s put this on the disk, too.

Now, let’s go back to the virtual machine and try to access the drive.

At the DOS prompt, type in A: and press Enter. The prompt should change to A:\>

Now, if we enter the dir command, we should see the two files that we added:

Let’s copy these two files into the DOS folder. After typing in each of the following lines, press enter:

copy oakcdrom.sys c:\dos
copy mouse.com c:\dos

Then, type in C: and press Enter to switch back to the hard drive (also known as Drive C).

Now, let’s go edit CONFIG.SYS again by typing edit config.sys and pressing Enter.

After the line for EMM386.EXE, but before the line for POWER.EXE, add the following line:

DEVICEHIGH=C:\DOS\OAKCDROM.SYS /D:MSCD001

This will tell the computer to load the CD-ROM driver into high memory. The bit at the end gives the device a name. I’m not entirely sure why, but “mscd001” seems to be the standard name used in pretty much every reference I’ve read, so let’s go with it. The file should now look like this:

Let’s save the file and exit back to the prompt.

Next, we need to edit a different configuration file: AUTOEXEC.BAT. This is less a configuration file and more like a script. (Technically, if we’re using DOS parlance, it’s called a “batch” file.) AUTOEXEC.BAT is essentially a startup file; it’s a series of DOS commands that the operating system issues right before it turns things over to the user.

So let’s edit the file by typing edit autoexec.bat and pressing Enter.

We’re going to add two lines to the end of this file:

LH C:\DOS\MSCDEX.EXE /D:MSCD001 /L:D
LH C:\DOS\MOUSE.COM

LH is as shortcut for the LOADHIGH command, which work similarly to DEVICEHIGH in CONFIG.SYS. It attempts to load a program into the high memory region (rather than the low or “conventional”) memory region. The idea is to keep the conventional memory (the first 640 kilobytes) as clear as possible to make more room to load actual applications.

Whereas OAKCDROM.SYS is a third-party driver that tells the computer how to talk to the CD-ROM hardware, MSCDEX.EXE is a program included with MS-DOS that helps the operating system read the actual data on the CD. The part of the line that begins “/D:” refers to the name we added in the CONFIG.SYS file. The part that says “/L:D” tells the computer to assign letter D to the CD-ROM drive.

Meanwhile, MOUSE.COM, as the name might suggest, is a mouse driver; it lets the computer respond to input from a mouse.

With these two lines added, the file should now look like this:

We should now save the file and reboot the virtual machine. If we look carefully at the status messages that show up while the machine is starting up, we should see indications that an Oak Technology CD-ROM driver, the Microsoft Power Manager, the MSCDEX program, and the Microsoft Mouse Drier have all been loaded.

We can see that the mouse actually works by trying to edit a file again. Let’s type in edit autoexec.bat and press Enter. Now, see what happens if you move your mouse around or play with your laptop’s touchpad.

(If nothing notable happens, you may need to tell the virtual machine to “capture” the mouse. You do this by clicking the first icon on the right side of the virtual machine’s toolbar—the one that looks like a mouse pointer with some lines around it. Now try moving the mouse around.)

With any luck, you should see a square-shaped box moving around the screen. You can use this cursor to select different locations in the file just like you would in a modern-day word processor. You can even use it to open the different menus at the top of the screen and select the various commands. Let’s go ahead and use the cursor to click on the File menu and select Exit.

(Reminder: If your cursor gets stuck inside the virtual machine, press CTRL+ALT or CTRL+Option to release it back to your host computer.)

Step 11: Have Fun!

Our basic DOS system is finally all set up. All that’s left is to install any of our favorite programs and, well, have at it!

In my case, I’ve been wanting to play SimCity 2000. My father bought the game for me some 25 years ago, and I just so happen to have an image file for the CD-ROM the game would have originally come on. Now that the virtual machine has a working CD-ROM driver, I can use the DOS command prompt to access this virtual CD.

First, I need to “insert” the CD. I’ll do this using that same icon in the toolbar that we’ve used a few times now to access floppy disks. This time, I’m going to hover over “CD/DVD (ISO) Image” and select “Change.” Then I’ll find the disk image on my host computer and select it.

One the disk is selected, I can type D: at the command prompt and press Enter. Then, I can type dir and press Enter to view the contents.

For some reason, it takes a really long time for the virtual machine to read the virtual CD the first time. I don’t know why, but it does eventually work.

From here, I can see that there is a file named INSTALL.EXE, which is presumably the game’s installer. So, I’ll go ahead and type install, followed by Enter, to run it. (DOS will attempt to run any file that ends with .EXE or .COM, even if you don’t type that part in.)

And here’s the installer! It pops up this weird error message about not having enough RAM, which is not true. The good news is, I’ve tested this and the program works anyway.

After following all the instructions in the installer, I’m dropped back to the command prompt.

The installer automatically puts me in the game’s directory (or folder). If it didn’t, I could return to the hard drive by typing C: and then enter the program’s folder by typing cd\sc2000. (Here are a couple helpful primers on DOS commands if you’re new to the operating system or need a refresher.)

Finally, I’ll run the main program (SC2000.EXE) by entering sc2000.

And…

…it works!

If you have a game or other program on a CD you’d like to access, go ahead and try it. If your application comes on a floppy, then you’ll access it the same way we did our blank floppy. And if you have the application files themselves, but they’re not on a CD or floppy image, then you can add them to the floppy image that we created together to load them into the virtual machine.

Wrapping Up

If you’re not sure what to do next, I suggest some Googling. There are a number of archives of old DOS software out there on the internet. As I think I made it clear earlier, I don’t condone piracy, but the good news is that many programs have been officially placed into the public domain by their original authors, were available for free in the first place, or are considered “abandonware,” which means no one is really responsible for them anymore. (As always, proceed at your own risk, both in terms of the legal implications of your decisions and the possibility of obtaining viruses and other malware from random stuff on the internet.)

If you’re interested in a serious deep dive into the land of MS-DOS, complete with internet connectivity (of a rudimentary sort), command prompt customization, more advanced memory management, and then some, do check out the LegRoom.net tutorial that I’ve cited a few times. If you’re feeling especially bold, you can even try installing Windows 3.1 on top of your DOS setup. (I haven’t done it on this computer yet, but I’ve managed it in the past.)

As for me, my next step may be to figure out if I can get sound working—and then maybe I’ll move on to Windows

If you’ve made it this far, you’re definitely a trooper. Now go build yourself some virtual skyscrapers!