Getting Started

This guide describes how to get started with libmcu by creating a new project from a template and how to integrate libmcu into an existing project.

See also User Manual and API Reference for more information.

Creating a new project

Tip

If you’re using VSCode, follow this step-by-step guide: Visual Studio Code for Firmware Development.

1. Set up the toolchain

Option 1. ARM Cortex-M

  1. Download the right toolchain for your system:

  2. Install

  3. Add the toolchain path to the system PATH environment variable

Option 2. ESP-IDF (Xtensa and RISC-V)

2. Install platform specific SDKs

Option 1. nRF Connect SDK

Option 2. STM32Cube

Option 3. Zephyr RTOS

3. Fork a template

4. Tweak some source code

int main(void)
{
     board_init(); /* should be called very first. */

     logging_init(board_get_time_since_boot_ms);
     logging_stdout_backend_init();

     const board_reboot_reason_t reboot_reason = board_get_reboot_reason();
     info("[%s] %s %s", board_get_reboot_reason_string(reboot_reason),
                     board_get_serial_number_string(),
                     board_get_version_string());

     struct gpio *led = gpio_create(PINMAP_LED);
     gpio_enable(led);

     while (1) {
             gpio_set(led, gpio_get(led) ^ 1);
             sleep_ms(500);
     }

     return 0;
}

5. Build the project

Make and CMake supported for building projects, so use your favorite.

Make

$ make

CMake

$ cmake -G Ninja -B build
$ cmake --build build

Note

For ESP-IDF or Zephyr, you can use idf.py or west repectively.

6. Flash onto the device

Make

$ make flash

CMake

$ cmake --build build --target flash

Note

J-Link is used as the debugger by default. To change to a different debugger or a different target device, see Flash onto the device.

Integrating into an existing project

The library can be intergrated in your project as a git submodule, using CMake FetchContent, or downloading manually.

1. Download Library

Option 1. git submodule

$ cd ${YOUR_PROJECT_DIR}
$ git submodule add https://github.com/libmcu/libmcu.git ${THIRD_PARTY_DIR}/libmcu

Option 2. Downloading latest release

  1. Download from releases on Github.

  2. And put it somewhere in your project

2. Integrating into your project

Note

Variable names between angle brackets(e.g. <SRC_FILES>) should be modified to suit your project.

Option 1. Make

LIBMCU_ROOT ?= <THIRD_PARTY_DIR>/libmcu
# The commented lines below are optional. All modules and interfaces included
# by default if not specified.
#LIBMCU_MODULES := actor metrics
include $(LIBMCU_ROOT)/projects/modules.mk

<SRC_FILES> += $(LIBMCU_MODULES_SRCS)
<INC_PATHS> += $(LIBMCU_MODULES_INCS)

#LIBMCU_INTERFACES := gpio pwm
include $(LIBMCU_ROOT)/projects/interfaces.mk

<SRC_FILES> += $(LIBMCU_INTERFACES_SRCS)
<INC_PATHS> += $(LIBMCU_INTERFACES_INCS)

Option 2. CMake

add_subdirectory(<THIRD_PARTY_DIR>/libmcu)

or

set(LIBMCU_ROOT <THIRD_PARTY_DIR>/libmcu)
include(${LIBMCU_ROOT}/projects/modules.cmake)
include(${LIBMCU_ROOT}/projects/interfaces.cmake)

# Add ${LIBMCU_MODULES_SRCS} to your target sources
# Add ${LIBMCU_MODULES_INCS} to your target includes

Option 3. CMake FetchContent

include(FetchContent)
FetchContent_Declare(libmcu
                  GIT_REPOSITORY https://github.com/libmcu/libmcu.git
                  GIT_TAG main
)
FetchContent_MakeAvailable(libmcu)

Option 4. Other

  1. add the sources under $LIBMCU_ROOT/modules/[common, actor, ...]/src/**/*.c to your project

  2. add the sources under $LIBMCU_ROOT/ports/<platform specific>/<feature specific>.c to your project

  3. add $LIBMCU_ROOT/modules/[common, actor, ...]/include to the include paths for your project