------------------------------------------------------------------------------
README
------------------------------------------------------------------------------

This repository contains assorted example projects for libopencm3.

The libopencm3 project aims to create an open-source firmware library for
various ARM Cortex-M3 microcontrollers.

For more information visit http://libopencm3.org

The examples are meant as starting points for different subsystems on multitude
of platforms.

Feel free to add new examples and send them to us either via the mailinglist or
preferably via a github pull request.

Usage
-----

You _must_ run "make" in the top level directory first.  This builds the
library and all examples.  If you're simply hacking on a single example after
that, you can type "make clean; make" in any of the individual project
directories later.

For more verbose output, to see compiler command lines, use "make V=1"
For insanity levels of verboseness, use "make V=99"

The makefiles are generally useable for your own projects with
only minimal changes for the libopencm3 install path (See Reuse)

For flashing the 'miniblink' example (after you built libopencm3 and the
examples by typing 'make' at the top-level directory) onto the Olimex
STM32-H103 eval board (ST STM32F1 series microcontroller), you can execute:

 $ cd examples/stm32/f1/stm32-h103/miniblink
 $ make flash

The Makefiles of the examples are configured to use a certain OpenOCD
flash programmer, you might need to change some of the variables in the
Makefile if you use a different one.

You can also flash manually like this:

 $ openocd -f interface/jtagkey-tiny.cfg -f target/stm32f1x.cfg
 $ telnet localhost 4444
 > reset halt
 > flash write_image erase foobar.hex
 > reset

Replace the "jtagkey-tiny.cfg" with whatever JTAG device you are using, and/or
replace "stm32f1x.cfg" with your respective config file. Replace "foobar.hex"
with the file name of the image you want to flash.

Reuse
-----

If you want to use libopencm3 in your own project, this examples repository
shows the general way.  (If there's interest, we can make a stub template
repository)

##### Create an empty repository

    $ mkdir mycoolrobot && cd mycoolrobot && git init .

##### Add libopencm3 as a submodule

    $ git submodule add https://github.com/libopencm3/libopencm3

##### Grab a copy of the basic rules
These urls grab the latest from the libopencm3-examples repository

    $ wget \
    https://raw.githubusercontent.com/libopencm3/libopencm3-examples/master/examples/Makefile.rules \
    -O libopencm3.rules.mk

##### Grab a copy of your target Makefile
in this case, for STM32L1

    $ wget \
    https://raw.githubusercontent.com/libopencm3/libopencm3-examples/master/examples/stm32/l1/Makefile.include \
    -O libopencm3.target.mk

##### Edit paths in libopencm3.target.mk
Edit the _last_ line of libopencm3.target.mk and change the include to read
include ../libopencm3.rules.mk (the amount of .. depends on where you put your
project in the next step..

##### beg/borrow/steal an example project
For sanity's sake, use the same target as the makefile you grabbed up above)

    $ cp -a \
    somewhere/libopencm3-examples/examples/stm32/l1/stm32ldiscovery/miniblink \
    myproject

Add the path to OPENCM3_DIR, and modify the path to makefile include

```
$ diff -u
---
2014-01-24 21:10:52.687477831 +0000
+++ Makefile	2014-03-23 12:27:57.696088076 +0000
@@ -19,7 +19,8 @@
 
 BINARY = miniblink
 
+OPENCM3_DIR=../libopencm3
 LDSCRIPT = $(OPENCM3_DIR)/lib/stm32/l1/stm32l15xxb.ld
 
-include ../../Makefile.include
+include ../libopencm3.target.mk
 
```

You're done :)

You need to run "make" inside the libopencm3 directory once to build the
library, then you can just run make/make clean in your project directory as
often as you like.