NVDA (NonVisual Desktop Access) is an open source screen reader for computers running on the Windows operating system. It allows blind and visually impaired users to operate a computer without a mouse or screen. Although NVDA has many advanced features, it currently does not support remote sessions (e.g. RDP, Citrix or VMware Horizon) natively.
Because of this, Access4U developed the UnicornDVC software. This is commercial software that allows you to create communication channels in remote desktop connections, in order for a local and remote instance of NVDA to communicate together. This opens the possibility for a speech and braille user to operate a remote session with the same performance as a local system.
Requirements
Our NVDA remote solution (from now on referred to as NVDA Remote DVC) consists of three parts, which can be downloaded from Babbage’s software and update page:
- The NVDA Screen reader, which can be downloaded from The NV Access website
- The NVDA Remote add-on, which facilitates communication between NVDA and the external Unicorn library. The original remote add-on can be downloaded from nvdaremote.com, but lacks support for Unicorn. NVDA Remote has been forked to support communication using the Unicorn library. This version of NVDA Remote can be downloaded from Babbage’s website. NVDA Remote is an add-on package for NVDA and needs to be installed in NVDA’s user profile on both the server and the client.
- UnicornDVC, the component that facilitates remote communication of speech and braille messages, which can also be downloaded from the software and updates page mentioned above. This software is currently not available for download. Per user licenses for this product are provided by Babbage. Unicorn itself consists of two parts:
- UnicornDVC Application library: communication library for applications. This is required for server and client installations.
- UnicornDVC Plugin library: communication library for client software, such as Citrix Workspace (formerly Receiver), VMware Horizon Client or the Windows built-in RDP client. This is required for client installations only.
License terms
NVDA and the NVDA Remote add-on are available under the GNU General Public License version 2, with two special exceptions: Non-GPL Components in Plugins and Drivers” and “Microsoft Distributable Code. NVDA also includes and uses components which are made available under different free and open source licenses.
The UnicornDVC software is a non-free component. Licenses are provided on a per user basis. This means that a license is bound to a single user or client. The instance of UnicornDVC that is active on the server can be used free of charge, but note that you will always require both a server and a client to communicate. A server that operates both as client and server (i.e. a so called stepping stone server or jump server) is treated as a client.
When you initialize UnicornDVC in client mode without an activation and a connection is established, you will get a warning indicating that you’re running a trial version.
Unicorn utilizes a ten minutes trial mode. After ten minutes, an existing connection will be disconnected automatically and you will have to reconnect.
Installation
The major part of the installation process of NVDA Remote DVC is fairly straight forward.
Installing NVDA
This process has to be executed on the server and on every client. NVDA can be downloaded from The NV Access website or from babbage.com.
NVDA is distributed as an executable installer. When you have successfully downloaded NVDA, you can run de downloaded file as usual. You will be asked if you want to install NVDA, create a portable copy or just continue using the temporary copy. Here, press the Install NVDA button.
The installation dialog that appears will confirm whether you wish to install NVDA and will also tell you whether this installation will be updating a previous install.
Pressing the Continue button will start installing NVDA.
There are also a few options in this dialog which are explained below.
Once the installation has completed, a message will appear telling you that it was successful.
Pressing OK at this point will restart the newly installed copy of NVDA.
Setting up Speech and Braille
You should setup speech and braille to your desired functionallity. If both speech and braille functions perfectly; You needn’t setup the remote speech and braille. The remote machine (perhaps somewhere at another location) doesn’t need to be speeking. The remote machine doesn’t need direct brailkle output neither.
Start at Windows Logon
This option allows you to choose whether or not NVDA should automatically start while on the Windows Logon screen, before you have entered a password. This also includes UAC control and other secure screens. This is recommended for client installations. For servers, it is discouraged to enable this, unless you are physically operating a server as a visually impaired server administrator. Note that on a server, NVDA will still talk on secure screens when the active user has NVDA running.
Create Desktop Shortcut (ctrl+alt+n)
This option allows you to choose whether or not NVDA should create a shortcut on the desktop to start NVDA.
If created, this shortcut will also be assigned a shortcut key of control+alt+n, allowing you to start NVDA at any time with this key stroke.
Note that this shortcut is system wide.
Installing NVDA Remote
Note: NVDA Remote installs in the currently active user profile, therefore you should install NVDA Remote when running as the user who has to use it.
NVDA Remote is distributed as an add-on package and can be downloaded from babbage.com/remote.
When installing the add-on in the user profile of an installed copy of NVDA, you can simply double click the add-on from the Windows Explorer, as the installation of NVDA will register itself with *.nvda-addon files. When an add-on is being installed, NVDA will first ask you to confirm that you really wish to install the add-on.
As the functionality of add-ons is unrestricted inside NVDA, which in theory could include accessing your personal data or even the entire system if you have administrative privileges, it is very important to only install add-ons from sources you trust.
Once the add-on is installed, NVDA must be restarted for the add-on to start running.
Alternative installation method
You can also install NVDA Remote from the NVDA menu, which you access with the Insert+N shortcut or by clicking the NVDA icon in the system tray. The Add-ons Manager, accessed by selecting Manage add-ons under Tools in the NVDA menu, allows you to install, uninstall, enable and disable add-on packages for NVDA. The Add-ons Manager contains a list that displays all the add-ons currently installed in the NVDA configuration for the current user. To install the NVDA Remote add-on you previously obtained, press the Install button.
Installing UnicornDVC
The basics of the UnicornDVC installation are straight forward.
Just follow the on screen instructions when running the installer.
Please pay extra attention to the components screen, and only install the parts you need.
UnicornDVC Application library
The UnicornDVC Application library is the library used within NVDA to communicate over a virtual channel, both for client and server instances.
This library can be installed using our installer.
The Application Library is always installed.
In case of RDP or Citrix, this library just covers it all for server installations.
When you are installing UnicornDVC inside a VMware Horizon VDI, you are required to install VMware Horizon support as well, which basically installs another library provided by VMware.
UnicornDVC Plugin library
The UnicornDVC Plugin library is the library used for communication by your client software (e.g. Remote Desktop Client, VMware Horizon Client or Citrix Workspace).
It implements the Microsoft DVC client-side APIs, which guarantees compatibility with all major remote desktop platforms currently available on the market.
It is only required on client systems and doesn’t have to be installed on a server, unless the particular server is a jump server.
It should be noted that this library is not suitable for portable use, since using it requires certain information to be added to the Windows Registry.
Automatic installation
By default, our installer software automatically installs the UnicornDVC Plugin library component.
On X64 systems, it will allow you to use the library from both X86 and X64 client software.
The installer automatically adds the required keys to the registry for use with Remote Desktop Client and VMware Horizon Client.
By default, the registry keys that are required for your client software are installed under the “HKEY_LOCAL_MACHINE” key, and thus on a per machine basis.
This is controlled by the Register plugin for all users component.
If you want to register the plugin for the current user only, disable this component and enable the Register plugin for this user option instead.
Note that Citrix support is always installed on a per machine basis due to limitations in the Citrix Workspace software.
To support Citrix Workspace, you need to enable Citrix support during the installation.
The installer will automatically try to detect whether Citrix Receiver is installed and checks the component if this is the case.
If there is no installation of Citrix Workspace, you will be unable to install Citrix support.
You will have to perform a manual installation of the Citrix support instead.
Manual installation
If you want to use the UnicornDVC Plugin library without installing it using our installer, go to the particular location from a command prompt with administrative privileges and run the following command:
regsvr32 UnicornDVCPlugin.dll
To uninstall, i.e. to remove the required registry keys, run the following instead:
regsvr32 /u UnicornDVCPlugin.dll
It is recommended to perform the manual installation/removal for both the X86 and X64 version of the UnicornDVC Plugin library.
Note: There is a hyper manual installation method, i.e. avoid the regsvr32 approach and do all the registry tweaks yourself, but due to the risks involved in this process (e.g. corrupting the registry), we didn’t bother documenting this.
Manual Citrix Receiver plugin registration
To use the UnicornDVC Plugin library with Citrix Receiver, additional steps are required when performing a manual installation:
- Go to the windows registry. If you don’t know how to get there, you are strongly discouraged to go on with this
- Find the following registry key on X64 systems:
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Citrix\ICA Client\Engine\Configuration\Advanced\ModulesAnd on X86 systems:
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\ICA Client\Engine\Configuration\Advanced\Modules - Open the sub key “DVCAdapter”
- Find the value called “DvcPlugins”
- Add the following to the end of the string:
,UnicornDVCPlugin
- Repeat step 2, be sure that you are add the “Modules” sub key
- Create a new sub key called “DVCPlugin_UnicornDVCPlugin”
- Within this sub key, add the following registry values:
"DvcNames"="UnicornDVCPlugin" "PluginClassId"="{E8BACC05-64F6-4534-9764-FB6698CA3362}"
Additional notes for system administrators
This paragraph contains some unordered notes that are particularly relevant for system or server administrators.
- By default, NVDA saves its user configuration in the NVDA folder of the user’s roaming application data profile. You need to make sure that this configuration folder is persistent (i.e. that the user configuration remains available to the user at all times and won’t be cleaned up).
- You can provide a different configuration folder using the “-c” command line parameter, but this is generally undesirable, as this causes conflicts when NVDA is started from the Windows Ease of Access Center.
- Even though the NVDA installer creates a desktop shortcut to
nvda_slave.exe, the main executable of NVDA isnvda.exe.- If you have to manually create a desktop shortcut (e.g. in the RES/Ivanti workspace management software), it is best to point the shortcut at
nvda.exe. - It is also advised to provide the “-r” command line parameter. If this command line parameter is provided, activating the shortcut while there is an active instance of NVDA will automatically close that instance and start a new one.
- If you have to manually create a desktop shortcut (e.g. in the RES/Ivanti workspace management software), it is best to point the shortcut at
- Running NVDA does not require administrative privileges. However, it does require the UIAccess privilege. An application is only able to gain this privilege when installed in one of the Program Files directories.Additionally, In some environments, there a limitations in the extend to which an application is allowed to spawn additional processes. Therefore, you might explicitly have to give
nvda.exethe permission to start the following processes:nvda_slave.exenvdaHelperRemoteLoader.exe: this file is usually located in a versioned subfolder of the lib64 directory (i.e. lib64\2018.2\nvdaHelperRemoteLoader.exe)C:\Windows\System32\Utilman.exe: this file is related to the Windows Ease of Access Center and allows NVDA to register itself as the active screen reader
Under windows 7 and server 2008R2, you should give the same permissions to
nvda_eoaProxy.exe. nvda_eoaProxy.exe should also be allowed to start nvda.exe.
Silent Unicorn installation
You can execute a silent NVDA installation by providing the --install-silent parameter to the installation executable. On server installations, you are strongly encouraged to also provide the --enable-start-on-logon=False option.
On a shared server, this ensures that NVDA will not talk when establishing the session or on the logon screen.
Silent Unicorn installation
It is possible to run the UnicornDVC installation in silent mode.
For this, you will have to pass the /S (upper case) command line parameter to the installer.
Additionally, you can control the installation of certain components with the following command line parameters. Replace x with 0 to disable and 1 to enable installation of the components:
| Parameter | Description | Default |
|---|---|---|
/SELECT_HORIZON=x |
Whether or not to install VMware Horizon support (server side) | 0 |
/SELECT_PLUGIN=x |
Whether or not to install the DVC plugin (client side) | 1 |
/SELECT_PLUGIN_ALL_USERS=x |
Whether or not to register the DVC plugin for all users | 1 |
/SELECT_PLUGIN_CURRENT_USER=x |
Whether or not to register the DVC plugin for the current user | 0 |
Note that the /SELECT_PLUGIN_ALL_USERS and /SELECT_PLUGIN_CURRENT_USER parameters are not mutually exclusive. Enabling them both will register the plugin both for all users and the current user. While this may sound confusing, it allows for maximum configurability.
Activating Unicorn on the client
A license key for UnicornDVC has to be installed and activated on a client system. One license key can be activated three times. Without a license key, UnicornDVC is ooperating in 10 minutes connection trial mode. Activation should only be performed on a client system when running NVDA under the user profile of the user who is going to use the software.
You can perform the activation as follows:
- Enter the NVDA menu (insert+N), and choose “Tools”, then “Remote”. Finally, press Enter on Manage Unicorn License Key…
- Enter the provided license key at purchase.
- Press Ok.
- When the activation/validation is succesful, this will be reported accordingly. If the resulting message reveals an error, please make sure that your network connection is working and that https traffic on port 443 is unrestricted. If the problem persists, please contact your Unicorn dealer.
Note that you can also deactivate an activated license using the “Manage Unicorn license” menu item. When you have a valid license, you will be automaticall asked whether you want to deactivate.
Setting up a connection
When the installation is complete, you can set up NVDA to automatically initiate a connection between the two NVDA instances. This is recommended on the server side. On the client, it is also recommended if a client is mainly used to control a remote session. You can also initiate the connection manually on both sides.
Automatic connection
Follow the steps below to let NVDA initiate remote connections automatically.
- Enter the NVDA menu (insert+N), and choose “Tools”, then “Remote”. Finally, press Enter on Options.
- Check the box that says, “Auto connect on startup”.
- In the first set of radio buttons, select “Use a virtual channel”.
- In a remote session (server side), select Allow this machine to be controlled in the second set of radio buttons. IN a local session (client side), select “Control another machine”.
- Press “OK”
- Restart NVDA. You can do this by pressing Insert+Q and selecting “Restart”. You can also open the exit dialog by choosing “Exit” from the NVDA menu.
When you executed the steps above for both sides of the connection, NVDA will automatically connect on both sides as soon as you are in a remote session and NVDA is active in both sessions. When the connection is set up succesfully, NVDA will play a beep and says “connected”. Furthermore, you will hear double speech output when controlling the remote session. You can safely disable the speech synthesizer in your remote session, as speech will now be controlled by the local instance of NVDA.
Manual connection
- Open the NVDA menu (Insert+N), “Tools”, “Remote”, “Connect”.
- Choose “Virtual channel (RDP/ICA/PCoIP)” in the first set of radio buttons.
- In a remote session (server side), select Allow this machine to be controlled in the second set of radio buttons. IN a local session (client side), select “Control another machine”.
- Press ok.
Once these steps are performed on both sides of the connection, you will hear a tone and the speech says “connected”. Furthermore, you will hear double speech output when controlling the remote session. You can safely disable the speech synthesizer in your remote session, as speech will now be controlled by the local instance of NVDA.
What if you don’t have braille output (or double speech output)
Speech will now be controlled by the local instance of NVDA. So if your local machine has the right setup, you will here the local speech and notice the output of the braille display. Look into the local braille and speech setting first.
You can safely disable the speech synthesizer in your remote session. If you have braille output and speech; you have proved that UNICORN is connecting the remote and local NVDA sessions.