5.8 Live Monitor

The Live Monitor is a feature introduced with Koala v2.2.0 that helps understanding how a value - be it a variable, a math operation or the content of an array - is changing over time.

The Live Monitor relies on two functions: DEBUG.osc_value(), which fills the Oscilloscope over time with a specific value, and DEBUG.osc_array(), which both fills the Oscilloscope with the trend of the array - to give you an overall look of the content of the array itself - and also displays the full content of the array into a text box.

DEBUG.osc_value

This function may be called inside a callback. Its purpose is to show how a specific value - which is passed as a parameter to the function - is changing over time, so it's useful for instance in the on listener callback and in every situation where a value is continuously changed over time (as in a loop).

DEBUG.osc_value(<value>)

• value Value to be monitored. Can be a math operation, a variable, anything.

SET_CONDITION(ENABLE_DEBUG)
import 'Koala/Koala.ksp'
	
on init
	activate_logger(get_folder(GET_FOLDER_PATCH_DIR) & "/log.nka")
	Koala.init	
	declare i

	create_instrument(250, '', '', 'Sandbox')
	set_listener(NI_SIGNAL_TIMER_MS, 10000)
end on

on listener
	if NI_SIGNAL_TYPE = NI_SIGNAL_TIMER_MS
		i := i mod real_to_int(~NI_MATH_PI * 2.0 / 100.0)
		DEBUG.osc_value(real_to_int(sin(int_to_real(i) / 100.0) * 100000.0))
		inc(i)
	end if
end on

In the example above, DEBUG.osc_value() is monitoring how a sin() function changes over time in the on listener callback. The parameter passed to the sin() function is a number that goes from 0 to 627 (which is a low-res integer representation of 2π). The amplitude of the output of sin() is then enhanced by 100000 times in order to generate a sine wave with range ±100000. This sine wave is displayed on the Oscilloscope in realtime.

DEBUG.osc_array

This function may be called outside any callback. It enables the Live Monitor to listen in realtime to any change into an array (which is passed as a parameter to this function). The content of the array may then be displayed either in the Oscilloscope or in the Array view.

DEBUG.osc_array(<array_name>)

• array_name Name of the array to be monitored.

SET_CONDITION(ENABLE_DEBUG)
import 'Koala/Koala.ksp'
	
on init
	activate_logger(get_folder(GET_FOLDER_PATCH_DIR) & "/log.nka")
	Koala.init	
	declare i
	declare sine_wave[628]

	create_instrument(250, '', '', 'Sandbox')
	set_listener(NI_SIGNAL_TIMER_MS, 10000)
end on

on listener
	if NI_SIGNAL_TYPE = NI_SIGNAL_TIMER_MS
		i := i mod real_to_int(~NI_MATH_PI * 2.0 / 100.0)
		sine_wave[i] := real_to_int(sin(int_to_real(i) / 100.0) * 100000.0
		inc(i)
	end if
end on

DEBUG.osc_array(sine_wave)

In the example above, the very same sine wave we used before is loaded into an array. The array is loaded with one full period of the sine wave. The function DEBUG.osc_array() is then called outside any other callback in order to enable the monitoring.

Elements of the Live Monitor

The Oscilloscope is basically a UI table that is filled either with a value or the content of an array. The purpose of the Oscilloscope is to give you an overall look of how a value is evolving over time. You can switch between the Oscilloscope and the Array view from the button with yellow text at the lower-right corner of the window.

The two buttons at the center of the view, Start Arr and Start Value, allow the user to start the Live Monitor. As the Live Monitor handles separately arrays and values, there are two independent sets of information that are executed according to what you want to monitor. Below these buttons there is a text box filled with some useful data about the current state of the Live Monitor.

The four knobs on the left-hand side are generic view settings that allow you to adjust the content of the Oscilloscope in order for the values to be visible.

• Zoom - knob goes from 1% to 100%. It helps you to scale down the content of the Oscilloscope if the values you are monitoring are outside the range displayed by the table (which is ±1000000). It works together with Zoom + in order to enable you to have full control over the zooming of the content of the Oscilloscope.
• Zoom + knob goes from 100% to 1000000%. It enables you to increase the values displayed by the Oscilloscope in order to bring them into a visibile range. This is useful when displaying very small values.
• Offset V knob moves the content of the Oscilloscope down or up.
• Res knob reduces the resolution of the Oscilloscope. Be aware that the usage of this control may produce aliasing on the displayed values if the incoming value is changing at a very fast rate, so use this with caution.

The next section is the Export Table. This section is used to export a 128-values sized array which contains exactly the values shown in the Oscilloscope. The generated lookup table may be used later for various purposes (for instance, to make a value follow a certain curve).

• Mult and Div value edits have to be set to a multiplier or a divider. These values are applied to the generated lookup table in order either to scale up or down the content of the generated table.
• Export Table button saves in the Data folder an array named DEBUG__osc_generate_output.nka which contains the result of the export.

The last three buttons on the right-hand side are Save Arr, Refresh and Oscilloscope/Array.

• Save Arr can be used only if DEBUG.osc_array() is called in the source script. It allows to save to disk the array that is being monitored.
• Refresh is used to reset the current view either of the Oscilloscope or of the Array view.
• Oscilloscope/Array displays either the Oscilloscope or the Array view.