PlatformIO Community

Troubleshooting CH340G issues on macOS

The CH340G USB-to-UART chip is used by a number of inexpensive development boards (e.g. WEMOS and LOLIN branded boards) and USB-to-serial adapters. It is manufactured by a Chinese company called WinChipHead or WCH (International web site, Chinese web site). Unfortunately, it often causes problems on macOS. This guide helps you resolve any problems you might have with the boards and adapters.

CH340G chip

Like all USB-to-Serial solutions, it requires a driver that creates the serial port when the board or adapter is plugged into a USB port of your Mac. The current macOS 10.14 Mojave includes a suitable driver (by Apple). So no additional software is needed.

Main issues

There are three main issues:

  1. Most drivers only work for upload speeds / data rates up to 460,800 bps.
  2. Many users have additional drivers from WCH or Repleo installed, either from earlier macOS versions or because of obsolete tips and instructions on the internet. With the additional drivers, two serial ports will be created and one of them will be non-functional. Furthermore PlatformIO will no longer be able to automatically select the port.
  3. There are many forums and web pages with instructions how to install the WCH driver. Unfortunately, they are obsolete. While they were helpful back then, they now cause additional trouble.

Setup

Do not install any additional software for the CH340G if you are using the current macOS 10.14 Mojave or later. macOS includes a suitable driver. Additional software will cause additional problems.

In your PlatformIO project, add the below line to platformio.ini and you should be ready to upload your sketch:

upload_speed = 460800

If you have an older macOS version and cannot upgrade to the latest version, you can download the driver from here.

How to check the drivers on your Mac

You can check for additional drivers by executing (in a terminal):

ls -l /Library/Extensions

The output will look something like this:

drwxr-xr-x  3 root  wheel      96 Apr 24  2018 ACS6x.kext
drwxr-xr-x  3 root  wheel      96 May  8  2018 ATTOCelerityFC8.kext
drwxr-xr-x  3 root  wheel      96 May  7  2018 ATTOExpressSASHBA2.kext
drwxr-xr-x  3 root  wheel      96 May  7  2018 ATTOExpressSASRAID2.kext
drwxr-xr-x  3 root  wheel      96 Sep  6  2017 ArcMSR.kext
drwxr-xr-x  3 root  wheel      96 Sep  1  2013 CalDigitHDProDrv.kext
drwxr-xr-x  3 root  wheel      96 May  9  2017 FTDIUSBSerialDriver.kext
drwxr-xr-x  3 root  wheel      96 May  4  2018 HighPointIOP.kext
drwxr-xr-x  3 root  wheel      96 Dec  5  2017 HighPointRR.kext
drwxr-xr-x  3 root  wheel      96 Mar 31  2017 PromiseSTEX.kext
drwxr-xr-x  3 root  wheel      96 Apr 25  2018 SoftRAID.kext
drwxr-xr-x  3 root  wheel      96 Jul  4  2018 usbserial.kext

The last entry usbserial.kext is the WCH driver. You should uninstall it (see below).

Apple’s driver is in a different directory. Execute:

ls -l /System/Library/Extensions

The output will include Apple’s driver for the CH340G chip:

...
drwxr-xr-x@ 3 root  wheel   96 Aug 23  2018 AppleUSBCHCOM.kext
...

Another way to check is to plug in a board with the CH340G chip and run:

ls -l /dev/cu.*
crw-rw-rw-  1 root  wheel   18,   5 Sep  7 10:54 /dev/cu.Bluetooth-Incoming-Port
crw-rw-rw-  1 root  wheel   18,   3 Sep  7 10:54 /dev/cu.MALS
crw-rw-rw-  1 root  wheel   18,   1 Sep  7 10:54 /dev/cu.SOC
crw-rw-rw-  1 root  wheel   18,  15 Sep  8 23:09 /dev/cu.usbserial-1410
crw-rw-rw   1 root  wheel   18,  14 Sep  8 23:09 /dev/cu.wchusbserial1410

This is the list of all serial ports. The port /dev/cu.wchusbserial1410 is a clear indication that the WCH driver is installed. You should uninstall it (see below).

The port /dev/cu.usbserial-1410 is from Apple’s driver.

How to uninstall the WCH driver

To uninstall the driver:

  1. Unplug all boards/adapters with a CH340G chip
  2. Execute the following commands to first unload and then uninstall the driver:
sudo kextunload /System/Extensions/usbserial.kext/
sudo rm -rf /System/Extensions/usbserial.kext/

If you remove the driver without first unloading it, you will have to reboot your Mac. If you stick to the order, no reboot is required.

How to limit the upload speed

The CH340G and/or its driver do not reliably work with speeds of 921,600, yet that’s the default in PlatformIO for many boards. So the below line is required in platformio.ini:

upload_speed = 460800

Monitor speed is usually 115,200 and therefore does not need to be changed.

Troubleshooting

The general approach for troubleshooting is:

  1. Uninstall the WCH driver
  2. Limit the upload speed
  3. Reboot

Specific problems

Resource busy: ‘/dev/cu.usbserial-1410’

If a resource busy error, occurs, the selected serial port is most likely blocked by a second driver. Uninstalling the WCH driver (see above) should fix it.

Timed out waiting for packet content*

If a Timed out waiting for packet content error occurs, the upload speed is likely too high. Limit the upload speed (see above) to fix the issue.

4 Likes