[logo]quasar

The quick opcua server generation framework.

Versions

Changelog

Credits

This framework was brought to you by:

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:
Recommended:

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
  2. 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
  3. From the ATLAS Central DCS

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 19.04

Execute:
sudo apt install cmake g++ libboost-all-dev libxml2-utils astyle xsdcxx libxerces-c-dev libssl-dev kdiff3 default-jre libxml2-utils python-enum34 python-lxml

Quick setup hints for Ubuntu 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

    To set up the generic server in a windows environment, follow the instrunctions found here

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

The relevant playlist:
https://www.youtube.com/playlist?list=PLz6bxFrT1-KBZxoSxr4ZvlTyxNeYE3L7b

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.

Quasar build system

Quasar build system is documented here.

Calculated Variables

Developer documentation of Calculated Variables

Logging

Logging in quasar servers is provided via the LogIt module.

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.
    3. Commit changes in both files
    4. To generate RPM, run either:
      ./buildRpm.sh --revision <revision_number>
      or
      ./buildRpm.sh --tag <tag_name>
    5. 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).
  5. 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>
  6. 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:
    Here is a picture taken from our CHEP2015 poster with sequence diagrams for both types of variables:


  7. 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. 
  8. 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:
    Please refer to the Changelog which lists (in backwards incompatibility column) at which moments you may need any of the above.
  9. 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
  10. How does a developer define specific command line options for my quasar server implementation?
    This is documented here: User Defined Command Line Parameters
  11. 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
  12. 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
  13. How do I link libraries, add include directories, use build configurations etc... ? See build system doc.



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.