MAC OS X 10.15 (Catalina) Fresh + Atom IDE + apio – OsháBlue: Web Log and B-Sides

Table of Contents

This note came out of a few specific installations where the installation methods didn’t quite work to allow Atom IDE / apio-ide (package) to run its commands, like Verify, Build and Upload, etc.

Synopsis: It would be helpful to try the Solution section below, which includes further steps beyond the fix for more readily getting apio path(s) accessed and using a specific apio version too, for this. However, it might still not entirely work in Catalina. That is to be determined. Please let me know how it goes. The work-around for apio==0.4.1 + Atom IDE + apio-ide + Catalina (macOS 10.15.5 used here), for expediency of outcome, was to run through a Windows toolchain, as described in this post. Which you might ultimately want too.

OS: macOS 10.15 (Catalina) – relatively fresh installation (VMWare Fusion VM of fresh Catalina 10.15.5 on a Mac), minimally outfitted with development software, as noted below.

Remember, for programming the hardware, HDL-0108-RSCPT, what needs to be connected to your system (including any VM) is the FTDI USB-SPI (serial) cable. And it needs to have been updated, as indicated here and in the firmware update post, by ft_prog (or equivalent) to have the right description. For the HDL board, the main USB connector needs to be connected to power the board and to run the DacqMan software or whatever else you are using to grab data, but for just programming the CCC/FPGA with a firmware update, it might get confusing if you have both cables connected to your VM, so make sure that just (or at least) the USB-SPI cable is what is connected and active in your VM (assuming you might be using a VM).

Problem

Clicking, for example, “Verify” in Atom IDE (with apio-ide installed) indicated an error that the “apio” executable or script wasn’t found in the path. And also, in that moment, we couldn’t find it anywhere.

Main issue was simply, indeed yes, PATH including (or not) the path for the apio executable/script, and then not being able to go back and find where apio has been installed.

Basically, the first attempt at “pip install -U apio” avoided using sudo during the installation. The script location directory after this first build thus went into a user directory, thus “which apio” produced nothing. And during subsequent installations with sudo (not necessarily recommended, more just a diagnostic or last ditch check), the location of the scripts wasn’t showing in the console output, because packages had already been built. The location was, of course, in the user’s directory in the Python directories in the user’s Library. Multi-tasking and other such things happening, I missed that first console output during the first build of the packages, indicating (most likely) where the scripts went.

There are a lot of work arounds, like adding PATH variable(s) into the Settings area for the package in Atom. We could have searched the whole PC to find the location of the apio executable, assuming that it built ok and was indeed somewhere, like in the user’s Python directory.

Solution

The quick solution for us here was (for better or worse – given perhaps not best practices):

$ pip uninstall apio 
# (caution, before you execute the next line,  
# please read the next few paragraphs to learn about  
# the specific version we are using at the moment) 
$ sudo pip install -U apio  
# (again, caution! read on...)

which simply forced some rebuild (maybe, this is from memory, definitely re-putting the scripts though), and/or otherwise simply installed the scripts, including “apio” in a global directory, “/usr/local/bin” and thus it could be found by the default PATH variables.

Then a simple base installation of Atom IDE and apio-ide worked fine.

BUT WAIT! For our project, this installs the latest version of apio, 0.5.4, or thereabouts, which changes yosys to use .json and uses nextpnr instead of arachne-pnr, which breaks the build of our code right now (May 2020). So instead we want to use:

$ sudo pip install -U apio==0.4.1

which preserves the yosys + .blif + (importantly) arachne-pnr (not nextpnr). We could locate the latest version that still used arachne-pnr (until a code update to function with nextpnr hopefully/perhaps). The current primary dev system is currently running apio 0.4.1 however… for consistency.

Continuing… Even though the above takes addresses one solution to letting Atom IDE find the apio executable, there’s more to get the whole toolchain running…

So, “Verify” and “Build” now function (given the context here). But “Upload” does not, due to (if you don’t see this error, then you already had libusb installed from something else.

dyld: Library not loaded: /usr/local/opt/libusb/lib/libusb-1.0.0.dylib 
Referenced from: /Users/oshablue/.apio/packages/tools-system/bin/lsusb 
Reason: image not found

which is somewhat familiar. So, a quick solution: using Homebrew [see instructions] at https://brew.sh/ to install libusb (btw, apio drivers command for ftdi needs homebrew anyway):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
brew install libusb

And lastly, we do need the ftdi drivers via apio for our project. On Mac OS X these use brew anyway:

apio drivers --ftdi-enable

Good “Upload” to the board works! Maybe. From here, actually some intermittencies. Including such bonus prizes as (output from Upload within Atom IDE):

iceprog -d i:0x0403:6010:0 hardware.bin
init...
Read Error.
ABORT

More: This is being tested on a fresh VMWare Fusion installation of Mac OS X Catalina. It is not clear at the moment if this is due to the fact that this is a VM or if this is due to something interesting with doing this in Catalina, due to macOS-packaged existing libffi and libftdi (what gets installed and maybe used, but definitely not symlinked by the brew installations that are triggered by apio drivers –ftdi-enable). Or maybe due to using apio==0.4.1 on Catalina, etc. So, the work around at the moment, if you encounter this: Try Windows (for now). Please see below, under the Windows heading, or directly at this link.

Caveats

This is a really quick note, just specific to this specific case.

On reflection, the solution regarding the paths used according to use of sudo for apio installation seems obvious. In the heat of the moment, not so much.

There are probably a lot of other ways, better ways to do this. Perhaps other best practices.

You could avoid “sudo” and just add the user’s Python path to, e.g. .bash_profile (or something else, whatever is relevant here, whatever Atom IDE loads), or similar, and then check that Atom IDE was correctly loading the matching environment before it loaded the package. Potentially. BTW, editing “/etc/paths” might work, but that would mean that one was adding a user’s directory to the global paths file, not such a great idea, imho/afaik.

This all applies to setting up development, here specifically, to upload new firmware into the HDL-0108-RSCPT hardware.

References

Snapshot

So the working sequence here, in a snapshot, for better or worse in terms of best practice, on Mac OS X (at least up until upload, see above) was:

sudo easy_install pip
sudo pip install -U apio (WAIT! For our project use: sudo pip install -U apio==0.4.1)
apio install –all
Get the latest Homebrew instruction for installing brew (homebrew) if you don’t already have it installed, then:
brew install libusb
apio drivers –ftdi-enable
Download and set up Atom IDE as an Application and run it
Install into Atom IDE the package apio-ide
(Re-Start Atom IDE)
Clone the repo (if not already cloned or using another)
Step through the “Verify”, “Build” and “Upload” commands, assuming the USB-Serial (SPI) cable has already been programmed to work with this or your use-case (see https://oshablue.com/bsides/2020/05/27/hdl-0108-rscpt-firmware-updates/)

Windows

If trying this on Windows, say for example, the comms to the FTDI USB-SPI (serial) cable, with updated description having used ft_prog, please see this post.