Skip to main content

How to Build the Ubuntu 24.04 Image

Scope — Images for Tachyon Only

This page is only about assembling full system images for Tachyon.
If your goal is to modify U-Boot or the kernel on a running device, you can do that directly on-device like a standard Linux system.
See the separate pages on U-Boot and building the kernel for those workflows.

Build instructions do not work on the Tachyon device

This page contains instructions for how to build Tachyon on a host device (such as x86 PC, Mac etc...). Building Tachyon on a device is not tested specifically because the build system can eat up a lot of resources and the build system was not constrained to make sure this was handled correctly.

This page provides step-by-step instructions for building the Tachyon Ubuntu 24.04 system image from source.
By following these steps, you can generate your own image, apply custom changes, or contribute improvements.

The build process uses open-source repositories maintained by Particle.

We recommend performing the build on a macOS/Linux host.

Prerequisites​

  • Git – to fetch the source code repositories
  • Make – ensure make is installed on your host machine
  • Docker – required for build containers

Cloning the Build Repositories​

Start by cloning the primary build orchestrator repository, tachyon-composer, which contains the main Makefile that drives the build.

git clone https://github.com/particle-iot/tachyon-composer.git
cd tachyon-composer

The composer automatically uses other repositories, either by downloading releases or locating them locally. It can fetch prebuilt components for specified version numbers.

For most users, cloning other repositories is optional. If you want to inspect or modify components, clone them alongside tachyon-composer:

git clone https://github.com/particle-iot/tachyon-ubuntu-24.04.git
git clone https://github.com/particle-iot/tachyon-ubuntu-24.04-kernel.git
git clone https://github.com/particle-iot/tachyon-u-boot.git
git clone https://github.com/particle-iot/tachyon-overlays.git
git clone https://github.com/particle-iot/tachyon-overlay-tool.git

Running the Build​

All build steps are handled by the make command provided by tachyon-composer.

🧩 Simple Build (Recommended First)

Run this first to confirm your environment is working:

make build_24.04 \
  VERSIONS_FILE=./versions.json \
  INPUT_REGION=RoW \
  INPUT_VARIANT=desktop

Parameters:

  • VERSIONS_FILE=./versions.json — Uses the default versions file to select the latest component releases from upstream repositories
  • INPUT_REGION=RoW — Region for the build. Use NA for North America or RoW (Rest of World)
  • INPUT_VARIANT=desktop — Variant to build. Only desktop is supported at this time

This builds using the most up-to-date versions without manually specifying component versions.

Full Build with Explicit Versions​

For more control, you can specify all inputs directly:

make build_24.04 \
  INPUT_BASE_20_04_VERSION=1.0.170 \
  INPUT_REGION=NA \
  INPUT_UBOOT_VERSION=1.0.4 \
  INPUT_BASE_24_04_VERSION=14-276cd6b \
  INPUT_OVERLAY_STACK=ubuntu-desktop-24.04 \
  INPUT_ENV_VARS="PKG_particle_linux=0.20.1-1,PKG_particle_tachyon_desktop_setup=2.7.0,PKG_particle_tachyon_ril=0.4.5-1,PKG_particle_tachyon_syscon=1.0.19-1,PIN_PRIORITY=900"

If all parameters are specified, the VERSIONS_FILE is not required. The build will fetch and assemble the specified components exactly as defined.

Using a Local U-Boot Directory​

If you’re modifying U-Boot (for example, editing DTS files), you can use a local build by specifying a directory:

make build_24.04 \
  VERSIONS_FILE=./versions.json \
  INPUT_REGION=RoW \
  INPUT_VARIANT=desktop \
  INPUT_UBOOT_DIR=../tachyon-u-boot
  • INPUT_UBOOT_DIR points to a local directory on your disk
  • This is useful for rapid iteration — clone, modify, build, and test locally

What the Build Does:

  1. Fetches base images – Downloads the base 20.04 image and 24.04 rootfs if missing
  2. Merges components – Injects Tachyon-specific kernel, firmware, and U-Boot
  3. Applies overlays – Uses tachyon-overlay-tool to apply configuration and package overlays
  4. Assembles final image – Produces a complete disk image and zipped bundle with metadata

Build time: The full process can take around 1 hour depending on system and network speed

Build Output​

The output is stored under:

./.tmp/output/tachyon-ubuntu-24.04-RoW-desktop-formfactor_dvt-9.9.999.zip

This file contains the final disk image and metadata needed for flashing.

Flashing the Image to Tachyon​

⚠️ Important

Installing a custom-built image is currently a manual process and carries risk. Tachyon’s bootloader and partition structure are complex (A/B slots, modem firmware, etc.). Proceed only if you are comfortable wiping the device.

Use the Particle CLI to install:

Recommended (with setup):

particle tachyon setup --version=<output_bundle_file.zip>

Direct flash:

particle flash --tachyon <output_bundle_file.zip>

Troubleshooting:​

  • Run make clean to remove intermediate artifacts
  • Check logs carefully for missing dependencies or network errors
  • Ensure sufficient disk space (8–10 GB recommended)
  • Cached artifacts are stored in .tmp/; reuse them to speed up builds

Next Steps

With a successful build, you now have a working Ubuntu 24.04 image for Tachyon. Continue by reviewing the pages on Tachyon boot flow, U-Boot, and Kernel development to understand how each layer integrates.