Introduction
This chapter provides an introduction to using emVNC. It explains the basicconcepts 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 features
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
Basic concepts
VNC is a remote control tool for GUI environments and graphical applications. Using a VNC connection allows the userto 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 withat 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 willbe a problem when compiling the software. Any compiler for 16/32/64-bit CPUs orDSPs that we know of can be used.A C++ compiler is not required, but can be used. The application program can thereforealso 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 applicationshould not use and rely on any of the internal elements, as only the documented APIfunctions are guaranteed to remain unchanged in future versions of the software.If you feel that it is necessary to use undocumented (internal) functions, please getin touch with SEGGER support in order to find a solution.
Configuring emVNC
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.
Integration Layer
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:
- Configuration
- 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.
Configuration
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.
Session Management
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.
Transport Layer
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.
Display Layer
The display layer is abstracted in VNC_DISPLAY_CALLBACKS. You need to provide callbacks VNC_GET_SIZE, VNC_GET_PIXEL_FORMAT, VNC_GET_PIXEL and optionally VNC_GET_RECT to return information on the display. You may provide VNC_LOCK and VNC_UNLOCK to allow locking against concurrent access to the display.
Event Layer
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.
Authentication Layer
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.
Running emVNC
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.
VNC
In this chapter, you will find a description of all API functions as well as all requireddata and function types.
Target API
This section describes the functions that can be used by the target application.
| Function | Description |
|---|---|
| General | |
| VNC_ServerInit() | Initialize VNC_CONTEXT structure so a server-process may be started on it. |
| VNC_EnableMouseInput() | Enables or disables mouse input via VNC. |
| VNC_DisplayChanged() | Tells the VNC server that an area of the display was changed. |
| VNC_EnableKeyboardInput() | Enables or disables keyboard input via VNC. |
| VNC_HandleClientProtocol() | Check up on client, maintain connection and answer any pending requests. |
| VNC_RingBell() | Ring a bell on the client if it has one. |
| VNC_SetLockFrame() | Configures the VNC server not to read the display while the display layer performs drawing operations. |
| VNC_SetPassword() | Sets the password to use for authentication of clients. |
| VNC_SetProgName() | Sets the title to be displayed in the title bar of the client window. |
| VNC_SetRetryCount() | Sets the number of additional trials in case of an error when trying to write data to a client. |
| VNC_SetSize() | Sets the display size to be transmitted to the client. |
VNC_ServerInit()
Description
Initialize VNC_CONTEXT structure so a server-process may bestarted on it.Call this function to initialize a client connection.
Prototype
void VNC_ServerInit( VNC_CONTEXT * pContext, const VNC_DISPLAY_CALLBACKS * Display, const VNC_CLIENT_CALLBACKS * Client, const VNC_AUTH_CALLBACKS * Auth, const VNC_FILE_CALLBACKS * File, const VNC_EVENT_CALLBACKS * Event);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a VNC_CONTEXT structure. This structure is used internally by the VNC server and should not be on the stack. |
| Display | Pointer to a VNC_DISPLAY_CALLBACKS structure containing display callback function pointers. |
| Client | Pointer to a VNC_CLIENT_CALLBACKS structure containing client callback function pointers. |
| Auth | Pointer to a VNC_AUTH_CALLBACKS structure containing authentication callback function pointers. This parameter is only available when VNC_SUPPORT_AUTH is enabled. |
| File | Pointer to a VNC_FILE_CALLBACKS structure containing file callback function pointers. This parameter is only available when VNC_SUPPORT_FILE is enabled. |
| Event | Pointer to a VNC_EVENT_CALLBACKS structure containing display callback function pointers. |
VNC_EnableMouseInput()
Description
Enables or disables mouse input via VNC.
Prototype
void VNC_EnableMouseInput(VNC_CONTEXT * pContext, int OnOff);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a VNC_CONTEXT structure. |
| OnOff | 1 for enabling mouse input, 0 for disabling. |
VNC_DisplayChanged()
Description
Tells the VNC server that an area of the display was changed.
Prototype
void VNC_DisplayChanged(VNC_CONTEXT * pContext, unsigned x, unsigned y, unsigned Width, unsigned Height);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a VNC_CONTEXT structure. |
| x | Base coordinate of changed area |
| y | Base coordinate of changed area |
| Width | Width of changed area |
| Height | Height of changed area |
Notes
MUST NOT be called while holding the display lock.
VNC_EnableKeyboardInput()
Description
Enables or disables keyboard input via VNC.
Prototype
void VNC_EnableKeyboardInput(VNC_CONTEXT * pContext, int OnOff);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a VNC_CONTEXT structure. |
| OnOff | 1 for enabling keyboard input, 0 for disabling. |
VNC_HandleClientProtocol()
Description
Check up on client, maintain connectionand answer any pending requests.Call this function regularly for every client to maintainthe client connection.
Prototype
int VNC_HandleClientProtocol(VNC_CONTEXT * pContext);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a VNC_CONTEXT structure. |
Return value
| > 0 | OK, a delay of this milliseconds is suggested before recalling the event handler. |
| = 0 | OK |
| < 0 | error |
Notes
pContext->aOutBuffer MUST be empty when calling.It will be used, but is guaranteed to be empty afterwards again.
VNC_RingBell()
Description
Ring a bell on the client if it has one.
Prototype
void VNC_RingBell(VNC_CONTEXT * pContext);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a VNC_CONTEXT structure. |
VNC_SetLockFrame()
Description
Configures the VNC server not to read the display whilethe display layer performs drawing operations.
Prototype
void VNC_SetLockFrame(VNC_CONTEXT * pContext, unsigned OnOff);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a VNC_CONTEXT structure. |
| OnOff | If set to a value >0 frame locking will be enabled. |
Additional information
This can be configured at compile time by using the compile time switchVNC_LOCK_FRAME.
Notes
The default of this is set via VNC_LOCK_FRAME.
VNC_SetPassword()
Description
Sets the password to use for authentication of clients
Prototype
void VNC_SetPassword( VNC_CONTEXT * pContext, const char * sPassword);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a VNC_CONTEXT structure. |
| sPassword | Location of password to use. Set to NULL to disable authentication. |
Notes
sPassword must remain valid until server is terminated or a newpassword is set. It is NOT copied to a local buffer.
VNC_SetProgName()
Description
Sets the title to be displayed in the title bar of the client window.
Prototype
void VNC_SetProgName( VNC_CONTEXT * pContext, const char * sProgName);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a VNC_CONTEXT structure. |
| sProgName | Title to be displayed in the title bar of the client window. |
VNC_SetRetryCount()
Description
Sets the number of additional trials in case of an error whentrying to write data to a client.
Prototype
void VNC_SetRetryCount(VNC_CONTEXT * pContext, unsigned Count);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a VNC_CONTEXT structure. |
| Count | Number of additional trials to be used in case of an error (default is 0). |
VNC_SetSize()
Description
Sets the display size to be transmitted to the client.
Prototype
void VNC_SetSize(VNC_CONTEXT * pContext, unsigned Width, unsigned Height);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a VNC_CONTEXT structure. |
| Width | X-size to be used. |
| Height | Y-size to be used. |
Additional information
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.
Structures
The table below lists the available structures.
| Structure | Description |
|---|---|
| VNC_DISPLAY_CALLBACKS | Callbacks used to handle display operations. |
| VNC_CLIENT_CALLBACKS | Callbacks used for data transfer. |
| VNC_EVENT_CALLBACKS | Callbacks used to handle VNC events. |
| VNC_AUTH_CALLBACKS | Callbacks used for authentication. |
VNC_DISPLAY_CALLBACKS
Description
Callbacks used to handle display operations.
Type definition
typedef struct { VNC_LOCK * pfLock; VNC_UNLOCK * pfUnlock; VNC_GET_SIZE * pfGetSize; VNC_GET_PIXEL_FORMAT * pfGetPixelFormat; VNC_GET_PIXEL * pfGetPixel; VNC_GET_RECT * pfReadRect;} VNC_DISPLAY_CALLBACKS;
Structure members
| Member | Description |
|---|---|
| pfLock | Lock display. |
| pfUnlock | Unlock display. |
| pfGetSize | Get display size. |
| pfGetPixelFormat | Get pixel format. |
| pfGetPixel | Get a single pixel. |
| pfReadRect | [Optional] Get rectangle. |
VNC_CLIENT_CALLBACKS
Description
Callbacks used for data transfer.
Type definition
typedef struct { VNC_SEND * pfSend; VNC_RECV * pfRecv;} VNC_CLIENT_CALLBACKS;
Structure members
| Member | Description |
|---|---|
| pfSend | Send data to client. |
| pfRecv | Receive data from client. |
VNC_EVENT_CALLBACKS
Description
Callbacks used to handle VNC events.
Type definition
typedef struct { VNC_MOUSE * pfMouse; VNC_KEYBOARD * pfKeyboard; VNC_COPY * pfCopy;} VNC_EVENT_CALLBACKS;
Structure members
| Member | Description |
|---|---|
| pfMouse | [Optional] Mouse callback. |
| pfKeyboard | [Optional] Keyboard callback. |
| pfCopy | [Optional] Copy callback. |
VNC_AUTH_CALLBACKS
Description
Callbacks used for authentication.
Type definition
typedef struct { VNC_GET_CHALLENGE * pfGetChallenge;} VNC_AUTH_CALLBACKS;
Structure members
| Member | Description |
|---|---|
| pfGetChallenge | [Optional] Handle authentication. |
Function Types
The table below lists the available function types.
| Type | Description |
|---|---|
| VNC_SEND | Send data to client. |
| VNC_RECV | Receive data from client. |
| VNC_LOCK | Protect display against concurrent accesses. |
| VNC_UNLOCK | Remove lock placed by VNC_LOCK. |
| VNC_GET_SIZE | Retrieves the display size. |
| VNC_GET_PIXEL_FORMAT | Retrieves the pixel format. |
| VNC_GET_PIXEL | Get color value for a specified pixel. |
| VNC_GET_RECT | Optional callback to retrieve multiple pixels in one go. |
| VNC_MOUSE | Handle mouse event coming from client. |
| VNC_KEYBOARD | Handle keyboard event coming from client. |
| VNC_COPY | Handle client copied text. |
| VNC_GET_CHALLENGE | Handle authentication. |
VNC_SEND
Description
Send data to client.
Type definition
typedef int (VNC_SEND)( VNC_CONTEXT * pContext, const U8 * pBuffer, unsigned Len);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a valid VNC_CONTEXT structure. |
| pBuffer | Pointer to the data to be sent. |
| Len | Number of bytes to be sent. |
Return value
| > 0 | Amount of data sent. |
| = 0 | Disconnected from the client. |
| < 0 | An error occurred. |
VNC_RECV
Description
Receive data from client.
Type definition
typedef int (VNC_RECV)(VNC_CONTEXT * pContext, U8 * pBuffer, unsigned Len);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a valid VNC_CONTEXT structure. |
| pBuffer | Pointer to a buffer. |
| Len | Number of bytes to read. |
Return value
| > 0 | Amount of data received. |
| = 0 | Disconnected from the client. |
| < 0 | An error occurred. |
VNC_LOCK
Description
Protect display against concurrent accesses.
Type definition
typedef void (VNC_LOCK)(VNC_CONTEXT * pContext);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a valid VNC_CONTEXT structure. |
VNC_UNLOCK
Description
Remove lock placed by VNC_LOCK.
Type definition
typedef void (VNC_UNLOCK)(VNC_CONTEXT * pContext);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a valid VNC_CONTEXT structure. |
VNC_GET_SIZE
Description
Retrieves the display size.
Type definition
typedef void (VNC_GET_SIZE)(VNC_CONTEXT * pContext, unsigned * pWidth, unsigned * pHeight);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a valid VNC_CONTEXT structure. |
| pWidth | in Display width. |
| pHeight | in Display height. |
VNC_GET_PIXEL_FORMAT
Description
Retrieves the pixel format.The callback must store the correct format inside VNC_CONTEXT->PixelFormat.
Type definition
typedef int (VNC_GET_PIXEL_FORMAT)(VNC_CONTEXT * pContext);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a valid VNC_CONTEXT structure. |
Return value
| = 0 | Success. |
| ≠ 0 | Error. |
VNC_GET_PIXEL
Description
Get color value for a specified pixel.
Type definition
typedef U32 (VNC_GET_PIXEL)(VNC_CONTEXT * pContext, unsigned x, unsigned y);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a valid VNC_CONTEXT structure. |
| x | Pixel coordinate. |
| y | Pixel coordinate. |
Return value
U32 color value, in device format.
Additional information
The function must perform a color conversion if necessary.
VNC_GET_RECT
Description
Optional callback to retrieve multiple pixels in one go.
Type definition
typedef void (VNC_GET_RECT)(VNC_CONTEXT * pContext, unsigned x, unsigned y, unsigned xSize, unsigned ySize, U32 * pPixelBuffer);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a valid VNC_CONTEXT structure. |
| x | Pixel coordinate. |
| y | Pixel coordinate. |
| xSize | Rectangle x size |
| ySize | Rectangle y size |
| pPixelBuffer | Pointer to a buffer to store the pixel data (pixel index only, no color conversion) |
Additional information
The function should not perform a color conversion.When using this function the color format ofthe client and the color format used for the display must match.
VNC_MOUSE
Description
Handle mouse event coming from client.
Type definition
typedef void (VNC_MOUSE)(VNC_CONTEXT * pContext, unsigned x, unsigned y, unsigned PressedButtonMap);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a valid VNC_CONTEXT structure. |
| x | Mouse coordinate. |
| y | Mouse coordinate. |
| PressedButtonMap | Map of buttons currently pressed on the mouse. |
VNC_KEYBOARD
Description
Handle keyboard event coming from client.
Type definition
typedef void (VNC_KEYBOARD)(VNC_CONTEXT * pContext, U16 Key, char IsPressed);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a valid VNC_CONTEXT structure. |
| Key | VNC key code. |
| IsPressed | 1 - key is pressed, 0 - key is released. |
VNC_COPY
Description
Handle client copied text.
Type definition
typedef void (VNC_COPY)(VNC_CONTEXT * pContext, char * pBuffer, unsigned Length);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a valid VNC_CONTEXT structure. |
| pBuffer | Pointer to a buffer containing the copied text. |
| Length | Length of the data in the buffer. |
VNC_GET_CHALLENGE
Description
Handle authentication.
Type definition
typedef void (VNC_GET_CHALLENGE)(VNC_CONTEXT * pContext, U8 * pChallenge);
Parameters
| Parameter | Description |
|---|---|
| pContext | Pointer to a valid VNC_CONTEXT structure. |
| pChallenge | Pointer to a buffer containing the authentication challenge. |
Additional information
This must save a challenge of VNC_AUTH_CHALLENGE_SIZE bytesin pChallenge. Usually that should be newly generated random data.
Support
Contacting support
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 pleasesend the following information via email to ticket_emnet@segger.com
By sending us an email your (personal) data will automatically be processed. For further information please refer to our privacy policy which is available at https://www.segger.com/legal/privacy-policy/.
:
- Your emVNC registration number.
- emVNC version.
- 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.
