Merge pull request #495 from microsoft/pete-dev

Tons of documentation updates to bring most docs back up to level

build/staging/version/BundleInfo.wxi

@@ -1,4 +1,4 @@
 <Include>
   <?define SetupVersionName="Developer Preview 9 Arm64" ?>
-  <?define SetupVersionNumber="1.0.2-preview-9.250118-2124" ?>
+  <?define SetupVersionNumber="1.0.2-preview-9.250119-1653" ?>
 </Include>

build/staging/version/WindowsMidiServicesVersion.cs

@@ -6,12 +6,12 @@ public static class MidiBuildInformation
 	{
 		public const string Source = "GitHub Preview";
 		public const string Name = "Developer Preview 9";
-		public const string BuildFullVersion = "1.0.2-preview-9.250118-2124";
+		public const string BuildFullVersion = "1.0.2-preview-9.250119-1653";
 		public const string VersionMajor = "1";
 		public const string VersionMinor = "0";
 		public const string VersionRevision = "2";
-		public const string VersionDateNumber = "250118";
-		public const string VersionTimeNumber = "2124";
+		public const string VersionDateNumber = "250119";
+		public const string VersionTimeNumber = "1653";
 	}
 }
 

build/staging/version/WindowsMidiServicesVersion.h

@@ -5,12 +5,12 @@
 
 #define WINDOWS_MIDI_SERVICES_BUILD_SOURCE               L"GitHub Preview"
 #define WINDOWS_MIDI_SERVICES_BUILD_VERSION_NAME         L"Developer Preview 9"
-#define WINDOWS_MIDI_SERVICES_BUILD_VERSION_FULL         L"1.0.2-preview-9.250118-2124"
+#define WINDOWS_MIDI_SERVICES_BUILD_VERSION_FULL         L"1.0.2-preview-9.250119-1653"
 #define WINDOWS_MIDI_SERVICES_BUILD_VERSION_MAJOR        L"1"
 #define WINDOWS_MIDI_SERVICES_BUILD_VERSION_MINOR        L"0"
 #define WINDOWS_MIDI_SERVICES_BUILD_VERSION_REVISION     L"2"
-#define WINDOWS_MIDI_SERVICES_BUILD_VERSION_DATE_NUMBER  L"250118"
-#define WINDOWS_MIDI_SERVICES_BUILD_VERSION_TIME_NUMBER  L"2124"
+#define WINDOWS_MIDI_SERVICES_BUILD_VERSION_DATE_NUMBER  L"250119"
+#define WINDOWS_MIDI_SERVICES_BUILD_VERSION_TIME_NUMBER  L"1653"
 
 #endif
 

docs/data-translation.md

@@ -12,10 +12,21 @@ Internally, the MIDI service moves messages around in the UMP format. This enabl
 
 ## A couple definitions
 
+### MIDI 1.0 (Byte) Data format
 
+This is the byte format (also called "byte stream" due to how it operates over MIDI 1.0 DIN/Serial connections) used by MIDI 1.0. 
 
+### MIDI UMP Data format
 
+This is the Universal MIDI Packet format. Packets are from 1 to 4 32-bit words in length, and are self-contained and atomic. Internally in Windows MIDI Services, all messages are processed and transports in UMP format, and translated to MIDI 1.0 byte data format as needed
 
+### MIDI 1.0 Protocol
+
+The MIDI messages defined in the MIDI 1.0 specifications, with most values between 0-127, and messages containing 1-3 bytes (except System Exclusive). These messages can be transported in the MIDI 1.0 data format, or in the Universal MIDI Packet format.
+
+### MIDI 2.0 Protocol
+
+The MIDI messages defined in the MIDI 2.0 UMP specifications, excluding the MIDI 1.0 protocol messages in UMP format.
 
 ## Translation Scenarios involving data format changes
 
@@ -32,7 +43,9 @@ Windows MIDI Services supports both MIDI 1.0 and MIDI 2.0 devices.
 
 ### Translation between Message type 2 (MIDI 1.0 Channel Voice) and Message type 4 (MIDI 2.0 Channel Voice)
 
-Currently, Windows MIDI Services does not translate messages based on negotiated protocol or Function Block declared protocol. Instead, for native UMP endpoints, applications should send the correct protocol messages (message type 2 for MIDI 1.0-compatible and message type 4 for MIDI 2.0-compatible messages) based upon the information provided by the `MidiEndpointDeviceInformation` class. In addition, for native MIDI 1.0 byte data format endpoints, applications should send the appropriate MIDI 1.0 messages in UMP.
+Currently, Windows MIDI Services does not translate messages based on Function Block declared protocol. Instead, for native UMP endpoints, applications should send the correct protocol messages (message type 2 for MIDI 1.0-compatible and message type 4 for MIDI 2.0-compatible messages) based upon the information provided by the `MidiEndpointDeviceInformation` class. In addition, for native MIDI 1.0 byte data format endpoints, applications should send the appropriate MIDI 1.0 messages in UMP.
+
+Windows MIDI Services will downscale messages as needed based on negotiated protocol. We plan to add upscaling (if an endpoing negotiates MIDI 2 but doesn't support MIDI 1), but that is not in place in the first release.
 
 If a MIDI 1.0 device is connected to the new MIDI 2.0 Class Driver, Windows MIDI Services *will* downscale Message Type 4 to Message Type 2 before sending to the driver. This is because the driver, when working with a MIDI 1.0 device, only handles UMP messages which can be directly translated to MIDI 1.0 data format.
 

docs/developer-how-to/how-to-bootstrap-windows-midi-services.md

@@ -0,0 +1,71 @@
+---
+layout: page
+title: Bootstrap Windows MIDI Services
+parent: Developer How-to
+has_children: false
+---
+
+# How to bootstrap the SDK and Start the Service
+
+TODO: This document is a work-in-progress.
+
+The SDK is a central installation with a bootstrapper COM component. The COM component handles all WinRT activation for Windows MIDI Services without requiring the MIDI types to be included in any type of manifest (for desktop apps). Applications do not deploy anything except their own compiled code.
+
+Individual applications do not deploy the SDK with their binaries. The C# projection in the NuGet package contains everything a C# application needs. For C++, the NuGet package includes a .hpp file with the required implementation.
+
+## Examples
+
+```cpp
+// MTA by default
+winrt::init_apartment();
+
+// this is the initializer in the bootstrapper hpp file
+std::shared_ptr<init::MidiDesktopAppSdkInitializer> initializer = std::make_shared<init::MidiDesktopAppSdkInitializer>();
+
+// you can, of course, use guard macros instead of this check
+if (initializer != nullptr)
+{
+    if (!initializer->InitializeSdkRuntime())
+    {
+        std::cout << "Could not initialize SDK runtime" << std::endl;
+        std::wcout << "Install the latest SDK runtime installer from " << initializer->LatestMidiAppSdkDownloadUrl << std::endl;
+        return 1;
+    }
+
+    if (!initializer->EnsureServiceAvailable())
+    {
+        std::cout << "Could not demand-start the MIDI service" << std::endl;
+        return 1;
+    }
+}
+else
+{
+    // This shouldn't happen, but good to guard
+    std::cout << "Unable to create initializer" << std::endl;
+    return 1;
+}
+```
+
+
+```csharp
+// the initializer implements the Dispose pattern, so will shut down WinRT type redirection when disposed
+using (var initializer = Microsoft.Windows.Devices.Midi2.Initialization.MidiDesktopAppSdkInitializer.Create())
+{
+    // initialize SDK runtime
+    if (!initializer.InitializeSdkRuntime())
+    {
+        Console.WriteLine("Failed to initialize SDK Runtime");
+        return 1;
+    }
+
+    // start the service
+    if (!initializer.EnsureServiceAvailable())
+    {
+        Console.WriteLine("Failed to get service running");
+        return 1;
+    }
+
+    ...
+
+}
+```

docs/endpoints/config-json.md

@@ -74,7 +74,7 @@ Here's an example of a bare-bones file, with sections for three different transp
 
 > NOTE: This section is in flux, as we're changing how devices are identified, and how properties are set.
 
-The basics of this are identical for each transport. We'll use KS (USB) as an example as it has the most complex lookup mechanisms to attempt to identify devices, even when they are moved from port to port.
+Here's how the KS (USB using the new UMP driver) transport works as an example as it has the most complex lookup mechanisms to attempt to identify devices, even when they are moved from USB port to port.
 
 ```json
 "{26FA740D-469C-4D33-BEB1-3885DE7D6DF1}":
@@ -98,7 +98,10 @@ The basics of this are identical for each transport. We'll use KS (USB) as an ex
 },
 ```
 
-Valid properties you can set across all supported endpoints
+> TODO: Include KSA endpoints and their generated group terminal blocks / groups.
+
+
+Valid properties you can set:
 
 | Property | Type | Description |
 | -------- | ---- | ----------- |

docs/endpoints/diagnostic-endpoints.md

@@ -10,7 +10,7 @@ has_children: false
 
 | Property | Value |
 | -------- | ----- |
-| Abstraction Id | `{ac9b5417-3fe0-4e62-960f-034ee4235a1a}` |
+| Transport Id | `{ac9b5417-3fe0-4e62-960f-034ee4235a1a}` |
 | Abbreviation | `DIAG` |
 
 (Note: This transport cannot be disabled and is not listed in the registry. Its activation is hard-coded into the Windows service. Settings for this transport are not read from the configuration file and cannot be changed.)
@@ -50,15 +50,13 @@ If you need the more typical timestamp behavior, you can set up app-to-app MIDI
 
 ### Metadata Capture
 
-The Loopback endpoints capture Endpoint and Function Block metadata just like any other endpoint. Because of this, you can change the name of the endpoint through in-protocol messages. If you do that, simply change it back later using the same type of message.
-
-> Note: We're working to purge the endpoint metadata cache on device reconnection or service restart, which would reset those properties and names. Currently, it persists across service and Windows restarts.
+The Loopback endpoints capture Endpoint and Function Block metadata just like any other endpoint. Because of this, you can change the name of the endpoint through in-protocol messages. If you do that, simply change it back later using the same type of message, or with a service restart.
 
 ## Ping
 
-The ping endpoint is not normally returned through any enumeration. It is for internal use only, and should not be used by any applications. It recognizes only one type of proprietary message.
+The ping endpoint is not normally returned through any enumeration. It is for internal use only, and should not be used by any applications. It recognizes only one type of proprietary message that is not part of the standard MIDI 2.0 UMP Protocol.
 
-Behavior and implementation of the Ping endpoint is subject to change and should not be relied upon by any code outside of the API.
+Behavior and implementation of the Ping endpoint is subject to change and should not be relied upon by any code outside of the SDK.
 
 ## Compatibility
 

docs/endpoints/kernel-streaming-aggregate.md

@@ -10,18 +10,16 @@ has_children: false
 
 | Property | Value |
 | -------- | ----- |
-| Abstraction Id | `TBA` |
+| Transport Id | `{0F273B18-E372-4D95-87AC-C31C3D22E937}` |
 | Abbreviation | `KSA` |
 
 ## Overview
 
-The Kernel Streaming Aggregator transport creates UMP endpoints for MIDI 1.0 devices using MIDI 1.0 byte format devices, like third-party MIDI 1.0 drivers.
-
-> NOTE: This transport may be recombined with the base Kernel Streaming transport in the future
+The Kernel Streaming Aggregator transport creates UMP endpoints for MIDI 1.0 devices using MIDI 1.0 byte format devices, like third-party MIDI 1.0 drivers, and our in-box USB MIDI 1.0 Class Driver.
 
 ## Suggested Uses
 
-Although this transport is primarily recommended for USB devices, it may be used for access to most other existing MIDI 1.0 devices on Windows.
+Although this transport is primarily recommended for USB devices, it may be used for access to most other existing MIDI 1.0 devices on Windows as long as they have a Kernel Streaming driver.
 
 ## Compatibility
 
@@ -33,6 +31,10 @@ The best experience for Windows MIDI Services will be with applications using th
 | WinRT MIDI 1.0 | Yes | Data is translated between UMP and MIDI bytes (MIDI 1.0 data format) as required. |
 | WinMM MIDI 1.0 | Yes | Data is translated between UMP and MIDI bytes (MIDI 1.0 data format) as required. |
 
+## Grouping
+
+When creating MIDI 2.0 / UMP Endpoints, the aggregation happens at the device level. All interfaces and pins under the device are aggregated and presented as a single UMP endpoint.
+
 ## Naming
 
 MIDI 1.0 port names use a new algorithm for naming, compared to what we have had in the past. Specifically, the device interface (the filter) name is the default root of the name. If there is no filter name, then we walk up to the parent device and use that device's name as the root. Next, we query for the pin names, if provided via `iJack`, and append that to the name.
@@ -46,16 +48,18 @@ Endpoints for this transport are not created through the configuration file, but
 ```json
 "endpointTransportPluginSettings":
 {
-    "{26FA740D-469C-4D33-BEB1-3885DE7D6DF1}":
+    "{0F273B18-E372-4D95-87AC-C31C3D22E937}":
     {
         "_comment": "KSA MIDI (USB etc.)",
-        "SWD: \\\\?\\SWD#MIDISRV#MIDIU_KSA_BIDI_6799286025327820155#{e7cce071-3c03-423f-88d3-f1045d02552b}":
+        "SWD: \\\\?\\swd#midisrv#midiu_ksa_6799286025327820155#{e7cce071-3c03-423f-88d3-f1045d02552b}":
         {
 
         }
     }
 }
 ```
 
-## Implementation
+> TODO: Need to add options for the WinMM port numbers and more
+
 
+> If you want to see how Windows sees any given device at the Kernel Streaming interface level, run the SDK tool `midiksinfo`. That will list all KS devices as they are seen before we create MIDI endpoints for them.

docs/endpoints/kernel-streaming.md

@@ -10,7 +10,7 @@ has_children: false
 
 | Property | Value |
 | -------- | ----- |
-| Abstraction Id | `{26FA740D-469C-4D33-BEB1-3885DE7D6DF1}` |
+| Transport Id | `{26FA740D-469C-4D33-BEB1-3885DE7D6DF1}` |
 | Abbreviation | `KS` |
 
 ## Overview
@@ -29,7 +29,7 @@ The best experience for Windows MIDI Services will be with applications using th
 | WinRT MIDI 1.0 | Yes | Data is translated between UMP and MIDI bytes (MIDI 1.0 data format) as required. |
 | WinMM MIDI 1.0 | Yes | Data is translated between UMP and MIDI bytes (MIDI 1.0 data format) as required. |
 
-> When creating endpoints for use by MIDI 1.0 applications which connect to MIDI 2.0 devices, we're limited to using the declared Group Terminal blocks and their associated groups, unless the device is MIDI 2.0 and the function blocks retrieved are marked as static function blocks. 
+> When creating WinMM and WinRT MIDI 1.0 endpoints for applications using the older APIs, we first use the declared Function Blocks. If there are no function blocks, we use the Group Terminal Blocks. If there are no declared group terminal blocks, we currently create 16 input ports and 16 output ports -- 1 for each group in each direction. However, we're likely to change this in the future and require the user to specify if they want more than 1 group in each direction because creating the backwards compatible WinMM ports is costly.
 
 ## Configuration
 
@@ -51,3 +51,7 @@ Endpoints for this transport are not created through the configuration file, but
 }
 ```
 
+> TODO: Need to add options for the WinMM port numbers and more
+
+> If you want to see how Windows sees any given device at the Kernel Streaming interface level, run the SDK tool `midiksinfo`. That will list all KS devices as they are seen before we create MIDI endpoints for them.
+