Using the AdminProtocol

This page has been updated on the 24 March 2010.

What is this document about?

Here we’ll explain how to use the adminProtocol to configure your device over the air.

What is the adminProtocol?

The adminProtocol enables you to configure a device over the air by using the G8way graphical interface.

With the adminProtocol you can:

  • Request configuration parameters
  • Set configuration parameters
  • Call Remote API of components of the device

The messages are based on JSON format.

How does it work?

This is quite simple to use. Through the CloudConnect, you send a message to the device you want to set up. Once the device receives the message, it executes a bunch of commands to set the parameters specified into the message. This message needs to have a specific syntax to be understood by the device.

The adminProtocol is a protocol based on messages over the ASN1 protocol.

One channel is reserved for the adminProtocol : the channel 3.

It requires that the device be connected to a server based on ASN1 protocol.
On the device the following components must be at least active:

  • binaryGate
    • binaryGate.port : the port of the ASN1 server
    • binaryGate.url : the url of the ASN1 server
  • messageGate
    • messageGate.active must be set to 1, to do so enter the command s messageGate active 1 into the console.
  • adminProtocol
    • adminProtocol.active must be set to 1, to do so enter the command s adminProtocol active 1 into the console.

How to use it?

  1. Go to http://sandbox.g8teway.com/apiv2/
  2. Use your login/password/client.

3. On the top frame select Site Index>Search by ModID.

4. Select Toggle, type the ModID/BoardID of your device then press “enter”.

5. Now you have identify the device you want to send a new configuration, on the top frame select site index then Send new message

6. Here you have a form, you need to fill in to send the message:

  • the unit id is the id of the unit you want to sent a message to.
  • the user id is the id of the person sending the message (the default value is 1, you can leave this value if you have no id).
  • the direction should be usertounit.
  • the channel id must be 3. That is the adminProtocol channel.
  • the Timeout, you can let the default value.
  • the message, here is the message you are going to send.

The requests

Here, we explain what should be the content of a message and what should the answer from the device be.
There are several types of requests, you can do configuration requests or Remote API Call Requests.

Configuration

Components list requests

You can request the list of all the components installed on the device with the request “modnames”.
It is used to request partial configuration or set parameters.

  • Server → Device: Request message format:
    {"request": "modnames"}
  • Device → Server: The device sends a message with the following format:
    [ “componentName”, …“componentName” ]
    With componentName = component name as JSON string.

Example:

[
"dbg",
"ibutton",
"update",
"gpsMvtDetector",
"dnsProxy",
"sshTunnel",
"geoFencing",
"temperatureSensor",
"onewire",
"pwrManager",
"gps",
"criticalCommandManager",
...
"versionManager",
"binaryGate",
"pdm",
"smartCardManager",
"bootReason"]

Partial configuration requests

You can request the configuration of one or some components with the request “somemods”.
You must specify the list of components as an array.

  • Server → Device: Request message format
{"request": "somemods", "data": [componentName,..., componentName] }

Example:

{ "request": "somemods", "data": [ "geoFencing", "binaryGate"]}
  • Device → Server: The device sends a message with the following format
{
	componentName: { "values": { paramName : value, paramName : [ value, ..., value ] , ..., paramName : value } },
	...
	componentName: { "values":{ paramName : value, paramName : [ value, ..., value ] , ... } }
}

Full configuration request

You can request the full configuration of the device with the request “allmods”.

  • Server → Device: request message format
{ "request": "allmods" }
  • Device → Server: the device sends a message with the following format:
    It is the same format as the partial request but with all the components of the device.

Setting parameters

You can set one or some parameters using the request “setval”.
You must specify the component name(s), parameter name(s) and value(s).
Note: if a value is an array, you must define the full array.

  • Server → Device: Request message format
{"request": "setval", "data": { componentName:{ paramName : value, paramName : [ value, ..., value ] , ... }, ... }}

Example:

{"request": "setval", "data":{ "gps":{ "default_antenna_source":"0" }, "geoFencing":{ "directory":[ "data/geofencing", "/mnt/user/mmc/geofencing" ], "active":"0" } }}
  • Device → Server: The device sends a message with the following format:
    There is no answer to a “setval” request.

Remote API Call Request

Remote API calls allow the user to access most features in the devices.

You must specify:

  • the component name
  • the published interface of the component
  • the method
  • the list of the parameters, and for each parameter, its type and its value

Note: The method will be called in the same process of the adminProtocol component.
Beware when calling blocking method.

Call request format

You must use the request “methodcall”.

Note:

  • Some APIs require that the BuffRef given in the parameter to get the answer back be big enough to contain the answer. E.g for the DB API in version 2.3.6. The BuffRef can be padded with space on any other characters.
  • If a parameter is an array, you must give the full array. See the SDK for further information on the API that can be called.
  • Server → Device Request message format:
{ "request" : "methodcall", "component": componentName, "interface" : interfaceName, "method" : methodName, "params" : [ { "type" :  typeValue, "value" : paramValue }, ..., { "type" :  typeValue, "value" :  paramValue } ] }

With
componentName = component name as JSON string
interfaceName = published interface as JSON string
methodName = method to call as JSON string
typeValue = type of parameter. as JSON string

Type can be : “byte”, “byte[]”, “char”, “char[]”, “BuffRef”, “int”, “int[]”, “IntRef”,“boolean”, “boolean[]”, “BoolRef”, “String”, “String[]”, “long”

paramValue = depending of type. See the following table:

Type as JSON string Value
“byte” JSON int
“byte[]” JSON array of JSON int
“char” JSON char
“char[]” JSON array of JSON char
“BuffRef” JSON string
“int” JSON int
“int[]” JSON array of JSON int
“IntRef” JSON int
“boolean” true or false
“boolean[]” JSON array of (true or false)
“BoolRef” true or false
“String” JSON string
“String[]” JSON array of JSON string
“long” JSON int
“void” null

Example 1:
To callcom.mdi.services.commandManager.CommandManager.treat (BuffRef command, BuffRef response)
with the command “status”.

{ "request":"methodcall", "component":"com.mdi.services.commandManager", "interface":"CommandManager", "method":"treat", "params":[ {"type":"BuffRef", "value":"status" },{ "type":"BuffRef", "value":"" } ] }

Example 2:

To call com.mdi.drivers.ios.DigitalOutputs.setState (int outputNumber, boolean state) to set the output 2 to an inactive state
{ "request": "methodcall", "component": "com.mdi.drivers.ios", "interface": "DigitalOutputs", "method":"setState", "params": [ { "type":"int","value": 2 }, { "type":"boolean", "value": false } ] }

Response format

The device sends an answer including all parameters that are of type BuffRef, IntRef or BoolRef (same order as in the method prototype) plus the result of the call.

It is given as a JSON array with type and value for each parameter and for the result.

If the method returns nothing, type is “void” and “value” is null.

The format is the following:

[ { "type": typeValue, "value": paramValue }, ..., { "type": typeValue, "value": paramValue } ]

With
typeValue = type of parameter as JSON string.See the former table.
paramValue = depending of type. See the former table.

Example 1:
Result for call of com.mdi.services.commandManager.CommandManager.treat (“status”,"") that returns a boolean.

[ { "type":"BuffRef", "value" :"" }, { "type" :"BuffRef", "value" :"status,358281005317064_000505020000282a,2.27112,48.84585,108690,8,G,P,M,b,2, w,-1,G" }, { "type" :"boolean", "value" : true } ]

Example 2:
Result for call of com.mdi.drivers.ios.DigitalOutputs.setState (2, false) that returns a boolean

[ { "type":"boolean", "value" : true } ]

DB request example

Here is an example to get a value in the DB of the device.
It requires 2 remote API calls : one to get the DB key, one to get the value.

The example is based on a 2.3.6 version where the BuffRef must be padded to get the answer back.
The requested key is MDI_BOARD_ID

  • Request of the DB key
{ "request" : "methodcall", "component":"com.mdi.tools.config", "interface" : "DB", "method" : "getKey", "params" : [ { "type":"String", "value":"MDI_BOARD_ID" } ] }

Response:

[ { "type" : "int", "value" : 47 } ]
  • Request of the value
{ "request" : "methodcall", "component" : "com.mdi.tools.config", "interface" : "DB", "method" : "get", "params" : [ { "type":"int", "value" : 47 }, { "type" : "BuffRef", "value":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } ] }

Response

[ { "type" : "BuffRef", "value" : "000505020000282a" }, { "type" : "int", "value" : 0 } ]