Command

Commands allow you to control things directly from Omnyvore. More technically speaking, commands are bound to topics and represent outgoing flows of information directed to things over predefined topics. For example, you may want to remotely turn off a stove with just a click or a tap.

In the following subsections, we will illustrate you how Omnyvore makes this possible for you.

Create a new command

Select the Add button in the top right corner of the tab: Add button in Command list view

Then, you can configure the new command by filling out a dedicated window:

  • Name: mnemonic name for the command;
  • Description: textual explanation which you can (optionally) provide for the command;
  • Topic: suffix (ending part) of the topic over which data will be sent;
  • Message: payload of the message, in which you can define custom parameters by enclosing them in square brackets (e.g., [temperature]). For each of these parameters, you can put a textual description, specify its type and constrain the parameter to a set of values;
  • Retained: specify if the command is retained;
  • Message processing: either an expression written with Omnyvore's DSL or a script used to process the incoming payload. You can refer to the guidance provided for Channels, since processing works in the same way for Commands;
  • Request-reply settings: set if Omnyvore has to expect an asynchronous reply for the command and, optionally, if it has to process the reply message with custom behaviour. Creation window for command

Edit an existing command

To modify an existing command, click on it from the command list and then an editing window similar to the one used at creation time will appear. Nevertheless, this window includes also the test feature, which allows you to test commands before sending actual data to the device: this utility might be useful if you want to perform some dry runs before committing some modifications to an already existing script. Message processing tests are described more in detail in the Script section.

Delete an existing command

To delete an existing command, click on it from the command list and then an editing window similar to the one used at creation time will appear. At this point, you just have to click on the Delete link in the bottom left corner of the window.

Request-reply

Sometimes you might desire to launch a command and see a reply come back. This is the rational behind Omnyvore's request-reply feature, which helps correlating inputs received by a thing to the subsequent change of state. Omnyvore implements request-reply on top of a lightweight protocol: commands which support this feature contain two parameters automatically set by the platform, that is correlationid and replyto. These two parameters can be used to:

  • correlationid: identifier which has to be present also in the reply in order to correlate the reply to the starting request
  • replyto: topic to which the thing has to reply

Replies can be processed in two ways, i.e., by means of expression or with Omnyvore scripts (similarly to channels' and commands' data).

Processing replies with Omnyvore DSL

Omnyvore's DSL (Domain Specific Language) provides a handy way to process replies sent in response to commands. When using this option (which is called Editor in the Edit channel window), you can write an expression which will be used to parse incoming data. Writing these expressions is quite simple: you just have to compose a template which will be used to parse the payload.

Hereafter there are some examples, in which:

  • # Expression is the expression written in the editor
  • # Payload is the textual payload sent by the thing
  • # Outcome is what happens when Omnyvore applies the expression to the reply payload
Simple payload
# Expression
PAR(correlationid)
# Payload
24
# Outcome
Omnyvore checks that correlation id is defined and indeed it finds 24. If a command was sent with 24 as its correlation id, than no error occurs
Wrong payload
# Expression
PAR(speed)
# Payload
24
# Outcome
Omnyvore doesn't find correlation id defined

Processing replies with Omnyvore scripts

Sometimes devices send data alongside replies. For instance, a device may ask for the speed value with a command and have it returned in a subsequent reply. If you want to store measurements alongside replies, then you'll probably have to use Javascript snippets. When processing replies, your scripts have to return Reply objects.

Example of reply processing by means of scripts can be found in the following lines:

Simple payload
var payloadStr = OMV.toString(payload); // let's assume that the payload was the string '24'
var reply = new Reply();
reply.correlationId = payloadStr;
reply.payload = payloadStr;
reply.when = (new Date()).getTime();
reply.measurements = new java.util.ArrayList();
return reply;
Payload with measurements
var payloadStr = OMV.toString(payload); // let's assume that the payload was the string '{ "correlationId": 24, "speed": 56 }'
var payloadObj = JSON.parse(payloadStr);
var reply = new Reply();
var now = (new Date()).getTime();
reply.correlationId = payloadObj.correlationId;
reply.payload = JSON.stringify(payloadObj);
reply.when = now;
reply.measurements = new java.util.ArrayList();
reply.measurements.add(new Measurement('speed', payloadObj.speed, now));
return reply;