# Introduction

This document describes how to use VNC server on a CCpilot display.

# Overview

Virtual Network Computing, [VNC][2], allows someone to remotely view and control a computer, or in this case a display.
Each of our CCpilot displays can be extended with a VNC server which means you may remotely connect and control the display from a VNC Client.
The VNC server has been developed to be a standalone service, without use of Qt or other services.

The screen mirroring module contains tar archives for each of our units. The tar packages contain the following:

* VNC binary
* Usage documentation
* Systemd service file for auto start

## Glossary

| Word/Abbrevation | Explanation |
|------------------|-------------|
| VNC          | Virtual Network Computing |
| fps                  | Frames Per Second |
| client                  | The device that want to see the content of another device on screen |
| server                  | The device that will send its content over the network to a client |

## CCVNC server

CrossControl has made a VNC server implementation based on the open-source library [LibVNCServer][1]. This server will forward mouse clicks from a VNC client to multi touch events on the display.

The different CCpilot display types use the same software but needs some specific options to be able to handle the difference in screen sizes. The following command line options are available:

* touch-device = touch device to be used (Default: /dev/input/touchscreen0)
* port = port number to connect to (Default: 5900)
* passwd = password to view server content (Default: No passwd used)
* viewonly = no input from client to server possible.
* verbose = turn on VNC server logging
* x-scale = x-scaling for the unit (Default: 125)
* y-scale = y-scaling for the unit (Default: 125)
* invert = invert x/y scaling (only needed for CCpilot VC)
* fps = number of fps (Default: 2). Higher FPS makes interaction more responsive but with increased CPU and network load.
* rotate = rotation of screen when being sent to client. (Default: 0 degrees, possible values 0, 90, 180, 270)  

To connect to the VNC server in the CC display you will need to start a VNC client/viewer on your remote device and connect to the CC display with the IP address. You should see the display screen mirrored on your VNC client and be able to control the display from the VNC client.

## Installation on i.MX8 devices

CCVNC server can be installed on the target in two different ways.

### Supported devices

* CCPilot VS
* CCPilot V510
* CCPilot V700
* CCPilot V705
* CCPilot V710
* CCPilot V1000
* CCPilot V1200
* CCPilot V1090
* CCPilot V1290

### RAUC bundle

For production use the CCVNC server should be installed on the target using a RAUC bundle.  
Reference the `CC Linux - Using RAUC` documentation on the support web site for more information about how to generate a RAUC bundle.

### Installing it manually for development/testing

During development or testing of the CCVNC server it can be installed on the target manually by unlocking `appfs` and manually unpacking the tarball, tar.gz, under `appfs`.

#### Unlock /appfs for development/testing

1. Open an ssh session to the target:
    <code>ssh ccs\<ip-address></code>
2. Change write permissions of /appfs:
    <code>sudo mount -o remount,rw /appfs</code>
3. Check which version partition /appfs is mounted to:
    <code>rauc status</code>
4. Unmount /appfs:
    <code>sudo umount /appfs</code>
5. Format the partition:
    <code>sudo mkfs.ext4 /dev/\<partition></code>
6. Remount /appfs:
    <code>sudo mount /dev/\<partition> /appfs</code>

#### Unpacking tarball

1. Download the tarball, ccvncserver_1.0.0_\<TARGET>.tar.gz, from the support site under:
    `Software & Solution -> Screen sharing -> Downloads -> Device downloads -> <TARGET>`
2. Transfer the tar.gz package to device:
    <code>scp ccvncserver_1.0.0_\<TARGET>.tar.gz ccs@\<ip-address>:/tmp</code>
3. Open an ssh session to the target:
    <code>ssh ccs@\<ip-address></code>
4. Change directory to `/tmp`:
    <code>cd /tmp</code>
5. Run the following code to unpack it:
    <code>sudo tar xzf ccvncserver_1.0.0_\<TARGET>.tar.gz -C /appfs</code>
6. CCVNC server will not automatically start at boot. See [Example usage](#example-usage).

## Example usage

After unpacking the **tar.gz** package on the V700 the VNC server will not start automatically. See below for how to enable auto start of the server. Once the service has been started it will start using a script in /appfs/vncserver/ to start the VNC server. The script will autodetect the correct scaling if you are running the VNC server on a V700 or a V1X00, but you can modify the script yourself to change the FPS and more.

To enable the VNC server use

```sh
sudo systemctl enable ccvncserver
```

## Known limitations:

### CCpilot X900 & X1200

The CCpilot X900 and X1200 does currently not support a VNC connection using CCVNC server. Alternative approach is to use Qt and the built-in "VNC" platform as covered in the QT VNC platform plugin section.

### CCpilot VS

Wayland works good but EGLFS doesn't work as expected. The mouse clicks behaves odd when running Qt-apps.

### CCpilot V510 / V700 / V705 / V710 / V1000 / V1200 / V1090 / V1290

For the iMX8-platform you need to use the vivante version of the Qt EGLFS graphics integration driver (eglfs_viv) that uses the framebuffer to get the VNC server to work correctly.

To enable VNC rendering in the iMX8 displays, a Qt application must be started with the following flags:

* export QT_QPA_EGLFS_INTEGRATION=eglfs_viv
* export QT_QPA_EGLFS_FORCE888=1  

## Qt VNC platform plugin

An alternative approach instead of using the CCVNC server is to use the Qt platform plugin "vnc". A Qt application can be started with the flag "-platform vnc" to start a VNC server session.
This will render graphics to a VNC offscreen buffer instead of the display screen and all graphics will be sent over the network.
The drawback with this approach is that the Qt application must be restarted in VNC mode and the display screen will be black during this time.
But if this is an acceptable behaviour during a service session, the performance is superior in this approach compared to running the CCVNC server.

## VNC Client

Currently the displays do not support using a VNC client, i.e. viewing/interacting with a remote computer from a CCpilot display.

## Security considerations

* Some customers have had problems with the default VNC port (5900). There is a possibility that this port number attracts a huge number of login tries if a display is public accessible on the Internet. That amount of data traffic can slow down the communication and might also add a traffic cost.

* Change the server to use a different VNC port number to avoid easy detection from malicious botnets and similar.

* A password is always recommended before allowing a client to attach to the display.

* Only enable VNC server for a limited time, during a service session, and not enabled by default.

## License

The CCVNC server builds on libvnc which uses a GPL v2 license and this software will also use GPL v2 license.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

A written offer to get the source code will be included in the downloadable package.

[1]: https://libvnc.github.io/ "LibVNCServer github repository"
[2]: https://en.wikipedia.org/wiki/Virtual_Network_Computing "Virtual Network Computing"