7.2. Update Package¶
SEMS Lite agent gets an update package from the update manager. The upgrade package contains package meta data header and set of APDUs(MulticastCommands) to be sent to the SE for update. It may optionally also contain host control commands (e.g. Reset the secure element).
Format of the update package:

NXP provides customer package meta data and Multicast commands in JSON file. NXP also provides generator tool to turn the JSON file to binary file and .c/.h files. Customer can decide which one to be used by update manager according to their platform. Update manager should create update package from these files. This chapter has provided examples for the use of generator. It also provides links to the demos which will use the generated files to create update package.
7.2.1. Package Meta Data¶
Package meta data includes information such as version and memory requirement. These information will help SEMS Lite agent to preprocess package before loading APDU commands to SE.
MulticastPackageFormatVersion: Version information of this json Format for MulticastPackages.
TargetEntityID: Entity ID, 16bytes long Binary Coded Decimal, of the target device where this MulticastPackage is intended to be executed on. It is an identifier of the key-set of the Multicast Applet Loader.
Target12nc: Target 12nc is a 12 digit numerical code identifying the target device where this MulticastPackage is intended to be executed on, as known to customers and used on EdgeLock2Go to identify device types.
requiredFreeBytesNonVolatileMemory: Minimum required free Non Volatile memory in bytes that have to be available on the target device before execution of this MulticastPackage.
requiredFreeBytesTransientMemory: Minimum required free transient (RAM) memory in bytes that have to be available on the target device before execution of this MulticastPackage.
MulticastPackageName: Giving a descriptive name to the complete Multicast Package.
MulticastPackageVersion: Version information of this MulticastPackage, describing the sum version over all contained content.
SubComponentMetaData: A list of subcomponents of this MulticastPackage, designating all Executable Load Files (ELFs) Contained. It usually contains one entry, but can have multiple in the case multiple dependent ELFs get modified. This list can be empty, e.g. for a KeyRotation or deletion of content.
SubComponentMetaData name: A human readable name for this subcomponent.
SubComponentMetaData aid: The Application Identifier (AID) of the Executable Load File (ELF) which makes up the content of this subcomponent. This is stored as string to have it formatted in upper-case hexadecimal and therefore recognizable form.
SubComponentMetaData version: Version information of this subcomponent.
SubComponentMetaData minimumPreviousVersion: Minimum version number of this subcomponent as installed on the secure element before this script is executed. If this field is omitted there is no minimum version requirement, e.g. initial Installation of an applet.
SignatureOverCommands: The signature over the multicast commands in an machine readable form. So it does not have to be parsed form the script commands. String encoding (upper-case hexadecimal) is chosen here, as many json parsers can not handle such large integer values.
MulticastCommands: The complete Multicast Applet Loader Script (certificate, signature, encrypted and signed commands) in ls-cgt format, encoded in base64.
7.2.2. MulticastCommands In Protocol Buffer Format¶
Note
Advanced information
The information below is for advanced users and kept here for the sake of completeness of information. This section can be skipped.
Technically, the APDUS(MulticastCommands) in update package is encoded in Protocol Buffers format (https://developers.google.com/protocol-buffers/) as defined below
/* Full request from cloud/host to the agent */
message Requests {
/* An array of RequestPayload */
repeated RequestPayload payload = 1;
}
/* Consolidated response from the agent to the cloud/host */
message Responses {
/* An array of ResponsePayload */
repeated ResponsePayload responses = 1;
}
/* The request payload would be either of these */
message RequestPayload {
oneof payload {
/* Hello from EdgeLock 2GO cloud service to the EdgeLock 2GO agent.
*
* Used only by EdgeLock 2GO agent. */
AgentHelloRequest hello = 1;
/** Good Bye from EdgeLock 2GO cloud service to the EdgeLock 2GO agent.
*
* Used only by EdgeLock 2GO agent. */
AgentGoodbyeRequest goodbye = 2;
AgentCrlRequest crl = 3;
/* An APDU to a SE.
*
* Used both by EdgeLock 2GO agent and SEMS Lite agent. */
ApduRequest apdu = 20;
/* Message to read and write configuration data.
*
* Used only by EdgeLock 2GO agent. */
DatastoreRequest datastore = 30;
/* Message to contol the host software on the device.
*
* Not implemented. */
RpcRequest rpc = 40;
/*
*
* Used only by SEMS Lite Agent */
HostControlCmdRequest hostCmd = 50;
}
}
message ApduRequest {
/* Array of bytes to be sent to the SE */
optional bytes message = 100;
/* What response is expected from the SE for this APDU?
*
* If this field is skipped from protobuf, then,
* only 0x9000 is expected from the SE
*
* There are potentially multiple distinct values
* are expected the from the SE, then this
* can be an array of those values.
*
* e.g. expectation: [ 0x9000, 0x6A82 ]
*
* For complex schems where a every big range/mask
* is expected, e.g. 6AXX, 6DXX then the upper
* 16 bits are treated as mask.
*
* e.g. expectation: [ 0x00FF6A00, 0x00FF6D00 ]
*
* This field is unused by EdgeLock 2GO cloud service.
*/
repeated uint32 expectation = 101;
}
/* Response from the SE to host */
message ApduResponse {
/* Byte array */
optional bytes message = 100;
}
7.2.3. Generator Tools¶
NXP provides 2 generator tools in semslit/tools/sems-lite-generator
directory:
JSON Generator: A tool to convert the output of CGT tool to a JSON format output
SEMS Lite generator: A tool to convert JSON output to binary file and .c/.h files which will be used by update manager

7.2.3.1. JSON Generator¶
Usage: MulticastPackageCli.py [-h] –config_file [CONFIG_FILE] –script_file [SCRIPT_FILE] –out [OUT]
Arguments:
- –config_file [CONFIG_FILE]
Config File for MulticastPackage generation. It should follow the format defined in
semslit/tools/sems-lite-generator/schema/MulticastPackage.jsonschema
. NXP provides an example insemslit/tools/sems-lite-generator/config/ExampleConfig.json
- –script_file [SCRIPT_FILE]
Encrypted and Signed script as output by the ls-cgt tool.
- –out [OUT]
Output MulticastPackage json file.
Example:
python ./MulticastPackageCli.py –config_file .config.json –script_file .encrypted.txt –out .Upgrade_IoTApplet.json
7.2.3.2. SEMS Lite Generator¶
Usage: generate.py [-h] [-i INPUT_JSON] [-o OUTPUT_PATH] [-n NAME] [-p PROTOC_PATH]
Process sems-lite-generator arguments
- Arguments:
- -h, --help
show this help message and exit
- -i, --input_json INPUT_JSON
input json file
- -o, --output_path OUTPUT_PATH
output folder path
- -n, --name NAME
stem name of output files. By default, it would use the same name as input json file.
- -p, --protoc_path PROTOC_PATH
protoc file path. Use tools/mw_onverter/protoc.exe by default
Example:
python ./generate.py -i ./Upgrade_NXP-IoTApplet-6.0.json -o ./
The generated files:
Upgrade_NXP-IoTApplet-6.0.bin: Binary file. It can be used for platforms that have a file system (Windows, Linux, etc). It is encoded in TLV as following:
0x21 Len multicastPackage
|- 0x22 Len Major Minor MulticastPackageFormatVersion
|- 0x23 Len Binary TargetEntityID
|- 0x2f Len Binary Target12nc
|- 0x24 Len u32/u16 requiredFreeBytesNonVolatileMemory
|- 0x25 Len u32/u16 requiredFreeBytesTransientMemory
|- 0x26 Len String MulticastPackageName
|- 0x27 Len Major Minor MulticastPackageVersion
|- 0x28 Len SubComponentMetaData
|- |- 0x2B Len String SubComponentMetaData1.name
|- |- 0x2C Len Binary SubComponentMetaData1.aid
|- |- 0x2D Len Major Minor SubComponentMetaData1.version
|- |- 0x2E Len Major Minor SubComponentMetaData1.minimumPreviousVersion
|- |- 0x2B Len String SubComponentMetaData2.name
|- |- 0x2C Len Binary SubComponentMetaData2.aid
|- |- 0x2D Len Major Minor SubComponentMetaData2.version
|- |- 0x2E Len Major Minor SubComponentMetaData2.minimumPreviousVersion
...
|- |- 0x2B Len String SubComponentMetaDataN.name
|- |- 0x2C Len Binary SubComponentMetaDataN.aid
|- |- 0x2D Len Major Minor SubComponentMetaDataN.version
|- |- 0x2E Len Major Minor SubComponentMetaDataN.minimumPreviousVersion
|- 0x29 Len Binary SignatureOverCommands
|- 0x2A Len Binary MulticastCommands
Upgrade_NXP-IoTApplet-6.0.c and .h: These 2 files instantiate update package. They can be integrated into customer tools and can be used for all platforms.
We provide examples for how to use the generated files: Section 5.1.1.12 SEMS Demos
7.2.3.3. Generator Tool Version Compatibility¶
NXP provides both SEMS Lite generate tool and JSON format in semslite\tools folder. Generate tool should only work with the JSON schema in the same release. For example, in SEMS Lite 2.0.0 (Refer to semslite\version_info.txt) the JSON package format version is 1.2. Generate tool should only use this JSON schema.
|
|
|
SEMS Lite 1.0.0 |
Supported |
Not supported |
SEMS Lite 2.0.0 |
Not supported |
Supported |