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
Download the right toolchain for your system:
Install
Add the toolchain path to the system PATH environment variable
Option 2. ESP-IDF (Xtensa and RISC-V)
If you’re using VSCode, ESP-IDF extenstion is the most convenient way to use it.
Otherwise follow the getting started guide on their site.
2. Install platform specific SDKs
Option 1. nRF Connect SDK
Please follow the getting started guide available on their site.
Option 2. STM32Cube
Download the proper STM32Cube firmware package for your board:
Alternatively you can install and use STM32CubeMX or STM32CubeIDE
Option 3. Zephyr RTOS
Please follow the getting started guide available on their site.
3. Fork a template
nRF52 project template
RP2040 project 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
Download from releases on Github.
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
add the sources under
$LIBMCU_ROOT/modules/[common, actor, ...]/src/**/*.c
to your projectadd the sources under
$LIBMCU_ROOT/ports/<platform specific>/<feature specific>.c
to your projectadd
$LIBMCU_ROOT/modules/[common, actor, ...]/include
to the include paths for your project