Kubos Project Configuration

For Kubos projects using C, the project configuration is derived from yotta’s configuration system and module.json files.

If a project’s configuration is changed, the new settings will be incorporated during the next execution of kubos build.

config.json

Overview

Each Kubos target comes with a set of default configuration options. These options describe things like hardware bus availability and communication settings. The config.json file, which lives in the top level directory of a Kubos project, allows users to override any of these options with a custom value.

Under the covers, the target.json and config.json files are used to generate a yotta_config.h file, which contains #define YOTTA_CFG_{option} statements for each defined option. These YOTTA_CFG_* variables can then be referenced within the Kubos project’s source code.

The current configuration of a project can be seen using the kubos config command. Each configuration option in the output will have a comment showing the origin of the value. Anything marked with “application’s config.json” will have been taken from the project’s config.json file. All other comments will have “*-gcc”, which indicates that that option is a default value taken from the corresponding target.json file.

For example:

$ kubos config

{
  "hardware": {
    "i2c": {
      "count": 1, // kubos-linux-isis-gcc
      "defaults": {
        "bus": "K_I2C1", // kubos-linux-isis-gcc
        "role": "K_MASTER", // kubos-gcc
        "clockSpeed": 100000, // kubos-gcc
        "addressingMode": "K_ADDRESSINGMODE_7BIT" // kubos-gcc
      },
      "i2c1": {
        "device": "/dev/i2c-0" // kubos-linux-isis-gcc
      }
    },
    "uart": {
      "count": 0, // kubos-gcc
      "defaults": {
        "baudRate": 9600, // kubos-gcc
        "wordLen": "K_WORD_LEN_8BIT", // kubos-gcc
        "stopBits": "K_STOP_BITS_1", // kubos-gcc
        "parity": "K_PARITY_NONE", // kubos-gcc
        "rxQueueLen": 128, // kubos-gcc
        "txQueueLen": 128 // kubos-gcc
      }
    },
    "spi": {
      "count": 0, // kubos-gcc
      "defaults": {
        "bus": "K_SPI1", // kubos-gcc
        "role": "K_SPI_MASTER", // kubos-gcc
        "direction": "K_SPI_DIRECTION_2LINES", // kubos-gcc
        "dataSize": "K_SPI_DATASIZE_8BIT", // kubos-gcc
        "clockPolarity": "K_SPI_CPOL_HIGH", // kubos-gcc
        "clockPhase": "K_SPI_CPHA_1EDGE", // kubos-gcc
        "firstBit": "K_SPI_FIRSTBIT_LSB", // kubos-gcc
        "speed": "10000" // kubos-gcc
      }
    }
  },
  "system": {
    "initAfterFlash": false, // kubos-linux-gcc
    "initAtBoot": false, // kubos-linux-gcc
    "runLevel": 50, // kubos-linux-gcc
    "destDir": "/home/system/usr/local/bin", // kubos-linux-gcc
    "password": "Kubos123" // kubos-linux-gcc
  }
}

Custom Settings

Users can add new settings to a config.json file which can then be used within their project. These settings will be generated as #define YOTTA_CFG_{user_option} {value} statements during project compilation time.

For example:

{
  "CSP": {
    "my_address": "1",
    "target_address": "2",
    "port": "10",
    "uart_bus": "K_UART6",
    "uart_baudrate": "115200",
    "usart": {}
  }
}

Will generate the following statements:

#define YOTTA_CFG_CSP_MY_ADDRESS 1
#define YOTTA_CFG_CSP_TARGET_ADDRESS 2
#define YOTTA_CFG_CSP_PORT 10
#define YOTTA_CFG_CSP_UART_BUS K_UART6
#define YOTTA_CFG_CSP_UART_BAUDRATE 115200
#define YOTTA_CFG_CSP_USART

Non-Default Settings

These are settings which are not included by default as part of any target device, so must be explicitly provided in a config.json file in order to be made available to the project.

SDIO

General SDIO support is turned on via the hardware.sdio object. This support is not automatically included with any target device.

hardware.sdio

SDIO support

There are no configuration properties for this object. It simply enables the use of the HAL SDIO library

Example:

{
    "hardware": {
        "sdio": {}
    }
}

User-Configurable Included Settings

These are settings which may be changed by the user without compromising the target device, but which will automatically be included in the project without a config.json file present.

System

system

Kubos Linux file system properties related to Kubos applications

Object Properties:
 
  • initAfterFlash (boolean) – (Default: false) Specifies whether the application should be started as a background daemon on the target device immediately after being flashed
  • initAtBoot (boolean) – (Default: true) Specifies whether the application should be started on the target device during system initialization. An init script will be generated with the run level specified by runLevel
  • runLevel (number) – (Default: 50. Range: 10-99) The priority of the generated init script. Scripts with lower values will be run first
  • destDir (string) – (Default: “/home/system/usr/local/bin”) Specifies flashing destination directory for all non-application files
  • password (string) – (Default: “Kubos123”) Specifies the root password to be used by ``kubos flash` to successfully connect to the target device

Example:

{
    "system": {
      "initAfterFlash": true,
      "initAtBoot": true,
      "runLevel": 40,
      "destDir": "/home/myUser/storage",
      "password": "password"
    }
}

Hardware

hardware

Description of target board’s hardware peripherals

Object Properties:
 
  • console (console) – Debug console
  • externalClock (integer) – Clock rate of external clock
  • pins (pins) – Custom name -> pin mapping
  • i2c (i2c) – Availability and properties of I2C
  • uart (uart) – Availability and properties of UART
  • spi (spi) – Availability and properites of SPI
hardware.console

The debug UART console

Object Properties:
 
  • uart (KUARTNum) – UART bus to connect to
  • baudRate (string) – (Default: “115200”) Connection speed

Example:

{
    "hardware": {
        "console": {
            "uart": "K_UART1",
            "baudRate": "9600"
        }
    }
}
hardware.pins

Custom name -> pin mapping. Allows more readable pin names to be used in Kubos projects.

Object Properties:
 
  • {pin-name} (pin) – Pin name/value pair

Example:

{
    "hardware": {
        "pins": {
            "LED1": "PA1",
            "LED2": "PA2",
            "USER_BUTTON": "PA3"
        }
    }
}
hardware.i2c

Availability and properties of I2C on the target device

Object Properties:
 
  • count (integer) – Number of I2C buses available
  • defaults (defaults) – Default I2C connection settings
  • i2c{n} (bus) – I2C bus definitions

Example:

{
    "hardware": {
      "i2c": {
        "count": 2,
        "defaults": {
          "bus": "K_I2C1",
          "role": "K_MASTER",
          "clockSpeed": 100000,
          "addressingMode": "K_ADDRESSINGMODE_7BIT"
        },
        "i2c1": {
          "scl": {
            "pin": "PB6",
            "mode": "GPIO_MODE_AF_PP",
            "pullup": "GPIO_NOPULL",
            "speed": "GPIO_SPEED_MEDIUM"
          },
          "sda": {
            "pin": "PB7",
            "mode": "GPIO_MODE_AF_OD",
            "pullup": "GPIO_PULLUP",
            "speed": "GPIO_SPEED_MEDIUM"
          },
          "alt": "GPIO_AF4_I2C1"
        },
        "i2c2": {
          "scl": {
            "pin": "PB10",
            "mode": "GPIO_MODE_AF_PP",
            "pullup": "GPIO_NOPULL",
            "speed": "GPIO_SPEED_MEDIUM"
          },
          "sda": {
            "pin": "PB11",
            "mode": "GPIO_MODE_AF_OD",
            "pullup": "GPIO_PULLUP",
            "speed": "GPIO_SPEED_MEDIUM"
          },
          "alt": "GPIO_AF4_I2C2"
        }
      }
    }
}
hardware.i2c.defaults

Default I2C connection settings

Object Properties:
 
hardware.i2c.i2c{n}

I2C bus definition

Object Properties:
 
  • scl (scl) – Clock line settings
  • sda (sda) – Data line settings
  • alt (string) – (STM32F4* only) GPIO alternate function mapping (GPIO_AFx_I2Cy)
hardware.i2c.i2c{n}.scl

I2C bus clock line settings

Object Properties:
 
  • pin (pin) – Clock line pin
  • mode (KGPIOMode) – Pin GPIO mode
  • pullup (KGPIOPullup) – Pin pullup/pulldown setting
  • speed (type) – Clock line speed (GPIO_SPEED_[LOW, MEDIUM, FAST, HIGH])
hardware.i2c.i2c{n}.sda

I2C bus data line settings

Object Properties:
 
  • pin (pin) – Data line pin
  • mode (KGPIOMode) – Pin GPIO mode
  • pullup (KGPIOPullup) – Pin pullup/pulldown setting
  • speed (string) – Data line speed (GPIO_SPEED_[LOW, MEDIUM, FAST, HIGH])
hardware.uart

Availability and properties of UART on the target device

Object Properties:
 
  • count (integer) – Number of UART buses available
  • defaults (defaults) – Default UART connection settings
  • uart{n} (bus) – UART bus definitions

Example:

{
    "hardware": {
      "uart": {
        "count": 2,
        "defaults": {
          "baudRate": 9600,
          "wordLen": "K_WORD_LEN_8BIT",
          "stopBits": "K_STOP_BITS_1",
          "parity": "K_PARITY_NONE",
          "rxQueueLen": 128,
          "txQueueLen": 128
        },
        "uart1": {
            "tx": "P33",
            "rx": "P34"
        },
        "uart2": {
            "tx": "P44",
            "rx": "P45"
        }
      }
    }
}
hardware.uart.defaults

Default UART connection settings

Object Properties:
 
  • baudRate (integer) – Default bus speed
  • wordLen (KWordLen) – Default word length
  • stopBits (KStopBits) – Default number of stop bits
  • parity (KParity) – Default parity setting
  • rxQueueLen (integer) – Default size of RX queue
  • txQueueLen (integer) – Default size of TX queue
hardware.uart.uart{n}

UART bus definition

Object Properties:
 
  • tx (pin) – Bus transmit pin
  • rx (pin) – Bus receive pin
hardware.spi

Availability and properties of SPI on the target device

Object Properties:
 
  • count (integer) – Number of SPI buses available
  • defaults (defaults) – Default SPI connection settings
  • spi{n} (bus) – SPI bus definitions

Example:

{
    "hardware": {
      "spi": {
        "count": 3,
        "defaults": {
          "bus": "K_SPI1",
          "role": "K_SPI_MASTER",
          "direction": "K_SPI_DIRECTION_2LINES",
          "dataSize": "K_SPI_DATASIZE_8BIT",
          "clockPolarity": "K_SPI_CPOL_HIGH",
          "clockPhase": "K_SPI_CPHA_1EDGE",
          "firstBit": "K_SPI_FIRSTBIT_LSB",
          "speed": "10000"
        },
        "spi1": {
          "mosi": "PA7",
          "miso": "PA6",
          "sck": "PA5",
          "cs": "PA4",
          "port": "GPIOA",
          "alt": "GPIO_AF5_SPI1"
        },
        "spi2": {
          "mosi": "PB15",
          "miso": "PB14",
          "sck": "PB13",
          "cs": "PB12",
          "port": "GPIOB",
          "alt": "GPIO_AF5_SPI2"
        },
        "spi3": {
          "mosi": "PC12",
          "miso": "PC11",
          "sck": "PC10",
          "cs": "PC8",
          "port": "GPIOC",
          "alt": "GPIO_AF6_SPI3"
        }
      }
    }
}
hardware.spi.defaults

Default SPI connection settings

Object Properties:
 
  • bus (KSPINum) – Default SPI bus
  • role (SPIRole) – Default communication role
  • direction (SPIDirection) – Default SPI communication direction/s
  • dataSize (SPIDataSize) – Default data size
  • clockPolarity (SPIClockPolarity) – Default clock polarity
  • clockPhase (SPIClockPhase) – Defaut clock phase
  • firstBit (SPIFirstBit) – Default endianness
  • speed (integer) – Default bus speed
hardware.spi.spi{n}

SPI bus definition

Object Properties:
 
  • mosi (pin) – Master-out pin
  • miso (pin) – Master-in pin
  • sck (pin) – Clock pin
  • cs (pin) – Chip-select pin
  • port (pin) – GPIO port that the SPI pins belong to
  • alt (string) – (STM32F4* only) GPIO alternate function mapping (GPIO_AFx_I2Cy)

module.json

The Kubos project’s module.json file is originally based on yotta’s module.json file

Default Configurations

When you run kubos init -l, a module.json file is created for you with some default values:

{
    "bin": "./source",
    "license": "Apache-2.0",
    "name": "{your-project-name}",
    "repository":{
        "url": "git://<repository_url>",
        "type": "git"
    },
    "version": "0.1.0",
    "dependencies":{
        "csp": "kubos/libcsp#~1.5.0"
    },
    "homepage": "https://<homepage>",
    "description": "Example app running on Kubos Linux."
}

Relevant Configuration Options

These are the configuration options which are most likely to be changed for a project. (For all other options, refer to yotta’s documentation.)

name

The module name, which is also used as the file name of the compiled application binary.

By default, this is the project name, however, it can be changed to anything.

Naming rules:

  • Must start with a letter
  • No uppercase letters
  • Numbers are allowed
  • Hyphens are allowed
bin

Relative path to the project’s source code.

dependencies

Project library dependencies.

To keep Kubos project binaries small, kubos build will only include libraries which have been specified in this object. As a result, if you want to use a Kubos library, it must be specified here, or must be included with another library you specify.

Object Properties:
 
  • {component} (string) – Project dependency location and/or version

Available dependency name/value pairs (hierarchy denotes included dependencies. Italics denotes yotta targetDependencies):

  • “ccan-json”: “kubos/ccan-json”

  • “cmocka”: “kubos/cmocka”

  • “csp”: “kubos/libcsp”

    • “kubos-hal”: “kubos/kubos-hal”
    • “tinycbor”: “kubos/tinycbor”

  • “kubos-hal”: “kubos/kubos-hal”

    • “csp”: “kubos/libcsp”

    • “kubos-hal-linux”: “kubos/kubos-hal-linux”

      • “kubos-hal” : “kubos/kubos-hal”

  • “isis-iobc-supervisor”: “kubos/isis-iobc-supervisor”

  • “tinycbor”: “kubos/tinycbor”