7.3. SEMS Lite Agent Usage

7.3.1. Case 1: Basic Usage

Basic API usage documentation for using SEMS Lite agent is as under.

  1. Call sems_lite_agent_init_context() to do context initialization.

  2. Call sems_lite_agent_session_open() to open channel to SE and select SEMS Lite applet.

  3. Call sems_lite_agent_load_package() to load upgrade script.

  4. SEMS Lite agent would internally query the tear status from SE051, if there was a power interrupt during upgradation(tearing event).

  5. SEMS Lite agent load the script from package to SE051 and get response from SE051.

  6. SEMS Lite agent checking the response and return “Success” to user.

  7. User call sems_lite_agent_session_close() to close channel.

../../_images/0022_flow_api_success.png

7.3.2. Case 2: In case there was a tearing

In case of tear which is due to system power off during uploading, user would receive return code “DoRerun” when he try to load new package. Use must load the torn again.

  1. Call sems_lite_agent_init_context(), sems_lite_agent_session_open() and sems_lite_agent_load_package() as those in Case 1: Basic Usage.

  2. SEMS Lite agent would query tear status from SE.

  3. In case tear happens, SEMS Lite agent would get signature of tear script from SE and compare it to the signature of loaded script.

  4. If these 2 signatures are same, it means the loaded script is the re-run script. SEMS Lite agent load it to SE.

  5. If the signatures are different, SEMS Lite agent would inform user to load script again.

  6. User must find the correct script by signature and load it again.

../../_images/0020_flow_with_signature.png

7.3.3. Case 3: Doing a recovery after a failed update

In case the upgrade can not complete, user would receive return code “Do Recovery”. User must load recovery script to resume SE to old Applet.

  1. Call sems_lite_agent_init_context(), sems_lite_agent_session_open() and sems_lite_agent_load_package() as those in Case 1: Basic Usage.

  2. SEMS Lite agent would query tear status from SE as in Case 2: In case there was a tearing.

  3. SEMS Lite agent load the script from package to SE. SE can’t complete upgrade and inform SEMS Lite agent to do recovery by response.

  4. SEMS Lite agent checking the response and return “DoRecovery” to user.

  5. User must find the recovery script which is used to load the old Applet.

  6. User load the recovery script and get response from SEMS Lite agent.

../../_images/0025_flow_api_recovery.png

Details for SE to report “Do Recovery” can be found in following:

../../_images/0030_flow_apis_recovery_detection_scenario1.png ../../_images/0030_flow_apis_recovery_detection_scenario2.png

7.3.4. Case 4: Tearing during recovery

Case 4: In case tear happens when loading recovery package, User should re-run the script in the same way described in Case 2: In case there was a tearing.

../../_images/0041_flow_recovery_tear.png

7.3.5. Case 5: Load Key rotate script encounter SE unexpected power off

In case the SE is powered off unexpectedly during uploading key rotate script, user would receive return code “COM_FAILURE” which means communication failure. User has 2 choices:

  1. Load next script. SEMS Lite agent will check tear status and inform user if it’s required to re-run last script. It’s same to Case 2: In case there was a tearing.

  2. User software checks tear status and then decides whether to re-load the broken script as following:

  1. Call sems_lite_agent_init_context() and sems_lite_agent_session_open() as those in Case 1: Basic Usage.

  2. Call sems_lite_check_Tear() to decide if tear happens for last upgrade.

  3. In case tear happens, call sems_lite_get_SignatureofLastScript() to get last script signature

  4. Find the correct script by signature and load the tear script again with sems_lite_agent_load_package().

../../_images/0050_flow_unexpected_power_off.png

7.3.6. API Calls for Usage of SEMS Lite Agent

#include "sems_lite_api.h"

Declare a SEMS Lite input buffer: SEMS Lite input buffer is hex file converted from protobuf file

Declare SEMS Lite context: SEMS Lite context holds flags and variables used through the whole loading process

sems_lite_agent_ctx_t s_sems_lite_agent_ctx = {0};

Initilize the context:

rv = sems_lite_agent_init_context(&s_sems_lite_agent_ctx, &pCtx->session);

Open session:

rv = sems_lite_agent_session_open(&s_sems_lite_agent_ctx);

Load Package:

status = sems_lite_agent_load_package(
    &s_sems_lite_agent_ctx, &multicast_package);

Close the session:

rv = sems_lite_agent_session_close(&s_sems_lite_agent_ctx);