|
| Lightweight Machine to Machine Technical Specification Software Management |
| Approved Version: 1.0.2 - 2021-01-19 |
| Open Mobile Alliance |
| OMA-TS-LWM2M_SwMgmt-V1_0_2-20210119-A |
| master: 25 Jan 2021 15:52:00 rev: 9b8591d |
|
|
| Lightweight Machine to Machine Technical Specification Software Management |
| Approved Version: 1.0.2 - 2021-01-19 |
| Open Mobile Alliance |
| OMA-TS-LWM2M_SwMgmt-V1_0_2-20210119-A |
| master: 25 Jan 2021 15:52:00 rev: 9b8591d |
Use of this document is subject to all of the terms and conditions of the Use Agreement located at https://www.omaspecworks.org/about/policies-and-terms-of-use/.
Unless this document is clearly designated as an approved specification, this document is a work in process, is not an approved Open Mobile Alliance™ specification, and is subject to revision or removal without notice.
You may use this document or any part of the document for internal or educational purposes only, provided you do not modify, edit or take out of context the information in this document in any manner. Information contained in this document may be used, at your sole risk, for any purposes. You may not use this document in any other manner without the prior written permission of the Open Mobile Alliance. The Open Mobile Alliance authorizes you to copy this document, provided that you retain all copyright and other proprietary notices contained in the original materials on any copies of the materials and that you comply strictly with these terms. This copyright permission does not constitute an endorsement of the products or services. The Open Mobile Alliance assumes no responsibility for errors or omissions in this document.
Each Open Mobile Alliance member has agreed to use reasonable
endeavors to inform the Open Mobile Alliance in a timely manner of
Essential IPR as it becomes aware that the Essential IPR is related to
the prepared or published specification.
However, the members do not have an obligation to conduct IPR searches.
The declared Essential IPR is publicly available to members and
non-members of the Open Mobile Alliance and may be found on the “OMA IPR
Declarations” list at https://www.omaspecworks.org/about/intellectual-property-rights/.
The Open Mobile Alliance has not conducted an independent IPR review of
this document and the information contained herein, and makes no
representations or warranties regarding third party IPR, including
without limitation patents, copyrights or trade secret rights. This
document may contain inventions for which you must obtain licenses from
third parties before making, using or selling the inventions. Defined
terms above are set forth in the schedule to the Open Mobile Alliance
Application Form.
NO REPRESENTATIONS OR WARRANTIES (WHETHER EXPRESS OR IMPLIED) ARE MADE BY THE OPEN MOBILE ALLIANCE OR ANY OPEN MOBILE ALLIANCE MEMBER OR ITS AFFILIATES REGARDING ANY OF THE IPR’S REPRESENTED ON THE “OMA IPR DECLARATIONS” LIST, INCLUDING, BUT NOT LIMITED TO THE ACCURACY, COMPLETENESS, VALIDITY OR RELEVANCE OF THE INFORMATION OR WHETHER OR NOT SUCH RIGHTS ARE ESSENTIAL OR NON-ESSENTIAL.
THE OPEN MOBILE ALLIANCE IS NOT LIABLE FOR AND HEREBY DISCLAIMS ANY DIRECT, INDIRECT, PUNITIVE, SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR EXEMPLARY DAMAGES ARISING OUT OF OR IN CONNECTION WITH THE USE OF DOCUMENTS AND THE INFORMATION CONTAINED IN THE DOCUMENTS.
THIS DOCUMENT IS PROVIDED ON AN "AS IS" "AS AVAILABLE" AND "WITH ALL FAULTS" BASIS.
Copyright 2021 Open Mobile Alliance.
Used with the permission of the Open Mobile Alliance under the terms set forth above.
This document defines the technical specification for a Software management Object, to be used in conjunction with the Lightweight M2M enabler.
| [RFC2119] | “Key words for use in RFCs to Indicate Requirement Levels”, S. Bradner, March 1997, URL:http://www.ietf.org/rfc/rfc2119.txt |
| [RFC4234] | “Augmented BNF for Syntax Specifications: ABNF”. D. Crocker, Ed., P. Overell. October 2005, URL:http://www.ietf.org/rfc/rfc4234.txt |
| [SCRRULES] | “SCR Rules and Procedures”, Open Mobile Alliance™, OMA-ORG-SCR_Rules_and_Procedures, URL:http://www.openmobilealliance.org/ |
| [OMADICT] | “Dictionary for OMA Specifications”, Open Mobile Alliance™, OMA-ORG-Dictionary-V2_9, URL:http://www.openmobilealliance.org/ |
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
All sections and appendixes, except “Scope” and “Introduction”, are normative, unless they are explicitly indicated to be informative.
| OMA | Open Mobile Alliance |
The LwM2M software management object enables remote software management in M2M devices.
V1.0 of the specification covers:
Software download
Software installation
Software deinstallation
Software activation
Software deactivation
Update state and result reporting
V1.0.2 adds the optional elements "LWM2MVersion" and "ObjectVersion" to both Software Management Objects: 9 and 14.
The Software Management process is split in 2 sub-processes: a Package Installation Process and a Software Activation Process.
The Package Installation Process is in charge of managing all the operations performed on a Package up to the final software installation in the LwM2M Client. Once the software is installed, the Software Activation Process manages the operations for authorizing or not this software to be used by the LwM2M Client.
Note: Each sub-process is governed by its own State Machine; however the Software Activation State Machine is alive only when the Package Installation State Machine is in the INSTALLED state.
The Package Installation State Machine can also be represented by the following table of transitions:
| Transition | Description | Applicable State | Post Transition State |
|---|---|---|---|
| PKG/URI Write | Start of the PKG Download Process | INITIAL | DOWNLOAD STARTED Update Result = Downloading |
| PKG Download Failed | Error during Download process | DOWNLOAD STARTED | INITIAL Update Result = error |
| PKG Written | PKG fully loaded | DOWNLOAD STARTED | DOWNLOADED Update Result = Initial |
| PKG Integrity OK | PKG successfully loaded | DOWNLOADED | DELIVERED Update Result = Initial |
| PKG Integrity not OK | PKG with Integrity failure | DOWNLOADED | INITIAL Update Result = Integrity Failure |
| Install execution | SW successfully Installed | DELIVERED | INSTALLED Update Result = SW successfully installed |
| Install execution | Installation failure | DELIVERED | DELIVERED Update Result = Software Installation failure |
| Uninstall execution | Software is de-installed | INSTALLED | INITIAL Update Result = Initial |
| Uninstall execution | Software is de-installed | DELIVERED | INITIAL Update Result unchanged |
Five states compose the Package Installation State Machine.
In the INITIAL State there is no package downloaded in the LwM2M Device. In that State, the Package Installation State Machine is waiting for the event, which will trigger the process of downloading a new package in the device. The Update Result would be set to 0 at this stage and Update State would be INITIAL.
This event is generated by the Server in uploading some data in the SwMgmt Object Instance. The target of this upload could be:
That event will trigger the transition from INITIAL State to DOWNLOAD STARTED State.
The State Machine enters the DOWNLOAD STARTED state from the INITIAL State when the process of loading a new package in the device is triggered, and stays in that State as long as the downloading process is on-going, and no error occurs during that downloading process.
In that state, the “Update Result” resource contains the Downloading value.
If any error occurs during this phase, the State Machine exits this DOWNLOAD STARTED state and returns back to the INITIAL State (Faulty package is removed); in that case the “Update Result” resource contains the code identifying which error has occurred (range from 3 to 9).
The State Machine enters the DOWNLOADED state from the DOWNLOAD STARTED State when the process of loading a new package in the device is finished (Package is fully written)
In that state, the “Update Result” resource is reset to the Initial value (i.e. 0).
The transition from this DOWNLOADED State to the DELIVERED State will automatically occur when the integrity of the loaded Package is successfully verified.
If the Package Integrity Check fails, the State Machine exits this state and returns back to the INITIAL State (Faulty package is removed); in that case the “Update Result” resource contains the code identifying the error (i.e. Integrity check failure value).
To enter that state the package MUST have been successfully loaded at the DOWNLOADED State (Integrity of the downloaded package has been successfully verifyed) The transition from this DELIVERED State to the INSTALLED State occurs when the Install resource is triggered, and the installation process is successful.
If any error occurs during the installation, the Package Installation State Machine remains in the DELIVERED State and the “Update Result” resource contains the code identifying which error has occurred (range from 3 to 9).
The transition from this DELIVERED state to the INITIAL State occurs when the Uninstall resource is triggered, the package is then removed from the LwM2M Device, and the Update Result resource is set to the Initial value (i.e; 0).
In that the state, the software has been successfully installed from the downloaded package, As long as the State Machine remains in that state, the “Update Result” resource contains the “Software successfully installed” value, and the Software Activation sub-process is validated.
When the Uninstall resource is triggered, there is a transition back to the INITIAL State, the package is removed from the LwM2M Device, the Update Result resource is reset to theIinitial value 0, and the Software Activation sub-process is devalidated.
Two executable resources have been defined for implementing the Software Install and Uninstall operations.
This Executable Install resource aims at triggering the software installation from the downloaded package when the State Machine is in DELIVERED State.
When the software installation is successful, the transition from the DELIVERED State to the INSTALLED State is performed and the “Update Result” resource is set to the “Software successfully installed” value.
When the State Machine is not in DELIVERED state, executing that Install resource has no effect. When this installation fails, the Package Installation State Machine remains in the DELIVERED State and the “Update Result” resource contains the code identifying which error has occurred (range from 3 to 9).
Install Executable Resource can be used to install the Software from scratch, or to upgrade a Software already in place with the content of the last Downloaded Package
This Executable Uninstall resource aims at preparing the LwM2M Client to receive a new Package for Installation; When the Uninstall resource is executed, the Package InstallationState Machine performs a transition back to the INITIAL State and the Update Result is reset to the initial value 0. When this command is used with an argument “ForUpdate” (argument=1), the LwM2M Client is prepared to receive a new Package which will be used to upgrade the Software already in place. When this Resource is Executed without Argument (or argument=0), the Package is removed from the LwM2M Device.Triggering this Uninstall resource whereas the Package InstallationState Machine is neither in INSTALLED State nor in DELIVERED State, will produce no effect.
The Sofware Activation State Machine is alive only when the Package Installation State Machine is in the INSTALLED State.
When the Software Activation State Machine is not alive, no transition inside this State Machine is allowed.
When the Package InstallationState Machine enters the INSTALLED State, the current state of the Software Activation State is set to INACTIVE State.
The Software Activation State Machine is defined by:
When the current state is set to INACTIVE, the LwM2M Client MUST NOT use the installed software.
When the current state is set to ACTIVE, the installed software can be used by the LwM2M Client.
The transition from the INACTIVE State to the ACTIVE State occurs when the Activate Executable Resource is triggered.
The transition from the ACTIVE State to the INACTIVE State occurs when the Deactivate Executable Resource is triggered.
The Activation State resource is set accordingly: ENABLED when the Activation State Machine is at ACTIVE, DISABLED when either the Activation State Machine is at INACTIVE or this State Machine is not alive.
It could be desirable to deliver multiple Software Components in a single download operation depending on various constraints in the network and devices. The Software Update Package abstraction represents platform specific package formats used to deliver Software Components to the Device. A single Software Update Package MAY contain one or more Deployment Components.
The Object for Software Component provides a generic ability to bring in one to many relationships between Software Management Object tree and Software Component Object tree.
Description
This LwM2M objects provides the resources needed to perform software management on the device. Each software component is managed via a dedicated Software Management Object instance.
Object definition
| Name | Object ID | Object Version | LWM2M Version |
| LWM2M Software Management | 9 | 1.0 | 1.0 |
| Object URN | Instances | Mandatory | |
| urn:oma:lwm2m:oma:9 | Multiple | Optional | |
Resource definitions
| ID | Name | Operations | Instances | Mandatory | Type | Range or Enumeration | Units | Description |
|---|---|---|---|---|---|---|---|---|
| 0 | PkgName | R | Single | Mandatory | String | 0..255 bytes | Name of the software package | |
| 1 | PkgVersion | R | Single | Mandatory | String | 0..255 bytes | Version of the software package | |
| 2 | Package | W | Single | Optional | Opaque | Software package The package can be in one single software component, or any delivery material used by the Device to determine the software component(s) and proceed to their installation. Can be archive file, executable, manifest. This resource to be used when it is single block of delivery. | ||
| 3 | Package URI | W | Single | Optional | String | 0..255 bytes | URI from where the device can download the software package by an alternative mechanism. As soon the device has received the Package URI it performs the download at the next practical opportunity. Can be direct link to a single software component or link to archive file, executable, or manifest, used by the Device to determine, then access to the software component(s). This resource to be used when it is single block of delivery. | |
| 4 | Install | E | Single | Mandatory | Installs software from the package either stored in Package resource, or, downloaded from the Package URI. This Resource is only executable when the value of the State Resource is DELIVERED. | |||
| 5 | Checkpoint | R | Single | Optional | Objlnk | Link to a "Checkpoint" object which allows to specify conditions/dependencies for a software update. E.g. power connected, sufficient memory, target system. | ||
| 6 | Uninstall | E | Single | Mandatory | Uninstalls the software package. This executable resource may have one argument. If used with no argument or argument is 0, the Package is removed i from the Device. If the argument is 1 ("ForUpdate"), the Client MUST prepare itself for receiving a Package used to upgrade the Software already in place. Update State is set back to INITIAL state. | |||
| 7 | Update State | R | Single | Mandatory | Integer | 0..4 | Indicates current state with respect to this software update. This value is set by the LwM2M Client. 0: INITIAL Before downloading. (see 5.1.2.1) 1: DOWNLOAD STARTED The downloading process has started and is on-going. (see 5.1.2.2) 2: DOWNLOADED The package has been completely downloaded (see 5.1.2.3) 3: DELIVERED In that state, the package has been correctly downloaded and is ready to be installed. (see 5.1.2.4) If executing the Install Resource failed, the state remains at DELIVERED. If executing the Install Resource was successful, the state changes from DELIVERED to INSTALLED. After executing the UnInstall Resource, the state changes to INITIAL. 4: INSTALLED In that state the software is correctly installed and can be activated or deactivated according to the Activation State Machine. (see 5.1.2.5) | |
| 8 | Update Supported Objects | RW | Single | Optional | Boolean | If this value is true, the LwM2M Client MUST inform the registered LwM2M Servers of Objects and Object Instances parameter by sending an Update or Registration message after the software update operation at the next practical opportunity if supported Objects in the LwM2M Client have changed, in order for the LwM2M Servers to promptly manage newly installed Objects. If false, Objects and Object Instances parameter MUST be reported at the next periodic Update message. The default value is false. | ||
| 9 | Update Result | R | Single | Mandatory | Integer | 0..200 | Contains the result of downloading or installing/uninstalling the software 0: Initial value. Prior to download any new package in the Device, Update Result MUST be reset to this initial value. One side effect of executing the Uninstall resource is to reset Update Result to this initial value "0". 1: Downloading. The package downloading process is on-going. 2: Software successfully installed. 3: Successfully Downloaded and package integrity verified (( 4-49, for expansion, of other scenarios)) 50: Not enough storage for the new software package. 51: Out of memory during downloading process. 52: Connection lost during downloading process. 53: Package integrity check failure. 54: Unsupported package type. 56: Invalid URI 57: Device defined update error 58: Software installation failure 59: Uninstallation Failure during forUpdate(arg=0) 60-200 : (for expansion, selection to be in blocks depending on new introduction of features) This Resource MAY be reported by sending Observe operation. | |
| 10 | Activate | E | Single | Mandatory | This action activates the software previously successfully installed (the Package Installation State Machine is currently in the INSTALLED state) | |||
| 11 | Deactivate | E | Single | Mandatory | This action deactivates softwareif the Package Installation State Machine is currently in the INSTALLED state. | |||
| 12 | Activation State | R | Single | Mandatory | Boolean | Indicates the current activation state of this software: 0: DISABLED Activation State is DISABLED if the Software Activation State Machine is in the INACTIVE state or not alive. 1: ENABLED Activation State is ENABLED only if the Software Activation State Machine is in the ACTIVE state | ||
| 13 | Package Settings | RW | Single | Optional | Objlnk | Link to "Package Settings" object which allows to modify at any time software configuration settings. This is an application specific object. Note: OMA might provide a template for a Package Settings object in a future release of this specification. | ||
| 14 | User Name | W | Single | Optional | String | 0..255 bytes | User Name for access to SW Update Package in pull mode. Key based mechanism can alternatively use for talking to the component server instead of user name and password combination. | |
| 15 | Password | W | Single | Optional | String | 0..255 bytes | Password for access to SW Update Package in pull mode. | |
| 16 | Status Reason | R | Single | Optional | String | Contains the status of the actions done by the client on the SW Component(s) referred by the present SW Update Package. The status is defined in Appendix B. | ||
| 17 | Software Component Link | R | Multiple | Optional | Objlnk | Reference to SW Components downloaded and installed in scope of the present SW Update Package Note: When resource 17 objlink exist, resources 2, 3 and 12 in this table are ignored. | ||
| 18 | Software Component tree length | R | Single | Optional | Integer | 0..255 | Software Component tree length indicates the number of instances existing for this software package in the Software Component Object. |
Software Update Consideration
If some Objects are not supported after software update, the LwM2M Client MUST delete all the Object Instances of the Objects that are not supported.
Description
If some Objects are not supported after software update, the LwM2M Client MUST delete all the Object Instances of the Objects that are not supported.
Object definition
| Name | Object ID | Object Version | LWM2M Version |
| LWM2M Software Component | 14 | 1.0 | 1.0 |
| Object URN | Instances | Mandatory | |
| urn:oma:lwm2m:oma:14 | Multiple | Optional | |
Resource definitions
| ID | Name | Operations | Instances | Mandatory | Type | Range or Enumeration | Units | Description |
|---|---|---|---|---|---|---|---|---|
| 0 | Component Identity | R | Single | Optional | String | 0..255 bytes | Name or identifier of the software component | |
| 1 | Component Pack | R | Single | Optional | Opaque | Software components is stored in this resource | ||
| 2 | Component Version | R | Single | Optional | String | 0..255 bytes | Version of the software component. | |
| 3 | Activate | E | Single | Optional | This action activates the software previously successfully installed (the SW Update Package Installation State Machine is currently in the INSTALLED state). | |||
| 4 | Deactivate | E | Single | Optional | This action deactivates software if the SW Update Package Installation State Machine is currently in the INSTALLED state. | |||
| 5 | Activation State | R | Single | Optional | Boolean | Indicates the current activation state of this software component: 0: DISABLED Activation State is DISABLED if the Software Component Activation State Machine is in the INACTIVE state or not alive. 1: ENABLED Activation State is ENABLED only if the Software Component Activation State Machine is in the ACTIVE state. |
| Reference | Date | Description |
|---|---|---|
| OMA-TS-LWM2M_SwMgmt-V1_0-20180301-A | 01 Mar 2018 | Status changed to Approved by BoD Doc Ref # OMA-DM-2018-0014-INP_LwM2M_Object_Software_Management_V1_0_RRP_Final_Approval |
| OMA-TS-LWM2M_SwMgmt-V1_0_1-20200616-A | 16 Jun 2020 | Editorial updates to rectify validation errors. |
| OMA-TS-LWM2M_SwMgmt-V1_0_2-20210119-A | 19 Jan 2021 | Document agreed by DMSE WG on January 19th and ratified by BoD Meeting on 25th Jan 2021 |
| Value | State | Description |
|---|---|---|
| 10 | Idle/Start | There is no data available and download is about to start |
| 20 | Download failed | Download failed and there is No data received |
| 30 | Download Progressing | Denotes that a download has started and that 0 or more bytes of data have been downloaded |
| 40 | Download Complete | Have data after Download has been completed successfully |
| 50 | Install Progressing | Denotes that an installation has started |
| 60 | Install Failed with data | Install failed and the downloaded package is still in the Device |
| 70 | Install Failed without data | Install failed and the downloaded package is deleted |