Commit 3d27ba13 authored by aleks's avatar aleks
Browse files

Format README

parent 43464dd5
......@@ -5,31 +5,30 @@ 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>).
Copyright (C) 2016..2020 Thomas Schöpping et al.
(a complete list of all authors is given below)
Copyright (C) 2016..2020 Thomas Schöpping et al. (a complete list of all authors
is given below)
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.
This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
You should have received a copy of the GNU General Public License along with
this program. If not, see <http://www.gnu.org/licenses/>.
This research/work was supported by the Cluster of Excellence
Cognitive Interaction Technology 'CITEC' (EXC 277) at Bielefeld
University, which is funded by the German Research Foundation (DFG).
This research/work was supported by the Cluster of Excellence Cognitive
Interaction Technology 'CITEC' (EXC 277) at Bielefeld University, which is
funded by the German Research Foundation (DFG).
Authors:
- Thomas Schöpping (tschoepp@cit-ec.uni-bielefeld.de)
- Stefan Herbrechtsmeier (sherbrec@cit-ec.uni-bielefeld.de)
- Marvin Barther
- Thomas Schöpping (tschoepp@cit-ec.uni-bielefeld.de)
- Stefan Herbrechtsmeier (sherbrec@cit-ec.uni-bielefeld.de)
- Marvin Barther
References:
......@@ -38,53 +37,43 @@ References:
International Conference on System Theory, Control and Computing (ICSTCC),
Sinaia, 2016, pp. 687-692.
--------------------------------------------------------------------------------
Contents
========
1. Required Software
1. Git
2. GNU Make
3. GCC
4. stm32flash
5. GNU ARM Embedded Toolchain
6. CMake
2. Recommended Software
1. PlantUML
2. QtCreator IDE
3. Compiling the Source Code
1. Host Software
2. Target Software
--------------------------------------------------------------------------------
--------
1. Required Software
1. Git
2. GNU Make
3. GCC
4. stm32flash
5. GNU ARM Embedded Toolchain
6. CMake
2. Recommended Software
1. PlantUML
2. QtCreator IDE
3. Compiling the Source Code
1. Host Software
2. Target Software
1 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.
1.1 Git
-------
### 1.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.
1.2 GNU Make
------------
### 1.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.
1.3 GCC
-------
### 1.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
......@@ -92,20 +81,21 @@ 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.
1.4 stm32flash
--------------
### 1.4 stm32flash
This tool is required to flash the bootloader binaries to the microcontrollers
of the AMiRo base modules. Since it is included in this project as a Git
submodule, you can just run the setup script in the project root directory:
>$ ./setup.sh
```sh
./setup.sh
```
Follow the instructions to download the source code and compile the tool. The
resulting binary path is `./Host/Source/stm32flash/stm32flash`. Other scripts
that require `stm32flash` will search for the binary at this location by
default.
default.
The setup script does not install the tool to your system path, though, since
this usually requires root permissions. However, `stm32flash` provides a
`Makefile` with installation capabilities. Just Follow the instructions given in
......@@ -117,9 +107,7 @@ the tool this way. However, the scripts will always check for a 'local'
installation in `./Host/Source/stm32flash/` first and only try a system-wide
installation afterwards.
1.5 GNU ARM Embedded Toolchain
------------------------------
### 1.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
......@@ -134,50 +122,43 @@ several 32-bit libraries. The required packages are `libc6`, `libstdc++6`, and
`libncurses5`. You can run the following shell commands to install the according
32-bit versions of the packages:
>$ sudo dpkg --add-architecture i386
>$ sudo apt-get update
>$ sudo apt-get install libc6:i386 libstdc++6:i386 libncurses5:i386
```sh
sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install libc6:i386 libstdc++6:i386 libncurses5:i386
```
1.6 CMake
---------
### 1.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.
2 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.
2.1 PlantUML
------------
### 2.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/Doc/` directory. Please refer to the PlantUML documentation for how to
generate figures from these script files.
2.2 QtCreator IDE
-----------------
### 2.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. It will
automatically generate the required files and you can import the projects by
opening the `.creator` files with QtCreator IDE.
opening the `.creator` files with QtCreator IDE.
Please note that you will need to recompile the AMiRo-BLT source code after each
project generation, since the generator executes a compiler call.
3 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
......@@ -189,69 +170,73 @@ connector of the lowermost AMiRo module is the only one accessible when the
robot is fully set up, this enables to update the firmware even for other
modules.
### 3.1 Host Software
3.1 Host Software
-----------------
The `stm32flash` tool is requried to flash bootloader binaries to the MCUs.
Instructions on how to build and intall the tool are given in chapter 1.4 of
The `stm32flash` tool is required to flash bootloader binaries to the MCUs.
Instructions on how to build and install the tool are given in chapter 1.4 of
this file.
The `SerialBoot` tool can be built by using `cmake`. The according
`CMakeLists.txt` file can be found in the `./Host/Source/SerialBoot/` directory.
To ensure compatibility with other software (e.g. AMiRo-OS) it is higly
To ensure compatibility with other software (e.g. AMiRo-OS) it is highly
recommended to use the provided setup script to build `SerialBoot`. 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`.
3.2 Target Software
-------------------
### 3.2 Target Software
Module specific code for the several AMiRo base modules is located in the
individual subfolders in the `./Target/Modules/` directory. To compile
(and flash; please read further) the bootloaders, it is recommended to run
`make` in the `./Target/` folder.
individual subfolders in the `./Target/Modules/` directory. To compile (and
flash; please read further) the bootloaders, it is recommended to run `make` in
the `./Target/` folder.
In order to flash the bootloader to a microcontroller, you first have to set
full read and write permissions to the USB ports of your system when a
programming cable is plugged in. To do so, first create a new file by executing
the following command:
>$ sudo touch /etc/udev/rules.d/50-usb-serial.rules
```sh
sudo touch /etc/udev/rules.d/50-usb-serial.rules
```
Open the file in a text editor of your choice (root permissions required!) and
add the following lines:
# Future Technology Devices International Ltd. - TTL-232RG
SUBSYSTEMS=="usb", ACTION=="add", KERNEL=="ttyUSB[0-9]*", SYMLINK+="ttyAMiRo%n",
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE="0666"
```
# Future Technology Devices International Ltd. - TTL-232RG
SUBSYSTEMS=="usb", ACTION=="add", KERNEL=="ttyUSB[0-9]*", SYMLINK+="ttyAMiRo%n",
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE="0666"
# Future Technology Devices International Ltd. - FT231X
SUBSYSTEMS=="usb", ACTION=="add", KERNEL=="ttyUSB[0-9]*", SYMLINK+="ttyAMiRo%n",
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6015", MODE="0666"
# Future Technology Devices International Ltd. - FT231X
SUBSYSTEMS=="usb", ACTION=="add", KERNEL=="ttyUSB[0-9]*", SYMLINK+="ttyAMiRo%n",
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6015", MODE="0666"
```
Now connect the module you want to flash directly to your system (note that
indirect flashing using `SerialBoot` is not possible for the bootloader itself) and run the command
indirect flashing using `SerialBoot` is not possible for the bootloader itself)
and run the command
>$ make flash
```sh
make flash
```
If the procedure was not successful, the following hints might help:
* Did your system apply the new `udev` rules?
Re-login (or reboot) and try again!
* Could make execute the stm32flash tool?
Check the stm32flash installation (reinitialize the submodule if required) and try again!
* Are the permissions for USB ports set correctly?
Check the udev rules!
* Are there any other applications using the serial connection?
Close any other applications using the serial connection!
* Is the AMiRo module connected to your system?
Use the programming cable to connect the module to your system!
* Is the AMiRo module powered up?
Keep a charger plugged in during flashing!
* Was there an error when opening the ports?
Please read on!
- Did your system apply the new `udev` rules?<br/>
Re-login (or reboot) and try again!
- Could make execute the stm32flash tool?<br/>
Check the stm32flash installation (reinitialize the submodule if required) and
try again!
- Are the permissions for USB ports set correctly?<br/>
Check the udev rules!
- Are there any other applications using the serial connection?<br/>
Close any other applications using the serial connection!
- Is the AMiRo module connected to your system?<br/>
Use the programming cable to connect the module to your system!
- Is the AMiRo module powered up?<br/>
Keep a charger plugged in during flashing!
- Was there an error when opening the ports?<br/>
Please read on!
By default, the scripts use the first matching port (i.e. `/dev/ttyAMiRo0` or
`/dev/ttyUSB0`) for flashing. If you have connected multiple AMiRo boards to
......@@ -260,10 +245,11 @@ Furthermore, other USB devices (also internal components) might be listed as
such as well. In those cases, you have to specify the correct port manually when
calling `make`:
>$ make flash STM32FLASH_PORT=/dev/ttyAMiRo#
```sh
make flash STM32FLASH_PORT=/dev/ttyAMiRo#
```
where you have to replace the trailing `#` with the according integer.
**Attention**: Never flash a bootloader to the wrong module! Doing so might
cause severe errors and damage the hardware.
Markdown is supported
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