Introduction

The Universal MIDI Packet (UMP) Format and MIDI 2.0 Protocol introduced Relative Registered Controllers and Relative Assignable Controllers:

Section 7.4.8 of Version 1.1.2 Registered Controller Messages and Assignable Controller Messages directly set the values of the destination properties. With the MIDI 2.0 Protocol’s Relative Registered Controller and Relative Assignable Controller Messages, it is now also possible to make relative increases or decreases to the current values of those same properties. These new messages act upon the same address space as the MIDI 2.0 Protocol’s Registered Controllers and MIDI 2.0 Assignable Controllers, and use the same controller Banks [and Indexes]. However, these Relative controllers cannot be translated to the MIDI 1.0 Protocol. Figure 62 MIDI 2.0 Relative Registered Controller Message Figure 63 MIDI 2.0 Relative Assignable Controller Message Data The data field in the MIDI 2.0 Relative Registered Controller and Relative Assignable Controller messages contains a Two’s Complement value, to provide negative and positive relative control of the destination value.

This article uses the term “Relative Controllers” to mean both Relative Registered Controllers and Relative Assignable Controllers.

However, the specification does not provide implementers details of how the data field values are used. The following article provides a set of generic ways for Relative Controllers’ values to be sent from a variety of different physical rotary devices. The receiver does not need to know how the sender is creating a value (or the type of rotary encoder), and the sender does not need to know how a receiver is converting the sent value into a parameter or action.

This work is important to several upcoming Profile specifications. These Profiles will be the first MA specifications where Relative Controllers are defined.

Relative Controllers: How do they work

Relative Registered Controllers (RRC) are an addition to a matched Registered Controllers(RC); the RRC is matched at the same Bank and Index of a RC and adjusts the same parameter on the Receiver. An RRC does not exist without the matching RC. This relationship is the same for Relative Assignable Controllers (RAC) and Assignable Controllers (AC).

The values sent in a relative controllers are not immediately obvious, and can change depending on the type of physical control that is used. A Profile specification might define specific values that should be sent, where it may suggest different values for different encoders.

Different types Encoders

A Rotary Encoder generally has detents, with most mechanical encoders commonly having 24 detents per 360 degrees.

Like a normal potentiometer, a Rotary potentiometer provides a voltage that is read by an ADC. Unlike a standard potentiometer it rotates a full 360°. Depending on the circuits involved this can have resolutions as high as 1024 steps (or higher) per full revolution. 

Relative Controller Values 

The value of a Relative Controller is a Two’s Complement value ranging from -2,147,483,647 to +2,147,483,647.

To understand what value we should send we must first look to the matched RC/AC. The RC/AC has a value from 0 to 4,294,967,295. For example: The sender doe not know the current value of the RC/AC. The sender sends an Relative Controller to increase the RC/AC value by 10% (sends 429,496,729). As a result:

Receivers New RC/AC Value = Receivers Current RC/AC Value + 429,496,729.

In other words, we need to send the value of 429,496,729 in the Relative Controller to move the RC/AC value by 10%.

Relative Controller Value Formula for Resolution of the Encoder 

If the value being adjusted has a value between 0% and 100%, how many revolutions are required to move from 0% to 100%? An encoder with 24 detents may require a lot more revolutions than a Rotary Potentiometer with 1024 steps.

Step Value = TRUNCATE ( 0xFFFFFFFF /  (steps per revolution * rotations) )

If the Rotary Encoder has 24 detents and it takes 8 revolutions to go from 0%-100% then the formula is:

Step Value = TRUNCATE (0xFFFFFFFF / (24*8))
Step Value = 22,369,621

If the Rotary Potentiometer has 1024 steps and it takes 2 revolutions to go from 0%-100% then the formula is:

Step Value = TRUNCATE (0xFFFFFFFF / (1024*2))
Step Value = 2,097,151

Not Sending Every Step 

Sending an Relative Controller message for every step when the encoder is moving quickly could very quickly flood a connection, especially if the encoder has a high resolution.

Instead the encoder might use a longer service interval between sent messages, with a cumulation of changes during that interval. For example, the sender’s Rotary Potentiometer above moves 30 steps in a single service interval. Then the sender would send 2,097,151 * 30 = 62,914,530 as the value in the Relative Controller.

Fine Grain Control 

Devices often support sending a finer grain control by holding down a button and then sending through a value that is less than the default step value. It is up to the implementation to decide what fraction of the default step value is sent when using a fine grained Relative Controller message.

Receiver should handle the accumulation of values 

Regardless of the value sent, the Receiver of an Relative Controller message should accumulate the values and store them against the local RC/AC value. This avoids situations where receiving a single step value is too small to trigger a change in the parameter value. However, additional step values sent are enough to trigger a change. By using this accumulation method the user does not experience a situation where sending multiple single steps does not move the parameter value.

Step Size vs. Acceleration

Step Size sent is in the domain of the Sender. For example, a Sender might select from 2 values to send: one larger value for each step of the encoder and a smaller value when in Fine Grain mode.

Acceleration is usually in the domain of the Receiver. When the Receiver receives an incoming message, it interprets and implements that change. But if the Receiver receives multiple incoming messages in a short period of time, then the Receiver might implement a larger change for each incoming value.

Bounded Controls vs  Non-Bounded Controls

Some properties have clear boundaries of values (such as Min to Max). Such properties are addressable by a Registered Controller or Assignable Controller. Therefore, it may be useful to address the same property in a relative manner.

Some properties or mechanisms are not clearly bound to a fixed range of values (e.g. Scrubbing through a Timeline) and are not easily addressed by a Registered Controller or Assignable Controller. In such cases, it is not appropriate to define a Relative Controller.

Avoid Recording and Playback of Relative Controllers 

Recording and Playback of Relative Controllers is problematic because they act upon the current value in the Receiver which can be different at a later time.

For Example:
If a Relative Registered Controller addresses the 1′ drawbar to increase its setting by one step, every time the track plays back that drawbar will get louder and louder.

To mitigate against the issue, the recording device should use the Relative Controller value to adjust its known internal RC/AC value.

For Example:
A DAW has a plugin in focus and an Relative Registered Controller is attached to edit the plugin parameter controlled by an RC. As the user moves the encoder then the automation lane records the adjusted RC value of the plugin parameter, not the RRC from the sender.

There may be exceptions to this use case and recording Relative Controllers is not prohibited. Relative Controller may exist in an environment where the value should be recorded and sent back to a device that understands the Relative Controller.

MIDI 2.0 Protocol provides many improvements to musicians to help in the creation of music. One of the stand out features is the increase of resolution of MIDI messages from 128 steps to 4.2 billion steps (and 65 thousand for velocity).

This increase ensures that changes in parameters are far smoother and more analogue in their responsiveness. 

Note: In MIDI specifications we use hex representations because it can be easier to understand for development. For 32 bit values we use 0x00000000 to represent the smallest value, and 0xFFFFFFFF represents the largest value.

However this huge range presents problems to developers on how to display these values to users. A lot of MIDI 1.0 Devices use 0-127 as the value displayed to musicians, and those musicians are used to seeing and understanding those numbers. 

When numbers are much larger it is more difficult to display these numbers to users. For example, is 0x8000000 the halfway point, or is it just 3.1% of the total range of values?*

For more information on converting between different bit sizes and how to handle different resolutions, please see the document MIDI 2.0 Bit Scaling and Resolution.

How to Display Such Large Numbers to a User?

Where possible, the MIDI Association recommends that developers undertake these options in this order:

1. Provide the Interpreted Value to the Musician.

The MIDI Association is working hard to provide ways for MIDI Devices to declare meaningful units and values. For example Profiles and Property Exchange contain methods that declare how a MIDI message value could be represented as a human readable value. 

For example, Using the Default Control Change Mapping Profile to understand that Control Change #7 defines the representation of the volume in decibels from -infinity to +0db is more informative than 0x00000000 to 0xFFFFFFFF.

2. Display 0% – 100%

When a unit and value is unknown it is often acceptable to use percent values [0% .. 100%], or to use [-100% .. 100%] for bipolar values if applicable.

As a developer you may decide how many decimal places are best suited for your display.

3. Display 0.00 – 1.00

Similarly to the previous option, when a unit and value is unknown it is often acceptable to use floating point [0.0 .. 1.0], or to use [-1.0 to 1.0] for bipolar values, if applicable. This is more inline with the internal values used in plugins.

As a developer you may decide how many decimal places are best suited for your display.

4. Display 0 – 127 with decimal places

If the previous options do not suit and you must display MIDI 1.0 like values, or if you need to display values where the MIDI device is working in both MIDI 1.0 and MIDI 2.0 Protocol environments; then the 32 bit value should be treated as 7.25 fixed point values.

This means the value being visualized starts at 0 and approaches (but not reaches) 128.

In doing this the precise center value (0x80000000) is maintained and translation between MIDI 2.0 and MIDI 1.0 Protocol results in the expected value being sent to MIDI 1.0 devices.

In order to visualize the absolute minimum value (0x00000000), the absolute maximum value (0xFFFFFFFF) and the precise center value (0x80000000) one should use symbolic values “MIN”, “MAX”  and “MID”.
This ensures that these special values can be differentiated from values being very close to them (0.00000001 rounded to e.g. 0.000, 63.9999999 rounded to e.g. 64.0, 127.9999998 rounded to e.g. 127.999).

C++ Example of a function to display these values:

template <typename T>
std::string hirezRepresentationString(T value, uint32_t decimalPlaces)
{
   constexpr int numBits = sizeof(T) * 8;
   constexpr int fractionalBits = numBits - 7; 
   constexpr T maxVal = std::numeric_limits<T>::max();
   constexpr T midVal = (1 << (numBits - 1));


   if (value == 0) {
       return "MIN";
   }


   if (value == midVal) {
       return "MID";
   }


   if (value == maxVal) {
       return "MAX";
   }


   const auto hiRezValue = static_cast<double>(value) / static_cast<double>(1 << fractionalBits);
   const auto formatString = std::format("{{:.{}f}}", decimalPlaces);
   return std::vformat(formatString, std::make_format_args(hiRezValue));
}

Note that this code works up to 6 decimal places. However, this is more than enough for most applications.

* It’s 3.1% for those playing at home 🙂

Developer Design Options for Devices based on MIDI-CI v1.2

by Andrew Mee and Mike Kent

MIDI-CI defines how a device can use a bidirectional connection to discover details of another device. In some cases a device might be connected to more than 1 other device which also uses MIDI-CI. 

This article discusses device design strategies for handling MIDI-CI functions when the current connections are more than one to one. For this purpose we present two terms which are not defined by MIDI-CI but used only to explain design strategies in this article.

• Session: A binding between 2 devices created by ongoing communication of MIDI-CI Transactions. Generally established while using a Profile, a PE Resource, or a Process Inquiry.
• MIDI-CI Instance: Inside a MIDI device, a set of information stored about another connected MIDI-CI device, with the MUID of the connected device as the core property.

A Session often requires a MIDI-CI Instance in the Initiator and sometimes in the Responder.

MIDI-CI defines that a Transaction is an inquiry sent by one MIDI Device and a reply returned by a second MIDI Device. Single Transactions do not establish any kind of Session. Therefore, and in most cases, the following Transactions do not require a MIDI-CI Instance in a device.

• Discovery
• Profile Inquiry
• Inquiry: Property Exchange Capability
• Inquiry: Process Inquiry Capability

Some MIDI-CI mechanisms rely on an ongoing set of Transactions. These mechanisms probably require a device to consider those mechanisms as establishing a kind of Session between two devices. One or both devices might require an internal MIDI-CI Instance. Such mechanisms are:

• When 2 Devices agree to use Process Inquiry, the Initiator usually creates a MIDI-CI Instance. The Responder may not need a MIDI-CI Instance.
• When two Devices agree to use a Profile, the Initiator usually creates a MIDI-CI Instance. The Responder may not need a MIDI-CI Instance.
• When 2 Devices agree to use a Property Exchange Resource, the Initiator usually creates a MIDI-CI Instance. The Responder usually only needs a MIDI-CI Instance if it agrees to serve subscriptions.

Do Not Create a MIDI-CI Instance Unless Necessary

Note: Devices should send the associated reply to these inquiries, even if the Device cannot create a new MIDI-CI Instance:

• Discovery -> Reply to Discovery
• Profile Inquiry -> Reply to Profile Inquiry
• Inquiry: Property Exchange Capabilities -> Reply to Property Exchange Capabilities
• Inquiry: Process Inquiry Capabilities -> Reply to Process Inquiry Capabilities
• Inability to create a new MIDI-CI Instance should not cause sending a NAK.  (There may be other reasons to reply with a NAK.)

Sending a reply to these inquiries only requires the Responder to store information about the inquiry, including the MUID address of the Initiator, until the Responder has sent a reply.

Example Implementation Scenarios for Devices with Limited Resources

Some devices have limitations of memory and processing power. Typically, hardware devices have more limitations than software applications running on a computer. Following are 2 examples of potential issues, each with several proposed solutions.
Some of the solutions provided are for normal MIDI-CI mechanisms, but some are provided to deal with error cases such as a device which becomes disconnected without sending an Invalidate MUID message.

Example 1: Responder Device Restricted to Supporting Single MUID

In this example, a limited hardware device which acts only as a Responder is connected to a computer with the potential for multiple MIDI-CI Initiators. The Responder only has enough memory to store a single MIDI-CI Instance.

There are potential issues which could occur:

• If the Responder creates a MIDI-CI Instance for the first Initiator which requests a connection, that could “lock” the Responder against other MIDI-CI Instances. The Responder might NAK other Initiators. The Responder may not be able to determine that a different Initiator is preferred.
• If an Initiator “goes away” without sending invalidate MUID, Responder is unable to see that Initiator no longer exists. i.e. no clean-up
• Responder has limited methods to verify Initiator still exists.

Responder Solution 1: Device Does Not Create a MIDI-CI Instance to Store Initiator MUID/Info

A simple MIDI-CI Device (with restricted memory), acting as a Responder, probably does not need to store the Initiator MUID and associated information. Instead, Responder might:

• Respond to request from the Initiator using the Source MUID from the request as the Destination MUID in the reply. Then forget the MUID of Initiator.
• Only Send out Notifications using the Broadcast MUID. e.g. Profile Enable Message.

Responders using this method do not need to track active status of Initiators. No MIDI-CI Instance has been created so no “clean-up” needed.

Note: This solution is not applicable in a few cases (because in these cases the Responder probably needs to create a MIDI-CI Instance):

• The Responder wants to accept Property Exchange Subscriptions requests.
• An active Profile requires the Responder to send notifications to an Initiator using a non-Broadcast address.
• The Responder is expected to make a Profile Details Inquiry of the Initiator more than once after a Profile is enabled.
• More than 512 bytes of Sysex data is needed to be sent on any given MIDI-CI message.

However, many Responders will work well without any of the mechanisms listed above.

Responder Solution 2: Device Only Stores Minimal Initiator Information When Absolutely Needed

Responder should only store the data which is absolutely needed for each MIDI-CI Instance.
There is a lot of data provided in MIDI-CI messages, much can be “thrown away”. Some examples of data which might not need to be stored:

• Manufacturer, Family, Model Id’s, and Version are often not needed. 
• Devices that are only working with Profiles do not need to store PE data.
• Max Sysex only important if you are going to use messages greater than 512 bytes

A clean-up mechanism to remove inactive MIDI-CI Instances should be considered when this solution is used.

Example Device: The MIDI Association developed a prototype to test and demonstrate Property Exchange. The device has a total memory of only 96Kb.
The device only creates a MIDI-CI Instance when a Subscription is requested. When a change occurs, the device looks through the list of MIDI-CI Instances to find current subscription(s), and sends out the Property Exchange Subscription notification.
If Property Exchange Subscription Notification is sent and no Reply to Subscription Message is received, a clean-up process is initiated for that MIDI-CI Instance.

This method keeps memory use to a minimum. This prototype can manage 25 unique Subscriptions in fixed memory, using less than 256 bytes.

Responder Methods of “Clean-up”:

• Do Not Create MIDI-CI Instance – no need for clean-up (suitable for many devices but not in all situations, see Responder Solution 1)
• Use MIDI-CI Messages sent directly to Initiator (not Broadcast) and check for Reply. If there is no reply then it can be considered inactive and removed from memory.
• Resend Discovery. If an existing Initiator does not respond it can be considered inactive and removed from memory.
• Receive Invalidate MUID message containing Initiator MUID.

Example 2: Initiator Device Discovers many Responders available for Communication

In this example, a limited hardware device which acts as an Initiator is connected to a computer with the potential for multiple MIDI-CI Responders. The Initiator has limited memory for MIDI-CI Instances.

There are potential issues which could occur after the Discovery Transaction:

• The Responder may already have a MIDI-CI Instance for another Initiator (this may include inactive Initiators) and may NAK a new Session. 
• The Initiator may have “choice paralysis”, as such the Initiator may have difficulty automatically deciding which Initiator  is best for the user.
• The Initiator may be unaware if a Responder disappears in the future.

Solution: Initiator and Responder Implementations

Responder

• Should support multiple Initiators. As Responder is on a computer, memory for multiple MIDI-CI Instances is not an issue.

Initiator

• Offer a choice to the user for selecting which Responder to communicate with.
• Use Clean-up methods (below) to remove inactive Responders.

Initiator Methods of “Clean-up”:

• If the device receives an Invalidate MUID message containing Responder MUID, then remove the MIDI-CI Instance.
• Resend Discovery to confirm that the Responder is still active. If a prior existing Responder no longer replies, the Responder can be considered inactive and removed from memory.
• A Session and MIDI-CI Instance are usually needed to work with a Responder for one of 3 “P”s: Profile Configuration, Property Exchange, or Process Inquiry. Send a Profile Inquiry, PE Capabilities, or Process Inquiry Capabilities message periodically as a “Ping” to confirm that the Responder is still active.

Note: There is usually no need to create a MIDI-CI Instance for any device which does not support one of the 3 “P”s.