user manual
- Grid Editor
Table of contents generated with markdown-toc
Grid Editor is the configuration software for Grid modular MIDI controllers. It's a cross-platform application working on Mac OS, Windows and Linux. Designed to allow in-depth customization for Grid users. It's an open-source project, based on svelte, nodejs and electron.
🛑 Important Notice! 🛑
In order to use the Grid Editor software, first you need to install the new firmware on your Grid modular MIDI controller.
Guide to install the firmware is here!
Grid Editor is in alpha state. The word alpha refers to the maturity of the software, bugs and crashes are expected. Please stick with us, doing our best to improve the software.
We are building the Grid Editor for Mac OS, Windows and Linux. Here you can find the respective guides and information.
Grid Editor is a signed and notarized application with a valid developer ID issued by Apple Inc. Tested on High Sierra (10.13) and other versions are also being tested soon. Different versions may give an alert of unidentified developer, resulting in blocking the application from opening. This can be overridden by following this guide by Apple.
https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unidentified-developer-mh40616/mac
If this happens with you too, let us know. We do our best to make Grid Editor compatible with various mac OS.
- You will need the grid_editor_Setup-{release number}.zip file to be downloaded and unzipped.
- After unzipping move the Grid Editor.app to the Applications folder.
- Launch the app.
Grid Editor has self-update functionality. This does only work, if your mac OS validates the application on first download. If it fails to validate the app, the updates downloaded in the background are also failing in validation. We are still debugging how we can make sure that the user is notified on validation problems and is directed to proper solution when it comes to updating the app. Removing previous app version and installing the fresh release is always an option.
Grid Editor is not a signed application in the alpha release stage. Up until app signing, security warnings may appear. We have tested the application extensively on Windows 10.
- You will need the grid_editor_Setup-{release number}.exe file to be downloaded and unzipped.
- Launch the downloaded .exe and start installation.
- Windows may show an application install security warning. Choose to run the app anyway.
- Launch the installed app.
Grid Editor has self-update functionality. We had no issues as of today with this functionality on Windows.
More information coming soon.
Opening up the Grid Editor, a similar view should be visible (yes, if you have EN16, then that will show up). The program's logic follows this pattern from top left to right:
- Top: Open connection with Grid control surface and the Editor software;
- Left: Set Global Settings which are reflected on the control surface as a whole;
- Right: Set specific settings on each control element on the Element Settings panel;
- Bottom: Menu bar with Grid Editor (left) and Grid Firmware (right) versions.
On the top you can select and open possible Grid serial ports to start communication with the Open button and its companion dropdown menu. These ports are only visible if you connect your controller(s) to your computer. After selecting the desired serial port (starting with Grid) hit Open and you should see your control surface appear on your screen.
Properties of the bar at the top of the Editor window:
- debug button: serial debug window for monitoring incoming- and outgoing serial messages
- drop-down menu: here you can select the serial port of your choosing
- open: opens the selected serial port and enables module discovery and other functionality
- close: closes the selected serial port
- connection indicator
Global Settings panel reflects changes made on all the connected control modules as a control surface. As of today, Bank settings are the global settings.
The term Bank, refers to an independently customisable mode of a given Grid module. At default you have four (4) Banks available to you on each Grid module. Banks store their settings independently from each other, so you can configure multiple different setups and switch between them on the fly.
You can switch between Banks quickly by pressing the Bank button located on the side opposite from the USB port.
Properties of the Banks section:
- Banks 1-4:
- click on any of the numbers to choose a Bank you are working with
- the connected control surface and the user interface should reflect the changes
- Name:
- you can name each Bank as you prefer (this feature will have more meaning in later release...)
- Enabled/Disabled toggle:
- enable or disable the selected Bank, indicated by green (on) or red (off) dot
- a Disabled Bank will be skipped when switching Banks directly on your Grid
- Disabled Banks can still be configured as normal
- Bank colour
- change the colour of the selected Bank
The last settings are the Global commands, Store, Recall and Clear.
The Element Settings panel is where most of the magic happens. Here you can adjust and configure all functions assigned to a module on a per-Element basis.
You can select a control element in the Grid Editor either by Left-Click or interact with one of the Control Elements on the connected Grid control surface.
A Control Element refers to a specific potentiometer, button, encoder or fader on your Grid module. Each Element has a number assigned to it and you can also see the currently selected Element highlighted on the specific module.
The top of the Element Settings panel will show which module type and control element number you are interacting with.
Encoders (EN16) can be selected by pressing the knobs!
You can name each Control Element (coming handy with future releases..). For the names to show up on the overlay click on the eye icon have the names of your Control Elements appear.
For the length of names on display, the UI will follow these guidelines:
- 4 characters will be visible if the size setting of the UI is smaller than 2.5;
- 8 characters will be visible if the size setting of the UI is higher than 2.5;
Events describe every physical interaction that a given Control Element can recognize.
For example pressing down (down) or releasing a button (up) are two different inputs.
Interacting with a Control Element will send the input specific event and related configured Actions to the connected computer (and software).
Actions assigned to the event are sent out in order starting from the top!
When switching banks, this is an event automatically emitted. Each control element will send out the configured actions under the bank init event to the connected computer. All the control elements have this event type.
It's a good practice to set the LED Color on a bank init event. This way the LED config action will happen only on bank changes.
The absolute value change event sends messages in the form of absolute values, ranging from 0 to 127. Encoders, potentiometers and faders can use this event type.
The relative value change event sends ”value increment” and ”value decrement” messages instead of absolute values. Encoders can use this event type.
The down event is used by buttons and encoders. When you push down a Control Element, it will act out all actions configured under the down event.
The up event is used by buttons and encoders. When you release a Control Element, it will act out all actions configured under the up event.
Usually up and down events are used together:
on down >> actions to start something
on up >> actions to stop something
Example: Note - On & Note - Off pairs.
Actions describe functions that you can assign to inputs (events) on a per-Element, per-Event basis.
From a drop-down list you can choose various actions. Each action has different input fields. Some input fields will offer suggestions for the given action. An action and its values have to be validated before configuration can happen. Actions have an order number, they are sent out to the computer in order from top to bottom. Each action has a name, two order change buttons and a remove button.
Some actions have input fields with template parameters. These template parameters may feel alien at first but it's one of the cool things making Grid stand out.
The template parameters are not constant values, instead Grid renders the corresponding values in the background through messages. For example under the MIDI Dynamic action, you won't have to set each Control Element's second parameter (pitch or control number) to a constant value (12 or 14), instead you can use the template parameter A0 to tell Grid: you can assign this selected Control Element default number to the second parameter.
Control Element Parameters:
-
A0: Control Element's default control number
-
A1: Control Element's default control number in reverse
This is because of Drum Rack.
-
A2: Absolute value of the control element in 7-bit (0...127, use it with MIDI)
-
A3: Absolute value of the control element in 8-bit (0...255, use it with LED)
-
A4: Upper byte of control value in 14-bit format (coming soon)
-
A5: Lower byte of control value in 14-bit format (coming soon)
-
A6: Digital value of the push button in 7-bit (0 or 127, use it with MIDI)
-
A7: Digital value of the push button in 8-bit (0 or 255, use it with LED)
Global Parameters:
- B0: Active bank number (0...3)
- B1: Bank default color red (0..255)
- B2: Bank default color green (0..255)
- B3: Bank default color blue (0..255)
Grid's unique feature is that you can reposition interconnected modules on the fly and get new mapping options in each position.
By default Grid sends MIDI Dynamic actions upon interacting with Control Elements. You can overwrite the default behaviour by using the MIDI Dynamic action. In MIDI Dynamic mode the MIDI channel used to send out the MIDI messages are determined by Grid, based on the position of the module.
-
First Input Field (Command)
Choose between MIDI Commands, Note On / Note Off or Control Change here. This input field can accept hex strings as well as numbers. For example 0x90 equals with 144 which equals with Note On. Try it out!
Valid values: 128-255
-
Second Input Field / Parameter 1
Set the first MIDI parameter here. If first input field is set to Control Change, Control Number can be defined. If first input field is set to Note On / Note Off, Pitch parameter can be defined here. Template parameters are also available.
Valid values: 0-127
-
Third Input Field / Parameter 2
Set the second MIDI parameter here. If first input field is set to Control Change, Control Value can be defined. If first input field is set to Note On / Note Off, Velocity can be defined here. Template parameters are also available.
Valid values: 0-127
Prior to the Grid Editor release we often referred to this as Relative Mode, but this terminology was confusing with the relative change values and switched to Dynamic Mode instead.
With the MIDI static action you can define a full MIDI message, including the MIDI channel.
-
Channel
Set here the MIDI Channel.
Valid values: 1-16
-
Command
Choose between MIDI Commands, Note On / Note Off or Control Change here. This input field can accept hex strings as well as numbers. For example 0xb0 equals with 176 which equals with Control Change. Try it out!
Valid values: 128-255
-
Parameter 1
Set the first MIDI parameter here. If first input field is set to Control Change, Control Number can be defined. If first input field is set to Note On / Note Off, Pitch parameter can be defined here. Template parameters are also available.
Valid values: 0-127
-
Parameter 2
Set the second MIDI parameter here. If first input field is set to Control Change, Control Value can be defined. If first input field is set to Note On / Note Off, Velocity can be defined here. Template parameters are also available.
Valid values: 0-127
Prior to the Grid Editor release we often referred to this as Absolute Mode, but this terminology was confusing with the absolute change values and switched to Static Mode instead.
LED Color action is used to set the color of a Control Element.
It's best used with LED Phase action: LED Color will only set the color, LED Phase handles the LED intensity!
-
Element
Define which Control Element's color should be changed. Template parameters are also available (and suggested to be used).
Valid values: Template Parameter, 0-15
-
Layer
There are two layers available: A and B layer.
- A: Default layer of potentiometers, buttons, encoder turn (value change) and faders.
- B: Push action on the Encoder
Mostly you should use the A layer. B layer is there, because there are Control Elements with multiple input formats (encoder can be pushed and turned too).
Valid values: At least one layer has to be selected.
-
Red
Set the red component of the RGB LED color.
Valid Values: 0-255
-
Green
Set the green component of the RGB LED color.
Valid values: 0-255
-
Blue
Set the green component of the RGB LED color.
Valid values: 0-255
-
Alpha
Set the alpha component of the LED color. Instead of traditional transparency, each color component is multiplied by the alpha value to give dimmer or stronger color components. For example alpha = 0.5; red = 255 * 0.5 = 127; values are round down to closest integer.
Valid values: 0-1
The LED Phase action changes the intensity of a LED.
-
Element
Define which Control Element's LED intensity should be changed. Template parameters are also available (and suggested to be used).
Valid values: Template Parameter, 0-15
-
Layer
There are two layers available: A and B layer.
- A: Default layer of potentiometers, buttons, encoder turn (value change) and faders.
- B: Push action on the Encoder
Mostly you should use the A layer. B layer is there, because there are Control Elements with multiple input formats (encoder can be pushed and turned too).
Valid values: At least one layer has to be selected.
-
Intensity
Adjust the LED intensity.
Valid values: Template Parameter, 0-255
This is a special action, without validator. To trigger the validity change detection the send button has to be clicked. The RAW action's text area input will be serialized. You can input multiple messages in the text area and hit enter to separate them.
This is a development tool mostly for now, although with further documentation interesting things can be presented, like sending SySex or other unique messages to the computer.
Once you have finished a configuration you should hit the Store button in the local commands panel. This will save your configuration onto your Grid controllers. Local Store saves all your non-global settings, not only on the specific Element Settings you see on Grid Editor's user interface.
The Recall is available on the user interface, although it does not reload the connected Grid controller's configuration onto the Grid Editor software. This is a feature we are currently working on.
The Clear button clears all the non-global configuration from you connected control surface.
We have implemented in the alpha release a feedback form, with a simple text box where you can send a direct email to us to say hello or share your experience, help us in splatting bugs or send us feature requests.
You can also subscribe to our newsletter, privacy policy applies.
On different screen sizes, the Global and Element Settings panels may overlap your control surface, resulting in inaccessible control elements. You can resize the window or use the Alt + Left Click mouse movement to pan the control surface.
We are collecting anonymous data during the Grid Editor usage, tracking user interface interaction, installed software version, operating system, screen width and other data which may help us in deciding where to put our development efforts.
How is the data submitted anonym?
We use a library called uuid to generate a unique user id without using any personal information. This id is saved in Grid Editor's resources and is being paired with all the tracked events you trigger during software usage. We are using Google Analytics as a third party analytics tool.
We do believe analytics is a necessary evil to help us shape the future of Grid. Won't abuse your trust nor your data.
This privacy note is far from a relevant GDPR privacy policy, that will come later. Relevant bits from our privacy policy applies for the Grid Editor software.