ThingWorx SCM Edge Extension for the ThingWorx Edge C SDK > SCM Edge Extension Capabilities
SCM Edge Extension Capabilities
The ThingWorx 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.
The extension package, ThingWorx-Software-Content-Management-v.v.v.v, provides the SCM utility that you can use to create, edit, test, publish, and deploy software packages to remote devices. Previously, the SCM utility worked only with the ThingWorx WebSocket-based Edge MicroServer (WS EMS) and supported only the Lua scripting language. With the first release of the SCM Edge Extension for the ThingWorx Edge C SDK, support was extended to that SDK.
Using the latest release of the C SDK, the SCM Edge Extension for the C SDK, the ThingWorx SCM Extension, and ThingWorx Asset Advisor, you can create packages that will execute 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 be available on the target devices. 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 on the device. To designate what program will run the script, you must create a whitelist file. Release 1.0.1 adds the ability for SCM operations to survive a client reboot. See for details
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 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 update 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, 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 Software Update Manager 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. The SCM client application must permit the registration of callbacks to end user code for notification of state changes.
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:
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, 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 */
/* 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 <> */
/* The real path to the directory containing all of the */
/* files associated with this update*/
/* Whitespace delimited list of params to be sent to the */ /* actual install function*/
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. Calling this service allows the start time to be set 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.
The ScheduleInstall() service is similar to the ScheduleDownload() service in that it adds a time to a job that controls when installation can begin. In addition, it requires an id and a time field (DATETIME) as arguments and does not use a JSON payload.
This service does not use a JSON payload.
For details about states and how a job transitions through states, see SCM State Transitions.
Software update callbacks are supported and include the following actions from the TriggerUpdateAction service:
These callbacks are defined in the file, scmRuntimeApi.h, which has a corresponding .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:
Decompress a downloaded file (zip and gzip).
Read a whitelist file for allowed executables.
Execute the software update.
Providing Feedback to the Update Manager
The ThingWorx platform needs to know which state each job for your Thing is in. The states are tracked by a Thing called TW.RSM.SFW.SoftwareManager. The software manager gets its services invoked each time a state transition occurs, allowing the platform to react to each state 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) — Field used to provide feedback on how this state was attained. It could be an error message.
Reason (String) — Field used to provide feedback on how this state was attained. It could be an error message.