1. Introduction
The NXP HCP Toolbox enables automatic code generation for applications prototyping from Simulink for NXP’s S32G2xx and S32S2xx MPUs.
This article details the steps to build, deploy, and run the HEV demo on S32G2xx, and also collect telemetry data using AWS IoT Greengrass.
2. Hardware overview
The following hardware components are needed for running the HEV demo:
- an S32G274A RDB2 Evaluation Board
Configure the evaluation board to boot from the SD card.
- a microSD card
We'll flash and boot the GoldVIP Linux from this card
- a micro USB cable
Connect the cable to the UART0 port and your host machine. This connection will be shown in Windows as a serial port and we'll use it to connect from a terminal emulator for the initial Linux setup.
- two Ethernet cables
Connect another Ethernet cable to the P3A port and to your LAN network. This connection will be used for AWS data telemetrics.
Connect one Ethernet cable to the P3B port and to your LAN network. This connection will be used for PIL communication between MATLAB and the application running on the board.
- a Logitech F310 or compatible gamepad
Connect the gamepad to your host machine before opening the HEV model. We'll use it to drive the car in the virtual 3D environment: to steer, accelerate, and brake.
The following figure shows the USB, UART, CAN and power connectors on the S32G2 RDB2 evaluation board.
The following figure shows the Ethernet connectors on the S32G RDB2 evaluation board.
3. Software overview
To run the HEV demo we must perform the following steps to install the required software.
3.1 Mathworks MATLAB and Add-Ons
Install the following software from Mathworks required to build and run any model that uses the NXP Model-Based Design Toolbox for HCP :
- MATLAB 2020a or newer
- MATLAB Embedded Coder, the key component that allows us to generate the C code that will be cross-compiled to be executed on the target
- Embedded Coder Support Package for ARM Cortex-A Processors
Install the following additional toolboxes from Mathworks required to build and run the HEV demo:
- Powertrain Blockset
- Vehicle Dynamics Blockset
- Automated Driving Toolbox
- Simulink 3D Animation
- Mapping Toolbox
All these toolboxes can be installed from MATLAB, by opening Get Add-Ons window and searching for each of these toolboxes.
3. 2 NXP Model-Based Design for HCP Toolbox
Install NXP MBDT HCP Toolbox to add the HCP target support to the MATLAB environment to allow code generation and deployment.
Following are the steps to install NXP’s Model-Based Design Toolbox for HCP Series of MPUs:
1. Go to nxp.com and sign in to your NXP account.
If you don't have an NXP account, create one from the Registration page. Toolbox is for free but an account is required to download the tool and access training & support on NXP Model-Based Design Toolbox Community).
2. Go to NXP Model-Based Design Toolbox (MBDT) page, select the DOWNLOADS tab and press the Download page, which will open the Model-Based Design Toolbox download page.
3. From the Model-Based Design Toolbox download page select the Model-Based Design Toolbox for HCP 1.0.0, and then on the next page, you will be asked if you agree to the Software Terms and Conditions.
4. On the Model-Based Design Toolbox for HCP download page, download the following files:
- SW32_MBDT_HCP_1.0.0_EAR_D2111.mltbx, the toolbox installer
- MBDToolbox_HCP_1.0.0_S32S2xx_Tools.zip, the S32G2xx build toolchain
Some browsers will download the .mltbx file as .zip file. To avoid that, please press right click on the download link and select Save link as.
5. Open MATLAB, navigate to where you downloaded the toolbox installer, and run the installer (press double click or right-click and select Install).
6. After a few minutes (~4-5min), the NXP’s Model-Based Design Toolbox should be visible as a new add-on in the Add-On Manager.
7. The Model-Based Design Toolbox uses the toolchain mechanism exposed by the Simulink to build the code generated with Embedded Coder toolbox. By default, the toolchain is configured for the MATLAB R2020a / R2020b / R2021a releases. For any other MATLAB release, the user needs to execute a toolbox m-script to generate the appropriate settings for his/her installation environment.
This is done by running the mbd_hcp_path.m script.
>> mbd_hcp_path
No compatible target currently available for NXP S32G2xx. Creating one..
Creating folders for the target 'NXP S32G2xx' in the folder 'C[…]\NXP_MBDToolbox_HCP\mbdtbx_hcp\codertarget\2021b\s32g2'...
Creating the framework for the target 'NXP S32G2xx'...
Registering the target 'NXP S32G2xx'...
Done.
No compatible target currently available for NXP S32S2xx. Creating one..
Creating folders for the target 'NXP S32S2xx' in the folder 'C[…]\NXP_MBDToolbox_HCP\mbdtbx_hcp\codertarget\2021b\s32s2'...
Creating the framework for the target 'NXP S32S2xx'...
Registering the target 'NXP S32S2xx'...
Done.
Successful.
3.3 Gold Vehicle Integration Platform (GoldVIP)
In the case of S32G2 at the start of the PIL simulation a Linux application is cross-build on the MATLAB host machine, deployed to the evaluation board via SSH, and executed inside a Linux operating system running on that board.
We'll use the Linux image from Gold Vehicle Integration Platform (GoldVIP) package that supports telemetry to cloud using AWS IOT Greengrass. Telemetry statistics are fetched from the device, calculated and sent to the cloud counterpart of the application. Statistics received in the cloud are then displayed into user-friendly graphs. The statistics include but may not be limited to: Networking accelerator usage statistics, Realtime cores load, Domain-0 VCPU load and Domain-0 Memory utilization statistics.
The GoldVIP is a reference software platform for a vehicle service-oriented gateway running on NXP vehicle network processors like the S32G274A.
Following figure shows the GoldVIP high-level architecture.
NOTE: GoldVIP is available upon NXP approval as an Early Access Release. Please contact your NXP sales representative for more information.
Once you get the approval, go to the GoldVIP download page and download the following files:
- GoldVIP-0.11.0-binaries.zip
- GoldVIP-0.11.0_User-Manual.pdf
Next we unzip the GoldVIP-0.11.0-binaries.zip archive and we'll find the Linux image fsl-image-goldvip-s32g274ardb2.sdcard in GoldVIP-0.11.0-binaries\binaries folder.
5. Toolbox setup
NXP Model-Based Design Toolbox for HCP offers a Setup GUI to select which toolchain to use, flash the Linux image card, configure and test the network connection.
After the installation of the toolbox has finished the GettingStarted.mlx file is opened.
To run it go to the LIVE EDITOR tab and push the Run button. Running it will open the Setup GUI that will help you configure the toolbox.
5.1 Select Target
We are going to select S32G274A and push the Next button.
5.2 Setup Toolchain
Select I need to acquire the toolchain and push the Next button. In case you already have the toolchain the steps are a subset of the one below.
5.3 Download Toolchain
Next download the S32G2xx toolchain by following the steps from 3.2, step 4, if you haven't already done so, and then select the path to the downloaded toolchain archive.
Then select the folder to where the archive should be unzipped.
Next press the Unzip button to unzip the selected toolchain archive. This step will take around 10 minutes.
If the toolchain archive is unzipped successfully, the Next button is enabled.
5.4 Validate build toolchain
Select the toolchain folder using the Browse button to verify it.
Push the Validate button. If everything is alright the message is Toolchain is valid, otherwise the message is Toolchain is not valid. If the toolchain is valid the Next button is enabled and should be pushed to continue the configuration
5.5 Write Linux on the microSD card
This page helps you to write the Linux on a microSD card. First, insert the microSD card, then push the Refresh button to actualize the drive list. If the microSD is available in Windows the list should be not empty. Select a drive from the list and push the Next button.
Select the Linux image using the Browse button.
Finally, push the Write button to write the Linux image.
5.6. Get additional software
In order to connect to the S32G2 board we'll need to install additional software. You can use Terminal Emulator familiar to you, such as Tera Term, Putty or other. Also install FTDI CDM WHQL driver for serial configuration from FTDI chip, otherwise you will not be able to connect to the board using the serial port.
5.7 Connect Hardware
Connect the board using the following instructions:
1. Remove the memory card from the host computer and insert into the S32G2 board micro SD card slot.
2. Connect two Ethernet cables to S32G2 board, one to P3A port and another one to P3B port. Connect the other ends of the cables to your LAN or HOME network.
3. Connect an USB cable between the UART0 port on the S32G2 board and your host computer.
4. Connect the 12 V power supply to the S32G2 board and power on the board.
5. Open the terminal emulator (e.g. putty) to connect to the board and configure the network settings.
Select the serial port added to Ports (COM & LPT) in Device Manager when the micro USB cable is connect to the host machine, and select 115200 as the baud rate.
If you didn't install the FTDI driver in the previous steps, a new COM port will not be added when you connect the USB cable.
Once you connect over the serial to the board, you will be asked to log into Linux in the terminal emulator. The default username is root, without a password.
If your network assigns IP address automatically via DHCP, you don't need to do any network configuration on Linux. Otherwise, you will have to configure the network settings for pfe2 interface.
Run ifconfig pfe2 to get the IP address that we'll use for PIL simulation. The field that we are looking for is inet, and in the bellow output the IP address is 192.168.2.152.
root@s32g274ardb2:~# ifconfig pfe2
pfe2: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
inet 192.168.2.152 netmask 255.255.255.0 broadcast 192.168.2.255
inet6 fe80::6da:49da:68c3:24d9 prefixlen 64 scopeid 0x20<link>
ether 00:01:be:be:ef:33 txqueuelen 1000 (Ethernet)
RX packets 190 bytes 14318 (13.9 KiB)
RX errors 0 dropped 0 overruns 0 frame 0
TX packets 186 bytes 18928 (18.4 KiB)
TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
device memory 0x46000000-46ffffff
Copy this IP address as we'll need it in the next step of the toolbox setup.
5.8. Setup network connection
Fill in the Device Address, Username, Password, and Download folder, and then push the Test Connection button. This tests if the device address is valid, and also if the a SSH commands can be run.
For the Device Address use the IP address copied from the output of ifconfig pte2. Default username is root, and no password is set. Default download folder is the home folder of the root use, /home/root.
5.9. Setup done
Congratulations! You are ready to use the Model-Based Design for HCP toolbox.
Note: Press the Finish button to save the toolchain path and network connection settings.
7. GoldVIP setup
By default, the GoldVIP deliverable includes Xen hypervisor. Xen is a type 1 hypervisor (bare metal) that makes possible running multiple instances of the same operating system seamlessly on the hardware. Xen allows creation of virtual machines from the command line or automatically at startup. Xen virtualizes CPUs, memory, interrupts and timers, providing virtual machines with virtualized resources.
Two types of virtual machines are defined by Xen:
- Privileged (Dom0 or Domain-0): The first machine that runs natively on the hardware and provides access to the hardware for unprivileged domains.
- Unprivileged (DomUs): Virtual machines spawned by Dom0. These machines use the hardware resources allocated from the privileged domain (CPU, Memory, Disk, Network).
In the GoldVIP, two virtual machines are started by default, before the user logs in:
- Domain-0, which has access to all the system resources and creates a network bridge for the unprivileged guest. This bridge, namely xenbr0 is the network interface that forwards packets to the DomU;
- v2xdomu, unprivileged domain, which has access only to a limited number of resources.
The HEV demo will run in Domain-0, in the privileged domain.
Telemetry data is collected from Domain-0 and passed to v2xdomu through a TCP client-server communication.
To switch to v2xdomu type: xl console v2xdomu
The username on the v2xdomu is root without a password.
To exit from v2xdomu press Ctrl + ]
7. AWS setup
7.1 Prerequisites
You will need an AWS account with SSO enabled. Follow the steps in this guide to enable SSO: https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html
Enabling SSO will grant you access to the SSO console. SSO is also required to use the SiteWise Dashboard.
7.2 AWS IAM Permissions
A policy for an AWS IAM user, it contains the necessary permissions for the deployment and use of the telemetry use case:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"cloudformation:*",
"cloudwatch:*",
"iot:*",
"lambda:*",
"logs:*",
"s3:*",
"greengrass:*",
"sns:*",
"iotsitewise:*",
"iam:*",
"sso:*",
"sso-directory:*"
],
"Resource": "*"
}
]
}
AWS IAM documentation: https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_
create-delegated-user.html
7.3 Deployment of the Telemetry Stack in AWS
1. Go to the AWS SAR console: https://console.aws.amazon.com/serverlessrepo/
2. Go to Available applications tab; then to Public applications and search for goldvip.
3. Check Show apps that create custom IAM roles or resource policies to see the application.
4. Click on nxp-goldvip-telemetry. You can modify the application parameters.
5. Check I acknowledge that this app creates custom IAM roles.
6. Click Deploy. The deployment will take a few minutes. You will be redirected to another page.
The name of the stack is on the top of the page, starting with serverlessrepo-, if you changed the application name you will need this name in the next step. You can go to the Deployments tab and see the status of the deployment.
Wait for the status to change from Create in progress to Create complete. Note: you may need to
refresh the page to see the status change.
This CloudFormation stack creates on your account:
- A Greengrass V2 telemetry component, this is a python function which runs on v2xdomu and sends data to AWS IoT Core. The provisioning script described in chapter 7.4. Connecting the board to AWS creates a Greengrass V2 continuous deployment which will run the telemetry component on your board.
- A SiteWise Portal with multiple Dashboards; after the board is connected to AWS a live visual representation of the telemetry data received via the Greengrass V2 component is displayed in these.
7.4. Connecting the board to AWS
1. Log into the v2xdomu virtual machine using the command: xl console v2xdomu
2. Configure environment variables for Greengrass provisioning script:
From the v2xdomu console, set the AWS credentials as environment variables:
$ export AWS_ACCESS_KEY_ID=<access key id>
$ export AWS_SECRET_ACCESS_KEY=<secret access key>
One way of obtaining your AWS credentials is the following:
From the AWS SSO console select your account and retrieve the environment variables by clicking on Command line or programmatic access. From section macOS and Linux copy the variables and paste them on your board. Use Option 1: set the AWS credentials as environment variables.
Please check the AWS documentation for additional information: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html
Note:
- IAM credentials should never be used on a device in production scenario.
- These variables are temporary and are erased at reboot.
3. Run the Greengrass provisioning script on your board:
$ python3 ~/cloud-gw/greengrass_provision.py --stack-name <stack-name> --region-name <region-name>
Where <stack-name> is the name of the deployed stack. If you did not change the application name you do not need to specify this parameter. In <region-name> put the region you have selected from the supported ones: us-west-2 or eu-west-1.
This will setup the network interface, start the Greengrass V2 Nucleus, and create a Greengrass V2 continuous deployment, which will run the telemetry component created by the Telemetry Stack.
Note: the provisioning script will try to setup the internet connection using the eth0 network interface by default.
To get more details about the script parameters use:
$ python3 ~/cloud-gw/greengrass_provision.py -h
The board is now connected to your AWS account and it will begin to send telemetry data.
7.6. Accessing the SiteWise dashboard
1. Go to the SiteWise console: https://console.aws.amazon.com/iotsitewise/
2. Click on Portals from the list on the left.
3. Click on the name of your portal, it starts with SitewisePortal_serverlessrepo.
4. Click on Assign administrators.
5. Add your account and any other you want to have access to the SiteWise Dashboard.
6. Click Assign administrators.
7. Click on the Portal’s Url (or Link).
8. Close the Getting started pop up window.
9. Click on one of the dashboards to visualize the telemetry.
You will now see the live telemetry data from your board.
For more information check the GoldVIP User Manual.
8. Running HEV demo
1. A Logitech F310 gamepad is needed to control the car. Connect the gamepad before opening the model.
2. We recommend to make a copy of the HEV demo folder from HCP toolbox in another working folder.
Run the following command in Matlab to navigate to S32G2xx examples folder.
cd(fullfile(mbd_find_hcp_root(), 'HCP_Examples', 's32g2')
Copy the HEV_P4_Ext_TV to another working folder, e.g. C:\workspace\.
3. Open the HEV_P4_ExternalDriver_v3_TV_v4_fixedStep.slx model.
The HEV demo is already configured for PIL simulation mode.
3. Run the PIL simulation by pressing the Start button from . Simulink generates the code for the model, compiles it, downloads it on the board, and then starts the simulation.
