# Adafruit CH9328 UART to HID Keyboard Breakout
## Overview
We love using chips with 'native USB' peripherals - that's the magic silicon that lets a microcontroller act like an HID keyboard or mouse or disk drive or MIDI synth. It's a standard addition on [SAMD21](https://www.adafruit.com/product/4600), [RP2040](https://www.adafruit.com/search?q=rp2040), and even the latest [ESP32-S2](https://www.adafruit.com/search?q=esp32-s2) and [ESP32-S3](https://www.adafruit.com/search?q=esp32-s3) boards. But what about when you have a classic ATmega328 Uno? or an original ESP32 or ESP8266? Maybe even a single-board computer like a Raspberry Pi? We would say "sorry...that's not possible", UNTIL NOW!
The [CH9328](https://www.wch-ic.com/products/CH9328.html) is a funky chip that is basically a programmed microcontroller that enumerates as an every-day HID keyboard and can convert ASCII or 8-byte raw reports, read over a standard serial port UART, into keypresses. So, you can emulate a keyboard even if your chip doesn't have native USB! You _do_ need a hardware or software serial port: some way to generate 9600 baud 3V-logic signal that the CH9328 can read.
We added all the support circuitry to make this chip easy to use, you may not even need to do any soldering. The CH9328 is connected to a USB Type C port so it's easy to plug into any computer, laptop or even phone/tablet. Then, you can get 5V power from the 5V and Ground pads. There's a UART RX receive input plus a reset line if you want to perform a hard reset. [If you want 'solderless' functionality, grab one of our JST SH cables](https://www.adafruit.com/product/5755): the red line will provide 5V, black is Ground, and the white wire is data in.
You can configure the 'Mode' using the 4 on-board switches, do that before powering it up:
- **Switch #1** is used to configure the "Upload speed" - for most cases it doesn't matter which way it's set
- **If Switch #2, #3 and #4 are all 'ON' the chip is in Mode 0:**
Visible ASCII characters are sent as-is: if you send ASCII "A", an "A" is typed. If 0x1B is received, it is converted to the Enter key
- **If Switch #2 and #4 are 'ON' and Switch #3 is 'OFF' the chip is in Mode 1:**
Visible ASCII characters are sent as-is: if you send ASCII "A", an "A" is typed
- **If Switch #2 and #3 are 'ON' and Switch #4 is 'OFF' the chip is in Mode 2:**
Visible ASCII characters are sent as-is: if you send ASCII "A", an "A" is typed. If 0x28 is received, it is converted to the Enter key
- **If Switch #3 and #4 are 'ON' and Switch #2 is 'OFF' the chip is in Mode 3:**
This is the mode for sending raw 8-byte HID reports. This is also good if you want more control over the keypresses, or keyholds, or to mimic a non-US keyboard because you can control exactly what control codes are sent and when.
We recommend using mode 3 if possible, but you'll want to use our CH9328 library to do so.
This is a nice and easy way to emulate a keyboard without having to worry about native USB support, gadget mode, or maybe you just want to emulate more than one kind of device. You can also do 'funky' things like have one desktop or single-board computer 'type' into a device such as a computer or mobile device by running our Python code and having it [send UART data via a USB-to-UART converter](https://www.adafruit.com/product/954). Either way, the CH9328 will make it easy to keeb away.
# Adafruit CH9328 UART to HID Keyboard Breakout
## Pinouts
## Power
- **USB C Port** - at the top edge of the board is the USB C port. Use this port to connect the breakout to your computer, laptop or even a phone or tablet. This port provides power and ground to the CH9328, as well as an HID connection to your chosen device.
- **VCC** - this is the power output from the USB C port. It is 5V by default.
- **GND** - common ground for power and logic.
## UART
- **RX** - This is the UART **RX** receive input for the CH9328. Connect this pin to the UART TX transmit output pin on your microcontroller.
## Reset
- **RST** - This is the **reset** line for the CH9328. If you want to perform a hard reset, set this pin low.
## JST SH Port
- [**JST SH**](https://www.adafruit.com/product/5755) - 1mm pitch JST port for use with [3-pin JST SH cables](https://www.adafruit.com/product/5765). It has connections for:
- **GND** - common ground for power and data. It is the black wire on the JST SH cable.
- **VCC** - power output from the USB C port. It is the red wire on the JST SH cable.
- **RX** - RX input for the CH9328. It is the white wire on the JST SH cable.
## Switches
There are four switches on the breakout board labeled **1** , **2** , **3** and **4**. Switch **1** is used to configure the "Upload speed" - when the switch is on, it is set to normal speed and when it is off it is set to high speed (approximately 2x the speed of normal speed). For most cases it doesn't matter which way its set.
Switches **2** , **3** and **4** configure the 'Mode' for the CH9328. You'll need to select your 'Mode' before powering up the board. There are four modes available:
- **Mode 0:**
Visible ASCII characters are sent as-is: if you send ASCII "A", an "A" is typed. If 0x1B is received, it is converted to the Enter key
- **Mode 1:**
Visible ASCII characters are sent as-is: if you send ASCII "A", an "A" is typed
- **Mode 2:**
Visible ASCII characters are sent as-is: if you send ASCII "A", an "A" is typed. If 0x28 is received, it is converted to the Enter key
- **Mode 3:**
This is the mode for sending raw 8-byte HID reports. This is also good if you want more control over the keypresses, or keyholds, or to mimic a non-US keyboard because you can control exactly what control codes are sent and when.
The modes are selected with these switch combinations:
## VCC Jumper
On the back of the board is the **VCC jumper**. It is outlined in white on the board silk and is labeled **VCC**. If you cut the **5V** pad from the **center pad** , this will disconnect the 5V line output from the VCC pin. If you solder the **3V** pad to the **center pad** , it will connect the 3V output to the VCC pin. This will cause the output voltage from VCC to be 3V.
## Status LEDs
There are two LEDs on the front of the board:
- **HID** - This is the HID USB status LED. It is a yellow LED and it is connected to the ACT pin on the CH9328. When the USB configuration setup is complete, this LED will light up.
- **USB** - This is the serial UART status LED. It is a red LED and it is connected to the T\_LED pin on the CH9328. This LED is lit when a serial UART message is received on the RX pin and is sent via USB. If there is no UART activity, then this LED will be off.
# Adafruit CH9328 UART to HID Keyboard Breakout
## CircuitPython and Python
It's easy to use the **CH9328** with CircuitPython and the [Adafruit\_CircuitPython\_CH9328](https://github.com/adafruit/Adafruit_CircuitPython_CH9328) driver. This driver allows you to easily write Python code to send UART messages to the CH9328.
You can use this driver with any CircuitPython microcontroller board or with a computer that has GPIO, UART and Python [thanks to Adafruit\_Blinka, our CircuitPython-for-Python compatibility library](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux). For Blinka, this example was tested with a Raspberry Pi. To use the example as-is with built-in UART, you'll need to follow [these configuration steps](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux/uart-serial#the-hard-way-using-built-in-uart-2998808) outlined in the Blinka Learn Guide.
### CircuitPython Libraries on Linux and Raspberry Pi - UART / Serial
[CircuitPython Libraries on Linux and Raspberry Pi](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux)
[UART / Serial](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux/uart-serial)
Warning: Make sure that the CH9328 onboard switches are set to Mode 3 (switch 2 off, switches 3 and 4 on) before powering it up.
## CircuitPython Microcontroller Wiring
First wire up the breakout to your board exactly as follows. The CH9328 and the microcontroller will both be connected to your computer via USB but will share a ground connection. Make sure that the CH9328 onboard switches are set to Mode 3 (switch 2 off, switches 3 and 4 on) before powering it up. The following is the breakout wired to a Feather RP2040 using the JST SH connector.
- **Board GND** to **breakout JST SH** **GND (black wire)**
- **Board TX** to **breakout JST SH RX (white wire)**
The following is the breakout wired to a Feather RP2040 using a solderless breadboard:
- **Board GND** to **breakout**** GND (black wire)**
- **Board TX** to **breakout** **RX (white wire)**
## Python Computer Wiring
Since there are _dozens_ of Linux computers/boards you can use, we will show wiring for Raspberry Pi. For other platforms, [please visit the guide for CircuitPython on Linux to see whether your platform is supported](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux).
Here's the Raspberry Pi wired to the breakout using a JST SH cable:
- **Pi GND** to **breakout** **JST SH GND (black wire)**
- **Pi TX** to **breakout** **JST SH** **RX (white wire)**
Here is how you'll wire the breakout to a Raspberry Pi with a breadboard:
- **Pi GND** to **breakout**** GND (black wire)**
- **Pi TX** to **breakout** **RX (white wire)**
## Python Installation of the Adafruit CH9328 Library
You'll need to install the **Adafruit\_Blinka** library that provides the CircuitPython support in Python. This may also require enabling I2C and [built-in UART](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux/uart-serial#the-hard-way-using-built-in-uart-2998808) on your platform and verifying you are running Python 3. [Since each platform is a little different, and Linux changes often, please visit the CircuitPython on Linux guide to get your computer ready](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux)!
Once that's done, from your command line run the following command:
- `pip3 install adafruit-circuitpython-ch9328`
If your default Python is version 3 you may need to run 'pip' instead. Just make sure you aren't trying to use CircuitPython on Python 2.x, it isn't supported!
Warning: Make sure to follow the [built-in UART setup steps](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux/uart-serial#the-hard-way-using-built-in-uart-2998808) if you are using the TX pin on the Raspberry Pi.
## CircuitPython Usage
To use with CircuitPython, you need to first install the **Adafruit\_CircuitPython\_CH9328** library into the **lib** folder on your **CIRCUITPY** drive. Then you need to update **code.py** with the example script.
Thankfully, we can do this in one go. In the example below, click the **Download Project Bundle** button below to download the necessary libraries and the **code.py** file in a zip file. Extract the contents of the zip file, and copy the **entire** **lib** **folder** and the **code.py** file to your **CIRCUITPY** drive.
Your **CIRCUITPY/lib** folder should contain the following folder:
- **adafruit\_ch9328/**
## Python Usage
Once you have the library `pip3` installed on your computer, copy or download the following example to your computer, and run the following, replacing **code.py** with whatever you named the file:
`python3 code.py`
## Example Code
Once everything is saved to the **CIRCUITPY** drive, [connect to the serial console](https://learn.adafruit.com/welcome-to-circuitpython/kattni-connecting-to-the-serial-console) to see the data printed out!
https://github.com/adafruit/Adafruit_CircuitPython_CH9328/blob/main/examples/ch9328_simpletest.py
In the code, the CH9328 is initialized over UART. After a two second delay, the text "Hello World!" is typed out from the CH9328. After an additional two second delay, the text is deleted. The delays are there so that you can position your cursor before the HID key presses are sent.
# Adafruit CH9328 UART to HID Keyboard Breakout
## Python Docs
# Adafruit CH9328 UART to HID Keyboard Breakout
## CPython
The CH9328 can allow you to do 'funky' things. In this example, you can have one desktop or single-board computer 'type' into a device such as a computer or mobile device by running our Python script and having it [send UART data via a USB-to-UART converter](https://www.adafruit.com/product/954).
### USB to TTL Serial Cable - Debug / Console Cable for Raspberry Pi
[USB to TTL Serial Cable - Debug / Console Cable for Raspberry Pi](https://www.adafruit.com/product/954)
The cable is easiest way ever to connect to your microcontroller/Raspberry Pi/WiFi router serial console port. Inside the big USB plug is a USB\<-\>Serial conversion chip and at the end of the 36" cable are four wire - red power, black ground, white RX into USB port, and green TX out...
In Stock
[Buy Now](https://www.adafruit.com/product/954)
[Related Guides to the Product](https://learn.adafruit.com/products/954/guides)
## Wiring
You'll plug the USB to TTL cable into the computer running the CPython script. The cable will connect to the CH9328 breakout RX and GND connections. The CH9328 breakout will plug into the computer that you want to send the HID commands to.
The USB to TTL cable has four wires: red power, black ground, white RX into USB port, and green TX out of the USB port. You'll be using the black ground wire and the green TX wire.
- **USB to TTL cable GND** to **breakout JST SH GND (black wire)**
- **USB to TTL cable TX** to **breakout JST SH RX (white wire)**
The CH9328 should be in Mode 0. Switches 2, 3 and 4 should all be switched on. The mode needs to be selected before the breakout is powered on.
Warning: Make sure that the CH9328 onboard switches are set to Mode 0 (switch 2, 3 and 4 on) before powering it up.
## CPython CH9328 Code
To run the script you will need a desktop or single board computer with Python 3 installed.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CH9328_CPython_Demo/code.py
## CPython Dependencies
First, you'll use `pip` to install the Python libraries required to run the script:
```terminal
pip install pyserial
pip install keyboard
```
Danger: Some versions of RapsberryPi OS use the 'venv' virtual environment and may balk at installing packages at the root level. 'keyboard' needs to be run at root level (which is scary and dangerous, beware) If you run into the 'error externally-managed-environment` use this instead:
```terminal
sudo pip install pyserial --break-system-packages
sudo pip install keyboard --break-system-packages
```
## Customize the Script
Open the script in your preferred text editor or IDE. At the top of the code, you'll need to update `port` to [match the COM port](https://learn.adafruit.com/dude-where-s-my-com-port) that your USB to TTL cable is plugged into. Otherwise, the script will not work.
```python
port = '/dev/ttyUSB0' # Replace with your actual serial port
```
Warning: Update the COM port before running the script!
## Run the Script
After adding your COM port, you can run the **code.py** script inside a terminal window on your computer with:
```terminal
sudo python code.py
```
The `keyboard` library requires that the script be run as an administrator or `root`, depending on your operating system.
After the script starts to run, any keyboard typing that takes place on your computer will be mirrored via the USB TTL cable and CH9328 breakout. In the .GIF below, the script is running on a Raspberry Pi and the CH9328 is connected to a Windows PC.
# Adafruit CH9328 UART to HID Keyboard Breakout
## Arduino
Using the CH9328 breakout with Arduino involves wiring up the breakout to your Arduino-compatible microcontroller, installing the [Adafruit\_CH9328](https://github.com/adafruit/Adafruit_CH9328/) library and running the provided example code.
## Wiring
Wire as shown when you are uploading code to the microcontroller. The CH9328 and the microcontroller will both be connected to your computer via USB but will share a ground connection. Make sure that the CH9328 onboard switches are set to Mode 3 (switch 2 off, switches 3 and 4 on) before powering it up.
Here is an Adafruit Metro wired up to the breakout using a JST SH cable.
- **Board GND** to **breakout** **JST SH GND (black wire)**
- **Board pin 2** to **breakout** **JST SH** **RX (white wire)**
Here is an Adafruit Metro wired up using a solderless breadboard:
- **Board GND** to **breakout**** GND (black wire)**
- **Board pin 2** to **breakout** **RX (white wire)**
Warning: Make sure that the CH9328 onboard switches are set to Mode 3 (switch 2 off, switches 3 and 4 on) before powering it up.
## Library Installation
You can install the Adafruit CH9328 library for Arduino using the Library Manager in the Arduino IDE.
Click the **Manage Libraries ...** menu item, search for **Adafruit CH9328** , and select the **Adafruit CH9328** library:
Info: There are no additional dependencies for this library.
## Example Code
https://github.com/adafruit/Adafruit_CH9328/blob/main/examples/CH9328_test/CH9328_test.ino
Upload the sketch to your board and open up the Serial Monitor ( **Tools -\> Serial Monitor** ) at 115200 baud. The text "`Hello World!`" will be typed out and then deleted. This will only happen once, since the loop in the example is empty.
# Adafruit CH9328 UART to HID Keyboard Breakout
## Arduino Docs
# Adafruit CH9328 UART to HID Keyboard Breakout
## Downloads
## Files
- [CH9328 Datasheet](https://cdn-learn.adafruit.com/assets/assets/000/130/514/original/CH9328DS1.PDF?1717789673)
- [EagleCAD PCB Files on GitHub](https://github.com/adafruit/Adafruit-CH9328-Breakout-PCB)
- [Fritzing object in the Adafruit Fritzing Library](https://github.com/adafruit/Fritzing-Library/blob/master/parts/Adafruit%20CH9328%20UART%20to%20HID%20Keyboard%20Breakout.fzpz)
## Schematic and Fab Print
## Primary Products
### Adafruit CH9328 UART to HID Keyboard Breakout
[Adafruit CH9328 UART to HID Keyboard Breakout](https://www.adafruit.com/product/5973)
We love using chips with 'native USB' peripherals - that's the magic silicon that lets a microcontroller act like an HID keyboard or mouse or disk drive or MIDI synth. It's a standard addition on [SAMD21](https://www.adafruit.com/product/4600),
In Stock
[Buy Now](https://www.adafruit.com/product/5973)
[Related Guides to the Product](https://learn.adafruit.com/products/5973/guides)
## Featured Products
### JST SH 1mm Pitch 3 Pin to Socket Headers Cable - 100mm long
[JST SH 1mm Pitch 3 Pin to Socket Headers Cable - 100mm long](https://www.adafruit.com/product/5765)
If you fancy connecting to anything else with a JST SH compatible 3-pin connector, this cable will do the trick. For example, our [NeoPixel JST Breakout boards](https://www.adafruit.com/product/5975), or [UPDI Friend](https://www.adafruit.com/product/5879), or
In Stock
[Buy Now](https://www.adafruit.com/product/5765)
[Related Guides to the Product](https://learn.adafruit.com/products/5765/guides)
### JST SH Compatible 1mm Pitch 3 Pin to Premium Male Headers Cable
[JST SH Compatible 1mm Pitch 3 Pin to Premium Male Headers Cable](https://www.adafruit.com/product/5755)
If you fancy connecting to anything else with a JST SH compatible 3-pin connector, this cable will do the trick. For example, our [NeoPixel JST Breakout boards](https://www.adafruit.com/product/5975), or [UPDI Friend](https://www.adafruit.com/product/5879), or
Out of Stock
[Buy Now](https://www.adafruit.com/product/5755)
[Related Guides to the Product](https://learn.adafruit.com/products/5755/guides)
### USB to TTL Serial Cable - Debug / Console Cable for Raspberry Pi
[USB to TTL Serial Cable - Debug / Console Cable for Raspberry Pi](https://www.adafruit.com/product/954)
The cable is easiest way ever to connect to your microcontroller/Raspberry Pi/WiFi router serial console port. Inside the big USB plug is a USB\<-\>Serial conversion chip and at the end of the 36" cable are four wire - red power, black ground, white RX into USB port, and green TX out...
In Stock
[Buy Now](https://www.adafruit.com/product/954)
[Related Guides to the Product](https://learn.adafruit.com/products/954/guides)
## Related Guides
- [Adafruit Infrared IR Remote Transceiver](https://learn.adafruit.com/adafruit-infrared-ir-remote-transceiver.md)
- [Introducing ItsyBitsy M0 Express](https://learn.adafruit.com/introducing-itsy-bitsy-m0.md)
- [NXP Precision 9DoF Breakout](https://learn.adafruit.com/nxp-precision-9dof-breakout.md)
- [Adafruit TPS65131 Split Power Supply Boost Converter](https://learn.adafruit.com/adafruit-tps65131-split-power-supply-boost-converter.md)
- [Adafruit STEMMA Analog SPDT Switch](https://learn.adafruit.com/adafruit-stemma-analog-spdt-switch.md)
- [AD8495 Analog Output K-Type Thermocouple Amplifier](https://learn.adafruit.com/ad8495-thermocouple-amplifier.md)
- [Adafruit SHT4x Trinkey](https://learn.adafruit.com/adafruit-sht4x-trinkey.md)
- [BlueLive: Livestream Studio switcher controller](https://learn.adafruit.com/bluelive.md)
- [Light-Up Reactive Ukulele](https://learn.adafruit.com/light-up-reactive-ukulele.md)
- [Simple and Beautiful NeoPixel Holiday Lights](https://learn.adafruit.com/simple-beautiful-color-changing-light-strand.md)
- [Adafruit LiIon or LiPoly Charger BFF Add-On for QT Py](https://learn.adafruit.com/adafruit-qt-py-charger-bff.md)
- [Adafruit ATtiny Breakouts with seesaw](https://learn.adafruit.com/adafruit-attiny817-seesaw.md)
- [Adafruit SensorLab - Gyroscope Calibration](https://learn.adafruit.com/adafruit-sensorlab-gyroscope-calibration.md)
- [Adafruit MiniPOV3 Kit](https://learn.adafruit.com/minipov3.md)
- [LED Matrix Alarm Clock](https://learn.adafruit.com/led-matrix-alarm-clock.md)