added bbb guide and updated rpi guide

This commit is contained in:
Robin Müller 2021-05-01 17:48:08 +02:00
parent 9f7aca0be5
commit f5f33fd194
3 changed files with 379 additions and 94 deletions

291
doc/README-bbb.md Normal file
View File

@ -0,0 +1,291 @@
<img align="center" src="./images/bbb/beagleboard-logo.png" width="30%">
<sub><sup>Image taken from [Beagle Bone website](https://beagleboard.org/logo) and used in
accordance to their trademark rules.</sup></sub>
# Getting started on the Beagle Bone Black
The FSFW can be run on a Beagle Bone Black with the Linux OSAL, using
an ARM linux (cross) compiler. Instructions will be provided on how to do this.
## General Information
The following instructions will show how to build the example on the Beagle Bone Black directly.
It will also show how to cross-compile on a host machine and mirror the Beagle Bone sysroot folder
on the host machine so that the same libraries and headers used on the BBB are used
for the cross-compilation process.
Some Eclipse project files were provided as well to help with setting up the indexer in Eclipse
more quickly.
## Prerequisites for direct compilation and cross-compiling
1. SSH connection to the Beagle Bone Black working
2. Beagle Bone Black linux environment set up properly
3. `CMake` installed
## Setting up general prerequisites for Linux systems
1. Install CMake and rsync
```sh
sudo apt-get install cmake rsync
```
2. Configure the Beagle Bone Black Linux environment. The last section of the
[Linux README](README-linux.md#top) specifies how to set up a UNIX environment for the FSFW and
is also applicable to the Beagle Bone Black. SSH into the BBB and
follow the instructions in that section.
3. Install the `gpiod` library
```sh
sudo apt-get install gpiod libgpiod-dev
```
## Getting started on the Beagle Bone Black
Make sure to follow the steps above. Now you should be able to build the software on
the Beagle Bone Black. A ssh connection to the Raspberry Pi is assumed here
You can build the software with the following commands
```sh
mkdir build-Debug-BBB
cd build-Debug-BBB
cmake -DOS_FSFW=linux -DTGT_BSP=arm/beagleboneblack -DLINUX_CROSS_COMPILE=OFF -DCMAKE_BUILD_TYPE=Debug ..
cmake --build . -j2
```
## Prerequisites for cross-compiling
These prerequisites are valid for Linux as well as Windows hosts.
1. ARM Linux cross compiler installed
2. Beagle Bone Black sysroot folder mirrored on the host machine, using `rsync`
3. gdb-multiarch installed on host for remote debugging or `tcf-agent` running on the BBB
## Cross-Compiling on a Linux Host
### Setting up prerequisites for cross-compiling
## Cross-Compiling on a Windows Host
### Additional Prerequites
1. [MSYS2](https://www.msys2.org/) installed. All command line steps shown here
were performed in the MSYS2 MinGW64 shell (not the default MSYS2, use MinGW64!).
Replace `<UserName>` with respectively. It is recommended to set up
aliases in the `.bashrc` file to allow quick navigation to the `fsfw_example`
repository and to run `git config --global core.autocrlf true` for git in
MinGW64.
### Setting up prerequisites for Windows
1. Install CMake and rsync in MinGW64 after installing MSYS2
```
pacman -S mingw-w64-x86_64-cmake rsync
```
2. Configure the Beagle Bone Black linux environment. The last section of the
[Linux REAMDE](README-linux.md#top) specifies how to set up a UNIX environment
for the FSFW and isalso applicable to the Raspberry Pi. SSH into the
Beagle Bone Black and follow the instructions in that section.
3. Install the correct [ARM Linux cross-compile toolchain](https://releases.linaro.org/components/toolchain/binaries/latest-7/).
provided by Linaro.
Test the toolchain by running:
```sh
arm-linux-gnueabihf-gcc --version
```
4. Set up a sysroot folder on the local host machine. Make sure the SSH connection to
the Raspberry Pi is working without issues. Then perform the following steps
```sh
cd /c/Users/<UserName>
mkdir beaglebone
cd beaglebone
mkdir rootfs
cd rootfs
pwd
```
Store the result of `pwd`, it is going to be used by `rsync` later.
Now use rsync to clone the Rapsberry Pi sysroot to the local host machine.
You can replace `<ip-address>` with `beaglebone.local` to use DNS.
Use the rootfs location stored from the previous steps as `<rootfs-path>`.
```sh
rsync -vR --progress -rl --delete-after --safe-links <username>@<ip-address>:/{lib,usr,opt/vc/lib} <rootfs-path>
```
5. There might be some issues with the pthread symbolic links. Navigate to the folder
containing the symlinks
```sh
cd /c/User/<UserName>/beaglebone/rootfs/usr/lib/arm-linux-gnueabihf
```
Type `more libpthread`, press `TAB` and check whether the symbolic
link `libpthread.so` is shown. If it is not, we are going to set it up
manually to avoid issues when linking against `pthread` later.
Run the following command to create a symlink to `libpthread.so.0`
```sh
ln -s ../../../lib/arm-linux-gnueabihf/libpthread.so.0 libpthread.so
```
Please note that there might also be issues with some symlinks or libraries not being copied
properly. This has occured with files like `libc.so.6`. If there are linker issues at a later
stage, you can try to rerun `rsync` without `--safe-links` or copy the shared libraries or
symlinks manually from the Raspberry Pi to the sysroot with `scp`.
For example, you can copy `libc.so.6` from the Raspberry Pi to the sysroot with
the following command
```sh
scp pi@<ip-address>:lib/arm-linux-gnueabihf/lib.so.6 <rootfs-path>/lib/arm-linux-gnueabihf
```
6. It is recommended to install `gdb-multiarch`.
This tool will allow remote debugging on the host computer. Replace
`x86_64` with the correct processor architecture for other architectures.
```sh
pacman -S mingw-w64-x86_64-gdb-multiarch
```
7. Perform the steps [in the following chapter](#cross-test) to build the
software for the Raspberry Pi and test it.
## <a id="cross-test"></a> Testing the cross-compilation
It is recommended to set the following environmental variables for the CMake build:
- `CROSS_COMPILE`: Explicitely specify the name of the cross compiler
- `RASPBIAN_ROOTFS`: Explicitely set the path to the local BBB rootfs
For example with the following commands
```sh
export CROSS_COMPILE="arm-linux-gnueabihf"
```
It is recommended to test whether the environmental variables were set correctly,
for example by running
```sh
echo $RASPBIAN_ROOTFS
```
These variables can either be set every time before a debugging session to
keep the environment clean (should be done before starting Eclipse)
or permanently by adding the `export` commands to system files.
A helper script has been provided in `cmake/scripts/BBB` to perform
setting up the environment. The scripts need to be `source`d instead of
being run like regular shell scripts.
You can also set up the environmental variables permanently by adding the
export commands to the `.profile` or `.bashrc` file in the `$HOME` folder.
On Windows, MinGW64 was used to set up the build system, so you can use the
MinGW64 `.bashrc` file to do this. If you are using Eclipse to build
the software, Eclipse will have the system variables from Windows,
so it is recommended to either permanently set the three environmental
variables in the Windows system environmental variables or add them in
Eclipse. See the [Eclipse README](README-eclipse.md#top) for more information.
Now we can test whether everything was set up properly by compiling the example
and running it on the BBB via command line. Navigate into the `fsfw_example` folder first.
1. Build the software locally to test the cross-compilation process.
A debug build directory is created first.
```sh
mkdir build-Debug-BBB
cd build-Debug-BBB
```
2. Configure the build system. On Linux, run the following command:
```sh
cmake -G "Unix Makefiles" -DOS_FSFW=linux -DTGT_BSP=arm/beagleboneblack -DLINUX_CROSS_COMPILE=ON -DCMAKE_BUILD_TYPE=Debug ..
```
On Windows, replace `-G "Unix Makefiles"` with `-G "MinGW Makefiles"`.
Alternatively, you can use the helper shell scripts located inside `cmake/scripts/BBB/crosscompile`
or the Python helper script `cmake_build_config.py` inside the `cmake/scripts` folder.
The `BBB` folder also contains template shell files which can be `source`d
to quickly set up the environmental variables if you want to keep the system path clean.
3. Run the binary to test it
```sh
scp fsfw_example <username>@beaglebone.local:/home/fsfw_example
ssh <username>@beaglebone.local
./fsfw_example
```
### Setting up Eclipse for a BBB remote target
It is recommended to use the provided Eclipse project files and
launch configurations to have a starting point. See the specific section in
the [Eclipse README](README-eclipse.md#top) for information how to do this.
#### Windows
There are some additional steps necessary on Windows: The cross-compiler by
default is configured to look for the cross-compiler in `/opt/cross-pi-gcc/bin`.
The toolchain path needs to be corrected, for example like shown in the following image:
<img align="center" src="./images/eclipse/eclipse-cross-compile-win.png" width="50%">
## Setting up the TCF agent on the BBB
It is recommended to set up a [TCF agent](https://wiki.eclipse.org/TCF) for comfortable
Eclipse remote debugging. The following steps show how to setup the TCF agent
on the Raspberry Pi and add it to the auto-startup applications. The steps are taken
from [this guide](https://wiki.eclipse.org/TCF/Raspberry_Pi)
1. Install required packages on the RPi
```sh
sudo apt-get install git uuid uuid-dev libssl-dev
```
2. Clone the repository and perform some preparation steps
```sh
git clone git://git.eclipse.org/gitroot/tcf/org.eclipse.tcf.agent.git
cd org.eclipse.tcf.agent.git/agent
```
3. Build the TCF agent
```sh
make
```
and then test it by running
```sh
obj/GNU/Linux/arm/Debug/agent S
```
4. Finally install the agent for auto-start with the following steps. And set it up for
auto-start.
```sh
cd org.eclipse.tcf.agent/agent
make install
sudo make install INSTALLROOT=
sudo update-rc.d tcf-agent defaults
```
The [Eclipse README](README-eclipse.md#top) specifies how to perform remote
debugging using the TCF agent.

View File

@ -1,39 +1,41 @@
<img align="center" src="./images/rpi/RPi-Logo-Landscape-Reg-PRINT.png" width="30%"> <img align="center" src="./images/rpi/RPi-Logo-Landscape-Reg-PRINT.png" width="30%">
<sub><sup>Image taken from [Raspberry Pi website](https://www.raspberrypi.org/trademark-rules/). Raspberry Pi is a trademark of the Raspberry Pi Foundation</sup></sub> <sub><sup>Image taken from [Raspberry Pi website](https://www.raspberrypi.org/trademark-rules/).
Raspberry Pi is a trademark of the Raspberry Pi Foundation</sup></sub>
# Getting started on the Raspberry Pi # Getting started on the Raspberry Pi
The FSFW can be run on a Raspberry Pi with the Linux OSAL, using The FSFW can be run on a Raspberry Pi with the Linux OSAL, using
an ARM linux cross compiler. Instructions will be provided on how an ARM linux (cross) compiler. Instructions will be provided on how
to do this. to do this.
## General Information ## General Information
The following instructions will show how to install the cross compiler on The following instructions will show how to build the example on the Raspberry Pi directly.
a host machine and mirror the Rapsberry Pi sysroot folder on the host machine It will also show how to cross-compile on a host machine and mirror the Raspberry Pi sysroot folder
so that the same libraries and headers used on the Raspberry Pi are used on the host machine so that the same libraries and headers used on the RPi are used
for the cross-compilation process. The provided Eclipse project files for the cross-compilation process.
and launch configurations also provide a starting point to perform
remote debugging on a Raspberry Pi, using a SSH connection. Some Eclipse project files were provided as well to help with setting up the indexer in Eclipse
more quickly.
## Prerequisites for direct compilation and cross-compiling ## Prerequisites for direct compilation and cross-compiling
1. SSH connection to the Raspberry Pi working 1. SSH connection to the Raspberry Pi working
2. Raspberry Pi linux environment set up properly 2. Raspberry Pi linux environment set up properly
3. CMake and rsync installed 3. `CMake` installed
## Setting up general prerequisites for Linux systems ## Setting up general prerequisites for Linux systems
1. Install CMake and rsync 1. Install `CMake` and `rsync`
```sh ```sh
sudo apt-get install cmake rsync sudo apt-get install cmake rsync
``` ```
2. Configure the Raspberry Pi Linux environment. The last section of the 2. Configure the Raspberry Pi Linux environment. The last section of the
[Linux REAMDE](README-linux.md#top) specifies how to set up a UNIX environment for the FSFW and is [Linux README](README-linux.md#top) specifies how to set up a UNIX environment for the FSFW and
also applicable to the Raspberry Pi. SSH into the Raspberry Pi and is also applicable to the Raspberry Pi. SSH into the Raspberry Pi and
follow the instructions in that section. follow the instructions in that section.
3. Install the `gpiod` library 3. Install the `gpiod` library
@ -62,9 +64,7 @@ These prerequisites are valid for Linux as well as Windows hosts.
1. ARM Linux cross compiler installed 1. ARM Linux cross compiler installed
2. Raspberry Pi sysroot folder mirrored on the host machine, using `rsync` 2. Raspberry Pi sysroot folder mirrored on the host machine, using `rsync`
3. gdb-multiarch installed on host for remote debugging or TCF agent running on Raspberry Pi 3. gdb-multiarch installed on host for remote debugging or `tcf-agent` running on Raspberry Pi
## Cross-Compiling on a Linux Host ## Cross-Compiling on a Linux Host
@ -76,7 +76,6 @@ based on Debian buster is used. If this is not the case, it is recommended to
follow the steps in the stackoverflow post above and to make sure that the follow the steps in the stackoverflow post above and to make sure that the
toolchain binaries are added to the path accordingly. toolchain binaries are added to the path accordingly.
### Setting up prerequisites for cross-compiling ### Setting up prerequisites for cross-compiling
1. Install the pre-built ARM cross-compile with the following command 1. Install the pre-built ARM cross-compile with the following command
@ -105,7 +104,6 @@ toolchain binaries are added to the path accordingly.
arm-linux-gnueabihf-gcc --version arm-linux-gnueabihf-gcc --version
``` ```
2. Set up a sysroot folder on the local host machine. Make sure the SSH connection to 2. Set up a sysroot folder on the local host machine. Make sure the SSH connection to
the Raspberry Pi is working without issues. Then perform the following steps the Raspberry Pi is working without issues. Then perform the following steps
@ -260,7 +258,6 @@ export RASPBERRY_VERSION="4"
export RASPBIAN_ROOTFS="<pathToRootFS>" export RASPBIAN_ROOTFS="<pathToRootFS>"
``` ```
It is recommended to test whether the environmental variables were set correctly, It is recommended to test whether the environmental variables were set correctly,
for example by running for example by running
@ -268,7 +265,6 @@ for example by running
echo $RASPBIAN_ROOTFS echo $RASPBIAN_ROOTFS
``` ```
These variables can either be set every time before a debugging session to These variables can either be set every time before a debugging session to
keep the environment clean (should be done before starting Eclipse) keep the environment clean (should be done before starting Eclipse)
or permanently by adding the `export` commands to system files. or permanently by adding the `export` commands to system files.
@ -333,7 +329,6 @@ The toolchain path needs to be corrected, for example like shown in the followin
<img align="center" src="./images/eclipse/eclipse-cross-compile-win.png" width="50%"> <img align="center" src="./images/eclipse/eclipse-cross-compile-win.png" width="50%">
## Setting up the TCF agent on the Raspberry Pi ## Setting up the TCF agent on the Raspberry Pi
It is recommended to set up a [TCF agent](https://wiki.eclipse.org/TCF) for comfortable It is recommended to set up a [TCF agent](https://wiki.eclipse.org/TCF) for comfortable
@ -351,7 +346,6 @@ from [this guide](https://wiki.eclipse.org/TCF/Raspberry_Pi)
```sh ```sh
git clone git://git.eclipse.org/gitroot/tcf/org.eclipse.tcf.agent.git git clone git://git.eclipse.org/gitroot/tcf/org.eclipse.tcf.agent.git
cd org.eclipse.tcf.agent.git/agent cd org.eclipse.tcf.agent.git/agent
cp -R machine/arm machine/armv6l
``` ```
3. Build the TCF agent 3. Build the TCF agent
@ -362,11 +356,11 @@ from [this guide](https://wiki.eclipse.org/TCF/Raspberry_Pi)
and then test it by running and then test it by running
```sh ```sh
obj/GNU/Linux/armv6l/Debug/agent S obj/GNU/Linux/arm/Debug/agent S
``` ```
4. Finally instal lthe agent for auto-start with the following steps. The last step 4. Finally instal lthe agent for auto-start with the following steps and set it up for auto-start.
did not work on a Rapsberry Pi 4, but apparentely was not necessary. The last step did not work on a Rapsberry Pi 4, but apparentely was not necessary.
```sh ```sh
cd org.eclipse.tcf.agent/agent cd org.eclipse.tcf.agent/agent

Binary file not shown.

After

Width:  |  Height:  |  Size: 67 KiB