JSON link protocol

--Dchassin 17:47, 30 March 2013 (UTC)

JSON link protocol - Protocol for JSON client/server connections

The JSON link allows data to be exchanged with GridLAB-D using JSON schemas.

Initialization
The initialization handshake sequence is as follows regardless of who originates the connection:

--> {"method":"init", "params":{"application":"gridlabd", "version":major.minor, "modelname":"modelname.glm"}, "id":msg-num} <-- {"result":"init", "params":{"remote":"remotename"} "id":msg-num}

--> {"method":"input", "schema":{"name0":"type0 object0:property0", ...}, "id":msg-num } <-- {"result":"input", "id":msg-num }

--> {"method":"output", "schema":{"name0":"type0 object0:property0", ...}, "id":msg-num } <-- {"result":"output", "id":msg-num }


 * Note : global variables are designated using the object name "global"

--> {"method": "start", "data":{"name0":"value0", ...}, "id": msg-num } <-- {"result": "start", "id": msg-num}

If an error occurs, the result message is:

<-- {"result":"method", "error":code, "params":"message", "id",msg-num}

Synchronization
A synchronization message will be transmitted at the interval specified by the refresh parameter (in seconds). GridLAB-D will wait up to timeout seconds for a response. If no response is received, GridLAB-D stops waiting and a timeout error is indicated.

--> {"method":"sync", "data":{"name0":"value0", ...}, "id":msg-num } <-- {"result":"sync", "data":{"name0":"value0", ...}, "id":msg-num}

If an error occurs, the result message is:

<-- {"result":"method", "error":code, "params":"message", "id":msg-num}

Termination
A termination message will be transmitted when the simulation is ended for any reason. GridLAB-D will wait up to timeout seconds for a response. If no response is received, GridLAB-D stops waiting and a timeout error is indicated.

--> {"method": "term", "data":{"name0":"value0", ...}, "id":msg-num } <-- {"result": "term", "data":{"name0":"value0", ...}, "id":msg-num}

If an error occurs, the result message is:

<-- {"result": "method", "error": code, "params": ["message"], "id": msg-num}

Protocols
The message format will depend on the protocol selected.

Raw TCP/UDP
When the protocol is udp or tcp, the client or servers use the following format for the message.

Request/Response header
Bytes    Contents - 00-01     Header version (currently "0", space padded) 02-05    Offset to message from byte 00 (currently always 32, max is 999, space padded) 06-13    Size of message (varies, max is 9999999, space padded) 14-19    Type of message (currently "JSON", space padded) 20-23    Version of type (currently "1.0", space padded) 23-24    Connection status (0=closed, 1-9=keep-alive timeout, space padded) 24-30    Response code (0 for requests, must be 200 for responses, space padded) 31-32    Reserved (space padded) 32-      Message content (current JSON 1.0 format)

Any Response Code other than 200 will be reported as an error status. See HTTP/1.1 standard for valid response codes.


 * Example header

0 32 28       JSON   1.0 1 0     {"method":"example","id":1}


 * Example response

0 32 28       JSON   1.0 1 200   {"result":"example","id":1}

HTTP/1.1
When the protocol is http the client or servers conform to the HTTP/1.1 standard. Specifically required header parameters are as follows.

Request header

 * Content-Type : The content type is always application/json


 * Content-Length : The content length is always the length of the JSON message (in bytes)


 * Connection : The connection is always set to Keep-Alive


 * Keep-Alive : The keep alive parameter is always set to value the timeout parameter (a single digit) and establishes the maximum time (in seconds) to client will wait for a return message before the request is considered ignored and an error is returned.

Response header

 * Response code : The response code must be 200. No other response code will be accepted.


 * Content-Length : The content length must be provided.


 * Connection : The connection status must be set to close before the connection is closed.