Commit 6feb42c8 authored by Thomas Schöpping's avatar Thomas Schöpping
Browse files

Patch 1.0.1:

- Introduced target/Makefile for conventient building and flashing from a single location.
- Added stm32flash (version 0.5) as Git submodule.
- Enhancements to the various bash scripts. Most of all, these scripts can now be executed from arbitrary location.
parent 470d0567
[submodule "Host/stm32flash"]
path = Host/Source/stm32flash
url = https://git.code.sf.net/p/stm32flash/code
......@@ -215,7 +215,7 @@ static void DisplayProgramInfo(void)
printf("Copyright (c) by Feaser http://www.feaser.com \n");
printf("---------------------------------------------------------------------------\n");
printf("This tool was modified for the 'Autonomous Mini Robot' - AMiRo. \n");
printf("Copyright (c) 2016..2017 Marvin Barther, Thomas Schoepping, and Stefan \n");
printf("Copyright (c) 2016..2018 Marvin Barther, Thomas Schoepping, and Stefan \n");
printf(" Herbrechtsmeier \n");
printf("This is free software; see the source for copying conditions. There is NO \n");
printf("warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n");
......
stm32flash @ 1f934ae8
Subproject commit 1f934ae86babdeea47afdfae1d856d5fd5da6c53
AMiRo-BLT is the bootloader and flashing toolchain for the base version of the
Autonomous Mini Robot (AMiRo) [1,2]. It is based on OpenBLT developed by Feaser
Autonomous Mini Robot (AMiRo) [1]. It is based on OpenBLT developed by Feaser
(see <http://feaser.com/en/openblt.php>).
Copyright (C) 2016..2017 Thomas Schöpping et al.
Copyright (C) 2016..2018 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
......@@ -24,17 +24,15 @@ University, which is funded by the German Research Foundation (DFG).
Authors:
- Thomas Schöpping <tschoepp[at]cit-ec.uni-bielefeld.de>
- Stefan Herbechtsmeier <sherbrec[at]cit-ec.uni-bielefeld.de>
- Stefan Herbrechtsmeier <sherbrec[at]cit-ec.uni-bielefeld.de>
- Marvin Barther
References:
[1] Herbrechtsmeier S., Rückert U., & Sitte J. (2012). "AMiRo - Autonomous Mini
Robot for Research and Education". In Advances in Autonomous Mini Robots
(pp. 101-112). Springer Berlin Heidelberg.
[2] Schöpping T., Korthals T., Herbrechtsmeier S., & Rückert U. (2015). "AMiRo:
A Mini Robot for Scientific Applications" In Advances in Computational
Intelligence (pp. 199-205). Springer International Publishing.
[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.
################################################################################
......@@ -58,14 +56,16 @@ AMiRo base modules.
CONTENTS:
1 Required software
1.1 stm32flash
1.2 GCC ARM Embedded Toolchain
1.3 GNU Make
1.4 CMake
1.1 Git
1.2 GNU Make
1.3 GCC
1.4 stm32flash
1.5 GCC ARM Embedded Toolchain
1.6 CMake
2 Recommended Software
3 Compiling the source code
3.1 target software
3.2 host software
3.1 host software
3.2 target software
================================================================================
......@@ -80,41 +80,67 @@ with the microcontrollers (MCUs) of AMiRo, the former is used to write this data
to the hardware.
1.1 - Git
---------
Since all main- and subprojects are available as Git repositories, installing a
recent version of the tool is mandatory.
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 (e.g. features of a very
recent version) are required.
1.1 - stm32flash
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
----------------
To build the tool from source, clone the GIT repository to a local folder on
your machine:
>$ git clone git://git.code.sf.net/p/stm32flash/code
Make sure that you have selected version 0.4 or later of the tool. You can now
build the tool simply by executing 'make'. Finally, you must make the resulting
binary (stm32flash) globally available in your environment. You can do so by
either copying the file to an appropriate location (e.g. /usr/local/bin/) or
creating an according link. The tool must be available as 'stm32flash' in every
new shell.
This tool is required to flash the bootloader binaries to the microcontrollers.
Since it is included in this project as a submodule, you can just run the setup
script in the 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.
1.2 - GCC ARM Embedded Toolchain
1.5 - GCC ARM Embedded Toolchain
--------------------------------
Various versions of the GCC for ARM embedded devices can be found at
<https://launchpad.net/gcc-arm-embedded>. For installation of the compiler
toolchain, please follow the instructions that can be found on the web page.
If you have access to the AMiRo-OS project as well, it is highly recommended
to use the setup application provided there.
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.
1.3 - 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 (e.g. features of a very
recent version) are required.
If you are running a 64-bit operating system, you may have to install several
32-bit libraries in order to make the compiler work. 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.4 - CMake
1.6 - CMake
-----------
In order to build the SerialBoot host application, CMake version 2.8 or later is
......@@ -146,7 +172,21 @@ accessible when the robot is fully set up, this enables to update the firmware
even for other modules.
3.1 - target software
3.1 - host software
-------------------
The stm32flash tool is requried to flash bootloader binaries to the MCUs.
Instructions for builing 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.sh 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
---------------------
In the ./Target/Demo/ directory there are three subfolders, one for each AMiRo
......@@ -155,32 +195,40 @@ base module. Within each of these is an additional Boot/ folder
be compiled by executing 'make' in these directories.
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. You can do so
by executing the following command:
>$ sudo echo 'KERNEL=="ttyUSB[0-9]*",NAME="tts/USB%n",SYMLINK+="%k",MODE="0666"' > /etc/udev/rules.d/50-ttyusb.rules
full read and write permissions to the USB ports of your system. 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 (sudo required) and add the
following lines:
# Future Technology Devices International Ltd. - TTL-232RG
SUBSYSTEMS=="usb", ACTION=="add", KERNEL=="ttyUSB[0-9]*",
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE="0666"
# Future Technology Devices International Ltd. - FT231X
SUBSYSTEMS=="usb", ACTION=="add", KERNEL=="ttyUSB[0-9]*",
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6015", MODE="0666"
Now connect the module you want to flash directly to your system (note that
indirect flashing 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?
Reboot and try again!
- Could the makefile execute the stm32flash tool?
Reinitialize the submodule 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.
ATTENTION:
Never flash a bootloader to the wrong module! Doing so might cause severe errors
and damage the robot.
3.2 - host software
-------------------
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.sh script to build SerialBoot. In the end the binary path
should be ./Host/Sotware/SerialBoot/build/SerialBoot.
================================================================================
......@@ -170,7 +170,7 @@ void blCallbackHandleShutdownRequest(void);
const blCallbackTable_t cbtable __attribute__ ((section ("_callback_table"))) = {
.magicNumber = BL_MAGIC_NUMBER,
.vBootloader = {BL_VERSION_ID_AMiRoBLT_Release, BL_VERSION_MAJOR, BL_VERSION_MINOR, 0},
.vBootloader = {BL_VERSION_ID_AMiRoBLT_Release, BL_VERSION_MAJOR, BL_VERSION_MINOR, 1},
.vSSSP = {BL_VERSION_ID_SSSP, SSSP_VERSION_MAJOR, SSSP_VERSION_MINOR, 0},
.vCompiler = {BL_VERSION_ID_GCC, __GNUC__, __GNUC_MINOR__, __GNUC_PATCHLEVEL__}, // currently only GCC is supported
.cbShutdownHibernate = blCallbackShutdownHibernate,
......
......@@ -140,7 +140,7 @@ void blCallbackHandleShutdownRequest(void);
const blCallbackTable_t cbtable __attribute__ ((section ("_callback_table"))) = {
.magicNumber = BL_MAGIC_NUMBER,
.vBootloader = {BL_VERSION_ID_AMiRoBLT_Release, BL_VERSION_MAJOR, BL_VERSION_MINOR, 0},
.vBootloader = {BL_VERSION_ID_AMiRoBLT_Release, BL_VERSION_MAJOR, BL_VERSION_MINOR, 1},
.vSSSP = {BL_VERSION_ID_SSSP, SSSP_VERSION_MAJOR, SSSP_VERSION_MINOR, 0},
.vCompiler = {BL_VERSION_ID_GCC, __GNUC__, __GNUC_MINOR__, __GNUC_PATCHLEVEL__}, // currently only GCC is supported
.cbShutdownHibernate = blCallbackShutdownHibernate,
......
......@@ -193,7 +193,7 @@ void blCallbackHandleShutdownRequest(void);
const blCallbackTable_t cbtable __attribute__ ((section ("_callback_table"))) = {
.magicNumber = BL_MAGIC_NUMBER,
.vBootloader = {BL_VERSION_ID_AMiRoBLT_Release, BL_VERSION_MAJOR, BL_VERSION_MINOR, 0},
.vBootloader = {BL_VERSION_ID_AMiRoBLT_Release, BL_VERSION_MAJOR, BL_VERSION_MINOR, 1},
.vSSSP = {BL_VERSION_ID_SSSP, SSSP_VERSION_MAJOR, SSSP_VERSION_MINOR, 0},
.vCompiler = {BL_VERSION_ID_GCC, __GNUC__, __GNUC_MINOR__, __GNUC_PATCHLEVEL__}, // currently only GCC is supported
.cbShutdownHibernate = blCallbackShutdownHibernate,
......
STM32FLASH = stm32flash
STM32FLASH := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))../../Host/Source/stm32flash/stm32flash
ifeq ($(OS),Windows_NT)
STM32FLASH_PORT ?= COM5
else
......
################################################################################
# AMiRo-BLT is the bootloader and flashing toolchain for the base version of #
# the Autonomous Mini Robot (AMiRo). It is based on OpenBLT developed by #
# Feaser (see <http://feaser.com/en/openblt.php>). #
# 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). #
################################################################################
ROOT_PATH = ..
DWD_PATH = $(ROOT_PATH)/Target/Demo/ARMCM3_STM32F103_DiWheelDrive_GCC/Boot
PM_PATH = $(ROOT_PATH)/Target/Demo/ARMCM4_STM32F405_Power_Management_GCC/Boot
LR_PATH = $(ROOT_PATH)/Target/Demo/ARMCM3_STM32F103_LightRing_GCC/Boot
all:
$(MAKE) -C $(DWD_PATH)
$(MAKE) -C $(PM_PATH)
$(MAKE) -C $(LR_PATH)
clean:
$(MAKE) -C $(DWD_PATH) clean
$(MAKE) -C $(PM_PATH) clean
$(MAKE) -C $(LR_PATH) clean
DiWheelDrive:
$(MAKE) -C $(DWD_PATH)
PowerManagement:
$(MAKE) -C $(PM_PATH)
LightRing:
$(MAKE) -C $(LR_PATH)
flash_DiWheelDrive:
$(MAKE) -C $(DWD_PATH) flash
flash_PowerManagement:
$(MAKE) -C $(PM_PATH) flash
flash_LightRing:
$(MAKE) -C $(LR_PATH) flash
This diff is collapsed.
################################################################################
# AMiRo-BLT is an bootloader and toolchain 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). #
################################################################################
#!/bin/bash
################################################################################
# GENERIC FUNCTIONS #
################################################################################
### print an error message #####################################################
# Prints a error <message> to standard output.
#If variable 'LOG_FILE' is specified, the message is also appended to the given file.
#
# usage: printError <message>
# arguments: <message>
# Message string to print.
# return: n/a
#
function printError {
local string="ERROR: $1"
# if a log file is specified
if [ -n "$LOG_FILE" ]; then
printf "[$(date '+%Y-%m-%d %H:%M:%S')] $string" >> $LOG_FILE
fi
printf "$(tput setaf 1)>>> $string$(tput sgr 0)" 1>&2
}
### print a warning message ####################################################
# Prints a warning <message> to standard output.
#If variable 'LOG_FILE' is specified, the message is also appended to the given file.
#
# usage: printMessage <message>
# arguments: <message>
# Message string to print.
# return: n/a
#
function printWarning {
local string="WARNING: $1"
# if a log file is specified
if [ -n "$LOG_FILE" ]; then
printf "[$(date '+%Y-%m-%d %H:%M:%S')] $string" >> $LOG_FILE
fi
printf "$(tput setaf 3)>>> $string$(tput sgr 0)"
}
### print an information message ###############################################
# Prints an information <message> to standard output.
#If variable 'LOG_FILE' is specified, the message is also appended to the given file.
#
# usage: printInfo <message>
# arguments: <message>
# Message string to print.
# return: n/a
#
function printInfo {
local string="INFO: $1"
# if a log file is specified
if [ -n "$LOG_FILE" ]; then
printf "[$(date '+%Y-%m-%d %H:%M:%S')] $string" >> $LOG_FILE
fi
printf "$(tput setaf 2)>>> $string$(tput sgr 0)"
}
### print a message to file ####################################################
# Appends a <message> to a log file, specified by the variable 'LOG_FILE'.
#
# usage printLog <message>
# arguments: <message>
# Message string to print.
# return: n/a
#
function printLog {
local string="LOG: $1"
# if a log file is specified
if [ -n "$LOG_FILE" ]; then
printf "[$(date '+%Y-%m-%d %H:%M:%S')] $string" >> $LOG_FILE
fi
}
### exit the script normally ###################################################
# Prints a delimiter and exits the script normally (returns 0).
#
# usage: quitScript
# arguments: n/a
# return: 0
# No error or warning occurred.
#
function quitScript {
printInfo "exiting $(realpath ${BASH_SOURCE[0]})\n"
printf "\n"
printf "######################################################################\n"
exit 0
}
### read a user input ##########################################################
# Reads a single character user input from a set up <options> and stores it in
# a given <return> variable.
#
# usage: readUserInput <options> <return>
# arguments: <options>
# String definiing the set of valid characters.
# If the string is empty, the user can input any character.
# <return>
# Variable to store the selected character to.
# return: n/a
#
function readUserInput {
local input=""
# read user input
while [ -z $input ] || ( [ -n "$1" ] && [[ ! $input =~ ^[$1]$ ]] ); do
read -p "your selection: " -n 1 -e input
if [ -z $input ] || ( [ -n "$1" ] && [[ ! $input =~ ^[$1]$ ]] ); then
printWarning "[$input] is no valid action\n"
fi
done
printLog "[$input] has been selected\n"
eval $2="$input"
}
### check whether argument is an option ########################################
# Checks a <string> whether it is an option.
# Options are defined to either start with '--' followed by any string, or
# to start with a single '-' followed by a single character, or
# to start with a single '-' followed by a single character, a '=' and any string.
# Examples: '--option', '--option=arg', '-o', '-o=arg', '--'
#
# usage: parseIsOption <string>
# arguments: <string>
# A string to check whether it is an option.
# return: 0
# <string> is an option.
# -1
# <string> is not an option.
#
function parseIsOption {
if [[ "$1" =~ ^-(.$|.=.*) ]] || [[ "$1" =~ ^--.* ]]; then
return 0
else
return -1
fi
}
### set the log file ###########################################################
# Sets a specified <infile> as log file and checks whether it already exists.
# If so, the log may either be appended to the file, its content can be cleared,
# or no log is generated at all.
# The resulting path is stored in <outvar>.
#
# usage: setLogFile [--option=<option>] [--quiet] <infile> <outvar>
# arguments: --option=<option>
# Select what to do if <file> already exists.
# Possible values are 'a', 'c', 'r' and 'n'.
# - a: append (starts with a separator)
# - c: continue (does not insert a seperator)
# - r: delete and restart
# - n: no log
# If no option is secified but <file> exists, an interactive selection is provided.
# --quiet
# Suppress all messages.
# <infile>
# Path of the wanted log file.
# <outvar>
# Variable to store the path of the log file to.
# return: 0
# No error or warning occurred.
# -1
# Error: invalid input
#
function setLogFile {
local filepath=""
local option=""
local quiet=false
# parse arguments
local otherargs=()
while [ $# -gt 0 ]; do
if ( parseIsOption $1 ); then
case "$1" in
-o=*|--option=*)
option=${1#*=}; shift 1;;
-o*|--option*)
option="$2"; shift 2;;
-q|--quiet)
quiet=true; shift 1;;
*)
printError "invalid option: $1\n"; shift 1;;
esac
else
otherargs+=("$1")
shift 1
fi
done
filepath=$(realpath ${otherargs[0]})
# if file already exists
if [ -e $filepath ]; then
# if no option was specified, ask what to do
if [ -z "$option" ]; then
printWarning "log file $filepath already esists\n"
local userinput=""
printf "Select what to do:\n"
printf " [A] - append log\n"
printf " [R] - restart log (delete existing file)\n"
printf " [N] - no log\n"
readUserInput "AaRrNn" userinput
option=${userinput,,}
fi
# evaluate option
case "$option" in
a|c)
if [ $quiet = false ]; then
printInfo "appending log to $filepath\n"
fi
if [ $option != c ]; then
printf "\n" >> $filepath
printf "######################################################################\n" >> $filepath
printf "\n" >> $filepath
fi
;;
r)
echo -n "" > $filepath
if [ $quiet = false ]; then
printInfo "content of $filepath wiped\n"
fi
;;
n)
if [ $quiet = false ]; then
printInfo "no log file will be generated\n"
fi
filepath=""
;;
*) # sanity check (return error)
printError "unexpected argument: $option\n"; return -1;;
esac
else
if [ $quiet = false ]; then
printInfo "log file set to $filepath\n"
fi
fi
eval ${otherargs[1]}="$filepath"
return 0
}
################################################################################
# SPECIFIC FUNCTIONS #
################################################################################
### print welcome text #########################################################
# Prints a welcome message to standard out.
#
# usage: printWelcomeText
# arguments: n/a
# return: n/a
#
function printWelcomeText {
printf "######################################################################\n"
printf "# #\n"
printf "# Welcome to the AMiRo-BLT compiler setup! #\n"
printf "# #\n"
printf "######################################################################\n"
printf "# #\n"
printf "# Copyright (c) 2016..2018 Thomas Schöpping #\n"
printf "# #\n"
printf "# This is free software; see the source for copying conditions. #\n"
printf "# There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR #\n"
printf "# A PARTICULAR PURPOSE. The development of this software was #\n"
printf "# supported by the Excellence Cluster EXC 227 Cognitive Interaction #\n"
printf "# Technology. The Excellence Cluster EXC 227 is a grant of the #\n"
printf "# Deutsche Forschungsgemeinschaft (DFG) in the context of the German #\n"
printf "# Excellence Initiative. #\n"
printf "# #\n"
printf "######################################################################\n"
}
### print help #################################################################