The Bliss GUI Framework Installation Guide Author Date Matías Guijarro 08/09/05
Index 1. Installing the Framework... 3 1.1 Deploying the packages... 3 1.2 Testing the installation... 4 2.Setting up the Hardware Repository... 5 2.1 What is the Hardware Repository?... 5 2.2 Installing the Hardware Repository Server... 6 2.3 Starting the Hardware Repository Server... 6 2.3 Start filling the Hardware Repository... 8 2.4 Preparing the client... 9 3. Creating a graphical user interface... 11 3.1 Understanding GUI files... 11 3.2 GUI design... 11 3.2.1 Adding a window... 11 3.2.2 Adding a brick in a window... 12 3.2.3 Changing brick properties... 14 3.2.4 The Logging brick... 15 3.2.5 Saving the GUI file... 16 3.3 Generating a startup script... 16 Figures Fig. 1 : the Framework package in the Bliss Installer... 3 Fig. 2 : the GUI editor window is launched through the startgui command... 4 Fig. 3 : the HardwareRepositoryServer package in the Bliss Installer... 6 Fig. 4 : output of the "bliss_dserver status" command... 7 Fig. 5 : the "hwrserver" command can also be used to launch the Hardware Repository Server... 7 Fig. 6 : the XML files generated by genspecxml... 8 Fig. 7 : basic Hardware Repository XML file for a Spec motor... 9 Fig. 8 : the Hardware Objects in the Bliss Installer... 10 Fig. 9 : inserting a new Popup window... 11 Fig. 10 : setting "Hello, world!" as a caption for the first window... 12 Fig. 11 : the design grid toolbar... 12 Fig. 12 : the grid cell is higlighted... 13 Fig. 13 : the MotorBrick is added... 13 Fig. 14 : the MotorBrick is online... 14 Fig. 15 : the LogViewBrick is added... 15 Fig. 16 : the "Submit feedback" tab in LogViewBrick in Tabs mode... 15 Fig. 17 : the GUI editor toolbar... 16 Fig. 18 : the GUI Applications Manager main window... 16 Fig. 19 : the script editor window... 17 Fig. 20 : the Applications browser allows to select an existing GUI file... 18 2
This guide will help you through the process of installing the Bliss GUI Framework on a beamline. You will learn how to install the Framework in itself, and how to set up a Hardware Repository. The third part is a step-by-step guide to a first (and very simple!) beamline GUI. 1. Installing the Framework Installing the Bliss GUI Framework is an easy task thanks to the Bliss Installer, the standard Bliss deployement tool. Nevertheless it is a bit more complicated than installing a simple Spec macro, because it involves several pieces of software. What is commonly called "Bliss GUI Framework" is in fact 2 things : a beamline GUI designer tool (editor) a set of Python modules, providing services dedicated to beamline GUI elements (aka "bricks") design, interaction and integration The standard way to create a new beamline GUI is to use the GUI editor to arrange some GUI bricks in windows, to define their properties and to eventually set connections between them. 1.1 Deploying the packages Go on the machine where you want to create graphical user interfaces and start the Bliss Installer. The GUI Framework is located under Applications/Control/Framework : Fig. 1 : the Framework package in the Bliss Installer 3
It contains 4 elements : BlissFramework-Core : this is the core package, containing the GUI editor and the base Python modules Bricks : all the graphical components that can be used within the Framework are organised into separated packages under the "Bricks" node. There are already bricks for various devices like motors, shutters or equipments like slits, minidiffractometer, sample changer... Feel free to install only the bricks you need ; however it does not use much disk space and you can install everything if you are not sure what you are doing. Icons : an optional package containing icons Windows : the bricks are put into windows ; windows themselves are also separated components that you might want to install or not. It is recommended to install all the available windows. The Core package has some dependencies : HardwareRepositoryClient : see next section to learn more about the Hardware Repository PyQt Python Bricks may also have dependencies on some other packages ; that's life : do not be afraid by a long list of packages to be installed. You can proceed with the installation. 1.2 Testing the installation After you installed the components, you can test if it worked. As blissadm -or op(i)dxx it doesn't matter- just type "startgui" in a terminal window : Fig. 2 : the GUI editor window is launched through the startgui command 4
The GUI editor window should appear. Congratulations : the Core part of the Bliss GUI Framework is successfully installed. ê You are probably going to see the following error message : Please discard it for the moment ; just click Cancel to continue. Exit the editor (File...Quit or the click red cross at the upper right corner) ; now it is time to discover the Hardware Repository. 2.Setting up the Hardware Repository 2.1 What is the Hardware Repository? The Hardware Repository is essential to the Bliss GUI Framework because this is what makes the link between the "Hardware" -in general : Spec, Device Servers, etc.- and the GUI bricks. Every graphical application obeys more or less to the MVC pattern (Model-View-Controller). This means that control is separated from the GUI as much as possible. To achieve this goal, the Hardware Repository brings a database where hardware components are described. The database is a set of XML files. There is one Hardware Repository database per beamline. A Hardware Repository Server gives access to the XML files to its clients. The Hardware Repository Client get the files from the server, and creates Python objects (aka Hardware Objects) from the descriptions in XML format. Clients can also commit changes on Hardware Objects, i.e the Hardware Repository Server can modify a XML file according to changes decided in the Python Hardware Objects. The Hardware Repository Server is also a Spec server (a program that implements the client/server protocol of Spec). For example, commands can be executed from a Spec client version in the Hardware Repository Server using "remote_eval". The Hardware Repository introduces a new layer between what already exists at ESRF to control devices (Spec, Device Servers) and the application level ; the aim is not to replace these control systems, on the contrary Hardware Objects are there to provide adaptators so they can be used with a GUI without worrying too much. Q: Why should we need a "new" database? There are already the Spec configuration files, the Taco/Tango database... A: Yes, but... Graphical applications often need informations that are missing in such databases ; for example, GUI apps do not need to know that motor X is controlled by a MaxeVpap, but might want to know that position 10 for motor X corresponds to zoom level 1, in order to display a message to the user. 5
2.2 Installing the Hardware Repository Server First of all you have to choose a machine where the Hardware Repository server is going to run. Usually, the NETHOST machine is the right choice. Log in the NETHOST as blissadm, and execute the Bliss Installer program ; you find the Hardware Repository Server under Control/HWR/HardwareRepositoryServer : Fig. 3 : the HardwareRepositoryServer package in the Bliss Installer Install it ; then, exit the Bliss Installer and go under $BLISSADM/local. You should find an empty HardwareRepository directory. This is the directory where the XML files will be stored. 2.3 Starting the Hardware Repository Server The Hardware Repository Server is supposed to be launched with the bliss_dserver script. It means that the standard bliss_dserver start/stop/restart and status commands should also work with it, and it also ensures that the server will be launched at the same time as the machine. This is not a Taco device, though : there is no ressource file (it can't read them, anyway!). Edit the $BLISSADM/local/daemon/config/device_servers file and insert the following section : [HardwareRepositoryServer] /users/blissadm/local/hardwarerepository 6
Then, try to launch the Hardware Repository server : bliss_dserver start HardwareRepositoryServer Check if it worked : bliss_dserver status You should see the following output : Fig. 4 : output of the "bliss_dserver status" command ê Maybe no device server is supposed to run on the computer you chose ; but please consider that it doesn't matter if bliss_dserver is installed just for the Hardware Repository Server. The Hardware Repository Server is not a Device Server ; it has to be compared to the Taco database server, for example. bliss_dserver is needed to start it, but that's all. The Hardware Repository Server can also be started with the hwrserver script. To see the command line options, just try : hwrserver -help You should see the following output : Fig. 5 : the "hwrserver" command can also be used to launch the Hardware Repository Server 7
2.3 Start filling the Hardware Repository Now that the server is running, it is time to add some XML files in the Hardware Repository. The Hardware Repository Server comes with a handy tool called genspecxml. This is a small script that takes a Spec version name, and that generates some basic XML files for each motor defined in the Spec configuration. The usage is as follows : genspecxml machine specversion hwrdir For example, if there is a Spec version called "demo" running on the host "wow" and that the Hardware Repository directory points to /bliss/users/guijarro/demo/hwr, it is possible to run the following command line in order to generate the XML files for the motors in the "demo" Spec version: genspecxml wow demo /bliss/users/guijarro/demo/hwr Fig. 6 : the XML files generated by genspecxml 8
Each single motor has its own XML file. The Hardware Repository can be used with several Spec versions at the same time ; that's why genspecxml put the motors for a Spec version in a subdirectory in the Hardware Repository. Q: I have no idea what a XML file looks like! I am completely lost... Can I use the Hardware Repository, anyway? A: Yes! In fact, the XML format derives from SGML and is easy to read for a human. It facilitates organising information hierarchically. It looks like HTML, except that the tags are custom. Understanding Hardware Repository XML files is as difficult as understanding Taco ressource files... Don't worry :-) Let's open one of these files : Fig. 7 : basic Hardware Repository XML file for a Spec motor This a basic Hardware Repository file for a Spec motor. The class keyword is an attribute of the device tag. It indicates the kind of Python Hardware Object that will be built from the reading of the XML file by the Hardware Repository Client. Then, there are some properties that are just defined by custom tags : username is a label describing the motor for the user, specname is the spec mnemonic of the motor, and specversion specifies where this motor can be found using a "host:version" string. 2.4 Preparing the client The server is ready now. Go back to the host from where you want to execute Framework-based graphical applications : the remaining task is to configure the Client side of the Hardware Repository. Let's add a BLISS environment variable that points to the Hardware Repository Server (replace "host" 9
with the name of the machine running the Server) : blissrc -a HARDWARE_REPOSITORY_SERVER host:hwr Test the connection with the Hardware Repository Server : just try to start a new GUI with the startgui command ; this time, you should not see any message saying that a timeout occured while connecting to the Hardware Repository Server. The last step is to install the Python Hardware Objects modules. When the Hardware Repository Client gets a XML file from the Hardware Repository Server, it creates the corresponding Python object. Thus, each class type defined in the XML file corresponds to one Hardware Object module ; the Hardware Objects modules for the Hardware Repository are a bit like the Bricks for the Framework. Launch the Bliss Installer, and go under Control/HWR/Objects ; you can see the list of existing Hardware Objects : Fig. 8 : the Hardware Objects in the Bliss Installer Feel free to install any Hardware Object you may need. In our previous example, with the Spec motors, the only needed Hardware Object is SpecMotor. If you are not sure what you should do, just install everything. 10
3. Creating a graphical user interface In this chapter you will learn how to create your first beamline GUI. The Framework and Hardware Repository are supposed to be installed as described in chapter 1 and 2. Before continuing, make sure the SpecMotor Hardware Object and the Motor brick are installed. 3.1 Understanding GUI files The Framework has 2 modes : design mode : when the GUI is being built inside the GUI editor execution mode : when the GUI application is running The GUI editor produces GUI files : a GUI file contains everything needed for the Framework to draw a graphical user interface. It includes window positions, bricks layout, connections, bricks parameters, etc. The "startgui" script can execute any GUI file. When executed (that is, interpreted), a GUI file produces a graphical application and the user can interact with it. It is a good idea to provide a directory where all the GUI files for a beamline could be stored for example $BLISSADM/local/GUI. 3.2 GUI design Let's start a new GUI application. As blissadm, change directory to $BLISSADM/local/GUI (or whatever directory you may have choosen) and execute : startgui test This will open the GUI editor with a new "test" project. "test" will be the name of the GUI file. 3.2.1 Adding a window First step is to add a window ; click on the Insert...Window...PopupWindow menu : Fig. 9 : inserting a new Popup window 11
A popup window is a simple window, with no special feature. It was primarly designed to be a companion window of a MainWindow, showing up only when needed. But it can still be used as a basic stand-alone window. You can easily change the caption of any window, by entering some text in the "Caption :" textbox on the left panel. Let's put "Hello, world!" : Fig. 10 : setting "Hello, world!" as a caption for the first window You can notice that the "Main window" checkbox is checked ; the first window added in a GUI is always the main window. It means that if the user closes this window, the GUI application quits. It is mandatory for a GUI application to have a main window. A "popup" window will be hidden until it is shown ; do not mix up the PopupWindow, which is a kind of window, and the "popup" attribute of a window. 3.2.2 Adding a brick in a window Each window defines design zones, that is zones containing a grid where Bricks can be placed. The design grid toolbar on top of each design zone allows to add rows, columns, etc in the grid. Delete a row Delete a column Edit connections between bricks (do not use it now) Add a row Add a column Put a multi-cell brick (do not use it now) Fig. 11 : the design grid toolbar 12
For a PopupWindow, the entire window is one design zone. Add a row to the grid ; then, click on Insert...Brick...MotorBrick. Move the mouse to the top cell in the grid : Fig. 12 : the grid cell is higlighted Click on the cell with left mouse button ; the MotorBrick is added : Fig. 13 : the MotorBrick is added 13
3.2.3 Changing brick properties You can notice that once the brick is added, the left part of the screen shows the brick properties. The properties are just key-value pairs ; the values are of different types : string integer float checkbox : boolean value combo : a list of string file : a file selector formatstring : a string that can be interpreted to format numbers ; # represents a digit. For example, the ###.## format string will produce the "<space>13.00" string for the number 13. Most of the bricks have a mnemonic property. This is what makes the link between bricks and the Hardware Repository Client. The mnemonic property is just a string field ; what is expected is the full name of a Hardware Object. The full name of a Hardware Object is the path of the Hardware Object XML file in the Hardware Repository database, starting from the root Hardware Repository database directory and without the.xml extension. To continue with the previous example (see 2.3 "Start filling the Hardware Repository"), /demo/att1 is a valid name for a Motor Hardware Object. Feel free to enter a valid full name for a Motor Hardware Object in the mnemonic field, then press enter. The brick will get the corresponding Python Hardware Object from the Hardware Repository Client, and will try to establish the connections. If the Spec version is running, the brick will be online, i.e it will report the state of the Hardware Object. In case of a motor, the position, limits and state : Fig. 14 : the MotorBrick is online 14
3.2.4 The Logging brick Every graphical application should be able to report its status to the user : the Framework provides the LogViewBrick for this purpose. Logging in the Framework is achieved through the standard logging Python module. Each Framework component can import the logging module and then use it to log messages with a level, depending on the message (DEBUG, INFO, WARNING, ERROR). See the logging module documentation for details. The LogViewBrick installs a log handler in order to get all the logged messages, including uncaught exceptions in Python code. Let's add this brick to our GUI project : click Insert...GUI brick...logviewbrick then put it under the MotorBrick. Fig. 15 : the LogViewBrick is added Feel free to play with the brick properties. One of the interesting features of the LogViewBrick is the email feedback system ; to enable it, just select the Tabs appearance and click "Enable Feedback". Email addresses have to be put in the "emailaddress" string field, separated with spaces. Fig. 16 : the "Submit feedback" tab in LogViewBrick in Tabs mode 15
3.2.5 Saving the GUI file Once the GUI application is ready for the users, you can click on the "Save" button on the toolbar in order to save it to the GUI file. Then, you can directly switch in Execution mode in order to run the GUI application immediately by clicking on the "Launch" button. Clicking on "Launch" will automatically save the GUI file before switching to Execution mode but it is a good practice to save it before, anyway. Click on the Save icon to save the current GUI file Click on the Launch button to switch to Execution mode Fig. 17 : the GUI editor toolbar The GUI file will be saved under the name given as first argument to the startgui script. In our example, the file will be called "test". It will be located in the directory where the startgui command has been executed (current path - "/users/blissadm/local/gui" in this example). 3.3 Generating a startup script When a GUI application is finished, it is time to create a startup script for users to be able to start it easily. The Framework provides a tool called GUIAppMan (GUI Applications Manager) dedicated to this task. As blissadm, start the GUI Applications Manager and specify the directory where GUI files are with the "-a" command line option : GUIAppMan -a ~/local/gui A small window should appear : Fig. 18 : the GUI Applications Manager main window 16
By default, scripts go into $BLISSADM/local/bin ; this can be changed with the "-s" command line option. For more information, do not hesitate to start "GUIAppMan -help". The existing startup scripts are shown in the "Available startup scripts" list. Double-clicking on an existing startup script will open the editor window, in order to modify it. For the moment, just click "Create new". You will be prompt for a script name ; just enter "test" and click OK. Then, the script editor window appear : Fig. 19 : the script editor window 17
Click on the "Change" button in order to select an application to launch : Fig. 20 : the Applications browser allows to select an existing GUI file Select the "test" application and click OK. Then, set the right parameters depending on the GUI application you want to launch. For example, you may want to click on "Start GUI for execution only" in order to prevent users from right-clicking on a brick and changes its configuration. You may also want to have a log file instead of having all the messages on the screen ; in this case, click on "Log to file" and browse for a directory where to put the log file. When the script parameters are ready, click on "Save script". In our example, this will create a "test" shell script file in $BLISSADM/local/bin for starting the "test" application. 18