MOD HMI LV2 Extension

http://moddevices.com/ns/hmi — spec version 1.1

Overview

The hmi: extension lets a plugin take part in what a MOD device shows and lights for one of its parameters once the user has addressed that parameter to a hardware control (knob, footswitch, encoder). The host tells the plugin when a parameter is addressed and unaddressed; in between, the plugin may set the label, value, unit and indicator shown for that control, drive its LED, and open a popup.

The extension is a C API with two LV2 identifiers: a host feature and a plugin interface. The reference header is mod-hmi.h (also shipped in mod-host as src/lv2/lv2-hmi.h); the LV2 bundle with the TTL is mod-hmi.lv2.

Availability. mod-host passes hmi:WidgetControl to every plugin on MOD Duo, Duo X and Dwarf. It is not provided by MOD Desktop or by generic LV2 hosts, so a plugin must declare it as lv2:optionalFeature, check for it at instantiation, and work without it. Which calls do anything for a given addressing is reported per addressing in LV2_HMI_AddressingInfo::caps.

Prefixes

@prefix hmi:  <http://moddevices.com/ns/hmi#> .
@prefix lv2:  <http://lv2plug.in/ns/lv2core#> .

Identifiers

URI	Kind	Description
`hmi:WidgetControl`	`lv2:Feature`	Host-provided feature. `LV2_Feature::data` points to an `LV2_HMI_WidgetControl` struct (host handle, struct size, and the widget functions below). Declare with `lv2:optionalFeature hmi:WidgetControl`.
`hmi:PluginNotification`	`lv2:ExtensionData`	Plugin-provided interface returned by `extension_data()` for this URI: an `LV2_HMI_PluginNotification` struct with the `addressed` and `unaddressed` callbacks. Declare with `lv2:extensionData hmi:PluginNotification`.

Plugin interface: `LV2_HMI_PluginNotification`

Callback Description

addressed(handle, index, addressing, info) The user addressed the control port at index to a hardware control. The plugin keeps the opaque addressing handle and passes it to every widget call for this parameter. info (an LV2_HMI_AddressingInfo) is valid only during the call: capabilities, flags, the user's label, the user's min/max (or the port defaults) and the number of steps (201 on the Dwarf, 33 elsewhere, unless the user chose otherwise).

unaddressed(handle, index) The addressing was removed. The plugin must not call any widget function with that addressing handle afterwards.

Callback	Description
`addressed(handle, index, addressing, info)`	The user addressed the control port at `index` to a hardware control. The plugin keeps the opaque `addressing` handle and passes it to every widget call for this parameter. `info` (an `LV2_HMI_AddressingInfo`) is valid only during the call: capabilities, flags, the user's label, the user's min/max (or the port defaults) and the number of steps (201 on the Dwarf, 33 elsewhere, unless the user chose otherwise).
`unaddressed(handle, index)`	The addressing was removed. The plugin must not call any widget function with that addressing handle afterwards.

Addressing capabilities (`caps`)

Bit flags saying which widget functions will do anything for this addressing.

Flag	Enables
`LV2_HMI_AddressingCapability_LED`	`set_led_with_blink`, `set_led_with_brightness`
`LV2_HMI_AddressingCapability_Label`	`set_label`
`LV2_HMI_AddressingCapability_Value`	`set_value`
`LV2_HMI_AddressingCapability_Unit`	`set_unit`
`LV2_HMI_AddressingCapability_Indicator`	`set_indicator`

Addressing flags (`flags`)

Flag	Meaning
`LV2_HMI_AddressingFlag_Coloured`	Parameter is a coloured list. Currently unused.
`LV2_HMI_AddressingFlag_Momentary`	The control acts in momentary mode instead of toggle: press and hold is ON, release is OFF ("momentary-on").
`LV2_HMI_AddressingFlag_Reverse`	With `Momentary`: press and hold is OFF, release is ON ("momentary-off").
`LV2_HMI_AddressingFlag_TapTempo`	Parameter is mapped to tap tempo. Currently unused.

Host feature: `LV2_HMI_WidgetControl`

The struct starts with the host handle and its own size; a plugin must compare size against the constant of a function before calling it, so that newer plugins keep working on older hosts. All functions take the host handle and the addressing handle received in addressed().

Function	Requires	Description
`set_led_with_blink(colour, on_ms, off_ms)`	`SIZE_BASE`	LED colour with optional blink timing in ms (0–5000; 0 = no blink). Plugins should use the `LV2_HMI_LED_Blink` presets (None, Slow, Mid, Fast), passing them as `on_ms`.
`set_led_with_brightness(colour, brightness)`	`SIZE_BASE`	LED colour with brightness 0–100 (0 = off). Plugins should use the `LV2_HMI_LED_Brightness` presets (None, Low, Mid, High = Normal).
`set_label(label)`	`SIZE_BASE`	Text shown as the control's label on the display.
`set_value(value)`	`SIZE_BASE`	Text shown as the control's value.
`set_unit(unit)`	`SIZE_BASE`	Text shown as the control's unit.
`set_indicator(pos)`	`SIZE_BASE`	Position of the control's indicator, normalised 0–1.
`popup_message(style, title, message)`	`SIZE_POPUP_MESSAGE`	Opens a popup on the display with a title and a message; `style` is `LV2_HMI_Popup_Style_Normal` or `_Inverted`. Added after the first revision: check `size >= LV2_HMI_WIDGETCONTROL_SIZE_POPUP_MESSAGE` first.

LED colours are a fixed set: Off, Red, Green, Blue, Cyan, Magenta, Yellow, White (LV2_HMI_LED_Colour).

Declaring it in a plugin TTL

@prefix hmi: <http://moddevices.com/ns/hmi#> .

<http://example.com/plugins/my-looper>
    a lv2:Plugin ;
    lv2:optionalFeature hmi:WidgetControl ;
    lv2:extensionData hmi:PluginNotification ;
    # ...

Versioning of this API

Functions are only ever appended to LV2_HMI_WidgetControl, each with its own LV2_HMI_WIDGETCONTROL_SIZE_* constant, and fields only ever appended to LV2_HMI_AddressingInfo. A plugin built against a newer header runs on an older host as long as it checks size before each call. Proposed additions (such as pixel drawing into the addressed control's display area) go through the same mechanism and are documented here once adopted.