amiro-os / README.txt @ 4df853e0
History | View | Annotate | Download (7.99 KB)
1 | e545e620 | Thomas Schöpping | AMiRo-OS is an operating system for the base version of the Autonomous Mini |
---|---|---|---|
2 | 3dcad54e | Thomas Schöpping | Robot (AMiRo) [1]. It utilizes ChibiOS (a real-time operating system for |
3 | embedded devices developed by Giovanni di Sirio; see <http://chibios.org>) as |
||
4 | e545e620 | Thomas Schöpping | system kernel and extends it with platform specific configurations and further |
5 | functionalities and abstractions. |
||
6 | 58fe0e0b | Thomas Schöpping | |
7 | e545e620 | Thomas Schöpping | Copyright (C) 2016..2018 Thomas Schöpping et al. |
8 | 58fe0e0b | Thomas Schöpping | (a complete list of all authors is given below) |
9 | |||
10 | This program is free software: you can redistribute it and/or modify |
||
11 | it under the terms of the GNU General Public License as published by |
||
12 | the Free Software Foundation, either version 3 of the License, or (at |
||
13 | your option) any later version. |
||
14 | |||
15 | This program is distributed in the hope that it will be useful, but |
||
16 | WITHOUT ANY WARRANTY; without even the implied warranty of |
||
17 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
||
18 | General Public License for more details. |
||
19 | |||
20 | You should have received a copy of the GNU General Public License |
||
21 | along with this program. If not, see <http://www.gnu.org/licenses/>. |
||
22 | |||
23 | 074e10d7 | Thomas Schöpping | This research/work was supported by the Cluster of Excellence |
24 | Cognitive Interaction Technology 'CITEC' (EXC 277) at Bielefeld |
||
25 | University, which is funded by the German Research Foundation (DFG). |
||
26 | 58fe0e0b | Thomas Schöpping | |
27 | Authors: |
||
28 | e545e620 | Thomas Schöpping | - Thomas Schöpping <tschoepp[at]cit-ec.uni-bielefeld.de> |
29 | - Marc Rothmann |
||
30 | 58fe0e0b | Thomas Schöpping | |
31 | References: |
||
32 | 3dcad54e | Thomas Schöpping | [1] S. Herbrechtsmeier, T. Korthals, T. Schopping and U. Rückert, "AMiRo: A |
33 | modular & customizable open-source mini robot platform," 2016 20th |
||
34 | International Conference on System Theory, Control and Computing (ICSTCC), |
||
35 | Sinaia, 2016, pp. 687-692. |
||
36 | |||
37 | |||
38 | |||
39 | ################################################################################ |
||
40 | # # |
||
41 | # RRRRRRRR EEEEEEEE AAA DDDDDDDD MM MM EEEEEEEE # |
||
42 | # RR RR EE AA AA DD DD MMM MMM EE # |
||
43 | # RR RR EE AA AA DD DD MMMM MMMM EE # |
||
44 | # RRRRRRRR EEEEEE AA AA DD DD MM MMM MM EEEEEE # |
||
45 | # RR RR EE AAAAAAAAA DD DD MM MM EE # |
||
46 | # RR RR EE AA AA DD DD MM MM EE # |
||
47 | # RR RR EEEEEEEE AA AA DDDDDDDD MM MM EEEEEEEE # |
||
48 | # # |
||
49 | ################################################################################ |
||
50 | |||
51 | This file will help you to setup all required software on your system, compile |
||
52 | the source code, and flash it to the AMiRo modules. |
||
53 | |||
54 | ================================================================================ |
||
55 | 58fe0e0b | Thomas Schöpping | |
56 | CONTENTS: |
||
57 | e545e620 | Thomas Schöpping | |
58 | 1 Required software |
||
59 | 1.1 Git |
||
60 | 1.2 Bootloader & Tools |
||
61 | 1.3 System Kernel |
||
62 | 1.4 Low-Level Drivers |
||
63 | 2 Recommended software |
||
64 | 2.1 gtkterm and hterm |
||
65 | 2.2 QtCreator IDE |
||
66 | 2.3 Doxygen & Graphviz |
||
67 | 3 Building and flashing |
||
68 | 58fe0e0b | Thomas Schöpping | |
69 | 3dcad54e | Thomas Schöpping | ================================================================================ |
70 | |||
71 | |||
72 | 58fe0e0b | Thomas Schöpping | |
73 | 1 - REQUIRED SOFTWARE |
||
74 | --------------------- |
||
75 | |||
76 | e545e620 | Thomas Schöpping | In order to compile the source code, you need to install the GNU ARM Embedded |
77 | Toolchain. Since this project uses GNU Make for configuring and calling the |
||
78 | compiler, this tool is requried too. AMiRo-OS uses ChibiOS as system kernel, |
||
79 | so you need a copy of that project as well. |
||
80 | 3dcad54e | Thomas Schöpping | |
81 | |||
82 | ea4d1c60 | Thomas Schöpping | 1.1 - Git |
83 | --------- |
||
84 | |||
85 | Since all main- and subprojects are available as Git repositories, installing a |
||
86 | recent version of the tool is mandatory. |
||
87 | |||
88 | |||
89 | e545e620 | Thomas Schöpping | 1.2 Bootloader & Tools |
90 | ---------------------- |
||
91 | 3dcad54e | Thomas Schöpping | |
92 | e545e620 | Thomas Schöpping | AMiRo-OS can take advantage of an installed bootloader if such exists and |
93 | provides an interface. By default, AMiRo-BLT is included as a Git submodule and |
||
94 | can easily be initialized via the ./setup.sh script. If requried, you can |
||
95 | replace the used bootloader by adding an according subfolder in the ./bootloader |
||
96 | directory. Note that you will have to adapt the makefiles and scripts, and |
||
97 | probably the operating system as well. |
||
98 | AMiRo-BLT furthermore has its own required and recommended software tools as |
||
99 | described in its README.txt file. Follow th instructions to initialize the |
||
100 | development environment manually or use the ./setup.sh script. |
||
101 | ea4d1c60 | Thomas Schöpping | |
102 | 58fe0e0b | Thomas Schöpping | |
103 | e545e620 | Thomas Schöpping | 1.3 System Kernel |
104 | ----------------- |
||
105 | 58fe0e0b | Thomas Schöpping | |
106 | 3dcad54e | Thomas Schöpping | Since AMiRo-OS uses ChibiOS as underlying system kernel, you need to acquire a |
107 | e545e620 | Thomas Schöpping | copy of it as well. For the sake of compatibility, it is included in AMiRo-OS as |
108 | a Git submodule. It is highly recommended to use the ./setup.sh script for |
||
109 | initialization. Moreover, you have to apply the patches to ChibiOS in order to |
||
110 | make AMiRo-OS work properly. It is recommended to use the .setup.sh script for this |
||
111 | purpose. |
||
112 | If you would like to use a different kernel, you can add a subfolder in the |
||
113 | ./kernel/ directory and adapt the scripts and operating system source code. |
||
114 | |||
115 | |||
116 | 1.4 Low-Level Drivers |
||
117 | --------------------- |
||
118 | |||
119 | Any required low-level drivers for the AMiRo hardware is available in an |
||
120 | additional project: AMiRo-LLD. It is included as a Git subodule and can be |
||
121 | initialized via the ./setup.sh script. |
||
122 | 3dcad54e | Thomas Schöpping | |
123 | 58fe0e0b | Thomas Schöpping | |
124 | |||
125 | 2 - RECOMMENDED SOFTWARE |
||
126 | ------------------------ |
||
127 | |||
128 | e545e620 | Thomas Schöpping | AMiRo-OS can take advanatge of an installed bootloader, which is recommended for |
129 | the best experience. In order to use all features of AMiRo-OS it is also |
||
130 | recommended to install either the 'hterm' or 'gtkterm' application for accessing |
||
131 | the robot. To ease further development, this project offers support for the |
||
132 | QtCreator IDE. |
||
133 | 3dcad54e | Thomas Schöpping | |
134 | 58fe0e0b | Thomas Schöpping | |
135 | 2.1 - gtkterm and hterm |
||
136 | 3dcad54e | Thomas Schöpping | ----------------------- |
137 | 58fe0e0b | Thomas Schöpping | |
138 | e545e620 | Thomas Schöpping | Depending on your operating system it is recommended to install 'gtkterm' for |
139 | 3dcad54e | Thomas Schöpping | Linux (available in the Ubuntu repositories), or 'hterm' for Windows. For |
140 | e545e620 | Thomas Schöpping | gtkterm you need to modify the configuration file ~/.gtktermrc (generated |
141 | 3dcad54e | Thomas Schöpping | automatically when you start the application for the first time) as follows: |
142 | 58fe0e0b | Thomas Schöpping | |
143 | 9f224ade | Thomas Schöpping | port = /dev/ttyAMiRo0 |
144 | 58fe0e0b | Thomas Schöpping | speed = 115200 |
145 | bits = 8 |
||
146 | stopbits = 1 |
||
147 | parity = none |
||
148 | flow = none |
||
149 | wait_delay = 0 |
||
150 | wait_char = -1 |
||
151 | rs485_rts_time_before_tx = 30 |
||
152 | rs485_rts_time_after_tx = 30 |
||
153 | echo = False |
||
154 | crlfauto = True |
||
155 | |||
156 | e545e620 | Thomas Schöpping | For hterm you need to configure the tool analogously. With either tool the robot |
157 | can be reset by toggling the RTS signal on and off again, and you can access the |
||
158 | 9f224ade | Thomas Schöpping | system shell of AMiRo-OS. If you need legacy support for older version of |
159 | AMiRo-BLT, you can replace the port value by '/dev/ttyUSB0'. |
||
160 | 58fe0e0b | Thomas Schöpping | |
161 | 3dcad54e | Thomas Schöpping | |
162 | e545e620 | Thomas Schöpping | 2.2 - QtCreator IDE |
163 | ------------------- |
||
164 | 3dcad54e | Thomas Schöpping | |
165 | e545e620 | Thomas Schöpping | In order to setup QtCreator projects for the three AMiRo base modules, you can |
166 | use the provided ./setup.sh script. Further instructions for a more advanced |
||
167 | configuration of the IDE are provided in the ./tools/qtcreator/README.txt file. |
||
168 | |||
169 | |||
170 | 2.3 Doxygen & Graphviz |
||
171 | ----------------------- |
||
172 | |||
173 | In order to generate the documentation from the source code, Doxygen and |
||
174 | Graphviz are requried. It is recommended to install these tool using the |
||
175 | default versions for your system. Ubuntu users should simply run |
||
176 | >$ sudo apt-get install doxygen graphviz |
||
177 | 3dcad54e | Thomas Schöpping | |
178 | 58fe0e0b | Thomas Schöpping | |
179 | |||
180 | 3 - BUILDING AND FLASHING |
||
181 | ------------------------- |
||
182 | |||
183 | 3dcad54e | Thomas Schöpping | Each time you modify any part of AMiRo-OS, you need to recompile the whole |
184 | e545e620 | Thomas Schöpping | project for the according AMiRo module. Therefore you can use the ./Makefile by |
185 | simply executing 'make' and follow the instructions. Alternatively, you can |
||
186 | either use the makefiles provided per module in ./os/modules/<ModuleToCompile> |
||
187 | or - if you want to compile all modules at once - the makefile in the |
||
188 | ./os/modules folder. After the build process has finished successfully, you |
||
189 | always have to flash the generated program to the robot. Therefore you need an |
||
190 | appropriate tool, such as stm32flash (if you don't use a bootloader) or |
||
191 | SerialBoot (highly recommended; provided by AMiRo-BLT). Similarly to the |
||
192 | compilation procedure as described above, you can flash either each module |
||
193 | separately, or all modules at once by executing 'make flash' from the according |
||
194 | directory. |
||
195 | |||
196 | When using SerialBoot, please note that you must connect the programming cable |
||
197 | either to the DiWheelDrive or the PowerManagement module for flashing the |
||
198 | operating system. All other modules are powered off after reset so that only |
||
199 | these two offer a running bootloader, which is required for flashing. |
||
200 | 58fe0e0b | Thomas Schöpping | |
201 | 3dcad54e | Thomas Schöpping | ================================================================================ |