The STM32H563 product lifecycle which is supported by PEmicro consists of a number of Product States, each with their own degree of security. The tutorial below demonstrates how to program main flash and provision a device for debug Authentication with password when TrustZone is disabled.

Tutorial Summary

1. PRODUCT_STATE  "Open".  Program the main flash and .obk file containing the password hash created in STM32 Trusted Package Creator.
2. Transition to PRODUCT_STATE "Provisioning" by programming the provisioning.opt file. (Debug is partially opened)
3. Transition to PRODUCT_STATE "Closed" by programming a closed.opt file. (Further debug access is not permitted without debug Authentication)
4. Regression of a secured device is achieved by entering a valid password into the programmer's connection settings. A regressed device will return to the "Open" Product State, similar to a factory reset.

Note: The user is strongly encouraged to ensure the OBKeys are correctly provisioned and the password is programmed before transitioning from the open state. Failure to correctly program the .obk file will result in the user being unable to regain debug access once the device has transitioned to PRODUCT_STATE "Closed"

Programming can be done with either PEmicro's Cyclone Production Programmer or PEmicro's PROGACMP software with a Multilink debug cable. 

Prerequisites for both PROGACMP and Cyclone Image Creation Utility.

1. Create .OBK file in Trusted Package Creator

Users are assumed to have a working knowledge of STM Trusted Package Manager software tool in order to effectively utilize this tutorial. The .obk file produced here will contain a hash of the user's password. This file is then easily and directly programmed with PEmicro's software as shown later in this sequence. 

Open STM32 Trusted Package Creator and select H5 from the left menu. Upload the configuration .xml and adjust password as needed. If the user is unfamiliar with this process, a sample file "DA_ConfigWithPassword.xml" file is provided with STM32 Trusted Package Creator software. Select an output file path and click Generate OBKey.

2. Create User Option Files (.OPT)

Prior to entering the script for programming, the user will need to create a couple of option bytes file to put the device into Provisioning mode and then later into Closed mode. If the user is unfamiliar with creating User Option Files, more details can be found in the following article: Option Bytes Revisited.

To transition from PRODUCT_STATE Open (User Flash Open, Debug open) to PRODUCT_STATE Closed (Debug disabled, regression is possible), two User Option Files are required. Transitions must occur in the correct order. The first option file created (provisioning.opt) will transition the PRODUCT_STATE from "Open" to "Provisioning". The second option file (closed.opt) will transition from PRODUCT_STATE "Provisioning" to "Closed". It is not possible to transition directly from "Open" to "Closed". 

Valid PRODUCT_STATE values are shown in the following table :

To create an options file in PEmicro's PROGACMP, or in the Cyclone Image Creation Utility "Program Sequences" window, click "Create/Modify User Options File". This will bring up a list of available option bytes which may be set.  Change the PRODUCT_STATE option byte to the desired value. In this example, 0x17 indicates the Provisioning State. 

The user may also modify any other option bytes that they want programmed at this time, then click Save to File and save to provisioning.opt. When this file is programmed (and launched), the device state will change to Provisioning.

Create another options file closed.opt which sets the PRODUCT_STATE option to 0x72 (Closed).

Both of the files will be needed to secure the device.

Programming with the Cyclone Programmer

If the user is unfamiliar with the creation of a stand-alone programming (SAP) image, they can refer to the article: How to Regenerate a Stand Alone Programming Image” for a broader explanation of how to create a Stand Alone Programming Image. The Cyclone LC and Cyclone FX user manuals also describe this procedure. 

The user employs the Image Creation Utility to generate the Stand Alone Programming image. After selecting the appropriate device, a programming script is created which specifies all of the steps to erase, program, and provision the device. This is then compiled into a production programming image which runs on the Cyclone. 

Note 1: When creating the programming script, the device should be erased not only by the Erase Entire Module (EM) command, but also the Erase Keys (EK 01) command. The value of 01 for the Erase Keys command will erase data from HDPL 1 and higher (HDPL1, HDPL2, HDPL3_Secure and HDPL3_NS) and will ensure the entire OBkeys region is blank. 

Note 2: After programming option bytes with the PU command (Program User Options), the LO command (Launch Options) needs to be run so that the options immediately take effect. This is important to do when changing PRODUCT_STATE since the state needs to operationally change before further steps in the script can run.

Below is an example sequence/script for programming. It programs both an application binary file and the OBK password and closes the device.

CM C:\PEMicro\cyclone\supportfiles\supportFiles_ARM\ST\STM32H5\ST_STM32H563ZI_2MB.arp 
EM                                 ;Erase Main Flash
EK 01                              ;Erase OBKeys
QO C:\mainFlash.S19                ;Queue main program
QO C:\DA_ConfigWithPassword.obk    ;Queue .OBK file containing password
PM                                 ;Program Both Files
VM                                 ;Verify Both Files
SU C:\provisioning.OPT             ;Select options file to transition to Provisioning
PU                                 ;Program User Options                          
VU                                 ;Verify User Options 
LO                                 ;Transition to PRODUCT_STATE=Provisioning
SU C:\Closed.OPT                   ;Select options file to close the device
PU                                 ;Program User Options                        
VU                                 ;Verify User Options
LO                                 ;Transition to PRODUCT_STATE=Closed

The product state will be closed when programming finishes. Debug is disabled and regression is only allowed with debug authentication. 

Click "Build & Deploy" to launch the Cyclone Control GUI. Once connected to the Cyclone, ensure the image is displayed at the bottom of the list, then "Click To Apply Changes And Exit". The Cyclone Control GUI will close and the image will be stored on the Cyclone, (indicated with a "Success!" notification), ready to be programmed. The user can then press "Start" to program a connected device. Once programmed, the device is secured with Debug Authentication, and a password is now required to regain access.

Regression and Reprogramming with Cyclone

In the case where the user wishes to re-program a device which has already been programmed and secured and has the Debug Authentication via Password enabled, the programming image can be configured to unlock the device prior to programming. The following steps add the password to the debug entry used by Cyclone when connecting to the programmed device:

1. Select the Power and Communication tab next to Image Script

2. Click Mass erase upon connection to target and Allow Regression, then enter the Password used to create the .obk file provisioned to the device. Note: Both boxes must be checked to fully regress the device.

3. Click "Build & deploy" as detailed above to display Cyclone control GUI, then "Click To Apply Changes And Exit". Once the image is stored to the Cyclone, press "Start" to program a device. 

4. When the Cyclone attempts to connect to the device, the "Allow Regression" setting will result in the Cyclone attempting to regress the part into the "Open" state before going through the programming sequence.

In the case that the user wishes to erase the secure part, but not reprogram it, shorten the programming sequence to the following (erase but do not program) :

CM C:\PEMicro\cyclone\supportfiles\supportFiles_ARM\ST\STM32H5\ST_STM32H563ZI_2MB.arp 
EM                                 ;Erase Main Flash
EK 01                              ;Erase OBKeys

Programming with PROGACMP

The PROGACMP is a software based flash programmer that has many of the same capabilities as the Cyclone Production Programmer. PROGACMP is and interactive programmer and CPROGACMP is a scripted version of the same. The steps for programming a device exactly match the ones shown above for the Cyclone Programmer.  If the user is unfamiliar with the PROGACMP software interface, please refer to the PROGACMP User Manual for more detailed instructions

Regressing a Secured Device with PROGACMP

1. Upon connection with the device, check “Mass erase upon connection to target”.

2. Click Security Settings and enter the Password used to secure the device, followed by OK.

3. Click connect.  A successful debug authentication will erase user data in user Flash SRAM and OBKeys, similar to a factory reset, and return the device to an Open state. If Debug authentication is unsuccessful, PEMicro Connection Manager will reappear with the error message “Can’t communicate with the target processor."