Pn-4940. 020: Smart Device Communications; Protocol Aspects; Introduction



Download 106.57 Kb.
Date28.01.2017
Size106.57 Kb.

PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction

Contents

final~

1Introduction 4

2References 5

2.1Normative References 6

3Definitions, Symbols and Abbreviations 7

3.1Definitions 8

3.2Abbreviations 9

4M2M Frame 10

4.1M2M Request Frame Description 11

4.2M2M Response Frame Description 13

5Basic Commands 15

5.1method.list 16

5.1.1Request 17

5.1.2Response 18

5.2method.exec 19

5.2.1Request 20

5.2.2Response 21

6Security Commands 22

6.1api.authenticate 23

6.1.1Request 24

6.1.2Response 25

6.2api.deauthenticate 26

6.2.1Request 27

6.2.2Response 28

6.3api.authorize 29

6.3.1Request 30

6.3.2Response 31

6.4api.deauthorize 32

6.4.1Request 33

6.4.2Response 34

7Common Data Structure 35




List of Figures
final~

Figure - Basic Command Flow 15

Figure - Basic Security Commands 22



Foreword

(This foreword is not part of this Standard.)

This document was formulated under the cognizance of the TIA Committee TR50, Smart Device Communications.

The contents of the present document are subject to continuing work within the Formulating Group and may change following formal approval. Should the Formulating Group approve modification, the present document will be re-released with an identifying change of release level, for example:



Suggestions for improvement of this document are welcome, and should be sent to:

Telecommunications Industry Association,
Standards and Technology,
2500 Wilson Boulevard, Suite 300
Arlington, VA 22201-3834

Scope

This document is a member of a multi-part standard that, when taken in total, defines the requirements for communications pertaining to the access agnostic (e.g. PHY and MAC agnostic) monitoring and bi-directional communication of events and information between smart devices and other devices, applications and networks. This document provides an introduction to the protocols.




1Introduction


This document is a member of a multi-part standard that has controlling document TIA-4940-000. When taken in total, defines the requirements for communications pertaining to the access agnostic (e.g., PHY and MAC) monitoring and bi-directional communication of events and information between logical entities, such as Point-of-Attachment and applications or networks. This document provides an introduction to the protocols.

2References

  1. Normative References


The following standards contain provisions which, through reference in this text, constitute provisions of this Standard. At the time of publication, the editions indicated were valid. All standards are subject to revision, and parties to agreements based on this Standard are encouraged to investigate the possibility of applying the most recent editions of the standards indicated below. ANSI and TIA maintain registers of currently valid national standards published by them.

References are either specific (identified by date of publication, release level, etc.) or non-specific. For a specific reference, subsequent revisions do not apply. For a non-specific reference, the latest version applies: a non-specific reference implicitly refers to the latest version.



  1. Hypertext Transfer Protocol - HTTP/1.1
    http://tools.ietf.org/html/rfc2616

  2. HTTP Over TLS
    http://tools.ietf.org/html/rfc2818

  3. JSON
    http://tools.ietf.org/html/rfc4627

  4. TIA-4940.005: Smart Device Communications; Architecture

3Definitions, Symbols and Abbreviations


This section contains definitions, symbols and abbreviations that are used in this document.
  1. Definitions


None
  1. Abbreviations


API – Application Programming Interface

JSON – JavaScript Object Notation, see 3

M2M – Machine to Machine

4M2M Frame


The communication between the client and server should be based on the reliable network communication when M2M frames are used.

4.1M2M Request Frame Description


The M2M request frames are based on a JSON structure and consist of two major sections:


  1. Authentication – this is the place where the entire authentication items are placed.

  2. Command(s) – this is the place where the commands items are placed

Below is the structure of the M2M frame:



{

"auth": {

"applicationToken": "",

"sessionId": ""

},

"refcmd": {

"command": "",

"params": []

}

}
In order to minimize the traffic, it is possible to have M2M frames with multiple commands as shown below:
{

"auth": {

"applicationToken": "",

"sessionId": ""

},

"refcmd1": {

"command": "",

"params": []

},

"refcmd2": {

"command": "",

"params": []

},

"refcmd3": {

"command": "",

"params": []

}

}


Name

Description

Type

Mandatory

auth

Keyword. Identifies the authentication stanza in the M2M request frame

String

Yes

applicationToken

Keyword. Identifies the application making the request

String

Yes

sessionId

Keyword. Unique ID received after the use of the authentication services. Identifies the current session between the two entities

String

Yes

refcmd1, refcmd2, refcmd3

Identifies the commands that are in the request. Can be simple identifiers. They are not keyword. It is expected that the response will contain them.

String

Yes

command

Keyword. Identifies a known command that can be executed

String

Yes

params

Keyword. Identifies the parameters required by the command. The field must exist, but it can be empty.

String

Yes


4.2M2M Response Frame Description


The frame is described in a JSON format.

The response frame has the following structure:


{

"refcmd1": {

"success": true,

"params": []

},

"cmd2": {

"success": false,

"errorMessage": "",

"errorMessage": ""

},

"refcmd23": {

"success": false,

“errorCodes”:

[

,



]

"errorMessagesrMessages":

[

{



"errorCode": "",

<"errorMessage>”,e

": ""



},

{

"errorCode": "",

"errorMessage": "”"

}

]

},
}


Name

Description

Type

Mandatory

refcmd1,ref cmd2, refcmd3

Identifies the request commands.

String

Yes

sSuccess

Keyword. Identifies the response. Can be true or false

String

Yes

errorCodes

Keyword. Identifies the error codes .







errorMessages(s)

Keyword. Identifies the error message. or an array of messages when the “success” is false. Ignored otherwise

String

NoYes

pParams

Keyword. Identifies the response parameters. Can be empty.

String

Yes


5Basic Commands

Every system implementing this protocol shall implement the following basic commands for listing and executing capabilities of an entity:




  • method.list




  • method.exec

The following diagram shows the way these two commands could be executed:



Figure - Basic Command Flow


5.1method.list


Use this command to list all the available methods and their description.

5.1.1Request


{

  "auth": {

    "applicationToken": "",

    "sessionId": ""

  },

  "refcmd": {


"command": "method.list"

    "params": {

      "objectId": ""

    }

  }

}
The “auth” section is described in section 4.1.
The “refcmd” section is described below:


Name

Description

Type

Mandatory

Command

Keyword. Identifies the invoke method. Always set to “method.list”

String

Yes

objectId

Keyword. Identifies the entity that would be asked for the list of methods. If it is not present, all the method registered with the target entity will be returned.

String

No



5.1.2Response


The following JSON stanza represents the response for the “method.list” command.
{

  "refcmd": {

    "success": true,

    "params": {

      "remoteMethods": [

         {"remoteMethod": "myMethod1",



"objectId": "",

"notificationVariables": {},

"completionVariables": {}

},

         {"remoteMethod": "myMethod2",



"notificationVariables": {},

"completionVariables": {}

}

      ]

    }

  }



}


Name

Description

Type

Mandatory

remoteMethods

Keyword. Identifies the array of methods that can be invoked.

String

Yes

remoteMethod

Keyword. Identifies the method’s name

String

Yes

notificationVariables

Keyword. Identifies the method’s input parameters and their definition as specified in the section 7

String

Yes

completionVariables

Keyword. Identifies the method’s output (results) values and their definition as specified in the section 7

String

Yes

objectId

Keyword. Identify the objectId in the target entity space that implements the remote method.

String

No


5.2method.exec


Use this command to execute a specific method on a remote entity.

5.2.1Request


{

"auth": {

"applicationToken": "",

"sessionId": ""

},

"refcmd": {

"command": "method.exec"

"params": {

"objectId": "<the target objectId>",

"remoteMethod": "",

"notificationVariables": [

{"input1": ""},

{"input2": ""}

]

}

}

}
The “auth” section is described in section 4.1.
The “refcmd” section is described below:


Name

Description

Type

Mandatory

command

Keyword. Identifies the invoke method. Always set to “method.exec”

String

Yes

objectId

Keyword. Identifies the entity that will execute the method described by the “remoteMethod”

String

NoYes

remoteMethod

Keyword. Identifies the method that needs to be invoked.

String

Yes

notificationVariables

Keyword. Identifies the array of invoked method input params.

String

Yes

input1, input2, …

Keyword. Identifies the input parameters.

String

No



5.2.2Response


The response of the invocation method is described here:
{

  "refcmd": {

    "success": true,

    "params": {

      "completionVariables": [

        {"return1": "foo" },

        {"return2": "bar" }

      ]

    }

  }



}
Fields Description:

Name

Description

Type

Mandatory

success

Keyword. If the invocation succeeded, it would always be “true”.

String

Yes

completionVariables

Keyword. Identifies the array of the returning results.

String

Yes

return1, return2

Keyword. Identifies the return result.

String

No

If the field “success” is “false”, the response is described as in the following section 4.1.



6Security Commands

These services would apply to the following connections:



Connection Name

Server

Client

Notes

A1

AAA-SD

Home Application

Bi-directional

A2

AAA-SD

Node Application

Bi-directional

A3/A3’

AAA-SD

PoA device/application

Bi-directional

A short description of the communication between the Home Application, PoA and AAA-SD is shown below:


Figure - Basic Security Commands


6.1api.authenticate


Use this API command to authenticate an M2M application against the AAA-SD and to obtain the credentials for subsequent api.authorize and api.deauthorize commands

6.1.1Request



{

"refcmd": {

"command": "api.authenticate",

"params": {

"applicationToken": "",

"organizationToken": ""

}

}

}


Name

Description

Type

Mandatory

applicationToken

Keyword. The application token. Identifies the application requesting access to the system. In some cases, the applicationToken can be a userId.

String

Yes

organizationToken

Keyword. The organization token. Identifies the organization requesting access to the system. In some cases, the organizationToken can be passwod

String

Yes

The call will verify the applicationToken and the organizationToken or the username and password. Once validated, a sessionId will be issued.


A sessionId is non-expiring however once the application or organization tokens change or the user account is disabled or deleted then the sessionId will be invalidated and a new sessionId will be required.

6.1.2Response


The following is the description of the response to the authentication request:
{

"refcmd":

{

"success": true,

"params": {

"sessionId": ""

}

}

}


Name

Description

Type

Mandatory

cmd

The command. Must match the request.

String

Yes

success

Keyword. The response of the authentication request. Always true.

String

Yes

params

Keyword. Identifies the response.

String

Yes

sessionId

Keyword. The sessionId returned by the AAA-SD (a string 36 in length)

String

Yes

If the field “success” is “false”, the response is described as in the following section 4.1.



6.2api.deauthenticate


Use this API command to de-authenticate your M2M application program with AAA-SD.

6.2.1Request



{

"refcmd": {

"command": "api.deauthenticate",

"params": {

"applicationToken": "",

"organizationToken": "",

"sessionId": ""

}

}

}


Name

Description

Type

Mandatory

applicationToken

Keyword. The application token. Identifies the application requesting access to the system. In some cases, the applicationToken can be a userId.

String

Yes

organizationToken

Keyword. The organization token. Identifies the organization requesting for de-authentication.

String

Yes

sessionId

Keyword. If present, identifies the sessionId that you want to invalidate.

String

No

If the sessionId is present, only the respective sessionId will be invalidated, if not all the sessionId associated with the applicationToken and organizationToken will be invalidated.



6.2.2Response


The following is the description of the response to the de-authentication request:
{

"refcmd":

{

"success": true,

"params": []

}

}


Name

Description

Type

Mandatory

cmd

The command. Must match the request.

String

Yes

success

Keyword. The response of the authentication request. Always true.

String

Yes

params

Keyword. Empty if the operation is successful.

String

Yes

If the field “success” is “false”, the response is described as in the following section 4.1.



6.3api.authorize


Use this API command to authorize the request of an entity.

6.3.1Request


{

"refcmd": {

"command": "api.authorize",

"params": {

"applicationToken": "",

"sessionId": "",

"remoteApplicationToken": "",

"remoteSessionId": "",

"objectId": "<>",

"methodName": "<>",
}

}

}


Name

Description

Type

Mandatory

applicationToken

Keyword. The application token. Identifies the application requesting access to the system.

String

Yes

sessionId

Keyword. The session ID of the entity making requests.

String

Yes

remoteApplicationToken

Keyword. The application token of the remote entity.

String

Yes

remoteSessionId

Keyword. The session ID of the remote entity.

String

Yes

objectId

Keyword. If present , identifies the object ID that the remote entity tries to access

String

No

methodName

Keyword. If present, identifies the method name that the remote entity tries to access.

String

No



6.3.2Response


The following is the description of the response to the authorization request:
{

"refcmd":

{

"success": true,

"params": {

"authorizationToken": ""

}

}

}


Name

Description

Type

Mandatory

Rrefcmd

The command. Must match the request.

String

Yes

success

Keyword. The response of the authorization request. Always true.

String

Yes

params

Keyword. Return parameters are included here

String

Yes

authorizationToken

Keyword. Identifies the authorization token for the respective request. If the request contains a method the authorization token is only for that specific method, if the request does not have an method, the authorization token is for all the requests for that specific applicationToken / sessionId combination.

String

Yes

If the field “success” is “false”, the response is described as in the following section 4.1.



6.4api.deauthorize


Use this method to de-authorize an entity from accessing the system. This request is made only by the AAA-SD to a specific entity in the system to de-authorize the access to the system.

6.4.1Request


{

"refcmd": {

"command": "api.dauthorize",

"params": {

"authorizationToken": "",

}

}

}


Name

Description

Type

Mandatory

authorizationToken

Keyword. Identifies the authorization token that the AAA-SD de-authorize.

String

Yes



6.4.2Response


The following is the description of the response to the de-authorization request:
{

"refcmd":

{

"success": true,

"params": []

}

}


Name

Description

Type

Mandatory

refcmd

The command. Must match the request.

String

Yes

success

Keyword. The response of the authorization request. Always true.

String

Yes

params

Keyword. Empty if the operation is successful.

String

Yes

If the field “success” is “false”, the response is described as in the following section 4.1.


7Common Data Structure

When using “method.list”, each remote method will contain a list of notification and completion variables. The data structure for these variables as well as possible values follows:



{

"name": "To",

"type": "STRING",

"count": 1,

"length": 16

}


Option

Description

Mandatory

name

The name of the variable

Yes

type

The data type of the variable. Can be one of the following common types:

INT1INT2INT4INT8UINT1

UINT2UINT4UINT8FLOAT4

FLOAT8, STRING, BOOL, BINARY (Base64 Encoded)

Yes

count

Specifies the number of data variable variables, which are included, each of the length specified below, as a single value single value. or as an array. If the field is missing or specified to be a non-positive integer, the count is assumed to be 1.

NoYes

length

Specifies the The allowallowable ed length of the data variables which are included. valueMandatory for and only applicable to STRING type. If the field is missing or specified to be a negative integer, the length is assumed to be 0..

NoYes









Contents |

Download 106.57 Kb.

Share with your friends:




The database is protected by copyright ©ininet.org 2020
send message

    Main page