Skip to content

Connecting Your uThing™ Dongle

This guide covers how to connect your uThing™ dongle to a computer, identify its serial port name, and start communicating with it.

When connected, the dongle automatically enumerates as a standard Virtual COM Port (VCP), compatible with Linux, macOS, and Windows without needing special drivers.

USB Device ID

The device uses Vendor ID: 0x0483 and Product ID: 0x5740.

1. Finding the Serial Port

Once connected, your computer assigns a port name to the device. Here’s how to find it on different operating systems.

Linux

The port name is typically /dev/ttyACM* or /dev/ttyUSB*. To find the exact assigned name, open a terminal and run:

ls /dev/ttyACM*

If that doesn't work (it depends on the Linux distribution), try: 

ls /dev/ttyUSB*

Linux Permissions

By default, many Linux distributions mount USB devices with read-only permissions. If you can read data but cannot send commands, you will get a "Permission denied" error. See the Fixing Linux Permissions section below.

macOS

The port name will begin with /dev/cu.usbmodem. To find the exact name, open a terminal and run:

ls /dev/cu.usbmodem*

Windows

Open the Device Manager (press Win and search for "Device Manager"). The device will appear under the Ports (COM & LPT) section as a "USB Serial Device". The COM port number (e.g., COM3) is the identifier you will use.

Windows Device Manager

2. Fixing Linux Permissions

If you see a "Permission denied" error on Linux when trying to write to the device, you need to grant your user account the necessary permissions.

Permission Denied Error

You can solve this in one of two ways:

This is the simplest method. Add your user to the dialout group, which typically owns serial devices.

sudo usermod -a -G dialout $USER
You will need to log out and log back in for this change to take effect.

Option B: Create a udev Rule

For a more permanent, system-wide solution, you can create a udev rule that automatically sets the correct permissions whenever a uThing™ device is connected.

  1. Create the rule file: 
    echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="0483", MODE="0666"' | sudo tee /etc/udev/rules.d/50-uThing.rules
  2. Reload the udev rules: 
    sudo udevadm control --reload-rules
  3. Unplug and reconnect the device.

3. Communicating with the Device

Once you have the port name, there are three primary ways to communicate with the device:

  • Using a GUI Terminal: Applications like PuTTY (Windows), CoolTerm (macOS/Windows), or minicom (Linux) let you interactively view data and send commands. This is often the easiest way to start.
  • Directly from the Command Line: On Linux and macOS, you can use basic shell commands for quick tests or scripting.
  • Programmatically: Integrate the device into your own application using serial port libraries available for most languages (e.g., PySerial for Python, serialport for Node.js).

Baud rate and other connection settings are not required, as they are handled automatically by the USB VCP.

Example: Interacting and viewing sensor output data with the PuTTY application.

PuTTY example

Reading Sensor Data

The device starts sending data in JSON format by default as soon as it's connected.

To view this data stream, simply cat the device file:

# Replace with your actual port name
cat /dev/ttyACM0

The output will be a stream of JSON objects, depending on the connected product:

{"temperature": 24.40, "pressure": 1022.63, "humidity": 49.69, "gasResistance": 556385, "IAQ": 27.1, "iaqAccuracy": 2, "eqCO2": 507.94, "eqBreathVOC": 0.52}

{"noise":{"rms":36.2,"peak":36.2,"base":25.9},"pir":{"detections":0,"detPerHour":110},"light":{"last":11.82,"average":11.10}}

{"ph":{"last":6.378,"average":6.381},"voltage":{"last":38.21,"average":38.07},"temperature":{"onBoard":23.10,"external":23.31}}

Logging Data to a File

You can easily save this data to a file for logging: 

# Log data to activity.log in the background
cat /dev/ttyACM0 > activity.log &
If the “&” symbol is added at the end of the command, the process will be forked, and the system will keep storing the data until the user logs out or the dongle is disconnected.

This trick could be very useful for quick datalogging. By first configuring the CSV format, then the generated file can easily be opened in Excel or any spreadsheet application. For easier analysis, first switch the device to CSV output mode, then log.

Sending Commands

You can send commands to the device to change its configuration (e.g., output format, LED status). Commands can be single characters (interactive mode) or JSON objects.

To send a command from the terminal, use printf:

# Example: Send the 'h' command for help (interactive mode)
printf 'h\n' > /dev/ttyACM0

# Example: Disable the LED using a JSON command
printf '{"led":false}\n' > /dev/ttyACM0
For a full list of commands, see the Configuration page for your specific device.