Skip to main content

Tips & Tricks for Tachyon

This page collects useful commands and tricks for working with Tachyon on Linux. If you have any useful additions, feel free to share them in the Tachyon community forums!

Check the Installed Ubuntu OS Version​

To check which version of Ubuntu is running on your Tachyon device, use:

cat /etc/particle/distro_versions.json

This outputs a JSON object showing the current stack version, firmware versions, and other key details:

{
    "distro": {
        "stack": "ubuntu-base",
        "version": "1.0.25",
        "variant": "release"
    },
    "src": {
        "ubuntu_20_04": "image-48-ff4c992de",
        "quectel_bp_fw": "1.0.5",
        "syscon_firmware": "v0.7.16"
    }
}

Collecting System Logs​

For troubleshooting issues (especially connectivity problems), we’ve added a helper script called collect-particle-logs.sh. This script gathers the last 24 hours of logs from Particle services and the system kernel, packaging them into a single archive at:

/tmp/system-logs.zip

How to Use​

If you have physical access to the device via USB, you can run the script and copy the logs to your computer with:

adb shell collect-particle-logs.sh
adb pull /tmp/system-logs.zip

You can then share the system-logs.zip file with Particle support.

caution

The logs may contain sensitive information. Do not post the zip file on public forums. Send it directly to Particle when requested.

Recovering from a broken apt state​

In rare cases, the apt package manager can get interrupted, leaving the system in a broken state where apt install or apt upgrade no longer work. The typical fix is to run:

sudo dpkg --configure -a

However, if the issue involves particle-linux, running dpkg --configure -a will stop the particle-linux service. Since particle-linux manages key system processes, this can cause the dpkg command itself to fail, preventing recovery.

Workaround​

To bypass this problem, temporarily mask the particle-linux service before running the repair command, then unmask it afterward:

sudo systemctl mask particle-linux.service
sudo dpkg --configure -a
sudo systemctl unmask particle-linux.service

This prevents particle-linux from being stopped during the repair process, allowing dpkg to complete successfully.

Enabling Display in Headless Mode​

By default, the display is disabled when Tachyon is set up in headless mode. However, you can manually start a basic Weston display session if needed.

To enable the display for the current session, run:

systemctl start init_display

To automatically start the display on boot, run:

systemctl enable init_display

Note: In desktop mode, Tachyon boots directly into the GNOME GUI.

Turn Off Kernel Debug Prints on the Root Console​

If your serial console is flooded with kernel messages, you can disable them by running:

sudo dmesg -n 1

# To set back to the highest log level
sudo dmesg -n 8

This sets the log level to only critical messages, reducing clutter.

Check System Resource Usage (CPU, Memory, Disk, etc.)​

htop

• Provides an interactive way to monitor CPU, memory, and process activity.

df -h

• Shows disk space usage in a human-readable format.

Find Which Process is Using a Port​

If a port is in use and preventing a service from starting, you can find the process using it:

sudo netstat -tulnp | grep LISTEN

or

sudo lsof -i -P -n | grep LISTEN

• These commands list all open ports and their associated processes.

Restart Network Interfaces​

If you need to restart the network without rebooting:

sudo systemctl restart NetworkManager

or

nmcli networking off && nmcli networking on

• Useful for Wi-Fi and LTE debugging.

Check Boot Logs for Errors​

If your device isn’t booting properly, check the logs:

journalctl -xe

• Shows detailed logs, including boot issues and systemd service failures.

Test Internet Connectivity​

ping -c 5 8.8.8.8

Note: this uses the highest priority default route, i.e. Ethernet > Wi-Fi > Cellular

• Checks if the device has internet access.

curl -Is https://particle.io | grep particle

• Verifies if a specific website is reachable.

Quickly Find and Kill a Stuck Process​

ps aux | grep <process-name>

• Finds all running instances of a process.

sudo kill -9 <PID>
  • Kills a process by PID (replace PID with the actual number).

Alternative Flashing Method​

You can manually flash your Tachyon device using a specific image with the following command:

particle flash --tachyon <filename>

⚠️ Important: This method does not perform any device setup (e.g., Wi-Fi, Particle Cloud, eSIM profile download). The device will boot, but core services may not function until setup is complete. The root password will be particle (not secure — change immediately if network-accessible).

Step 1: Get the Latest Image List

To retrieve the latest available images, run:

wget https://tachyon-ci.particle.io/meta/tachyon-latest.json
cat tachyon-latest.json

You’ll see output similar to:

{
  "release_name": "tachyon-ubuntu-20.04-RoW-desktop-1.0.162",
  "version": "1.0.162",
  "region": "RoW",
  "variant": "desktop",
  "platform": "qcm6490",
  "board": "formfactor_dvt",
  "os": "linux",
  "distribution": "ubuntu",
  "distribution_version": "20.04",
  "distribution_variant": "ubuntu",
  "build_date": "2025-07-31T21:54:47.056539",
  "artifacts": [
    {
      "artifact_url": "https://tachyon-ci.particle.io/release/tachyon-ubuntu-20.04-RoW-desktop-formfactor_dvt-1.0.162.zip",
      "sha256_checksum": "f34a7f610c2485c3066d494f22e67acc7a89db0104b9201d3dd1bcb6e30573af",
      "type": "release_image"
    }
  ]
},

Choose the image that matches your needs:

  • Region: NA (North America) or RoW (Rest of World)
  • Variant: headless or desktop
  • Board: make sure to use formfactor_dvt as the board type!

Step 2: Download and Flash the Image

Example:

wget https://tachyon-ci.particle.io/release/tachyon-ubuntu-20.04-NA-headless-1.0.61.zip
particle flash --tachyon ./tachyon-ubuntu-20.04-NA-headless-1.0.61.zip

Known Issues

Some users have reported flashing failures at ~99%, particularly when writing to modem_a.

Example error output:

[ERROR] bulk write failed: Operation timed out
[ERROR] USB write failed for data chunk
[ERROR] firehose_run failed
Unable to complete device flashing.

If you see this, try the following:

  • Use a high-quality USB 3.0 cable — some cables cause unreliable transfers as the data speed is pretty high
  • Avoid USB hubs — plug directly into your host machine.
  • Try the flash again - sometimes transient errors can be resolved with a retry.

Additional Notes

  • To see all available flashing options:
particle flash --tachyon --help

If you’re still having trouble, check the CLI output for the path to the .log file, or post your issue in the Particle Community.

Check the battery current level​

cat /sys/class/power_supply/battery/capacity

Output is 0 to 100% depending on the battery charge level.

Check if the battery is charging!​

cat /sys/class/power_supply/battery/status

This returns one of the following:

  • Charging
  • Discharging
  • Full
  • Not Charging

Check the instantaneous current from the battery​

cat /sys/class/power_supply/battery/current_now

The output is in microamperes (µA). To convert it to amperes (A), divide by 1,000,000.

Check the battery voltage​

cat /sys/class/power_supply/battery/voltage_now

Output is a number such as 3914982 which when padded out gives us 3,914,982 which is 3.9V

Check if USB-C is connected and available as a power source​

cat /sys/class/power_supply/usb/online

1 == online and available! 0 == not present.

Here is the QXDM section formatted in raw Markdown for inclusion in your Docusaurus Tips & Tricks page:

Using QXDM for Debug Logging​

Qualcomm’s QXDM (Qualcomm eXtensible Diagnostic Monitor) is a powerful tool for capturing low-level modem and system logs from Tachyon devices. It supports both on-device logging and live logging over USB or network.

Before you start, download the tools and check the relevant Qualcomm documentation:

  • Download QXDM via CreatePoint
  • Refer to:
    • QXDM Professional V5 for Windows OS User Guide (80-V1241-25)
    • QCM6490/QCS6490 Linux Android Software User Manual (SP80-PT831-4)

Option 1: On-Device Logging (Pull Logs After Testing)​

This method stores logs locally on the device and allows you to retrieve them after the test session.

Step 1: Generate a .cfg Log Mask File​

In QXDM:

Tools → CFG File Generator → Enable CHGPD → Select SD Logging Save Diag Masks for Stream 1 → OK

Save the file as diag.cfg.

Step 2: Push the Configuration File to the Device​

adb shell mkdir /tmp/diag_logs
adb push diag.cfg /tmp/diag_logs/diag.cfg

(noting you can put log files wherever you want!)

⚠️ If no config file is provided, default masks will be used.

Step 3: Start Logging on the Device​

Connect via adb, serial, or terminal and run:

sudo echo 1 > /proc/sys/kernel/printk
sudo diag_mdlog -o /tmp/diag_logs/ -f /tmp/diag_logs/diag.cfg &

If diag.cfg is not present, remove the -f option:

sudo diag_mdlog -o /tmp/diag_logs/ &

Example output:

diag_mdlog: command = o
diag_mdlog: command = f
diag:successfully connected to socket 5
diag:main: kernel supported: NUM_PERIPHERALS = 12, DIAG_CON_ALL: 4095
diag: No Session is active for the given mask
diag_mdlog: Closing diag_fd_temp
diag: Diag_LSM_DeInit: invoked for pid: 283962
diag: Diag_LSM_DeInit: Initiating deinit pkt transfer
diag: Diag_LSM_DeInit: Read status in CreateWaitThread, in_read: 1
diag: CreateWaitThread, Read DEINIT_TYPE packet
diag: Diag_LSM_DeInit: sending signal to unblock read thread
diag: CreateWaitThread, Exiting...
diag: Diag_LSM_DeInit: status of deinit_rcvd: 1, sig_rcvd: 0
diag: Diag_LSM_DeInit: Joining the read thread, deinit_rcvd: 1, sig_rcvd: 0
diag: Diag_LSM_DeInit: done for pid: 283962
diag_mdlog: Warning output directory already exists: /tmp/diag_logs
diag_mdlog: Proceeding...
diag:successfully connected to socket 6

diag_mdlog: Diag_LSM_Init succeeded.

 REMOTE PROCESSOR MASK 0
diag:kernel supported: NUM_PERIPHERALS = 12, DIAG_CON_ALL: 4095
diag: wrote switch log pkt ret:32
 logging switched 
Output dirs /tmp/diag_logs --- /tmp/diag_logs/

diag_mdlog: Reading mask for MSM, proc_type: 0
Reading the mask file: /tmp/diag_logs/diag.conf
diag: Determining contents of directory /tmp/diag_logs/ for circular logging ...
diag: Determining contents of directory /tmp/diag_logs/ for circular logging ...

 creating new file /tmp//diag_log_20250807_1123531754562233992.qmdl

Step 4: Stop Logging and Pull Logs​

sudo diag_mdlog -k
adb pull /tmp/diag_logs/<log_filename>.qmdl

Open the .qmdl file in QXDM on your computer for analysis.

Option 2: Live Logging via Network (TCP)​

This method streams logs in real time over TCP using QUTS (QXDM Unified Transport Server).

Step 1: Start TCP Server in QXDM​

In QXDM5 or later:

Actions → Start TCP Server

Make sure your PC’s firewall allows incoming connections on port 5000.

Step 2: Start Logging from the Device​

diag_socket_log -a <PC_IP_ADDRESS> -p 5000 -r 2 &

Where:

  • -a is the IP address of the PC running QXDM
  • -p is the port (usually 5000)
  • -r 2 specifies the logging mode

Step 3:​

The logs should appear live in the QXDM interface.

Note: You need to connect to the IP address in the 'Device Selection' window to enable those logs.

Power and USB Notes​

  • Use USB1 port on the device.
  • Attach a battery if your PC cannot provide sufficient USB power (recommend to keep this connected so you can remove the USB if things need a shell reset)
  • These tools require root access on the device (via ADB, serial, or terminal).

Troubleshooting​

  • If you get errors like No Session is active for the given mask or Error reading mask file, double-check the .cfg file.
  • If no valid masks are applied, QXDM may fall back to a default list or log very little data.

Got More Tips?​

We’re always looking for more useful tricks! If you’ve found something helpful, share it in the Tachyon community forum.