The USB STLK port is located to the right of the MXCHIP WiFi module in the figure. It is used for power supply, programming, debugging, and interacting with the application via UART over USB.
Depending on the board revision in use, you may need to update the wifi firmware for your board. For more information, visit the EMW3080 page on the ST Microelectronics website.
--imap lfcrlf --omap crcrlfUsing your platform’s package manager, install the following prerequisites: - Python 3.10 with pip - perl - cmake - git
There are many options for downloading and installing packages on windows. Use the approach you are most comfortable with.
Windows has a wide variety of unix or posix-like shells available. This guide will assume you are using GitBash which is included in the git for windows package.
Download and install the latest version of each of the following packages: - python (with pip) - perl - cmake - git
With scoop package manager installed, run the following command from your preferred shell.
scoop install python cmake perlWith chocolatey installed, run the following commands from your preferred shell.
choco install cmake
choco install wget
choco install git
choco install python3
choco install perlOn windows, long path names can present problems with some programs that utilize legacy APIs. Enable long path support in git so that git knows long paths are supported by STM32CubeIDE and the included toolchain.
Open GitBash or a similar unix-like shell environment and run the following command:
git config --system core.longpaths trueIn order to use the stm32u5_tool.sh script and the related STM32CubeIDE launch files, you must include bash.exe in your system path.
Locate your preferred version of bash.exe and determine the windows path to it.
For reference, the default location for GitBash is
C:\Program Files\Git\bin.
Run the following command to open the environment variable editor from Control Panel:
rundll32 sysdm.cpl,EditEnvironmentVariablesSelect the “Path” user environment variable and click “Edit”.
Select “New” and then paste the path to the directory containing bash.exe found above.
Press OK and OK to exit the environment variable editor.
Log out of your windows session and then log back in to allow the environment variable changes to take effect.
Install dependencies using your distribution’s package manager:
sudo apt install build-essential cmake python3 git libncurses5 libusb-1.0-0-devsudo dnf install -y cmake python3 git ncurses-libs libusb
sudo dnf groupinstall -y "Development Tools" "Development Libraries" --skip-brokenInstall the hombrew package manager from brew.sh
brew install python cmake git libusb greadlink coreutilssudo ln -s /usr/local/Cellar/coreutils/9.0_1/bin/realpath /usr/local/bin/realpath
sudo ln -s /usr/local/Cellar/coreutils/9.0_1/bin/readlink /usr/local/bin/readlinkUnzipping the contents of the X-CUBE-AWS package downloaded from www.st.com replaces this “clone” step.
Follow the instructions to Create an IAM user.
Run the following command to set up the aws cli.
aws configureFill in the AWS Access Key ID, AWS Secret Access Key, and Region based on the IAM user your created in the previous step.
If you have already configured your AWS account, you may accept the existing default values listed in [brackets] by pressing the enter key.
$ aws configure
AWS Access Key ID []: XXXXXXXXXXXXXXXXXXXX
AWS Secret Access Key []: YYYYYYYYYYYYYYYYYYYY
Default region name [us-west-2]:
Default output format [json]:Download the latest version of STM32CubeIDE from the STMicroelectronics website.
At the time of this writing, Version 1.9.0 was the latest release: - Windows - Mac OS - Debian Package bundle - Redhat Package bundle - Generic Linux Bundle
Abridged installation instructions are included below. Please refer to the STM32CubeIDE Installation guide and the included instructions for your platform if additional help is needed.
The projects in this repository have been verified with versions 1.8.0 and 1.9.0 of STM32CubeIDE.
Open a terminal window and follow the steps below to install STM32CubeIDE on a Debian based Linux machine.
Download the STM32CubeIDE Linux generic installer package
wget <URL HERE>Extract the package
unzip en.st-stm32cubeide_*_amd64.deb_bundle.sh.zipAdd execute permissions to the install package
chmod +x st-stm32cubeide_*_amd64.deb_bundle.shExtract the debian packages from the bundle:
mkdir -p cubeide_install
./st-stm32cubeide_1.9.0_12015_20220302_0855_amd64.deb_bundle.sh --tar xvf --directory cubeide_install .Install the debian packages
export LICENSE_ALREADY_ACCEPTED=1
sudo apt install -y ./cubeide_install/st-stm32cubeide-1.9.0-12015-20220302-0855_amd64.deb ./cubeide_install/st-stlink-udev-rules-1.0.3-2-linux-all.deb ./cubeide_install/st-stlink-server-2.1.0-1-linux-amd64.debStart the IDE
/opt/st/stm32cubeide_1.9.0/stm32cubeide_wayland
# Or
/opt/st/stm32cubeide_1.9.0/stm32cubeideOpen a terminal window and follow the steps below to install STM32CubeIDE on a Redhat based linux machine.
Download the STM32CubeIDE linux rpm installer package
wget <URL HERE>Extract the package
unzip en.st-stm32cubeide_*amd64.rpm_bundle.sh.zipAdd execute permissions to the install package
chmod +x st-stm32cubeide_*amd64.rpm_bundle.shStart the installation script and follow the prompts on the command line.
sudo ./st-stm32cubeide_1.9.0_12015_20220302_0855_amd64.rpm_bundle.shOpen a terminal window and follow the steps below to install STM32CubeIDE on a generic linux machine.
Download the STM32CubeIDE linux generic installer package:
wget <URL>Extract the package
unzip en.st-stm32cubeide*amd64.sh.zipAdd execute permissions to the install package
chmod +x st-stm32cubeide_*amd64.shStart the installation script and follow the prompts on the command line.
./st-stm32cubeide_1.9.0_12015_20220302_0855_amd64.shwget <URL>unzip st-stm32cubeide*.dmg.zipMount the resulting dmg disk image by double clicking on it.
Install the ST-link and/ or J-link debug tools.
Copy the STM32CubeIDE package to your /Applications directory.
Some releases of the STM32CubeIDE MacOS application is not properly signed and notarized, so the following command must be run after copying the .app to /Applications.
xattr -c /Applications/STM32CubeIDE.appNote: If you are not asked to select a workspace when STM32CubeIDE start, you may access this dialog via the File -> Switch Workspace -> Other menu item. 3. Select File -> Import. 4. Select General -> Existing Projects Into Workspace in the Select an Import Wizard dialog and click Next >. 5. Click Browse next to the Select root directory box and navigate to the root of this repository. 6. Click the check box next to both the b_u585i_iot02a_ntz and b_u585i_iot02a_tfm projects and then click Finish. Note: Ensure that copy projects into workspace is not selected
After importing the two demo projects into STM32CubeIDE, decide which one you will build and deploy first and follow the instructions below to do so.
In the Project Explorer pane of STM32CubeIDE, Double click on the project to open it.
Next, Right-click on the project in the Project Explorer pane and select Build Project
Note: You may also build the current project using the Project->Build Project menu item.
Review the README.md file for the Non TrustZone project for more information on the setup and limitations of this demo project.
To flash the b_u585i_iot02a_ntz project to your STM32U5 IoT Discovery Kit, select the Flash_ntz configuration from the Run Configurations menu.
Review the README.md file for the TrustZone Enabled project for more information on the setup and limitations of this demo project.
To flash the b_u585i_iot02a_tfm project to your STM32U5 IoT Discovery Kit, select the Flash_tfm_bl2_s_ns configuration from the Run Configurations menu.
The simplest way to provision your board is to run the tools/provision.py script.
After sourcing the tools/env_setup.sh script, run the folloing command: > Note: When running interactive python scripts in GitBash on Microsoft Windows, you must add “winpty” to the beginning of the command you wish to run.
% python tools/provision.py --interactive
Target device path: /dev/cu.usbmodem143303
Connecting to target...
[ INFO ] Found credentials in shared credentials file: ~/.aws/credentials (credentials.py:load)
Interactive configuration mode: Press return to use defaults (displayed in brackets)
time_hwm[1651013601]: <return>
mqtt_port[8883]: <return>
wifi_ssid[]: my_ssid<return>
wifi_credential[]: password<return>
mqtt_endpoint[xxxxxxxxxxxxxx-ats.iot.us-west-2.amazonaws.com]: <return>
thing_name[xxxxxxxxxxxxxxxx]: <return>
Commiting target configuration...
Generating a new public/private key pair
Generating a self-signed Certificate
Attaching thing: xxxxxxxxxxxxxxxx to principal: arn:aws:iot:us-west-2:XXXXXXXXXXXXXX:cert/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Attaching the "AllowAllDev" policy to the device certificate.
Importing root ca certificate: "Starfield Services Root Certificate Authority - G2"
Provisioning process complete. Resetting target device...The provision.py script has a variety of command line options that may be used to modify it’s behavior.
The –verbose option is particularly useful for debugging.
The –cert-issuer option may be set to either self to generate a self-signed certificate on the device or aws to generate a Certificate Signing Request and issue the cert using the AWS IoT CreateCertificateFromCsr API.
usage: provision.py [-h] [-i] [-v] [-d DEVICE] [--wifi-ssid WIFI_SSID] [--wifi-credential WIFI_CREDENTIAL] [--thing-name THING_NAME]
[--cert-issuer {self,aws}] [--aws-profile AWS_PROFILE] [--aws-region AWS_REGION] [--aws-access-key-id AWS_ACCESS_KEY_ID]
[--aws-access-key-secret AWS_ACCESS_KEY_SECRET]
optional arguments:
-h, --help show this help message and exit
-i, --interactive
-v, --verbose
-d DEVICE, --device DEVICE
--wifi-ssid WIFI_SSID
--wifi-credential WIFI_CREDENTIAL
--thing-name THING_NAME
--cert-issuer {self,aws}
--aws-profile AWS_PROFILE
--aws-region AWS_REGION
--aws-access-key-id AWS_ACCESS_KEY_ID
--aws-access-key-secret AWS_ACCESS_KEY_SECRETOpen the target board’s serial port with your favorite serial terminal. Some common options are terraterm, putty, screen, minicom, and picocom. Additionally a serial terminal is included in the pyserial package installed in the workspace python environment.
To use the pyserial utility, run the following command to interactively list available serial devices: > Note: When running interactive python scripts in GitBash, you must prepend “winpty” to the command you wish to run.
% source tools/env_setup.sh
% python -m serial - 115200
--- Available ports:
--- 1: /dev/cu.Bluetooth-Incoming-Port 'n/a'
--- 2: /dev/cu.usbmodem143303 'STLINK-V3 - ST-Link VCP Data'
--- Enter port index or full name: 2<return>
--- Miniterm on /dev/cu.usbmodem143303 115200,8,N,1 ---
--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---And select your b_u585i_iot02a board from the list by number or port name.
First, configure the desired thing name / mqtt device identifier:
> conf set thing_name my_thing_name
thing_name="my_thing_name"Next, configure you WiFi network details:
> conf set wifi_ssid ssidGoesHere
wifi_ssid="ssidGoesHere"
> conf set wifi_credential MyWifiPassword
wifi_credential="MyWifiPassword"Next, set the mqtt endpoint to the endpoint for your account:
> conf set mqtt_endpoint xxxxxxxxxxxxxx-ats.iot.us-west-2.amazonaws.com
mqtt_endpoint="xxxxxxxxxxxxxx-ats.iot.us-west-2.amazonaws.com"Note: You can determine the endpoint for your AWS account with the
aws iot describe-endpointcommand or on the Settings page of the AWS IoT Core console.
Finally, commit the staged configuration changes to non-volatile memory.
> conf commit
Configuration saved to NVM.Use the pki generate key command to generate a new ECDSA device key pair. The resulting public key will be printed to the console.
> pki generate key
SUCCESS: Key pair generated and stored in
Private Key Label: tls_key_priv
Public Key Label: tls_key_pub
-----BEGIN PUBLIC KEY-----
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=
-----END PUBLIC KEY-----Next, use the pki generate cert command to generate a new self-signed certificate:
> pki generate cert
-----BEGIN CERTIFICATE-----
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==
-----END CERTIFICATE-----Save the resulting certificate to a new file.
> reset
Resetting device.Follow the instructions at the AWS IoT Core Developer Guide to register a client certificate.
aws iot register-certificate-without-ca \
--status ACTIVE \
--certificate-pem file://device_cert_filename.pemaws iot create-thing \
--thing-name SampleIoTThingaws iot attach-thing-principal \
--principal certificateArn \
--thing-name thingNameaws iot create-policy \
--policy-name="AllowAllDev" \
--policy-document="{ \"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\", \"Action\": \"iot:*\", \"Resource\": \"*\"}]}"Note: This policy allows very broad access to AWS IoT MQTT APIs. Use a more restrictive policy for any production environments.
aws iot attach-policy \
--target certificateArn \
--policy-name AllowAllDevLog in to aws.amazon.com with the IAM User created earlier in this guide.
Navigate to the Iot Core service using the search box at the top of the page.
Using the menu on the left side of the screen, select Test->MQTT test client
Set the topic filter to # and click the Subscribe button.
You will soon see sensor data streaming from your test device. > Note: You may need to reset the board using the black RST button.
Devices uses digital signatures to verify the authenticity of the firmware updates sent over the air. Images are signed by an authorized source who creats the image, and device can verify the signature of the image, using the corresponding public key of the source. Steps below shows how to setup and provision the code signing credentials so as to enable cloud to digitally sign the image and the device to verify the image signature before boot.
[ req ]
prompt = no
distinguished_name = my_dn
[ my_dn ]
commonName = test_signer@amazon.com
[ my_exts ]
keyUsage = digitalSignature
extendedKeyUsage = codeSigningopenssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -pkeyopt ec_param_enc:named_curve -outform PEM -out ecdsasigner-priv-key.pemopenssl ec -inform pem -in ecdsasigner-priv-key.pem -pubout -outform pem -out ecdsasigner-pub-key.pemopenssl req -new -x509 -config cert_config.txt -extensions my_exts -nodes -days 365 -key ecdsasigner-priv-key.pem -out ecdsasigner.crt
Note: This command displays an ARN for your certificate. You will need this ARN when you create an OTA update job later.
aws acm import-certificate --certificate fileb://ecdsasigner.crt --private-key fileb://ecdsasigner-priv-key.pem> pki import key ota_signer_pub
# Press `Enter` then paste the contents of the PEM public key file `ecdsasigner-pub-key.pem` into the terminal.
# Press `Enter` again.Note:
ota_signer_pubis the label used to refer to the code signing key during verification of the firmware update.
aws signer put-signing-profile --profile-name <your profile name> --signing-material certificateArn=<certificate arn created in step 4> --platform AmazonFreeRTOS-Default --signing-parameters certname=ota_signer_pubS3 bucket is used to store the new firmware image to be updated. To create a new S3 bucket follow these steps here: https://docs.aws.amazon.com/freertos/latest/userguide/dg-ota-bucket.html
Create a service role which grants permission for OTA service to access the firmware image: https://docs.aws.amazon.com/freertos/latest/userguide/create-service-role.html
Create an OTA update policy using the documentatio here: https://docs.aws.amazon.com/freertos/latest/userguide/create-ota-user-policy.html
Add a policy for AWS IoT to access the code signing profile: https://docs.aws.amazon.com/freertos/latest/userguide/code-sign-policy.html
Bump up the version of the new firmware image to be updated. From
the demo project, open File
Src/ota_pal/ota_firmware_version.c and set
APP_VERSION_MAJOR to 1 higher than current version. Build the firmware
image using STM32Cube IDE.
Upload the new image to the s3 bucket created in the previous section.
aws s3 cp <image binary path> s3://<s3 bucket for image>/
Get the latest s3 file version of the binary image by executing the command below. The command returns an array of json structs containing details of all version. To get the latest version ID, look for VersionId field in the json struct where isLatest field is true.
aws s3api list-object-versions --bucket <s3 bucket for image> --prefix <image binary name>{
"otaUpdateId": "<A unique job ID for the OTA job>",
"targets": [
"arn:aws:iot:<region>:<account id>:thing/<thing name>"
],
"targetSelection": "SNAPSHOT",
"files": [{
"fileName": "<image binary name>",
"fileVersion": "1",
"fileLocation": {
"s3Location": {
"bucket": "<s3 image bucket created above>",
"key": "<image binary name>",
"version": "<latest s3 file version of binary image>"
}
},
"codeSigning": {
"startSigningJobParameter": {
"signingProfileName": "<signing profile name>",
"destination": {
"s3Destination": {
"bucket": "<s3 image bucket created above>"
}
}
}
}
}],
"roleArn": "<ARN of the OTA service role created above>"
}
Create a new OTA update job from the configuration file:
aws iot create-ota-update --cli-input-json file://<ota job configuration file path in your filesystem>The command on success returns the OTA Update identifier and status
of the Job as CREATE_PENDING. To get the corresponding job
ID of the OTA Job, execute the following command and look for
awsIotJobId field in json document returned.
aws iot get-ota-update --ota-update-id=<ota update id created above>Note down the job ID to check the status of the job later.
Once the job is created on the terminal logs, you will see that OTA job is accepted and device starts downloading image.
Create a new OTA update job from the configuration file:
aws iot create-ota-update --cli-input-json file://<ota job configuration file path in your filesystem>The command on success returns the OTA Update identifier and status of the Job as CREATE_PENDING. To get the corresponding job ID of the OTA Job, execute the following command and look for awsIotJobId field in json document returned.
aws iot get-ota-update --ota-update-id=<ota update id created above>Note down the job ID to check the status of the job later.
<INF> 16351 [OTAAgent] Current State=[WaitingForFileBlock], Event=[RequestFileBlock], New state=[WaitingForFileBlock] (ota.c:2834)
<INF> 15293 [OTAAgent] Extracted parameter: [key: value]=[execution.jobDocument.afr_ota.streamname: AFR_OTA-eb53bc47-6918-4b2c-9c85-a4c74c44a04c] (ota.c:1642)
<INF> 15294 [OTAAgent] Extracted parameter: [key: value]=[execution.jobDocument.afr_ota.protocols: ["MQTT"]] (ota.c:1642)
<INF> 15296 [OTAAgent] Extracted parameter: [key: value]=[filepath: b_u585i_iot02a_ntz.bin] (ota.c:1642)
<INF> 17784 [OTAAgent] Current State=[WaitingForFileBlock], Event=[RequestFileBlock], New state=[WaitingForFileBlock] (ota.c:2834)
<INF> 15297 [OTAAgent] Extracted parameter: [key: value]=[fileid: 0] (ota.c:1683)
<INF> 15298 [OTAAgent] Extracted parameter: [key: value]=[certfile: ota_signer_pub] (ota.c:1642)
<INF> 15300 [OTAAgent] Extracted parameter [ sig-sha256-ecdsa: MEUCIGWRkFqcumdPZhoZ93ov5Npvsjj7... ] (ota.c:1573)
<INF> 15301 [OTAAgent] Extracted parameter: [key: value]=[fileType: 0] (ota.c:1683)
<INF> 15301 [OTAAgent] Job document was accepted. Attempting to begin the update. (ota.c:2199)
<INF> 16533 [OTAAgent] Number of blocks remaining: 306 (ota.c:2683)
<INF> 15450 [OTAAgent] Setting OTA data interface. (ota.c:938)
<INF> 15450 [OTAAgent] Current State=[Creating
<INF> 67405 [OTAAgent] Received final block of the update. (ota.c:2633)
<INF> 67405 [OTAAgent] Validating the integrity of OTA image using digital signature. (ota_pal.c:681)
<INF> 69643 [OTAAgent] Received entire update and validated the signature. (ota.c:2654)<INF> 15487 [OTAAgent] In self test mode. (ota.c:2102)
<INF> 15487 [OTAAgent] New image has a higher version number than the current image: New image version=1.9.0, Previous image version=0.9.0 (ota.c:1932)aws iot describe-job-execution --job-id=<Job ID created above> --thing-name=<thing name>