MMC REQ-F-MMC-007: Procedures, Events, And Groups

by Alex Johnson 50 views

In the realm of MIDI Machine Control (MMC), the ability to automate tasks and synchronize devices is crucial for efficient and complex workflows. Requirement REQ-F-MMC-007 focuses on implementing procedures, events, and groups, which are fundamental building blocks for advanced automation. This article delves into the intricacies of this requirement, exploring its technical specifications, acceptance criteria, and practical applications. Let's explore the depths of these features and discover how they enhance the capabilities of MIDI devices.

Understanding the Core Concepts

Before diving into the technical details, it's essential to grasp the core concepts behind procedures, events, and groups. These features, as defined in RP-013 v1.0, empower users to create sophisticated automation workflows by enabling command sequences, time-triggered actions, and batch device control. Understanding these concepts will provide a solid foundation for comprehending the technical specifications and implementation details.

Procedures: Command Sequences

Procedures are essentially pre-defined command sequences stored within a device's memory. Think of them as macros or scripts that can be executed with a single command. This allows users to chain together multiple MMC commands, creating complex actions that can be triggered at will. For example, a procedure could consist of a sequence of commands to locate a specific point in a recording, set the playback speed, and then start playback. The reusability of procedures makes them incredibly valuable for streamlining repetitive tasks and ensuring consistent execution of command sequences.

The implementation of procedures involves several key sub-commands, each serving a specific purpose:

  • [ASSEMBLE]: This sub-command is used to define a new procedure. It involves specifying a procedure name, which acts as an identifier, and the command string, which contains the sequence of MMC commands to be executed. The device validates the command string during assembly to ensure that it contains valid MMC commands. This pre-checking mechanism helps prevent errors during execution.
  • [EXECUTE]: This sub-command triggers the execution of a previously assembled procedure. The device retrieves the command string associated with the specified procedure name and executes the commands as if they were received directly from the controller. This allows users to initiate complex actions with a simple command.
  • [SET]: This sub-command sets the current procedure for readback. It's used in conjunction with the PROCEDURE RESPONSE command to retrieve the definition of a procedure. This is useful for verifying the contents of a procedure or for transferring procedures between devices.

Events: Time-Based Command Triggering

Events introduce the element of time into the automation equation. They are time-triggered commands that execute when a specific time condition is met. This enables users to create actions that occur automatically at pre-determined points in time. For example, an event could be set to stop playback at a specific timecode or to trigger a recording at a particular measure in a song. The ability to trigger actions based on time opens up a wide range of possibilities for automated workflows.

The EVENT command offers several sub-commands for managing time-triggered actions:

  • [DEFINE]: This sub-command is used to create a new event. It involves specifying an event name, flags that control the event's behavior, a trigger source (e.g., timecode), a target time, and the command to be executed when the event is triggered. The flags allow for fine-grained control over the event's behavior, such as whether it should be deleted after triggering or whether it should only trigger during forward playback.
  • [ENABLE]: This sub-command activates a previously defined event, allowing it to trigger when its time condition is met.
  • [DISABLE]: This sub-command deactivates an event, preventing it from triggering even if its time condition is met.
  • [SET]: Similar to the PROCEDURE [SET] sub-command, this sets the current event for readback, allowing its definition to be retrieved using the EVENT RESPONSE command.

Groups: Device Grouping

Groups provide a mechanism for controlling multiple devices simultaneously. By assigning devices to a group, commands can be sent to the group address, and all devices in the group will execute the command. This simplifies the process of synchronizing actions across multiple devices, such as starting recording on several machines at the same time. Groups are essential for creating cohesive and synchronized workflows in multi-device setups.

The GROUP command includes the following sub-commands:

  • [ASSIGN]: This sub-command adds devices to a group. It involves specifying a group name and a list of device IDs to be included in the group. Once devices are assigned to a group, they will respond to commands sent to the group address.
  • [UNASSIGN]: This sub-command removes devices from a group. It involves specifying a group name and a list of device IDs to be removed from the group. This allows for dynamic modification of group membership as needed.
  • [SET]: This sub-command sets the current group for readback, allowing its membership to be retrieved using a dedicated response command.

Technical Specifications

The technical specifications for implementing procedures, events, and groups are detailed in RP-013 v1.0. These specifications outline the command formats, data structures, and error handling mechanisms required for proper implementation. Understanding these technical details is crucial for developers and engineers working on MIDI devices and software.

Procedure Command Formats

The PROCEDURE command uses a system exclusive (SysEx) message format, which allows for the transmission of variable-length data. The general format for a PROCEDURE command is as follows:

F0 7F <device_ID> 06 50 <sub-command> <data> F7

Where:

  • F0 is the SysEx start byte.
  • 7F is the non-real-time universal SysEx ID.
  • <device_ID> is the ID of the device receiving the command.
  • 06 is the sub-ID #1 for MMC commands.
  • 50 is the main command for PROCEDURE.
  • <sub-command> specifies the specific procedure sub-command (e.g., [ASSEMBLE], [EXECUTE], [SET]).
  • <data> contains the data specific to the sub-command, such as the procedure name and command string.
  • F7 is the SysEx end byte.

Each sub-command has its own specific data format. For example, the [ASSEMBLE] sub-command format is:

<count> 50h 00h <procedure_name> <command_string>

Where:

  • <count> is the number of bytes following this byte until the end of the SysEx message.
  • 50h 00h identifies the command as PROCEDURE [ASSEMBLE].
  • <procedure_name> is a 1-byte identifier for the procedure (00h-7Eh).
  • <command_string> is a sequence of MMC command bytes.

The [EXECUTE] sub-command has a simpler format:

<count> 50h 01h <procedure_name>

Where:

  • <count> is the number of bytes following this byte until the end of the SysEx message.
  • 50h 01h identifies the command as PROCEDURE [EXECUTE].
  • <procedure_name> is the 1-byte identifier of the procedure to execute.

Event Command Formats

The EVENT command also uses a SysEx message format, similar to the PROCEDURE command:

F0 7F <device_ID> 06 51 <sub-command> <data> F7

Where:

  • F0, 7F, <device_ID>, 06, and F7 have the same meaning as in the PROCEDURE command.
  • 51 is the main command for EVENT.
  • <sub-command> specifies the specific event sub-command (e.g., [DEFINE], [ENABLE], [DISABLE], [SET]).
  • <data> contains the data specific to the sub-command.

The [DEFINE] sub-command has a more complex format due to the various parameters involved:

<count> 51h 00h <event_name> <flags> <trigger_source> <time> <command>

Where:

  • <count> is the number of bytes following this byte until the end of the SysEx message.
  • 51h 00h identifies the command as EVENT [DEFINE].
  • <event_name> is a 1-byte identifier for the event (00h-7Eh).
  • <flags> is a 1-byte value controlling event behavior (e.g., delete after trigger, enable/disable).
  • <trigger_source> is a 1-byte identifier for the time source (e.g., selected timecode).
  • <time> is a 5-byte standard timecode value.
  • <command> is the MMC command to execute when the event triggers.

The [ENABLE] and [DISABLE] sub-commands have simpler formats:

<count> 51h 01h <event_name>  (ENABLE)
<count> 51h 02h <event_name>  (DISABLE)

Where:

  • <count> is the number of bytes following this byte until the end of the SysEx message.
  • 51h 01h and 51h 02h identify the commands as EVENT [ENABLE] and [DISABLE], respectively.
  • <event_name> is the 1-byte identifier of the event.

Group Command Formats

The GROUP command also utilizes the SysEx message format:

F0 7F <device_ID> 06 52 <sub-command> <data> F7

Where:

  • F0, 7F, <device_ID>, 06, and F7 have the same meaning as in the PROCEDURE and EVENT commands.
  • 52 is the main command for GROUP.
  • <sub-command> specifies the specific group sub-command (e.g., [ASSIGN], [UNASSIGN], [SET]).
  • <data> contains the data specific to the sub-command.

The [ASSIGN] sub-command format is:

<count> 52h 00h <group_name> <device_ID1> [<device_ID2>] ...

Where:

  • <count> is the number of bytes following this byte until the end of the SysEx message.
  • 52h 00h identifies the command as GROUP [ASSIGN].
  • <group_name> is a 1-byte identifier for the group (70h-7Eh).
  • <device_IDn> is one or more 1-byte device IDs to be added to the group.

The [UNASSIGN] sub-command has a similar format:

<count> 52h 01h <group_name> <device_ID1> [<device_ID2>] ...

Where:

  • <count> is the number of bytes following this byte until the end of the SysEx message.
  • 52h 01h identifies the command as GROUP [UNASSIGN].
  • <group_name> is the 1-byte identifier of the group.
  • <device_IDn> is one or more 1-byte device IDs to be removed from the group.

Error Handling

Proper error handling is crucial for robust implementation of procedures, events, and groups. RP-013 v1.0 defines several operational errors that should be generated in specific situations. These errors provide valuable feedback to the controller, allowing it to respond appropriately to unexpected conditions.

Some common operational errors include:

  • Undefined procedure (21h): Generated when attempting to execute a procedure that has not been defined.
  • Undefined event (22h): Generated when attempting to enable, disable, or set an event that has not been defined.
  • Undefined group (20h): Generated when attempting to unassign devices from or set a group that has not been defined.
  • Procedure buffer overflow (23h): Generated when attempting to assemble a procedure when the device's procedure memory is full.
  • Event buffer overflow (24h): Generated when attempting to define an event when the device's event memory is full.
  • Group buffer overflow (25h): Generated when attempting to assign devices to a group when the device's group memory is full.
  • Nested/recursive procedure (60h): Generated when a procedure attempts to execute itself recursively.

Acceptance Criteria

The acceptance criteria for REQ-F-MMC-007 provide a set of test scenarios that define the expected behavior of the implemented features. These scenarios cover various aspects of procedures, events, and groups, ensuring that they function correctly and meet the requirements of RP-013 v1.0. Each scenario is written in Gherkin syntax, a human-readable format that makes it easy to understand the test conditions and expected outcomes.

Here are a few examples of the acceptance criteria scenarios:

  • Scenario: ASSEMBLE procedure with multiple commands
    • Given device with empty procedure memory
    • When Controller transmits "F0 7F 01 06 50 06 00 05 44 02 00 08 02 F7"
    • Then device shall parse PROCEDURE [ASSEMBLE] sub-command
    • And shall store procedure_name 05h "MyLoop"
    • And shall store command_string: 44 02 00 08 (LOCATE GPO) + 02 (PLAY)
    • And procedure persists until MMC RESET or power cycle
  • Scenario: EXECUTE assembled procedure
    • Given procedure "MyLoop" (05h) defined as LOCATE GPO + PLAY
    • And GPO contains 01:00:00:00.00
    • When Controller transmits "F0 7F 01 06 50 02 01 05 F7"
    • Then device shall retrieve procedure 05h
    • And shall execute LOCATE [I/F] to GPO (move to 01:00:00:00.00)
    • And shall execute PLAY (enter playback mode)
  • Scenario: DEFINE event with time trigger
    • Given device supports EVENT command
    • When Controller transmits "F0 7F 01 06 51 0C 00 0A C0 01 60 1E 00 00 00 01 F7"
    • Then device shall parse EVENT [DEFINE] sub-command
    • And shall store event_name 0Ah "AutoStop"
    • And flags C0h: d=1 (delete after), e=1 (enabled), f=0, r=0 (bidirectional), p=0 (any speed)
    • And trigger_source = 01h (SELECTED TIME CODE)
    • And time = 01:30:00:00.00
    • And command = 01h (STOP)

The acceptance criteria cover a wide range of scenarios, including:

  • Assembling, executing, and setting procedures
  • Defining, enabling, and disabling events
  • Event triggering based on time and flags
  • Assigning and unassigning devices to groups
  • Group command distribution
  • Error handling (e.g., undefined procedure, buffer overflow)
  • Recursive procedure detection
  • MMC RESET clearing automation state

Practical Applications and Automation Workflows

The true power of procedures, events, and groups lies in their ability to create complex automation workflows. By combining these features, users can achieve a high degree of control over their MIDI devices and streamline their workflows.

Here are a few examples of practical applications:

  • Timed Auto-Stop: An event can be defined to automatically stop playback at a specific timecode, preventing the recording from running beyond the desired point. This is useful for ensuring that recordings don't accidentally capture unwanted material.
  • Looping Playback: A procedure can be created to locate to a loop start point and start playback. An event can then be defined to trigger this procedure when the playback reaches the loop end point, creating a seamless looping effect. This is useful for practicing sections of a song or for creating rhythmic patterns.
  • Synchronized Multi-Device Recording: Devices can be assigned to a group, allowing a single command to start recording on all devices simultaneously. This is essential for capturing synchronized performances across multiple machines.

These are just a few examples of the many possibilities offered by procedures, events, and groups. By understanding these features and their capabilities, users can unlock a new level of control and efficiency in their MIDI workflows.

Conclusion

REQ-F-MMC-007 is a critical requirement for implementing advanced automation features in MIDI devices. By implementing procedures, events, and groups according to the specifications in RP-013 v1.0, devices can offer powerful tools for creating complex workflows and synchronizing actions across multiple devices. The acceptance criteria provide a comprehensive set of tests to ensure that these features function correctly and meet the needs of users. Understanding the technical specifications, acceptance criteria, and practical applications of procedures, events, and groups is essential for developers, engineers, and users alike.

To learn more about MIDI and MMC, visit the official MIDI Association website: MIDI Association.