From GridLAB-D Wiki
Jump to: navigation, search

 REVIEW NEEDED 

This document describes the technical requirements for a GridLAB-D Graphical User Interface.

All changes to this document shall be processed as follows:

  1. A request for change is opened as a new top-level section in the discussion page.
  2. An impact assessment of the change shall be presented by those having standing to do so.
  3. The pros and cons of the changes shall be discussed in a subsections so labeled.
  4. The disposition of the change request shall be documented in a subsection so labeled.

Level 1 Requirements

All Level 1 requirements require Project Manager approval to be adopted.

Platforms supported

The GUI shall be implemented as a platform independent extension to the core.

Presentment encoding

The GUI layout shall be encoded so that it is driven by the GLM file. Ancillary files may be referenced by the GLM file.

Input entities

All GUI input entities functionality shall be implemented by the core.

Output entities

All GUI output entities functionality shall be implemented using a third-party plotting package (e.g., gnuplot, jpgraph).

Client/server model

The GUI shall be implemented using a client/server model over a TCP port registered with IANA.

Communication protocol

The server shall support HTTP 1.1 traffic according to RFC2616. All major clients conforming to HTTP 1.1 shall be supported.

Level 2 Requirements

All Level 2 requirements require Technical Manager approval to be adopted.

Entities supported

All GridLAB-D property types shall be supported for both input and output.

Entities with limited supported

TIMESTAMP, loadshape, enduse, and schedules shall be supported only as strings.

Synchronous loading

The GUI shall permit multiple gui blocks to the identified in a single session, provided each block is given a wait condition that pauses the loading process, presents the current GUI, and waits for the specified action to be selected by the user. After the wait condition is satisfied by the user, the current GUI is destroyed, and the load proceeds.

Supported clients

Runtime checks of supported browsers shall be performed at GUI startup to ensure that the GUI supports the major browsers at the time of delivery, specifically IE8, Firefox3, Safari5, and Chrome2 and

Level 3 Requirements

All Level 3 requirements require Task Manager approval to be adopted.

GLM GUI block syntax

GUI block

A GUI block shall be introduced by the term gui followed by a GLM block enclosed in {} braces.

Page entity

A page entity shall be introduced in a GUI block by the term page followed by a GLM block. Page entities shall instruct the server to copy the contents referred to by the source term. The source shall refer to the file containing the HTML code for the page, relative to the same path as the GLM file in which it is specified.

Wait entity

A wait entity shall be introduced in a GUI block by the term wait. Wait entities shall instruct the GUI loader to wait for the specified action button to be clicked before continuing the load process. The value of the wait entity shall determine what action button is required to continue the loading process.

Server connection

Connection threading

The server shall use a single thread only when connected to a GUI client and shall not accept other incoming connections while a connection is active.

Connection shutdown

The server shall respond to queries on the first successful connection received and shutdown the simulation when that connection is closed.

Multiple connection

The server shall have an option to operate in multi-client mode, as specified by the server_quit_on_close global variable.

XML transactions

XML object property queries

XML queries for object properties shall be transmitted in the current form /name/property. The response shall be mime text/xml in the form

<value>value</value>

If the value is given in a known unit, the unit shall be appended to the value and separated by a space character.

XML global variable queries

XML queries for global variables shall be transmitted in the form /name. The response shall be mime text/xml in the form

<value>value</value>

If the value is given in a known unit, the unit shall be appended to the value and separated by a space character.

XML updates

All queries containing an = character followed by text shall be treated as a set operation and update the specified variable or property as requested. The previous value of the variable or property shall be returned. The set value shall be parsed in a manner identical to the loader, including unit handling and functionals, but excluding macros, equations, transforms, and expressions.

XML object property list queries

XML queries for a list of known object properties shall be transmitted in the form /properties?name. The response shall be mime text/xml in the form

<properties>
  <property>name1</property>
  <property>name2</property>
  ...
  <property>nameN</property>
</properties>

XML global variable list queries

XML queries for a list of global variables shall be transmitted in the form /globals?. The response shall be mime text/xml in the form

<globals>
  <name>name1</name>
  <name>name2</name>
  ...
  <name>nameN</name>
</globals>

XML object find queries

XML queries for a list of objects shall be transmitted in the form /objects?filter where filter conforms to the search filter syntax for FINDPGM *find_mkpgm(char *search) (see Search functions for details). The response shall be mime text/xml in the form

<objects>
  <name>name1</name>
  <name>name2</name>
  ...
  <name>nameN</name>
</objects>

where the objects listed are those returned by FINDLIST *find_runpgm(FINDPGM *pgm, FINDLIST *list) (see Search functions for details).

XML unit conversion queries

XML queries for unit conversion shall be transmitted in the form /convert/value%20fromunit?tounit. The response shall be mime text/xml in the form

<value>value tounit</value>

GUI entity requests

GUI page requests shall be transmitted in the form /gui/pagename. All GUI page responses shall be mime text/html.

Output entity requests

Output requests (e.g., csv data) shall be transmitted in the form /output/filename, where the file is the name given in the GLM tape object. All output responses shall be the appropriate mime type, e.g., png, text/csv.

Gnuplot entity requests

Any request in the form /gnuplot/file?mime shall run Gnuplot with the indicated file name as the script, which is assumed to generate an output file of the specified mime type. The response shall be the specified mime output from gnuplot.

Perl entity requests

Any request in the form /perl/file?mime shall run Perl with the indicated file name as the script, which is assumed to generate an output file of the specified mime type. The response shall be the specified mime output from Perl.

Java entity requests

Any request in the form /java/file?mime shall run Java with the indicated file name as the script, which is assumed to generate an output file of the specified mime type. The response shall be the specified mime output from Java.

Favicon requests

A request for /favicon.ico shall return the file stored in rt/favicon.ico if present.

Cache support

All responses shall request that the client not store data and disable caching.

Level 4 Requirements

All Level 4 requirements require Technical Contributor approval to be adopted.

Object property get function

The object property get function shall use the function prototype gldGetProperty(name,property) and shall return the value of the object's property.

Object property set function

The object property set function shall use the function prototype gldSetProperty(name,property,value) and shall return the previous value of the object's property.

Global variable get function

The global variable get function shall use the function prototype gldGetVariable(name) and shall return the value of the global variable.

Global variable set function

The global variable set function shall use the function prototype gldSetVariable(name,value) and shall return the previous value of the global variable.

Object properties get function

The object get function shall use the function prototype gldGetProperties(name) and shall return a list of the object's properties.

Globals get function

The global get function shall use the function prototype gldGetVariables() and shall return a list of the defined global variables.

Object find function

The object find function shall use the function prototype gldFindObjects(filter) and shall return a list of the object names that match.

Unit conversion function

The unit conversion function shall use the function prototype gldConvertUnit(value,from,to) and shall return the converted value.

See also