Lightweight M2M – Device Capability management Object (LwM2M Object - DevCapMgmt)

Approved Version: 1.0.4 - 2020-12-08

Open Mobile Alliance

OMA-TS-LWM2M_DevCapMgmt-V1_0_4-20201208-A

master: 26 Jan 2021 12:13:00 rev: 15bc3de

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.

1. Scope

This document defines the technical specification for an Object to be used in conjunction with the Lightweight M2M enabler in order to manage Device Capability on the Device.

2. References

2.1. Normative References

2.2. Informative References

3. Terminology and Conventions

3.1. Conventions

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.

3.2. Definitions

3.3. Abbreviations

4. Introduction and Scope

M2M devices may support advanced features, such as various Sensors, various Controls, capabilities on Communication, on Visio, and even more. Use case could be to address the need of remotely adapting the M2M Device Capability according to a given level of subscription; in many circumstances also, Enterprises, regulations and others, have policies against the usage of some features but allow the use of other features available on such a M2M Device.

Device Capability Management aims at specifying the mechanisms required for the remote management of device capabilities, i.e. not only addressing the ability of remotely enable and disable device capabilities, but also to expose to Servers the capabilities of removable hardware when attached to the device.

The objective of this document is to specify an LWM2M object which allows to enable remote management of M2M device capabilities.

4.1. Version 1.0

4.1.1. Version 1.0.1

4.1.2. Version 1.0.2

4.1.3. Version 1.0.3

4.1.4. Version 1.0.4

Update TS to be aligned with SUP file.

5. Device Capability Management Functionality

The following basic device capability management functionalities can be considered:

1. Enablement/Disablement of a given LwM2M Device capability
2. Exposure of removable hardware capability of the LwM2M Device

5.1. LwM2M Device Capability general properties

The Group Resource specifies which kind of LwM2M Device Capability on this Device, is likely to be managed: 9 basic groups are identified for LwM2M Devices. Any LwM2M Device Capability should refer to one of the following categories:

• SENSOR dedicated to acquire data on physical events
• CONTROL dedicated to adjust various levels
• CONNECTIVITY dedicated to provide Communication capability
• NAVIGATION dedicated to provide geo localisation capability
• STORAGE dedicated to provide memory capability
• VISION dedicated to provide vision capability : video capability , photo capability
• SOUND dedicated to provide sound capability : buzzer, speaker
• ANALOG INPUT refers to a generic analog input capability
• ANALOG OUTPUT refers to a generic analog output capability

Property Resource is a list of LwM2M capabilities within a given Group, which can be managed together (Enable/Disable) in the device.

The Vocabulary List of Group and Properties are provided in 0.

Description Resource just provides Device Manufacturer Text informations relative to a given Instance of the Device Capability Object.

5.2. LwM2M Device Capability Disable/Enable functionality

To be operational on a LwM2M Device, a manageable Device Capability MUST be in the ‘Enabled’ State which is reflected by the 'Enabled' resource set to ‘True’.

The opEnable and opDisable Resource used as commands by the LwM2M Server, MUST respectively transfer the Device Capability State to ‘Enabled’ and ‘Disabled’ state.

When a LwM2M Device Capability "Enabled" resource is under "Observation" ("OBSERVE" command [LwM2M]), the notification of the value change MUST be reported ("NOTIFY" command: [LwM2M]) to the Server, only if the value of “NotifyEn” Resource was set to ‘True’.

5.3. LwM2M Device Capability Attachment and Exposure functionalities.

Hardware may be not permanently present on a device. It can be plugged to and removed from a device. When a removable hardware is plugged on a LwM2M device, the Device has to "attach" that new hardware before being able to use it. When this Device attachment operation is successful, the LwM2M Client MUST set to ‘True’, the "Attached" Resource value of the associated LwM2M Device Capability Instance.

When the removable hardware is unplugged from the Device, the LwM2M Client MUST set to ‘False’ the “Attached” Resource value.

If the Notification capability is enable (NotifyEn set to ‘True’), and the "Attached" Resource is under "Observation", the Server MUST be notified (through the "NOTIFY" operation) when the "Attached" Resource state changed.

This "Attached" resource is optional, so when this resource is not present in a Device Capability Instance, it means this Device Capability Instance doesn’t manage removable hardware.

When the "Attached" resource is present in a Device Capability Instance and there is no removable associated to it, the "Attached" resource value MUST be permanently set to ‘True’.

For being operational on a Device, a manageable and removable Hardware MUST have its associated Device Capability Resources "Attached" and "Enabled" both set to ‘True’.

6. LwM2M Object: Device Capability Management

Description

This LWM2M Object is dedicated to manage the device capabilities of a device e.g. sensors, communication, etc.

Object definition

Resource definitions

7. Device Capability Management JSON Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Device Capability Management",
    "description": " DevCapability ",
    "type": "object",
    "properties": {
        "Property": {
                         "description": "A list of Device Capabilities",
                         "type": "string",
                         "readonly": true
                 },
        "Group": {
                         "description": "Device Capabilities categories ",
               "type": "integer",
                          "enum": [SENSOR, CONTROL, CONNECTIVITY,NAVIGATION,STORAGE, VISION,
                                  ANALOG_INPUT, ANALOG_OUTPUT],
                          "readonly": true
        },
        "Description": {
            "description": "Manufacturer-specified string",
            "type": "string",
                            "readonly": true
        },
        "Attached": {
            "description": "Used for removable hardware capability",
            "type": "boolean",
                            "readonly": true
        },
        "Enabled": {
            "description": "Specifies if a Device Capability is operational",
            "type": "boolean",
                            "readonly": true
        },
        "opEnable": {
            "description": "Operation for enabling a Device Capability",
            "type": "boolean",
                            "writeonly": true
        },
        "opDisable": {
            "description": "Operation for disabling a Device Capability",
            "type": "boolean",
                            "writeonly": true
        },
        "NotifyEn": {
            "description": "Allow to Notify a Server when the Device Capability
                                            Enabled State is changing",
            "type": "boolean",
                            "writeonly": true
        },
    },
    "required": ["Property","Group","Enabled","OpEnable", "OpDisable"]
}

Appendix A. Change History (Informative)

A.1 Approved Version History

Appendix B. Device Capabilities Vocabulary

Note: To each Property is associated 2 ID’s range:

• [0x00-0x7F] range is allocated in that specification according to the table above,
• [0x80-0xFF] range is available to the Device Manufacturer (proprietary property ID Range) if no pre-defined property is appropriate for a specific Device capability.