edgent-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dan Debrunner <...@debrunners.com>
Subject Re: Standard commands for Quarks applications?
Date Tue, 10 May 2016 22:58:06 GMT
On 5/10/2016 3:08 PM, Susan Cline wrote:
  > Is it documented some where / can someone refer me to a list of 
commands (and the payload format) I can send to an IOTF device in a 
quarks application?

Not sure a central lists exists yet, I will work on one if I can figure 
out a good place in the javadoc for it.

The control mechanism is through the ControlService, which allows MBeans 
to be registered. MBeans are basically a subset of a full JMX MXBean 
because Quarks runs on Android which doesn't support JMX.

So the control service allows execution of operations (method calls) 
against registered control MBeans from outside a Quarks application.

Two implementation of the control service exist, JMX and JSON.

JmxControlService registers the MBeans within the platform JMX server 
thus allowing standard JMX control (remote clients etc.)

JsonControlService registers the MBeans and allows a JSON control 
request object to invoke an operation. The JSON object format is 
described (briefly) in the package for the JsonControlService but its 
formatting was messed up so it doesn't appear in the Javadoc (I'll fix 
that). The JSON control request object is passed directly into the 
JsonControlService instance to invoke the method.

This means that basically any void method on an MXBean can be invoked 
through the control service. Thus by looking at the MXBeans (class names 
ending in MXBean) one can see which operations are supported.

Separately the IotProvider sets itself up so that an IoT device command 
with command identifier `quarksControl' is sent to its 
JsonControlService. As long as a MBean can be identified uniquely by a 
type and an alias the operation will executed against that control MBean.

The command's data is the JSON control request, thus for example by 
sending a device command with identifier `quarksControl` and data:

{"type":"appService","alias":"quarks","op":"submit","args":["Heartbeat",{}]}

Will result in this method being called against the MBean registered by 
the ApplicationService to start the Heartbeat application.

ApplicationServiceMXBean.submit("Heartbeat", "{}")

Basically for the MBean of type 'appService' and alias 'quarks', call 
the method 'op' with arguments 'Heartbeat' and an empty JSON object 
(there are auto string<->json conversions).

The sample IotfFullScenario can be used to demonstrate this concept with 
IBM Watson Iot Platform.

> I’d like to know if all quarks applications will be accepting specific commands and
what format the payload needs to be in.  Is it correct to say that all
> iotf commands are in JSON format, and the required fields are these:
>
> { “my command”:
> 	{“payload”: {“application specific param1” : “app specific value 1”}}
> }

What you are doing is sending a device command to an application, in 
that case the device command has an identifier and data, the identifier 
is a string and the data is JSON. The format of the JSON is up to the 
application.
[What you are seeing with payload is a bug that I've just fixed pr114)]

I'm not sure where you saw the JSON format above, I don't think any 
Quarks code has the command data as the value for the command identifier.

"All Quarks applications" is somewhat hard to answer, since Quarks is an 
SDK there can be simple quarks applications that don't use IoTDevice, 
Iotf, the application or control services. But if Quarks applications 
are running in the IotProvider framework then they will support a number 
of commands:
  - submit application
  - change job state (e.g. to stop a running job)
  - any application that registers PeriodMBean's with a unique alias can 
have its period change (e.g. a periodic source). This will obviously be 
application specific.

> For example I think I have heard about a “start” and “stop” application command.
 Can someone tell me how these would work and if any other commands are available as
> “standard” commands?

The start command is the command above to submit an application 
previously registered with the application service.

I've just added a method to JobMXBean that will allow stopping a job 
now, and maybe pause eventually.

HTH,
Dan.


Mime
View raw message