Weird install experience with ESP-Prog (But it's all good. I think.)

PlatformIO IDE
1

Hi all,

I’m curious about what I just did. Please let me know if this makes any sense.

I’ve had an ESP-PROG board for a while, but I’ve merely used it as a USB-to-serial adapter. I never installed any drivers; the default Apple drivers have been fine. My Mac is running OSX 11.2.3 (Big Sur). Plugging in the ESP-Prog causes four new entries to appear in my dev directory:

/dev/cu.usbserial-14300
/dev/cu.usbserial-14301
/dev/tty.usbserial-14300
/dev/tty.usbserial-14301

The second one down has always worked fine with the six-pin “program” header on ESP-Prog board, for both program upload and serial monitor.

–

Today I decided to try out the JTAG interface.

So, I dutifully read the PlatformIO page:
ESP-Prog — PlatformIO latest documentation

Which directs me here here for driver information:
https://www.ftdichip.com/Support/Documents/AppNotes/AN_134_FTDI_Drivers_Installation_Guide_for_MAC_OSX.pdf

Which discusses installation of new VCP drivers, and a D2xx driver. It says the D2xx driver can’t do its thing if the VCP drivers assert the hardware first (also mentioned on the PlatformIO page), so there are a few options for disabling the VCP drivers. I opted to install their ‘D2xxHelper.kext’ utility, which simply blocks them. I did not install their new VCP drivers, since the ones I have seem to be working fine, and I assumed I’d be blocking them anyway.

After installation, sure enough the /dev/ ports stopped showing up but the “System report” still showed new USB FTDI hardware when the ESP-Prog was plugged in. Good so far.

Then I installed the D2xx driver.

I configured platformio.ini and tried ‘run/Start debugging.’ It worked great the first try.

But, my serial monitor was no more, and a bit of snooping on this forum & elsewhere suggested that folks were configuring the serial monitor like I had it originally: using the second port provisioned by the VCP drivers. Hmm?

So… I wondered if I really did need that ‘helper’ thing, and removed it.

My /dev/ ports showed up again, debugging still works, and now I have my serial monitor back.

So… now I wondered if I’d really needed that D2xx driver. Uninstalled; rebooted…

And everything still works.

So I should’ve just tried it first without reading the instructions. What a waste of time :-).

I’m guessing that the current PlatformIO code doesn’t use the D2xx driver (probably has the code static linked); and perhaps they’ve overcome this issue with the VCP drivers asserting the hardware first.

So it works. I’m happy.

But does it make sense? Am I missing something? Have other folks with OSX 11 had the same experience? Could it be I have a driver installed somewhere that I don’t know about? How could I tell?

Or, maybe the PlatformIO page ought to have a line that says “just try it first, before you go installing all this crap.”

-Matt

2

Out-of-the-box, macOS includes FTDI drivers for the serial port. That’s why they show up without further installation. The FTDI chip on the ESP-Prog provides two serial interfaces, thus there is /dev/cu.usbserial-14300 (using the same pins as the JTAG interface) and /dev/cu.usbserial-14301 for the dedicated RX/TX pins.

Forget the /dev/cu.tty... devices. They are an ancient thing for dial-in via a modem connected to your system.

Even without these drivers, any application can communicate with USB devices if they haven’t been grabbed by the system like USB mass storage devices or opened by some other software. So again, no driver installation needed.

PlatformIO uses this generic USB communication for debugging (or rather OpenOCD, which is run in the background, uses it). No drivers needed.

Linux would be similar, except you need to take care of permissions. Windows is very different: it uses heavy-weight driver installation and you need to explicitly configure each USB interface (like the two interfaces of the FTDI chip).

3

PlatformIO uses this generic USB communication for debugging …

Okay.

Why then does the PlatformIO page say the following?

macOS contains default FTDIUSBSerialDriver driver which conflicts with debug tools which are based on this chip. FTDI Chip company recommends removing this default driver from a system.

This seems to contradict what you’re saying, doesn’t it? Is that page, perhaps, out-of-date?

4

I just had another look at the FTDI application note referenced on the PlatformIO page.

It’s dated almost six years ago for one thing.

And, on page 9 it says:

Starting with 10.11 (El Capitan), Apple’s own driver seems to be sufficiently comprehensive that many customers will not need to install FTDI’s own VCP …

OSX 10.11 was released in 2015. I’m sure that the vast majority of Mac users these days will have a newer OS than that. I recommend that the PlatformIO page be updated to reflect this.

Perhaps, under “Drivers”, replace tthe “Mac:” paragraph with something like this:

On OSX 10.11 or later, ESP-Prog should work with Apple’s default drivers. If you encounter problems, or have an earlier OS, see this technical note for updated VCP drivers. Note: you do not need to install the D2XX drivers mentioned within. “AN134: FTDI Drivers Installation guide for MAC OS X” (link: http://www.ftdichip.com/Support/Documents/AppNotes/AN_134_FTDI_Drivers_Installation_Guide_for_MAC_OSX.pdf).

Is this the best place to make such a recommendation? …if not, where should I make it?