Skip to content

Step by Step Porting Guide for Murasaki

Jump to bottom
Seiichi "Suikan" Horie edited this page Mar 24, 2020 · 19 revisions

Let's install the Murasaki library into your Nucleo!

On this page, we explain how to install the Murasaki library to your Nucleo based project.

Nucleo 64 Nucleo 144

Contents

  1. Prerequisite
  2. Code Generation by STM32 CubeIDE
  3. Clone and install Murasaki
  4. Nucleo 64 Specific work
  5. Test the program

Prerequisite

Environment and tool

The followings are the test environment of the procedure on this page.

  1. Ubuntu 16.04 LTS / 18.04 LTS ( Windows 10 WSL is OK )
  2. STM32CubeIDE 1.3.0

Code generation by STM32 CubeIDE

We use STM32 Cube IDE to generate an application skeleton. The following are the procedure to generate.

Create a new project

At first, create a project by CubeIDE. You can search the Nucleo board name incrementally.

  1. Menu -> File -> New -> STM32 Project
  2. Select a target board

Selecting the Nucleo Board

Set project language to C++

The Murasaki library is a C++ class collection. We have to choose C++ as a project language.

  1. Select C++ as the project type.
  2. Click Finish to generate a project.
  3. The configurator automatically starts

Selecting Language

Configure the FreeRTOS

The Murasaki library utilizes the FreeRTOS. Using RTOS is not an option but essential.

  1. Open the Middleware group
  2. Click FreeRTOS
  3. Choose CMSIS_V1 as an interface.
  4. Set the memory size
    1. The min Stack Size: 256
    2. The heap size: larger than 16kB

The task stack size depends on your algorithm in the task. For the LED blinking and message output by printf, 256byte is enough.

Configuring FreeRTOS

Configure the CPU cache (CORTEX-M7 only)

CORTEX-M7 core has several mechanisms to accelerate memory access. This configuration is required only for Cortex-M7. And sometimes it's different between the CORTEX-M7 based microprocessor.

  1. Open System Core.
  2. Click Cortex-M7.
  3. Open Cortex Interface Settings.
  4. Enable all features.

Configuring caches

Configure the Timebase

The default time base of the STM32 Cube HAL is SYSTICK. But the SYSTICK timer is used by FreeRTOS. To avoid trouble, we have to change the timer for the time base.

  1. Open System Core.
  2. Click SYS.
  3. Choose TIMxx as Timebase Source.
    1. You may want to use the largest xx (ex: TIM14).
    2. FreeRTOS occupy SYSTICK. This time base for HAL should not be SYSTICK.

Configuring Timebase

Configure the UART DMA

The UART class of the Murasaki library uses DMA. Thus, Configuring the DMA is essential. The different class has their own DMA usage. See the API documentation of the Murasaki.

  1. Click UART3 ( UART2 for Nucleo 64)
  2. Select DMA Settings
  3. Add DMA and set it as TX
  4. Add DMA and set it as RX

UART DMA

Configure the UART interrupt

The UART class of the Murasaki library uses interrupt. Thus, enabling the interrupt is essential.

  1. Select NVIC Settings
  2. Check UARTx Global interrupt

UART interrupt

Configure the Clock ( F722 only )

The Firmware for Nucleo F722 has a bug on the clock configuration. We have to fix it before generating code.

  1. Select Clock configuration
  2. Change Input Frequency to 8Mhz
  3. Change HCLK to 216MHz

Configure the F722 clock

Generate the code

  1. Click the gear icon to generate. Generate the code

Build for sure

Once the code is generated, you can build it. Build it for sure.

  1. Click the project.
  2. Ctrl-B to build Test build

Clone and install Murasaki

In this section, we clone the Murasaki repository.

copy the Murasaki repository address

First, open the Murasaki project and get the project repository address. Note that we recommend you get the URL of the HTTPS protocol.

  1. open Murasaki project in the GitHub
  2. Click Clone or download
  3. Copy the URL
https://github.com/suikan4github/murasaki

Address to copy

Clone the Murasaki repository

  1. Open the shell window
  2. Go to the project directory
  3. Run following command :
git clone URL-of-the-repository

If you are using Windows 10 command line, run following command (Assuming the Ubuntu 16.04 or 18.04 is installed on the WSL) :

wsl git clone URL-of-the-repository

Clone the repository

Install Murasaki to the project

The installer copies the template of the code to the appropriate directory, and then, insert the hook in the existing code to allow to run the Murasaki application.

  1. Run the following command
cd murasaki
./install

If you are using Windows 10 command line, run following command (Assuming the Ubuntu 16.04 or 18.04 is installed on the WSL) :

cd murasaki
wsl ./install

Refresh the project

The installation is done in the command-line shell, to reflect the result, we have to refresh the IDE.

  1. Go back to the CubeIDE
  2. Click the project
  3. Type F5 to refresh.
  4. The Murasaki directory appears.

Refreshing project

Add an include path

We have to add the include directory to the project property because the Murasaki include directory is not in the existing include path, by default.

  1. Open the Project Properties
  2. C/C++ General -> Paths and Symbols -> Includes -> GNU C++
  3. Click Add button
  4. Add "murasaki/Inc"

Include path

Add a source path

Same as the include path, we have to add a source path.

  1. In the Paths and Symbols.
  2. Click the Source Location tab.
  3. Click Add Folder... button.
  4. Choose murasaki/Src.
  5. Click OK Source path

Let's build

  1. Close Project Properties.
  2. Type F5 to build.
  3. Build without problem (Except Nucleo 64) Building

Nucleo 64 Specific work

Nucleo 64 series are using different UART and LED port compared to the Nucleo 144.

Comparison

Nucleo 144

  1. UART3 for USB serial.
  2. LD2 for status.

Nucleo 64

  1. UART2/3 for USB serial
  2. LD2/3/4 for status.

Fix the UART ( Nucleo 64 only)

  1. Check the appropriate UART number by Nucleo Document.
  2. Confirm the device handle name ( huart# ) in main.c.
  3. Open Src/murasaki_platform.cpp.
  4. Substitute all UART3 with the console UART.

Fixing UART

Fix the LD ( Nucleo 64 only)

  1. In Src/murasaki_platform.cpp.
  2. Substitute all LD2 with LD3 ( or LD4 ).

Fix the LD file

Let's build again (Nucleo 64 only)

  1. Save the file.
  2. Choose the project.
  3. Type F5 to build.
  4. Build without problem (Except Nucleo 64)

Building

Test the program

Invoke the debugger

  1. Choose the project
  2. Debug As STM32 MCU C/C++ Application Invoking debugger

Confirm the Debug Configuration

  1. Just confirmation,
  2. Nothing to do.

Debug configuration

Run the debugger

  1. Wait a second until the Debugger becomes ready.
  2. Then, click the Run button.
  3. You must see the LD blinks
    1. LD2: Nucleo 144
    2. LD2, 3 or 4: Nucleo 64

Run

Murasaki Project

Clone this wiki locally