UniDA BasicGUI: Use Guide

About

The purpose of this document is to provide a simple guide for the UniDA BasicGUI application. This Java Swing based GUI acts both as a simple generic GUI that can interact with any available UniDA device and as a demo that shows how to use the UniDA API.

This guide covers mainly the first aspect so it explains every feature that UniDA BasicGUI provides. It also serves as a good entry point to learn the ideas of the UniDA protocol, which this app makes fully available.

Contents:

1. Main Window and Gateways
2. Manage autonomous behavior rules
3. Operations on a selected UniDA device:
   1. Send commands to a device
   2. Send On/Off commands to a device
   3. Read current values of all device states
   4. Read current value of a single device state
   5. Write a value for a device state
   6. Subscribe to a device state

Main Window and Gateways

The main window shows two areas that contain both data and actions. First block shows the detected UniDA gateways and second block contains info and actions for the devices that the selected gateway contains.

The gateways area contains:

• A grid that shows the detected UniDA gateways. For each one, its UniDA address and current registered state.
• A button to launch an UniDA Announce Request message ("Force Announce").
• A button that opens a dialog window to manage the autonomous behavior rules for the selected UniDA gateway.

The second block of main window contains the data and actions for the UniDA devices announced by the selected gateway:

• A grid that shows the Gateway IOs for the selected gateway. And for each IO, its numeric identification and a list of all the states it supports.
• A grid with info about the devices that the selected gateway manages. For each device, its complete identification (UniDA address plus device id), type and which IO is connected to.
• Buttons for actions related to a selected device (send a command, read its states, write a value for one state and subscribe to changes in one state).

A more user friendly focused UniDA based application would not show the gateways however, nor the gateway IOs. It should be device-centered. This is because the intent is that UniDA clients interact with UniDA devices, so UniDA gateways are just mediators that handle UniDA devices (and something UniDA clients don t need to worry about).

Manage autonomous behavior rules

TBD

Send commands to a device

For a selected UniDA device, this app allows the user to input the data for a command message that can be sent to that device.

An UniDA command message needs at least the functionality ID and command ID that identify the command to be executed on the selected device. The values for both IDs must be OWL axioms taken from a version of the DogOnt ontology that is used by the UniDA. The currently used descriptors for this ontology are these: DogOnt "base" ontology, classes added for UniDA .

The "Send Command" buttons sends away the UniDA message, and the GUI shows whether its ACK response message is received.

For some commands, one or more values are expected. These values can be OWL axioms or literals. If several values are accepted by the command being prepared, ";" will be interpreted as separator.

Send On/Off commands to a device

There is a kind of command that many devices support: the commands that turn it on and off (these commands are OnCommand and OffCommand, from OnOffFunctionality). A specific dialog is provided to send both to a selected device.

Read current values of all device states

Each device can inform of the current values for the states that describe it. To access that information, the BasicGUI app provide the "Read All States" button that sends an UniDA states request message and opens a dialog which shows the data that came with the UniDA states reply message.

Read current value of a single device state

UniDA provides another mechanism to consult the current state values of an UniDA device. Instead of asking for all the device states, a Unida state request message queries for just one state.

For a selected UniDA device, a dialog can be opened by clicking the "Read One State" button. This dialog asks for the URI that identifies the state to be queried. An UniDA state request message is sent by clicking on "Send Request", and the returned information with the current value for that state is shown when the UniDA state reply message is received.

Write a value for a device state

In some cases, an UniDA device allows a state to be changed using just an UniDA write state message.

The user must input the ID for the state whose value is to be written, along with the new value (which can be a literal or an URI for an OWL axiom).

After the "Send Request" button is clicked, an UniDA write state message is sent. The GUI shows whether its ACK is received or not.

Subscribe to a device state

For a selected device, the BasicGUI app allows the user to create a subscription to any state announced by the device. All that is needed is the ID for that state.

When the "Subscribe" button is clicked, an UniDA notification subscription message is sent. When that is done, any time the subscribed state is changed, and UniDA notification message reaches the BasicGUI app to inform of its new value, and the subscription dialog shows that new value to the user.