Skip to main content

Building Tachyon’s Ubuntu 24.04 Image

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 the open-source repositories discussed in the introduction. We recommend performing the build on a Tachyon device itself (running Ubuntu 20.04) or on an MacOS/Linux host with the appropriate cross-compilation tools installed.

Prerequisites​

  • Git: To fetch the source code repositories.
  • Make: Make sure that 'make' is installed on your host machine
  • Docker: 'Docker' is used to run the build containers

Cloning the Build Repositories​

Begin by cloning the primary build orchestrator repository, tachyon-composer. This contains the main Makefile that drives the build:

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

The composer will automatically utilize other repositories (either by downloading releases or expecting them in specific directories). It can fetch prebuilt components for given version numbers. However, if you intend to modify or build everything from scratch, you may also clone the other repos side by side. For a standard build using released components, cloning them manually is not strictly required – the make process will download needed artifacts.

If you do want to have the sources locally (for hacking or transparency), you can clone them as well in the same parent directory. For example:

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

(Cloning is optional; the build system can fetch released binaries using version numbers. But having them can help if you plan to modify or just inspect the code.)

Running the Build​

All build steps are handled through the make command provided by tachyon-composer. The composer supports building different OS versions and variants by specifying parameters. To build the Ubuntu 24.04 image, you’ll use the build_24.04 target along with a set of input variables that define exactly what to include.

Here’s an example command that initiates a build of the Ubuntu 24.04 image:

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-headless-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"

Let’s break down what these parameters mean:

  • INPUT_BASE_20_04_VERSION=1.0.170 – The base Ubuntu 20.04 Tachyon image version to use as a foundation. In this early phase, we incorporate parts of the 20.04 image (like partition layout, certain firmware) to ensure critical components (e.g., modem firmware) are present. Version 1.0.169 corresponds to a specific released Tachyon 20.04 build.

  • INPUT_REGION=RoW or NA – Region for the build. Tachyon has region-specific variants due to cellular modem differences. Use NA for North America or RoW for Rest of World, matching your device’s region.

  • INPUT_UBOOT_VERSION=1.0.4 – The version of the Tachyon U-Boot bootloader to include. This corresponds to a release of tachyon-u-boot (for example, 1.0.4 might be a tag or internal version of the bootloader). The build system will fetch the bootloader binary of that version to include, unless you override it with a custom build.

  • INPUT_BASE_24_04_VERSION=14-276cd6b – The base Ubuntu 24.04 root filesystem version to use. This likely points to a specific build of the tachyon-ubuntu-24.04 repository (for example, a commit hash or build number). It represents the rootfs and generic kernel for 24.04 before applying Tachyon customizations.

  • INPUT_OVERLAY_STACK=ubuntu-headless-24.04 – The overlay stack to apply on top of the base OS. In this example, we’re using the ubuntu-headless-24.04 stack, which will produce a headless image (no GUI). If you set INPUT_VARIANT=desktop, you might use an ubuntu-desktop-24.04 stack accordingly. The overlay stack defines extra packages, configs, and files to tailor the OS for Tachyon (for instance, enabling Wi-Fi at boot, adding Particle-specific utilities, etc.).

When you run this command, the build system will perform the following high-level steps:

  1. Fetch base images: It will download the specified base 20.04 image and base 24.04 rootfs (if not already present). These are used as input files.
  2. Merge and install components: The composer will take the 24.04 root filesystem and inject Tachyon-specific components. This includes installing the Tachyon-specific kernel (replacing the generic kernel in the rootfs), adding firmware binaries, and integrating the selected U-Boot bootloader into the image.
  3. Apply overlays: Using the tachyon-overlay-tool, the build will mount the filesystem and apply the overlay stack (ubuntu-headless-24.04 in the example). This step might install additional Debian packages, copy configuration files (such as enabling ssh or setting default user accounts), and generally customize the image to be “Tachyon-friendly.”
  4. Assemble final image: The result is packaged into a final disk image file (and possibly zipped into a bundle with metadata). The output will typically include a .img file (or a similar binary) representing the entire eMMC/UFS content for Tachyon, and/or a .zip bundle that the Particle CLI can use.

Build Time: Note that building the image from scratch can take quite some time (around an hour, depending on your machine and internet connection). The process has to construct an entire Ubuntu filesystem, which involves debootstrap and installing many packages, as well as building or downloading kernel and other components.

Build Output​

Upon success, the build process will place the output in a directory and includes the main release file:

./.tmp/output/tachyon-ubuntu-24.04-RoW-desktop-formfactor_dvt-9.9.999.zip - containing the image and metadata.

Make sure to note where the build saved these files. The image is what you will flash onto the Tachyon’s storage to run Ubuntu 24.04.

Flashing the Image to Tachyon

⚠️ Important

At this time, installing the custom-built image is a manual process and can carry risk. Tachyon’s bootloaders and partition layout are intricate (A/B slots, modem firmware, etc.). Proceed with caution and only flash if you’re comfortable loosing any data from the device.

Currently, the recommended way to deploy an image to Tachyon is using the Particle CLI or via the upcoming official OTA mechanism:

  • Its recommended that you use the setup function (as its captures initial wifi info etc...):

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

  • You can also direct flash using this command:

    particle flash --tachyon <output_bundle_file.zip>

For now, if your goal is to tinker and contribute, we suggest focusing on building and modifying the image. You can test changes on a Tachyon that you don’t mind resetting. Official released builds of 24.04 (once available) will come with easier installation instructions.

Troubleshooting the Build​

  • If in doubt, 'make clean' to remove all intermediate builds
  • If the build fails at some step, examine the output log. Common issues might be missing host tools or packages. Ensure all prerequisites are installed.
  • Network issues can cause package download failures. The build downloads Ubuntu packages and Particle artifacts – make sure your internet connection is stable.
  • Storage space: Building can consume several GB of space (the final image itself might be 5–8 GB, plus working files). Ensure you have enough disk space on the build machine.
  • To speed up iterative development, you might reuse some artifacts (for example, you don’t need to re-download base images each time). The composer will cache these in a .tmp folder by default. You can also adjust the input versions to point to local files or directories if you have them (advanced usage).

With a successful build, you now have a Tachyon Ubuntu 24.04 image ready. Next, let’s understand how Tachyon boots this new image and what the boot process entails.