Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


In its default state (where no "regions" or "layouts" are defined), it should look and behave similarly to (and eventually , the same as) the "classic" Topology view.


  • <region-id> is a unique identifier for the region
  • <region-name> is a human readable name for the region
  • <region-type> is one of the values defined in the Region.Type enumeration:
  • <lat/Y>, <long/X> are the latitude / longitude (for geo layouts) or Y-coord / X-coord (for grid layouts) to be assigned to the region when it is displayed as a node in its parent layout.
  • <locType> is either geo (for geographical (map) layoutto indicate coords are lat/long) or grid (for logical grid layoutto indicate coords are Y/X).
  • <region-master> is a list of sets of node-IDs for mastership of the devices (see RegionAddCommand for more details).


Code Block
region-add-devices rUK \
    of:0000000000000001 \
    of:0000000000000002 \    



The regions currently configured regions in the system can be listed with the regions command:


Code Block
onos> regions
id=rDE, name=Germany, type=COUNTRY
id=rES, name=Spain, type=COUNTRY


(Another region command we'll look at is region-add-peer-loc, but we'll defer that until we have covered layouts).

Note that regions do not have any notion of hierarchy; they are simply "collections of devices". The hierarchy is expressed using Layouts


A Layout is a "UI construct" that has an associated region "backing" it. Layouts define some other layout as its parent (except for the "root" layout, of course)) declare their parent layout, thereby allowing defining a hierarchy of layouts to be constructed.

This could be pictured as shown hereThe following diagram illustrates an example:

Note that the "root" (default) layout does not have a backing region. Any devices (and their attached hosts) that have not been assigned to a region will appear in the topology view at this top level.


Code Block
layout-add root @europe . . 4.66 -2562.93 -412.56
layout-add lUK @europe rUK root 11.63 -6652.54 -938.04
layout-add lIT @europe rIT root 7.15 -4818.73 -1330.36
layout-add lFR @europe rFR root 8.98 -5378.99 -1334.77

layout-add lMilan +segmentRouting rMilan lIT 0.86 68.58 54.71

Notes on <bg-ref>:

The <bg-ref> parameter should take the form:

    • "."            : to define no background,
    • "@{map-id}"    : to define a geo background, or
    • "+{sprite-id}" : to define a grid layout background

Map identifiers can be listed by using the ui-geo-map-list command in the onos CLI:

Code Block



onos> ui-geo-map-list
UiTopoMap{id=australia, desc=Australia}
UiTopoMap{id=americas, desc=North, Central and South America}
UiTopoMap{id=n_america, desc=North America}
UiTopoMap{id=s_america, desc=South America}

Additional maps can be registered from an application's server-side UiExtension implementation. 

Sprite identifiers can be listed by opening the web console, making sure verbose option is selected, and filtering for the string "createLayout":

Image Added

Additional sprite layouts can be registered from an application's topology overlay JavaScript code.

(need link to tutorial on building a custom topo2 overlay)


Notes on <scale>, <offset-x>, <offset-y> values can be determined by trial and error. See the section on Useful Techniques below for more detailsvalues:

Currently, getting these values right is a manual process:

    • start by setting them to  1.0  0.0  0.0
    • enable debugging of UiWebSocket to see message transmissions between client and server
      • onos> log:set DEBUG org.onosproject.ui.impl.UiWebSocket
    • in the UI, pan and zoom the map to the desired location
    • in the log, identify the last UiWebSocket RX message for "updateMeta2"
      • 2017-05-26 17:07:15,750 | DEBUG | tp1445302012-173 | UiWebSocket                      
      • | 158 - org.onosproject.onos-gui - 1.11.0.SNAPSHOT | RX message: 
      • {"event":"updateMeta2","payload":{"id":"layoutZoom",
      • "memento":{"scale":4.66,"offsetX":-2560.646888427734,"offsetY":-409.13537841796875}}}
    • use the values listed in the "memento" for your scripted command (you should be safe rounding to 4 decimal places)

One further note:

If the user zooms and pans a layout, the UI will remember how they left it.

However, by pressing the 'R' key, the map/grid will reset to the values configured in the layout-add command.