OpenMTC

SDK - The low-level CSE Client

Introduction

The OpenMTC SDK offers a client module for low-level access to the oneM2M resource tree exposed by a CSE's reference point. Currently, only the http and https protocols are supported. Basically, there are different types of Common Service Entities (CSE):

  • MN-CSE: Middle Node CSE (OpenMTC Gateway)
  • IN-CSE: Infrastructure Node CSE (OpenMTC Backend) The client module comprises classes for representing requests, responses as well as classes that provide an abstraction for a connection to a CSE's reference point (the actual client itself).

Requests

Requests to a CSE are called a OneM2MRequest. The OpenMTC SDK provides this class for representing the different types of requests that can be issued towards a CSE. This class resides under the openmtc_onem2m.transport package. The following requests (OneM2MOperation) are available:

  • retrieve
  • delete
  • create
  • notify
  • update

OneM2MRequest - Retrieve

The most trivial case of a OneM2MRequest is the retrieve. It takes the path of the resource to be retrieved as parameter upon construction. This file can be found here.


# Example 3: Retrieve OneM2MRequest
from openmtc_onem2m.transport import OneM2MRequest
request = OneM2MRequest("retrieve", to="onem2m")
print request.to
#>>> onem2m

OneM2MRequest - Delete

Like the retrieve OneM2MRequest, a delete OneM2MRequest merely takes the path of the resource to be deleted as parameter upon construction. This file can be found here.


# Example 4: Delete OneM2MRequest
from openmtc_onem2m.transport import OneM2MRequest
request = OneM2MRequest("delete", to="onem2m")
print request.to
#>>> onem2m

OneM2MRequest - Create

When creating a create OneM2MRequest object we need to specify the object to be created together with the path where it is to be created. In most cases this is done by creating an appropriate resource object and passing it. This file can be found here.


# Example 5a: Create OneM2MRequest
from openmtc_onem2m.transport import OneM2MRequest
from openmtc_onem2m.model import AE
my_app = AE(App_ID="myApp")
request = OneM2MRequest("create", to="onem2m", pc="my_app")
print request.to
#>>> onem2m
print request.pc
#>>> myApp

When creating contentInstances, we can also pass in a string of raw data. In this case, we also need to specify the mime-type of the data via the resource_type parameter (ty). This file can be found here.


# Example 5b: Create OneM2MRequest with data
from openmtc_onem2m.transport import OneM2MRequest
import json
sensor_data = {"type": "temperature",
               "value": 15 }
data_string = json.dumps(sensor_data)
request = OneM2MRequest("create", 
                        to="onem2m",
                        pc=data_string,
                        ty="application/json")
print request.to
#>>> onem2m
print request.pc
#>>> {"type": "temperature", "value": 15}

OneM2MRequest - Notify

For notify OneM2MRequest objects the same semantics as for create OneM2MRequest apply. This file can be found here.


# Example 6a: Notify OneM2MRequest
from openmtc_onem2m.transport import OneM2MRequest
from openmtc_onem2m.model import AE
my_app = AE(App_ID="myApp")
request = OneM2MRequest("notify", to="onem2m", pc=my_app)
print request.to
#>>> onem2m
print request.pc.App_ID
#>>> myApp

This file can be found here.


# Example 6b: Notify OneM2MRequest with data
from openmtc_onem2m.transport import OneM2MRequest
import json
sensor_data = {"type": "temperature",
               "value": 15 }
data_string = json.dumps(sensor_data)
request = OneM2MRequest("create", 
                        to="onem2m",
                        pc=data_string,
                        ty="application/json")
print request.to
#>>> onem2m
print request.pc
#>>> {"type": "temperature", "value": 15}

OneM2MRequest - Update

The update OneM2MRequest can be used to update specific attributes of an object (AE). If the request is legal, four different cases are distinguished:

  • If an attribute value is provided in the OneM2MRequest that exists in the target resource, the CSE will simply update that attribute in the resource representation.
  • If an attribute is not provided in the OneM2MRequest, but the attribute exists in the target resource, the hosting CSE will simply leave the value of that attribute unchanged.
  • If an attribute is provided in the OneM2MRequest and does not exist in the target resource, the hosting CSE will create such attribute with the provided value.
  • If an attribute is set to NULL in the OneM2MRequest and exists in the target resource, the hosting CSE will delete such attribute if the deletion of the attribute is allowed by the local policy. The following example shows the creation of a update OneM2MRequest. The CSE would either update the attribute (labels) in the resource representation if it exists already exists there, or create the attribute labels with the provided value if it does not exist in the CSE resource representation yet. This file can be found here.

# Example 7: Update OneM2MRequest
from openmtc_onem2m.transport import OneM2MRequest
from openmtc_onem2m.model import AE
my_app = AE(App_ID="myApp", labels=["keyword1", "keyword2"])
request = OneM2MRequest("update", to="onem2m", pc=my_app.labels)
print request.to
#>>> onem2m
print request.pc
#>>> [u'keyword1', u'keyword2']

Responses

Upon servicing a request, a CSE will return a OneM2MResponse, which is a class of the client module. This class is defined in the openmtc_onem2m.transport module and derives from the object base class. The following response types are possible:

  • Create
  • Retrieve
  • Update
  • Delete
  • Notify
  • Execute
  • Observe An OneM2MResponse has the following properties:
  • status_code - Denotes the result status of the operation (see below).
  • request - The type of the operation. One of (create, retrieve, update, delete, notify, execute, observe).
  • rqi - Denotes the request identifier (requestIdentifier).
  • pc - Denotes the resource content (primitiveContent).
  • to - Denotes to destination of the response.

Error Responses

If an error occurs on the CSE servicing the request, the CSE will return a OneM2MErrorResponse. Note that the OneM2MErrorResponse class is an Exception. In case that any error is reported by the CSE during processing a request, the client will raise an instance of OneM2MErrorResponse. The OneM2MErrorResponse heritates from the classes OneM2MResponse and OneM2MError (OpenMTCError) and is not yet implemented (pass).

Status Codes

The status_code of OneM2MResponse objects are defined as constants in the openmtc_onem2m.exc module. The following constants are defined:

STATUSnumeric_codehttp_status_code
STATUS_ACCEPTED1000202
STATUS_OK2000200
STATUS_CREATED2001201
STATUS_BAD_REQUEST4000400
STATUS_NOT_FOUND4004404
STATUS_OPERATION_NOT_ALLOWED4005405
STATUS_REQUEST_TIMEOUT4008408
STATUS_SUBSCRIPTION_CREATOR_HAS_NO_PRIVILEGE4101403
STATUS_CONTENTS_UNACCEPTABLE4102400
STATUS_ACCESS_DENIED4103403
STATUS_GROUP_REQUEST_IDENTIFIER_EXISTS4104409
STATUS_CONFLICT4015409
STATUS_INTERNAL_SERVER_ERROR5000500
STATUS_NOT_IMPLEMENTED5001501
STATUS_TARGET_NOT_REACHABLE5103404
STATUS_NO_PRIVILEGE5105403
STATUS_ALREADY_EXISTS5106403
STATUS_TARGET_NOT_SUBSCRIBABLE5203403
STATUS_SUBSCRIPTION_VERIFICATION_INITIATION_FAILED5204500
STATUS_SUBSCRIPTION_HOST_HAS_NO_PRIVILEGE5205403
STATUS_NON_BLOCKING_REQUEST_NOT_SUPPORTED5206501
STATUS_EXTERNAL_OBJECT_NOT_REACHABLE6003404
STATUS_EXTERNAL_OBJECT_NOT_FOUND6005404
STATUS_MAX_NUMBER_OF_MEMBER_EXCEEDED6010400
STATUS_MEMBER_TYPE_INCONSISTENT6011400
STATUS_MANAGEMENT_SESSION_CANNOT_BE_ESTABLISHED6020500
STATUS_MANAGEMENT_SESSION_ESTABLISHMENT_TIMEOUT6021500
STATUS_INVALID_CMDTYPE6022400
STATUS_INVALID_ARGUMENTS6023400
STATUS_INSUFFICIENT_ARGUMENT6024400
STATUS_MGMT_CONVERSION_ERROR6025500
STATUS_CANCELLATION_FAILED6026500
STATUS_ALREADY_COMPLETE6028400
STATUS_COMMAND_NOT_CANCELLABLE6029400

Exceptions

In addition to raising an instance of OneM2MErrorResponse, the CSE client might also inidcate error conditions that do not occur while the CSE was processing the request. This will mainly happen when the client was unable to contact the CSE for whatever reason. Exeptions that are raised will be subclasses of the OpenMTCError class defined in the openmtc.exc module.

Using the Client

The client implementation for interfacing with the HTTP interface of an CSE resides in the openmtc_onem2m.client.http module. The implementing class is called OneM2MHTTPClient. In the current version of the SDK, we simply import the class directly. This is planned to be replaced with a more sophisticated factory pattern that creates appropriate clients based on the transport scheme (e.g. http or mqtt) that is used. Client objects expose a method called send_onem2m_request for sending OneM2MRequest objects to a CSE.

Creating a Client

To create a client object, we simply import the OneM2MHTTPClient class from the openmtc_onem2m.client.http module and create an instance of it with the URI of a reference point of an oneM2M CSE. This file can be found here.


# Example 8a: Creating a Client
from openmtc_onem2m.client.http import OneM2MHTTPClient
# create a OneM2MHTTPClient object
client = OneM2MHTTPClient("http://localhost:8000", False)

Making Requests

To retrieve a resource from the CSE's resource tree, we can use the send_onem2m_request method and pass an appropriate OneM2MRequest object. In this case we retrieve the CSEBase resource of the CSE's resource tree. If successful, the operation returns a promise, which contains an OneM2MResponse object. The OneM2MResponse can be obtained from the promise by using .get(). The content property of the OneM2MResponse holds the appropriate CSEBase object. This file can be found here.


# Example 8b: Making Requests
from openmtc_onem2m.client.http import OneM2MHTTPClient
from openmtc_onem2m.transport import OneM2MRequest
# create a OneM2MHTTPClient object
client = OneM2MHTTPClient("http://localhost:8000", False)
# create a OneM2MRequest object
onem2m_request = OneM2MRequest("retrieve", to="onem2m")
# send the OneM2MRequest to the CSE
promise = client.send_onem2m_request(onem2m_request)
# reteive the OneM2MResponse from the returned promise
onem2m_response = promise.get()
print onem2m_response.to
#>>> onem2m
print onem2m_response.response_status_code
#>>> STATUS(numeric_code=2000, description='OK', http_status_code=200)
print onem2m_response.content
#>>> CSEBase(path='None', id='cb0')

Note: This example (and most of the following ones) will only work as shown, if a gateway instance is running in the background of the localhost. This can be launched by running the openmtc-open-source/openmtc-gevent/run_gateway script. To create a resource on the CSE, we first create the desired resource object and then send a create OneM2MRequest. In the following example, we will add the optional pararmeter resourceName="MYAPP" to the creation of the AE in order to facilitate the retrieval of this AE in the browser. After execution of the example (and the condition to have running CSE on the localhost) the created AE on the CSE should be retrievable at URL http://localhost:8000/onem2m/MYAPP in a browser on the localhost. Further, we add the mandatory parameter requestReachability=False which states, that the created AE should have no server capability and therefore no reachability for other instances. For a create OneM2MRequest, there are two additional parameters: ty=AE indicates that the resource that should be created on the CSE is of type AE (ApplicationEntity). The statement pc=my_app specifies what resource should be created on the CSE. In this case, it is the AE created previously. This file can be found here.


# Example 10: Create a resource
from openmtc_onem2m.model import AE
from openmtc_onem2m.client.http import OneM2MHTTPClient
from openmtc_onem2m.transport import OneM2MRequest
# create a OneM2MHTTPClient object
client = OneM2MHTTPClient("http://localhost:8000", False)
# create a resource to be created on the CSE
# resourceName: (optional) for easy check in browser
# requestReachability: (mandatory) for servercapability of the AE
my_app = AE(App_ID="myApp", 
            labels=["keyword1", "keyword2"], 
            resourceName="MYAPP", 
            requestReachability=False)
# create a OneM2MRequest object of type 'create'
# ty: resource_type of the created resource
# pc: Resource content to be transferred
onem2m_request = OneM2MRequest("create", to="onem2m", ty=AE, pc=my_app)
# send the 'create' OneM2MRequest to the CSE
promise = client.send_onem2m_request(onem2m_request)
# reteive the OneM2MResponse from the returned promise
onem2m_response = promise.get()
print onem2m_response.to
#>>> onem2m
print onem2m_response.response_status_code
#>>> STATUS(numeric_code=2001, description='CREATED', http_status_code=201)
print onem2m_response.content
#>>> AE(path='None', id='ae0')
print onem2m_response.content.App_ID
#>>> myApp
print onem2m_response.content.labels
#>>> [u'keyword1', u'keyword2']

Note: If this example throws a OneM2MErrorResponse with response_status_code: STATUS(numeric_code=4015, description='CONFLICT', http_status_code=409), then the resourceName might already be registered at the CSE. Try to alter the resourceName. ResourceNames need to be unique on the CSE. Alternatively, the running CSE process can be terminated and restarted. This avoids the need to change the resourceName. Note: At this point the application object has been created in the CSE's resource tree. However, the original object we created in our program (my_application) has not been altered in any way. Specifically, it does not contain any attributes that may have been set or altered by the CSE, nor has its path property been set. If we want to continue working with the application object it is good practice to retrieve the object again through the resourceName. This file can be found here.


# Example 11a: Create a resource (continued)
from openmtc_onem2m.model import AE
from openmtc_onem2m.client.http import OneM2MHTTPClient
from openmtc_onem2m.transport import OneM2MRequest
client = OneM2MHTTPClient("http://localhost:8000", False)
my_app = AE(App_ID="myApp", 
            labels=["keyword1", "keyword2"], 
            resourceName="MYAPP1", 
            requestReachability=False)
onem2m_request = OneM2MRequest("create", to="onem2m", ty=AE, pc=my_app)
promise = client.send_onem2m_request(onem2m_request)
onem2m_response = promise.get()
print onem2m_response.response_status_code
#>>> STATUS(numeric_code=2001, description='CREATED', http_status_code=201)
# Build path to retieve from
path = "onem2m/" + onem2m_response.content.resourceName
print path
#>>> onem2m/MYAPP
# Retrieve the AE from the CSE
onem2m_request = OneM2MRequest("retrieve", to=path)
promise = client.send_onem2m_request(onem2m_request)
onem2m_response = promise.get()
print onem2m_response.response_status_code
#>>> STATUS(numeric_code=2000, description='OK', http_status_code=200)
print onem2m_response.content
#>>> AE(path='None', id='ae0')
# Set the local AE to the retrieved content
my_app = None
my_app = onem2m_response.content
print my_app.App_ID
#>>> myApp
print my_app.resourceName
#>>> MYAPP
print my_app.labels
#>>> [u'keyword1', u'keyword2']

Note: Again, if this example throws a OneM2MErrorResponse with response_status_code: STATUS(numeric_code=4015, description='CONFLICT', http_status_code=409), then the resourceName might already be registered at the CSE. Try to alter the resourceName. Alternatively, the running CSE process can be terminated and restarted. This avoids the need to change the resourceName. The following example showcases how to update some fields using OneM2MRequest update. This file can be found here.


# Example 11b: Updating a resource using OneM2MRequest Update
from openmtc_onem2m.model import AE
from openmtc_onem2m.client.http import OneM2MHTTPClient
from openmtc_onem2m.transport import OneM2MRequest
client = OneM2MHTTPClient("http://localhost:8000", False)
my_app = AE(App_ID="myApp", 
            labels=["keyword1", "keyword2"], 
            resourceName="MYAPP2", 
            requestReachability=False)
# Create the AE 'my_app' at the CSE
onem2m_request = OneM2MRequest("create", to="onem2m", ty=AE, pc=my_app)
promise = client.send_onem2m_request(onem2m_request)
onem2m_response = promise.get()
print onem2m_response.content.labels
#>>> [u'keyword1', u'keyword2']
# Retrieve the AE from the CSE and check the labels
path = "onem2m/" + onem2m_response.content.resourceName
onem2m_request = OneM2MRequest("retrieve", to=path)
promise = client.send_onem2m_request(onem2m_request)
onem2m_response = promise.get()
print onem2m_response.content.labels
#>>> [u'keyword1', u'keyword2']
# Update the changes labels in the remote resource
# Therefore a temporay AE object is needed
# This temporary AE object should ONLY contian the fields that need to be updated 
tmp_app = AE(labels=["foo", "bar", "coffee"])
onem2m_request = OneM2MRequest("update", to=path, pc=tmp_app)
promise = client.send_onem2m_request(onem2m_request)
onem2m_response = promise.get()
print onem2m_response.content.labels
#>>> [u'foo', u'bar', u'coffee']
# Set the local AE to the retrieved content
my_app = None
my_app = onem2m_response.content
print my_app.labels
#>>> [u'foo', u'bar', u'coffee']

Error Handling

The examples above have so far omitted error handling for the sake of clarity and brevity. Obviously however, many things can go wrong at various stages of processing and these cases need to be dealt with. Any errors that are returned from the CSE will be represented in the form of an OneM2MErrorResponse instance. As stated before, the OneM2MErrorResponse class derives from Exception. Consequently, OneM2MErrorResponse objects are not returned from the method, instead they are raised as exceptions. In addition, it is possible that the CSE could not be contacted at all in the first place. In this case, an instance of openmtc.exc.ConnectionFailed will be raised, which also derives from Exception. Note: This implies that whenever one of the client methods returns normally, we can be sure that the operation has succeeded and continue working with the result as planned without further inspecting the result's status. This allows a very convenient and pythonic separation of error and result handling. With this in mind we can extend Example 8b by simply enclosing the invocation of the client method in a try/except/else block. This file can be found here.


# Example 12a: Making Requests with error handling
from openmtc_onem2m.client.http import OneM2MHTTPClient
from openmtc_onem2m.transport import OneM2MRequest, OneM2MErrorResponse
from openmtc.exc import OpenMTCError
client = OneM2MHTTPClient("http://localhost:8000", False)
try:
    onem2m_request = OneM2MRequest("retrieve", to="onem2m")
    promise = client.send_onem2m_request(onem2m_request)
    onem2m_response = promise.get()
except OneM2MErrorResponse as e:
    print "CSE reported an error:", e
    raise
except OpenMTCError as e:
    print "Failed to reach the CSE:", e
    raise
else:
    pass
# no exception was raised, the method returned normally.
print onem2m_response.to
#>>> onem2m
print onem2m_response.response_status_code
#>>> STATUS(numeric_code=2000, description='OK', http_status_code=200)
print onem2m_response.content
#>>> CSEBase(path='None', id='cb0')

Forwarding

OpenMTC will automatically handle forwarding of a OneM2MRequest if it is referring to a different CSE than the one the client is connected to. Forwarding in OneM2M is based on CSE-IDs whereas the ETSI M2M equivalent Retargeting is based on IPs. Lets suppose that a gateway is availabe at localhost:8000 and has the CSE-ID mn-cse-1. Then, its backend is available at localhost:18000 and has the CSE-ID in-cse-1. Due to forwarding, the following requests will have the same results:

  • localhost:8000/onem2m and localhost:18000/~/mn-cse-1/onem2m
  • localhost:8000/onem2m and localhost:8000/~/mn-cse-1/onem2m"
  • localhost:8000/~/in-cse-1/onem2m and localhost:18000/onem2m The following exaple illustrates this: This file can be found here.

# Example 12b: Forwarding
from openmtc_onem2m.client.http import OneM2MHTTPClient
from openmtc_onem2m.transport import OneM2MRequest
client = OneM2MHTTPClient("http://localhost:8000", False)
onem2m_request = OneM2MRequest("retrieve", to="onem2m")
onem2m_response = client.send_onem2m_request(onem2m_request).get()
print "---> Request to: http://localhost:8000" + "/" + onem2m_request.to
print onem2m_response.to
#>>> onem2m
print onem2m_response.response_status_code
#>>> STATUS(numeric_code=2000, description='OK', http_status_code=200)
print onem2m_response.content
#>>> CSEBase(path='None', id='cb0')
onem2m_request = OneM2MRequest("retrieve", to="~/mn-cse-1/onem2m")
onem2m_response = client.send_onem2m_request(onem2m_request).get()
print "---> Request to: http://localhost:8000" + "/" + onem2m_request.to
print onem2m_response.to
#>>> ~/mn-cse-1/onem2m
print onem2m_response.response_status_code
#>>> STATUS(numeric_code=2000, description='OK', http_status_code=200)
print onem2m_response.content
#>>> CSEBase(path='None', id='cb0')
client.port = 18000
onem2m_request = OneM2MRequest("retrieve", to="~/mn-cse-1/onem2m")
onem2m_response = client.send_onem2m_request(onem2m_request).get()
print "---> Request to: http://localhost:18000" + "/" + onem2m_request.to
print onem2m_response.to
#>>> ~/mn-cse-1/onem2m
print onem2m_response.response_status_code
#>>> STATUS(numeric_code=2000, description='OK', http_status_code=200)
print onem2m_response.content
#>>> CSEBase(path='None', id='cb0')