cumbia-libs
cumbia library documentation
Platform independent apps from anywhere
cumbia targets application portability and aims at extensive integration across several sources of data (services as well as native control system engines). After introducing the websocket module in 1.0, cumbia 1.2 introduces initial support to http and Server Sent Events technologies, looking forward to such services becoming available.
Applications written in any language will thus be enabled to connect to native control system engines from anywhere. Find out more here.
Qt6 ready version 2.0
Library version 2.0 has introduced support for Qt 6, added initial support for cmake, and has become part of a cumbia-world super project gathering together the main library alongside satellite libraries and plugins. Check out cumbia-world from gitlab.
Read more about cumbia version 2 here.
Write your own activities
Concentrate on the task you want to run in the background and use cumbia base library to write custom activities that will be executed on a separate thread. You will receive the progress updates and the results when they are ready. Nevermind thread synchronization issues.
Connect with the Tango and Epics (and more…) control system software
Write graphical user interface components and applications communicating with the Tango and Epics control systems. More control system engines can be added in the future and plugged into existing cumbia installations and applications.
Let your application written in any technology run from Everywhere through http[s] or websocket
Yes, the same app that connects to Tango or EPICS, can be restarted and rely on either http or websocket transparently. No code change, no source name changes, no rebuilding.
Combine results into formulas and functions
Mixing the Qt javascript integration and the cumbia formula plugin, read results from Tango and Epics can be introduced into functions. The results can be displayed into any cumbia-qtcontrols widget. Refer to the formula plugin section for details.
Realize Qt applications without writing any code
la-cumparsita is an application that interprets Qt designer UI files on the fly and performs as a full C++ Qt application in style and behavior. For the most demanding users, la-cumparsita allows javascript integration to display function results as described earlier in this page.
Test application interface, performance and usability without connecting to real control system engines
The cumbia-random module offers an interface to periodically generate random data of a given size and within a given range. Additionally, JavaScript files can be used as data sources. Read more about cumbia-random here.
Test the latest version locally
Testing a new library version under your home directory is as easy as executing the scripts/cubuild.sh installation procedure specifying the custom path and executing a one line command thereafter to set up the local environment in the current shell.
Use the included apps (with bash Tango source auto completion!) to access immediately multiple control systems
A Qt graphical client and a command line application are ready to communicate with the supported control systems and the cumbia-random module. An external plugin makes Tango source bash auto completion possible!
Getting started
- Download and install cumbia, following to the instructions in the cumbia-libs README.md file.
- Write a platform independent with cumbia multi engine support.
- Write your first Qt application with cumbia and Tango
- Find answers to common questions in the FAQ section (Tango)
Examples
Several examples come along with the library. Just look for the examples directories under each subproject.
- Under the cumbia-tango module, you’ll find examples to write a multi threaded Tango server using cumbia activities and read properties from the database.
- cumbia-qtcontrols includes examples of usage of some widgets as well as writing a simple activity to understand the basic concepts and thread management.
- qumbia-tango-controls provides examples of a multireader, a widget refreshed manually and an application that helps understand the concept of cumbia-qtcontrols context (CuContext).
- qumbia-epics-controls is shipped with examples showing how to use widgets with EPICS
- qumbia-plugins will teach you how to integrate formulas into applications
More examples you will find within cumbia sources!
Keywords and technologies
Everywhere
cumbia is written in C++ and uses the Qt libraries to develop graphical user interfaces. This means cumbia applications work on desktop computers as well as on Android devices. From version 1.2, cumbia is not only available wherever C++ and Qt are supported, but thanks to the websocket and http modules, any application, web included, can rely on cumbia to access control system data!
Not only, the same application can use either a native or a http/websocket engine transparently, that is, without changing one line of code or rebuilding, not even changing the source names. How difficult is that? As difficult as specifying a URL to a http or websocket service on the command line, or configure a http or websocket default engine in your environment.
Remote working apps
You can run your application relying on the native control system engine from your office or run it from home via http. Read the Platform independent apps from anywhere chapter.
Android and Linux platforms have been successfully tested and porting an application from one platform to another is just a matter of a few clicks with the Qt creator IDE.
Plugins
cumbia libraries provide a set of fundamental capabilities that can be summarized in the concepts above. A set of plugins extends those functions and new ones can be added. The core framework remains small and easy to maintain, while the capabilities extend distributed. The set of widgets offered by the base cumbia-qtcontrols module can be extended by plugins as well.
Screenshots
Here you can see some screenshots of applications written with cumbia.
Installation
To download and install cumbia, refer to the instructions in the cumbia-libs README.md file.
Instructions to prepare an ubuntu-desktop for cumbia, can be found in the README.UBUNTU.md file under cumbia-libs.
The library sources include copies of the README.md and README.UBUNTU.md files in the top level directory.
Cumbia for WebAssembly
To build Qt and cumbia for WebAssembly, please refer to this document.
Tutorials
Modules
| cumbia modules | |
|---|---|
| cumbia base. | qumbia-epics-controls. |
| cumbia-tango. | cumbia-random. |
| cumbia-qtcontrols. | cumbia-websocket. |
| cumbia-tango-controls. | qumbia-plugins module. |
| qumbia-epics. | cumbia-http. |
Plugins shipped with the base installation
| cumbia plugins | Description |
|---|---|
| formula plugin. | Compose sources into formulas |
| dbus plugin. | DBus plugin for inter app communication |
| multi reader plugin. | Read multiple sources |
| context menu actions plugin. | Contextual menu actions plugin for widgets |
| Qt designer plugin | Qt designer cumbia widget integration |
Additional plugins
Additional plugins can be downloaded from the ELETTRA-Sincrotrone Trieste github page.
| Plugin interfaces to extend cumbia | Description |
|---|---|
| cumbia-qtcontrols introspection plugin. | Look inside cumbia objects |
| Tango specific introspection plugin. | Look inside cumbia-tango objects |
| Plugin and app to search Tango database names. | Find Tango source names (and provide auto completion for apps!) |
| Add a copy source action to the context menu. | Adds a copy source action to the widgets contextual menu |
| Text view extra widget. | Provides a text view widget |
Apps
cumbia provides some applications as part of the software distribution. If you followed the scripts/cubuild.sh install method, they should be ready to use.
Otherwise, they have to be installed from the qumbia-apps sub-directory of the cumbia-libs distribution. To do this, cd into that folder and execute:
qmake
make
sudo make install
Along with the application executables and documentation, two bash scripts will be installed:
- /usr/local/cumbia-libs/bin/cumbia (or whatever/install/prefix/bin/cumbia)
- source /usr/local/cumbia-libs/share/bash-completion.d/cumbia (output of
pkg-config --variable=completionsdir bash-completioncan also be used, edit qumbia-apps/cumbia/cumbia.pro and look for BASH_COMPLETION_DIR)
They define shortcuts for the common operations provided by the cumbia applications as follows:
| Applications | description | app |
|---|---|---|
| cumbia read | read a quantity from the supported engines | cumbia reader |
| cumbia monitor | monitor a quantity over time from the supported engines | cumbia reader |
| cumbia apps module-default | show [set] the default module loaded by multi engine apps | Writing a platform independent app |
| cumbia new project | create a new cumbia project | qumbia-apps/qumbiaprojectwizard |
| cumbia import | migrate a QTango project into cumbia | qumbia-apps/qumbiaprojectwizard |
| cumbia new control | write a cumbia control reader or writer | qumbia-apps/qumbianewcontrolwizard |
| cumbia ui make | run cuuimake to generate qt+cumbia ui_*.h files | qumbia-apps/cuuimake |
| cumbia client | run a generic cumbia client | qumbia-apps/qumbia-client |
| cumbia upgrade | upgrade to a newer version of cumbia | - |
| la-cumparsita | on the fly applications from a Qt designer UI file | qumbia-apps/la-cumparsita |
bash auto completion will help you find out these shortcuts: try
cumbia [+TAB]
or
cumbia new [+TAB]
After the installation, it may be necessary to type
source /usr/local/cumbia-libs/share/bash-completion.d/cumbia
from the current shell or log out and log in again.
Want to TangoTest ?
If the TangoTest device is running, you can immediately try the generic cumbia client:
cumbia client test/device/1/double_scalar test/device/1/long_scalar
Performance
cumbia can be seen both as an extension and an evolution of the well known and long standing qtango framework. Additionally, it offers a relevant improvement in performance.
Are you ready?
Start reading the cumbia base library documentation or writing a new cumbia application.