facet

In a large working environment with many devices, such as an NS Power Grid deployment, writing an extensive suite of dialog menus for the sole purpose of displaying the status of numerous appliances quickly grows somewhat tedious. To mitigate this, RCG-DEV and FSD-DEV present Facet, a vendor-agnostic, reskinnable interface utility for displaying appliance status information on the HUD.

The Facet control channel is 5200. This is used bidirectionally for communications between the HUD and compatible appliances. Messages on the control channel are space-separated to facilitate human readability (and manual control), although appliances may send messages with multiple lines (separated by \n) for e.g. presenting menus more compactly.

Selection

Selection is the task of connecting a HUD to an appliance for interaction. Normally this is done by clicking on the appliance, which causes the appliance to send welcome on the Facet channel (5200) to the agent. The focus is then set on the HUD to the appliance, and the HUD requests a full menu update.

  1. Scripted connection: as an alternative to clicking on a device to interface with it, Facet HUDs can send connect to an object to attempt hand-shaking. They should time out if no response is received within 5 seconds.
  2. Appliance confirmation: regardless of whether the user clicked the appliance or the HUD sent the connect command, the appliance should respond with welcome to let the HUD know that it is OK to proceed.
  3. Appliance refusal: refused <reason> should be sent if for some reason the HUD is not allowed to connect, e.g. limited number of concurrent users, group mismatch (if appropriate), etc. The reason will be displayed to the user by the HUD.
  4. HUD refusal: refused [reason] should be sent by the HUD to the appliance if the appliance has offered welcome unexpectedly; in this case the reason is optional. This allows the appliance to avoid retaining session information for non-users, if it does at all.

Menu presentation

To begin the session, Facet sends refresh to the device. It is met with a menu command from the device, which is structured as follows:

menu <icon>
<button>
<button>
...

Where icon is the UUID of a square texture to display on the HUD (should be at least 256x256) representing the device, and button is a message following one of the templates:

  • <name> button <fallback-image> <label>
    Presents a button matching the given label. If the skin (see next section) does not support the label specified, the fallback image will be displayed. If the fallback image is blank and the label is unsupported, then a placeholder image will be shown with the label displayed in text. The result of clicking this button will be sent to the device (see 'Commands')
  • <name> link <url> <label> ["|" <prompt>]
    Presents a button pointing to an external link. An attempt will be made to look up the label and match it to an image, but if the skin does not support a suitable label then text will be shown over a default image (distinct from the one used for buttons.) The 'prompt' message is shown when the user clicks the link button; if one is not specified, then the label is repeated.
  • <name> text <fallback-image> <label> ["|" <prompt>]
    Presents a button requesting user text input. Fallback image and label behavior is consistent with button-type entries (see above.) The 'prompt' message is shown when the user clicks the button; if one is not specified, then the label is repeated.
  • <name> color <r> <g> <b> [<prompt>]
    Presents a button for color selection; opening it should open a color selector with <r, g, b> (floating point 0.0–1.0) as the current value. Prompt behavior matches that of a text control.
  • <name> scale <frac> <label>
    Presents a slider or progress bar, filled from the left up to <frac> × 100% of its total width. The label will be displayed over it. The user may click on the slider to send adjustment requests to the device.

Names of buttons should be unique within a given menu message.

Skinning

The _skin file specifies the images and colors used to display the interface. Each line consists of a UUID for a texture followed by a name. Two colors are also specified in the skin file, the background and foreground of the scale bars. (In the default NS implementation, the background color is also used for the spacer under the header image.)

Commands

Commands from the Facet HUD to the device follow the formats of the button types, generally with the name of the button followed immediately by valid inputs:

  • button: <name>
  • link: no message generated
  • text: <name> <value>
  • color: <name> <r> <g> <b>
  • scale: <name> <frac>