This is an archive of the ONOS 1.0 wiki. For the current ONOS wiki, look here.


NOTE: The GUI architecture is migrating to use the AngularJS framework – some of the information on this page is deprecated (the topo events are still good).

The ONOS GUI is a single-page web-application with hash-navigation. The GUI system comprises client-side code (a single HTML page, javascript libraries and modules, CSS files, etc.) and server-side code (Java classes that interface to ONOS Server APIs). The GUI web page is served up by a web server running on an ONOS instance.

Client-Side Architecture (Deprecated)

The client side code is comprised of:

The main application page
  • index.html
Third party libraries
  • tp/jquery-2.1.1.min.js
  • tp/d3.js (v3.4.12)
  • tp/topojson.v1.min.js

Framework code and supporting modules

  • onos.js
  • onosFlash.js
  • onosFloatPanel.js
  • onosMast.js
  • onosQuickHelp.js
Supporting libraries
  • d3Utils.js
  • geometry.js
  • glyphs.js
Topology view
  • topo.js
View module templates
  • module-div-template.js
  • module-svg-template.js
Sample views
  • sample.js
  • sampleHash.js
  • sampleKeys.js
  • sampleRadio.js

... along with their associated *.css stylesheets. 

The structure of the framework allows for the registration of multiple "views" and the subsequent navigation between them. 

For the first release, however, there is but a single view, the Topology View.

View Registration (Deprecated)

A view registers with the framework via a call to the addView(...) function.

onos.ui.addView('viewId', {
    init: init,
    reset: reset,
    load: load,
    unload: unload,
    resize: resize,
    theme: theme

The first argument to the function is a short string identifier for the view. 

The second argument to the function is an inline object block with the given keys, whose values are references to view life-cycle callback functions:

initThis function is called only once, the first time the view is loaded. It is called after the view's <div> has been added to the DOM.
resetThis function is called just before the view is shown. It can be used to clear stale data from the view.
loadThis function is called when the view is loaded.
unloadThis function is called when the view is unloaded. The view may use this to drop references to cached data, or stop background tasks.
resizeThis function is called when the view has been resized.
themeThis function is called when the user has toggled the theme.


Topology View (Deprecated)

In the first release, the Topology View is the only view available; it is loaded at GUI startup. The following paragraphs summarize each of the view's callbacks:


The init callback is used to initialize the view's SVG layer (including pan and zoom controls) and the Force Layout used to visualize the topology.


The reset callback is not needed, and thus not implemented.


The load callback starts by injecting the radio button set into the masthead and registering key bindings and mouse gesture descriptions. After that, it performs an asynchronous load of the background GeoMap (Continental USA), before finally opening a websocket connection to the server.

Once the websocket is established, an initial requestSummary event is sent to the server. The UI then processes incoming events from the server to build up a view of the topology. See Event Descriptions below.


The unload callback cancels the background timer, if it is running.


The resize callback updates the size of the SVG layer.


The theme callback updates instance and device colors.

Topology Model

The UI maintains an internal model of the topology by storing data representing ONOS instances, nodes (devices and hosts) and links. The model is empty initially, but is augmented as events (such as addInstance, addDevice, addLink, etc.) come in from the server. As these events arrive, the model is updated and the visual representation modified to reflect the current model.

Client-Server Communication

The Topology View uses a websocket to establish communication with the server. This provides a dedicated TCP connection along which the client and the server can emit messages to the other side. The server sends messages to the client describing status updates and/or changes to the topology; the client sends messages to the server, in response to gestures made in the UI by the user, requesting actions to be performed or requesting additional data.

Event messages are structured JSON objects, with the following general format:

  "event": "eventType",
  "sid": ... ,
  "payload": {

The event field is a string uniquely identifying the event type.

The sid field is an optional sequence identifier (monotonically increasing integers) which, if provided by the client, should be duplicated in the server's response to that event. Note that, in general,  server-initiated events do not include a sid field.

The payload field is an arbitrary JSON object the structure of which is implied by the event type. Many payloads include an id field at the top level, which holds the unique ID of the item being described by the event.

Event Descriptions

The following table enumerates the events, providing a high-level description of the payload. For explicit details of the payloads, see the source-code (smile).

Note that the term "node" (in this context) is used to mean "device or host node" in the topology visualization.

SourceEvent TypeDescription of PayloadTriggerComments
UIrequestSummary(no payload)Summary pane shownClient requesting the server to send topology summary data.
ServershowSummaryHigh level summary properties: total number of devices, links, hosts, ...Periodic updates in response to requestSummaryThe summary data is displayed in a "fly-in" pane in the top right of the view. Note that the server will continue to send these events to keep the summary data up-to-date.
UIcancelSummary(no payload)Summary pane hiddenClient requesting the server to stop sending summary data.
ServeraddInstanceInstance ID, IP address, online status, ...ONOS instance added to clusterAn ONOS instance to be added to the model.
ServeraddDeviceDevice ID, type, online status, mastership, labels, properties, ...ONOS discovers new deviceA device (switch, roadm, ...) to be added to the model.
ServeraddHostHost ID, type, connection point, labels, properties, ...ONOS discovers new hostA host (endstation, bgpSpeaker, router, ...) to be added to the model.
ServeraddLinkLink ID, type, source ID/port, destination ID/port, ...ONOS discovers new linkA link (direct, optical, tunnel, ...) to be added to the model.
ServerupdateInstance(same as addInstance)Instance changes stateAn ONOS instance with updated state.
ServerupdateDevice(same as addDevice)Device changes stateA device with updated state.
ServerupdateHost(same as addHost)Host changes stateA host with updated state.
ServerupdateLink(same as addLink)Link changes stateA link with updated state.
ServerremoveInstance(same as addInstance)(1)ONOS instance leaves clusterAn ONOS instance to be removed from the model.
ServerremoveDevice(same as addDevice)(1)Device removedA device to be removed from the model.
ServerremoveHost(same as addHost)(1)Host removedA host to be removed from the model.
ServerremoveLink(same as addLink)(1)Link removedA link to be removed from the model.
UIupdateMetaitem ID, item class (device, host, ...) memento dataUser drags node to new positionClient requesting data (a memento) associated with a specific node to be stored server-side; That same data (memento) should be returned in the payload of future events pertaining to that node. This mechanism facilitates server-side persistence of client-side meta data, such as the (user-placed) location of a node on the topology map.
UIrequestDetailsitem ID, item class (device, host, ...)User selects node on mapClient requesting details for the specified item.
ServershowDetailsitem ID, item type (switch, roadm, endstation, ...) and list of propertiesResponse to requestDetailsServer response to requestDetails.
UIaddHostIntentIDs of two selected hosts'Create Host-to-Host Flow' action button on multi-select pane.Client requesting server to install a host-to-host intent.
UIaddMultiSourceIntentIDs of selected nodes (multi source, single destination)'Create Multi-Source Flow' action button on multi-select pane.Client requesting server to install multiple intents.
UIrequestRelatedIntentsIDs of selected nodes, ID of hovered-over node'V' keystrokeClient requesting intents relating to current selection of nodes be highlighted.
UIrequestPrevRelatedIntent(no payload)'L-arrow' keystrokeClient requesting previous related intent to be highlighted
UIrequestNextRelatedIntent(no payload)'R-arrow' keystrokeClient requesting next related intent to be highlighted
UIrequestSelectedIntentTraffic(no payload)'W' keystrokeClient requesting continuous monitoring of traffic on the links of the selected intent
UIrequestDeviceLinkFlowsIDs of selected nodes, ID of hovered-over node'F' keystrokeClient requesting continuous monitoring of flow rules on the egress links of the selected device(s)
UIrequestAllTraffic(no payload)'A' keystrokeClient requesting continuous monitoring of traffic on all network infrastructure links
ServershowTrafficlist of paths (sets of link IDs) and labels to apply to those links, as well as the styling classes to apply to those pathsResponse to UI requests marked with Server response to requestTraffic. Note that the server will continue to send these events to keep updating the display.
UIcancelTraffic(no payload)'ESC' keystrokeUser cancels selection – Client requesting the server to stop sending traffic updates.
UIequalizeMasters(no payload)'E' keystrokeClient requesting server to rebalance mastership of devices across the cluster.


(1) Technically, only the ID field is required, but the server-side code is simplified by using the payload as is.

The topology model on the server side represents links as unidirectional, with a source and destination. In the UI, each link model object abstracts away the directionality. This is to provide a single "link" element between two "nodes" in the visualization. However, this makes the link event processing a little more complex. Internally the links are modeled something like this:

When a link event arrives, a lookup is done to see if the "parent" object for that link already exists. 

Server-Side Architecture

Websocket Servlet

When the topology view is loaded it makes an HTTP request to ws://<server>/onos/ui/ws/topology URL. This requests gets upgraded into a Web-Socket, thus establishing a symmetric and persistent connection between the client and the server. On the server side, this process is facilitated by GuiWebSocketServlet, which extends Jetty WebSocketServlet and results in creation of a session-specific TopologyViewWebSocket instance. This instance holds the necessary session-state for interacting with this specific client.

Topology Resources

The following Java classes comprise the server-side code for the Topology View:

  • TopologyResource - provides REST API for some auxiliary functionality, e.g. export of GEO location data
  • TopologyViewIntentFilter - responsible for identifying list of intents which pertain to the specified sets of end-station hosts or infrastructure devices
  • TopologyViewMessages - base class for composing various messages destined for the client and parsing those that were received from the client
  • TopologyViewWebSocket - main controller for processing inbound messages and emitting appropriate responses

To see the server-side handling of the UI, take a look at TopologyViewWebSocket, in particular the web socket methods:

  • onOpen()
  • onMessage()
  • onClose()



Previous : The Intent Framework
Use Cases : Architecture


  • No labels