Version: 2018/03/29
Author: support@iseg-hv.de
iCS Version: 2.2
For a live working Javascript Client example click here iCSapiWebsocket_Example.html
The iCSservice Websocket API is a software service, brought over Ethernet connection on TCP/IP protocol. It allows a bidirectional push communication. For more information please refer to https://en.wikipedia.org/wiki/WebSocket
THe iCSservice offers following advantages
The communcation will be established in the following sequence
Note: Inactive sessions will automatically been closed.
There are different types of JSON structures, which are used as websocket payload messages
| Structure type | parameters | response | description | state | example | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| login | username, password, ticket(opt.) | trigger message | creates session, requires established websocket connection | implemented | {
"i": "", // no session ID given
"t": "login", // type login
"c": { // content array, collects different request pakets
"l": "demo", // login name "demo"
"p": "demo", // login password "demo"
"t": "" // ticket: used if a server prepared ticket is used instead of name/password credentials
},
"r": "websocket" // session response type: websocket => push mode communication | xhr => polling mode communication
}
|
||||||||
| logout | session ID | trigger message | destroys session, connection can be closed | implemented |
{
"i": "12345", // session ID
"t": "logout", // type login
"c": {},
"r": "websocket" // session response type: websocket => push mode communication | xhr => polling mode communication
}
|
||||||||
| connect | session ID, interface | trigger message | connects the session to a specific hardware interface (CAN, USB, Serial etc.) | not implemented - currently fix to CAN0 | |||||||||
| disconnect | session ID, interface | trigger message | disconnects hardware | not implemented | |||||||||
| getConfig | session ID |
{"file":"icsConfig.xml",
"d":"PD94bWwgdmVyc2lvbj......”
}
|
The response is not a usual response type as JSON parsers might not handle big strings. The usual JSON parser is bypassed by the client. The data in “d” is a base64 encoded string that can be written to a file or parsed directly. | implemented |
{
"i":"55005e1a49cad-1",
"t":"getConfig",
"c":[],
"r":"websocket"
}
|
||||||||
| setConfig | session ID |
trigger message |
SetConfig can be used to store a new configuration in iCS. | implemented |
{
"i":"55005e1a49cad-1",
"t":"setConfig",
"f":"iCSconfig.xml",
"c":[],
"d": base64 encoded XML string (content of iCSconfig.xml file)
"r":"websocket"
}
|
||||||||
| request | session ID, content with request pakets | response or trigger messages | Using an open connection a request message can submit multiple commands, like getItem, setItem etc. This is useful to avoid overhead and multiple request can be sent at once | implemented |
{
"i": "55005e1a49cad-46", // session id, received by login
"t": "request", // type request
"c": [ // content array, collects different request pakets
{ // request paket object
"c": "getItem", // command: getItem
"p": {
"p": { // path object
"l": "0", // line (0)
"a": "*", // address (every device in line 0)
"c": "*" // channel (every channel of every device in line 0)
},
"i": "VoltageMeasure", // item type (measured Voltage)
"v": "", // must be empty
"u": "" // must be empty
}
}
],
"r": "websocket" // session response type: websocket => push mode communication | xhr => polling mode communication
}
|
||||||||
| response | server to client message | a response message can transport multiple event packets in content object | implemented | [ // A response/info can have multiple messages
{
"t": "response", // type info
"c": [ // content array, collects different request pakets
{ // paket structure
"e": "itemUpdated", // event: "item has been updated"
"d": { // data object
"p": { // system message -> no path neccessary
"l": "",
"a": "",
"c": ""
},
"i": "Status.heartBeat", // item Type: heartbeat
"v": "1153384", // value: CPU style cycle counter
"u": "", // unit
"t": "1479210474.0038" // timestamp UNIX style with microseconds
}
},
{
"e": "itemUpdated",
"d": {
"p": {
"l": "0",
"a": "0",
"c": ""
},
"i": "Status.currentLimit",
"v": "101.998",
"u": "%",
"t": "1479210473.4612"
}
},
{
"e": "itemUpdated",
"d": {
"p": {
"l": "0",
"a": "0",
"c": "0"
},
"i": "Status.currentMeasure",
"v": "-0.0015",
"u": "mA",
"t": "1479210473.9442"
}
},
]
}
]
|
|||||||||
| info | server to client message | a info message is similar to a response message, but will be pushed automatically without a request | implemented | [ // A response/info can have multiple messages
{
"t": "info", // type info
...
}
]
|
|||||||||
| trigger | server to client response:
|
a trigger message is similar to a response message, but will be pushed automatically without a request | implemented | {"trigger":"false"}
|
Using the login message an established websocket connection will be used for authentication on iCSservice. There are two ways to authenticate
Once the login succeeded the iCSservice creates a session and returns the Session-ID in a response message. When login fails a false trigger message will be issued.
The logout works identically, only the Session-ID must be provided. When sent, the iCSservice kills the session and returns trigger message true.
Using a Request Message the client commands the iCSservice to do something. Following commands are possible.
| Command | Parameter | Response | usage | state |
|---|---|---|---|---|
| getItem | SessionId, Path (line,address,channel), Item | Push mode: Response message, Poll mode: trigger message | request current status of items, subscribe for updates | implemented |
| setItem | SessionId, Path (line,address,channel), Item, Value, Unit(opt.) | trigger message | set value of specific item | implemented |
| getUpdate | SessionId | Response message | get updates collected in session queue | implemented |
| getLog | SessionId, Path, Item | Response message | get data logs | not yet implemented |
The getItem command asks the server to provide specific data. The parameters are the valid Session ID, the path of the object, and the Item name of the object. The value and unit must be empty. The iCSservice replies in Push mode with a Response message which contents the requested data. In Polling mode the iCSservice responses a trigger message.
The setItem command commands the server to set specific data points. The parameters are the valid Session ID, the path of the object, and the Item name of the object. The value must be filled, unit if applicable. The iCSservice responds always with a trigger response.
The getUpdate command is used in Polling (XHR) mode. Every the iCSservice creates per session a queue for data collection. This collected data will be sent as response. The parameters block in the request structure must kept empty.
| Level | shortcut in structure | type | description |
|---|---|---|---|
| 1 | n/a | system level | no path values are set |
| 2 | l | line level | possible hardware lines, possible from 0-15 |
| 3 | a | address level | hardware address of the device, typically modules from 0-63, controller devices (eg. crates) from 1000-1015, * wildcard for all |
| 4 | c | channel level | channels of a device, 0-63, * wildcard for all |
Different to isegHAL iCSservice allows group commands represented by wildcards "*" or by keeping path levels empty. By giving the wildcard the command requires all possible items of all underlying levels. By keep a path part empty the iCSservice responds all item objects of the specific level.
Example: line:0, addres:0, channel:"*", item:"*" gives all possible information on line 0 and device with address 0 including all channel data.
Example: line:0, addres:0, channel: "", item:"*" gives only all possible information on line 0 and device with address 0 withoud channel data (eg. device settings, temperatures, serial etc.) .
All items which can be address data objects are defined and described in the items.xml file. This can be downloaded here: /api/getItemsInfo
iCSservice Websocket API Documentation | 2016/11/22