ThingWorx SCM Edge Extension for the ThingWorx Edge .NET SDK > SCM Edge Extension Capabilities
SCM Edge Extension Capabilities
ThingWorx Software Content Management (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 the 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 Platform Side of SCM
The software package, ThingWorx-Software-Content-Management-v.<n.n.n>, is an extension for the ThingWorx Platform that provides the SCM utility that you can use to create, edit, test, publish, and deploy software packages to remote devices. This platform-side extension is available from the THINGWORX FOUNDATION software download pages on the PTC Support site. To download the current release, go to this page and expand the node for your release of ThingWorx. Then expand ThingWorx Utilities > Most Recent Version. 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.
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 .NET SDK. For the current release of the SDK and the Edge Extension, go to this page, expand Release SDKs > ThingWorx Edge SDK > Most Recent Version, and select to download the SCM-DOTNET-install package for your Windows platform (x86 or x64). To set up the SCM Edge Extension, refer to Setting Up SCM.
Once you have implemented the SCM Edge Extension in your Edge .NET application, 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.
Use Cases
The anticipated use cases for the SCM functionality include the following scenarios:
• Your 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 to update 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 upgrade capabilities:
• Ability to update by any device property, including location, type, model, customer, and so forth.
• 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 and setter functions that allow you to set different values. Instead of having to write, ScmThing.SetIdleTimeout(10000), you can write ScmThing.IdleTimeout = 10000. The following table describes the configuration settings, what you use in your code, and the corresponding setter functions to allow you to assign values:
Setting
Description
What you use
Setter Function
IdleTimeout
The number of milliseconds that a software update job may remain idle before being cleaned up. By default 30000 milliseconds.
scmThing.IdleTimeout = <number_of_milliseconds>
twScmConfig_SetIdleTimeout(idleTimeout)
StagingDir
The location for staging incoming software update packages (for example, ./staging).
scmThing.StagingDir = <./staging>
twScmConfig_setStagingDir([MarshalAs(UnmanagedType.LPStr)] string stagingDirectory)
ScriptExecutionTimeout
The number of milliseconds that a child process, such as a script, is permitted to run before it is terminated.
scmThing.ScriptExecutionTimeout = <number_of_millisesonds>
twScmConfig_SetScriptExecutionTimeout(idleTimeout)
SoftwareUpdateManager
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.
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.
The ScmThing provides four virtual functions that can be overridden in a derived class that allows for notification handling. The functions are:
• onJobStarted(string jobId)
• onJobPending(string jobId)
• onJobFailed(string jobId)
• onJobCompleted(string jobId)
Additional Features
The SCM Edge Extension provides the following additional features, which are described in the topic listed in the following table:
Feature
Description
For more information
Whitelist
A simple, comma-separated list file of the extensions of executables that are allowed to run any script enclosed in the package. The SCM Client loads this file at runtime.
Reboot persistence
Enables the restart of a device during a software update.
Digital signing (validation file)
Software update packages can be digitally signed and validated. A validation settings file can be loaded into the global validation settings for software update jobs.
Was this helpful?