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

documentation further revised

parent 5ffe336c
......@@ -36,7 +36,7 @@ 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
--------
......@@ -56,7 +56,7 @@ Contents
1. Host Software
2. Target Software
---
--------------------------------------------------------------------------------
1 - Introduction
================
......@@ -103,10 +103,10 @@ If your system is missing GCC, it is recommended to install it from the standard
-----------------
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:
Since it is included in this project as a Git submodule, you can just run the setup script in the project root directory using a terminal:
```sh
./setup.sh
>$ ./setup.sh
```
Follow the instructions to download the source code and compile the tool.
......@@ -115,10 +115,10 @@ Other scripts that require stm32flash will search for the binary at this locatio
The setup script does not install the tool to your system path, though, since this usually requires root permissions.
However, stm32flash provides a [`Makefile`](./Host/Source/stm32flash/Makefile) with installation capabilities.
Just Follow the instructions given in the file [`INSTALL`](./Host/Source/stm32flash/INSTALL).
Just Follow the instructions given in the [`INSTALL`](./Host/Source/stm32flash/INSTALL) file.
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.
If you do have root permissions on your system, you can install stm32flash this way.
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.
......@@ -131,12 +131,12 @@ Alternatively you can install the compiler manually by following the instruction
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:
You can run the following shell commands to install the according 32-bit versions of those packages:
```sh
sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install libc6:i386 libstdc++6:i386 libncurses5:i386
>$ sudo dpkg --add-architecture i386
>$ sudo apt-get update
>$ sudo apt-get install libc6:i386 libstdc++6:i386 libncurses5:i386
```
2.6 - CMake
......@@ -175,15 +175,15 @@ Please note that you will need to recompile the AMiRo-BLT source code after each
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 (_DiWheelDrive_) is the only one accessible when the robot is fully set up, this enables to update the firmware even for other modules.
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 (_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
-------------------
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.
Instructions on how to build and install the tool are given in chapter 2.4 of this file.
The SerialBoot tool can be built by using cmake.
The according [`CMakeLists.txt`](./Host/Source/SerialBoot/CMakeLists.txt) file can be found in the [`./Host/Source/SerialBoot/`](./Host/Source/SerialBoot/) directory.
......@@ -195,13 +195,13 @@ In the end, the binary path should be `./Host/Source/SerialBoot/build/SerialBoot
---------------------
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.
To compile (and flash; please read further) the bootloaders, it is recommended to run make in the [`./Target/`](./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 (root permissions required):
```sh
sudo touch /etc/udev/rules.d/50-usb-serial.rules
>$ sudo touch /etc/udev/rules.d/50-usb-serial.rules
```
Open the file in a text editor of your choice (with root permissions) and add the following lines:
......@@ -220,12 +220,13 @@ Now connect the module you want to flash directly to your system (note that indi
```sh
make flash
>$ make flash_<module>
```
where `<module>` specifies, which module you are going to flash (e.g. `DiWheelDrive_1-1`).
If the procedure was not successful, the following hints might help:
- Did your system apply the new `udev` rules?<br/>
- 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
......@@ -242,15 +243,20 @@ If the procedure was not successful, the following hints might help:
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`:
If you have connected multiple AMiRo modules to your system, those will be listed with increasing numbers in their identifiers.
Furthermore, other USB devices (possibly internal components) might be listed as such as well.
In those cases, you have to specify the correct port manually when calling make:
```sh
make flash STM32FLASH_PORT=/dev/ttyAMiRo#
>$ make flash STM32FLASH_PORT=/dev/ttyAMiRo#
```
where you have to replace the trailing `#` with the according integer.
You can easily list all connected devices via
```sh
>$ ls /dev/ | grep -E "^tty(USB|AMiRo)[0-9]+$"
```
**Attention**:<br/>
Never flash a bootloader to the wrong module!
......
......@@ -36,7 +36,7 @@ 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.
---
--------------------------------------------------------------------------------
Low-Power Modes
===============
......@@ -69,7 +69,7 @@ When the system entered DeepSleep mode, it will only wake up if one of the follo
In most cases the system will react by completely starting up, except when a power plug is detected, which makes it switch to hibernate mode.
This way the system usually draws as little power as possible and can still be charged using a power cord.
The worst case would be when a plug is detected but not powered, so that the system will wake up periodically (see hibernate mode) and draw energy.
The worst case would be when a plug is detected but not powered, so that the system will wake up periodically (see Hibernate mode) and draw energy.
Transportation
......
......@@ -36,13 +36,13 @@ 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.
---
--------------------------------------------------------------------------------
OS Interface
============
The bootloader provides an interface (cf. [`amiroblt.h`](../Target/Source/AMiRo/amiroblt.h)) for the operating system providing various information.
Most importantly, these include the definition of the "callback table" and its memory address as well as the definition of the contents of the backup register for the _PowerManagement_ module.
Most importantly, these include the definition of the "callback table" and its memory address as well as the definition of the contents of the backup registers for the _PowerManagement_ module.
The 64 byte callback table contains information about the AMiRo-BLT version and several function pointers.
The former can be used to detect whether the installed bootloader corresponds to the interface or if a legacy version is installed (or none at all).
......@@ -55,7 +55,7 @@ Callback Table
| bytes | content | description |
|:-----:|:--------------------------|:--------------------------------------------------------------------------------------------------------------------------|
| 1-4 | magic number | Can be used to check whether is is valid to interpret the data at this address as callback table . |
| 1-4 | magic number | Can be used to check whether it is valid to interpret the data at this address as callback table . |
| 5-8 | bootloader version | Version information about the installed bootloader. |
| 9-12 | SSSP version | Information about the implemented version of [SSSP](https://gitlab.ub.uni-bielefeld.de/AMiRo/sssp). |
| 13-16 | compiler version | Version information about the used compiler to build the bootloader. |
......
......@@ -36,7 +36,7 @@ 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.
---
--------------------------------------------------------------------------------
System Signals
==============
......@@ -50,17 +50,19 @@ The electrical interface of AMiRo, which connects all AMiRo Modules (AMs), defin
This signal is usually set inactive (high) and not used during operation.
Any AM can activate it (pull it low) to initiate a system shutdown or restart (cf. [SSSP](https://gitlab.ub.uni-bielefeld.de/AMiRo/sssp)).
- `SYS_REG_EN`<br/>
When set active (high), this signal indicates that it is safe to activate any voltage converters that use the system power supply (`VSYS`) to generate custom voltage. Whenever it is inactive (low), such converters must be turned off.
When set active (high), this signal indicates that it is safe to activate any voltage converters that use the system power supply (`VSYS`) to generate custom voltages.
Whenever it is inactive (low), such converters must be turned off.
- `SYS_SYNC_N` (aka `SYS_INT_N`)<br/>
Originally meant for system wide interrupts, this signal is now used to synchronize the AMs during startup, shutdown and operation (cf. [SSSP](https://gitlab.ub.uni-bielefeld.de/AMiRo/sssp)).
- `SYS_UART_UP/DN`<br/>
A neighbor signal, which can be used to communicate between neighboring AMs.
A neighbor signal, which can be used to communicate between adjacent AMs.
Except for the _DiWheelDrive_ and the _LightRing_, which are the top- and lowermost modules, each AM must provide both signals.
Note that neither signal is used for UART communication anymore despite their naming.
- `SYS_WARMRST_N`<br/>
Resets all slave modules the hard way.
Only the _PowerManagement_ and the _DiWheelDrive_ are not defined as slave modules.
Pull-up/down Configuration
--------------------------
......
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