Kubos SDK Cheatsheet

Note

This doc refers to the process used for creating and interacting with projects written in C. Please see the separate docs for details about using Rust or Python.

Creating a Project

Run the kubos init -l command followed by the name of your project to bootstrap your Kubos project. This will create a new directory under your current working directory with your project’s name and add the source files for a basic Kubos C project (kubos-linux-example).

$ kubos init -l linux-project-name # Creates a project

Note

Inside of the build system there are several reserved words, which cannot be used as the name of the project. These are test, source, include, yotta_modules and yotta_targets.

The contents of your project directory should look something like this:

$ ls
CONTRIBUTING LICENSE.txt module.json README source yotta_modules yotta_targets

Here is a quick rundown of the files that were generated:

File/folder Description
project-name This folder is where header files live
source This folder is where source files live
test This folder is where test source files live
module.json This file is yotta’s module description file
yotta_modules This directory holds the symlinks for the project’s module dependencies
yotta_targets This directory holds the symlinks for the available Kubos targets
CONTRIBUTING.md The doc outlining the process of contributing to a Kubos project
LICENSE.txt The software license associated with the example project
README.md The readme for the example project that outlines some of the basic details of the example

Kubos uses the yotta build/module system, which is where this file structure comes from. You can read more about yotta here.

Selecting a Target

Kubos needs to know which target you intend to build for so it can select the proper cross compiler. Kubos currently supports several different targets:

Vendor Kubos Target Description
ISIS kubos-linux-isis-gcc ISIS-OBC
Pumpkin kubos-linux-pumpkin-mbm2-gcc Pumpkin Motherboard Module 2
Beaglebone kubos-linux-beaglebone-gcc Beaglebone Black, Rev. C
(Vagrant) x86-linux-native Native target for the Kubos Vagrant image

To select a target, use the kubos target command with the appropriate value from the “Kubos Target” column.

For example

$ kubos target kubos-linux-beaglebone-gcc

To see all of the available targets run:

$ kubos target --list

Building a Project

To build a Kubos project, all we need to do is run the kubos build command. The Kubos CLI will read the module.json file, determine what libraries are needed, and build them.

Basic build command:

$ kubos build

Build with verbose output:

$ kubos build -- -v

Note

The Kubos CLI commands have their own specific arguments that can be used. There are also global arguments (like --verbose or -v). A double hyphen -- separates the command specific arguments from the global arguments

Clean command:

$ kubos clean

To build a project from scratch run kubos clean to remove all remaining files generated for previous builds followed by kubos build.

Linking Local Modules and Targets

The Kubos SDK comes with all of the latest Kubos modules and targets pre-packaged and pre-linked. If a module or target needs to be modified locally, the CLI comes with the ability to link that local module into the build process.

Modules and Targets

Modules are groups of source code that implement a feature or unit of functionality. Kubos operating systems are split into a number of modules. An example of a Kubos module is the Kubos HAL

Targets are groups of configuration files that allow toolchains to build and cross-compile modules for specific hardware targets. One example of a Kubos target is the Beaglebone Black Target

Linking Modules

Links are made in two steps - first globally, then locally.

By linking a module globally you are making it available to link into any of your projects. By linking the module locally you are including the linked module in your build.

  • To link a module globally:

    $ cd .../<module-directory>/
    $ kubos link
    
  • To link a module that is already globally linked into a project:

    $ cd .../<project-directory>/
    $ kubos link <module name>
    

The next time your project is built it will use your local development module, rather than the packaged version.

Note

Use kubos list to see the modules and depencies being used by your project as well as the directories they are being referenced from

Linking Targets

Custom or modified targets are linked in a very similar way to modules.

Links are made in two steps - first globally, then locally.

By linking a target globally you are making it available to link into any of your projects. By linking the target locally you are now able to use the linked target in your build.

  • To link a target globally:

    $ cd .../<target-directory>/
    $ kubos link-target
    
  • To link a target that is already globally linked into a project:

    $ cd .../<project-directory>/
    $ kubos link-target <target name>
    
  • You may now use the standard target command to select the newly linked target:

    $ cd ../<project-directory>/
    $ kubos target <target name>
    

The next time your project is built it will use your local development target, rather than the packaged version.

Note

Running kubos target will show you whether you are using a local or a linked copy of a target

Flashing your Project

Ensure that your board is plugged into your computer.

Running the following command will list all of the available devices in your Kubos SDK box.

$ lsusb

Run the flash command

$ kubos flash

Note

If your current user does not have read/write permission to your hardware device you may need to run this command as root

$ sudo kubos flash