This chapter provides an introduction to using emVNC. It explains the basic
concepts behind emVNC.
What is emVNC
emVNC is a VNC server optimized to run on embedded devices.
It can be used with a graphic library (like emWin) or with a simple pixel storage.
emVNC supports multiple transport layers, TCP/IP or USB can be used to provide a VNC connection to a device.
emVNC is written in ANSI C and can be used on virtually any CPU. Here is a list of emVNC features:
Abstract RFB protocol implementation for embedded systems
Configurable for minimal memory- and flash-footprint
Usable with custom or SEGGER’s off-the-shelf display- and network-modules
Supports all standard VNC clients, including SEGGER’s free, cross-platform emVNC Client
Supports VNC over USB (e.g. with SEGGER’s emUSB-Device stack) or any other socket-like transport layer
Optional user authentication
Optional hextile encoding support (less network throughput)
Optional file transfer support
Multiple examples for different integrations and use-cases
VNC is a remote control tool for GUI environments and graphical applications. Using a VNC connection allows the user
to remote control the ’desktop’ of an embedded target device and to interact with it using a PC’s mouse and keyboard.
It is based on the RFB protocol as described in RFC6143 and compatible with standard RFB / VNC client implementations.
This server module allows you to connect via any socket-like transport layer (e.g. TCP/IP or USB Bulk)
to an embedded device and interact with it via a virtual display. You can use this display like any other display.
You can use a stand-alone virtual display without any real hardware, or you can synchronize it with actually existing display hardware of your embedded device.
Development environment (compiler)
The CPU used is of no importance; only an ANSI-compliant C compiler complying with
at least one of the following international standard is required:
ISO/IEC 9899:1999 (C99)
ISO/IEC 14882:1998 (C++)
If your compiler has some limitations, let us know and we will inform you if these will
be a problem when compiling the software. Any compiler for 16/32/64-bit CPUs or
DSPs that we know of can be used.
A C++ compiler is not required, but can be used. The application program can therefore
also be programmed in C++ if desired.
Use of undocumented functions
Functions, variables and data-types which are not explained in this manual are considered internal. They are in no way required to use the software. Your application
should not use and rely on any of the internal elements, as only the documented API
functions are guaranteed to remain unchanged in future versions of the software.
If you feel that it is necessary to use undocumented (internal) functions, please get
in touch with SEGGER support in order to find a solution.
This chapter explains how to configure emVNC.
Using The VNC Server Module
To use this module go through this step-by-step list:
Include the module in your applications directory structure.
Let your build-system compile all provided C files when compiling your application.
Copy and edit the provided VNC_ConfExample.h to VNC_Conf.h to suit your configuration needs.
Create an integration layer (see section below)
Make sure that files in your integration layer can access the VNC.h, VNC_ConfDefaults.h and your VNC_Conf.h header files.
The VNC Server Module is a VNC / RFB protocol implementation and is kept as abstract and simple as possible, so that it can be used with any kind of display and over any kind of connection. To use it, you need to fill the following abstractions:
Session Management (run the server event loop)
Transport Layer (provide communication with the connected VNC client)
Display Layer (provide access to the display framebuffer)
(optional) Event Layer (publishes mouse- and keyboard-events from any connected client)
(optional) Authentication Layer (generate random data for VNC client challenge-response authentication)
You can find several examples in the examples/ directory, and in the separately provided example pack for the emPower embedded board. These include full integrations for plain framebuffers and for SEGGER’s emWin GUI framework, SEGGER’s emNet TCP/IP stack, SEGGER’s emUSB-Device USB device stack and also for Linux. (The latter mostly for testing of the protocol implementation.)
Detailed information on each of these layers follows. Please refer to VNC.h and VNC_ConfExample.h for exact interface definition of the layers that you need to provide.
As mentioned, you need to provide a VNC_Conf.h that should be based on VNC_ConfExample.h. Here you can en/disable optional features, but you also have to provide some type definitions and glue logic for the module.
You need to provide a session management that is responsible for accepting/setting up connections when a new client wants to connect, and to run the servers protocol handler function repeatedly for each connection until that client disconnects.
Best practice is to give each client a separate task or thread, such that a blocking network layer doesn’t block other tasks. Another option is to only accept a single client connection at a time and to run the main session management and this client connection in a single task.
Overall, for a single client connection you need to setup a VNC_CONTEXT with VNC_ServerInit(). Then repeatedly run VNC_HandleClientProtocol() until a negative value is returned, indicating that the client disconnected or a protocol error forced a disconnect. After that, or at any other time that VNC_HandleClientProtocol() is not running, the VNC_CONTEXT may be destroyed. Remember to free any other resource related to the client connection, like a socket or a USB bulk handle.
The transport layer to a connected client is abstracted in VNC_CLIENT_CALLBACKS and requires that you provide a callback VNC_SEND to send data to the connected client, and VNC_RECV to receive data from the client.
The optional event layer allows the server to publish events like key-presses or mouse motion, that a client sends to us. To use it, provide a VNC_EVENT_CALLBACKS with any or all of VNC_MOUSE, VNC_KEYBOARD and VNC_COPY. These will be called when any events are received from the client. To ignore these events, simply set these callbacks to NULL.
If password authentication is enabled and a password is set, you need to provide a VNC_AUTH_CALLBACKS structure with VNC_GET_CHALLENGE, which must return 16 random bytes. Otherwise the challenge/response authentication would be predictable.
Note that the authentication mechanism defined in the RFB protocol is by no means secure and should not be relied upon. But using a different, better authentication method would make using standard VNC clients impossible, and increase the server’s size and computational needs even further.
When the target is running the emVNC server and you are using emNet or a different TCP/IP stack for communication any VNC client can be used to connect to your target.
If you are using emUSB for the data transfer SEGGER’s emVNC PC client should be used.
In this chapter, you will find a description of all API functions as well as all required
data and function types.
This section describes the functions that can be used by the target application.
This function must be called between VNC_ServerInit() and VNC_ServerRun().
The size passed to this function may be smaller than the real display.
If the access methods (pfGetPixel) supports out-of-bounds access,
the size may also be larger than the actual display.
Per default the server uses the layer size.
Pointer to a buffer containing the authentication challenge.
This must save a challenge of VNC_AUTH_CHALLENGE_SIZE bytes
in pChallenge. Usually that should be newly generated random data.
Before contacting support please make sure that you are using the latest version of the emVNC package.
Also please check the chapter Configuring debugging output and run your application with enabled debug support.
If you are a registered emVNC user and you need to contact the emVNC support please
Your emVNC registration number.
A detailed description of the problem
The configuration files
Any error messages.
Please also take a few moments to help us to improve our service by providing a short feedback when your support case has been solved.