Thing commands

Omnyvore allows you to define and send command to the things. While the former can be done in the thing family settings, you can send commands from the management page of each thing.

To access the management page of a thing you need to look for and then select the thing in the thing list page, then click on the Manage button in the right upper corner.

The functionalities of the management page are divided into tabs, three of them are related to commands.

List of allowed commands

In the management page select the Commands tab. The tab contains all the commands configured for the family of the thing displayed as a grid of blocks. Each block of the grid is a command and it shows:

  • the name and description of the command;
  • the maximun number of parameters the user have to fill (also the not mandatory are counted);
  • the request/reply nature of the command;
  • the retained nature of the command.

Retained commands are persisted commands: this means that the command message is saved and sent to the thing each time it reconnects and subscribe to the command topic.

Also the color of the box circle is very important:

  • the circle of the color is blue when the thing is connected or the command is set as retained. This means that the user can actually send the command because he is sure that it will arrive to the thing;
  • the color is red when the thing is offline and the command is not set as retained. In this case the user can't send it simply because it will be lost.

Send a command

Click over the command box you want to send from the grid of commands, remember that the box circle must be colored in blue (red means that you cannot send it). After that, the parameters form window will appear. Fill out all the mandatory parameters and click the Send button. If the command doesn't require a reply, a simple message "Command sent" will appear. Otherwise, when commands are configured with request/reply, the box will wait for the thing to reply. A placeholder "Waiting for reply" will be displayed and, when the reply arrives, the placeholder will be replaced by the time and payload of the reply.

View command history

Sometimes is very important to search and analyze commands already sent to the things, for this reason the platform save each command sent. To view the history of commands sent to a thing simply select the Command History tab in the thing manage page.

By default the list contains the commands sent in the last 24 hours. Still, you can change this behavior by clicking on the Show filter button and setting the time interval you want to search over.

Each row of the list corresponds to a command sent and contains the following information:

  • Request time: when the command has been sent;
  • Name: the name of the command that has been sent;
  • User: which user sent it;
  • Request message: the payload which was actually sent;
  • Expect reply: "yes" if the command is set as request/reply, "no" otherwise;
  • Reply Received: "yes" if a reply has arrived, "no" otherwise.

By selecting a row in the list, you will open a new window containing more details about the command. The detail view contains:

  • complete information about the command sent (colored in blue);
  • information about reply, e.g., the receiving time and the payload (colored in green);
  • a warning message (colored in red) if the reply was expected but it never arrived.

View the current retained command values

Omnyvore allows you to set commands as Retained, i.e., messages that are sent will be always available each time a thing connects, until you overwrite them by sending a command once again.

Omnyvore's communication mechanism is based on MQTT. For this reason, in order to receive a retained message the firmware of the thing must connect to Omnyvoew and also subscribe to the topic of the command.

This feature (that is, retained messages) leads to a couple of problems:

  • it may be difficult to retrieve the current retained messages for a command;
  • it may not be straightforward to simply clean the retained message, without overwriting it with another bogus value.

To manage these problems you can access the Retained commands tab. This tab will show you the list of current values for retained commands and provide you with the ability to erase the published value by selecting the X button on the right end of each row.