This article will guide the user to enable remote screen grabbing for Qt applications by using the remote screen SDK provided by Teamviewer
General
TeamViewer currently provides 3 different options to access the content of the screen attached to a device on which the TeamViewer IoT agent installed. In this article the option to directly access Qt applications is described. This is realized through an SDK which TeamViewer provides. This SDK is directly linked into the application and so enables the connection to the Teamviewer IoT agent on the edge device and so to the TeamViewer network.
Building Block Description Qt application The Qt application that in the end provides a user frontend which can be accessed from the outside Customer Qt application The frontend part of the Qt application. This is not provided by TeamViewer, but from the entity that designs the application and device. RemoteScreen SDK Software Development Kit containing an interface and plugin to enable remote control for a customer application (short: SDK/plugin). TeamViewer IoT agent TeamViewer software enable the edge device to create TeamViewer connections for remote control TeamViewer Client The TeamViewer program installed on the user pc. To initiate remote control connections to the device.
Requirements
There are some preconditions, that you must meet, so that you can use this feature. Please make sure that you fulfill them all:
- You need a valid license for TeamViewer 14.
- The TeamViewer IoT agent must be installed on the device
- There must be a Qt application running on the device and this application must be accessible so the remote screen SDK can be linked to it.
- This device should either be configured to display the user interface via a Linux frame buffer device or is capable enough to send its image data to the SDK
Software dependencies
For building the whole package the following libraries and tool need to be available:
- CMake (3.5 or newer)
- Compiler tool chain with support for C++14 (like GCC or Clang)
- Google Protocol Buffers library (3.0 and newer)
- Google gRPC library (1.20 or newer)
- zlib (needed by gRPC
- Qt 5 (5.3 or newer)
On debian systems (when writing the documentation debian 10 was the latest) the following development packages can be used for building
- cmake
- build-essential or g++
- libgrpc++-dev
- protobuf-compiler-grpc
- libprotobuf-dev
- protobuf-compiler
- qtbase5-dev
- qtdeclarative5-dev
For example :
sudo apt-get -y install cmake
Hardware requirements
- For supported platforms regarding the TeamViewer IoT Agent visit https://www.teamviewer.com/link/?url=150157
- At least 30 MB free disk space
- Systemd software suite
- Glibc-utils package (version 2.17 higher)
- Linux 2.6.27 kernel
Where to download
The TeamViewer Remote Screen SDK can be downloaded by clicking on the following link:
https://download.teamviewer-iot.com/remoteScreenSDK/TVRemoteScreenSDK_1.1.40.zip
https://download.teamviewer-iot.com/remoteScreenSDK/TVRemoteScreenSDK_2.0.9.zip
How to build a Qt application with the Remote Screen SDK
To build the remote screen SDK please ensure that all required libraries and dependencies are installed and available.
Steps to build:
# create and navigate to a build directory
mkdir build
cd build
# run cmake
cmake <path to extracted SDK>
# run make
make
After building the package there should be two binaries:
- libTVQtRC.so - integration plugin, used by a Qt application for providing
- Remote Screen capabilities
- -qt_simulate - an example application showing the basic usage of the plugin
Installation for Development
The SDK can also be installed to be used in a development environment:
# default installation (as root, if needed)
make install
The default installation prefix for CMake is /usr/local. So after installation there are two projects installed:
- TVRemoteScreenSDK
- The Qt plugin (<prefix>/lib/lbTVQtRC.so) along with the public headers (<prefix>/include/*.h) to use it.
- TVRemoteScreenSDKCommunication
- The public C++ API used by the plugin. This API in independent of Qt and can be used together with any other framework.
To install the SDK into a custom prefix one can override CMAKE_INSTALL_PREFIX when configuring the SDK before building:
# configure to install into custom prefix
cmake -DCMAKE_INSTALL_PREFIX=<custom-install-path> <path-to-sources-root>
Configuration settings
Configuration of the TeamViewer IoT agent
The TeamViewer IoT agent needs then to be configured to remote control an "external application". This configuration involves also specifying a so-called "image grab strategy": With that the agent tells the application in what way it expects image updates. To do this:
From remote terminal run:
sudo teamviewer-iot-agent configure set EnableRemoteScreen 1
sudo teamviewer-iot-agent configure set RemoteScreenChannels \"EAP\"
Note:
That the value in escaped double quotes can vary from user case. The values could be:
Use case
Setting
External App (SDK) with built-in grabbing
[strng] RemoteScreenChannels = \"EAP\"
External App (SDK) with notifications about framebuffer changes
→ FB device /dev/fb42
[strng] RemoteScreenChannels = \"EAP:FBPush:/dev/fb42\"
External App (SDK) with frambuffer grabbing
→ first FB device (/dev/fb0)
[strng] RemoteScreenChannels = \"EAP:FBPull\"
The agent currently supports the following strategies:
- Application provided (default when setting the remote screen channel to "EAP")
- The application (or the Qt plugin) is grabbing internally and send resulting images to the TeamViewer agent.
- Linux frame buffer device continuous (called "FrameBuffer-Pull" or the channel setting "FBPull")
- This repeatedly copies the contents of a Linux frame buffer device regardless of any actual image changes.
- Linux frame buffer device with notifications (called "FrameBuffer-Push" or the channel setting "FBPush")
- This copies the contents of a Linux frame buffer device when the external application notifies the agent to do so.
After starting the agent its API for remote screen is now available and can be used by the Qt plugin.
Further configuration
After installing the IoT Agent it creates a system group called 'tv_api'. Every application that wants to communicate with the agent needs to run under a user that is part of the before mentioned system group:
# add current user to group tv_api
usermod -a -G tv_api $USER
For further information on the TeamViewer IoT agent check here
https://community.teamviewer.com/t5/TeamViewer-IoT-Knowledge-Base/TeamViewer-IoT-Remote-Screen/ta-p/58731
Example application
In the package for the SDK is an example application included. This example show the basic operations of the SDK and how to integrate the plugin into a Qt Quick based application. It requires Qt 5.3 with the modules Qt Quick 2.3 and Qt Quick Window 2.0 to run.
On debian based distributions the following packages are required to run:
- qml-module-qtquick2
- qml-module-qtquick-window2
To start the example application:
- Open the Build directory using graphical interface
- Locate the qt_simulate
- execute the qt_simulate
With the example application one can also test and see the basic operations:
- connectivity to the agent: the circle on the top left corner is green when the IoT agent is available (this does NOT indicate network connectivity)
- set the control mode: "Set Full Control" (image updates and input), "Set View Only" (image updates, no input), "Disable Remote Control" (no image updates, no input)
- terminate all incoming TeamViewer sessions: Terminate TV Session" is only enabled if there is at lease one active remote control session. By clicking, it terminates all incoming sessions and the button is disabled afterwards.
- mouse and keyboard input testing
- rudimentary animation testing
Known Issues
Please contact TeamViewer IoT Support ⟨iot-support@teamviewer-iot.com⟩ if you encounter problems when using the remote screen SDK.
Inverted Colors
On some ARM based devices, the colors may seem inverted or appear wrong on the client’s side.
Screen refresh
When the RemoteScreenChannels setting is configured with EAP:FBPush, it may happen that the client picture is sometimes not refreshed appropriately during a TeamViewer session. Resizing the window will force an update and will display the actual content of the application in the client window.
For more information about the different channel configurations and their use, please visit https://www.teamviewer.com/link/?url=710439
License information
The TeamViewer Remote Screen SDK is released under MIT License allowing an easy integration of our source code.
To create Qt applications respective Qt licenses are needed
Further reading/Realated articles
