Homebrew Hue-compatible smart lighting that won't cost you a fortune: a hardware-centered tutorial.

4

The most detailed guide on programming and debugging BluePill under Linux with IDE


Riding on the coattails of recent Bluepill craze, I already wrote up an article about programming this board with Platformio IDE (Arduino framework included!).

In case you didn't know, Bluepill is a generic name for tiny boards with ARM processor (STM32F103C8T6 -> specs on STMicroelectronics website) that are Arduino-compatible and often marketed as yet another Arduino-killer (sigh...).

Here's your run-of-the-mill bluepill.

This hype train just doesn't seem to stop just yet, so I decided to produce one more useful Bluepill tutorial.

If you're looking for a cheap alternative to Arduino boards (with a price tag of just about $2), take a look at blog post above. The rest of you who just think this is a neat new board that can be used to learn real microcontroller programming - read on!
When it comes to real work, Arduino IDE often simply lacks horsepower. It's simple and favored by many because of the great power of high-level hardware abstraction that Arduino API offers, but the same abstraction means that you're just limited by API's capabilities and its programming model.

(in prof. Farnsworth voice) Good news, everyone! You can program Bluepill just as easily in C, with access to interrupts, registers etc. This is mainly done with mighty IDEs such as Keil. It offers tight integration with all STM32 microchips. Debugging, programming, you name it - all this can be configured in a couple of clicks here.

Unfortunately, you'll have to pay big bucks to use it, and it only works in Windows. As a Linux user, I couldn't help wondering - can I have something as good in Linux? Turns out you can, and it's not much harder than installing an IDE. Here goes:

Prerequisites

You'll need the same bluepill + stlink adapter combo from my previous article. And a Linux machine, obviously, preferably 64 bit (only older versions of IDE are available for x86 architecture). My example is based upon Arch Linux.
Software-wise, you're going to need cross-crompiler and some minor stuff too:
?
1
[anon@anon-pc ~]$ yaourt -Sy gksu arm-none-eabi-gdb openocd stlink
Restart your PC so that udev rules for STLink programmer take effect.

Installing OpenSTM32 Workbench

  1. You'll have to register on OpenSTM32 website to download it (or you could avoid registering), but you can use it completely for free afterwards. 
  2. Download the latest version of IDE here. 
  3. Launch the installer. It pretty much looks like an ordinary Windows installer:
    ?
    1
    2
    [anon@anon-pc Downloads]$ chmod +x ./install_sw4stm32_linux_64bits-v2.2.run
    [anon@anon-pc Downloads]$ ./install_sw4stm32_linux_64bits-v2.2.run

    You may uncheck STLink Server.

    The least favorite part is waiting...

Debugging and programming with Blink example

Start eclipse executable (located in ~/Ac6/SystemWorkbench/ by default) and you'll be greeted by an old familiar Eclipse. What's next? Well, set up a project that can compile firmware for our target STM32F103 microcontroller, upload and debug it. That's where you'll see the difference between plain Eclipse and this one.
  1. Create a new C project
  2. Pick Executable  -> Empty project in Project type tree, and Ac6 STM32 MCU GCC toolchain. Enter your project's name.
  3. Leave Debug and Release configurations checked.
  4. In the next window, switch to Mcu tab, then pick your target. For Bluepill, it's going to be STM32F103C8Tx from STM32F1 series.
  5. After clicking Next you may pick any additional development libraries provided by STMicro. You can pick No firmware option (aka CMSIS) - then you'll have to manually manipulate your MCU's registers to make it work. In case you want something more high-level, there's the choice between StdPeriph library (older, less bugs, quite low-level) and CubeHAL (newer, used to be a lot of bugs but that's probably not true anymore. High-level). If in doubt, there's lots of reading material about these libraries online.
  6. That's it! Click finish and your project can be built. No feat, that, considering it's empty for now. Let's add some blinky code to /src/main.c:
    ?
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    #include "stm32f10x.h"
     
    #define DELAY 100000
     
    void simple_delay(uint32_t us)
    {
     while (us--) {
      asm volatile ("nop");
     }
    }
     
    int main(void)
     
    {
     
     /* reset rcc */
     RCC_DeInit();
     
     /* enable clock to GPIOC */
     RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOC, ENABLE);
     
     GPIO_InitTypeDef gpioInitStruct;
     GPIO_StructInit(&gpioInitStruct);
     gpioInitStruct.GPIO_Pin  = GPIO_Pin_13;
     gpioInitStruct.GPIO_Mode = GPIO_Mode_Out_PP;
     gpioInitStruct.GPIO_Speed = GPIO_Speed_2MHz;
     GPIO_Init(GPIOC, &gpioInitStruct);
     
     for (;;) {
      GPIO_WriteBit(GPIOC, GPIO_Pin_13, 1);
      simple_delay(DELAY);
      GPIO_WriteBit(GPIOC, GPIO_Pin_13, 0);
      simple_delay(DELAY);
     }
     
     return 0;
    }
    If everything's ok, your project is supposed to build without errors.
Our code builds now, but how to upload it to target? That's no linear process for bluepill, but once you do it, you'll be able to upload and debug your code in one click! At this point, you have to connect Bluepill to your computer with STLink programmer. The connection diagram is the same as in my previous post.

Here's how you set up OpenSTM32:
  1. In your workspace, create a file named bluepill_debug.cfg with following contents:
    ?
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    source [find interface/stlink-v2.cfg]
     
    set WORKAREASIZE 0x5000
     
    transport select "hla_swd"
     
    set CHIPNAME STM32F103C8Tx
     
    # Enable debug when in low power modes
    set ENABLE_LOW_POWER 1
     
    # Stop Watchdog counters when halt
    set STOP_WATCHDOG 1
     
    # STlink Debug clock frequency
    set CLOCK_FREQ 4000
     
    # We do not connect RESET line to stlink, that's why reset is disabled.
    reset_config none
     
    source [find target/stm32f1x.cfg]
  2. Open Debug configurations window:
    Create a new Ac6 STM32 Debugging configuration:
  3. Switch to Debugger tab. That's where magic starts. First unintuitive thing about OpenSTM32 Workbench is the fact that GDB and OpenOCD executables that come bundled with it don't mix well with your system's libraries. If you don't replace bundled executables, you're going to see "Could not determine GDB version using command" error:
    That's why we need to replace ${openstm32_compiler_path}/arm-none-eabi-gdb and "${openstm32_openocd_path}/openocd" with /usr/bin/arm-none-eabi-gdb and /usr/bin/openocd respectively. The automatically-generated configuration script is no good either - it doesn't take into account the lack of RST line. That's why you should pick your script from Step 1.
  4. Click Apply and then Debug. Here's what happens next: if your bluepill is connected to PC through STLink programmer, IDE will switch to Debugging perspective, upload your code and stop it at the first line. You're free to define breakpoints, step through lines one at a time, or just press F8 and behold the LED blink fast.
The same configuration can be used from Run button - acting as the equivalent of Upload button. If everything worked, you're all set to develop full-blown programs for your favorite inexpensive ARM board.

Troubleshooting

Now, let's move on to special cases.

1) In older versions of IDE this configuration skipped "Launch OpenOCD" part, which resulted in errors like "Remote debugging using localhost:3333 Remote connection closed" when trying to run GDB. I found that manually running OpenOCD as an external tool prior to debugging or uploading does the trick. And here's how:
  • Go to External Tools configuration.
  • Enter the following details:
    Location -> /usr/bin/openocd
    Working directory -> /usr/bin
    Arguments -> -f /usr/share/openocd/scripts/interface/stlink-v2.cfg -f /usr/share/openocd/scripts/target/stm32f1x.cfg
  • Click Apply. Run this tool once before each uploading-debugging session. 
2)  Sometimes STM32 chips come erase-protected from the factory (why though?). Symptoms are as follows - you can easily connect to your board via openocd like so:

openocd -f /usr/share/openocd/scripts/interface/stlink-v2.cfg -f /usr/share/openocd/scripts/target/stm32f1x.cfg

... but any firmware upload operation will fail with messages like

Got NACK from device on command 0x43
Can't initiate chip erase!
Failed to erase memory.

The solution is to issue the unlock command after connecting to Bluepill with OpenOCD:
Step-by-step guide:

  1. Connect St-LinkV2 programmer to PC.
  2. You should have OpenOCD installed. Open up 2 terminal windows.
  3. Open up an OpenOCD connection to microcontroller in the first window:
    ?
    Double click on code to select all
    1
    openocd -f /usr/share/openocd/scripts/interface/stlink-v2.cfg -f /usr/share/openocd/scripts/target/stm32f1x.cfg
  4. In the second window, connect to telnet session that OpenOCD created for the connection to microcontroller.
    ?
    Double click on code to select all
    1
    telnet localhost 4444
  5. Issue these commands in that same window now:
    reset halt
stm32f1x lock 0
reset halt
exit
Adding some instructions in a picture to complement the description (screenshot was taken on OSX, but same applies to Linux. OpenOCD installed via brew):

Comments

Post a Comment