Skip to main content

Troubleshooting: Serial port communication

Serial ports are used by several Mango data sources including Modbus Serial, BACnet MSTP, and the Serial data source. Because serial communication depends on operating system drivers, hardware adapters, wiring, and protocol settings all being correct simultaneously, troubleshooting can involve multiple layers. This page covers the most common serial port problems and how to resolve them.

Symptoms​

You may be experiencing one or more of these symptoms:

  • Serial port not found -- The serial port does not appear in Mango's port selection dropdown when configuring a data source.
  • Communication failures -- The data source starts but reports connection errors, timeouts, or "no response from device."
  • Garbled data -- The data source receives responses but values are incorrect, constantly changing, or show random characters in alphanumeric points.
  • Intermittent failures -- Communication works initially but drops out periodically or after a certain period of time.
  • Permission denied -- Mango logs show an error such as "Permission denied" or "Access denied" when attempting to open the serial port.

Error messages you might see:

com.serotonin.io.serial.SerialPortException: Port not found: /dev/ttyUSB0
gnu.io.PortInUseException: /dev/ttyUSB0 currently in use
java.io.IOException: Permission denied

Causes​

This problem is typically caused by one of the following issues.

Cause 1: Missing or incorrect USB adapter drivers​

Most modern computers do not have built-in RS-232 serial ports. USB-to-serial adapters are used instead, and these require operating system drivers to present the adapter as a serial port. If the driver is missing, not installed correctly, or incompatible with the adapter's chipset, the port will not appear.

Common USB-to-serial adapter chipsets:

ChipsetManufacturerNotes
FTDI FT232RFTDIMost reliable, widely supported, recommended for industrial use
Prolific PL2303ProlificCommon in consumer adapters; counterfeit chips may not work with newer drivers
CH340/CH341WCHLow cost, requires separate driver installation on Windows and macOS
CP2102/CP2104Silicon LabsGood reliability, driver available from Silicon Labs website

Cause 2: Linux permissions (udev rules and group membership)​

On Linux, serial port device files (e.g., /dev/ttyUSB0, /dev/ttyS0) are owned by root and the dialout group (or uucp on some distributions). If the Mango process runs as a user that is not a member of the correct group, the port cannot be opened.

Cause 3: Wrong baud rate or serial parameters​

Serial communication requires both ends (Mango and the device) to use identical settings for baud rate, data bits, parity, and stop bits. A mismatch in any of these parameters results in garbled data or no response at all.

Cause 4: RS-485 wiring and termination issues​

RS-485 communication (used by Modbus RTU and BACnet MSTP) is sensitive to wiring topology, termination resistors, and cable length. Incorrect wiring causes intermittent communication failures, garbled data, or complete communication loss on multi-drop networks.

Cause 5: Port locked by another process​

A serial port can only be opened by one process at a time. If another application (a terminal emulator, another instance of Mango, or a system service) has the port open, Mango will report it as "in use."

Cause 6: Windows COM port number too high​

On Windows, Mango may not detect COM ports with numbers higher than COM9 (or in some cases COM16). This occurs when USB adapters are assigned high COM port numbers after repeated plug/unplug cycles.

Solution​

Fix for cause 1: Install the correct USB adapter driver​

Windows:

  1. Plug in the USB-to-serial adapter.
  2. Open Device Manager and look under Ports (COM & LPT).
  3. If the adapter shows with a warning icon or appears under "Other devices," the driver is missing.
  4. Identify the chipset (check the adapter's documentation or the Device Manager hardware ID).
  5. Download and install the appropriate driver from the chipset manufacturer's website.
  6. After installation, the adapter should appear as a COM port in Device Manager.

Linux:

  1. Plug in the USB adapter.
  2. Run dmesg | tail -20 to see kernel messages about the newly detected device.
  3. The kernel should report the chipset and the assigned device path (e.g., /dev/ttyUSB0).
  4. If no device is created, the kernel module for the chipset may not be loaded. For CH340 adapters: sudo modprobe ch341.
  5. Verify the device exists: ls -la /dev/ttyUSB*.

Verification:

# Linux: Verify the serial port device exists
ls -la /dev/ttyUSB0

# Windows: Verify the COM port in Device Manager or via PowerShell
[System.IO.Ports.SerialPort]::GetPortNames()

Fix for cause 2: Configure Linux permissions​

  1. Determine which group owns the serial device:

    ls -la /dev/ttyUSB0
    # Output: crw-rw---- 1 root dialout 188, 0 Feb 16 10:00 /dev/ttyUSB0

  2. Add the Mango user to the dialout group (or whichever group owns the device):

    sudo usermod -aG dialout mango

  3. Log out and log back in (or restart Mango) for the group membership to take effect.

  4. For persistent USB adapter naming, create a udev rule so the device always gets the same path regardless of plug order. Create a file /etc/udev/rules.d/99-mango-serial.rules:

    SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", SYMLINK+="ttyModbus", GROUP="dialout", MODE="0660"

    This creates a symlink /dev/ttyModbus that always points to the FTDI adapter, regardless of which USB port it is plugged into.

  5. Reload udev rules:

    sudo udevadm control --reload-rules
    sudo udevadm trigger

Verification:

# Confirm user is in the dialout group
groups mango
# Expected output includes: dialout

# Confirm the symlink exists
ls -la /dev/ttyModbus

Fix for cause 3: Correct baud rate and serial parameters​

  1. Consult the device documentation for the correct serial settings.

  2. In the Mango data source configuration, set the following to match the device:

    ParameterCommon valuesNotes
    Baud rate9600, 19200, 38400, 57600, 115200Must match exactly
    Data bits8 (most common), 7Must match exactly
    ParityNone, Even, OddModbus RTU commonly uses Even or None
    Stop bits1 (most common), 2Must match exactly

  3. If you are unsure of the device settings, try the most common combination first: 9600 baud, 8 data bits, no parity, 1 stop bit (9600-8N1).

  4. If data is garbled at a known baud rate, try swapping the parity setting. Receiving garbled data usually means the baud rate is correct but another parameter is wrong.

Fix for cause 4: RS-485 wiring and termination​

RS-485 networks require proper topology and termination to function reliably.

Wiring best practices:

  • Use a daisy-chain (bus) topology -- Connect devices in a line, not in a star pattern. Star wiring creates signal reflections that corrupt data.
  • Use twisted pair cable -- RS-485 signals (A/B or D+/D-) must be on a twisted pair for noise rejection. Cat5e Ethernet cable works well (use one pair for A/B).
  • Connect signal ground -- Run a ground wire alongside the data pair. Floating grounds cause voltage offsets that corrupt communication.
  • Keep cable length within limits -- RS-485 supports up to 1,200 meters (4,000 feet) at 9600 baud. Higher baud rates require shorter cables.

Termination:

  • Install a 120-ohm termination resistor at each end of the bus (between A and B lines).
  • Do not install termination resistors at intermediate devices -- only at the two physical endpoints of the cable.
  • Many RS-485 adapters and devices have built-in switchable termination resistors. Check if yours is enabled when the device is at an end of the bus.

Multi-drop addressing:

  • RS-485 supports up to 32 devices on a single bus (or 128+ with high-impedance drivers).
  • Each device must have a unique address (slave ID for Modbus, MAC address for BACnet MSTP).
  • Verify there are no address conflicts on the bus.

Fix for cause 5: Release the locked port​

  1. Identify the process holding the port:

    # Linux
    sudo fuser /dev/ttyUSB0

    # Windows: Use Process Explorer or Resource Monitor to find the process using the COM port

  2. Stop the other process or close the application that is using the port.

  3. If the port was locked by a previous Mango instance that did not shut down cleanly, restart Mango. On Linux, you may need to kill any orphaned Java processes.

Fix for cause 6: Reassign Windows COM port number​

  1. Open Device Manager.
  2. Expand Ports (COM & LPT).
  3. Right-click the USB-to-serial adapter and select Properties.
  4. Go to the Port Settings tab and click Advanced.
  5. In the COM Port Number dropdown, select a lower port number (COM1 through COM9).
  6. Click OK and restart Mango.

Prevention​

How to avoid serial port problems in the future:

  • Use FTDI-based USB adapters -- They have the most reliable driver support across all operating systems and are less likely to cause driver issues.
  • Create udev rules on Linux -- Persistent device naming prevents port assignment changes when USB devices are reconnected.
  • Document serial settings -- Record the baud rate, parity, and stop bit settings for each device in the data source description field within Mango.
  • Use dedicated USB ports -- Plug serial adapters into the same USB port each time to avoid COM port number changes on Windows.
  • Test wiring with a loopback -- Before connecting to a device, perform a loopback test (connect TX to RX on the adapter) to verify the adapter and driver are working.
  • Install termination resistors during initial wiring -- Do not defer RS-485 termination as a "later" task; unterminated buses cause intermittent errors that are difficult to diagnose.