PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
1
Contents
2
3
1
Introduction ................................................................................................................................................................ 1
4
2
References ................................................................................................................................................................... 2
5
2.1
6
3
7
3.1
Definitions ................................................................................................................................................................ 3
8
3.2
Abbreviations ......................................................................................................................................................... 3
9
4
Normative References ......................................................................................................................................... 2
Definitions, Symbols and Abbreviations ......................................................................................................... 3
M2M Frame ................................................................................................................................................................. 4
10
4.1
M2M Request Frame Description ................................................................................................................... 4
11
4.2
M2M Response Frame Description................................................................................................................ 5
12
5
13
14
15
Basic Commands .................................................................................................................................................... 76
5.1 method.list ............................................................................................................................................................ 76
5.1.1 Request ............................................................................................................................................................... 86
5.1.2 Response ............................................................................................................................................................ 87
18
5.2 method.exec ......................................................................................................................................................... 98
5.2.1 Request ............................................................................................................................................................... 98
5.2.2 Response ......................................................................................................................................................... 118
19
6
16
17
20
21
22
23
24
25
26
27
28
Security Commands ......................................................................................................................................... 1210
6.1 api.authenticate ............................................................................................................................................. 1210
6.1.1 Request .......................................................................................................................................................... 1210
6.1.2 Response ....................................................................................................................................................... 1311
6.2 api.deauthenticate ........................................................................................................................................ 1411
6.2.1 Request .......................................................................................................................................................... 1411
6.2.2 Response ....................................................................................................................................................... 1512
6.3 api.authorize ................................................................................................................................................... 1512
6.3.1 Request .......................................................................................................................................................... 1613
6.3.2 Response ....................................................................................................................................................... 1613
31
6.4 api.deauthorize .............................................................................................................................................. 1714
6.4.1 Request .......................................................................................................................................................... 1714
6.4.2 Response ....................................................................................................................................................... 1814
32
7
29
30
Common Data Structure ................................................................................................................................ 1915
33
34
Contents
|
i
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
1
List of Figures
2
3
4
Figure 1 - Basic Command Flow .............................................................................................................................. 76
5
Figure 2 - Basic Security Commands ................................................................................................................ 1210
6
7
ii
|
List of Figures
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
1
Foreword
2
(This foreword is not part of this Standard.)
3
This document was formulated under the cognizance of the TIA Committee
TR-50, Smart Device Communications.
4
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 rereleased with an identifying change of release level, for example:
5
6
7
8
TIA-4940.020-A
revision level
part number
standard number
9
Suggestions for improvement of this document are welcome, and should be
sent to:
10
11
Telecommunications Industry Association,
Standards and Technology,
2500 Wilson Boulevard, Suite 300
Arlington, VA 22201-3834
12
13
14
15
16
17
18
19
20
21
22
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.
23
Foreword
|
iii
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
1
2
3
4
5
6
7
1 Introduction
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.
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
|
1
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
1
2 References
2
2.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.
3
4
5
6
7
8
9
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.
10
11
12
13
[1]
14
[2]
16
HTTP Over TLS
http://tools.ietf.org/html/rfc2818
17
[3]
18
JSON
http://tools.ietf.org/html/rfc4627
19
[4]
20
2
Hypertext Transfer Protocol - HTTP/1.1
http://tools.ietf.org/html/rfc2616
15
|
TIA-4940.005: Smart Device Communications; Architecture
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
1
3 Definitions, Symbols and Abbreviations
This section contains definitions, symbols and abbreviations that are used in
this document.
2
3
4
3.1
None
5
6
Definitions
3.2
Abbreviations
7
API – Application Programming Interface
8
JSON – JavaScript Object Notation, see [3]
9
M2M – Machine to Machine
10
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
|
3
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
1
4
M2M Frame
3
The communication between the client and server should be based on the reliable network
communication when M2M frames are used.
4
4.1 M2M Request Frame Description
5
The M2M request frames are based on a JSON structure and consist of two major sections:
2
6
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
7
8
9
10
Below is the structure of the M2M frame:
11
{
"auth": {
12
13
"applicationToken": "<application token>",
14
"sessionId": "<session token>"
15
},
16
"ref": {
17
"command": "<command keyword>",
18
"params": []
}
19
20
}
21
22
23
In order to minimize the traffic, it is possible to have M2M frames with multiple commands as
shown below:
24
25
{
"auth": {
26
27
"applicationToken": "<application token>",
28
"sessionId": "<session token>"
29
},
30
"ref1": {
4
|
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
1
"command": "<first command>",
2
"params": []
3
},
4
"ref2": {
5
"command": "<second command>",
6
"params": []
7
},
8
"ref3": {
"command": "<third command>",
9
"params": []
10
}
11
12
}
13
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
ref1, ref2, ref3
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
14
15
4.2 M2M Response Frame Description
16
The frame is described in a JSON format.
17
The response frame has the following structure:
18
19
{
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
|
5
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
"ref1": {
1
2
"success": true,
3
"params": []
4
},
5
"ref2": {
6
"success": false,
7
“errorCodes”:
[
8
<errorCode1>,
9
<errorCode2>
10
]
11
"errorMessages":
12
[
13
14
“<errorMessage>”,
15
“<errorMessage>”
]
16
},
17
18
}
19
Name
Description
Type
Mandatory
ref1,ref2, ref3
Identifies the request commands.
String
Yes
success
Keyword. Identifies the response. Can be true or false
String
Yes
errorCodes
Keyword. Identifies the error codes .
errorMessages
Keyword. Identifies the error message.
String
No
params
Keyword. Identifies the response parameters. Can be
empty.
String
Yes
20
6
|
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
1
5
Basic Commands
2
3
4
Every system implementing this protocol shall implement the following basic commands for
listing and executing capabilities of an entity:
5
6

method.list

method.exec
7
8
9
10
The following diagram shows the way these two commands could be executed:
11
12
13
Figure 1 - Basic Command Flow
14
15
16
17
5.1
method.list
18
Use this command to list all the available methods and their description.
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
|
7
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
1
5.1.1
2
{
Request
"auth": {
3
4
"applicationToken": "<guid>",
5
"sessionId": "<guid>"
6
},
7
"ref": {
8
"command": "method.list"
9
"params": {
"objectId": "<the target objectId>"
10
}
11
}
12
13
}
14
15
The “auth” section is described in section 4.1.
16
17
The “ref” section is described below:
18
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
19
20
5.1.2
Response
21
The following JSON stanza represents the response for the “method.list” command.
22
23
{
"ref": {
24
25
"success": true,
26
"params": {
8
|
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
"remoteMethods": [
1
{"remoteMethod": "myMethod1",
2
3
"objectId": "<the target objectId>",
4
"notificationVariables": {<common data structure>},
5
"completionVariables": {<common data structure>}
6
},
7
{"remoteMethod": "myMethod2",
8
"notificationVariables": {<common data structure>},
9
"completionVariables": {<common data structure>}
}
10
]
11
}
12
}
13
14
}
15
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
16
17
18
5.2
19
Use this command to execute a specific method on a remote entity.
20
5.2.1
21
{
22
method.exec
Request
"auth": {
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
|
9
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
1
"applicationToken": "<guid>",
2
"sessionId": "<guid>"
3
},
4
"ref": {
5
"command": "method.exec"
6
"params": {
7
"objectId": "<the target objectId>",
8
"remoteMethod": "<name of the invocation method>",
9
"notificationVariables": [
10
{"input1": "<input 1 data>"},
11
{"input2": "<input 2 data>"}
]
12
}
13
}
14
15
}
16
17
The “auth” section is described in section 4.1.
18
19
The “ref” section is described below:
20
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
No
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
21
10
|
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
1
5.2.2
Response
2
The response of the invocation method is described here:
3
4
{
"ref": {
5
6
"success": true,
7
"params": {
8
"completionVariables": [
9
{"return1": "foo" },
{"return2": "bar" }
10
]
11
}
12
}
13
14
}
15
16
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
17
18
If the field “success” is “false”, the response is described as in the following section 4.1.
19
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
|
11
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
1
6 Security Commands
2
3
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
4
5
6
A short description of the communication between the Home Application, PoA and AAA-SD is
shown below:
7
8
Figure 2 - Basic Security Commands
9
10
6.1
api.authenticate
12
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
13
6.1.1
11
Request
14
15
12
{
|
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
"ref": {
1
2
"command": "api.authenticate",
3
"params": {
4
"applicationToken": "<guid>",
5
"organizationToken": "<guid>"
}
6
}
7
8
}
9
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
10
11
12
The call will verify the applicationToken and the organizationToken or the username and
password. Once validated, a sessionId will be issued.
13
16
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.
17
6.1.2
18
The following is the description of the response to the authentication request:
14
15
Response
19
20
{
21
"ref":
22
{
23
"success": true,
24
"params": {
"sessionId": "<guid>"
25
26
}
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
|
13
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
}
1
2
}
3
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
4
5
6
If the field “success” is “false”, the response is described as in the following section 4.1.
7
8
6.2
9
Use this API command to de-authenticate your M2M application program with AAA-SD.
10
api.deauthenticate
6.2.1
Request
11
12
{
"ref": {
13
14
"command": "api.deauthenticate",
15
"params": {
16
"applicationToken": "<guid>",
17
"organizationToken": "<guid>",
18
"sessionId": "<guid>"
}
19
}
20
21
}
22
Name
14
|
Description
Type
Mandatory
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
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
1
2
3
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.
4
5
6.2.2
Response
6
The following is the description of the response to the de-authentication request:
7
8
{
"ref":
9
{
10
11
"success": true,
12
"params": []
}
13
14
}
15
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
16
17
If the field “success” is “false”, the response is described as in the following section 4.1.
18
19
6.3
api.authorize
20
Use this API command to authorize the request of an entity.
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
|
15
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
1
6.3.1
2
{
Request
"ref": {
3
4
"command": "api.authorize",
5
"params": {
"applicationToken": "<guid>",
6
"sessionId": "<guid>",
7
"remoteApplicationToken": "<guid>",
8
"remoteSessionId": "<guid>",
9
10
"objectId": "<>",
11
"methodName": "<>",
}
12
}
13
14
}
15
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
16
17
6.3.2
Response
18
The following is the description of the response to the authorization request:
19
20
16
{
|
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
1
"ref":
2
{
3
"success": true,
4
"params": {
5
"authorizationToken": "<guid>"
6
}
}
7
8
}
9
Name
Description
Type
Mandatory
Rref
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
10
11
12
If the field “success” is “false”, the response is described as in the following section 4.1.
13
14
6.4
api.deauthorize
16
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.
17
6.4.1
18
{
15
19
Request
"ref": {
20
"command": "api.dauthorize",
21
"params": {
22
"authorizationToken": "<guid>",
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
|
17
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
}
1
}
2
3
}
4
Name
Description
Type
Mandatory
authorizationToken
Keyword. Identifies the authorization token that the
AAA-SD de-authorize.
String
Yes
5
6
6.4.2
Response
7
The following is the description of the response to the de-authorization request:
8
9
{
10
"ref":
11
{
12
"success": true,
13
"params": []
}
14
15
}
16
Name
Description
Type
Mandatory
ref
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
17
18
18
If the field “success” is “false”, the response is described as in the following section 4.1.
|
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
PN-4940.020: Smart Device Communications;
Protocol Aspects; Introduction
1
7 Common Data Structure
2
3
4
5
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:
{
6
7
"name": "To",
8
"type": "STRING",
9
"count": 1,
"length": 16
10
}
11
12
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:
Yes
INT1, INT2, INT4, INT8, UINT1,
UINT2, UINT4, UINT8, FLOAT4,
FLOAT8, STRING, BOOL, BINARY (Base64 Encoded)
count
Specifies the number of data variables, which are included, each of the
length specified below, as a single value. . If the field is missing or
specified to be a non-positive integer, the count is assumed to be 1.
No
length
Specifies the allowable length of the data variables which are included.
Mandatory 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.
No
13
14
Ошибка! Используйте вкладку "Главная" для применения Heading 1 к тексту, который должен
здесь отображаться.
|
19