Automatic Serial Number Mechanism

For Cyclone LC, Cyclone FX, Cyclone MultiChannel

When producing a microcontroller- or microprocessor-based product, it is often useful to program a unique serial number into the permanent memory (FLASH) of the product.

PEmicro offers a serial number mechanism to automate this process. Each time you issue a serialization command in the programming software, the current serial number is programmed at a specified address. In addition, the serial number is incremented to the next available serial number and saved for future serialized programming operations.

The Cyclone adopts this automatic serial number mechanism for its stand-alone operations. The user can create a Serial File using PEmicro's Serialize Utility and then include commands in the programming sequence of the programming image to implement that Serial File. If needed, adjustments can later be made to the serial number of a programming image by using the Cyclone menu screen.

Understanding Serialization

The automatic serial number mechanism supports serial numbers from 1 to 16 bytes in length. Each byte of a serial number ranges between a lower and an upper bound. This approach allows the individual bytes of the serial number to have distinct properties. Some of the forms these properties can take are:

Type	Lower Bound (hex)	Upper Bound (hex)
Type	Lower Bound (hex)	Upper Bound (hex)
Constant	Constant	Constant
Binary	00	FF
ASCII Printable	20	7E
ASCII Numeric	30	39
ASCII Upper Case Letter	41	5A
ASCII Lower Case Letter	61	7A
Other	XX	YY

Each serial number and its properties are stored in a separate file. Any file name can be used for the serial number file, however the extension .ser is normally appended because it makes it simpler to locate the file.

A utility called SERIALIZE has been developed to make it easy to create, visualize, edit, and maintain these serial number files.

Serialize Utility

The serialize utility allows the user to create a serial number file with a serial number that is anywhere from 1 to 16 bytes long. Each byte may be bounded as a full binary or as a number, constant, alpha uppercase, alpha lowercase, or ASCII printable character. The serial number file also has a field for a starting hex address that may range from 00000000 to FFFFFFFF. Serial numbers can be programmed in order or in reverse order.

Figure: Serialize Main Screen

Startup and File Options

On startup, the Serialize program will automatically open the last file saved. If no file has been saved, it will default to blank.

• Reset Button - Lets you reset to a screen with only a single serial number byte defaulted to binary (00), hex address 00000000.
• Regenerate Button - Preserves serial number bytes and bounds but assigns a new Serial Number Unique ID
• Save Button, File→Save - Brings up a dialog which is set to save to the current serial file configuration.
• File→Save As - Brings up a dialog to select any file
• File→Load - Brings up a dialog to select a previously saved file

Reset

Instructs the program to start editing a NEW (as yet un-named) serial number file. It will throw away the information for any serial number currently being edited unless that information has been saved (Save Button). The new serial number is initialized with one (1) byte of binary.

Save

Pops up a Save dialog with the current serial number being edited into the file name and path as shown in the Serial Number File window. If a file name has not been provided, a dialog will pop up to allow the user to select a file name. Save will save any setup information in the file Serialize.ini. This file will initialize the setup information the next time the program is started.

Serial Number File

Displays the path and filename of the open Serial File, if saved.

Serial File Unique ID

Displays the unique ID associated with the Serial File. A unique ID is generated any time a Serial File is created or modified. Multiple programming images are able to share the same serial numbers by referencing the same ID number. The user can click the "Regenerate" button to assign a new unique ID to the current Serial File.

Serial File Name To Display

The name that will appear in the JSON viewer, Cyclone menu, and in the Name field of the Cyclone Control GUI. A descriptive name can help to easily differentiate Serial Files.

Serial File Notes

Allows the user to save notes regarding the Serial File. These will appear in the JSON viewer when viewing the properties of the Serial File, see Serial File Properties.

Number of Bytes in Serial Number

The up and down arrows allow the user to add or delete bytes for the serial number, the maximum in hexadecimal = 0x10 (16 base-10), the minimum = 1.

• Up Arrow Click - Adds new bytes to the Serial Number. Each byte added appears as a new column in the serial number representation. Added bytes are input as Binary Bytes, i.e. the upper bound is FF and the lower bound is 00.
• Down Arrow Click - Deletes bytes from the right end of the Serial Number. Any previously entered byte properties are lost.

Starting HEX Address

Assigns the starting address (in hexadecimal) of the device memory where the serial number will be programmed.

Count Sequence

This window lets you test the serial number by counting up or down through the sequencing of the serial number. The serial number will roll over the upper bounds of the serial number back to the lower bounds of the serial number, and vice versa.

• Up Arrow Click - Counts the serial number up.
• Down Arrow Click - Counts the serial number down.

Serial Number Bytes as Hex

There is one display column for each byte in the serial number shown as printable ASCII characters. Non-printable ASCII characters are indicated by a blank gray box.

• Up Arrow Click - Counts the serial number up.
• Down Arrow Click - Counts the serial number down.
• Click into the edit Box to enter any number within range. Values entered will be limited by the upper and lower bounds.

Hex Upper Bounds

There is one display column for each upper bound of the byte in the serial number in hex.

• Up Arrow Click - Increases the upper bound by one with a maximum of FF Hex.
• Down Arrow Click - Decreases the upper bound by one with a minimum of the current serial number byte value.
• Click into the edit box to enter any number within range (from the serial number value up to a maximum of Hex FF).

Hex Lower Bounds

There is one display column for each byte of the lower bound of the serial number in hex.

• Up Arrow Click - Increases the lower bound by one with a maximum of the current serial number byte value.
• Down Arrow Click - Decreases the lower bound by one with a minimum of 00 Hex.
• Click into the edit box to enter any number within range (from the serial number value to a minimum of 00 Hex).

Binary, Numeric, Constant, Alpha Upper, Alpha Lower, and Printable

Checkboxes at the bottom will select properties to set for each serial number byte. Selections will be highlighted in yellow. The buttons below may be used to set the boundary type for the selected serial number byte(s).

Byte Program Order

The user can choose whether the serial number increments from left to right, or from right to left, in the Byte Program Order section.

Serial File Properties

Serial File properties are easy to access, as the generated serial file is stored in JSON format. This makes it simple for the user to save and parse the information.

Users who wish to retrieve the original text serial number format can parse out the JSON file:

object -> pesettings -> serial_number_definition -> legacyv1encoding

Serial File Example

An example file is provided, Example.ser, located in the Image Creation folder of your installation directory. Below is a screen snapshot of the saved serial file as seen from a JSON viewer.

Figure: Example Serial File In JSON Viewer

Serial Number Handling

The Cyclone firmware implements the automatic serial number mechanism. The same serial number files are used with the Cyclone Image Creation Utility, and the same commands are used to specify the serial number file and initiate serial number programming and incrementing. The serial number data structure is saved in the SAP image. Once a "PS" command is carried out, a serial number is programmed into the target. Only after all operations have been completed successfully does the Cyclone firmware automatically increment the serial number and store it in the Cyclone's flash for internal images (or external CompactFlash for external SAP images).

The CS and PS commands are not present in the Cyclone Image Creation Utility until a valid programming algorithm is specified.

To complement the Cyclone's usage in production environments, the Cyclone supports multiple serial number structures for each programming algorithm block. Each SAP image may contain multiple programming algorithms for every memory module it needs to program, and each programming algorithm block may contain multiple serial number structures. The SAP image sequence below illustrates this briefly:

CM algorithm_file_1
CQ
QO object_code_1
EM
PM
VC
CS serial_file1.ser
PS
CS serial_file2.ser
PS
CS serial_file_3.ser
PS
CM algorithm_file_2
CQ
QO object_code_2
EM
PM
VC
CS serial_file4.ser
PS
CS serial_file5.ser
PS

Invoking A Serial File Via Command-Line

The command to invoke the serial number file in PEmicro's interactive programming software is "CS Choose Serial File". The command to actually program the serial number to the target and automatically increment the serial number afterward is "PS Program Serial Number".

PEmicro's command-line software uses the same commands in a command-line fashion to invoke the serial number file, initiate its programming, and increment:

CS serial_number_file.ser
PS

Creating A Programming Image With Multiple Serial Numbers

In the example shown in the figure below, an image was created that will select and program two different serial numbers into different locations in memory as part of the programming sequence. The first serial number counts by two with starting address 0x00020000 and the second serial number counts by four with starting address 0x00021000.

As indicated by the programming sequence, first the Algorithm is selected, followed by the S19 file. The part is erased, and then the s19 is programmed into the device. Once this is done, the first serial file is selected and programmed, and then the second serial file. These same unique serial numbers may be used by other programming images, and each programming operation will increase the serial number by the designated count defined in the serial number file.

Figure: Cyclone Image Creation Utility: Serial Files In Programming Sequence

Shared Serial Numbers

An important feature of the Serialize utility is that it automatically creates a Unique ID any time a serial file is created or modified. This allows programming images stored on a Cyclone to share serial numbers that reference the same unique serial number ID. There are several cases where this is very useful. The first is when a user may want to update their firmware for a product to a new version but needs the serial number to have persistence. The user may also have different products that need to be programmed with different firmware, but need to have those products draw from the same serialization sequence.

Note

Shared serial numbers require Cyclone firmware version 10.13 and later.

Example

This section describes how a user might configure multiple programming images on their Cyclone to share the same Serial File.

View and Edit Programming image via Cyclone Control GUI

In the figure below, the Cyclone Control GUI has been launched and is looking at the image contents of the Cyclone. In this case it shows that the Cyclone named Colossus contains four different images. To view properties of a particular image the user can simply right-click on the desired image and select "View properties" which will pop up an image properties window. In this case it shows Image "Kinetis K64 PE S2 and Mac S4." The Image Unique ID is visible, as well as the two serial numbers and their respective Unique IDs. It also shows the next serial numbers (in ASCII representation) to be programmed upon launch: PE-000 and MAC-00, respectively.

Figure: Cyclone Control GUI: Image Properties Window

Deleting the image will not delete the associated serial number as other images stored on the Cyclone may be using that same serial number. The serial number is tracked on the Cyclone by the imageuniqueid JSON property. If any image is added back onto the Cyclone with that same Serial Unique ID, it will continue to track with that same serial number at the latest count. So if a user has a new version of their firmware, they can create a new programming image that uses the same serial number as the previous firmware (referenced by the same serial unique ID) and the programming will continue the serial number sequence from the current serial number state since that serial file is stored on the Cyclone.

Once a programming image is loaded with a serial file, and it is selected as the current image on the Cyclone, it is possible to adjust the serial count. This is done by navigating through the following screens on the Cyclone.

Menu → Current Image Options → Serial Number

If the image has more than one serial number incorporated into the programming image, select the Serial number which is to be modified. Otherwise just select 'Modify Serial'.

Figure: Cyclone Menu Selection

It is possible to Decrease or Increase the Next Serial by -10, -1, +1, +10. This is often done to address issues in the production process, such as during initial setup.

Figure: Increase or Decrease Serial Number

Note that the Cyclone Control GUI has the ability to show all the Serial Files stored on the Cyclone. This is done by opening a Cyclone, and then navigating to the Serial Files Tab, as shown in the figure below. The Serial File tab has a Delete Button at the bottom which will remove the selected serial file from view and reset the tracking of the serial number to its original state. This does not actually delete the serial file. Once any programming is initiated using this 'deleted' serial file, the serial file will reappear in the list and program using the original serial number.

Figure: Cyclone Control GUI: Serial Files Tab

Program SAP images With Shared Serialization

The Cyclone screen in the figure below shows two programming images stored on the Cyclone: The first is 'Waynes Image Serialx2' and the second is 'Garths Image Serialx2'. They both use the same serial file named 'PEserial K64 Count by 2' which has a unique ID ser-4FD596BF-7DDD6470-5BDAE9E7 and the next serial number to be programmed (in ASCII) is PE-002. If we select Wayne's image we can see this current PE-002.

Figure: View Current Serial Number for "Wayne's Image"

Once programming is initiated, PE-002 is programmed into memory and the screen shows the next serial number to be programmed, which is PE-004.

Figure: Serial Number Incremented for "Wayne's Image"

If Garth's Image is now selected on the Cyclone, it will show that the next serial number to be programmed is PE-004 because it tracks the same serial number.

Figure: Serial Number Also Incremented for "Garth's Image"