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.
