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 many 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. Starting with macOS 10.14 Mojave, macOS provides suitable drivers out of the box, implemented by Apple itself. So no additional software is needed.

Main issues

There are three main issues:

  1. Most boards 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 macOS 10.14 Mojave or later (including macOS Big Sur). macOS includes all the required components. 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 for Apple drivers

macOS Catalina, macOS Big Sur and later:

ls -l /System/Library/DriverExtensions/com.apple.DriverKit-AppleUSBCHCOM.dext

should result in something like:

total 40
-rw-r--r--  1 root  wheel   2552 Jun  6  2020 Info.plist
drwxr-xr-x  3 root  wheel     96 Sep 26 11:36 _CodeSignature
-rwxr-xr-x  1 root  wheel  41280 Sep 22 02:45 com.apple.DriverKit-AppleUSBCHCOM
-rw-r--r--  1 root  wheel    535 Jun  6  2020 version.plist

For macOS Mojave, check with ls -l /System/Library/Extensions.

How to check for other drivers

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  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). The same would apply to the driver from Repleo. It’s called osx-ch341.kext.

If you can’t see any of these drivers, also check ls -l /System/Library/Extensions.

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 /Library/Extensions/usbserial.kext/
sudo rm -rf /Library/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.

If you want to remove a different driver or a driver in a different location, modify the command line, e.g.:

sudo kextunload /System/Library/Extensions/osx-ch341.kext/
sudo rm -rf /System/Library/Extensions/osx-ch341.kext/

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.

Checking for the serial port

When you plug in your board, the serial port should appear in /dev and have a name starting with ‘cu.’:

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

This is the list of all serial ports. /dev/cu.usbserial-1410 is the serial port created by Apple’s driver.

If the output however looks like so, there is a problem:

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

Two entries have been created for the same board because two drivers for the CH340G chip are installed. One of the ports will work, the other one will cause an error when a connection is attempted. The solution is to uninstall all non-Apple drivers (see above).

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 or other non-Apple drivers (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.

5 Likes

I just updated to Big Sur, and can no longer connect to my ESP8266s.

Following the discussion above, I saw that there were no ch340 drivers in either directory.

I installed the driver installation from the mfg, and rebooted.

The usbserial.kext driver appears in the /Library/Extensions folder. However there is are no /dev/cu.wcusbserial devices on my system.

I don’t have macOS Big Sur installed yet. But for all I know it includes drivers for WCH CH340, different FTDI chips and Silicon Labs CP2102. They are found in /System/Library/DriverExtensions and are called:

  • com.apple.DriverKit-AppleUSBCHCOM.dext
  • com.apple.DriverKit-AppleUSBFTDI.dext
  • com.apple.DriverKit-AppleUSBSLCOM.dext

The earlier posts referred to macOS versions before macOS Catalina.

What’s the exact error message you are getting? Is the board visible as /dev/cu..... It would likely be named /dev/cu.usbserial-14....

 /dev/cu.usbserial-14120

Success uploading to ESP8266!!!

Thank you so much for your post and help. I can now continue to use the Mac for development.

As an explanation of what I struggled with - I kept looking to connect to a device ‘cu.wchusbserial14120’. I was thinking the Apple driver would implement the dual scheme for the serial port that I was used to seeing… [BTW The Arduino IDE 1.8.10 is unable to obtain board info through this driver.]

Thank you.

If two drivers for the same device are installed, they both create an entry in /dev. But only one will work.

/dev/cu.wchusbserial14120 is the defunct one. I suggest you uninstall the WCH drivers at /Library/Extensions/usbserial.kext.

Then only one entry will be created and PlatformIO will likely pick the right one automatically.

Driver removed. Thank you.

Thanks for excellent write up. Unfortunately its not working for me on macOS Catalina 10.15.7. I’m trying to connect Platform IO to Wemos D1 Mini PRO which has an CH340C. The board is not visible at all under /dev/cu… I cannot find Apple’s driver AppleUSBCHCOM.kext under /System/Library/Extensions and I don’t have any additional drivers installed. it seems Apple made some changes here?

On macOS Cataling already, the driver is under /System/Library/DriverExtensions/com.apple.DriverKit-AppleUSBCHCOM.dext. I’m sure you’ll find it on your system as well.

Since it’s not working, try:

  • Check if the device is visible in the System Report (Apple Menu / About This Mac… / System Report… / Hardware / USB). If it is visible, what are the Product ID and Vendor ID?
  • Use a different USB cable. Some inexpensive USB cables are for power supply only and don’t have the wires for data. Or it might simply be defective.
  • If you are using a USB hub, try different USB ports on the hub.
  • Restart your Mac. If a device draws excessive current, devices stop to work until the next startup. I’m not sure if this is a deliberate features of macOS or rather a partial crash of the USB stack.

Thanks appreciate the help. I flashed the device using Platform IO on a PC so got the software running with no issues. Based on your advice I gave mac another try and I can locate the driver on my system and after connecting the board I can also see the device under System Report. It also shows up under /dev. Must have been an unfortunate combination of two faulty USB cables because I tried connecting using two different mac both running 10.15.7 Catalina and none of them found the device and I was careful not to use a power only USB cable. Anyway I’m back on track now :slight_smile:

Let me try sir! thank you for the knowledge!!!

Hi, a really well written FAQ.
But It is not working for me… damn…
So, I updated my mac from Catalina to Big Sur.
In my

/Library/Extensions/

I removed usbserial.kext. There isn’t file like osx-ch341.kext.

But I’m still not have a /dev/cu.usbserial-1410

Please help me.

Other information:
1] I can see in System Information under USB an idem USBasp.
2] UsbAsp is directly connected to mac using a usb->usbc
3] kernet stat:

➜ ~ kextstat | grep usb
Executing: /usr/bin/kmutil showloaded
No variant specified, falling back to release
20 11 0xffffff80019e2000 0x4000 0x4000 com.apple.driver.usb.AppleUSBCommon (1.0) 62FE0E66-DCCA-3443-B01E-0F0FAB0A820D <6 5 3 1>
62 1 0xffffff80030f0000 0x4f000 0x4f000 com.apple.driver.usb.AppleUSBXHCI (1.2) D623BBDD-59E1-3494-BE57-0F4AFD1CF853 <22 20 13 8 7 6 5 3 1>
63 0 0xffffff8003148000 0x28000 0x28000 com.apple.driver.usb.AppleUSBXHCIPCI (1.2) 279DC1E0-EDF4-3931-83DC-CF11DC249E98 <62 22 20 14 13 8 7 6 5 3 1>
72 3 0xffffff80019e7000 0x6000 0x6000 com.apple.driver.usb.AppleUSBVHCICommon (1.0) AF314B32-BF81-3386-9D5D-9CBE97F38A48 <22 20 8 6 5 3 1>
73 1 0xffffff80030cb000 0x1e000 0x1e000 com.apple.driver.usb.AppleUSBVHCI (1.2) 630BF562-58F3-38DE-B1D7-C96F93B822B4 <72 22 20 8 7 6 5 3 1>
74 1 0xffffff80019ee000 0xb000 0xb000 com.apple.driver.usb.AppleUSBVHCICommonBCE (1.0) 556E19FE-3DA5-3780-A5C9-CB649031C9B8 <72 69 20 8 6 5 3 1>
75 0 0xffffff80030ee000 0x1000 0x1000 com.apple.driver.usb.AppleUSBVHCIBCE (1.2) C28DAF11-2F78-319A-BCEC-82463267126A <74 73 72 69 22 20 13 8 7 6 5 3 1>
106 2 0xffffff8003048000 0x3000 0x3000 com.apple.driver.usb.AppleUSBHostCompositeDevice (1.2) E262EB63-C5DE-39E7-81A8-7D392721EF73 <22 20 7 6 5 3 1>
107 2 0xffffff8001a2a000 0x2000 0x2000 com.apple.driver.usb.networking (5.0.0) 9B5DD9DF-9A0D-31C5-80E0-670D6AFD6EF5 <22 7 6 5 3 1>
108 1 0xffffff80019de000 0x2000 0x2000 com.apple.driver.usb.cdc (5.0.0) B246DA0A-7913-37F2-AB4E-38CD5B154A19 <107 106 22 6 5 3 1>
109 0 0xffffff8001a21000 0x7000 0x7000 com.apple.driver.usb.cdc.ncm (5.0.0) CD9A1845-EEE9-39FF-A333-D36D98037AEB <108 107 106 46 42 22 7 6 5 3 1>
111 0 0xffffff8003052000 0x2b000 0x2b000 com.apple.driver.usb.AppleUSBHub (1.2) 7699C6C9-BEF3-358D-817A-C2F1C8D0DEDD <22 20 13 6 5 3 1>
113 0 0xffffff8003045000 0x2000 0x2000 com.apple.driver.usb.AppleUSBHostBillboardDevice (1.0) 83258EC3-7FF2-36E4-8979-A68499E7BE0B <22 20 6 5 3 1>
114 0 0xffffff8001a2d000 0x3000 0x3000 com.apple.driver.usb.realtek8153patcher (5.0.0) 0C58685F-3662-3A4D-AF8C-8B0AA87D046D <22 6 5 3 1>

It sounds as if you have an USBasp programmer, not a serial-to-USB converter using the CH340G chip.

The USBasp programmer does not offer a serial connection and therefore does not appear as /dev/cu.usb....

What’s the exact hardware you have and what do you want to use it for?

Hi, and thank you very much for your answer.

Using this UsbAsp with other old mac and this drivers GitHub - adrianmihalko/ch340g-ch34g-ch34x-mac-os-x-driver: CH340G CH34G CH34X Mac OS X driver everything works well.

It’s quite difficult for me describe exactly what hardware is, I attached a pic for more detail.

But looking better I cannot find CH340.

This is for a project commissioned me by my kid and I need to program an ATMEGA328P.

Thanks for your help.

looking for other USBasp on amazon or ebay I cannot recognize CH340… I’m quite disoriented…

You have an USBasp. It’s even labelled near the USB connector. And it’s the right tool to program an ATMEGA328P.

On macOS, no drivers or driver configurations are needed.

In PlatformIO, just add the below lines to platformio.ini and you’re good to go:

upload_tool = usbasp
upload_flags = -e

Remove any other upload options (like upload_port) if you have them in platformio.ini.

My MacOS Big Sur cannot detect the USB. Yes, I can see these drivers: /System/Library/DriverExtensions

  • com.apple.DriverKit-AppleUSBCHCOM.dext
  • com.apple.DriverKit-AppleUSBFTDI.dext
  • com.apple.DriverKit-AppleUSBSLCOM.dext
  1. My cable work with other ESP32 modules

  2. In the Hardware->USB, I got this output:

    Product ID: 0x7522
    Vendor ID: 0x1a86
    Version: 2.64
    Speed: Up to 12 Mb/s
    Location ID: 0x14200000 / 3
    Current Available (mA): 500
    Extra Operating Current (mA): 0
  3. Before using your approach, I install other USB drivers and already uninstall all of them using your guide

  4. Wemos D1 which use CH340C works. But LilyGo T-io Mac OS, Linux driver for CH340K · Issue #3 · LilyGO/LILYGO-T-OI · GitHub which uses CH340K doesn’t work

It looks as if you are out of luck: CH340K uses a different product ID (though it uses most likely the same protocol) and is neither supported by Apple’s driver nor by WCH driver on macOS.

Need to wait for Mr. Apple to add it. Thanks

So here’s a fun one. Tried to install CH34x_install_v1.5 on my late 2008 Alu MacBook (10.11.6), and it installed fine, but…. Completely disabled the native keyboard and touchpad. Didn’t even get to check if it connected to the board. I had to uninstall it, remove the battery and eventually keyboard worked again. Been told this may be a usb addressing thing, but… any advice?

These symptoms don’t sound familiar.

There used to be issues with WCH drivers when macOS Sierra was introduced. But macOS 10.11.6 is macOS “El Capitan”. That’s even older and predates the problem. You might want to go back to older drivers version like v1.3 (available on GitHub - adrianmihalko/ch340g-ch34g-ch34x-mac-os-x-driver: CH340G CH34G CH34X Mac OS X driver)

1 Like