.. _getting_started: 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 :ref:`usermanual` and :ref:`api` for more information. .. contents:: Table of Contents :depth: 3 Creating a new project ---------------------- .. tip:: If you're using VSCode, follow this step-by-step guide: :ref:`vscode`. 1. Set up the toolchain ^^^^^^^^^^^^^^^^^^^^^^^ Option 1. ARM Cortex-M """""""""""""""""""""" #. `Download `_ the right toolchain for your system: * `Windows(mingw-w64-i686) `_ * `Linux(x86_64) `_ * `Linux(AArch64) `_ * `MacOS(x86_64) `_ * `MacOS(Apple silicon) `_ #. 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: * `STM32CubeF0 `_ * `STM32CubeF1 `_ * `STM32CubeF2 `_ * `STM32CubeF3 `_ * `STM32CubeF4 `_ * `STM32CubeF7 `_ * `STM32CubeH7 `_ * `STM32CubeL0 `_ * `STM32CubeL1 `_ * `STM32CubeL4 `_ * `STM32CubeL5 `_ * `STM32CubeG0 `_ * `STM32CubeG4 `_ * `STM32CubeWL `_ * `STM32CubeWB `_ * `STM32CubeU5 `_ * `STM32CubeMP1 `_ * 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 ^^^^^^^^^^^^^^^^^^ * `ESP32 project template `_ * nRF52 project template * RP2040 project template * `STM32 project template `_ 4. Tweak some source code ^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: c 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 """" .. code-block:: shell $ make CMake """"" .. code-block:: shell $ 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 """" .. code-block:: shell $ make flash CMake """"" .. code-block:: shell $ 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 :ref:`flash`. 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 """"""""""""""""""""""" .. code-block:: bash $ 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. ````) should be modified to suit your project. Option 1. Make """""""""""""" .. code-block:: LIBMCU_ROOT ?= /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 += $(LIBMCU_MODULES_SRCS) += $(LIBMCU_MODULES_INCS) #LIBMCU_INTERFACES := gpio pwm include $(LIBMCU_ROOT)/projects/interfaces.mk += $(LIBMCU_INTERFACES_SRCS) += $(LIBMCU_INTERFACES_INCS) Option 2. CMake """"""""""""""" .. code-block:: cmake add_subdirectory(/libmcu) or .. code-block:: cmake set(LIBMCU_ROOT /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 """""""""""""""""""""""""""" .. code-block:: cmake 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 project #. add the sources under ``$LIBMCU_ROOT/ports//.c`` to your project #. add ``$LIBMCU_ROOT/modules/[common, actor, ...]/include`` to the include paths for your project