Terragraph is a gigabit wireless technology designed to meet the growing demand for reliable high-speed internet access. Documentation for the project can be found at terragraph.com.
This repository contains a software framework to build a complete Linux image for the radio nodes.
Terragraph uses the Yocto Project as the underlying build framework.
The Yocto naming pattern is used in this repository. A "meta-layer
" is used to
name a layer or a category of layers. A "recipe-abc
" is used to name a bitbake
recipe. The project itself exists as a meta layer on top of Poky, the
reference distribution of the Yocto Project.
-
recipes-backports - Backported recipes.
-
recipes-bsp - Extensions to BSP (Board Support Package) recipes.
-
recipes-connectivity - Extensions to various Poky networking recipes.
-
recipes-core - Extensions to various core recipes.
-
recipes-extended - Various tweaks to standard Poky recipes.
-
recipes-facebook - Meta's recipes for end-to-end networking setup and monitoring.
-
recipes-kernel - Build a Linux kernel.
-
recipes-radio - 60GHz radio drivers and firmware.
-
recipes-support - Various third-party helper libraries and utilities.
-
recipes-utils - Various helper scripts.
-
recipes-wifi - Recipes specific to Puma's ESP32 wifi module.
-
meta-x86 - Terragraph layer for building specific to x86 processors and emulation.
-
meta-qoriq - Terragraph layer for building specific to NXP QorIQ processors.
-
meta-qca - Terragraph layer for building specific to QTI-based radios on top of meta-qoriq.
-
conf - Various bitbake configuration files.
-
docs - Terragraph documentation.
-
docusaurus - Terragraph static website.
-
licenses - Additional open source licenses for code used in the project.
-
src - Sources for various Meta components.
-
utils - Miscellaneous utility scripts.
The build process automatically fetches all necessary packages and builds the complete Yocto image.
Building complete Yocto images from scratch can be time-consuming. It is
recommended that you set up a rather beefy machine or server with a flash
storage device for clean builds. To greatly reduce disk usage requirements
during builds, add INHERIT += "rm_work"
to conf/local.conf
in the build
directory.
The Yocto Project's Quick Start Guide covers how to set up a machine for
various platforms. Several Meta components require C++17 support and require a
modern GCC to compile. There are also a couple of different embedded firmwares
that can require additonal toolchains installed in /opt
. The
utils/docker/Dockerfile
script contains an example for setting up an Ubuntu
container to do meta-qca Puma-based builds. For other builds, the setup is
similar except that the ESP32 toolchain is not required.
By default, the builds are set to run with number of CPUs as both the number of
tasks and as the number of build threads. We have found that this can create
race conditions while building various components which results in mysterious
do_compilation
task failures. These can be resolved by rerunning the bitbake
command to retry the failed compilations.
The e2e-image target builds a tarball for an x86 chroot environment that can be used as the Terragraph E2E controller. This build target is available for all hardware platforms and is a good introduction to the Terragraph E2E stack and userland.
-
Set up the build environment based on the Yocto Project's Quick Start Guide.
-
Clone the Terragraph sources.
$ git clone https://github.com/terragraph/meta-terragraph.git
$ cd meta-terragraph
- Clone poky and meta-openembedded repositories into the
yocto
subdirectory.
$ ./sync_yocto.sh
- Initialize a build directory. After this step you will be dropped into the
build-x86
build directory.
$ source tg-init-build-env meta-x86 build-x86
- Start the build within the build directory. The build process automatically fetches all necessary packages and builds the complete image.
$ bitbake e2e-image
- Optionally run unit tests.
$ MY_BUILD_DIR=`pwd` ../utils/run_tests.sh
The final build result is
build-x86/tmp/deploy/images/tgx86/e2e-image-tgx86.tar.gz
. This is an x86
chroot environment suitable for use with the E2E controller.
Puma is an NXP/QTI-based radio platform and is available to build if there is a top-level meta-qca directory. It requires radio firmware from QTI to build.
-
Set up the build environment based on the Yocto Project's Quick Start Guide.
-
Install the ESP32 toolchain which is required to build the firmware for Puma's ESP32 wifi module. The expected location of the ESP32 toolchain is
/opt/esp32-toolchain/xtensa-esp32-elf
. SetESP32_TOOLCHAIN_PREFIX
inesp-fw_0.1.bb
for a different toolchain location. Note that the wifi firmware binaries and the script (flash_esp32
) required to flash the wifi module are all part of the Puma image.If you don't want to build the ESP32 wifi firmware, then skip the ESP32 toolchain installation and remove the
esp-fw
package from anyIMAGE_INSTALL
variables or pass-R ../conf/no-esp-fw.conf
to bitbake commands in later steps. -
Clone or untar the Terragraph sources.
$ git clone https://github.com/terragraph/meta-terragraph.git
$ cd meta-terragraph
- Clone poky and meta-openembedded repositories into the
yocto
subdirectory.
$ ./sync_yocto.sh
-
Acquire the radio firmware from QTI. This will generally be the latest available OEM (original equipment manufacturer) firmware. Terragraph uses the 3pp file to install both the firmware blobs as well as several utilities. This file will have a form similar to
qca6430-tg-1-0_qca_oem_3pp-r00083.1-0f0e6cdd976b960c43e4eb78e10def7470e82130.tar.gz
but with a different hash. Drop this file into theyocto/source_mirrors
directory created by./sync_yocto.sh
.Because the 3pp files vary from OEM to OEM, you may also have to edit the corresponding bitbake recipe include file to point at your filename and checksums, for example in
meta-qca/recipes-radio/wigig-utils/tg-qca6430-DPDK-OEMR2-CSU4-2022-01-20-OEM-ver-10-11-0-99-3pp.inc
. -
Initialize a build directory. After this step you will be dropped into the
build-qca
build directory.
$ source tg-init-build-env meta-qca build-qca
- Start the build within the build directory. The build process automatically fetches all necessary packages and builds the complete image.
$ bitbake terragraph-image
The final build result is
build-qca/tmp/deploy/images/qoriq/tg-update-qoriq.bin
. This file is a
self-extracting image for the Puma radios. Run ./tg-update-qoriq.bin -h
for
usage instructions.
Please review our Code of Conduct and Contributing Guidelines.
General discussions are held on our Discord server.
Terragraph is made up of different packages. Each package contains recipe files
that detail where to fetch source code from third party sources or local
directories. The recipe files themselves are provided under the MIT license in
licenses/Meta-MIT
, but your use of the code fetched by each recipe file is
subject to the licenses of each respective third-party project. Local components
are also specified under this MIT license unless otherwise stated.