Getting started with mikroe Clicker 2 for STM32 with ChibiOS

About

Introducing Clicker 2 for STM32

The Clicker 2 for STM32 is a compact development kit by mikroe (also known as MikroElektronika). This board is equipped with 2 mikroBUS socket that allow to connect the Click Boards. These boards, designed by mikroe, are small add-ons that allow to easily connect most common devices to your MCU. Indeed, in the last years mikroe has produced a lot of Click Boards (more than one hundred) with an extended documentation and with code examples.

Our purpose

During the Maker Faire Rome 2015, we meet some mikroe employee and we have explained them the purposes of PLAY Embedded. Some weeks later they graciously sent us a Click Pack and the board and we have decided to propose some articles on this development kit as it seems an interesting and very useful hardware. Since, mikroe provides a lot of information about this board and its uses, we have decided to provide another point of view of this product: we will se how to port ChibiOS on this board providing some tutorials about every Click board we will have at our disposal.

Hardware description

The Clicker 2 for STM32 is equipped with the same MCU of the STM32F407 Discovery: the STM32F407VGT6. This MCU is an ARM 32-bit Cortex-M4 CPU having a 168 MHz clock frequency, 1MB of Flash Memory and 192kB of SRAM.

The board is equipped also with

1. A LTC3568, a high efficiency USB Power Manager which is able to manage a Li-Ion battery (indeed there is a battery connector);
2. A USB mini-B connector;
3. Two already mentioned mikroBUS socket;
4. Two user push buttons, two user LEDs, a reset button and a power switch;
5. A 25MHz Crystal Oscillator and a 32,768KHz Ceramic Oscillator.

The mikroBUS socket

Every mikroBUS socket is actually represented by 2 line of 8 pin header connector. These 16 pins include an Analog input, a pin for reset purpose, a SPI (4 wires), a PWM, an interrupt source, a USART (2 wires), an I2C (2 wires), a 3.3V and a 5V power supply lines and 2 GND PINs.

Obviously, not every PIN is actually connected on the Clicker Board, but this BUS offers a general purpose interface for every kind of peripheral and seems to be a valid alternative to the well known Arduino Uno Connector.

Before starting

Requirements

Since our purpose for this new serie of tutorials is to use Clicker 2 for STM32 and Click Board with ChibiOS, it is required a basic knowledge of this product. For our most faithful users this is not a big deal. Anyway, we highly suggest at least a reading of the ChibiOS tutorials. In what follows, we will suppose that ChibiStudio is already installed and that user knows well how to deal with it.

Documentation

To work with Clicker 2 for STM32 we need at least of these documents. While the STM32F4 Reference Manual and the STM32F407VGT6 Datasheet are related to the MCU, the Clicker 2 For STM32 User Manual contains information about the board, even its schematics. Additionally we have included the LTC3568 Datasheet.

STM32F4 Reference Manual STM32F407VGT6 Datasheet Clicker 2 For STM32 User Manual LTC3568 Datasheet

Bootloader

The Clicker 2 for STM32 comes with a bootloader named mikroBootloader. This software is a firmware already flashed on the STM32F407’s Flash Memory which provides an interface through the USB enabling the user to upload a .hex firmware on the same Flash Memory. Obviously, the user firmware must be organized in a way to not overlap the memory area containing the bootloader.

The interface is managed on the PC-side through an application that is named USB HID Bootloader. It allows the connection to the target and the upload of the user firmware into the Flash Memory. If the application recognizes that the user firmware could impact over the mikroBootloader the operation is skipped. After the upload of a new firmware the target is reset, the mikroBootloader starts and waits some seconds for a USB connection. If the connection doesn’t occur the bootloader loads the user firmware.

Bootloader vs On-Chip debugger

Instead of the mikroBootloader we could use an external programmer like that proposed by mikroe which is named mikroProg for STM32 or like the one proposed by STMicroelectronics, the well known ST-Link v2, to completely remove the mikroBootloader and perform debugging using a software like OpenOCD.

Using a debugger, we can perform all that operation usually performed in the ChibiStudio‘s perspective Debug (Step by Step execution, exploration of registers value, use of the ChibiOS Debug View and so on). Anyway, sometime a Debugger could be unavailable or too much expensive for certain purposes. For that reason, in this tutorial we have decided to use the resident mikroBootloader. We will provide later a tutorial about how to connect a debugger to this board using the already existing JTAG Connector of the Clicker 2 for STM32.

Downloading the USB-HID Booatloader

The USB HID Bootloader could be downloaded from the Clicker 2 Official Page. Anyway, we are reporting the direct download link below:

USB HID Bootloader

By the end of this tutorial we will use this application to flash a firmware compiled in ChibiStudio.

Generating board files

The on-board MCU is widely supported by ChibiOS but we need to create some custom board files to use it. We already talked about
port a ChibiOS based application to another platform. Indeed, a good starting point is to duplicate the default project related to the STM32F4 Discovery and create custom board files using the .chcfg (that is actually a simple XML).

Unlike what we have seen in the video above, we should copy the “board” folder under the main project tree in order to avoid edits to the main ChibiOS folder and issues (expecially when we are moving to newer version of ChibiOS). For that reason, usually our edits are confined to the project folder.

Using the XML we need to configure the HSE (High Speed External) and LSE (Low Speed External) clock value and a minimal set of PINs. On this board we have both a HSE clock oscillator (a Crystal Oscillator at 25MHz) and a LSE clock oscillator (a Ceramic Oscillator at 32,768kHz). Reading the RCC (i.e. Reset and Clock Configuration) section in the STM32F4 Reference Manual, we can understand that in this case HSE Bypass mode and LSE Bypass mode must be both disabled (setting the related value to FALSE in the XML file).

All the needed informations are available cross reading the Board Schematic (that is into the Board User Manual) and GPIO and RCC chapter over the STM32F4 Reference Manual. We will avoid to list all the configurations chosen for each PIN suggesting to whom is interested to take a look at the XML included in the attached demo project. By the way, we have configured PINs related to the USB, SWD, Push-buttons, LEDs and the 2 mikroBUS socket. Note that to configure PINs is required a deep knowledge of the STM32 GPIO and these informations could be found on the STM32F4 Reference Manual. Some additional info could be found into our previous article Hello ChibiOS.

Note that once we have generated the board files we need to edit board.mk. This beacause we have placed the board files directly under the project folder. The file board.mk will sound like this:

# List of all the board related files.
BOARDSRC = ./board/board.c
# Required include directories
BOARDINC = ./board

We need also to edit the makefile to make it pointing to our just edited board.mk:

# Imported source files and paths
CHIBIOS = ../../chibios3
# Startup files.
include $(CHIBIOS)/os/common/ports/ARMCMx/compilers/GCC/mk/startup_stm32f4xx.mk
# HAL-OSAL files (optional).
include $(CHIBIOS)/os/hal/hal.mk
include $(CHIBIOS)/os/hal/ports/STM32/STM32F4xx/platform.mk
include ./board/board.mk
include $(CHIBIOS)/os/hal/osal/rt/osal.mk
# RTOS files (optional).
include $(CHIBIOS)/os/rt/rt.mk
include $(CHIBIOS)/os/rt/ports/ARMCMx/compilers/GCC/mk/port_v7m.mk
# Other files (optional).
include $(CHIBIOS)/test/rt/test.mk

Configuring the clock tree

The STM32F4 has a complex clock tree well described in the STM32F4 Reference Manual. ChibiOS initializes the whole clock tree at start up and all the configurations required to perform this operation are stored into the mcuconf.h. Note that, in board files we have already stored the value of HSE and LSE.

On STM32F4 we can choose three different sources as SYSCLK (i.e. the System Clock):

1. The HSI clock, an internal 16 MHz RC clock;
2. The HSE clock, an external Crystal/Resonator Oscillator or an External Clock Source up to 25 Mhz,
3. The Main PLL clock, with a configurable clock frequency multiplier.

The PLL is actually the only way to reach the maximum SYSCLK frequency available for this board (i.e. 168 MHz). It can receive as input the HSE clock as well as the HSI clock. The SYSCLK frequency is the result of these equations that we can found into the STM32F4 Reference Manual under the RCC section:

If we want to reach a clock frequency value of 168 MHz, since the P value must be at least 2 and selecting the 25 MHz HSE clock as PLL source, a good choice for M value could be 25 and N value could be 336. As said, all these configurations are selectable in the file mcuconf.h.

#define STM32_SW                            STM32_SW_PLL
#define STM32_PLLSRC                        STM32_PLLSRC_HSE
#define STM32_PLLM_VALUE                    25
#define STM32_PLLN_VALUE                    336
#define STM32_PLLP_VALUE                    2
#define STM32_PLLQ_VALUE                    7

This is the last step required to create a new working project for our board.

A simple demo

In our demo we will use the chprintf() already used in the tutorial Hello ChibiOS. This time, we will use theSerial Over USB Driver as BaseSequentialStream instead of the Serial Driver. This requires the configuration of the USB Driver and two files (usbcfg.h e usbcfg.c) from the USB-CDC official demo.

Our demo has two threads: the first one makes the 2 LEDs blinking, the other one reads the button status and prints it using the Serial Over USB driver:

#include "ch.h"
#include "hal.h"
#include "chprintf.h"
#include "usbcfg.h"
/*
 * Enable if your terminal supports ANSI ESCAPE CODE
 */
#define ANSI_ESCAPE_CODE_ALLOWED                     TRUE
static BaseSequentialStream * chp = (BaseSequentialStream*) &SDU1;
/*
 * This is a periodic thread that does absolutely nothing except flashing
 * a LED.
 */
static THD_WORKING_AREA(waThread1, 128);
static THD_FUNCTION(Thread1, arg) {
  (void)arg;
  chRegSetThreadName("blinker");
  while (true) {
    palTogglePad(GPIOE, GPIOE_LED1);
    chThdSleepMilliseconds(250);
    palTogglePad(GPIOE, GPIOE_LED2);
    chThdSleepMilliseconds(250);
  }
}
/*
 * Application entry point.
 */
int main(void) {
  /*
   * System initializations.
   * - HAL initialization, this also initializes the configured device drivers
   *   and performs the board-specific initializations.
   * - Kernel initialization, the main() function becomes a thread and the
   *   RTOS is active.
   */
  halInit();
  chSysInit();
  /*
   * Initializes a serial-over-USB CDC driver.
   */
  sduObjectInit(&SDU1);
  sduStart(&SDU1, &serusbcfg);
  /*
   * Activates the USB driver and then the USB bus pull-up on D+.
   * Note, a delay is inserted in order to not have to disconnect the cable
   * after a reset.
   */
  usbDisconnectBus(serusbcfg.usbp);
  chThdSleepMilliseconds(1500);
  usbStart(serusbcfg.usbp, &usbcfg);
  usbConnectBus(serusbcfg.usbp);
  chThdSleepMilliseconds(2000);
  /*
   * Creates the example thread.
   */
  chThdCreateStatic(waThread1, sizeof(waThread1), NORMALPRIO, Thread1, NULL);
  /*
   * Normal main() thread activity, in this demo it does nothing except
   * sleeping in a loop and check the button state.
   */
  while (TRUE) {
    if(palReadPad(GPIOA, GPIOA_BUTTON2) == PAL_LOW){
      chprintf(chp, "Button 2 is pressed");
    }
    if(palReadPad(GPIOE, GPIOE_BUTTON1) == PAL_LOW){
      chprintf(chp, "Button 1 is pressed");
    }
    if((palReadPad(GPIOA, GPIOA_BUTTON2) == PAL_HIGH) &&
       (palReadPad(GPIOE, GPIOE_BUTTON1) == PAL_HIGH)){
      chprintf(chp, "Buttons are both released");
    }
    chThdSleepMilliseconds(150);
#if ANSI_ESCAPE_CODE_ALLOWED
    chprintf(chp, "\033[2J\033[1;1H");
#endif
  }
}

Using the mikroe USB HID Bootloader

When we build a project in ChibiStudio, Eclipse creates a sub-folder named build into the folder project. In this sub

folder we can find our firmware with different extensions and we will use ch.hex with the USB HID Bootloader.

Indeed, the USB HID Bootloader is a simple GUI (see Fig. 4) that uploads a .hex file on the MCU Flash Memory. There isn’t any more to say about this GUI since the procedure to upload the firmware is a enumerated step by step guided procedure created by mikroe to be as simple as possible.

The operations are simple:connect the Clicker 2 using the USB, press the button “Connect”, select the path of the firmware ch.hex and upload it. The target will be automatically reset when the procedure will finish. Remember that this procedure is the easiest to use and the cheapest to implement, but since we aren’t using any Debugger, we are losing the capability to perform debug operations on our code.

Project used in this tutorial

RT-STM32F407-MIKROE-CLICKER2