Creator development - TheTechnobear/Eigenharp GitHub Wiki

This page is a quick guide on how to start looking at existing setups, and also developing your own templates.

Prerequisites - what i assume you know!

  1. you have read the GETTING STARTED guide, through to the bottom!! http://github.com/TheTechnobear/Eigenharp/wiki/CREATOR-GETTING-STARTED
  2. you have read the FAQ - important! it answers a lot of questions, about how and why! http://github.com/TheTechnobear/Eigenharp/wiki/CREATOR-FAQ
  3. you have knowledge of belcanto http://www.eigenlabs.com/wiki/2.0/The_EigenD_Reference/ http://www.eigenlabs.com/wiki/2.0/Introduction_to_EigenD/

Lets get started

First step is to understand the basics...
We will work thru the basic demo, to understand what is going on, I will take the pico as an example but its the same for all devices

Config files - conf/*

These files are used to tell Creator how to create a setup, basically what templates to use.
Each line says which template to use, and the parameters to use... more on this later

Templates - templates/*.bc

These are the building block. IF you know belcanto then you can EASILY create a new template, they really are just belcanto scripts. There are only 2 differences

  • They use variables rather than specific names e.g %VAR1% e.g. normal belcanto script metronome hey start templates script %VAR1% hey start ... we will see why in the example later...
  • no header, e.g. Script name ... this is because this is only used when loaded via interpreter, we execute the code directly via bscript (another eigend utility)

Unravelling the basicdemo

Ok, first I assume you have run it, and are familiar with what it does... and perhaps take a look in workbench at the results... i.e. so you know what its has created!
general point in conf files, and template (.bc) , # as first character on line, indicates a comment, so you can kind of ignore.

basic demo explained

createdevice.bc:
basicsetup.bc:
keymaps/factory_main.bc:main keygroup:
rigs/createsynth.bc:synth rig 1:
linkrig.bc:main keygroup:synth rig 1:1:1:

First, we can see there are 5 lines, each executes a template.

createdevice.bc:

ok, so the template is called createdevice.bc, and has no parameters (contrast with second line which takes 1, and the last line which takes 4)
So lets look at the template... but where is it? Usually they are in creator/templates ... but this one is not!?
That is because it is a device specific, so you will find it in creator/templates/device
i.e. in this example when running for pico it will use creator/templates/pico/createdevice.bc

**RULE: for every template line, creator will looking in the templates AND in templates/device, it will run from either and BOTH (the device one is always run AFTER the generic one) **

if you look at createdevice.bc, you will see its just plain belcanto

basicsetup.bc

Ok, same as createdevice.bc, no parameters, this time however its in templates as its common to all devices, which is the usual case.

keymaps/factory_main.bc:main keygroup:

Ok this is interesting for two reasons...

  • FIRST, it has one parameter, main keygroup

  • SECOND, the name keymaps/factory_main.bc ... YES, the templates can have sub directories in the name. AND this follows the same search rule ... this will be looked for in templates/keymaps/factory_main.bc AND templates/pico/keymaps/factory_main.bc. in this case its found in the later

  • THIRD, keymaps, ok this is just a convention, these directories hold the keyboard mappings. and are help in the device directories.. because they are the most likely thing to be different between devices, since they have different size keyboards!
    now lets look at the script... well the first 2 lines, as the rest follows the same

    %VAR1% hey mode key column to 3 set %VAR1% hey mode key row to 4 set

the important bit is %VAR1% , this says to use the first parameter (or variable, hence VAR), if you remember from above this was set to 'main keygroup'
so when executed we end up with

main keygroup hey mode key column to 3 set 
main keygroup hey mode key row to 4 set

Yes, its really as simple as that!!!

rigs/createsynth.bc:synth rig 1:

Ok, as far as creator is concerned this is very similar to last line
again, remember search rule, first it looks in templates, then device.. but as this is common, it finds it in templates/rigs/createsynth.bc. then passes the parameter synth rig 1 as VAR1, which is the name the belcanto use to name the script ... easy!

linkrig.bc:main keygroup:synth rig 1:1:1:

we are onto the last line already !!!
Ok this templates links the rig into the keygroup, you can see it takes 4 parameters

  • main keygroup - VAR1 , then keygroup to link the rig to
  • synth rig - VAR 2, the rig to link to the key group
  • 1 - VAR3, the keygroup output to use, and also used as the mixer channels input
  • 1 - VAR4, the eigenD channel

Lets have a quick look at the script

# this script will link a rig to a keygroup and the mixer console on a given channel  
# VAR1=%VAR1% keygroup to link VAR2=%VAR2% rig to link VAR3=%VAR3% mixer channel, VAR4=%VAR4% keygroup channel  
scheduler identifier to %VAR2% scheduler identifier connect  
metronome 1 to %VAR2% connect  
%VAR2% to console mixer mixer channel %VAR3% connect  
%VAR1% hey output %VAR3% create
%VAR1% hey keygroup output %VAR3% key column to 1 set
%VAR1% hey keygroup output %VAR3% key row to %VAR3%  set
%VAR1% output keygroup %VAR3% to %VAR2% into channel %VAR4% connect

Ok, the comments are important here.. MOST templates will have a comment on the first lines to say what it does AND what the parameters/variables are used for... so you don't have to read the belcanto to use it, just read the comment. Of course you know belcanto so you can check yourself, but some of the template scripts are pretty long, e.g. rigs so this is helpful
The rest really forms the same as before, Creator simply goes through each line and substitutes variables with the values passed in from the config file.

and that is IT, really its is no harder than that!!!

Iterators

Ok, these were added later, as it becomes obvious we repeat code quite alot, e.g. when we create a rig we have to connect it to all outlets in a keygroup

lets say we have a config lines like:

midi/linkmidirig.bc:percussion keygroup:midi rig 1:1:11:1:1:
midi/linkmidirig.bc:percussion keygroup:midi rig 2:2:11:1:2:
midi/linkmidirig.bc:percussion keygroup:midi rig 3:3:11:1:3:

we can now replace this with:

Iterate:%X%:midi rig 1,midi rig 2,midi rig 3:midi/linkmidirig.bc:percussion keygroup:%X%:%IDX%:11:1:%IDX:

ok, this looks confusing, but its pretty straightfoward

so whats going on here... generally the format is:

Iterate:VAR(=offset):LIST:existing config line to iterate

VAR is the variable name %X% in my example above optionally = offset can be used to create an offset index value, see below. LIST is the list of values to use (comma separated) in the existing config lines, you then just use VAR where you would have used the value before. there are two special variables: %IDX% which runs from 1 to list length. %IDX-OFFSET%, this is an offset index value e.g.

Iterate:%X%=9:midi rig 1,midi rig 2,midi rig 3:midi/linkmidirig.bc:percussion keygroup:%X%%IDX-OFFSET%:11:1:%IDX:

linkmidirig.bc will be called three times, substituting as follows:

first time %X% with midi rig 1 %IDX% with 1 %IDX-OFFSET% with 9

next time %X% with midi rig 2 %IDX% with 2 %IDX-OFFSET% with 10

next time %X% with midi rig 3 %IDX% with 3 %IDX-OFFSET% with 11

(IDX-OFFSET is used mainly if you have to split iterations over multiple lines due needing to call different templates)

Development process

Ok, now I will quickly explain how I develop things, there are lots of ways but this is easiest.

  • I create any new templates I need to, because I need some new functionality
  • I create a new configuration file, which has the bare minimum to test this new functionality
  • I run creator.sh with the configuration file
  • It fails to execute, with belcanto, because I have a syntax error :)
  • I correct the error, and run again, it creates setup.. but does not work,
  • I fix error, run again... and its works perfectly ;o)
  • I put this template into a larger config that does something useful!

Of course the glib bits here is 'I fix the error' ... how? Well there a few things to do...

see belcanto errors

as the setup runs, it will say OK against each good line, and a belcanto error for ones with errors.
IMPORTANT - look at the first one, as if you get one error early on, it can lead to many later ones.
e.g. if it fails to create keygroup, of course it will fail when other belcanto commands try to use it!!
**IMPORTANT NOTE - as soon as ONE line fails in a templates, it will stop executing other lines in that .bc file, HOWEVER, it will continue to execute the next template/.bc file! **

Seeing script

I run createsetup and generate the belcanto. e.g.

bin/creator.sh -D x.bc pico conf/basicdemo.conf

So this will create a file called x.bc with the belcanto code, with all the substitutions done. this is useful for two reasons.

  • You can see the final belcanto, and you can run manually into commander, look at to check syntax etc.
  • It shows you ALL the belcanto, remember in normal mode, templates will not execute lines, after a syntax error, but in this mode all subsequent lines are still generated (because we are not executing the code!)

Workbench

I usually have this running, this allows me to see what is being created and linked up. Also, it allows me to re-run bits of templates.
Example:
Lets say that in the basicdemo example, rig creation is failing... because of a bug in the template, lets say the scaler creation failed. What I can do is:

  • Run the setup as normal, and see the error in the console (as per first step here!)
  • Use workbench, to see where the templates got to.. from here, I can see not far, as scaler is created pretty early, and its not present within the rig.
  • Copy the basicdemo.conf file, to say x.conf ( im going to edit this!)
  • Edit x.conf, and comment all the lines except the rigs/createsynth.bc
  • as the rig was created, I delete the rig in Workbench
  • now I have a look at the createsynth.bc to see what the error was ... using techniques above!
  • I fix the error in createsynth.bc
  • I run creator.sh, with x.conf !!!!
  • Also you can now use the -C option of creator to run an individual line of a config file In this way, I can quickly debug and fix the createsynth.bc without having to run the entire setup again.
    Of course you can also combined this with the first 2 techniques, to see the belcanto and test it.
    Then finally once you have createsynth.bc working, delete your temporary x.conf file and run createsetup.sh with the normal configuration file. (remembering for course to load the blank setup between runs!)

With this approach its very rapid to debug things.

Final tip, if you use VI id recommend using my vi tools, which allow quick execution of belcanto from the editor!

I hope this helps, if something is unclear please either correct this doc, or let me know so I can clarify it.

Thanks and I hope you enjoy!!!!