Citrix Ready workspace hub

The Citrix Ready workspace hub combines digital and physical environments to deliver apps and data within a secure smart space. The complete system connects devices (or things), like mobile apps and sensors, to create an intelligent and responsive environment.

Citrix Ready workspace hub is built on the Raspberry Pi 3 platform and becomes a robust service delivered through Citrix Cloud. Citrix Ready workspace hub users can authenticate their mobile device through Citrix Workspace app to run published apps or desktops. For example, Citrix Virtual Apps and Desktops, Citrix Content Collaboration, and Microsoft Outlook. The mobile device then connects to the Citrix Ready workspace hub and casts the desktop or app on a larger display.

Citrix Ready workspace hub enables Citrix Casting, which offers two use cases that improve user productivity and collaboration.

  • Session roaming – A Citrix session roams from the mobile device (Android device) to the workspace hub.
  • Screen casting – Users redirect their display from a remote session from an Android or Windows device to an unoccupied hub.

Citrix Casting uses beacon detection or a QR code scanner for connecting. With beacon detection, if multiple Citrix Ready workspace hubs are available, the user must select the appropriate hub. Alternatively, a QR code scanner provides security to mitigate unintentional casting to the wrong display.

Also, the administrators can set up their environment with multiple display monitors by using the Secondary Display Adapter (SDA). Doing so enables end users to extend the desktop or app when using either use case.

System Requirements

Network

  • The mobile device must be on the same network as the workspace hub.
  • Do not block Port 55555 between the mobile device and the workspace hub.
  • For Citrix Casting, do not block port 1494.
  • Port 55556 is the default port for SSL connections between mobile devices and the Citrix Ready workspace hub. You can configure a different SSL port on Pi’s settings page. If the SSL port is blocked, users cannot establish SSL connections to the hub.

Citrix Virtual Desktops

Citrix Ready workspace hub is supported on Citrix XenDesktop 7.6 and later.

  • For session roaming, ensure that Citrix Ready workspace hub can access HDX servers (VDA).
  • For session roaming and screen casting, ensure the Use video codec for compression policy in Citrix Studio is set to For the entire screen. Failure to do so might cause performance issues.

Hardware

  • Citrix Ready workspace hub
  • Two monitors (for dual monitor setups only)
  • Mobile device running Citrix Workspace app
  • HDMI cable and power supply
  • Micro USB to USB A Cable (if a Secondary Display Adapter [SDA] is used)
  • Optional hardware, such as a USB keyboard, USB mouse, or headphones
  • SDA powered by Raspberry Pi Zero

As of October 2018, we support devices running on the following operating systems and versions of Citrix Receiver or Citrix Workspace app:

  • Android: Citrix Receiver 3.13.5 and later; Citrix Workspace app for Android 1808 and later
  • iOS: Citrix Workspace app 1810.1 for iOS
  • Mac: Citrix Workspace app 1808 for Mac (Preview, Screen casting only)
  • Windows: Citrix Workspace app 1809 for Windows (Screen casting only)

Upgrade HDX Ready Pi

To upgrade an existing HDX Ready Pi device to a Citrix Ready workspace hub, see the following procedures.

Initial setup with internal centralized management

To create a Stratodesk Management console, go to Stratodesk’s website and create an account. https://www.stratodesk.com/kb/Main_Page

Initial setup with Citrix Endpoint Management

To use Citrix Endpoint Management as the management solution for Citrix Ready workspace hub, you need to configure workspace hub to point to the central management URL. Follow the steps documented at Citrix Endpoint Management Server.

Note

If you’ve previously pointed your device at a NoTouch Management console you might need to reset the device to factory defaults.

Configuration with no centralized management

  1. Start the Citrix Ready workspace hub device.
  2. Go to Start > Configuration. The default password is “admin.”
  3. Go to Connections > Add.
  4. Edit the new Connection and choose Citrix/WorkspaceHub from Connection mode. Click Save.
  5. At the top of the screen, click the Workspace Hub button.
  6. Type the desired URL for Workspace Hub Launcher (add http:// or https:// to the URL). It typically points to a StoreFront or Citrix Gateway URL; however, you can point it to any URL you want to come up upon boot.
  7. Click Save.
  8. Reboot the Citrix Ready workspace hub.

Citrix Virtual Apps and Desktops configuration

Make a few changes to your Citrix Virtual Apps and Desktops configuration to ensure you have the best experience with Citrix Ready workspace hub.

Skype for Business

To use Skype for Business, install the HDX RealTime Optimization Pack version 2.4 or later on the VDA. Set Use Hardware Rendering to Off if the Optimization Pack is being used (see the following Performance policy section for more details).

Note

Currently dual display is not supported in version 2.4.

Performance policy

To get the best experience on your Citrix Ready workspace hub (and the SDA), enable H.264 encoding for full-screen mode. To do this, create a policy and enable the video codec for H.264 compression (H.264) for full-screen mode.

Performance policy settings image

Compression image

To confirm that H.264 compression is enabled for full-screen mode so that the SDA can function properly, see one of the following procedures.

  • Review Citrix Policy from the Deliver Controller.
  • In a VDA session, use the HDX Monitor 3.x. See Knowledge Center article CTX135817.
  • In a VDA session, place the following line into the Terminal: wmic /namespace:\\root\citrix\hdx path citrix_virtualchannel_thinwire get /value

Then you can verify that the graphic mode is configured correctly for full-screen H.264 mode:

  1. Component_VideoCodecUse = FullScreen
  2. Component_Encoder = DeepCompressionV2Encoder
  3. IsActive = Active

If the graphic mode is configured for selective screen H.264, confirm that:

  1. Component_VideoCodecUse = For actively changing regions
  2. Component_Encoder = CompatibilityEncoder
  3. IsActive = Active

For a better display resolution, enable the ClearType attribute on the Windows VDA. See Microsoft Cleartype overview and How to turn on or off ClearType in Windows 10 for more information.

Dual monitor setup

To support dual monitors, a Secondary Display Adapter (SDA) is required. You can purchase SDAs from ViewSonic or NComputing. For more information, see https://www.stratodesk.com/kb/Multimonitor

Physical setup

There are two micro USB ports on the SDA. One is labeled “Power” the other is labeled “USB.” Plug a standard Raspberry Pi USB power adapter into the power port, then connected the SDA’s USB port and the Citrix Ready workspace hub using a standard micro USB-to-USB cable.

Software setup

See the earlier section Citrix Virtual Apps and Desktops Configuration. Follow the Performance policy in setting up H.264 rendering on both screens.

When you roam a session to the Citrix Ready workspace hub, dual monitors can be started automatically. To change the layout and alignment configuration, from the Stratodesk Management console, go to the configuration path Connections > Workspace Hub > Citrix Workspace app > Secondary Display Adapter.

SDA image

Citrix Ready workspace hub in Citrix Workspace app

The Citrix Ready workspace hub is disabled by default in Citrix Workspace app.

To use the workspace hub with an Android device, see the Citrix Ready workspace hub section in Configuration.

To use the workspace hub with Windows devices, see Configuring Citrix Ready workspace hub.

With Citrix Ready workspace hub 1809 release, Citrix introduces screen casting for Mac as a preview release. To participate in the preview, contact https://podio.com/webforms/20584651/1410453.

Session roaming with proximity authentication

Proximity authentication can authenticate users and launch an HDX session automatically without users’ touching the mobile device. Proximity relies on Bluetooth technology to locate mobile devices.

After the configuration is complete and Citrix Workspace app is launched, the session roams to the Citrix Ready workspace hub when the Android device enters the proximity authentication range of the hub.

If multiple hubs are within range, the following dialog appears to let you select your hub of choice to roam your session.

Choose the hub image

If multiple Citrix Ready workspace hubs are within range and Citrix Workspace app is running in the background, a notification appears on your mobile device.

Click the notification.

Multiple hubs image

With proximity authentication, there are four ways to exit a session:

  • Move your mobile device out of Range 1 and 2.
  • Use two fingers to swipe down on the Citrix Workspace app main interface.
  • Close Citrix Workspace app.
  • Exit the Windows session on the Citrix Ready workspace hub.

Session roaming with QR code authentication

You can scan the QR code on the screen of the hub to roam your session.

To use session roaming with a QR code in an Android device:

  1. Start a session on the mobile device.
  2. Click the QR code scan button on the Citrix Workspace app toolbar to scan the QR code on the Citrix Ready workspace hub.
  3. The session starts roaming to the Citrix Ready workspace hub.

Qr button image

Close the session using one of the following methods:

  • Use two fingers to swipe down on the Citrix Workspace app main interface.
  • Close Citrix Workspace app.
  • Exit the Windows session on the Citrix Ready workspace hub.

Screen casting with QR code authentication

To cast an HDX session to a hub, you must launch the HDX session on a device first, then scan the QR code on the hub. After casting the session to the hub, you can use the keyboard and mouse on the mobile device to control the session on the hub.

To enable screen casting with QR code authentication in an Android device, you must change the configuration on Citrix Ready workspace hub’s settings page.

  1. Open System configuration.

    System configuration image

  2. Edit Connections named “Citrix Ready workspace hub.”

    Edit workspace hub image

  3. Under Connections > Citrix Ready workspace hub, change Work mode to Casting.

    Roaming image

After screen casting the session to the Citrix Ready workspace hub, Citrix Workspace app on the mobile device acts as soft keyboard and mouse to control the session on the hub. Soft control image

To close the session:

  • Use two fingers to swipe down on the Citrix Workspace app main interface to return the session to your mobile device.
  • Close the session in Citrix Workspace app.
  • Exit the Windows session and then Citrix Ready workspace hub to close the session both on your mobile device and on the hub. It might take about 20 seconds for the session on the hub to exit. (See Known Limitations)

Long running session

During a long running session, you can put the Android device down with the screen locked. To ensure that the session runs uninterrupted, consider the following tips:

  • Battery optimization can interfere with your session. To avoid the effects of battery optimization, add Citrix Workspace app to the Android battery optimization ignore lists:
    • On a Google Pixel, go to Settings > Battery > Battery optimization > All apps > Citrix Receiver > Don’t optimize.
    • On most Samsung devices, go to Settings > Battery > Battery usage > Optimize battery usage > All apps > Citrix Receiver > Don’t optimize.
    • If you’re using a third-party battery optimization app, remove Citrix Workspace app for Linux from its optimization list.
  • To lock the screen and put the device down for a longer time after the Citrix Ready workspace hub session starts, Citrix recommends that you bring the Citrix Workspace app’s main interface to the foreground before locking your screen. Doing so ensures that the mobile device operating system does not end the Citrix Workspace app session.

Standard Logging

This feature lets you record the execution of the processes running in the Citrix Ready workspace hub and to provide a way to dynamically change the debug level for different modules.

Configuration

The ctxlogd daemon and the setlog utility are included in the hub package. By default, the ctxlogd daemon starts when you start the hub.

ctxlogd daemon

All other services that are traced depend on the ctxlogd daemon. You can stop the ctxlogd daemon if you do not want to keep the hub traced by terminating the process relating to ctxlogd. The log file, wsh.log is located at /opt/Citrix/WorkspaceHub/Logs.

setlog utility

The setlog utility, at /opt/Citrix/WorkspaceHub/lib/wshlog, lets you dynamically change the debug level for different modules. Only root users have permission to run it. You can add “sudo” to the head of the command to run the command by using pi user.

For example:

  1. To check the current log level for all modules:

    sudo /opt/Citrix/WorkspaceHub/lib/wshlog/setlog levels

  2. To set the log level as verbose for the controlService module:

    sudo /opt/Citrix/WorkspaceHub/lib/wshlog/setlog level WSH_CONTROLSERVICE verbose

You can get more usage information from the help manual “sudo /opt/Citrix/WorkspaceHub/lib/wshlog/ setlog –help”.

Citrix Customer Experience Improvement Program

When you participate in the Citrix Customer Experience Improvement Program (CEIP), anonymous statistics and usage information are sent to Citrix to help improve the quality and performance of Citrix products.

The Citrix Ready workspace hub uses Google Analytics as documented in How Google uses data when you use our partners’ sites or apps. to do the data analysis. You can switch off CEIP if you do not want to send your data to Google Analytics.

CEIP Switch

By default, you automatically participate in the CEIP. You can turn off CEIP through the Stratodesk UI.

CEIP data collected from the workspace hub

The following table lists the types of anonymous information collected. The data does not contain any details that identify you as a customer.

Data Point Key Name Description
OS release os_release Release information of PI OS, such as 4.9.35-v7
OS version os_version Version information of PI OS, such as 2017-07-05-raspbian-Jessie
Workspace hub version wsh_version Version information of the workspace hub, such as 1.0.72
SSL feature enabled or not ssl_mode Indicating whether the SSL feature is enabled or not. 1: enabled. 0: disabled
Dual monitor is used or not monitor_mode Indicating whether the dual monitor is used or not. 1: dual monitor. 0: single monitor
Monitor resolution monitor_resolution_p3 Screen resolution for the monitor connecting with p3
Monitor resolution monitor_resolution_p0 Screen resolution for the monitor connecting with p0
Session duration time (for session roaming only) session_time The duration time of a session

Security connection

SSL/TLS connections between mobile devices and the Citrix Ready workspace hub are supported but disabled by default. You can enable them on the hub’s settings page. The SSL/TLS port is configurable. If you enable SSL/TLS, ensure that the SSL/TLS certificate is loaded and its path configured correctly on the hub. Self-signed certificates must be installed on Android devices before users start working with the hub.

To configure SSL/TLS:

  1. For information about adding certificates and private keys to the Citrix Ready workspace hub, see: https://www.stratodesk.com/kb/Certificates#Method_2:_Distribute_certificates_automatically
  2. Change the Require SSL option to on, update the certificate file (cert.pem) and private key file (key.pem) names, and then click Save. Both options are under Connections > Workspace Hub > Workspace Hub.

SSL image

Shortcuts

  • Control-Alt-S, gives a readout of relevant troubleshooting information.
  • Control-Alt-C, brings up the configuration menu.
  • When Citrix Casting, swiping down on the phone with two fingers disconnects the session, regardless of the session state or how you cast it to the workspace hub.

Known Limitations

  • Web Interface stores do not support session roaming. As a result, do not select the Add account type as Web Interface check box.
  • While screen casting, if you exit your Windows session on the Citrix Ready workspace hub by clicking Sign out or Disconnect in Windows, it might take approximately 20 seconds for the session to exit on the hub.
  • Dual monitors support session roaming. Session casting is not supported.
  • To use the HDX RealTime Optimization Pack, Use Hardware Rendering must be set to Off. The feature works only on the primary screen. The window on the secondary screen is gray.
  • Wireless mouse devices - You might notice a lag when dragging a wireless mouse. Report this error in the Citrix workspace hub Discussions forum. Include the make and model of the mouse.
  • Citrix Casting works only when the mobile device is connected to the same network as the workspace hub.
  • 5G Wireless - The workspace hub is built on the Raspberry Pi3 platform, which does not currently support 5G wireless. However, it is possible to support 5G using a USB Wi-Fi dongle (not recommended).
  • The root CA certificate must be signed with SHA256. Citrix Workspace app for Linux does not accept SHA1-signed certificates. https://support.citrix.com/article/CTX200114
  • The Enlightened Data Transport (EDT) protocol is not supported with Citrix Ready workspace hub.

Troubleshoot

Screen casting failure

Citrix Ready workspace hub screen casting supports both full-screen H.264 and selective H.264 graphic modes. However, for optimal performance Citrix recommends the use of full-screen H.264. If you are experiencing a screen casting failure, check the graphic mode to ensure it is configured properly.

“Incompatible server” message

In Citrix Workspace app for Android, a failure in session casting leads to the following message:

Incompatible server image

This error occurs if the graphic mode is configured as selective H.264 on the VDA. Screen casting performs better with the full-screen H.264 graphic mode. Reconfigure the graphic mode to Full Screen in System Configuration > Connections > Workspace Hub, or upgrade the VDA to version 7.19 or later.

By default, SSL is disabled on the Citrix Ready workspace hub. To enable SSL/TLS, ensure that the SSL certificate is loaded and that its path is configured correctly on the hub. SSL configuration issues can result in failed casting session failure without displaying an error message.

User issue Suggestion
The WorkspaceHubControlService process is not initiated properly. In the terminal, enter the command: ps –ef|grep ControlService. If no process is found, check with IT to confirm that the ports 55555 and 55556 are not blocked on the network.
SSL is enabled without certificates installed on the hub or it is configured with an incorrect certificate path. Verify that the certificates and key files are installed on the Citrix Ready workspace hub. To do this, go to /opt/Citrix/WorkspaceHub/keystore/certs and confirm that the certificates are installed. If you are using a Stratodesk image, follow the path to find the ssl_enabled configuration item at System Configure > Connections > Citrix Workspace Hub > Workspace Hub. If using a Citrix image, check the ssl.config file at /opt/Citrix/WorkspaceHub/config/.
SSL is enabled on the Citrix Ready workspace hub, but the certificate is not installed on the Android client. Install the key files on the Android client.
A DisplayConnector process is already running. An earlier instance of the DisplayConnector process was not terminated properly. Terminate the process and try casting again.

Session roaming failure

This issue can occur after setting up a new Citrix Ready workspace hub. Session roaming can fail when the workspace hub configurations do not comply with the VDA session.

To resolve this issue:

  1. Start the VDA session in using Citrix Workspace app for Linux installed on the hub.
  2. Verify that the SSL is configured properly.

Fixed issues

The following issues have been fixed with the version 1809:

  1. If you walk out of range too quickly, the session might not disconnect properly.

    [WH-602]

  2. Administrators cannot set the full path for the SSL key and the certificate.

    [WH-745]

  3. You might experience intermittent disconnects of Citrix Ready workspace hub.

    [WH-770]

  4. Citrix Ready workspace hub might lose its connection to the keyboard after the session is idle or locked.

    [WH-790]

  5. When moving a video from the primary screen to the secondary screen in selective H.264 graphic mode, the hub screen might become unresponsive.

    [WH-835]

  6. The Bluetooth MAC address is always the same in the StratoDesk OS when doing screen casting.

    [WH-1060]

  7. In session roaming, the QR code keeps showing on the screen for selective H.264 graphic mode.

    [WH-1071]

  8. Occasionally, a QR code cannot be generated.

    [WH-1106]

Known Issues

  1. There are unexpected black lines on the Microsoft Windows 10 session desktop.

    [WH-860]

  2. Hublauncher might crash unexpectedly and the hub logon page appears. [WH-1371]

  3. The mouse might jump to the middle of the screen when you exit extending mode for screen casting on a Windows device.

    [WH-1402]

  4. A DisplayConnector mouse thread was terminated unexpectedly during session casting from a Xiaomi Mi pad.

    [WH-1419]

Support Information

Support for the Citrix Ready workspace hub device is available through the approved vendors from whom the device was purchased. Those vendors are NComputing, Stratodesk, and ViewSonic.