aboutsummaryrefslogtreecommitdiffstats
path: root/README
blob: 3249e84796657fa78e576dfc1506f633deaf43cc (plain)
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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

         _ _ _                         _           _              
        | (_) |__  _ __ __ _ _ __ ___ | |__  _   _| |_ __ _ _ __  
        | | | '_ \| '__/ _` | '_ ` _ \| '_ \| | | | __/ _` | '_ \ 
        | | | |_) | | | (_| | | | | | | |_) | |_| | || (_| | | | |
        |_|_|_.__/|_|  \__,_|_| |_| |_|_.__/ \__,_|\__\__,_|_| |_|


The latest version of this repository can be found here:

    https://github.com/rambutan32/librambutan

IMPORTANT: read HACKING _before_ submitting patches.

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

librambutan is a fork of Leaflab's libmaple firmware libraries. As of 2015
Leaflabs is not actively maintaining libmaple and the original Maple series
hardware is End Of Life. For the foreseeable future the name 'libmaple' will
continue to be used in documentation and filenames for backwards compatability.
You can get the latest information about the Rambutan project at:

    https://forums.rambutan.cc

The original libmaple can be found at:

    https://github.com/leaflabs/libmaple

librambutan 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 librambutan
------------------------------------------------------------------------------

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

    http://docs.rambutan.cc/projects/librambutan/en/master/unix-toolchain.html

At a minimum you will need the gcc-arm-none-eabi toolchain on your path,
including the newlib libc and the libstdc++ libraries.

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

Hosted HTML documentation for several versions of librambutan are available at:

    http://docs.rambutan.cc/projects/librambutan/en/master/

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 docs directory. See the READMEs there
for details.

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

/build/

    Compiler output

/contrib/

    Community-contributed resources.

/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. librambutan is (mostly) under an MIT
    license.

/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.