This page describes the serial communication settings, port name differences per platform, and what to check when something goes wrong.
Serial settings
The settings specified with Initialize are listed below. The values must match the settings of the peer device (or software).
| Setting | Default | Description |
|---|---|---|
| Port Name | COM1 | Port name. Formats per platform: see the table below |
| Baud Rate | 9600 | Communication speed in baud. Arduino sketches often use 115200 |
| Data Bits | 8 | Data bits per character (5-8) |
| Parity | None | Parity bit (None/Odd/Even/Mark/Space) |
| Stop Bits | 1 | Stop bits (1/1.5/2) |
| Flow Control | None | Flow control (None/Hardware (RTS/CTS)/Software (XON/XOFF)) |
| Write Timeout | 1000 | Write timeout in milliseconds. Change with Set Write Timeout |
| Receive Buffer Size | 8192 | Receive buffer size in bytes (minimum 1024). Change with Set Receive Buffer Size |
| Initial DTR | true | DTR signal state right after the port opens |
| Initial RTS | true | RTS signal state right after the port opens |
If settings such as the baud rate do not match the peer device, communication may succeed while the received data is garbled. Check the peer device’s specification and configure accordingly.
Receive modes
Received data is read on a background thread. Use Set Receive Mode to change how the thread polls.
| Receive Mode | Behavior | Use case |
|---|---|---|
| Low | Waits 10 milliseconds when no data arrives | Reduce CPU load for low-frequency communication |
| Normal | Always waits 1 millisecond (default) | General use |
| High | Waits with Yield instead of sleeping | Minimize latency for high-frequency, high-volume reception |
Receive events (Data Received and family) are dispatched on the game thread, so you can update UI inside the event handlers.
Data formats and delimiters
The receive data format is specified with Data Format on Initialize (or Set Data Format). See Switch the data format in Use Cases for details.
| Data Format | Received data | Notified event |
|---|---|---|
RawBytes | Byte array | Data Received |
UTF8String | UTF-8 string | Data Received String |
HexString | Hex string | Data Received Hex |
With UTF8String, strings are restored by splitting on the delimiter (default \r\n). Change it with Set String Delimiter. If the peer device uses a protocol that sends no newline, match the delimiter setting to the peer’s specification.
Port names per platform
Port name formats differ by platform.
| Platform | Example port names | What is enumerated |
|---|---|---|
| Windows | COM3, COM5 | Connected COM ports (SetupAPI) |
| Mac | cu.usbmodemXXXX, cu.usbserial-XXXX | Callout devices (names starting with cu.) |
| Linux | ttyUSB0, ttyACM0, by-id path names | /dev/ttyUSB*, /dev/ttyACM*, and more, plus /dev/serial/by-id/ |
On Mac and Linux, you can specify just the device name without the /dev/ prefix (it is completed automatically). On Linux, by-id path names stay the same even when the device is plugged into a different USB port, which is useful when port names change often.
Get Available Serial Ports excludes ports it cannot open. On Linux, if the current user lacks permission to open a port, that port does not appear in the list. If needed, check the OS-side settings, such as adding the user to the group allowed to use serial ports.
Port exclusivity
On most operating systems, only one application can open a serial port at a time. UniversalSerial is no exception.
- On Windows,
Openfails and theErrorevent fires while another application, such as the Arduino IDE serial monitor, holds the port. - After using the Arduino IDE serial monitor to check communication, close the monitor before calling
Openin Unreal Engine.
Troubleshooting
| Symptom | What to check | Related information |
|---|---|---|
| Cannot open the port | Is the device connected? Is another application holding the port? Is the port name correct? | Quick Start troubleshooting |
Get Available Serial Ports returns empty | Is the device recognized (check the OS device manager)? On Linux, does the user have permission to open the port? | “Port names per platform” on this page |
| Received data is garbled | Do the baud rate, data bits, parity, and stop bits match the peer device? | “Serial settings” on this page |
| Strings are not received | Is Data Format UTF8String? Does the peer device send the delimiter (default \r\n)? | Switch the data format |
| Received strings are cut off midway | Does the delimiter setting match the peer device? Check with Set String Delimiter | “Data formats and delimiters” on this page |
| No response right after connecting | Does the device reset when the port opens (Arduino)? Wait 1-2 seconds and send again | Quick Start |
| Missing data at high receive rates | Try Set Receive Mode High. Increase the buffer with Set Receive Buffer Size | “Receive modes” on this page |
| Device does not react to sends | Are you sending while connected (sending while disconnected only logs a warning)? Does Send String UTF8’s Add Delimiter match the peer? | Blueprint API Reference |
| The port stays open after PIE ends | Are you calling Close in EndPlay? | End communication in the Quick Start |
To isolate the cause, it also helps to output the Error Message of the Error event. For the plugin’s internal logs, search the output log for the LogUniversalSerial category.
Operational notes
- Supported platforms are Windows, Mac, and Linux. Android and iOS are not supported.
- The plugin directly uses each OS’s API. Unexpected behavior may therefore occur on older operating systems. Verify the behavior in your environment in advance with the Tester app.
- Reception runs on a background thread, but receive events are dispatched on the game thread.
- One
Serial Port Managerhandles one port. Create one manager per port to use multiple ports.