Declaring sketch parameters

The definition of ‘parameters’ makes it possible to parameterize the sketch. These parameters can be stored either in RAM only, or in (emulated) EEPROM.

In order to declare parameters to following macro must be used:

RK002_DECLARE_PARAM(name,flags,min,max,def)

As can be seen from the above definition, the macro takes 5 parameters:

1. name = the name of the parameter
2. flags = flags for the creation of the parameter: currently only the following values are supported: (0=default, 1=store in EEPROM)
3. min = minimal value of the parameter
4. max = maximal value of the parameter
5. def = default value of the parameter

Our example sketch can be extended by using a parameter definition.

#include <RK002.h>

RK002_DECLARE_INFO("SAMPLE CODE","duy@retrokits.com","1.0","7b47d3dd-991a-4197-ac02-d340cdabfb59")

RK002_DECLARE_PARAM(TRANSPOSE,1,-12,12,0);

boolean RK002_onNoteOn(byte channel, byte key, byte velocity)
{
  RK002_sendNoteOn(channel, key + RK002_paramGet(TRANSPOSE), velocity);
  return true;
}

boolean RK002_onNoteOff(byte channel, byte key, byte velocity)
{
  RK002_sendNoteOff(channel, key + RK002_paramGet(TRANSPOSE), velocity);
  return true;
}

void setup()
{
}

void loop()
{
}

There is a lot of under-water-magic going on when defining parameters this way. During the compilation of the sketch all occurrences of the RK002_DECLARE_PARAM macro will be replaced by internally used code.

• Every occurrence of the RK002_DECLARE_PARAM macro will create 1 parameter.
• A parameter can internally hold a 16-bit value, either signed or unsigned.
• Per default a parameter is treated internally as a unsigned value. When the minimal value of a parameter is below zero the parameter will be treated as signed.
• In total there can be defined max. 32 parameters.
• Parameters can be inquired by MIDI sysex : the RK002 loader uses this to display the parameter names and ranges.
• Parameters can be read & written by MIDI sysex : the RK002 library will handle this transparently : the sketch can be notified when a parameter has been written by means of callback function
• Parameters can be read & written by the sketch itself : the outside world will be notified when a parameter has been written by means of MIDI sysex.
• Parameters can be stored in (emulated) EEPROM so that they will be available even when the cable is not powered.
• Parameters can be referenced by their name or index inside the sketch.
• Parameters have to be referenced by their index when accessing by MIDI.

The sketch can access parameters by means of the following 2 functions:

void RK002_paramSet(unsigned param_nr, int val)

This will set the parameter to the requested value. The value will be bound-checked, possible call-back functions will be called, and a MIDI sysex message will be generated to indicate parameter change.

Note that the parameter value is defined as an “int” On the Arduino platform an “int” is acutally a 32-bit value. Inside the RK002 library however a parameter is a 16-bit value (signed or unsigned) This means that the actual range of a parameter is -32768..32767 or 0..65535 depending on the min argument during declaration (!)

int RK002_paramGet(unsigned param_nr)

This will fetch a parameter value.

Whenever a paramer is written by MIDI (sysex) the RK002 library will handle the actual communication. In order to be notified of a parameter change the sketch can implement the following callback:

void RK002_onParamSet(unsigned param_nr, int param_val)

this callback will be called on every parameter write, regardless whether the param_val has changed or not.

and / or

void RK002_onParamChange(unsigned param_nr, int param_val)

this callback will be called only when the parameter_val really changes.