AMiRo-OS

[submodule "kernel/ChibiOS"]

	path = kernel/ChibiOS

	url = https://github.com/ChibiOS/ChibiOS.git

	ignore = dirty

[submodule "bootloader/AMiRo-BLT"]

	path = bootloader/AMiRo-BLT

	url = http://openresearch.cit-ec.de/git/amiro-os.amiro-blt.git

[submodule "periphery-lld/AMiRo-LLD"]

	path = periphery-lld/AMiRo-LLD

	url = http://openresearch.cit-ec.de/git/amiro-os.amiro-lld.git

################################################################################

# AMiRo-OS is an operating system designed for the Autonomous Mini Robot       #

# (AMiRo) platform.                                                            #

# Copyright (C) 2016..2018  Thomas Schöpping et al.                            #

#                                                                              #

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

################################################################################

define HELP_TEXT

################################################################################

#                                                                              #

# Copyright (c) 2016..2018  Thomas Schöpping                                   #

#                                                                              #

# This is free software; see the source for copying conditions. There is NO    #

# warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  #

# The development of this software was supported by the Excellence Cluster     #

# EXC 227 Cognitive Interaction Technology. The Excellence Cluster EXC 227 is  #

# a grant of the Deutsche Forschungsgemeinschaft (DFG) in the context of the   #

# German Excellence Initiative.                                                #

#                                                                              #

################################################################################

  AMiRo-OS Makefile help

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

ARGUMENTS:

  help:

      Prints this text.

  all:

      Builds the binaries for all modules.

  flash:

      Flashes all binaries to the hardware.

      If the binaries do not exist, they are created beforehand.

  clean:

      Deletes all temporary and binary files of all modules.

  <module>:

      Builds the binary only for the specified module.

      Possible values for <module> are:

        - DiWheelDrive

        - PowerManagement

        - LightRing

EXAMPLES:

  >$$ make DiWheelDrive

      This command will generate the binary file for the DiWheelDrive module.

  >$$ make DiWheelDrive LightRing

      This command will generate the binary files for the two modules

      DiWheelDrive and LightRing.

  >$$ make flash -j

      This command will first build all missing binary files and flash all

      modules as soon as the binaries are ready.

      By the additional argument '-j' the build process will be parallelized.

  >$$ make clean && make all && make flash

      This command will first clean all thee projects. In a second step the

      binaries for al three modules are build from scratch. Finally all modules

      are updated with the latest software.

      The following command can be used as a shorter and faster version:

          >$$ make clean && make flash -j

################################################################################

endef

export HELP_TEXT

OS_BASE_DIR := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))

help:

	@echo "$$HELP_TEXT"

	@exit

include $(OS_BASE_DIR)/os/modules/Makefile

AMiRo-OS is an operating system for the base version of the Autonomous Mini

system kernel and extends it with platform specific configurations and further

functionalities and abstractions.

Copyright (C) 2016..2018  Thomas Schöpping et al.

 - Thomas Schöpping          <tschoepp[at]cit-ec.uni-bielefeld.de>

 - Marc Rothmann

  1  Required software

    1.1  Git

    1.2  Bootloader & Tools

    1.3  System Kernel

    1.4  Low-Level Drivers

  2  Recommended software

    2.1  gtkterm and hterm

    2.2  QtCreator IDE

    2.3  Doxygen & Graphviz

  3  Building and flashing

In order to compile the source code, you need to install the GNU ARM Embedded

Toolchain. Since this project uses GNU Make for configuring and calling the

compiler, this tool is requried too. AMiRo-OS uses ChibiOS as system kernel,

so you need a copy of that project as well.

1.2 Bootloader & Tools

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

AMiRo-OS can take advantage of an installed bootloader if such exists and

provides an interface. By default, AMiRo-BLT is included as a Git submodule and

can easily be initialized via the ./setup.sh script. If requried, you can

replace the used bootloader by adding an according subfolder in the ./bootloader

directory. Note that you will have to adapt the makefiles and scripts, and

probably the operating system as well.

AMiRo-BLT furthermore has its own required and recommended software tools as

described in its README.txt file. Follow th instructions to initialize the

development environment manually or use the ./setup.sh script.

1.3 System Kernel

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

copy of it as well. For the sake of compatibility, it is included in AMiRo-OS as

a Git submodule. It is highly recommended to use the ./setup.sh script for

initialization. Moreover, you have to apply the patches to ChibiOS in order to

make AMiRo-OS work properly. It is recommended to use the .setup.sh script for this

purpose.

If you would like to use a different kernel, you can add a subfolder in the

./kernel/ directory and adapt the scripts and operating system source code.

1.4 Low-Level Drivers

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

Any required low-level drivers for the AMiRo hardware is available in an

additional project: AMiRo-LLD. It is included as a Git subodule and can be

initialized via the ./setup.sh script.

AMiRo-OS can take advanatge of an installed bootloader, which is recommended for

the best experience. In order to use all features of AMiRo-OS it is also

recommended to install either the 'hterm' or 'gtkterm' application for accessing

the robot. To ease further development, this project offers support for the

QtCreator IDE.

Depending on your operating system it is recommended to install 'gtkterm' for

gtkterm you need to modify the configuration file ~/.gtktermrc (generated

For hterm you need to configure the tool analogously. With either tool the robot

can be reset by toggling the RTS signal on and off again, and you can access the

system shell of AMiRo-OS.

2.2 - QtCreator IDE

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

In order to setup QtCreator projects for the three AMiRo base modules, you can

use the provided ./setup.sh script. Further instructions for a more advanced

configuration of the IDE are provided in the ./tools/qtcreator/README.txt file.

2.3  Doxygen & Graphviz

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

In order to generate the documentation from the source code, Doxygen and

Graphviz are requried. It is recommended to install these tool using the

default versions for your system. Ubuntu users should simply run

  >$ sudo apt-get install doxygen graphviz

project for the according AMiRo module. Therefore you can use the ./Makefile by

simply executing 'make' and follow the instructions. Alternatively, you can

either use the makefiles provided per module in ./os/modules/<ModuleToCompile>

or - if you want to compile all modules at once - the makefile in the

./os/modules folder. After the build process has finished successfully, you

always have to flash the generated program to the robot. Therefore you need an

appropriate tool, such as stm32flash (if you don't use a bootloader) or

SerialBoot (highly recommended; provided by AMiRo-BLT). Similarly to the

compilation procedure as described above, you can flash either each module

separately, or all modules at once by executing 'make flash' from the according

directory.

When using SerialBoot, please note that you must connect the programming cable

either to the DiWheelDrive or the PowerManagement module for flashing the

operating system. All other modules are powered off after reset so that only

these two offer a running bootloader, which is required for flashing.