1. Project Directory Layout
The top-level directory structure of the firmware project looks something like this:
* bin Pre-Build FW and test binaries * CHANGELOG Firmware Change-Log * common_lib.mk Common makefile used for library building * common.mk Common makefile used for firmware building * doc Common documentation * libemb Git sub-project referencing to "libemb" * libsherpacore uSherpa core (protocol and core functionality) * Makefile Top-Level makefile * README This README * serial-sherpa Firmware which exposes the uSherpa on 1st UART * test Various test firmwares * tools Various tools, used mainly internally
Each library sub-project (names starting with “lib*”) has the following layout:
* doc Library specific documentation * gen Source code documentation generated by doxygen (after "make gen-docs") * doxygen.conf Configuration for doxygen * lib Library in binary format (after "make") * Makefile Library top-level makefile * README Library specific README * src Library sources * include Library header files * Makefile Library makefile
Each firmware sub-project (“*-sherpa” and “test/*”) has the following layout:
* doc Firmware specific documentation * gen Source code documentation generated by doxygen (after "make gen-docs") * doxygen.conf Configuration for doxygen * bin Firmware in binary format (after "make") * Makefile Firmware top-level makefile * README Firmware specific README * src Firmware sources * include Firmware header files * Makefile Firmware makefile
2. Prerequisites
To compile all the libraries, firmware variants and test firmwares, the following mandatory tools need
to be installed on your Linux build-host:
- msp430-gcc for compiling (I use 4.5.3 which is `available on Ubuntu as packet|TODO link to Ubuntu Wiki`)
- mspdebug for flashing (I use 0.16 which is `available on Ubuntu as packet|TODO link to Ubuntu Wiki`)
- GNU-make or make (I use GNU make 3.81 which is available also as a pecket on Ubuntu)
To perform some of the extra tasks (like doxygen etc.), the following optional tools need to be installed on your build-host:
- doxygen for creating HTML documentation from the code annotations
- astyle for code formating
- cppcheck for static code checking
3. Getting the Sources
The sources are available on github:
git clone https://github.com/wendlers/usherpa-firmware.git
4. Compiling the Sources
When building the firmware the first time, the git submodule for “libemb” has to be initialized (since the “libemb” subdirectory
is a stub only otherwise). To initialize the “libemb” submodule, do the following (while in the top-level directory):
git submodule init git submodule update
To compile all the libraries, firmware variants and test firmware, change to the top-level directory “firmware” and issue:
make
This will produce the firmware binaries in various formats in the “bin” sub-directory of each variant. i
Currently the only firmware variant is the “serial-sherpa” firmware located in the directory “serial-sherpa”.
It will also produce a bunch of test firmwares located under the “test” directory. For more details on the
firmware variants or the tests, see the corresponding README files in the sub-directories.
NOTE: a pre-compiled version of the firmware and some of the tests could always be found in the top-level “bin” directory”.
5. Flashing
make flash-target
For the MSP430 target on a Launchpad, the “mspdebug” tool is used for flashing.
6. Generating API Documents
If you installed doxygen on your system, you could generate the HTML-based API documentation by calling:
make gen-docs
This will create the API documentation under “doc/gen/html” within each of the sub-directories of the libraries and
firmwares.
7. Applying Code Formating Guidelines
To format all code located in “*.h” and “*.c” files, you could issue the following command in one of the sub-directories:
make style
This will use “astyle” to format the code in “stroustrup” style.
8. Tailoring the Build Settings
General build settings (compiler, linker, flags etc.), and settings regarding code formatting and static code checks could be
adjusted in two files on a global basis:
common.mk: This is the common make file shared across all firmware variants as well as by the test firmware.
common_lib.mk: This is the common make file shared across all libraries.