libmaple/README

                   _ _ _                           _
                  | (_) |__  _ __ ___   __ _ _ __ | | ___
                  | | | '_ \| '_ ` _ \ / _` | '_ \| |/ _ \
                  | | | |_) | | | | | | (_| | |_) | |  __/
                  |_|_|_.__/|_| |_| |_|\__,_| .__/|_|\___|
                                            |_|               by LeafLabs!
                                                              leaflabs.com


The latest version of this repository can be found here:

    https://github.com/leaflabs/libmaple

IMPORTANT: read HACKING _before_ submitting patches.

General information
------------------------------------------------------------------------------

libmaple is a library for programming ST's STM32 line of Cortex M3
microcontrollers.  It has a pure C layer, libmaple proper, which does
most of the work, and a C++ layer, Wirish, which provides high-level
convenience functions and a Wiring/Arduino-compatible interface.

libmaple is designed for portability, and currently runs on a variety
of STM32F1 performance and value line MCUs, with experimental support
for STM32F2 MCUs.

Using libmaple
------------------------------------------------------------------------------

The easiest way to use libmaple is in concert with the Maple IDE.
Maple IDE, a sister project from LeafLabs, is an Arduino IDE fork
usable for programming Maple boards, which includes libmaple and a
compilation and upload toolchain:

    http://leaflabs.com/docs/maple-ide-install.html

Additionally, a HOWTO on setting up this library for use from the
command line in a Unix environment is available here:

    http://leaflabs.com/docs/unix-toolchain.html

Documentation, Etc.
------------------------------------------------------------------------------

HTML documentation for the latest release of libmaple/Maple IDE is
available here:

    http://leaflabs.com/docs/

libmaple is well documented via Doxygen comments.  The HTML
documentation referenced above (which also includes the Doxygen
output) is automatically generated from the source files in the
leaflabs-docs repository.  In order to obtain the leaflabs-docs
repository, visit:

    http://github.com/leaflabs/leaflabs-docs/

Repository Layout
------------------------------------------------------------------------------

/build/

    Compiler output

/contrib/

    Community-contributed resources.  LeafLabs doesn't maintain the
    contents of this directory, so it may get stale.

/examples/

    Example code and test programs. Copy these to /main.cpp to compile them.

/libmaple/

    This is the meat of the library.  C only, no C++.  The
    Arduino-like compatibility layer (in C++) is in /wirish/.

/libraries/

    Special-purpose libraries that don't merit inclusion in the
    /libmaple/ and /wirish/ directories, which are intended for
    general use.  Arduino-compatible libraries go here.

/LICENSE

    Licensing and copyright information.

/main.cpp.example

    main.cpp is required for a successful build but is non-existent by
    default; use this file as a template for building your program. By
    default, just blinks an LED.

/Makefile

    libmaple build instructions for GNU Make. (This is supplemented by
    build-targets.mk, the rules.mk files throughout the tree, and the
    files in support/make/).

/notes/

    Unstructured text notes that may be useful.

/README

    This file ;).

/support/

    Support files and scripts for various purposes.

    gdb/              GDB scripts.
    ld/               Linker scripts.
    make/             Additional files used by the top-level Makefile.
    scripts/          Miscellany.
    doxygen/          Doxygen configuration.
    stm32loader.py    Upload script for the STM32's built-in USART bootloader.

/wirish/

    Extra wrappers and functionality around the lower level code in
    /libmaple/. These files implement an Arduino "Wiring"-like
    library.