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 and code-generation
- 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 and PetaLinux
- CalculatedVariables
- Stefan Schlenker (stefan.schlenker@cern.ch)
- Use cases, ideas, optional modules mechanism
- Cristian-Valeriu Soare
- 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
- Get Eclipse (www.eclipse.org) with :
- CDT (C/C++ Development tools) - "Eclipse IDE for C/C++
Developers"
- XML editors - "Eclipse XML Editors and Tools"
- Subversive SVN and SVN providers
- 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
- 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
- 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
- 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
- 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
- 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 : ...
- 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.
- Quasar specific documentation, targeted at quasar developers
and quasar framework maintainers can be found here
- Generic LogIt documentation can be found here
FAQ
- 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
- 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
- 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.
- 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.
- You will need to set repository paths in the build scripts.
- Then edit template.spec:
- 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.
- You may edit Summary: field with short (one-line)
description of the server.
- You may edit %description section with long description of
the server.
- 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...)
- If applicable, complete %pre, %post, %preun and %postun
sections.
- Commit changes in both files
- To generate RPM, run either:
./buildRpm.sh --revision <revision_number>
or
./buildRpm.sh --tag <tag_name>
- 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).
- How to upgrade to
newer release of
Generic Server Framework?
- Download quasar in the version of your choice
- Unpack it
- 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>
- 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:

- 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.
- 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.
- 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
- How does a developer define specific command line options for
my quasar server implementation?
This is documented here: User Defined
Command Line Parameters
- 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
- 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
- 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.