Firstly, welcome to STM32PLUS, the C++ library that eases the burden of programming the STM32F103 and STM32F4 devices.

The main introduction and getting started guide can be found at my website, http://www.andybrown.me.uk.

Before you can use the library you need to build it because, although much of the library is provided 'header-only' there is a substantial amount of compiled code that you must link to.

Please see the INSTALL.txt file for detailed compilation instructions.

In the 'examples' subdirectory you will find dozens of examples nearly all of which will work without modification on the F1 and F4 devices. The examples are heavily commented to help you understand what's going on.

The examples are designed to work on the F1 devices at 72MHz with an 8MHz HSE and on the F4 at 168MHz with either an 8MHz or a 25MHz HSE. If your board has a different oscillator or core clock speed then you may need to adjust 'System.c' in the 'system' subdirectory of the example that you are looking at.

HTML documentation can be found in the doc/html subdirectory. This documentation is auto-generated by the 'doxygen' tool from the comments in the source code.

I freely admit that the documentation lags in both quantity and quality behind the code itself and it's a future task for me to improve it. In the meantime I hope that the heavily commented examples are enough to get you started.

If you think that you've found a bug then please enter a bug report at http://www.andybrown.me.uk/bugs. It really helps if you can give me enough information to reproduce the bug myself.

Yes you can. Visit the 'downloads' page at my website for a binary package that covers all possible MCU combinations. Note that this binary package is compiled for an 8MHz external oscillator (HSE).

/CHANGELOG.txt

The change log. In here I'll detail the changes made in each release. 2.0.0 is an exception because so much has changed that it gets a write-up on my website instead.

/INSTALL.txt

The installation guide. This file explains how to build the library. If you read nothing else, read this!

/SConstruct

The top level scons build file, broadly equivalent to a Makefile for those that have not used scons before.

/VERSION.txt

Contains the date and time of the build that made this release.

stm32plus/

The root directory containing the library source code.

stm32plus/include

The include files for the library. This directory and the parent stm32plus directory must be on the include path of any programs that you write. As of 2.0.0 the only include files that you need to know about are those in the 'config' subdirectory. It should only ever be necessary to include 'config/stm32plus.h' and one each for the peripherals that you want to use, for example 'config/usart.h' or 'config/spi.h'. These high level files take care of including everything else that they need.

stm32plus/doc

The auto-generated HTML documentation. As noted above this documentation is an area slated for improvement in the future.

stm32plus/src

The C++ source files that make up the library. Everything in here is considered internal.

stm32plus/fwlib

Source code to the ST Microelectronics standard peripheral libraries for the F1 and F4 processors.

examples/

The examples that demonstrate the features of the library. There is one subdirectory for each example. All the examples follow the same general format. There is the main example source code and a 'system' subdirectory. The 'system' subdirectory is the same for every example and contains the startup and initialisation code required for the F1 and F4 MCU. The SConscript file takes care of selecting the appropriate code for your target MCU. To build modified example, run scons again from the root directory. scons is smart enough to only build changed files and their dependents. When I develop the examples in Eclipse I have a build configuration for each MCU, e.g. "Debug_F1" and "Debug_F4" and I use the "Resource Configurations -> Exclude from build" option to exclude the system files for the other MCU.

utils/bm2rgbi

This PC utility is for converting graphics files (jpeg, png, gif etc.) into an internal format suitable for efficient transfer to a TFT. It also supports compression using the LZG format that results in files roughly the same size as a PNG. You'll need this utility if you decide to use the bitmap functions in the graphics library.

utils/FontConv

This PC utility is for converting TrueType bitmap fonts such as those you can download for free from www.dafont.com into font files suitable for compiling and using with the stm32plus text output graphics library functions.

utils/LzgFontConv

This PC utility is for converting TrueType vector anti-aliased fonts into compressed graphical representations suitable for compiling and using with the stm32plus bitmap text output graphics library functions.

A QUICK GUIDE TO FLASHING USING OPENOCD

At the time of writing the lastest version of openocd is 0.6.1 and it contains full support for the STM32 connected via JTAG and also via ST-Link (e.g. the STM32F4DISCOVERY board). The following guide assumes that you are using either Linux or Windows with a Unix-like shell (cygwin or mingw) and that you have built the binaries.

FLASHING THE STM32F4DISCOVERY BOARD

'cd' into the openocd directory and run it with the flags required for the discovery board. For me on Windows 7 x64/cygwin this is:

$ bin-x64/openocd-x64-0.6.1.exe -f scripts/board/stm32f4discovery.cfg
Open On-Chip Debugger 0.6.1 (2012-10-07-10:39)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.sourceforge.net/doc/doxygen/bugs.html
adapter speed: 1000 kHz
srst_only separate srst_nogate srst_open_drain
Info : clock speed 1000 kHz
libusbx: info [cache_config_descriptors] could not access
configuration descriptor (dummy) for
'\\.\USB#VID_0424&PID_2504#6&247B17EE&0&1':
[31] A device attached to the system is not functioning.
libusbx: info [cache_config_descriptors] could not access
configuration
descriptor (dummy) for
'\\.\USB#VID_1A40&PID_0101#5&476FB6F&0&4':
[31] A device attached to the system is not functioning.
Info : stm32f4x.cpu: hardware has 6 breakpoints, 4 watchpoints

openocd is now up and running waiting for you to do something. Don't worry about the libusb 'errors', they are harmless.

Now telnet to openocd and flash your hex image:

$ telnet localhost 4444
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Open On-Chip Debugger

Reset the device and halt it:

> reset init
target state: halted
target halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x08000b9c msp: 0x20020000

Flash your hex image:

> flash write_image erase p:/button.hex
auto erase enabled
target state: halted
target halted due to breakpoint, current mode: Thread 
xPSR: 0x61000000 pc: 0x20000042 msp: 0x20020000
wrote 16384 bytes from file p:/button.hex in 1.147065s (13.949 KiB/s)

Reset the device to run the program:

> reset

FLASHING AN F1 BOARD USING JTAG

The procedure is much the same as the F4. We will start openocd and then use a telnet connection to flash the image. First start openocd. I can't give you the exact startup command for openocd because it will vary according to the JTAG dongle that you have purchased. I use the Olimex ARM-USB-TINY-H device that has an OpenOCD configuration file dedicated to it. Here's what openocd reports when I start it up:

Open On-Chip Debugger 0.5.0-dev-00852-gf9feeac-dirty (2011-07-27-21:58)
Licensed under GNU GPL v2
For bug reports, read
   http://openocd.berlios.de/doc/doxygen/bugs.html
Info : only one transport option; autoselect 'jtag'
1000 kHz
adapter_nsrst_delay: 100
jtag_ntrst_delay: 100
cortex_m3 reset_config sysresetreq
Info : device: 6 "2232H"
Info : deviceID: 364511274
Info : SerialNumber: OLTMERU�A
Info : Description: Olimex OpenOCD JTAG ARM-USB-TINY-H A
Info : max TCK change to: 30000 kHz 
Info : clock speed 1000 kHz
Info : JTAG tap: stm32.cpu tap/device found: 0x3ba00477 (mfg: 0x23b, part: 0xba00, ver: 0x3)
Info : JTAG tap: stm32.bs tap/device found: 0x06414041 (mfg: 0x020, part: 0x6414, ver: 0x0)
Info : stm32.cpu: hardware has 6 breakpoints, 4 watchpoints

Now we can telnet to openocd:

$ telnet localhost 4444
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Open On-Chip Debugger

And now we can reset the device

> reset init
JTAG tap: stm32.cpu tap/device found: 0x3ba00477 (mfg: 0x23b, part: 0xba00, ver: 0x3)
JTAG tap: stm32.bs tap/device found: 0x06414041 (mfg: 0x020, part: 0x6414, ver: 0x0)
target state: halted
target halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x08000a84 msp: 0x2000fffc

Flash the program hex image to the board:

> flash write_image erase /tmp/pframe.hex
auto erase enabled
device id = 0x10036414
flash size = 512kbytes
Padding image section 0 with 4 bytes

Reset the MCU to start the program:

> reset
JTAG tap: stm32.cpu tap/device found: 0x3ba00477 (mfg: 0x23b, part: 0xba00, ver: 0x3)
JTAG tap: stm32.bs tap/device found: 0x06414041 (mfg: 0x020, part: 0x6414, ver: 0x0)

That's all, I hope my experience with OpenOCD can help you get started.