AMiRo-OS

About & License

===============

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)

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.

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

Authors:

-   Thomas Schöpping (tschoepp@cit-ec.uni-bielefeld.de)

-   Stefan Herbrechtsmeier (sherbrec@cit-ec.uni-bielefeld.de)

-   Marvin Barther

References:

[1] S. Herbrechtsmeier, T. Korthals, T. Schopping and U. Rückert, "AMiRo: A

    modular & customizable open-source mini robot platform," 2016 20th

    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

===================

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

-------

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

------------

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

-------

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.

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

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.  

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

the file `./Host/Source/stm32flash/INSTALL`.

Alternatively, some Linux distributions provide the tool in their software

repositories. If you do have root permissions on your system, you can install

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

------------------------------

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. Alternatively you can install the compiler

manually by following the instructions that can be found on the web page.

If you are going to install an old version, which is not available as 64-bit

package, but your are running a 64-bit operating system, you have to install

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

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

------------

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

-----------------

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.  

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

of the AMiRo platform. The latter are the `stm32flash` tool as already mentioned

above and the `SerialBoot` tool, which can be used to flash further binaries

(e.g. an operating system) to the microcontrollers without connecting to the

module directly (data is passed through via CAN bus). Since the programming

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

-----------------

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

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

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

-------------------

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.

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

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

    >$ 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!

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

your system, those will be listed with increasing numbers in their identifiers.

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#

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.