The basis of an SDrive-Max is an Arduino UNO.
Compared to a "Genuine" UNO R3 (top), the clone (bottom) is not very different. Most obvious is where the Genuine UNO has a large socketed DIP package for the Mega328, the clone has the chip in a much smaller package. This opens up space on the board for what I wanted: solder pads for each pin and an extra set of headers. Since the LCD shield is going to occupy all the pins, these extra pads make a good place to attach the SIO cable. Otherwise, I would have had to attach them underneath the board.
This is a "HiLetgo" UNO clone I got from Amazon for less than 10 bucks.
Connect USB to the UNO. It lights up, but as expected, there's no serial device present on my computer after doing so. The chipset driver needs to be installed. Unplug the device for now.
This UNO uses a CH340 serial driver. This is the first step down a rabbit hole of software installations, so let's just follow it.
OS X Software
We need to have certain things installed. OS X gives us a terminal program and a lot of other command-line utilities for free, but we have to go out of our way to install some more.
As a note, the starting point for this guide is a fresh install of OS X 10.13 (High Sierra) in a VMWare Fusion virtual machine. The only software installed are the current updates from the App Store and the VMWare Tools package. Otherwise, the starting point is as vanilla and out-of-the-box as possible.
We don't need the whole giant multi-gigabyte XCode development environment installed, we just need the "XCode Command Line Tools" which include utilities and compilers used at the Terminal.
A quick way to get these installed is to open a Terminal and enter the command gcc. This is a compiler command that doesn't exist, and the system tells us so:
xcode-select: note: no developer tools were found at '/Applications/Xcode.app', requesting install. Choose an option in the dialog to download the command line developer tools.
Additionally, the system generates a pop up asking if we'd like to install the command line tools. Select the "Install" button and accept the license agreement. The installation is pretty small and doesn't take long.
After the install completes, press "Done" and enter the following command in the Terminal. The output should match what's shown here:
$ xcode-select -p
I'll be honest. I dislike downloading a bunch of little disk images and running installers for a bunch of things. You never really know what you have or where it went. Linux systems have "package managers" for this sort of thing. There are a couple of projects that bring similar functionality to OS X, incuding macports and homebrew. These are package managers that (1) know how to install a whole bunch of software, (2) know how to keep it updated, and (3) lets you keep track of what you have. I choose Homebrew.
Install Homebrew with this Terminal command:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
I don't like this method of installing software, and if you don't either, then you can browse the Homebrew web site (https://brew.sh) and investigate alternative installation methods. This script method is fast and direct, though.
The Homebrew install script starts by showing you what directories and binaries are being installed. Notice that everything listed is prefixed by /usr/local meaning it's not putting stuff all over the system. Instead, it's staying in one location. Press Return to continue and enter your OS X user password to allow the changes.
A lot of stuff happens that takes a few minutes but it should work out just fine. You'll know it's done when it's done.
Test it out by typing brew list. This won't show anything but it doesn't produce an error either. This command lists all the software that Homebrew has installed, so you can always take a look.
CH340 Serial Driver
With XCode and Homebrew taken care of, we can take the next step in our adventure and install the CH340 serial driver for the UNO clone. There are roughly one million references to this driver from all sorts of places on the 'net, and if you want to go this route and install the thing from some disk image package somewhere, go for it. In this guide, we're using Homebrew.
The driver we're installing is a repackage of the OEM driver available at GitHub but the great thing about this guy is he's made it available through Homebrew too.
The command brew tap lets you manage repositories from which Homebrew may find the software you ask for. This command adds the place we'll find the CH340 driver:
brew tap mengbo/ch340g-ch34g-ch34x-mac-os-x-driver \
The command brew cask installs a piece of software. The "cask" means that's it's a special piece of software, like a GUI or other kind of specialized program, like a CH340 serial driver. The distinction isn't important here.
brew cask install wch-ch34x-usb-serial-driver
This command fetches the driver and installs it. You'll need to provide your OS X password again to allow it. Functionally this is not different to downloading a PKG file and running the installer, but now Homebrew manages it.
You may get a popup saying that an extension was blocked. Follow the on-screen prompts to open the "Security & Privacy" preference pane to "Allow" the driver to work.
Once Brew is done installing, it'll tell you:
installer: Package name is CH34x_Install
installer: Installing at base path /
installer: The install was successful.
installer: The install requires restarting now.
wch-ch34x-usb-serial-driver was successfully installed!
So, restart the computer and prepare for the next phase. If all goes well you'll get no error messages or popups.
After the restart, open a Terminal window and plug in the UNO board. We're going to look for the UNO's serial port now. Issue the following command and check that output:
$ ls /dev/*usbserial*
The listing that starts with "tty" is the one we're looking for. The fact that it's there means we're on the right track.
The SDrive-MAX Repository
Next we'll install the thing about which there is all this fuss: the SDrive-Max repository.
Open a Terminal and make sure you're in your home directory (which would be the default landing spot for a Terminal). You can issue the command pwd (Present Working Directory) and get a response like /Users/yourname and be satisfied you're in the right place.
Now retrieve the SDrive-Max repository using git, a popular source code tool that's built into OS X:
git clone https://github.com/kbr-net/sdrive-max.git
There'll be some output then you'll be back at the prompt. Enter the directory and "check out" the correct version, like it was a book at a library:
git checkout V1.1
This switches the repository to the version 1.1 of the SDrive-Max. Developers use tags like this like bookmarks to keep track of things. In the future, if there was a new version you'd check that one out instead.
Before we can build the SDrive-Max stuff, we need to turn back to Homebrew briefly and install a couple of things to make this possible:
brew install xa
brew install avrdude
brew cask install crosspack-avr
The package "xa" is a 6502 cross-assembler we'll need to build SDrive-MAX, and "avrdude" is the tool that writes firmware files to the Arduino.
The "crosspack-avr" cask should have everything else we need to continue. Enter your password when prompted. At completion, a browser window may open to a page about CrossPack, which you can read or dismiss. Once you're back at the Terminal window, we'll move ahead.
The "crosspack-avr" cask essentially installs the same package you could download from the CrossPack site, and you could also install individual items through HomeBrew. This would include "avrdude", "avr-gcc" and "avr-binutils" but you'd have to tap an extra repository to get most of these.
After installing the CrossPack, you need to restart the Terminal (not the computer). Just "exit" and start a new Terminal, again making sure you're in your home directory. Then get back into the SDrive directory and "make" the software.
The make command goes out and does all the work, and builds all the things. It should complete successfully and the output should resemble the following and at least not include anything that says "Error".
AVR Memory Usage
Program: 30872 bytes (94.2% Full)
(.text + .data + .bootloader)
Data: 1497 bytes (73.1% Full)
(.data + .bss + .noinit)
EEPROM: 321 bytes (31.3% Full)
Software Phase Complete
That's it for software. Now it's time to install it on the UNO.
Flashing the Arduino
First things first, disconnect the Arduino and attach the display shield.
I'm using the Elegoo 2.8" TFT Touch Screen which has the "ili9341" chipset. It fits perfectly atop the Arduino.
Plug the Arduino back into the computer. The screen will light up but won't say anything because it's got nothing to say.
The screen chipset is important, because the SDrive-Max supports a handful of different ones. In the previous section, the "make" command went through and created builds for all of them.
In the "sdrive-max" directory, enter this command to list some stuff:
$ ls -d atmega*
atmega328-hx8347g atmega328-ili9329 atmega328-ili9341
These are all combos that SDrive-Max supports. "atmega328" is the chipset on the Arduino, and the other part is the chipset of the screen. Since I have the "ili9341" screen, I want to enter the matching directory "atmega328-ili9341".
There are two files we're interested in within this directory, shown below.
$ cd atmega328-ili9341
$ ls *.hex
The first file to load is the eeprom_writer.hex. We use the next command to do it:
avrdude -p m328p -c arduino -P /dev/tty.wchusbserial1710 -U flash:w:./eeprom_writer.hex
This command has a few pieces to it, so let's break it down. Note that capitalization matters and this is all case-sensitive -- "-p" is not the same as "-P":
"avrdude": the program we installed with HomeBrew that will program the Arduino.
"-p m328p": the AVR "part" so avrdude knows what it's working with. The chip on the Arduino is a "ATMEGA328P" and the token for this is "m328p" according to avrdude.
"-c arduino": the "programmer" type. We have an Arduino, so this should be self-explanatory.
"-P /dev/tty.wchusbserial1710": the serial port used to communicate with the device. We identified this thing earlier after we installed the serial driver. This will be different on your system.
"-U flash:w:./eeprom_writer.hex": I'm not sure what "U" means but this option tells avrdude what to actually do. There are three parts to the command but they're not in natural order. The command is "w" (write) to "flash" memory on the device the contents of the ./eeprom_writer.hex file (the './' prefix tells avrdude to look in the current directory for that file).
When you execute this command, two things happen: one, avrdude does the thing, and two, you'll see the thing happening on the Arduino's screen.
The avrdude output looks like this:
avrdude: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.02s
avrdude: Device signature = 0x1e950f (probably m328p)
avrdude: NOTE: "flash" memory has been specified, an erase cycle will be performed
To disable this feature, specify the -D option.
avrdude: erasing chip
avrdude: reading input file "./eeprom_writer.hex"
avrdude: input file ./eeprom_writer.hex auto detected as Intel Hex
avrdude: writing flash (3646 bytes):
Writing | ################################################## | 100% 1.77s
avrdude: 3646 bytes of flash written
avrdude: verifying flash memory against ./eeprom_writer.hex:
avrdude: load data flash data from input file ./eeprom_writer.hex:
avrdude: input file ./eeprom_writer.hex auto detected as Intel Hex
avrdude: input file ./eeprom_writer.hex contains 3646 bytes
avrdude: reading on-chip flash data:
Reading | ################################################## | 100% 1.64s
avrdude: verifying ...
avrdude: 3646 bytes of flash verified
avrdude: safemode: Fuses OK (E:00, H:00, L:00)
avrdude done. Thank you.
The Arduino screen will say "Writing EEPROM..." then "Verifying EEPROM..." and then "Done!" in green letters.
Unplug the Arduino, count to 5, and plug it back in to reboot it before continuing.
The second file to load is the SDrive.hex. The command is similar to the last one, the only difference being the name of the file to write:
avrdude -p m328p -c arduino -P /dev/tty.wchusbserial1710 -U flash:w:./SDrive.hex
The avrdude output is going to look a lot like the last time, but it will take a little bit longer.
When it's done, the screen will have a white calibration crosshair. Use the stylus to press the crosshair center. It turns green and a new one appears. Repeat this for the four corners. Some information text appears in the center of screen. Tap once more to finish calibration and enter the SDrive-Max software.
You're done! All that remains is to attach the cable and plug it in.