Overview

Software running locally on a gateway can communicate with the EDGEHOG Device Manager Agent via internal local APIs.

The Device Manager Agent exposes a Socket Server on port 5288 that supports the TR-50 M2M standard, in order to communicate and let use a subset of its services.

The client-server communication is JSON based with two main sections:

• Authentication: specifies any authentication for the request

• Command(s): specifies any commands to be sent

Here you can find the specification of the TR-50 messages that can be used to communicate with the Device Manager Agent.

TR-50 typical Request

To use the command interface on the API, you must format the messages you send according to the TR50 protocol specification which defines a JSON object format.

Multiple commands can be sent in a single packet. Each command must have a unique command ID (the "1" and "2" below) so that the replies can be properly correlated. The "params" field is optional, and the contents depend on the particular command. If a command has no parameters, it is best to not send the parameter field at all.

{  
   "auth":{  
     "applicationToken":"<applicationToken>",
     "sessionId":”<sessionId>”
   },
    
   "1":{  
      "command":"<insert_command_here>",
      "params": {<command_specific_parameters_here>}
      }
   },
   "2":{  
      "command":"<insert_command_here>",
      "params": {<command_specific_parameters_here>}
      }
   }
}

TR-50 typical Response

Each command will respond with a "success" boolean that is either true or false. If the success field is false, then the errorCodes and errorMessages fields will be available, each field is an array allowing for multiple error codes to be referenced.

{  
   "1":{  
      "success":true,
      "params": []
      }
   },
   "2":{  
      "success":false,
      "errorCodes": 
       [
        <errorCode1>,
        <errorCode2>
       ]
       "errorMessages":
       [
        "errorMessage”,
        "errorMessage”
       ]
      }
   }
}

Here some bash examples of requests that can be done through the terminal.

$ nc localhost 5288 
{ "1": { "command": "cmd.test"}}
​
$ cat > /dev/tcp/localhost/5288
{ "1": { "command": "cmd.test"}}
​
$ exec 3<>/dev/tcp/localhost/5288
$ echo "{ "1": { "command": "cmd.test"}}" >&3
$ cat <&3
​
$ exec 3<>/dev/tcp/localhost/5288 && echo "{ "1": { "command": "devman.info"}}" >&3 && cat <&3

File Uploader External ACK

In a File upload request, more control over the validation of the file can be added by enabling the receipt of an ACK from external software. When the external ack is enabled in the File Model, EDGEHOG Device Manager Agent waits for an ACK message from a third-party application to confirm the successful download campaign to the Cloud.

The ACK need to be sent through TR-50, specifying in the request the absolute path of the downloaded file.

{  
   "1":{  
      "command":"file.ack",
      "params":{
        "success": boolean,
        "path": "string",
        "[message]": "string"
      }
   }
}

Here an inline bash example:

$ nc localhost 5288
{ "1": { "command": "file.ack", "params": { "success": true, "path": "/var/lib/seco-iot/downloads/test_dir/test.bin"  }}}