Skip to main content

yotta is the software module system used in Mbed OS 3 (Mbed OS 5 uses alternative build tools). It is responsible for assembling the software modules that your application needs and controlling the build system to make those modules available to you.

yotta makes it easy to reuse software modules in C and C++ software and provides an offline toolchain for the Arm Mbed IoT Platform. It is open-source, and we encourage other C and C++ software projects to adopt it as well. Even outside Mbed, yotta enables wider reuse of C-family software modules and accelerates application development.

yotta is a command line tool written in Python. It runs on Linux, Windows and OS X. It allows you to develop and build your software in an offline environment. When you use a new open-source module in your program yotta will download it for you from the yotta modules registry. yotta also supports early development by pulling modules from a git repository, including any private GitHub repos that you have access to. 

Using yotta as the foundation for software development on Mbed means that development can move seamlessly between different IDEs, whether they are online or desktop based.

Installing yotta

Installers for Windows and OSX are available for download here:

Windows Installer

File size: 168 MB

Download for Windows 

OSX Installer

File size: 190 MB

Download for OSX 

Older releases for Windows and OSX can be found on GitHub:

Windows installer releases | OSX installer releases

Structure of a yotta module or application

An application and a reusable yotta module have similar structures:

  • A module.json file.
  • A source directory containing source files to compile.
  • A headers directory with the same name as the module.
  • A test directory.
  • A file summarizing the API of the module.
  |_ module.json
  |_ source
  |  |_ a_file.cpp
  |  \_ another.cpp
  |_ mymodule
  |  |_ a_header.h
  |  \_ some_other_header.h
  |_ test
  |  |_some_test.c
  |  \_subdir
  |    |_supporting_file.c
  |    \_main.c

The module.json file is the most important file in a yotta module. It describes the name, semantic version and license information of this module to yotta. It also describes any dependencies that this module might have. A module can be either an executable application or a reusable library; the module.json file specifies if the module is compiled into an executable application, otherwise it is a reusable library module.

The source directory and any subdirectories contain the source files that yotta will automatically use to build the library. Source files in any other top-level directories will normally be ignored. See the build process description below for exceptions.

The headers directory should have the same name as your module and should contain all (and only) the public headers that your module exposes to anyone that depends on it. The name must be the same as your module name so that `#include` directives look like `#include "modulename/a_header.h"`, which prevents conflicts between multiple modules that have headers with the same name.

The test directory contains source files and subdirectories to compile into tests. yotta strongly encourages writing tests for modules (and makes it really easy!), because thorough testing is an important part of making software truly reusable. Any source files at the top-level of the test directory will be compiled into separate test executables, and the (recursive) contents of any subdirectories will each be compiled into a single test executable. You can use the `yotta test` subcommand to automatically build and run these tests

You can use `yotta init` to construct a new skeleton module or application in an empty directory by answering a simple series of questions. 

A guide to creating your first yotta module and application, which also explains some best practices, can be found on the yotta docs site.

The yotta module registry

The yotta module registry makes it possible to publish, find and reuse yotta modules. It stores snapshots of versions of modules that people have published, allows people to search for them and makes them available for other people to download.

Publishing a module to the yotta registry requires an open-source compatible license (our favorite is Apache 2.0). Modules that contain binary blobs of any sort must ensure that the binary is at least free for people to reuse in open-source applications.

Finding and using modules

There are several ways to find modules in the yotta registry:

  •   From the website, which lists Mbed modules built by the mbed community.
  •   Searching the registry through the web interface at
  •   Searching from the command-line, using the `yotta search` subcommand.
  •   Via Google, or another search engine.

Once you've found a module, you can add it as a dependency of your current module or application by running:

yotta install --save <modulename>

This will automatically update the dependencies in your module.json file and download the module.

You can also manually edit the module.json file in order to change the version of the module that you depend on. Editing the module.json file also allows you to specify that the module should be retrieved from GitHub or a git repository instead of the public registry. For more details on this, check out the module.json documentation.

Publishing modules

When you're ready for someone else to use your module, you can make it available in the registry by publishing it. This is as simple as running `yotta publish` in the directory of your module, which will upload the current version to the registry and make it available for other people to find and use.

yotta modules are versioned according to the Semantic Versioning specification, so before publishing a new version of your module you should update the version number to reflect the changes you've made. The `yotta version` subcommand can help you do this. For example, use `yotta version patch` to bump the least-significant (patch) version of your module.

For a more detailed explanation of publishing yotta modules, be sure to check out the guide.

yotta target descriptions

One of the most important features of yotta is the ability to compile the same software for different compilation targets, such as different development boards, embedded devices, or even desktop targets. The modularity enabled by yotta allows modules to adapt the way that they work to different target devices.

Before you build anything with yotta, select the target that you want to build for using the `yotta target` subcommand. The instructions for a particular development board or shield will tell you which target to use to build software for that hardware target, or you can find target descriptions by searching the yotta registry.

Common targets include:

  • `frdm-k64f-gcc` for compiling for the FRDM-K64F development board using the arm-none-eabi-gcc compiler.
  • `x86-linux-native` and `x86-osx-native` for compiling natively for OS X and Linux, using the system compilers (normally gcc and clang respectively). Note that Mbed OS does **not** support cross-compilation to desktop platforms as a whole, but this can be useful for testing your own modules.

To provide consistent functionality across different targets, modules can use the "targetDependencies" section of their module.json files to specify dependencies that should be included only when compiling for certain kinds of targets.

Creating your own target description

yotta target descriptions can inherit from other target descriptions. This means that when you're creating your own board based on an existing Mbed development board, you can create a target description that specifies the existing development board as its base target. This way you'll be able to compile software that works for that development board for your new target and override only the things that you need to change.

More information is available on the yotta targets tutorial.

The build process

yotta uses the powerful CMake build system. It isn't necessary to write any CMake code to create simple modules and applications because yotta will generate the CMake descriptions for you. However, if you need to, then CMake allows you to add custom build steps and write your own target descriptions.

By default yotta configures CMake to use the Ninja build tool to drive the compiler. Ninja tracks which files have changed since the previous build and will only run the minimal set of build steps. Ninja is like the classic `make` program, but much faster and optimized to be driven by other programs rather than by humans.

Everything that yotta generates during a build is created within the `build` subdirectory of your application, which is divided by target. This means it's possible to safely build and test for several different targets without having to clean your build.The yotta build process

The yotta build process

Overriding yotta's default build rules

To override yotta's default build rules for the `source` and `test` directories, place your own CMakeLists.txt file in these directories. yotta will also ensure that any CMakeLists.txt file in any other top-level subdirectory of your module is included in the build. The testing with yotta guide explains how to make yotta aware of any tests you add manually so that `yotta test` can run them.

yotta will also respect a CMakeLists.txt file at the top-level of your module. If this file is detected, then yotta will not automatically generate any build rules. This is useful if you're adding yotta support to a module with an existing build system, especially if the build system already uses CMake.

To ensure that yotta can automatically link your module to other modules, make sure you define exactly one library with the same name as your module. A custom build system may also define other build artifacts; In this case take care to ensure that you name them in a way that minimizes the likelihood of name collisions with other modules.

Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.