Commit 48044f4c authored by Thomas Schöpping's avatar Thomas Schöpping
Browse files

Readme.md documentation slightly extended.

parent c6f83da5
......@@ -44,23 +44,28 @@ Contents
1. [Introduction](#1-introduction)
2. [Required Software](#2-required-software)
1. [Git](#21-git)
2. [GNU Make](#22-gnu-make)
3. [GCC](#23-gcc)
4. [stm32flash](#24-stm32flash)
5. [GNU ARM Embedded Toolchain](#25-gnu-arm-embedded-toolchain)
6. [CMake](#26-cmake)
1. [Git](#21-git)
2. [GNU Make](#22-gnu-make)
3. [GCC](#23-gcc)
4. [stm32flash](#24-stm32flash)
5. [GNU ARM Embedded Toolchain](#25-gnu-arm-embedded-toolchain)
6. [CMake](#26-cmake)
3. [Recommended Software](#3-recommended-software)
1. [PlantUML](#31-plantuml)
2. [QtCreator IDE](#32-qtcreator-ide)
4. [Compiling the Source Code](#4-compiling-the-source-code)
1. [Host Software](#41-host-software)
2. [Target Software](#42-target-software)
1. [PlantUML](#31-plantuml)
2. [QtCreator IDE](#32-qtcreator-ide)
4. [File Structure](#4-file-structure)
1. [docs/](#41-docs)
2. [Host/](#42-host)
3. [Target/](#43-target)
4. [tools/](#44-tools)
5. [Compiling the Source Code](#5-compiling-the-source-code)
1. [Host Software](#51-host-software)
2. [Target Software](#52-target-software)
--------------------------------------------------------------------------------
1 - Introduction
================
1 -- Introduction
=================
AMiRo-BLT is the bootloader and flashing toolchain for the base version of the Autonomous Mini Robot (AMiRo) [1].
It is based on OpenBLT developed by Feaser (see <http://feaser.com/en/openblt.php>) and implements the [Startup Shutdown Synchronization Protocol (SSSP)](https://gitlab.ub.uni-bielefeld.de/AMiRo/sssp).
......@@ -72,35 +77,35 @@ While this file provides information for end users of AMiRo-BLT, developers can
2 - Required Software
=====================
2 -- Required Software
======================
In order to compile and flash the AMiRo bootloader, some additional software is required, all of which are described in detail in the following.
2.1 - Git
---------
2.1 -- Git
----------
Since all main- and subprojects are available as Git repositories, installing a recent version of the tool is mandatory.
Most Linux distributions like Ubuntu provide a sufficient version in their software repositories.
2.2 - GNU Make
2.2 -- GNU Make
---------------
GNU Make usually comes as preinstalled tool on Ubuntu based operating systems.
If your system is missing GNU Make, it is recommended to install it from the standard repositories since no special requirements (i.e. features of a very recent version) are required.
2.3 - GCC
---------
2.3 -- GCC
----------
In order to build some required tools from source, GCC is required.
It usually comes as preinstalled tool on Ubuntu based operating systems.
If your system is missing GCC, it is recommended to install it from the standard repositories since no special requirements (e.g. features of a very recent version) are required.
2.4 - stm32flash
2.4 -- stm32flash
-----------------
This tool is required to flash the bootloader binaries to the microcontrollers of the AMiRo base modules.
......@@ -123,8 +128,8 @@ If you do have root permissions on your system, you can install stm32flash this
However, the scripts will always check for a "local" installation in [`./Host/Source/stm32flash/`](./Host/Source/stm32flash/) first and only try a system-wide installation afterwards.
2.5 - GNU ARM Embedded Toolchain
--------------------------------
2.5 -- GNU ARM Embedded Toolchain
---------------------------------
Various versions of the GCC for ARM embedded devices can be found at <https://developer.arm.com/open-source/gnu-toolchain/gnu-rm> (old versions are available at <https://launchpad.net/gcc-arm-embedded>).
For installation of the compiler toolchain and managing of multiple versions, it is highly recommended to use the provided setup script.
......@@ -140,30 +145,30 @@ You can run the following shell commands to install the according 32-bit version
>$ sudo apt-get install libc6:i386 libstdc++6:i386 libncurses5:i386
```
2.6 - CMake
-----------
2.6 -- CMake
------------
In order to build the SerialBoot host application, CMake version 2.8 or later is required.
If possible, it is recommended to instal it from the standard repositories of your operating system.
3 - Recommended Software
========================
3 -- Recommended Software
=========================
The software tools named in this section are not essential for simply using or further development of AMiRo-BLT, but are useful in both scenarios.
3.1 - PlantUML
--------------
3.1 -- PlantUML
---------------
PlantUML is a free and open source Java tool to generate UML diagrams via scrips (see <https://plantuml.com>).
AMiRo-BLT provides according scripts in the [`./Target/docs/`](./Target/docs/) directory.
Please refer to the PlantUML documentation for how to generate figures from these script files.
3.2 - QtCreator IDE
-------------------
3.2 -- QtCreator IDE
--------------------
AMiRo-BLT provides support for the QtCreator IDE.
In order to setup according projects, use the setup script and follow the instructions.
......@@ -171,8 +176,52 @@ It will automatically generate the required files and you can import the project
Please note that you will need to recompile the AMiRo-BLT source code after each project generation, since the generator executes a compiler call.
4 - Compiling the Source Code
-----------------------------
4 -- File Structure
===================
The AMiRo-BLT root directory contains four folder.
First, the `docs/` folder contains files related to documentation.
Actual code of the bootloader and the toolchain for host systems is located in the folders `Host/` and `Target/`.
Finally, several useful tools for installation, maintenance and development can be found in the `tools/` directory.
4.1 -- docs/
------------
Since all code is documented inline, this directory just contains several further Markdown files, detailing the following aspects:
- Low power modes available on the AMiRo platform and supported by AMiRo-BLT.
- Interface for an operating system to interact with the bootloader.
- System signals used by the Bootloader during system startup and shutdown.
4.2 -- Host/
------------
This directory contains all source code for the essential tools to be executed on a host machine.
First, there is the `SerialBoot` tool, which can be used to interact with the bootloader on a device to update the firmware.
Second, `stm32flash`, which is required to flash the bootloader to a device, is included here as Git submodule.
When compiled using the provided Makefiles, the resulting binaries are placed in according subfolders.
4.3 -- Target/
--------------
This directory contains all source code for the bootloader itself.
While the `docs/` folder contains some further documentation, specifically for this part of AMiRo-BLT, all bootloader code is located in the folders `Modules/` and `Source/`.
Any code which is individual for each device can be found in the former, whereas all general code which is identical for all devices is located in the latter.
When compiled using the provided Makefiles, the resulting binary images are placed in according subfolders within the folders for the individula modules (e.g. `Target/Modules/DiWheelDrive_1-1/`).
4.4 -- tools/
-------------
This directory contains several useful tools to initialize and configure AMiRo-BLT, install and manage cross compilers as well as setting up IDE projects.
For convenience, all these tools can be accessed via the `setup.sh` script in the AMiRo-BLT root directory.
5 -- Compiling the Source Code
==============================
The AMiRo-BLT project is separated into two major parts: target- and host-related software.
The former comprises the bootloaders for the base modules of the AMiRo platform.
......@@ -180,7 +229,7 @@ The latter are the stm32flash tool as already mentioned above, and the SerialBoo
Since the programming connector of the lowermost AMiRo module (_DiWheelDrive_) is the only one accessible when the robot is fully set up, this enables to update the firmware even for other modules without the need to disassemble the device.
4.1 - Host Software
5.1 - Host Software
-------------------
The stm32flash tool is required to flash bootloader binaries to the MCUs.
......@@ -192,8 +241,8 @@ To ensure compatibility with other software (e.g. [AMiRo-OS](https://gitlab.ub.u
In the end, the binary path should be `./Host/Source/SerialBoot/build/SerialBoot`, which is the default for any scripts and tools that use SerialBoot.
4.2 - Target Software
---------------------
5.2 -- Target Software
----------------------
Module specific code for the several AMiRo base modules is located in the individual subfolders in the [`./Target/Modules/`](./Target/Modules/) directory.
To compile (and flash; please read further) the bootloaders, it is recommended to run make in the [`./Target/`](./Target/) folder.
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment