Build the Linux Kernel Module to Enable RTL8811CU/RTL8821CU USB Wireless Dongles

There is no built-in support for Realtek RTL8811CU^[1][2] and RTL8821CU^[3] in Ubuntu 20.04 LTS. The later also has a Bluetooth controller. I have to download the RTL8811CU/RTL8821CU driver source code, compile to a kernel module, add it to the kernel, and switch to the WiFi USB mode.

The following USB wireless dongle uses the RTL8811CU chipset:

1. TOTOLINK A650UA^[4]

Quick Summary

For Ubuntu 18.04 LTS and 20.04LTS, follow these steps:

$sudo apt-get update
$sudo apt-get install dkms git
$git clone https://github.com/brektrou/rtl8821CU.git
$cd ~/rtl8821CU
$sudo ./dkms-install.sh
$sudo /usr/sbin/usb_modeswitch -KW -v 0bda -p 1a2b

If the usb_modeswitch doesn’t work, check the vendor and product id:

$sudo modprobe 8821cu
$lsusb

If it works, make it work automatically:

$sudo vi /lib/udev/rules.d/40-usb_modeswitch.rules
/1a2b
# D-Link DWA-171 Wifi Dongle
#ATTR{idVendor}=="0bda", ATTR{idProduct}=="1a2b", RUN+="usb_modeswitch '/%k'"

# TOTOLINK A500UA
ATTR{idVendor}=="0bda", ATTR{idProduct}=="1a2b", RUN+="/usr/sbin/usb_modeswitch -K -v 0bda -p 1a2b"

For RTL8821CU, run systemctl start bluetooth.service to enable Bluetooth.

Prepare to Build

Get codes and tools in different packages:

$sudo apt-get update
$sudo apt-get install linux-headers-generic build-essential git

Or the dkms (Dynamic Kernel Module Support Framework)^[5] package:

$sudo apt-get update
$sudo apt-get install dkms git

1. Get only the essential Linux kernel headers^[6]. I am not going to compile the full kernel.^[7]
2. Get the build-essential package^[8] which includes
   • Debian package development tools
   • C/C++ Compilers
   • Development Libraries and Header Files
   • Make utility
3. Get the Git^[9] which contains the tool to clone the source code from a git server.
4. Get the dkms which contains code and tools in linux-headers-generic and build-essential.

Build and Install Kernel Module

I use brektrou’s^[10] solution because it is up to date and has a detailed document.

Always read the “README.md” to check if it works with the current kernel.

Use the shell script to install:

$git clone https://github.com/brektrou/rtl8821CU.git
$cd ~/rtl8821CU
$sudo ./dkms-install.sh

Switch from Disk to WiFi Dongle

RTL8811CU/RTL8821CU is identified as a disk when plugged in for the first time. It needs to be switched to WiFi mode and will be identified as a WiFi dongle after that.

If it is identified as a WiFi dongle when plugged in for the first time, skip this section.

Find the vendor and product ID

Use lsusb to list all connected USB devices. It might look different on others.

$lsusb
...
Bus 002 Device 003: ID 0bda:1a2b Realtek Semiconductor Corp.
...

In this case, the vendor ID is 0bda while the product ID is 1a2b.

Switch from Disk Mode to WiFi

Use usb_modeswitch^[11] to change. The ‘-K’ will send an eject signal to trigger the switch event:

$sudo /usr/sbin/usb_modeswitch -KW -v 0bda -p 1a2b
Take all parameters from the command line

* usb_modeswitch: handle USB devices with multiple modes
* Version 2.5.2 (C) Josua Dietze 2017
* Based on libusb1/libusbx

! PLEASE REPORT NEW CONFIGURATIONS !

DefaultVendor= 0x0bda
DefaultProduct= 0x1a2b

StandardEject=1

Look for default devices ...
  found USB ID 0bda:1a2b
   vendor ID matched
   product ID matched
  found USB ID 8087:0020
  found USB ID 1d6b:0002
  found USB ID 1d6b:0003
  found USB ID 1d6b:0002
  found USB ID 17ef:480f
  found USB ID 0a5c:217f
  found USB ID 147e:2016
  found USB ID 046d:c50a
  found USB ID 8087:0020
  found USB ID 1d6b:0002
 Found devices in default mode (1)
Access device 003 on bus 002
Get the current device configuration ...
Current configuration number is 1
Use interface number 0
 with class 8
Use endpoints 0x0b (out) and 0x8a (in)

USB description data (for identification)
-------------------------
Manufacturer: Realtek
     Product: DISK
  Serial No.: not provided
-------------------------
Sending standard EJECT sequence
Looking for active drivers ...
 OK, driver detached
Set up interface 0
Use endpoint 0x0b for message sending ...
Trying to send message 1 to endpoint 0x0b ...
 OK, message successfully sent
Read the response to message 1 (CSW) ...
 Response successfully read (13 bytes), status 1
Trying to send message 2 to endpoint 0x0b ...
 OK, message successfully sent
Read the response to message 2 (CSW) ...
 Response successfully read (13 bytes), status 0
Trying to send message 3 to endpoint 0x0b ...
 Sending the message returned error -1. Try to continue
Read the response to message 3 (CSW) ...
 Response reading failed (error -1)
 Device is gone, skip any further commands
-> Run lsusb to note any changes. Bye!

Now, it should be available in the WiFi Settings. The device has changed to a different device number and product ID:

$lsusb
...
Bus 002 Device 004: ID 0bda:2006 Realtek Semiconductor Corp.
...

For RTL8821CU, run systemctl start bluetooth.service to enable Bluetooth.

Update to Switch Automatically

Edit the rules to insert a new usb_modeswitch command and remake the old one for matched idVendor and idProduct. Once a matched USB device is plugged in, this rule would be triggered to run usb_modeswitch automatically. Here is my example:

$sudo vi /lib/udev/rules.d/40-usb_modeswitch.rules
...
# D-Link DWA-171 Wifi Dongle
#ATTR{idVendor}=="0bda", ATTR{idProduct}=="1a2b", RUN+="usb_modeswitch '/%k'"

# TOTOLINK A500UA
ATTR{idVendor}=="0bda", ATTR{idProduct}=="1a2b", RUN+="/usr/sbin/usb_modeswitch -K -v 0bda -p 1a2b"
...

It is suggested to reboot for a complete test.

Detect Installed RTL8811CU/

RTL8821CU Devices

The installed kernel module is “8821cu”:

$sudo modprobe 8821cu

Issues

PCIe Activate State Power Management

Tomás Pinho shared a solution when there is any PCIe Activate State Power Management issue^[12]. Just add ‘pci=noaer’ at the end of “GRUB_CMDLINE_LINUX_DEFAULT” and update grub.

$sudo vi /etc/default/grub
...
GRUB_CMDLINE_LINUX_DEFAULT="quiet splash pci=noaer"
...
$sudo update-grub

Special Topics

Device Name in WiFi Settings

To find the name used for A650UA, run usb_modeswitch to fetch device information in WiFi mode. The product ID is 2006 in WiFi mode while 1a2b in disk mode:

$sudo /usr/sbin/usb_modeswitch -W -v 0bda -p 2006
...
USB description data (for identification)
-------------------------
Manufacturer: Realtek
Product: 802.11ac NIC
Serial No.: 123456
-------------------------
...

The “802.11ac NIC” in the “USB description data” is the name displayed in the WiFi Settings.

Uninstall

Run the shell script to remove the kernel module. Manually edit the /lib/udev/rules.d/40-usb_modeswitch.rules to remove the added rule.

cd ~/rtl8821CU/
$sudo ./dkms-remove.sh

Reference

1. DeviWikiDev: Realtek: Wireless chipsets
2. Realtek: RTL8811CU
3. Realtek: RTL8821CU
4. Wireless CAT: TOTOLINK A650UA
5. Ubuntu: Package: dkms (2.3-3ubuntu9)
6. Ubuntu: Package: linux-headers-generic (4.15.0.96.87 and others) [security]
7. nixCraft: Howto: Build Linux Kernel Module Against Installed Kernel w/o Full Kernel Source Tree
8. Ubuntu: Package: build-essential (12.4ubuntu1)
9. Ubuntu: Package: git (1:2.17.1-1ubuntu0.7 and others) [security]
10. GitHub: brektrou / rtl8821CU
11. USB_ModeSwitch – Handling Mode-Switching USB Devices on Linux
12. GitHub: tomaspinho/rtl8821ce
13. Style Guide