This document guides you through all of the steps required to run Device Management Client example on the CYTFM_064B0S2_4343W target.
Install the libusb
dependency for pyOCD based on the Cypress documentation.
Note: Due to a known issue, Cypress recommends using libusb
version 1.0.21 on Windows instead of the most recent version.
PATH
environment variable to point to the installation.From the Mbed Studio menu bar, select File > Import Program... and on the URL
textbox enter the path to this repository:
https://github.com/PelionIoT/mbed-os-example-pelion-psoc64
Leave the rest of the dialog options as is and click Add Program. The checkout takes some time since it downloads and initalizes both Mbed OS and the dependant libraries, so be patient!
From the Mbed Studio menu bar, select Terminal > New Terminal to open a terminal.
Important Note Due to a known issue with the Mbed Studio terminal feature, if you close and re-open Mbed Studio, you need to close the terminal tab and re-open it. Otherwise the terminal's path environment variable may be corrupted.
Install CySecureTools:
pip install cysecuretools
You need to carry out this step only once on each board to be able to re-provision later with your root CA and device certificate.
In the Mbed Studio terminal, set up your project workspace for CySecureTools and create keys for provisioning:
cd ./mbed-os-example-pelion-psoc64/mbed-os/targets/TARGET_Cypress/TARGET_PSOC6/TARGET_CYTFM_064B0S2_4343W
cysecuretools -t cy8ckit-064b0s2-4343w init
cysecuretools -t cy8ckit-064b0s2-4343w -p policy/policy_multi_CM0_CM4_tfm.json create-keys
You will be prompted to overwrite existing files. Type y
to continue.
Unplug your device from the power supply.
Remove the jumper shunt from J26.
Plug-in power.
Press the ‘Mode’ button on the kit until the KitProg3 Status LED blinks fast:
To provision the board with basic configuration, run:
_Still within mbed-os-example-pelion-psoc64/mbed-os/targets/TARGET_Cypress/TARGET_PSOC6/TARGET_CYTFM_064B0S24343W
cysecuretools -t cy8ckit-064b0s2-4343w -p policy/policy_multi_CM0_CM4_tfm.json provision-device
Unplug your device from the power supply.
Put back the jumper shunt in J26.
Plug-in power.
Note: You don't need the keys and other files that are created in this flow in the future. At this point, you can delete these files.
For more information about the initial provisioning process, please see the "Provision the Device" section of the CY8CKIT-064B0S2-4343W PSoC 64 Secure Boot Wi-Fi BT Pioneer Kit Guide.
Navigate to the root of the project and enter the TARGET_CYTFM_064B0S2_4343W
directory:
cd mbed-os-example-pelion-psoc64/TARGET_CYTFM_064B0S2_4343W
Create a certificates
directory:
_Within mbed-os-example-pelion-psoc64/TARGET_CYTFM_064B0S24343W
mkdir certificates
Name your own root CA private key and certificate rootCA.key
and rootCA.pem
respectively, and place them in the certificates/
directory.
Alternatively, if you don't have a root CA, you can generate a root CA private key and certificate using the OpenSSL toolkit:
openssl ecparam -out certificates/rootCA.key -name prime256v1 -genkey
Create a new configuration file called root.cnf
and place it in the certificates/
directory. The file is passed as input to the openssl
tool in the next step, to create the final certificate.
The contents of the file should be the following:
[ req ]
distinguished_name=dn
prompt = no
[ ext ]
basicConstraints = CA:TRUE
keyUsage = digitalSignature, keyCertSign, cRLSign
[ dn ]
CN = ROOT_CA
Finally, create the certificate:
openssl req -key certificates/rootCA.key -new -x509 -days 7300 -sha256 -out certificates/rootCA.pem -config certificates/root.cnf -extensions ext
Upload the root CA certificate generated from the previous step to the portal. Refer to the Pelion Documentation for instructions on how to accomplish this.
Important: When you upload your root CA certificate to Device Management Portal, you must select Enrollment - I received this certificate from the device manufacturer or a supplier from the How will devices use this certificate? dropdown.
Set up your project workspace for CySecureTools and create keys based on the cytfm_pelion_policy.json
policy:
_Still within mbed-os-example-pelion-psoc64/TARGET_CYTFM_064B0S24343W
cysecuretools -t cy8ckit-064b0s2-4343w init
cysecuretools -t cy8ckit-064b0s2-4343w -p policy/cytfm_pelion_policy.json create-keys
Note: You use these keys to sign future application images and the device uses the keys to verify the application images. Therefore, if you lose the keys, you need to re-provision the board with new keys.
Provision the device with your root CA, app keys and device certificate:
Note: Make sure to replace
'<device's unique serial number>'
with your own serial number. An example serial number that can be used is111222333444555
python ../mbed-os/targets/TARGET_Cypress/TARGET_PSOC6/TARGET_CYTFM_064B0S2_4343W/reprov_helper.py -d cy8ckit-064b0s2-4343w -p policy/cytfm_pelion_policy.json -existing-keys --serial <device's unique serial number> -y
Navigate back to the root of the project:
cd ..
In Windows only, rename .mbedignore-for-win
to .mbedignore
:
rename .mbedignore-for-win .mbedignore
Note: Due to mbed-os issue 7129, the include path might exceed the maximum Windows command line string length. Using
.mbedignore
decreases the length of the include path but makes these features unavailable:
- Certificate enrollment.
- Device Sentry.
- Secure device access.
- Factory flow using FCU.
In Windows, Mac and other case-insensitive file systems, apply a patch that resolves an issue with conflicting file names by running:
cd mbed-cloud-client
git am ../mcc-fix-conflict-fname.patch
Once the patch is applied, return to the root of the project:
cd ..
Add your WiFi access point information:
Open the file mbed_app.json
within Mbed Studio.
Edit the lines to update the default WiFi SSID & password:
"nsapi.default-wifi-ssid" : "\"SSID\"",
"nsapi.default-wifi-password" : "\"PASSWORD\"",
To enable firmware update:
Install manifest-tool v2.0 or higher:
pip install --upgrade manifest-tool
Note: The Cypress update flow requires the newest version of the manifest-tool.
Initialize the upgrade environment:
Note: You need to pass an
Access Key
that you create in the Pelion portal. For information about access keys and how you can create one, please refer to our documentation.Note: Make sure after you create the
Access key
in the portal, to keep it in a safe place cause you won't be able to retrieve it again. If you lose it, you need to create a new one.
Once the access key is created, pass it as a parameter:
Within the top level project directory: mbed-os-example-pelion-psoc64
manifest-dev-tool init --force -a [access key from Device Management Portal]
Configure the target:
Mbed OS supports two target configurations for this board. For this tutorial, we will use CYTFM_064B0S2_4343W which enables support for Trusted Firmware-M (TF-M) secure services. The default target that Mbed Studio recognizes for this board is _CY8CKIT_064B0S24343W, so it needs to be changed.
In Mbed Studio, click the down arrow in the Target box.
Click the chip icon to open the Manage Custom Targets menu.
From the USB device dropdown, select the connected board.
Enter CYTFM_064B0S2_4343W
for both Target name and Build target fields.
Click Save All.
Click the hammer icon () to build the application:
Upon success, the output looks like this:
020-09-16 15:41:57,783 : C : INFO : Image for slot BOOT signed successfully! (BUILD/CYTFM_064B0S2_4343W/ARMC6\tfm_s.hex)
2020-09-16 15:41:58,168 : C : INFO : Image for slot UPGRADE signed successfully! (BUILD/CYTFM_064B0S2_4343W/ARMC6\tfm_s_upgrade.hex)
2020-09-16 15:42:00,372 : C : INFO : Image for slot BOOT signed successfully! (BUILD/CYTFM_064B0S2_4343W/ARMC6\mbed-os-example-pelion-psoc64.hex)
2020-09-16 15:42:01,813 : C : INFO : Image for slot UPGRADE signed successfully! (BUILD/CYTFM_064B0S2_4343W/ARMC6\mbed-os-example-pelion-psoc64_upgrade.hex)
| Module | .text | .data | .bss |
|-----------------------------------------------|------------|----------|------------|
| TARGET_CYTFM_064B0S2_4343W\cy_factory_flow.o | 2113(+0) | 0(+0) | 2000(+0) |
| [lib]\c_w.l | 13006(+0) | 16(+0) | 392(+0) |
| [lib]\fz_wm.l | 1888(+0) | 0(+0) | 0(+0) |
| [lib]\libcpp_w.l | 5(+0) | 0(+0) | 0(+0) |
| [lib]\libcppabi_w.l | 44(+0) | 0(+0) | 0(+0) |
| [lib]\m_wm.l | 754(+0) | 0(+0) | 0(+0) |
| anon$$obj.o | 48(+0) | 0(+0) | 5120(+0) |
| main.o | 3059(+0) | 0(+0) | 369(+0) |
| mbed-cloud-client\device-sentry-client | 166(+0) | 0(+0) | 0(+0) |
| mbed-cloud-client\factory-configurator-client | 11190(+0) | 2(+0) | 83(+0) |
| mbed-cloud-client\mbed-client | 67037(+0) | 22(+0) | 12(+0) |
| mbed-cloud-client\mbed-client-pal | 14254(+0) | 1(+0) | 79(+0) |
| mbed-cloud-client\source | 10166(+0) | 5(+0) | 24(+0) |
| mbed-cloud-client\update-client-hub | 28753(+0) | 146(+0) | 5178(+0) |
| mbed-os\connectivity | 165477(+0) | 200(+0) | 105681(+0) |
| mbed-os\drivers | 6614(+0) | 0(+0) | 84(+0) |
| mbed-os\events | 2138(+0) | 0(+0) | 4672(+0) |
| mbed-os\features | 6470(+0) | 1(+0) | 228(+0) |
| mbed-os\hal | 3580(+0) | 8(+0) | 248(+0) |
| mbed-os\platform | 10393(+0) | 80(+0) | 1420(+0) |
| mbed-os\rtos | 16028(+0) | 168(+0) | 7897(+0) |
| mbed-os\storage | 5873(+0) | 0(+0) | 548(+0) |
| mbed-os\targets | 508073(+0) | 533(+0) | 3817(+0) |
| update_default_resources.o | 432(+0) | 0(+0) | 0(+0) |
| Subtotals | 877561(+0) | 1182(+0) | 137852(+0) |
Total Static RAM memory (data + bss): 139034(+0) bytes
Total Flash memory (text + data): 878743(+0) bytes
Update Image: BUILD/CYTFM_064B0S2_4343W/ARMC6\mbed-os-example-pelion-psoc64_update.bin
Image: BUILD/CYTFM_064B0S2_4343W/ARMC6\mbed-os-example-pelion-psoc64.hex
Notes:
- Depending on your system, the building can take two minutes (best case) to 20 minutes (worst case).
- Ignore this error:
Configuration error: Bootloader not supported on this target. RAM start not found in targets.json.
Click the run icon () to flash and run the application:
Alternatively, you can flash the application directly:
BUILD/CYTFM_064B0S2_4343W/ARMC6/mbed-os-example-pelion-psoc64.hex
) to the mounted drive for the board.Open the serial monitor (click View > Serial Monitor in Mbed Studio) and choose baud rate 115200
.
Enroll the device to your Pelion account:
The first time the application successfully boots up and connects to the network, it prints its enrollment ID on the serial monitor.
Note: For development purposes, you can reset the Device Management credentials by running
pyocd erase -s 0x101C0000-0x101C9000
.
The CYTFM_064B0S2_4343W
target board has two cores - CM0 for the T-FM firmware, CM4 for the example application.
We currently support updating the example application in the CM4 core.
To update the example application:
Update the firmware version in the TARGET_CYTFM_064B0S2_4343W/policy/cytfm_pelion_policy.json
file:
Go to "id": 16
in the file.
This section of the file holds the CM4 core configuration.
Update "version": "<new firmware version>",
.
Where <new firmware version>
is a string in MSB.LSB (Most Significant Byte/Least Significant Byte) format.
Click the hammer icon () to build the upgraded signed image:
This creates a ./BUILD/CYTFM_064B0S2_4343W/ARMC6/mbed-os-example-pelion-psoc64_upgrade.hex
file.
The manifest tool does not currently support hex files; therefore, you must convert the image to bin format.
Convert the upgrade image from hex to bin format. Open Mbed Studio terminal and in the root of the project enter:
within the top level project directory: mbed-os-example-pelion-psoc64
python inthex2bin.py BUILD/CYTFM_064B0S2_4343W/ARMC6/mbed-os-example-pelion-psoc64_upgrade.hex
This creates the ./BUILD/CYTFM_064B0S2_4343W/ARMC6/mbed-os-example-pelion-psoc64_upgrade.bin
file.
Perform the update:
manifest-dev-tool update-v1 --payload-path BUILD/CYTFM_064B0S2_4343W/ARMC6/mbed-os-example-pelion-psoc64_upgrade.bin --fw-version <new firmware version> --device-id <device ID> --start-campaign --wait-for-completion --no-cleanup --timeout 3600
Where:
<new firmware version>
is a 64-bit unsigned integer, where 32 MSBs represent the major version and 32 LSBs represent the minor version. For example, version 1.0 is represented as 4294967296
and version 1.1 as 4294967297
. You can run the following to calculate the value, replacing 1.0
with your desired version number:python -c "a, b = '1.0'.split('.'); print((int(a)<<32) + int(b))"
<device ID>
is the ID of the device to be updated. The Device ID is printed in the console when the device boots up or is visible in the Pelion portal at the Device Directory section (column Device ID
)When executing this command, the manifest tool:
You can validate that the device is using the upgraded firmware in the serial monitor printout:
Current FW image version: <new firmware version>
You can check the status of the update campaign by selecting it in the portal and opening its details pane. It should be marked as successful:
If the Python commands fail to run
which python
(Mac or Linux) or where python
on windows. The path to the correct version of Python should be within Mbed Studio files.If the provisioning tools fail to connect
If the provisioning process fails
If the application fails to build in Mbed Studio
If the device fails to connect to the Pelion service
manifest-dev-tool init
within a project multiple times, which causes the update certificate to change. If this occurs, follow these steps.
pyocd erase -s 0x101C0000-0x101C9000
.If you missed getting the enrollemnt ID from the device
c
in the serial monitor before copying the enrollment ID, run the command pyocd erase -s 0x101C0000-0x101C9000
to start over.If the firmware update campaign fails to start
pyocd erase -s 0x101C0000-0x101C9000
, reset the board, and try again.If the device does not start downloading the update
More information for PSoC® 64 and Pelion™ IoT platform can be found in the following pages: