Help

The Monomodular framework has two things at its core that allow it to operate:

The Monomodular Python Scripts

These reside in Live's Application bundle on MacOSX, or in the Program Folder on Windows. They are capable of communicating with other loaded Monomodular compliant control scripts internally via Python. They also contain individual client components that communicate via MXDCore to m4l patches, and the mod.js javascript implementation (see below). As of b993, they also contain a MonoLinkClient, which is a new class that is capable of sending and receiving OSC in monomeserial or serialosc communication protocols to emulate a monome directly, as well as publish its connection information via Bonjour.

The mod.js Javascript Object

The mod.js is a javascript object that connects to the Live API Control Surface controls inside of the Monomodular script in order to communicate directly with the other controller scripts that it has access to. The javascript itself lives inside of a bpatcher, with some other objects that are necessary for it to connect and disconnect when Live changes in and out of edit mode, as well as a menu object for assigning the Python Client class that it's connected to. It should remain in this bpatcher to work properly, and the best way to use it in a new patch is to install it from Max's clippings.

The mod object automatically attempts to connect to a Python client whenever it is installed in an active Live set. However, its behaviour while in edit mode is somewhat different (and at times unpredictable, so its best to play by the rules with it). Don't have more than one mod instance open in a patch. Also, don't have more than mod instance open in the editor at once. Its possible to work this way, but can cause connection issues and posssible crashes of the editor.

Recently (b993), the mod.js has been corrected to maintain its connection state when switching between edit modes in Live, and to persist after saving a patch wherein it is connected to a client.

Inlets

The mod object, in its connected state, is capable of sending data to its Client instance, and of receiving data from the physical controllers that are connected to it. Each individual inlet on the top of the bpatcher object accepts a different kind of data:

1. The leftmost inlet accepts grid states. This data should be sent in the form (x, y, value), where x and y are values between 0 and 15, and value is a number between 0 and 127. It is intended to be used with a [matrixctrl], but this is only a convenience. You can send data from anything, as long as its formatted correctly.

2. The next inlet accepts key states. This data should be sent in the form (key, value), where key is a value between 0 and 7, and value is a number between 0 and 127.

3. The third inlet accepts swing value. It should be sent as a single integer value between 0 and 100. This inlet is here so that you can send the current swing value out to the Monomodular switchboard, and have it transmitted to another 'global swing' patch, like the Swing16 mod. It will probably be removed in b994.

4. This inlet accepts three different general functions. Among these are 'autoselect', 'offset', and 'color_map'. This outlet, also, will probably disappear by b994.

5. The last outlet accepts data that will be sent to a connected Code controller. Whilst the Code is supported by Monomodular, its architecture is different and therefore required a different set of commands. They will be detailed later in the section directly covering Code functions.

There are quite a few other commands that can be sent to the mod object, however they are inlet-independent (i.e. you can send them in any inlet). The convention of having different inlets for general data is merely a convenience, and any of the functions sent to them can be effected in the same manner by prefixing a set of arguments by their function name.

   For example, sending the message "0 0 1" in the first inlet of the mod object will have the same effect 
   as sending a message "grid 0 0 1" in any of the inlets:  both will light the top left button of their corresponding Client.

Additional commands available for input:

send_color_map: This allows a properly formatted color map to be sent to Monomodular, which contains specific color mappings for different kinds of supported controllers. For instance, you can create two different color maps, one for a monochrome device, and another for an RGB device, so that things can be displayed in more sensible ways depending on the controller being used. See below for more info on this.

set_report_offset: This function tells Monomodular to send the current offset value back to the mod anytime that it changes.

clear: This is functionally the same as calling "batch_grid_all 0", and will set all values of the grid (16x16) to 0.

batch: This sets a set of cells to the same value. It requires a second argument:

   grid:  The statement "batch grid 2" will set all cells on the 16x16 grid to the value of 2.
   row:  The statement "batch row 0 1" will set an entire top row on the grid to the value of 1.
   column:  The statemnt "batch column 15 0" will turn off an entire right column of the grid.

mask: This allows masking of a cell without actually changing its Client's stored value. For instance, if you've sent a "grid 0 0 1" call to the client, it has stored the top left cell's value as 1. If you navigate to a different client from the controller, or change navigation positions, and then return to view that cell, it will be relit to a value of 1. However, the "mask" function allows the user to send a new value to that cell without changing its stored value. This is useful for overlays or running status indicators that are not meant to be stored values, but merely flash for an instant and then go away as soon as the condition changes.

The "mask" function also requires a second argument:

   grid will mask a single cell, for example, "mask grid 0 0 2" will light the top left cell with the value of 2.  
   To turn off the mask, we would call "mask grid 0 0 -1".   
   You an also mask columns or rows by calling "mask column x value" or "mask row y value".  
   If you don't turn off the mask, it will revert to the stored value the next time the Python Client updates. 

send_hotline: this is a new function in b993, and basically allows calling internal functionality of another connected mod.js by routing it through the Monomodular switchboard. If it does not find a corresponding function in the target mod.js, it sends the arguments out of a uniquely named send in the target mod's patcher [r ---hotline]. As an example:

   To call the 'clear' function in another connected mod (say, the one in mod slot three), we could send a command:
   "send_hotline 3 clear"
   Or, to set the swing of all connected mods to 0%, we could send the command:
   "send_hotline all swing 50"
   Or, to send a message to the [r ---hotline] object of mod 2 (if it has one), we could send the command:
   "send_hotline blah 34"
   This last one would cause the [r ---hotline] receiver to spit out the message 'blah 34'.

This is hardly useful yet for me, but I have devious plans for it in the future ;)

exclusive: this is an extension of the hotline() function, and has the same effect, except that it will send the arguments out of other mod connected patchers through a uniquely named receive object with the name of the first argument to the exclusive function.

   Sending the mod bpatcher the arguments "exclusive blah sammy 35" will cause the message "sammy 35" to be distributed to any 
   connected mods and sent out a [r ---blah] object in those mods (if one exists).

Outlets

The outlets transmit data from a Monomodular controller when it is connected to the Client belonging to the mod:

1. The leftmost outlet will send out grid press data in the format: x, y, value. x and y are numbers between 0 and 15, and value is always either 0 or 1.

2. The second outlet will send out key press data in the format: key, value. key is a number between 0 and 7, and value is always either 0 or 1.

3. The third outlet will send out the current channel selection of the client. It will be a number between 0 and 15.

4. The fourth outlet will send out 'wheel' data from a connected Code controller. Again, the format of this data will be discussed in the section specific to the Code.

In addition to these outlets, you can also create a [receive] object prefixed with '---' and the function's name, and it will receive the same data.

   For instance, the same data will emit from the first outlet as it will from a receive object named [r ---grid] when you press a grid button on the connected
   controller and it is in modmode with your client selected on that controller.

Other commands that can be received through uniquely named receive objects include the following:

[r ---toggle_mute]: this object will send out the current mute status of the controller when holding alt and pressing the 6th key.

[r ---refresh]: this object will send out a bang any time the Monomodular Switchboard connects to the mod patch (e.g. when first loading the mod or when changing its client number).

[r ---alt]: this object will send the current value of the alt button any time it is pressed or released.

[r ---offset]: when "set_report_offset" is set to 1, this object will report any changes to the currently selected client's offset values.

[r ---hotline]: this object will receive calls initiated from other mods that are connected to Monomodular. See above.

Creating a mod instance from scratch

If you've installed Monomodular using its installer (from version b993 and forward), it should have been placed there automatically. If not, you can place the files manually:

The file "mod_b993.js" should be somewhere in your Max search path. The installer places it inside of the "aumhaa_blocks" folder.

The file "mod_b933_abstract.maxpat" should be in the same place (or somewhere in your Max search path).

The file "mod_b993.maxpatch" should be in your "/Max5.xx/patches/clippings" folder.

Once these three files are in their proper places, restart Max. If you open up a new m4l patch and right click a blank space, you should be presented with a menu. Towards the bottom of that menu is a submenu called clippings. You can paste a new instance of the mod object from here.

Once you've pasted the new instance of the mod object inside a patcher, you'll need to save the patch, delete it from your Live set, and then reload it in order for it to work right.

Once you've reloaded the fresh patch, it should automatically connect to a Client. You should not make changes to the client settings if you are editing the patch. I've tried to sandbox it so that things don't go wrong while in edit mode, but doing this requires that the Client number be locked, and this is far from fool-proof. Its best just not to mess with it ;)