Pn-4940. 020: Smart Device Communications; Protocol Aspects; Introduction
Download 106.57 Kb.
|
- Navigate this page:
- 2References Normative References
- 3Definitions, Symbols and Abbreviations
- 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
- 4.2M2M Response Frame Description
|
Contents 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 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 TR 50, 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,
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. 1IntroductionThis 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
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.
3Definitions, Symbols and AbbreviationsThis section contains definitions, symbols and abbreviations that are used in this document.
None
API – Application Programming Interface JSON – JavaScript Object Notation, see 3 M2M – Machine to Machine
4M2M FrameThe communication between the client and server should be based on the reliable network communication when M2M frames are used. 4.1M2M Request Frame DescriptionThe M2M request frames are based on a JSON structure and consist of two major sections:
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": [] } }
4.2M2M Response Frame DescriptionThe 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": " } ] }, }
5Basic CommandsEvery system implementing this protocol shall implement the following basic commands for listing and executing capabilities of an entity:
The following diagram shows the way these two commands could be executed: 
Figure - Basic Command Flow 5.1method.listUse this command to list all the available methods and their description. 5.1.1Request{ "auth": { "applicationToken": " "sessionId": " }, "refcmd": { "command": "method.list" "params": { "objectId": " } }
5.1.2ResponseThe 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": { } ] } } }
5.2method.execUse 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:
5.2.2ResponseThe response of the invocation method is described here: { "refcmd": { "success": true, "params": { "completionVariables": [ {"return1": "foo" }, {"return2": "bar" } ] } } } Fields Description:
If the field “success” is “false”, the response is described as in the following section 4.1. 6Security CommandsThese services would apply to the following connections:
A short description of the communication between the Home Application, PoA and AAA-SD is shown below: 
Figure - Basic Security Commands 6.1api.authenticateUse 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": " } } }
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.2ResponseThe following is the description of the response to the authentication request: { "refcmd": { "success": true, "params": { "sessionId": " } } }
If the field “success” is “false”, the response is described as in the following section 4.1. 6.2api.deauthenticateUse this API command to de-authenticate your M2M application program with AAA-SD. 6.2.1Request{ "refcmd": { "command": "api.deauthenticate", "params": { "applicationToken": " "organizationToken": " "sessionId": " } } }
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.2ResponseThe following is the description of the response to the de-authentication request: { "refcmd": { "success": true, "params": [] } }
If the field “success” is “false”, the response is described as in the following section 4.1. 6.3api.authorizeUse this API command to authorize the request of an entity. 6.3.1Request{ "refcmd": { "command": "api.authorize", "params": { "applicationToken": " "sessionId": " "remoteApplicationToken": " "remoteSessionId": " "objectId": "<>", "methodName": "<>", } } }
6.3.2ResponseThe following is the description of the response to the authorization request: { "refcmd": { "success": true, "params": { "authorizationToken": " } } }
If the field “success” is “false”, the response is described as in the following section 4.1. 6.4api.deauthorizeUse 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": " } } }
6.4.2ResponseThe following is the description of the response to the de-authorization request: { "refcmd": { "success": true, "params": [] } }
If the field “success” is “false”, the response is described as in the following section 4.1. 7Common Data StructureWhen 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 }
Contents | Download 106.57 Kb. Share with your friends:
|