Quasar

The quick opcua server generation framework.

Versions

Changelog

Credits

This framework was brought to you by:

  • Damian Abalo Miron (damian.abalo@cern.ch)

    • Windows / MSVC10 compatibility

    • Python-based scripts and tools

  • Benjamin Farnham (benjamin.farnham@cern.ch):

    • LogIt logging engine

    • Meta module

    • Use cases & ideas

  • Viatcheslav “Slava” Filimonov (viatcheslav.filimonov@cern.ch):

    • XML Configuration

    • Calculation engine

    • Node manager

  • Piotr Nikiel (piotr.nikiel@cern.ch, piotr@nikiel.info):

    • Framework’s concept and architecture

    • Address Space, Device and Configuration generation (XSLTs, design files, scripts)

    • CMake-based build system

    • RPM generation for Linux

    • Documentation and screencasts

    • Build configurations for Raspberry Pi, Zynq and MSVC10 on Wine

    • Yocto compatibility

  • Stefan Schlenker (stefan.schlenker@cern.ch)

    • Use cases, ideas, optional modules mechanism

  • Cristian-Valeriu Soare

    • Embedded python module

  • Giordon Holtsberg Stark

    • Quasar with Yocto on a “big” Zync: ideas, consulting, development, testing

Dependencies

Note: there are direct instructions for the following operating systems: SLC6 (~ Red Hat Enterprise Linux 6), CC7 (~ CentOS 7, Red Hat Enterprise Linux 7), Ubuntu, MS Windows.
Mandatory:

  • Suitable C++ compiler (gcc is assumed by default)

  • The Unified Automation OPC UA Toolkit in versions 1.3.x, 1.4.x or 1.5.x  or  another OPC-UA toolkit with compatible API (e.g. open62541 + open62541-compat). More info on alternative backends.

  • Boost development libraries. (In principle, boost-regex, boost-devel and boost-program-options should be sufficient)

  • XSLT processor capable of XSLT2.0 processing. We use The Saxon XSLT and XQuery Processor from Saxonica Limited which is re-distributed with the Quasar package (version 9.5 HE). Conditions of redistribution are explained at this link.

  • Java run time environment, to run the Saxon XSLT Processor.

  • Cmake version 2.8 or later. Available in SLC6 as cmake28 package.

Recommended:

  • Schema-aware XML editor. We use Eclipse, as can be seen in the screencasts.

  • Good C++ IDE / editor. We use Eclipse, as can be seen in the screencasts.

  • Good merge tool. We use kdiff3 (available as kdiff3 RPM in SLC6 Linux).

  • ArtisticStyle ( http://astyle.sourceforge.net/ ) for automatic formatting of generated code. If you don’t use it, the generated code will look like a shipwreck (but will still work). ArtisticStyle RPM for SLC6 can be obtained from Piotr Nikiel, or you can compile it yourself from sources.

  • graphviz, if you want to visualize your object design in UML-alike class diagram. Available in SLC6 as graphviz RPM package.

  • UnifiedAutomation UaExpert or any other OPC UA Client for exploring OPC UA address space.

  • Valgrind, for checking memory-related problems. (valgrind RPM in SLC6)

  • PDF viewer for opening UML-like diagrams created from design file.

  • Doxygen for generating documentation.

  • RPM Build tools for RPM generation


Quick setup hints for SLC6 users

  1. Get Eclipse (www.eclipse.org) with :

    1. CDT (C/C++ Development tools) - “Eclipse IDE for C/C++ Developers”

    2. XML editors - “Eclipse XML Editors and Tools”

    3. Subversive SVN and SVN providers

  3. Issue this to install software from official SLC6 RPMs: sudo yum install gcc-c++ gdb boost-devel boost-regex boost-program-options boost-signals jre cmake28 kdiff3 graphviz valgrind doxygen rpm-build subversion xsd openssl-dev libxml2-devel xerces-c-devel

  4. From the ATLAS Central DCS

    • obtain OPC UA Toolkit 1.3.3 RPM and astyle and install them: sudo yum install OpcUaToolkit-1.3.3-0.x86_64.rpm astyle-2.0.4-0.rpm

    • obtain UaExpert and install it

Quick setup hints for CC7/CentOs7 users

  1. Get Eclipse (www.eclipse.org), preferably the C/C++ Developers version (e.g. https://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/oxygenr) Once installed, install Eclipse add-ons for XML editors

  2. Issue this to install software from the official CC7 RPM repos: sudo yum install gcc-c++ gdb boost-devel boost-regex boost-program-options boost-signals jre cmake kdiff3 graphviz valgrind doxygen rpm-build subversion xsd openssl-devel libxml2-devel xerces-c-devel python2-pip libgit2 libgit2-devel

  3. Deploy Python’s pygit2 (recommended) WARNING: the version of pygit2 should match the version of libgit2-devel! At the time of writing it was 0.26.4 sudo pip install pygit2==0.26.4

  4. If you have access to the UA SDK, install it (the evaluation version works fine). Quasar should work with UA SDK versions 1.3.2 up to 1.5.5. If you don’t have the UA SDK, you can run Quasar with open62541, through open62541-compat module which is off-the-shelf available in Quasar. Documentation : …

  5. Download UaExpert for an universal test&dev tool for OPC-UA.

Quick setup hints for Ubuntu (here: 14.04)

Execute:
sudo apt-get install cmake g++ libboost-all-dev libxml2-utils astyle xsdcxx libxerces-c-dev libssl-dev kdiff3 default-jre libxml2-utils
Note you will need the UA SDK (i.e. evaluation version) or alternative backend (consider open62541 with quasar integration).

Setup for Windows users

Tutorial

quasar has a pretty detailed tutorial for both newcomers as well as experienced users.
The tutorial is available at our YouTube channel:
https://www.youtube.com/channel/UCQdLb4N-CEWrpYROcC-UF6w

Optional modules

quasar is containing a list of built-in (mandatory) modules. A number of optional modules exist which can be used for implementing various flavours of OPC UA servers. Amongst those are alternative OPC UA backends, APIs for device specific protocols or software utilites.
The list of optional modules is maintained by the quasar team on github.
To enable and use a module:
./quasar.py enable_module MyQuasarModule [tag] [git server]
Pulls quasar-modules MyQuasarModule from git, checks version of chosen module to be compatible. A module version can be specified, if later a new module tag/release is needed, call the command again (the existing module version will be removed). You can specify a git server URL e.g. to use mirrors in restricted networks (e.g. ssh://git@gitlab.cern.ch:7999).
To download the module and include it in the build configuration run:
./quasar.py prepare_build
cmake will check for new enabled modules and pull from git if they are not yet existing. Thereafter you can build your project normally using ./quasar.py build which will consider includes and create and link an object library called like the module itself.
Further commands related to optional modules are:
./quasar.py remove_module MyQuasarModule Removes downloaded module code, if modifications are found - abort.
./quasar.py disable_module MyQuasarModule Removes module and disables its use (need to enable first again if needed).
./quasar.py list_modules [git server] List all maintained modules from git and their required quasar versions.
./quasar.py list_enabled_modules List all modules enabled in the project and their versions.

Logging

Logging in quasar servers is provided via the LogIt module.

  • Quasar specific documentation, targeted at quasar developers and quasar framework maintainers can be found here

  • Generic LogIt documentation can be found here

FAQ

  1. How to build an executable with debug symbols? Just append Debug to your “quasar.py build” invocation, i.e.: ./quasar.py build Debug or ./quasar.py build <build_config_name> Debug

  2. Build fails Try to read carefully the output. If you can’t figure the issue on your own, try contacting quasar-developers@cern.ch, at the last resort contact piotr.nikiel@cern.ch

  3. The server starts up, but crashes. There are plenty of possibilities here. The best way is to build a server with debug symbols (explained above in the tutorial) and enable core dumping in your system. Then run it again and let it crash. You will obtain a coredump file, which you can load into GDB this way: gdb <path_to_executable> <core_dump_file> Then type ‘bt’ and gdb will show you crash back trace. If it seems that the crash is within quasar itself, please don’t hesitate and file a report to us.

  4. How to create a RPM package with my server? RPM builder is provided with the quasar. RPM builder builds “directly” from your version control system and not from your local files (this is intentional and will not be changed). At the moment SVN and Git are supported. Please have a look at scripts in RPM/build_from_svn or RPM/build_from_git.

    1. You will need to set repository paths in the build scripts.

    2. Then edit template.spec:

      1. In the very first line, set name of the RPM. It shall match the value of “projectShortName” which you have put into design element of your Design.xml file.

      2. You may edit Summary: field with short (one-line) description of the server.

      3. You may edit %description section with long description of the server.

      4. Review the list of files listed in %install section. These files will be packed inside the package. Add additional files, if applicable (e.g. documentation, data files, additional libraries, etc…)

      5. If applicable, complete %pre, %post, %preun and %postun sections.

    4. Commit changes in both files

    5. To generate RPM, run either: ./buildRpm.sh –revision <revision_number> or ./buildRpm.sh –tag <tag_name>

    7. IMPORTANT: For delivering production packages, you should first tag given release on SVN, and then generate RPM from the tag (using the second version of command listed above).

  6. How to upgrade to newer release of Generic Server Framework?

      1. Download quasar in the version of your choice

      2. Unpack it

      3. Execute quasar.py upgrade_project which is in its root directory, passing path to your project to be upgraded as the first parameter: ./quasar.py upgrade_project <path>

  8. What is the difference between cache variable and source variable? The difference lies in where factual value of the variable is stored, which impacts what happens after Read OPC UA Transaction:

    • For cache variables, there are stored in the server’s RAM (thus “cache”), and the value served back to the client is the value from RAM. Cache variables are perfect whenever some device logic code updates the address space or reads from the address space.

    • For source variables, there are stored “at the source”, which for example might be at a remote computer. Therefore every Read transaction will trigger Device Logic method supposed to fetch that data from the source.  Contrary to cache variables one may expect that such Read  transaction may be blocking and time consuming, and therefore may be required to be executed in a separate thread of execution.

    Here is a picture taken from our CHEP2015 poster with sequence diagrams for both types of variables: image1

  9. Can I use evaluation version of the UA Toolkit to create an OPC UA server using this framework? You can. Beware that at the time of writing the evaluation version is only available in 32 bits. Therefore we recommend to create a build configuration specifically for compiling in 32 bits with evaluation version of the toolkit.

  10. How to use upgrade_design tool? Rarely - but sometimes - XML stylesheet of Design file (Design.xsd) changes in backwards-incompatible way. For all such changes conversion tools are provided to mitigate the pain. upgrade_design is one of them. upgrade_design currently accepts this commands:

    • ./quasar.py upgrade_design convert_to_hasDeviceLogic=yes

    • ./quasar.py upgrade_design add_nullPolicy=nullAllowed or ./quasar.py upgrade_design add_nullPolicy=nullForbidden

    • ./quasar.py upgrade_design remove_makeSetGet=yes

    Please refer to the Changelog which lists (in backwards incompatibility column) at which moments you may need any of the above.

  11. Can I automatically prepare the required dependencies? We have a shell script which could be useful if you e.g. need to crosscompile and do not yet have the libs required by Quasar. The script is places in the Documentation/Addons/prepare_dependencies.sh

  12. How does a developer define specific command line options for my quasar server implementation? This is documented here: User Defined Command Line Parameters

  13. How does a developer define a dynamic (at start up) configuration? For example, where the server ‘discovers’ connected hardware on start up. This is documented here: User Defined Runtime Configuration

  14. How does a developer persist a ‘discovered’ configuration as described above? For example, where the server ‘discovers’ connected hardware initially and saves it for use thereafter as a static configuration. This is also documented here: User Defined Runtime Configuration


Written by Piotr Nikiel <piotr.nikiel@cern.ch>
Report inconsistencies and bugs to the email above.
(C) CERN 2015. All rights not expressly granted are reserved.