8.1 USB service port and parameter interface (CTRL-USB)

CTRL-USB is an optional feature in two roles: a CTRL-USB device, a module, supply, converter, bus board, or enclosure whose settings are seen and changed through a CTRL-USB port behind its panel; and a case host, a module or a bus board that connects to those ports and edits them. The leads between them are cables of the feature; a claim file gives the role. The port is a USB 2.0 device; its parameters follow the MIDI 2.0 standards of the MIDI Association and AMEI, so any conforming host, and any MIDI 2.0 software on a computer, can list and set them without knowing the product. EIS adds what those standards leave open: the connector, the read-back of current values, and an optional description of units. The figures are in data/ctrl_usb.json; the units schema is data/ctrl-units-v1.schema.json.

EIS · CTRL-USB: a case host, its ports, and the USB-PH4 port behind each product case host computer 8.2 bridge 1 2 3 4 5 6 7 each port ≤ 500 mA, switched module USB-PH4 module USB-PH4 supply USB-PH4 lead ≤ 300 mm, D+ / D− twisted 1 VBUS 2 D− 3 D+ 4 0 V USB-PH4 from the mating side, 2.0 mm pitch VBUS ≤ 100 mA drawn, never driven marked USB; survives 5.25 V or 0 V on any pin A USB 2.0 full-speed device on USB-PH4 (USB-001), marked and robust (USB-002), drawing ≤ 100 mA from VBUS (USB-003); a straight lead (USB-004). The host limits and switches each port (USB-013) and numbers it (USB-014).

The port

A CTRL-USB device shall have a USB 2.0 full-speed device port on a USB-PH4 connector with the pin functions tabulated below (USB-001). The port shall be marked USB beside it and shall withstand 5.25 V or 0 V on any of its pins without damage (USB-002): a lead made for another purpose with the same housing can be fitted to it. A product shall draw no more than 100 mA from VBUS at its CTRL-USB port and shall not drive VBUS (USB-003). In a row it runs from its power entries (6.1); VBUS may power it on a bench.

Variant Header (reference) Mating housing (reference) Rated per circuit (A)
USB-PH4 JST B4B-PH-K-S (top entry) or S4B-PH-K-S (side entry) JST PHR-4 with SPH-002T-P0.5S crimp terminals 2

USB-PH4 pins

Pin Function
1 VBUS
2 D−
3 D+
4 0 V (GND)
Figure Value
Signalling USB 2.0 full speed, 12 Mbit/s
VBUS drawn by a device at most 100 mA; never driven
Withstood on any pin 5.25 V or 0 V
Lead at most 300 mm, D+ and D− twisted, at least 28 AWG
Case host port current limit at most 500 mA, switched per port

A CTRL-USB lead shall connect each pin to the same pin at both ends, be no longer than 300 mm, and twist the D+ and D− conductors as a pair (USB-004). The CTRL-USB lead joins the 0 V of the two products it connects, like a patch cable (6.3).

Identity

A CTRL-USB device's iProduct string shall be the product name its claim gives, and its iSerial string shall be unique to the unit and the same at every enumeration (USB-005). A host tells two units of one product apart by iSerial, and finds a unit again after it moves to another port. Products of one maker may share a USB product ID; iProduct names the product.

A CTRL-USB device shall use its maker's own System Exclusive manufacturer ID in MIDI-CI, never the non-commercial ID 7D (USB-006). A manufacturer ID is a paid, one-time registration with the MIDI Association; it is the one cost this feature puts on a maker.

Parameter interface

A CTRL-USB device shall present a USB-MIDI 2.0 function with alternate setting 1 carrying one Universal MIDI Packet endpoint pair, and alternate setting 0 carrying USB-MIDI 1.0 (USB-007). It shall answer MIDI-CI discovery and Property Exchange with the resources ResourceList, DeviceInfo, and AllCtrlList, and CtrlMapList when any control is a toggle or a list (USB-008). Each AllCtrlList entry shall give a CtrlMapList for a toggle or a list and a stepCount for a control that moves in steps, and shall be set by a 32-bit Control Change, RPN, or NRPN message (USB-009).

EIS · CTRL-USB: what a case host asks a device, from enumeration to edited values enumerate iProduct, iSerial USB-005 USB-MIDI 2.0 alt 1, UMP endpoints USB-007 MIDI-CI discovery; the maker's own ID USB-006 PE resources ResourceList, DeviceInfo, AllCtrlList, CtrlMapList USB-008 units JSONSchema ctrl-units-v1 USB-012 subscribe AllCtrlList: every value, then changes USB-010 edit 32-bit CC, RPN, NRPN USB-009 park and reopen: subscribe again The host knows no product: it lists and sets controls with these standard steps alone (USB-015). Units are optional; without them it shows a percentage, the step, or the map's titles. A device keeps working when parked (USB-011) and the host subscribes again when it reopens it (USB-016).

The standards give a host no way to read a control's current value. On a Property Exchange subscription to AllCtrlList, a CTRL-USB device shall send the current value of every control whose transmit is not false as its controller message, and send it again whenever it changes (USB-010). A CTRL-USB device shall keep working when a host closes its MIDI endpoints and opens them again (USB-011); a host with few endpoints parks the devices it is not showing.

Units

A control's 32-bit value says nothing of its engineering units. A device that gives an x-units object on a controller entry shall serve the ctrl-units-v1 schema as the JSONSchema resource with resId ctrl-units-v1 and follow it (USB-012): the engineering values at the two ends of the entry's range, mapped linearly, with a unit, decimals, a fine and a coarse step, and the origin of a bipolar bar.

Field Meaning
min required Engineering value at minMax[0]
max required Engineering value at minMax[1]
unit optional Shown after the value: an SI symbol (ns, kHz, ms, V), %, °, or a short word
decimals optional
step optional Fine step in engineering units; values are rounded to it. Default 10^-decimals
coarse optional Normal (coarse) step; default = step
zero optional Bar origin for bipolar controls; default 0 when min < 0 < max, else min

Mapping: v = min + (raw − minMax[0]) / (minMax[1] − minMax[0]) × (max − min); a value outside minMax is clamped.

EIS recommends x-units on every continuous control: "+2000 ns" tells the user more than "53.1 %". A host that finds no ctrl-units-v1 resource ignores every x-units the device sends and shows the standard fields.

Case host

A case host is a module or a bus board in the host role: it claims module (CTRL-USB-HOST) or bus board (CTRL-USB-HOST), meets every requirement of its own role, and these as well. A case host shall give each downstream port its own current limit of at most 500 mA and a switch that power-cycles that port alone (USB-013), and shall mark each downstream port with the number it shows for that port (USB-014). It shall find and edit the controls of any CTRL-USB device with the interfaces of this clause alone, showing a control without x-units by its standard fields: a percentage of its range, its step, or its map's titles (USB-015). A case host that closes a device's endpoints shall subscribe to AllCtrlList again when it opens them (USB-016).

A case host that offers a computer a link to the products behind it, for their consoles or their firmware, shall implement the host bridge protocol of 8.2 (USB-017). The products' own console commands and firmware formats stay their makers'.

tools/pe_check.py checks a device's Property Exchange resources, saved as JSON, against USB-008, USB-009, and USB-012; data/examples/pe-video-reference-generator.json is a worked example.