Skip to content

Commit 20164ae

Browse files
Merge pull request #313 from microsoft/pete-dev
Docs updates and clean up error logging in scheduler
2 parents a6272ba + 9838b04 commit 20164ae

13 files changed

+334
-224
lines changed

build/staging/version/BundleInfo.wxi

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
<Include>
22
<?define SetupVersionName="Developer Preview 6 arm64" ?>
3-
<?define SetupVersionNumber="1.0.24107.1653" ?>
3+
<?define SetupVersionNumber="1.0.24107.2219" ?>
44
</Include>

docs/midi-console.md docs/console/endpoints.md

+13-163
Original file line numberDiff line numberDiff line change
@@ -1,152 +1,10 @@
11
---
22
layout: page
3-
title: MIDI Console
4-
parent: Windows Midi Services
3+
title: Endpoints and Messages
4+
parent: MIDI Console
55
---
66

7-
# Windows MIDI Services Console
8-
9-
If you have the midi console installed, you can invoke it from any command prompt using `midi`. We recommend using [Windows Terminal](https://aka.ms/terminal) for the best experience.
10-
11-
## General Information
12-
13-
### Commands vs Options
14-
15-
MIDI Console commands are words with no symbol prefix. For example `endpoint` or `send-message-file`. Options are prefixed with two dashes if you use the full word, or a single dash if you use the single-letter abbreviation. For example `--help` or `-h`. There is no statement completion built in to the console, but there are some supported abbreviations for commands. These are not yet fully documented but are present in the Program.cs in the console source code.
16-
17-
### "Ports" vs "Streams"
18-
19-
In MIDI 1.0, specifically USB MIDI 1.0, a connected device would have a single input and single output stream. Inside that stream are packets of data with virtual cable numbers. Those numbers (16 total at most) identify the "port" the data is going to. Operating systems would then translate those into input and output ports. Those cable numbers were hidden from users.
20-
21-
MIDI 2.0 does not have a concept of a port. Instead, you always work with the stream itself. The group number, which is in the MIDI message now, is the moral equivalent of that cable number.
22-
23-
So where you may have seen a device with 5 input and 5 output ports in the past, you will now see a **single bidirectional UMP Endpoint stream** with 5 input groups and 5 output groups. We know this can take some getting used to, but it enables us to use MIDI 1.0 devices as though they are MIDI 2.0 devices, and provide a unified API.
24-
25-
### Help
26-
27-
Add the option `--help` or its short version `-h` to any command to get information and examples for that command.
28-
29-
```
30-
midi --help
31-
midi service --help
32-
midi enumerate --help
33-
midi enumerate endpoints --help
34-
```
35-
36-
The `--help` option will always provide the most up-to-date list of commands and options supported by the MIDI Services Console.
37-
38-
## Check the MIDI Service Health
39-
40-
The heart of Windows MIDI Services is the Windows Service which processes and routes messages, creates endpoints, and more. The MIDI Services Console app includes a few commands to check the status and health of the service.
41-
42-
### Check MIDI Service Status
43-
44-
If you want to verify that the MIDI Service is running, you can check its status using the Service Control Manager, or through the MIDI Console.
45-
46-
```
47-
midi service status
48-
midi svc status
49-
```
50-
51-
If you uset the `--verbose` or `-v` option, the console will display more information about the service.
52-
53-
```
54-
midi service status
55-
midi svc status
56-
```
57-
58-
### Ping the Service
59-
60-
If you want to verify that the service is transmitting and receiving messages, you can use the ping command, much like you would
61-
62-
```
63-
midi service ping
64-
midi svc ping
65-
```
66-
67-
This command also supports the `--verbose` or `-v` option to display the full results of the ping. It also supports a `--count` or `-c` parameter for the number of messages you want to send. Finally, the call supports a `--timeout` or `-t` parameter to set the timeout in milliseconds before the ping is considered to have failed.
68-
69-
Here are examples of the command with various parameters.
70-
71-
```
72-
midi service ping --verbose
73-
midi service ping --verbose --count 20 --timeout 20000
74-
```
75-
76-
### Stop / Start / Restart the Service
77-
78-
The MIDI console has three commands for managing the Windows service. These can be useful when developing or debugging service-side plugins. Note that these must be run from an Administrator console session.
79-
80-
```
81-
midi service stop
82-
midi service start
83-
midi service restart
84-
```
85-
86-
## See the Current Timestamp and Frequency
87-
88-
If you want to see the MIDI clock we're using for timestamps and message scheduling, you can use the `time` command. It will display the current timestamp in ticks, and the number of ticks per second (the resolution)
89-
90-
```
91-
midi time
92-
midi clock
93-
```
94-
95-
## Enumerate (List) MIDI Entities
96-
97-
A basic operation you may do with the tool is list the major entities (Endpoints and Plugins) in the system.
98-
99-
The enumerate command has the aliases `enum` and `list` which may be used instead of the full `enumerate` command.
100-
101-
### Enumerate MIDI UMP Endpoints
102-
103-
The `ump-endpoints` parameter has the alias `endpoints` and the alias `ump` so either may be used with the same results. These commands are all equivalent:
104-
105-
```
106-
midi enumerate ump-endpoints
107-
midi enumerate endpoints
108-
midi enum endpoints
109-
midi list endpoints
110-
midi list ump
111-
```
112-
113-
All of the above statements will return a list of all the user-focused UMP endpoints on the system.
114-
115-
> **Note:** There are loopback endpoints A and B that are always available and are built into the service. They are crosswired to each other so that any message sent to A is received on B, and vice versa. They cannot be removed or disabled. Because these are more for support, testing, and developer scenarios, they are not returned from enumeration calls by default. Instead, you would supply the `--include-loopback` option for the enumeration commands.
116-
117-
### Enumerate Classic Byte-stream (MIDI 1.0) Endpoints
118-
119-
This uses the old WinRT API. Its primary reason for existance is so you can see what's shown to older APIs vs what is shown for the new Windows MIDI Services API. As with the UMP endpoints, the commands have aliases, so the following are all equivalent
120-
121-
```
122-
midi enumerate bytestream-endpoints
123-
midi enumerate legacy-endpoints
124-
midi enum legacy-endpoints
125-
midi list legacy
126-
```
127-
128-
### Enumerate Transport Plugins
129-
130-
TODO: This feature is actively in development.
131-
132-
### Enumerate Message Processing Plugins
133-
134-
TODO: This feature is actively in development.
135-
136-
## Watch UMP Endpoints for Changes
137-
138-
Enumerating endpoints gives you a snapshot of the list at a moment in time. Watching the endpoints will give you a constantly updating list, which reflects device add/remove as well as property updates. This is useful more for developers, or those who are using tools to modify endpoints and want to verify that the changes were reported.
139-
140-
The `watch-endpoints` command has the alias `watch`, so these are equivalent:
141-
142-
```
143-
midi watch-endpoints
144-
midi watch
145-
```
146-
147-
Note that only UMP endpoints (or bytestream endpoints converted to UMP by the new USB driver and service) are watched for changes. The older MIDI API is not used here. When you want to stop watching the endpoints for changes, hit the `escape` key.
148-
149-
## Single-Endpoint Commands
7+
# Single-Endpoint Commands
1508

1519
There are a number of commands, including those for monitoring and sending messages, which operate on a single endpoint.
15210

@@ -158,7 +16,7 @@ If you want to script the commands without requiring any user interaction, provi
15816
midi endpoint \\?\SWD#MIDISRV#MIDIU_DIAG_LOOPBACK_B#{e7cce071-3c03-423f-88d3-f1045d02552b} properties --verbose
15917
```
16018

161-
### Get Detailed Endpoint Properties
19+
## Get Detailed Endpoint Properties
16220

16321
In the Device Manager in Windows, you can only see a subset of properties for a device. The same goes with the `pnputil` utility. It can be useful to see all of the key properties of a MIDI Endpoint. Therefore, we've baked property reporting right into the MIDI Services Console.
16422

@@ -174,7 +32,7 @@ midi endpoint properties --verbose
17432

17533
As with other endpoint commands, if you provide the endpoint device Id, it will be used. Otherwise, you will be prompted to select an endpoint.
17634

177-
### Monitor an Endpoint for Incoming Messages
35+
## Monitor an Endpoint for Incoming Messages
17836

17937
By default, every UMP Endpoint in Windows MIDI Services is multi-client. That means that more than one application can open a connection to the endpoint and send and/or receive messages. This also makes it possible to monitor all the incoming messages on an endpoint, even when that endpoint is in use by another application.
18038

@@ -194,7 +52,7 @@ Verbose mode:
19452
midi endpoint monitor --verbose
19553
```
19654

197-
#### Saving messages to a file
55+
### Saving messages to a file
19856

19957
When monitoring, you also have the option to save the messages to a file. This can be used to capture test data which you will send using the `send-message-file` command, or for storing something like a System Exclusive dump.
20058

@@ -211,7 +69,7 @@ If no file extension is specified, the extension `.midi2` will be automatically
21169

21270
When you have completed monitoring an endpoint, hit the `escape` key to close the connection and the app.
21371

214-
### Send a Message from the Command Line
72+
## Send a Message from the Command Line
21573

21674
Sending a message to an endpoint is very helpful for testing, but can also be used in automation to, for example, change the current program, or set a MIDI CC value. It would be very easy for a person to build a batch file or PowerShell script which used midi.exe to synchronize different devices, or reset devices to a known state in preparation for a performance.
21775

@@ -237,7 +95,7 @@ midi endpoint send-message 0x41234567 0xDEADBEEF --count 15 --pause 2000
23795

23896
In general, we recommend sending messages in hexadecimal format (prefix `0x` followed by 8 hexadecimal digits)as it is easier to visually inspect the information being sent. The 1-4 MIDI words are in order from left to right, from 1 to 4.
23997

240-
#### Special debug messages
98+
### Special debug messages
24199

242100
One thing that can be useful is to send otherwise valid UMP messages where the last word is incremented by 1 for each sent message. This helps to validate that all messages were received by your application, and in the correct order. Note that this requires a message type of at least two words. We don't recommend sending Type F stream messages as those have the potential to corrupt data. Instead, a Type 4 MIDI 2.0 channel voice message is usually safer.
243101

@@ -247,9 +105,7 @@ midi endpoint send-message 0x41234567 0x00000000 --count 10000 --pause 2 --debug
247105

248106
When sent, you should see messages where the second word is updated from `0x00000000` through `0x00002710` (decimal 10000). We recommend the pause when sending large numbers of messages because a pause of 0 ("send as fast as possible") can flood the buffers with more data than the client may be able to retrieve in time and may result in dropped messages. A warning is displayed when that possibility seems likely.
249107

250-
#### Scheduling messages
251-
252-
> NOTE: In current Developer Preview builds, message scheduling is turned off so the timestamp is ignored. Refer to the release notes.
108+
### Scheduling messages
253109

254110
When sending messages, you have two options for timestamps:
255111

@@ -271,7 +127,7 @@ Of course, you can also use the `midi time` command to see the current timestamp
271127

272128
Finally, if you do not specify a timestamp, the current time is used.
273129

274-
### Send a File full of Messages
130+
## Send a File full of Messages
275131

276132
If you want to send a file full of messages, for SysEx or testing, for example, the console has provision for this.
277133

@@ -334,7 +190,7 @@ F3345678h 12345678h 86754321h 86753099h
334190
# bunch of empty lines above. And the file ends with a comment
335191
```
336192

337-
### Sending Endpoint Metadata Requests
193+
## Sending Endpoint Metadata Requests
338194

339195
The MIDI Services Console also makes it possible to send some common stream request messages without having to remember their exact format.
340196

@@ -344,7 +200,7 @@ These are primarily a convenience for developers.
344200

345201
Note that in all the request commands, you may abbreviate `request` as `req`
346202

347-
#### Send a Function Block Request Message
203+
### Send a Function Block Request Message
348204

349205
In the command, you may abbreviate `function-blocks` as `fb`, `functions`, `function` or `function-block`. The singular versions are available to make the command make more sense when requesting a single block's data.
350206

@@ -369,7 +225,7 @@ midi endpoint request function-blocks --all --request-name false
369225
midi endpoint request function-blocks --all --request-info false
370226
```
371227

372-
#### Send an Endpoint Information Request Message
228+
### Send an Endpoint Information Request Message
373229

374230
In the command, you may abbreviate `endpoint-metadata` as `em` or `metadata`.
375231

@@ -402,9 +258,3 @@ midi endpoint request endpoint-metadata --stream-configuration
402258
```
403259

404260
Finally, note that you can provide a UMP version to send with the request. By default, the version is Major 1, Minor 1. The `--ump-version-major` and `--ump-version-minor` options are what you want to use here.
405-
406-
## Technical Information
407-
408-
The Windows MIDI Services Console app has been developed using C#, .NET 8, the MIT-licensed open source [Spectre.Console](https://spectreconsole.net/) library, and the Microsoft-developed open source [C#/WinRT](https://learn.microsoft.com/windows/apps/develop/platform/csharp-winrt/) toolkit.
409-
410-
The console uses the same Windows MIDI Services WinRT APIs available to other desktop applications. Its full source code is available [on our Github repo](https://aka.ms/midirepo). Pull-requests, feature requests, and bug reports welcome. The project is open source, but we request that instead of forking it to create your own version, you consider contributing to the project.

docs/console/enum-endpoints.md

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
layout: page
3+
title: Enumerate Endpoints
4+
parent: MIDI Console
5+
---
6+
7+
# Enumerate (List) Endpoints
8+
9+
## Enumerate MIDI UMP Endpoints
10+
11+
The `ump-endpoints` parameter has the alias `endpoints` and the alias `ump` so either may be used with the same results. These commands are all equivalent:
12+
13+
```
14+
midi enumerate ump-endpoints
15+
midi enumerate endpoints
16+
midi enum endpoints
17+
midi list endpoints
18+
midi list ump
19+
```
20+
21+
All of the above statements will return a list of all the user-focused UMP endpoints on the system.
22+
23+
> **Note:** There are loopback endpoints A and B that are always available and are built into the service. They are crosswired to each other so that any message sent to A is received on B, and vice versa. They cannot be removed or disabled. Because these are more for support, testing, and developer scenarios, they are not returned from enumeration calls by default. Instead, you would supply the `--include-loopback` option for the enumeration commands.
24+
25+
## Enumerate Classic Byte-format (MIDI 1.0) Endpoints
26+
27+
This uses the old WinRT API. Its primary reason for existance is so you can see what's shown to older APIs vs what is shown for the new Windows MIDI Services API. As with the UMP endpoints, the commands have aliases, so the following are all equivalent
28+
29+
```
30+
midi enumerate bytestream-endpoints
31+
midi enumerate legacy-endpoints
32+
midi enum legacy-endpoints
33+
midi list legacy
34+
```
35+
36+
## Watch UMP Endpoints for Changes
37+
38+
Enumerating endpoints gives you a snapshot of the list at a moment in time. Watching the endpoints will give you a constantly updating list, which reflects device add/remove as well as property updates. This is useful more for developers, or those who are using tools to modify endpoints and want to verify that the changes were reported.
39+
40+
The `watch-endpoints` command has the alias `watch`, so these are equivalent:
41+
42+
```
43+
midi watch-endpoints
44+
midi watch
45+
```
46+
47+
Note that only UMP endpoints (or bytestream endpoints converted to UMP by the new USB driver and service) are watched for changes. The older MIDI API is not used here. When you want to stop watching the endpoints for changes, hit the `escape` key.
48+

docs/console/enum-plugins.md

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
layout: page
3+
title: Enumerate Plugins
4+
parent: MIDI Console
5+
---
6+
7+
# Enumerate (List) MIDI Service Plugins
8+
9+
The enumerate command has the aliases `enum` and `list` which may be used instead of the full `enumerate` command.
10+
11+
## Enumerate Transport Plugins
12+
13+
This command makes it easy to see which transports are currently enabled in Windows MIDI Services.
14+
15+
```
16+
midi enumerate transport-plugins
17+
```
18+
19+
![Enumerate Transport Plugins](./enum-transports.png)
20+
21+
22+
## Enumerate Message Processing Plugins
23+
24+
TODO: This feature is actively in development.
25+

docs/console/enum-transports.png

139 KB
Loading

0 commit comments

Comments
 (0)