Merge pull request #78 from davidkline-ms/master

Fix device filtering for virtual machines and documentation refresh

merging per approvals

HoloLensCommander/HoloLensCommander/Controls/DeviceMonitorControlViewModel.cs

@@ -71,27 +71,6 @@ namespace HoloLensCommander
             DeviceMonitor monitor)
         {
             this.deviceMonitorControl = control;
-            switch (monitor.Platform)
-            {
-                case DevicePortalPlatforms.HoloLens:
-                    this.Filter = DeviceFilters.HoloLens;
-                    this.DeviceTypeLabel = DeviceIsHoloLensLabel;
-                    this.IpdVisibility = Visibility.Visible;
-                    break;
-
-                case DevicePortalPlatforms.Windows:
-                    this.Filter = DeviceFilters.Desktop;
-                    this.DeviceTypeLabel = DeviceIsPCLabel;
-                    this.IpdVisibility = Visibility.Collapsed;
-                    break;
-
-                default:
-                    Debug.Assert(false, "Unknown device platform.");
-                    this.Filter = DeviceFilters.None;
-                    this.DeviceTypeLabel = DeviceIsUnknownLabel;
-                    this.IpdVisibility = Visibility.Collapsed;
-                    break;
-            }
 
             this.RegisterCommands();
 
@@ -100,10 +79,13 @@ namespace HoloLensCommander
             this.deviceMonitor.HeartbeatReceived += Device_HeartbeatReceived;
             this.deviceMonitor.AppInstallStatus += DeviceMonitor_AppInstallStatus;
 
+            this.SetFilter();
+
             this.IsConnected = true;
 
             this.Address = deviceMonitor.Address;
             this.IsSelected = true;
+
         }
 
         /// <summary>
@@ -656,6 +638,59 @@ namespace HoloLensCommander
                 });
         }
 
+        /// <summary>
+        /// Determine the correct setting for the Filter property.
+        /// </summary>
+        private void SetFilter()
+        {
+            switch (this.deviceMonitor.Platform)
+            {
+                case DevicePortalPlatforms.HoloLens:
+                    this.Filter = DeviceFilters.HoloLens;
+                    this.DeviceTypeLabel = DeviceIsHoloLensLabel;
+                    this.IpdVisibility = Visibility.Visible;
+                    break;
+
+                case DevicePortalPlatforms.Windows:
+                    this.Filter = DeviceFilters.Desktop;
+                    this.DeviceTypeLabel = DeviceIsPCLabel;
+                    this.IpdVisibility = Visibility.Collapsed;
+                    break;
+
+                case DevicePortalPlatforms.VirtualMachine:
+                    switch (this.deviceMonitor.DeviceFamily)
+                    {
+                        case "Windows.Desktop":
+                            this.Filter = DeviceFilters.Desktop;
+                            this.DeviceTypeLabel = DeviceIsPCLabel;
+                            this.IpdVisibility = Visibility.Collapsed;
+                            break;
+
+                        case "Windows.Holographic":
+                            this.Filter = DeviceFilters.HoloLens;
+                            this.DeviceTypeLabel = DeviceIsHoloLensLabel;
+                            this.IpdVisibility = Visibility.Visible;
+                            break;
+
+                        default:
+                            Debug.Assert(false, "Virtual Machine: Unknown device family.");
+                            this.Filter = DeviceFilters.None;
+                            this.DeviceTypeLabel = DeviceIsUnknownLabel;
+                            this.IpdVisibility = Visibility.Collapsed;
+                            break;
+                    }
+                    break;
+
+                default:
+                    Debug.Assert(false, "Unknown device platform.");
+                    this.Filter = DeviceFilters.None;
+                    this.DeviceTypeLabel = DeviceIsUnknownLabel;
+                    this.IpdVisibility = Visibility.Collapsed;
+                    break;
+            }
+        }
+
+
         /// <summary>
         /// Monitors running processes and when the specified id is no longer running, update's the status message ui.
         /// </summary>

HoloLensCommander/HoloLensCommander/Controls/DeviceMonitorControlViewModelCommands.cs

@@ -82,6 +82,9 @@ namespace HoloLensCommander
                 "Manage apps", 
                 ContextMenuCommandHandler,
                 MonitorContextMenuCommandIds.ManageApps));
+            // Virtual Machines do not support Mixed Reality, base the decision
+            // on whether or not to show the Mixed Reality view item on the platform
+            // rather than the filter.
             if (this.deviceMonitor.Platform == DevicePortalPlatforms.HoloLens)
             {
                 contextMenu.Commands.Add(new UICommand(

HoloLensCommander/HoloLensCommander/Controls/DeviceMonitorControlViewModelProperties.cs

@@ -78,7 +78,23 @@ namespace HoloLensCommander
         /// <summary>
         /// Specifies the type of device this control is managing.
         /// </summary>
-        public readonly DeviceFilters Filter;
+        private DeviceFilters deviceFilter = DeviceFilters.None;
+        public DeviceFilters Filter
+        {
+            get
+            {
+                return this.deviceFilter;
+            }
+
+            private set
+            {
+                if (this.deviceFilter != value)
+                {
+                    this.deviceFilter = value;
+                    this.NotifyPropertyChanged("Filter");
+                }
+            }
+        }
         
         /// <summary>
         /// Gets or sets a string representation of the interpuplliary distance recorded on this device.

HoloLensCommander/README.md

@@ -1,201 +1,244 @@
 ## Windows Mixed Reality Commander
 
-Windows Mixed Reality Commander is a Universal Windows application that demonstrates using the Windows Device Portal in a classroom environment. It enables observation and management of one or more HoloLens and/or PC devices. This application is built upon the open source [Windows Device Portal Wrapper](https://github.com/Microsoft/WindowsDevicePortalWrapper) project and is used by the Microsoft HoloLens team in the Holographic Academy.
+Windows Mixed Reality Commander is a Universal Windows application that demonstrates using the Windows Device Portal in a classroom environment. It enables observation and management of one or more HoloLens and/or Windows PC devices. Along with managing a classroom, Windows Mixed Reality Commander can be used to effectively control devices in a demo environment.
+
+This application is built upon the open source [Windows Device Portal Wrapper](https://github.com/Microsoft/WindowsDevicePortalWrapper) project and is used by the Microsoft HoloLens team in the Holographic Academy.
 
 ![Windows Mixed Reality Commander](ReadmeImages/MainWindow.png)
 
 ### Requirements
 Windows Mixed Reality Commander requires:
-- A Windows 10 Device (Currently tested on x86 and x64)
-- A HoloLens or Windows PC (In developer mode with the [Windows Device Portal](https://developer.microsoft.com/en-us/windows/holographic/using_the_windows_device_portal#setting_up_hololens_to_use_windows_device_portal) enabled and configured)
+* A Windows 10 Device (Currently tested on x86 and x64)
+* A HoloLens or Windows PC (In developer mode with the [Windows Device Portal](https://developer.microsoft.com/en-us/windows/holographic/using_the_windows_device_portal#setting_up_hololens_to_use_windows_device_portal) enabled and configured)
 
 ### Building
-Building Windows Mixed Reality Commander requires [Visual Studio 2015 Community and the Windows 10 SDK](https://developer.microsoft.com/en-us/windows/downloads). Visual Studio 2015 Professional and Enterise are also supported.
-- Load HoloLensCommander.sln
-- Build and deploy the solution.
+Building Windows Mixed Reality Commander requires [Visual Studio 2015 Community and the Windows 10 SDK](https://developer.microsoft.com/en-us/windows/downloads). Visual Studio 2015 Professional and Enterprise are also supported.
+* Load HoloLensCommander.sln
+* Build and deploy the solution.
 
-### How to use Windows Mixed Reality Commander
-Note: The first time you start Windows Mixed Reality Commander on your PC, you will need to enter credentials or set the default credentials for Windows Device Portal connections to the HoloLens.
 
-#### Connecting to a device
-![Connection controls](ReadmeImages/ConnectionControls.png)
+### Key User Interface Elements
+
+#### Device Connection
+
+![Device Connection Controls](ReadmeImages/ConnectionControls.png)
 
 ##### Connect
 
-Connects to the specified device.
+The Connect button reads the user name and password, then displays a dialog allowing you to target a specific device.
 
-![Connect to device dialog](ReadmeImages/ConnectDialog.png)
+Before attempting to connect to a device, please be sure that the Windows Device Portal is enabled and paired with your desired credentials.
 
-Note: Leaving the address field blank, in the Connect to Device dialog, will attempt to use a USB connection between the PC and a HoloLens. This is for **development** and **side-load** scenarios only. By default Windows Store applications are not allowed to make loopback connections. At development time, Visual Studio enables loopback for your application automatically for debugging purposes. When side-loaded, you will need to explicity allow loopback connections as described in the [documentation](http://msdn.microsoft.com/en-us/library/windows/apps/hh780593.aspx).
+```
+Note: Windows PCs must be rebooted after enabling the Windows Device Portal.
+```
 
-You can optionally connect your device to a specific network access point by providing the SSID and network key in the appropriate boxes. Leaving these blank will not change your device's current WiFi settings.
+![Connection Dialog](ReadmeImages/ConnectDialog.png)
 
-When the Update Connection option is checked, Windows Mixed Reality Commander will attempt to change the IP address used for communicating with the device after the inital connection is established.
+###### Address
 
-##### Additional connection commands
+Enter the IP Address in the Address field. If you are connecting to a Windows PC, you must also provide the port number (typically 50443). To determine the correct address to specify:
 
-The additonal connection commands button (...) displays a context sensitive menu providing the following options:
+* HoloLens: Run the Settings application, select Network & Internet > Wi-Fi.
 
-- Reconnect to previous session
+* Windows PC : Run the Settings application, select Update & Security > For Developers.
 
-The reconnect command enables you to reconnect to the currently available devices that were managed in the previous Windows Mixed Reality Commander session. This command is available only if a HoloLens connection has yet to be established and the User name and Password fields are populated.
+###### SSID and Key
 
-- Set credentials as default
+If you wish to set your device onto a specific network access point, enter the SSID and network key in these boxes.
 
-Stores the current values of the User name and Password fields as the default credentials to be used when connecting to your device.
+###### Update Connection
 
-- Use default credentials
+Checking Update Connection instructs Windows Mixed Reality Commander to query the device for the first valid (non-169.x.x.x) IP address it reports. 
 
-Replaces the current values of the User name and Password fields with the stored default credentials.
+If you specified an SSID, this value may change, and the connection update may fail. Please retry the connection again without setting the SSID and verify the correct network configuration in the Settings application.
 
-##### User name
+##### Additional Options
 
-The user name used to connect to the device.
+The additional options (…) button displays a menu that provide less common connection related functionality.
 
-##### Password
+**Reconnect to previous session**
 
-The password used to connect to the device.
+This option allows you to reconnect to the devices that were connected in a previous session of Windows Mixed Reality Commander.
 
-#### Applications
-The applications section allows for managing the applications running on multiple devices simultaniously.
+For this to be successful, devices need to have been connected using a common set of credentials and the credentials must be set in the User name and Password fields before selecting this option.
 
-![Application management controls](ReadmeImages/ApplicationManagementControls.png)
+```
+Note: Reconnect to previous session will not appear in the additional options menu after 
+a reconnection has been attempted or the Connect button has been used one or more times.
+```
 
-##### Common applications list
-This list shows the applications that are installed on all of the selected devices.
+**Set credentials as new default**
 
-##### Refresh
-Queries the selected devices and updates the lost of common applications.
+This stores the current values for user name and password in a text file that resides in the Windows Mixed Reality Commander’s application data folder. 
 
-##### Run
-Runs the application selected in the common applications list on the selected devices.
+```
+Note: This data is stored in clear text and should not be considered secure storage.
+```
 
-##### Close All
-Stops all applications that are currently running on the selected devices.
+**Use default credentials**
 
-##### Install
-Installs an application on the selected devices.
+If you have persisted the device credentials, you can use the Use default credentials to instruct Windows Mixed Reality Commander in the case where they may have been overridden for a specific device.
 
-![Select Application Files Dialog](ReadmeImages/SelectAppFiles.png)
+##### Connection Shortcut for Development Machiens and Side-Loading
+
+Getting the IP address from your HoloLens can be a more time-consuming process than getting it from your Windows PC (ex: ipconfig).
+
+Users of the Windows Device Portal are aware of the ability to connect to an attached HoloLens using the loopback address (http://127.0.0.1:10080) when the Windows Phone IP over USB Transport service is installed (available as part of the Windows 10 SDK) and running.
+
+To take advantage of this feature, Windows Mixed Reality Commander will default to this loopback address if the Connect dialog’s Address field is left blank.
+
+```
+Note: By default, UWP applications are subject to network isolation. For development and 
+side-load scenarios, your PC can be configured to allow an application to establish
+loopback connections.
+
+Building Windows Mixed Reality Commander using Visual Studio, on the PC on which it will
+be run, will automatically configure to allow loopback connections.
+
+For side-load scenarios, please refer to the documentation describing network isolation
+troubleshooting (the application container name, at the time of this writing, for 
+Windows Mixed Reality Commander is “HoloLensCommander_ksbfhw2wnm4q4”).
+```
+
+#### Common Applications
+
+The applications section displays and controls applications that are common to all selected devices. Each time a device is selected or deselected, this list is updated.
+
+![Common Application Controls](ReadmeImages/ApplicationManagementControls.png)
+
+The Close All button will stop all running UWP applications on the selected devices. To be more selective in closing an application, you will need to use the Manage apps option for each device.
 
-##### Uninstall
-Uninstalls the application selected in the common applications list from each of the selected devices.
 
 #### Mixed Reality Capture
-The Mixed Reality Capture control section allows for recording and saving of Mixed Reality Capture videos from the selected devices.
 
-![Mixed Reality Capture controls](ReadmeImages/MixedRealityControls.png)
+The mixed reality capture section allows you to start and stop a recording on the selected devices. You can also save them to the PC running Windows Mixed Reality Commander and optionally delete them from the device after they have been saved locally.
 
-Note: Mixed Reality Capture is available only on HoloLens devices.
+![Mixed Reality Capture Controls](ReadmeImages/MixedRealityControls.png)
 
-##### Start
+Files are saved to your PC’s Pictures Library under HoloLensCommander, and each device’s files will be placed in a folder named after the device’s address or tag.
 
-Starts a Mixed Reality Capture video recording. Users will notice a recording indicator in the upper left of the Holographic Frame and will experience a reduced application frame rate until the recording is stopped.
+```
+Note: Windows PC devices do not support Mixed Reality Capture.
+```
 
-##### Stop
 
-Stops the Mixed Reality Capture video recording.
+#### Device control
 
-##### Save
+The device control section allows you to bulk reboot or shutdown the selected devices. It also allows you to instruct Windows Mixed Reality Commander to forget all connected devices.
 
-Files created by the Start and Stop controls, along with any other Mixed Reality Capture files created on the device (via Windows Mixed Reality Commander, the Windows Device Portal or a Cortana voice command) will be downloaded to the Pictures Library on the PC. Files will be saved to HoloLensCommander\<device address|name>.
+![Device Control Controls](ReadmeImages/DeviceControlControls.png)
 
-##### Delete files after saving
+![Reboot Button](ReadmeImages/RebootButton.png) Reboots the devices selected in the device list. Devices will show “Lost connected to the device” while rebooting and will reactivate upon completion.
 
-Checking this option will result in downloaded Mixed Reality Capture files to be deleted from the device.
+![Shutdown Button](ReadmeImages/ShutdownButton.png) Shuts down the selected devices. Devices remain in the list and will report “Lost connection to the device”.
 
-#### Device controls
-![Device control controls](ReadmeImages/DeviceControlControls.png)
+![Forget Devices Button](ReadmeImages/ForgetDevicesButton.png) Forgets all connected devices by removing them from the devices list and updating the application state.
 
-The device control controls provide options (from left to right) to:
 
-- Reboot the selected devices
-- Shut down the selected devices
-- Forget all connected devices
+#### Device List
 
-Note: All devices will be disconnected and will not be restorable via the Reconnect button.
+When you connect a device (HoloLens or Windows PC) an entry will be created in the device list (right side of the UI).
 
-#### Registered devices list
-The right side of the Windows Mixed Reality Commander interface contains the list of connected devices along with controls to manage device selection. Each entry provides the ability to select/deselect the specific device, view summary information related to the HoloLens (battery level, etc.) as well as access to functionality specific to that device.
+![Device List](ReadmeImages/DeviceList.png)
 
-![Device Selection Controls](ReadmeImages/SelectionControls.png)
+In the previous image, the upper device is a HoloLens and the lower is a Windows PC. You can differentiate, at a glance by the items highlighted in the red and blue boxes.
 
-Summary view for HoloLens.
+The HoloLens supports viewing and setting the interpupillary distance (IPD) and provides controls to view and update the value (red box).
+
+Windows PC devices do not support the IPD controls and have a small icon (blue box) between the additional options button (…) and the address.
+
+
+#### Managing Applications on an Individual Device
+
+There are times when you need to manage applications on a single device. To accomplish this, select the Manage apps from the menu displayed when clicking the additional commands button (…).
+
+![Manage Applications Dialog](ReadmeImages/ManageAppsDialog.png)
+
+![Run Application Button](ReadmeImages/RunAppButton.png) Runs the app selected in the Installed Applications list.
+
+![Uninstall Application Button](ReadmeImages/UninstallAppButton.png) Uninstalls the app selected in the Installed Applications list.
+
+![Stop Application Button](ReadmeImages/CloseAppButton.png) Stops the app selected in the Running Applications list.
+
+![Stop All Applications Button](ReadmeImages/CloseAllAppsButton.png) Stops all apps listed in the Running Applications list.
+
+
+### Using Windows Mixed Reality Commander
+
+Windows Mixed Reality Commander can manage one or more HoloLens and/or Windows PC devices in a classroom or demo setting. The following sections describe common usage patterns for both settings.
+
+#### Customizing for the User
+
+HoloLens is designed for all users. The headband is adjustable to fit different sized heads and the optics are designed to allow for different distances between the eyes (interpupillary distance).
+
+To promote user comfort and hologram clarity, it is recommended to configure the IPD to match the user. There are two convenient methods for setting this value.
+
+##### Directly Setting the IPD
 
 ![HoloLens Summary View](ReadmeImages/HoloLensSummaryView.png)
 
-Summary view for Windows PC
+If the user is already aware of his/her IPD, you can use the edit button to the right of the IPD to set it directly.
 
-![Windows PC Summary View](ReadmeImages/WindowsPCSummaryView.png)
+![IPD Setting Dialog](ReadmeImages/IpdDialog.png)
 
-From right to left, the Summary view contains:
+Clicking Ok will send the desired value to the HoloLens. Within a few seconds, the UI will be updated to reflect the new setting.
 
-- Selection check box
+##### Running Calibration on the HoloLens
 
-Unchecking this box will prevent this device from responding to commands other than those shown by clicking the Additional commands button, EXCEPT for the clear devices button in the Device Control controls.
+If the user is not aware of his/her IPD, you can run the HoloLens Calibration application to have the value measured and set.
 
-- Additional commands button
+There are two ways this can be performed using Windows Mixed Reality Commander:
 
-- Device address and name
+1.	Start and run Calibration on ALL selected devices.
+2.	Run Calibration on a specific device using the Manage apps option for that device.
 
-The address is the IP address of the device on your network. The name is a Windows Mixed Reality Commander only value that is not transmitted to the device.
+While Calibration is running you will see “Waiting for Calibration to exit” in the device control. When complete, the control will display “Calibration has exited”.
 
-- Set Tag button
+#### Controlling Application Lifetime
 
-The button to the right of where the device name is displayed allows you to set the name mentioned previously.
+Controlling application lifetime is a common requirement when running a classroom or demo.  Students and users often are required to spend a finite time in any given experience before moving on to the next task.
+
+Windows Mixed Reality Commander enables application lifetime control by using the Common Applications controls or the Manage Apps option for a specific device.
+
+When an application is running on a device, you will see "Waiting for Application to exit" on the right side of the appropriate device list entry.
+
+![Waiting for Application Exit](ReadmeImages/WaitingForAppExit.png)
+
+When the application has been closed, by the user or via Windows Mixed Reality Commander, the message will change to "Application has exited".
+
+#### Assisting Users
+
+Mixed Reality is a new experience for many users, and they may, at times, get confused with where to look and/or how to interact with your application. To help you help your users, Windows Mixed Reality Commander provides Mixed Reality view.
+
+```
+Note: Mixed Reality View is only available for HoloLens devices.
+```
+
+Mixed Reality view allows you to see what your user is seeing, enabling you to guide and assist him/her.
+
+```
+Note: Windows Mixed Reality Commander supports Mixed Reality view for one HoloLens device at a time.
+```
+
+To turn on Mixed Reality view, click the additional options (…) button for the device and select Mixed Reality view.
+
+![Mixed Reality View](ReadmeImages/MixedRealityViewDialog.png)
+
+This will cause the user to see a red "REC" indication, in the upper left of the Holographic Frame. It is recommended that you tell your user to expect to see this. The indicator will turn off when you close the Mixed Reality view dialog.
+
+#### Keeping Track of Devices
+
+If you are managing multiple devices, it can become challenging to keep track of who is using which device. To make that easier, Windows Mixed Reality Commander allows you to tag the device with a custom name that is not communicated to the device. 
+
+For example, you may have 30 HoloLens devices in your classroom and notice that a student named Mick is having trouble with his assignment. Rather than having to memorize that IP address 10.254.130.7 is Mick's device, you can select the edit button next to the Name field to display the Tag Device dialog.
+
+![Edit Device Tag](ReadmeImages/EditDeviceTag.png)
+
+This will allow you to set a descriptive name for the device.
 
 ![Tag Device Dialog](ReadmeImages/TagDialog.png)
 
-- Battery information and IPD (InterPupilary Distance)
-
-Battery information includes the remaining capacity and an indication as to whether or not the device is plugged in.
-
-- Set IPD button
-
-The button to the right of where the IPD is displayed allows you to set update the IPD value stored on the device.
-
-Note: Setting the IPD is available only on HoloLens devices.
-
-![Set IPD Dialog](ReadmeImages/IpdDialog.png)
-
-- Status message
-
-##### Additonal commands
-##### Device Information
-![Device Information Dialog](ReadmeImages/DeviceInfoDialog.png)
-
-The HoloLens Information dialog displays information about the operating system installed on your device.
-
-Also displayed is the name of the dewvice. This name is not the name from the Tag dialog and is not updated by the Windows Mixed Reality Commander.
-
-##### Manage apps
-![Manage Apps Dialog](ReadmeImages/ManageAppsDialog.png)
-
-The Manage apps dialog displays the installed and running applications on the device. From top to bottom, the available controls are:
-
- - Refresh the list of installed applications
- - Run the selected application
- - Uninstrall the selected application
- - Refresh the list of running applications
- - Close the selected application
- - Close all running applications
-
-##### Mixed Reality view
-![Mixed Reality View Dialog](ReadmeImages/MixedRealityViewDialog.png)
-
-The Mixed Reality view dialog allows the Windows Mixed Reality Commander user to see what the device is seeing. This feed takes a few seconds to initialize and then runs at 15 frames per second (to limit the impact on the wireless network). 
-
-On the device, the user will see a recording indicator in the upper left of the Holographic Frame and the frame rate will be reduced. Although a recording indicator is displayed, no recording is being created.
-
-Note: Mixed Reality View is only availabe for HoloLens devices.
-
-##### Show Device Portal
-
-The Show Device Portal command launches the default web browser and connects to the Windows Device Portal on the device.
-
-##### Disconnect
-
-Disconnects from the device and removes it from the list.
 
 ### Project dependencies
 Windows Mixed Reality Commander depends on:
@@ -204,5 +247,10 @@ The device must be in developer mode with the Windows Device Portal enabled and
 - Windows Device Portal Wrapper
  - https://github.com/Microsoft/WindowsDevicePortalWrapper
 
+
 ### Contributing
 We welcome and encourage contributions to the Windows Mixed Reality Commander project. We look forward to evolving this tool with the community!
+
+
+
+