iii scripting reference

Note: if you’re updating v1.0.0 iii code, see the porting guide.

device: grid

function	description
`event_grid(x,y,z)`	callback function for grid key
`grid_led(x,y,z,rel)`	set coordinates x,y to value z, or if rel is true, add z to existing value
`grid_led_get(x,y)`	returns value at coordinates x,y
`grid_led_all(z,rel)`	set all values to z, or if rel is true, add z to all existing values
`grid_intensity(b)`	set global intensity to brightness b, triggers refresh
`grid_refresh()`	refresh LED values
`grid_size_x()`	returns x size
`grid_size_y()`	returns y size

device: arc

function	description
`event_arc(n,d)`	callback function for arc knob ring n delta d
`event_arc_key(n,d)`	callback function for arc knob ring n delta d
`arc_res(n,div)`	set knob resolution for ring n to div (default 1, use higher values for less resolution)
`arc_led(n,x,z,rel)`	set ring n segment x to value z, or if rel is true, add z to existing value
`arc_led_ring(n,z,rel)`	set all values of ring r to z, or if rel is true, add z to existing values
`arc_led_all(z,rel)`	set all values to z, or if rel is true, add z to existing values
`arc_intensity(b)`	set global intensity to brightness b, triggers refresh
`arc_refresh()`	refresh LED values

lib

These functions are included on all iii devices. Most of these functions are defined in the file lib.lua which is stored in the onboard filesystem.

lib.lua can be modified, though we recommend staying close to the original for compatibility. If you need to return your lib file to its default state, use rm(lib.lua) and it will be rebuilt on next boot.

midi

USB MIDI device functions

function	description
`event_midi(byte1, byte2, byte3)`	callback function for incoming USB MIDI
`midi_to_msg(data)`	returns decoded midi byte array data as a labeled table
`midi_out(table)`	table can be data bytes or msg, sent to USB MIDI port
`midi_note_on(note, vel, ch)`	shortcut function for sending note on
`midi_note_off(note, vel, ch)`	shortcut function for sending note off
`midi_cc(cc, val, ch)`	shortcut function for sending cc

metro

Repeating timers which executes a callback function.

Note these are hardware driven, limited to 15 total. You can of course use one fast timer to creatively manage sub-timers if you need more.

function	description
`m = metro.init(callback, time_sec, count_optional)`	initialize a metro m, with callback function, time in seconds, (optional) count before stop
`m:start(time_optional)`	start metro, with optional new time value
`m:stop()`	stop metro

slew

Stepped interpolation between values over specified time interval. No hard limit to how many slews can be created, though memory or cpu time will eventually cause problems with high numbers of simultaneous slews.

function	description
`id = slew.new(callback, start_val, end_val, time_sec, q)`	create a new slew with callback function, from start_val to end_val over interval time_sec, with callbacks on quantum q (default 1). returns id which is used to further manage the slew.
`slew.to(id, end_val, time_optional)`	interrupt running slew, set new destination from current position, new time interval optional
`slew.freeze(id)`	freezes slew, can be resumed with slew.to
`slew.allfreeze()`	freezes all slews
`slew.stop(id)`	stops and removes a slew
`slew.allstop()`	stop and remove all slews

pset

function	description
`pset_init(name)`	assign name to pset files to be written and read
`pset_write(index, table)`	writes pset number index with data table
`pset_delete(index)`	deletes pset at index
`table = pset_read(index)`	read pset number index into table

utils

function	description
`dostring(lua_command)`	send text to lua interpreter, execute command
`get_time()`	returns time in seconds with usec precision
`ps(formatted_string,...)`	print a formatted string, like printf
`pt(table)`	print table
`clamp(n,min,max)`	returns n clamped between min and max
`round(n,quant)`	returns n rounded to nearest quant (default 1)
`linlin(n,slo,shi,dlo,dhi)`	returns n transposed from range (slo,shi) to range (dlo,dhi)
`wrap(n,min,max)`	returns n wrapped within range (min,max)

system

function	description
`device_id()`	returns device name
`ls()`	list files
`cat(file)`	display file
`rm(file)`	remove file
`mem()`	display current memory availability
`gc()`	garbage collector (see lua docs)
`require(file)`	run file
`first(file)`	set file to be run at startup, omit file to remove current startup