Getting Started

This page documents the steps needed to run the Safety Island Actuation Demo with the Primary Compute on an AVA Developer Platform, connected over Ethernet to the Safety Island on an S32Z development board.

Note

All command examples on this page from the HTML document format can be copied by clicking the copy button. In the PDF document format, be aware that special characters are added when lines get wrapped.

Requirements

Hardware

Software

S32Z setup

Hardware setup

Note

The S32Z board exists in two different hardware versions. Its Power Management Integrated Circuit (PMIC) can either be the PF71 or the PF5030, which implies different jumper settings. The variant of the S32Z board documented here has the PMIC PF5030 installed.

The jumpers on the board are on:

JP4     1-2
J13     5-6
J15     5-6
J19     5-6
J21     7-8
J23     7-8
J28     2-3
J32     1-3 2-4
J37     1-2 4-5 7-8 10-11
J38     1-2 4-5 7-8 10-11
J62     1-2 3-4 5-6 7-8
J65     2-3 5-6 8-9 11-12
J66     2-3 5-6 8-9 11-12
J68     2-3 5-6 8-9 11-12
J121    1-2
J122    1-2
J123    2-3
J124    2-3
J125    1-2
J130    2-3
J131    1-2
J132    2-3 5-6 8-9 11-12
J134    1-2 4-5 7-8 10-11 13-15
J135    1-2
J244    3-5 4-6
J247    1-2
J248    2-3
J249    2-3

The RCON switches are configured as (0 for OFF, 1 for ON):

SW4      SW7      SW5      SW6
00110000 00001010 00000000 00000000

The development board is connected to:

  • the network, through its Ethernet port

  • the S32 Debug Probe, through its JTAG connector (J134)

  • a workstation, over UART, through its USB port (J119, not J137)

    • 115200 of baud rate

    • prints the actuation commands generated by the application

  • the power, through 12V in

Software setup

Follow the instructions provided with the software listed in the Software paragraph to install it and to set it up. Note that the S32 Design Studio needs a graphical user interface in order to be installed and used. The instructions in this page assume that the S32 Design Studio gets installed on a Linux machine.

Note that once the S32 Design Studio is installed, documentation for the S32 Debug Probe can be found under S32DS/tools/S32Debugger/Debugger/Docs from the root of the installation directory.

Install the dependencies for running the debugger. A curated and updated version of the required installation steps for our use case (derived from the “Installation prerequisites for Linux platforms” paragraph of the installation guide found under S32DS/help/pdf from the root of the installation directory) is as follows:

$ sudo apt update
$ sudo apt install --no-install-recommends python2-minimal libpython2.7 libx11-6 libusb-1.0-0 libxss1 libxft2 curl ca-certificates
$ curl https://bootstrap.pypa.io/pip/2.7/get-pip.py --output get-pip.py
$ python2 get-pip.py
$ ${HOME}/.local/bin/pip2 install enum34

Install the “S32Z2/E2 development package” extension to the S32 Design Studio, in order to support flashing the S32Z board. This can be done in the S32 Design Studio IDE, from “Help” -> “S32DS Extensions and Updates” at the top.

Note

This guide was validated with the following versions of the software:

  • GDB Client for Arm Embedded Processors 12.1 Build 1702

  • GNU ARM PEMicro Interface Debugging Support 5.7.6

  • NXP GCC for Arm Embedded Processors Build 1620

  • NXP GCC for Arm Embedded Processors v10.2 build 1728

  • S32 Design Studio Platform package 3.5.8

  • S32 Design Studio Platform Tools package 3.5.8

  • S32Z2/E2 development package 3.5.6

AVA Developer Platform setup

EWAOL installation

The following instructions are derived from the EWAOL documentation.

Download and Build

On a workstation running Linux (validated on an x86_64 machine with Ubuntu 20.04 and 200GB of free disk space), install the build tools by following the Build Host Environment Setup paragraph of the EWAOL documentation.

Clone the meta-ewaol repository and checkout the kirkstone-dev branch:

$ git clone https://gitlab.com/soafee/ewaol/meta-ewaol.git -b kirkstone-dev
$ cd meta-ewaol

Build for the AVA Developer Platform with ~60GB of extra disk space:

$ EWAOL_ROOTFS_EXTRA_SPACE=60000000 kas build --update meta-ewaol-config/kas/baremetal.yml:meta-ewaol-config/kas/ava.yml

Note that at the time of writing, the EWAOL build was validated with:

meta-adlink-ampere   = "kirkstone:2cd61ca517a4866947d4a4d3dddcf93ce7be916f"
meta-filesystems
meta-networking
meta-oe
meta-python          = "kirkstone:402affcc073db39f782c1ebfd718edd5f11eed4c"
meta-virtualization  = "kirkstone:88327090d26955a678c6f8bd2585aad4d802f6c4"
meta
meta-poky            = "HEAD:51f801195652d518e31f9a6c1e9a07f7f1b67d36"
meta-ewaol-bsp
meta-ewaol-distro    = "HEAD:9bfd34b22cbbade94b111f088220441f7c54c59f"

Deploy

Follow the steps in the “AVA” deployment paragraph of the EWAOL documentation to flash the generated image onto the AVA Developer Platform, by following the “Baremetal distribution image” (non-SDK) choices.

Run

Login as ewaol.

X11 forwarding

Installation

In order to use the rviz2 visualization software with the AVA Developer Platform when working over SSH, X11 forwarding needs to be enabled. To do this, follow the steps below.

Get into an Ubuntu container:

$ docker run -it --name x11docker ubuntu:20.04

Inside this container, get the necessary X11-related packages:

Note

The following warning lines are expected: W: Download is performed unsandboxed as root as file '[...]' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied).

# apt update
# extract_to="./xauth"; \
>   pkgs=(libxmuu1 xauth libxext6); \
>   for pkg in "${pkgs[@]}"; do apt-get download $pkg; dpkg-deb -x ${pkg}*.deb ${extract_to}; done
# exit

Now outside the docker container, install the files from those packages:

$ docker cp x11docker:/xauth .
$ docker rm x11docker
$ sudo cp -rv ./xauth/usr/bin/* /usr/bin/
$ sudo cp -rv ./xauth/usr/lib/aarch64-linux-gnu/* /usr/lib/
$ rm -r ./xauth/

SSH connection

Identify the IP of the AVA Developer Platform with:

$ ifconfig enP4p4s0 | grep inet

Connect to the AVA Developer Platform from a Linux machine with (replacing ${TARGET_IP} with the actual address from the previous step):

$ ssh -X ewaol@${TARGET_IP}

Swap file

Some Autoware packages require a lot of RAM to build. Add 20GB of swap memory in addition to the 32GB of RAM with:

$ sudo fallocate -l 20G /swapfile
$ sudo chmod 600 /swapfile
$ sudo mkswap /swapfile
$ sudo swapon /swapfile

Actuation Demo

Dependencies

The Actuation Demo repository hosts a Dockerfile for building a docker image, which contains Zephyr dependencies (adapted from the Zephyr documentation) and the Zephyr SDK. Copy the Dockerfile to the AVA Developer Platform and build a docker image:

$ wget -O /home/ewaol/Dockerfile https://gitlab.arm.com/automotive-and-industrial/safety-island/actuation-demo/-/raw/v2.0/Dockerfiles/Dockerfile
$ docker build --tag actuation_zephyr-image --file /home/ewaol/Dockerfile /home/ewaol/

Create a docker container from the docker image built by the previous step and setup the repository:

Note

The SSH connection section needs to have been followed first for the X11-related files to have been created.

$ docker run -it -v $(pwd):$(pwd) -w $(pwd) --net host -v /tmp/.X11-unix:/tmp/.X11-unix:rw -v ${HOME}/.Xauthority:${HOME}/.Xauthority:rw -e XAUTHORITY=${HOME}/.Xauthority -e DISPLAY=${DISPLAY} actuation_zephyr-image
$ git clone https://gitlab.arm.com/automotive-and-industrial/safety-island/actuation-demo.git -b v2.0
$ cd actuation-demo
$ git submodule init
$ git submodule update

Install Zephyr-specific dependencies:

$ pip3 install -r zephyr/scripts/requirements-base.txt
$ west init -l zephyr_app
$ west update
$ west zephyr-export

Build

Build all the components:

$ ./build.sh

The resulting Zephyr binary is located at build/zephyr_app/zephyr/zephyr.elf.

S32Z run

Copy the elf file generated in the previous step to the workstation where the S32 Design Studio IDE is installed.

On that workstation, set the path to the S32 Design Studio installation directory ($HOME/NXP/S32DS.3.5 when installed with the default values) to the S32DS_PATH variable, the path to the S32 Debug Probe (its IP address or its hostname in case of an Ethernet connection, or its serial ID in case of a USB connection) to the PROBE_PATH variable, and the path to the copied elf file to the ELF_PATH variable:

$ export S32DS_PATH=...
$ export PROBE_PATH=...
$ export ELF_PATH=...

Launch the GDB server (in the background) and client in order to load the binary to the S32Z board’s memory and start the execution:

$ ${S32DS_PATH}/S32DS/tools/S32Debugger/Debugger/Server/gta/gta -p 45000 &
$ ${S32DS_PATH}/S32DS/tools/gdb-arm/arm32-eabi/bin/arm-none-eabi-gdb-py -ex "py _PROBE_IP=\"s32dbg:${PROBE_PATH}\"" -ex "py _JTAG_SPEED=16000" -ex "py _GDB_SERVER_PORT=45000" -ex "py _CORE_NAME=\"S32Z270_R52_0_0_LS\"" -ex "py _SOC_NAME=\"S32Z270\"" -ex "source ${S32DS_PATH}/S32DS/tools/S32Debugger/Debugger/scripts/s32z2e2/s32z2e2_generic_bareboard.py" -ex "py board_init()" -ex "py core_init()" -ex "file ${ELF_PATH}" -ex load --batch

Note that the server running in the background will terminate when the client session closes.

Note that the expected output includes potential warning: No executable has been specified and Program received signal SIGINT, Interrupt. lines. It is expected to finish with lines similar to:

Start address 0x3211bc64, load size 1004330
Transfer rate: 106 KB/sec, 11956 bytes/write.
[Inferior 1 (Remote target) detached]

AVA Developer Platform run

Note

The following steps need to be executed with X11 forwarding. See the SSH connection paragraph.

On the AVA Developer Platform, inside the previously created Docker container, set up the execution environment:

Note

If needed, see the docker exec documentation on how to attach to a running container.

$ cd /home/ewaol/actuation-demo
$ source install/setup.bash
$ export ROS_DOMAIN_ID=1
$ export CYCLONEDDS_URI=$(pwd)/cyclonedds.xml

Note

The ROS Domain IDs 1 and 2 are expected not to be used by other machines on the sub-network.

Set up the demo by following the Preparation paragraph of the Autoware documentation.

Run the demo with:

$ ros2 launch actuation_demos planning_simulator.launch.xml map_path:=$HOME/autoware_map/sample-map-planning vehicle_model:=sample_vehicle sensor_model:=sample_sensor_kit

Note

Periodic error logs are expected from this command.

By default, it launches rviz2 for visualization.

Follow steps 2 to 4 in order to interact with the simulator and run the demo.

Note

The steering wheel overlay may look oversized due to X11 forwarding.