SCM Edge Extension Capabilities
The ThingWorx Software Content Management (SCM) Extension enables customers to provide reliable software and firmware updates through package delivery and management. SCM users can create a software package that contains a file that can be downloaded to one or more devices from a ThingWorx Platform.
ThingWorx SCM enables customers to provide reliable software and firmware updates through package delivery and management. SCM users can create a software package that contains a file that can be downloaded to one or more devices from an instance of ThingWorx Platform. The SCM functionality requires installations on your ThingWorx Platform as well as use of the SCM Edge Extension in your ThingWorx Edge application. The next two sections explain these SCM components.
ThingWorx Edge SDK Side of SCM
The SCM Edge Extension for the .NET SDK supports SCM functionality for IoT Edge applications that you write using the ThingWorx Edge .NET SDK. The SCM Edge Extension is available on the THINGWORX EDGE SDK software download page with the related release of the C SDK. For the current release of the SDK and the Edge Extension, go to this page, expand Release SDKs > ThingWorx Edge SDK > Most Recent Datecode, and select to download the SCM-Extension-v-v-v-bbb package. To set up the SCM Edge Extension, refer to Setting Up SCM.
Once you have implenented the SCM Edge Extension in your Edge C SDK application, you and ThingWorx administrators can create packages that can perform software or firmware updates, using virtually any scripting language, such as node.js, Perl, Linux bash, Windows batch, Lua, and Python. Note that the executable for running the script must exist on the target devices before the package is sent. It is important to remember that when you provide a script, the script is not an executable in and of itself. Rather it must be executed by an executable that exists on the device. To designate what program should run the script, you must create a whitelist file.
ThingWorx Platform Side of SCM
The software package, ThingWorx-Software-Content-Management-v.<n.n.n>, provides the SCM utility that you can use to create, edit, test, publish, and deploy software packages to remote devices. When you use the SCM Edge Extension in your .NET application, users can run the utility provided in the ThingWorx Software Content Management (SCM) Extension. This platform-side extension is available from the THINGWORX FOUNDATION software download pages on the PTC Support site. To the current release, go to this page and expand the node for your release of ThingWorx. Then expand ThingWorx Utilities > Most Recent Datecode. Note that you must download versions of this extension and the ThingWorx Utilities Core Extension that match the version of ThingWorx Platform you are using. Install the Utilities Core Extension first and then the SCM Extension on your ThingWorx Platform.
Use Cases
The anticipated use cases for the SCM functionality include the following scenarios:
Customers need to update the firmware on devices remotely to reduce maintenance costs while maintaining control of device updates. Assets may include industrial equipment (scales, fire protection), medical devices (imaging machines), and scientific equipment (lab analysis, including mass spectrometers). SCM enables customers to push firmware updates to connected devices and execute updates on those devices.
Developers want to use a scripting language other than Lua for updating remote devices.
Customers expect the total population of devices that need updates to grow to anywhere from the high hundreds to tens of thousands, even millions.
Edge application developers can build applications that have all of the following remote firmware update capabilities:
Ability to update by any device property, including location, type, model, customer, and so on.
Ability to distribute files from the platform.
Visibility into status of firmware upgrade. For example, sending command, preparing for update, updating, update complete.
Graceful error recovery, retry, and debug capabilities.
Configuring SCM Settings at Runtime
The SCM Edge Extension provides default values for settings that are most commonly used, namely the idle timeout (300000 ms) and the staging directory for packages (./staging). The scmcfg singleton structure allows overriding the default values at runtime. The GetScmConfig() interface in the scmConfig.c and scmConfig.h files provides the structure and the macro definitions that are used for overriding the default values at run time.
Software Update Manager
The SCM client application creates a SoftwareUpdateManager that maintains a list of jobs in progress. Each job has its own id that identifies it uniquely and that must be pushed through a series of states. These states represent tasks that must be performed by the Software Update Manager, which operates independently of any Edge Thing that may be using it. These states are described in SCM State Transitions. The SCM client application must permit the registration of callbacks to end user code for notification of state changes.
Only certain states are reported back as statuses. The following table describes the reported statuses:
Job Status
Description
NONE
Initial value.
PENDING
The update is waiting to begin.
STARTED
The update has started.
COMPLETED
The update has completed successfully.
FAILED
The update failed.
Software Update Services
The client application of the SCM Edge Extension defines the following services to support the SCM Edge Thing Shape and software updates:
TriggerUpdateAction()
ScheduleDownload()
ScheduleInstall()
The TriggerUpdateAction service forces a specified job to enter a specific state on demand inside the Software Update Manager. These states are:
Abort — Places job into aborted state and cancels any long running process, such as an installation or a download.
Download — Forces the job into the Start Download state, beginning a download now.
Downloaded — Forces a job into the Downloaded state, preventing it from starting a download and allowing its installation to move forward.
Start — Creates a job. JSON payload populates job description field. The params payload looks like this:

/* A string ID used to reference this job in the future */id::"",
/* Also known as campaign name */
name"",
/* The name of the Update Manager Thing on the server */updateManager:"",
/* The name of the script file to pass to functions, */
/* or the script itself if surrounded with <> */
script:"",
/* The real path to the directory containing all of the */
/* files associated with this update*/
path:"",
/* Whitespace delimited list of params to be sent to the */ /* actual install function*/
scriptParams:{flags:["",...]}
}
The ScheduleDownload() service adds a time to a job that controls when a download can begin. When a job is created using the start action, the job is scheduled with a start time of zero. By calling this service, you can set the start time for a point in the future so that the job can progress. This service requires an id and a time field (DATETIME) as arguments.
* 
This service does not use a JSON payload.
Similarly to the ScheduleDownload() service, the ScheduleInstall() service adds a time to a job that controls when an installation can begin. In addition to the time argument (DATETIME), the ScheduleInstall() service requires an id argument.
* 
This service does not use a JSON payload.
For details about states and how a job transitions through states, refer to SCM State Transitions.
You can use software update callbacks that include the following actions from the TriggerUpdateAction service:
start()
abort()
download()
downloaded()
scheduleDownload()
scheduleInstall()
These callbacks are defined in the file, scmRuntimeApi.h, which has a corresponding scmRuntimeApi.c file. For users of the C SDK, these files should be compiled into an application that needs to communicate with SCM.
Internal methods support the following capabilities:
Decompressing a downloaded file (zip and gzip).
Reading a whitelist file for allowed executables.
Executing the software update.
Providing Feedback to the Update Manager
The ThingWorx Platform needs to know the status of each SCM job for a Thing. The statuses are tracked by a Thing called TW.RSM.SFW.SoftwareManager. The software manager services are invoked each time a transition occurs, allowing the platform to react to each change.
The services called by the remote SCM client follow:
UpdateState(ID,State) service — Notifies the platform that a job has transitioned to a new state, where:
ID (String) — The identifier of the job
State (String) — One of the established states, not as a number but as a string version of the number. The acceptable values are notified, downloading, downloaded, installing, completed, and failed.
CompleteDeliveryTarget(ID,Success,Message,Reason) service — Used to signal a final state for a job, where:
ID (String) — The identifier of the job
Success (Boolean) — True if this job completed successfully.
Message (String) — The field used to provide feedback on how this state was attained. Depending on the state, the field can contain an error message.
Reason (String) — The field used to explain how this state was attained. This field also can contain an error message.
Was this helpful?