Troubleshooting Communications Issues

Issues communicating between the microcontroller and computer?

No communication with my hardware works, what do you suggest?

It's possible you need to install drivers for your dev-board.

While macOS and Linux distro's typically have good hardware support, we've summarised common USB-Serial chipsets which need specially installed drivers to function.

  • Silabs CP210x are commonly used on ESP8266 and ESP32 boards, install is often needed on macOS.

  • EXAR USB-UART, are sometimes needed on the Linux platforms we've tried (not great mainline support).

  • FTDI USB-UART chipsets are common, but Windows needs help sometimes. macOS and Linux are typically fine.

  • Prolific PL2303 are older and increasingly less common. We've found Windows had issues getting this driver right.

On Windows, the automatic install process doesn't always get the right driver variant, or you can have conflicts with drivers installed by other software.

  1. Open the device manager and attempt to find the USB-Serial converter.
  2. Right click on the device and open the Properties menu.
  3. Uninstall the driver
  4. Install the driver properly.

I can know my serial device works, but I can't see it in my UI

The most common issue is the serial port locking for use by another program on your computer.

This might be the serial terminal you had connected earlier, your serial based programming process (Arduino programming occurs over serial), etc.

Close the program claiming the serial port, try unplugging and reinserting the hardware, a different USB port, or rebooting the computer.

Check the baudrate specified for the UI during the device hinting stage matches the baudrate configured on your hardware.

Linux (and macOS) - Troubleshooting serial devices

List serial devices with ls -l /sys/class/tty/ttyUSB*, ls -l /dev/serial/ or with this small bash script.

Some serial adaptors will use the ttyACM* notation in the above command snippet.

If you know the comPath of your device, but something is using it, use ps -ef | grep ttyUSB9 to show the offending process.

Do you have permission to access the serial device (Linux)? Add yourself to the dialout group sudo usermod -a -G dialout $USER .

Arduino Mega (2560) or Arduino Due connection issues

The default firmware on the 16u2 USB-Serial converter microcontroller sends a few bytes of data to the microcontroller when a serial connection opens (such as searching for, or connecting to a device in Electric UI).

Some people had issues with their firmware catching this serial data, and more recent firmwares have an inbuilt delay to avoid this issue.

We've noticed this issue occuring on 3rd party (clone) Arduino Mega boards, as the firmware wasn't updated.

As Electric UI's connections handler is event driven and tries to minimise connection latency, the first heartbeat packets sent from the UI to the microcontroller don't always make it to your userspace firmware. To resolve this issue, Electric UI should retry using an exponential backoff.

To manually configure the connections delay (and thus the backoff durations), try increasing the heartbeat frequency by changing the HeartbeatConnectionMetadataReporter options intervalDelay and timeout durations in the /src/transport-manager/config/serial.tsx settings file.

  1. const heartbeatMetadata = new HeartbeatConnectionMetadataReporter({
  2. interval: 500,
  3. timeout: 1000,
  4. // measurePipeline: true,
  5. })

Modifying the heartbeat behaviour resolves this issue as heartbeats are used as part of the device discovery and hint validation process.

Arduino auto-reset on serial connection

Many traditional Arduino devboards like the Arduino Uno, Arduino Mega, and many derivative boards are designed to reset the microcontroller when a serial connection is opened to the hardware.

This hardware design choice was intended to make program behaviour more understandable to beginners, but makes it harder for our rather fast event-based connection search and handshake process.

The Arduino website has a page on how to disable this behaviour in hardware.

We can work around this behaviour by forcing the UI to wait after opening the serial port, edit the transport configuration file /project-name/src/transport-manager/config/serial.tsx to uncomment the attachmentDelay line near the bottom of the file:

  1. configure: (hint: Hint) => {
  2. const identification = hint.getIdentification()
  3. const configuration = hint.getConfiguration()
  4. const options: SerialTransportOptions = {
  5. SerialPort,
  6. comPath: identification.comPath,
  7. baudRate: configuration.baudRate,
  8. // if you have an Arduino that resets on connection, uncomment this line to delay the connection
  9. attachmentDelay: 2500,
  10. }
  11. return options
  12. },

Some boards will boot faster than others, so feel free to tweak the attachment delay to suit your hardware's behaviour. We've found at least 500ms is a reliable setting across Windows, macOS and Linux OS's.

Can't see any serial devices on Linux

We provide a pre-built library responsible for serialport and USB interfacing. We build it on a Ubuntu based system, and while we've validated compatibility with Solus, Arch and Fedora distributions, some systems may have compatibility issues.

Ensure you have libusb and libusb-devel installed on your system.

If you want to try building the usb and serial dependancies, contact us, as we haven't documented this yet.