Monogram API
Search…
⌃K

Actions and Inputs

Actions represent the expected behaviour of Monogram when a module is actuated.
Actions can be categorised by two properties: Dimensional Type and Execution Type.

Actions by Dimensional Type

Dimensional Types enforce compatibility between an Actions and physical inputs.
  • Pulse: An action that executes a zero-dimensional input (e.g., "delete photo")
  • Nudge: An action that changes a one dimensional input by a relative delta value (e.g., "increase exposure by 0.1")
  • Set: An action that changes a one dimensional input to an given absolute value (e.g., "set exposure to 1.5")
For example, keyboard shortcut (a Pulse action) cannot be assigned to a dial's turn because turn is a nudge action config. However, it can be assigned to leftTurn or rightTurn of a dial because they are pulse action configs. See definition for DialSettingsType for details.

Actions by Execution Type

Execution Types indicate how should the Action be executed.
  • Native Action: Actions that result in a message sent through WebSocket to your app
    • Generated from inputs.json that you provide
    • See section below for details
    • Native Actions can be Pulse, Nudge, or Set
  • Built-in Action: Actions that are provided by Monogram. To learn more about using these Actions, see the guide on OS Inputs
  • Internal Action: Actions that runs routines internal to Monogram
    • Dispatch Actions: Switch between profiles, show layout preview, etc...
    • For internal use only

How are Actions generated

This section provides more insight into how Monogram translates the Inputs provided in a Config Bundle into actions assignable to Monogram modules.
The following inputs from the MyPhotoEditor guide are used for this example.
[
{
"name": "Auto Tone"
},
{
"name": "Next Photo"
},
{
"name": "Previous Photo"
},
{
"name": "Likes",
"step": 1
},
{
"name": "Exposure",
"range": [-5, 5],
"step": 0.01,
"reset": 0
},
{
"name": "Saturation",
"range": [-100, 100],
"step": 1,
"reset": 0
}
]

Pulse Actions

The first 3 entries (Auto Tone, Next Photo, Previous Photo) are inputs which do not require any parameters to configure or execute. These are called Pulse Actions and can be assigned to a Button Press or Dial Press.
Tip You can use a short form for these kinds of actions in inputs.json by expressing the entry as a string instead of an object with a name key. For example:
[
"Auto Tone",
"Next Photo",
"Previous Photo",
{
"name": "Likes",
"step": 1
}
]

Step Actions

Suppose MyPhotoEditor records how many people have liked an image. Likes is a number which range from 0 to infinity, and can be increased (+1) or decreased (-1) relative to its current value.
The Likes entry has a step parameter to configure and execute. These inputs are called Step Actions.
Step actions can be assigned to a Button Press, Dial Press, Dial Rotation, Orbiter Ring Rotation, or the Orbiter disc.
Note: The end-user can increase the step value. For example, a Button Press can be configured to increment Likes by 5 at a time.

Set Actions

The Exposure and Saturation entries contain range, and reset parameters. These inputs are called Set Actions, as Monogram sends commands with an absolute value for the input.
Set Actions can be assigned to Button Press, Dial Press, and Slider.
The range property can also be used as a bound for Dial Rotation, Orbiter Ring Rotation, and the Orbiter disc.

Inferring actions

Monogram API infers the kind of Action based on the parameters you provide in each entry.
For more details on the format of inputs.json, see API Reference/inputs.json