Contributions:SerialWidgetADC - Revision history

Jhill: /* Widget Timing */

2026-01-26T00:48:17Z

Widget Timing

← Older revision		Revision as of 00:48, 26 January 2026
Line 103:		Line 103:
	#. The <code>debugCommOverhead</code> variable will now contain a timing measurement indicating the number of microseconds it took to send data over the serial port for the last sample-block. This will be roughly proportional to the number of channels and the number of samples per block. It should not exceed the sample period in microseconds (<code>1e6/samplesPerSecond</code>): if it does, your data will contain readings that were unevenly sampled in time. In that case, you should reduce <code>samplesPerSecond</code>, reduce <code>samplesPerBlock</code>, or reduce the number of channels in <code>sourcePins</code>.		#. The <code>debugCommOverhead</code> variable will now contain a timing measurement indicating the number of microseconds it took to send data over the serial port for the last sample-block. This will be roughly proportional to the number of channels and the number of samples per block. It should not exceed the sample period in microseconds (<code>1e6/samplesPerSecond</code>): if it does, your data will contain readings that were unevenly sampled in time. In that case, you should reduce <code>samplesPerSecond</code>, reduce <code>samplesPerBlock</code>, or reduce the number of channels in <code>sourcePins</code>.

	You can also probe the capabilities of your system by setting <code>debugSampleInterval=1</code>, then setting <code>samplesPerSecond</code> too high and repeatedly querying the <code>debugSampleInterval</code> variable. This gives you an empirical measurement of the interval between the sample before last and the last one in microseconds. (With <code>debugSampleInterval</code> set to non-zero you can also use BCI2000 to do something similar: set the <code>SamplingRate</code> parameter too high, and use the timing window to look at the difference between nominal and measured sample-block durations.) Remember to set <code>debugSampleInterval=0</code> when you have finished debugging - this ~~will~~ the system more responsive to, and ~~allow~~ more robust recovery from, transient timing hiccups (~~continued~~ tolerance of overly long sample intervals will lead to data loss).		You can also probe the capabilities of your system by setting <code>debugSampleInterval=1</code>, then setting <code>samplesPerSecond</code> too high and repeatedly querying the <code>debugSampleInterval</code> variable. This gives you an empirical measurement of the interval between the sample before last and the last one in microseconds. (With <code>debugSampleInterval</code> set to non-zero you can also use BCI2000 to do something similar: set the <code>SamplingRate</code> parameter too high, and use the timing window to look at the difference between nominal and measured sample-block durations.) Remember to set <code>debugSampleInterval=0</code> when you have finished debugging - this makes the system more responsive to, and allows more robust recovery from, transient timing hiccups (whereas prolonged tolerance of overly-long sample intervals will lead to data loss).

	''NB: the use of <code>debugCommOverhead</code> and <code>debugSampleInterval</code> assume you are working with version 1.4.0 or later of the ''SignalAcquisition'' Arduino-IDE library.''		''NB: the use of <code>debugCommOverhead</code> and <code>debugSampleInterval</code> assume you are working with version 1.4.0 or later of the ''SignalAcquisition'' Arduino-IDE library.''

Jhill: /* Widget Timing */

2026-01-26T00:47:05Z

Widget Timing

← Older revision		Revision as of 00:47, 26 January 2026
Line 105:		Line 105:
	You can also probe the capabilities of your system by setting <code>debugSampleInterval=1</code>, then setting <code>samplesPerSecond</code> too high and repeatedly querying the <code>debugSampleInterval</code> variable. This gives you an empirical measurement of the interval between the sample before last and the last one in microseconds. (With <code>debugSampleInterval</code> set to non-zero you can also use BCI2000 to do something similar: set the <code>SamplingRate</code> parameter too high, and use the timing window to look at the difference between nominal and measured sample-block durations.) Remember to set <code>debugSampleInterval=0</code> when you have finished debugging - this will the system more responsive to, and allow more robust recovery from, transient timing hiccups (continued tolerance of overly long sample intervals will lead to data loss).		You can also probe the capabilities of your system by setting <code>debugSampleInterval=1</code>, then setting <code>samplesPerSecond</code> too high and repeatedly querying the <code>debugSampleInterval</code> variable. This gives you an empirical measurement of the interval between the sample before last and the last one in microseconds. (With <code>debugSampleInterval</code> set to non-zero you can also use BCI2000 to do something similar: set the <code>SamplingRate</code> parameter too high, and use the timing window to look at the difference between nominal and measured sample-block durations.) Remember to set <code>debugSampleInterval=0</code> when you have finished debugging - this will the system more responsive to, and allow more robust recovery from, transient timing hiccups (continued tolerance of overly long sample intervals will lead to data loss).

	''NB: the use of <code>debugCommOverhead</code> and <code>debugSampleInterval</code> assume you are working with version 1.4.0 or later of the ''SignalAcquisition'' Arduino-IDE library.		''NB: the use of <code>debugCommOverhead</code> and <code>debugSampleInterval</code> assume you are working with version 1.4.0 or later of the ''SignalAcquisition'' Arduino-IDE library.''
	In earlier versions, similar functionality was available under the names <code>commOverheadMicros</code> and <code>measuredMicrosPerSample</code> but we strongly recommend that you update your library to the latest version.''		''In earlier versions, similar functionality was available under the names <code>commOverheadMicros</code> and <code>measuredMicrosPerSample</code> but we strongly recommend that you update your library to the latest version.''

	==See also==		==See also==

Jhill: /* Widget Timing */

2026-01-26T00:35:00Z

Widget Timing

← Older revision		Revision as of 00:35, 26 January 2026
Line 103:		Line 103:
	#. The <code>debugCommOverhead</code> variable will now contain a timing measurement indicating the number of microseconds it took to send data over the serial port for the last sample-block. This will be roughly proportional to the number of channels and the number of samples per block. It should not exceed the sample period in microseconds (<code>1e6/samplesPerSecond</code>): if it does, your data will contain readings that were unevenly sampled in time. In that case, you should reduce <code>samplesPerSecond</code>, reduce <code>samplesPerBlock</code>, or reduce the number of channels in <code>sourcePins</code>.		#. The <code>debugCommOverhead</code> variable will now contain a timing measurement indicating the number of microseconds it took to send data over the serial port for the last sample-block. This will be roughly proportional to the number of channels and the number of samples per block. It should not exceed the sample period in microseconds (<code>1e6/samplesPerSecond</code>): if it does, your data will contain readings that were unevenly sampled in time. In that case, you should reduce <code>samplesPerSecond</code>, reduce <code>samplesPerBlock</code>, or reduce the number of channels in <code>sourcePins</code>.

	~~As of version 1.4.0 of the ''SignalAcquisition'' library, you~~ can also probe the capabilities of your system by setting <code>debugSampleInterval=1</code>, then setting <code>samplesPerSecond</code> too high and repeatedly querying the <code>debugSampleInterval</code> variable. This gives you an empirical measurement of the interval between the sample before last and the last one in microseconds. (With <code>debugSampleInterval</code> set to non-zero you can also use BCI2000 to do something similar: set the <code>SamplingRate</code> parameter too high, and use the timing window to look at the difference between nominal and measured sample-block durations.) Remember to set <code>debugSampleInterval=0</code> when you have finished debugging - this will the system more responsive to, and allow more robust recovery from, transient timing hiccups (continued tolerance of overly long sample intervals will lead to data loss).		You can also probe the capabilities of your system by setting <code>debugSampleInterval=1</code>, then setting <code>samplesPerSecond</code> too high and repeatedly querying the <code>debugSampleInterval</code> variable. This gives you an empirical measurement of the interval between the sample before last and the last one in microseconds. (With <code>debugSampleInterval</code> set to non-zero you can also use BCI2000 to do something similar: set the <code>SamplingRate</code> parameter too high, and use the timing window to look at the difference between nominal and measured sample-block durations.) Remember to set <code>debugSampleInterval=0</code> when you have finished debugging - this will the system more responsive to, and allow more robust recovery from, transient timing hiccups (continued tolerance of overly long sample intervals will lead to data loss).

			''NB: the use of <code>debugCommOverhead</code> and <code>debugSampleInterval</code> assume you are working with version 1.4.0 or later of the ''SignalAcquisition'' Arduino-IDE library.
			In earlier versions, similar functionality was available under the names <code>commOverheadMicros</code> and <code>measuredMicrosPerSample</code> but we strongly recommend that you update your library to the latest version.''

	==See also==		==See also==

Jhill: /* Widget Timing */

2026-01-26T00:22:07Z

Widget Timing

← Older revision		Revision as of 00:22, 26 January 2026
Line 93:		Line 93:

	#. In the Serial Monitor of the Arduino IDE, first send the commands to set the acquisition parameters the way you want them. (NB: where you see <code>\n</code> above, do not literally type a backslash followed by an <code>n</code>: the <code>\n</code> stands for the newline character, which the Serial Monitor will append for you when you press return.)		#. In the Serial Monitor of the Arduino IDE, first send the commands to set the acquisition parameters the way you want them. (NB: where you see <code>\n</code> above, do not literally type a backslash followed by an <code>n</code>: the <code>\n</code> stands for the newline character, which the Serial Monitor will append for you when you press return.)
	#. Then, additionally send <code>~~commOverheadMicros~~=1</code> to enable measurement of the serial-port overhead.		#. Then, additionally send <code>debugCommOverhead=1</code> to enable measurement of the serial-port overhead.
	#. Then send <code>mute=0</code> to begin sending sample-blocks.		#. Then send <code>mute=0</code> to begin sending sample-blocks.
	#. Send <code>mute=1;?</code> to stop the flow and examine variables.		#. Send <code>mute=1;?</code> to stop the flow and examine variables.
Line 101:		Line 101:

	#. The <code>idleLoops</code> variable should be reliably greater than 0 when queried with <code>mute=1;?</code> . If it is 0, this indicates that your sketch may be unable to keep up with the desired sample rate. You need to reduce <code>samplesPerSecond</code>.		#. The <code>idleLoops</code> variable should be reliably greater than 0 when queried with <code>mute=1;?</code> . If it is 0, this indicates that your sketch may be unable to keep up with the desired sample rate. You need to reduce <code>samplesPerSecond</code>.
	#. The <code>~~commOverheadMicros~~</code> variable will now contain a timing measurement indicating the number of microseconds it took to send data over the serial port for the last sample-block. This will be roughly proportional to the number of channels and the number of samples per block. It should not exceed the sample period in microseconds (<code>1e6/samplesPerSecond</code>): if it does, your data will contain readings that were unevenly sampled in time. In that case, you should reduce <code>samplesPerSecond</code>, reduce <code>samplesPerBlock</code>, or reduce the number of channels in <code>sourcePins</code>.		#. The <code>debugCommOverhead</code> variable will now contain a timing measurement indicating the number of microseconds it took to send data over the serial port for the last sample-block. This will be roughly proportional to the number of channels and the number of samples per block. It should not exceed the sample period in microseconds (<code>1e6/samplesPerSecond</code>): if it does, your data will contain readings that were unevenly sampled in time. In that case, you should reduce <code>samplesPerSecond</code>, reduce <code>samplesPerBlock</code>, or reduce the number of channels in <code>sourcePins</code>.

	As of version 1.2.0 of the ''SignalAcquisition'' library, you can also probe the capabilities of your system by setting <code>samplesPerSecond</code> too high and repeatedly querying the <code>~~measuredMicrosPerSample~~</code> variable. This gives you an empirical measurement of the interval between the sample before last and the last one. (~~You~~ can also use BCI2000 to do something similar: set the <code>SamplingRate</code> parameter too high, and use the timing window to look at the difference between nominal and measured sample-block durations.)		As of version 1.4.0 of the ''SignalAcquisition'' library, you can also probe the capabilities of your system by setting <code>debugSampleInterval=1</code>, then setting <code>samplesPerSecond</code> too high and repeatedly querying the <code>debugSampleInterval</code> variable. This gives you an empirical measurement of the interval between the sample before last and the last one in microseconds. (With <code>debugSampleInterval</code> set to non-zero you can also use BCI2000 to do something similar: set the <code>SamplingRate</code> parameter too high, and use the timing window to look at the difference between nominal and measured sample-block durations.) Remember to set <code>debugSampleInterval=0</code> when you have finished debugging - this will the system more responsive to, and allow more robust recovery from, transient timing hiccups (continued tolerance of overly long sample intervals will lead to data loss).

	==See also==		==See also==

Jhill: /* Parameters */

2025-06-16T15:04:24Z

Parameters

← Older revision		Revision as of 15:04, 16 June 2025
Line 43:		Line 43:


	Parameters common to all source modules are described under [[User Reference:DataIOFilter]].		Parameters common to all source modules ('''SamplingRate''', '''SampleBlockSize''', '''SourceCh''', etc.) are described under [[User Reference:DataIOFilter]].
	''SerialWidgetADC'' adds only one parameter of its own:		''SerialWidgetADC'' adds only one parameter of its own:

Jhill: /* Source Code Revisions */

2025-06-16T15:02:50Z

Source Code Revisions

← Older revision		Revision as of 15:02, 16 June 2025
Line 17:		Line 17:
	===Source Code Revisions===		===Source Code Revisions===
	*Initial development: r7613		*Initial development: r7613
	*Known to compile under: ~~r7613~~		*Known to compile under: r8888
	*Broken since: --		*Broken since: --


	==Functional Description==		==Functional Description==

Jhill: /* Parameters */

2025-06-16T14:53:42Z

Parameters

← Older revision		Revision as of 14:53, 16 June 2025
Line 39:		Line 39:
	The same is true of the <code>--PublishCommand</code> parameter, if used.		The same is true of the <code>--PublishCommand</code> parameter, if used.

	The one departure from ''SerialInterface'' behavior is the handling of custom ~~<code>~~StartCommand~~</code>~~ and ~~<code>~~StopCommand~~</code>~~ messages. ADCs expect the signal to be delivered between runs as well as during runs. Therefore, if a ~~<code>~~StartCommand~~</code>~~ message is specified, the ADC sends it to the widget as soon as the user presses ~~'''~~Set Config~~'''~~ (whereas the ''SerialInterface'' Extension would wait until the user presses ~~'''~~Start~~'''~~ or ~~'''~~Resume~~'''~~). Similarly, if a ~~<code>~~StopCommand~~</code>~~ message is specified, the ADC only sends it immediately prior to disconnecting and reconnecting on subsequent ~~'''~~Set Config~~'''~~ operations, and/or when BCI2000 quits (whereas the ''SerialInterface'' Extension would send it when the user presses ~~'''~~Suspend~~'''~~).		The one departure from ''SerialInterface'' behavior is the handling of custom '''StartCommand''' and '''StopCommand''' messages. ADCs expect the signal to be delivered between runs as well as during runs. Therefore, if a '''StartCommand''' message is specified, the ADC sends it to the widget as soon as the user presses Set Config (whereas the ''SerialInterface'' Extension would wait until the user presses Start or Resume). Similarly, if a '''StopCommand''' message is specified, the ADC only sends it immediately prior to disconnecting and reconnecting on subsequent Set Config operations, and/or when BCI2000 quits (whereas the ''SerialInterface'' Extension would send it when the user presses Suspend).

	Additional Parameters may be defined by the widget itself, if you specify a <code>--PublishCommand</code> on the command-line and the widget is programmed to support the specified command, [[Contributions:SerialInterface#Defining_BCI2000_Parameters_and_Events_from_the_Widget\|as described in the SerialInterface documentation]]. As also described there, the values of widget-defined parameters may optionally be updated by the widget when a run ends, if you specify a '''ParameterUpdateCommand''' that the widget supports.		Additional Parameters may be defined by the widget itself, if you specify a <code>--PublishCommand</code> on the command-line and the widget is programmed to support the specified command, [[Contributions:SerialInterface#Defining_BCI2000_Parameters_and_Events_from_the_Widget\|as described in the SerialInterface documentation]]. As also described there, the values of widget-defined parameters may optionally be updated by the widget when a run ends, if you specify a '''ParameterUpdateCommand''' that the widget supports.

Jhill: /* SourceChPins */

2025-06-16T14:50:00Z

SourceChPins

← Older revision		Revision as of 14:50, 16 June 2025
Line 49:		Line 49:
	===SourceChPins===		===SourceChPins===

	This is a list of integer values, one per channel. The widget interprets these numbers when deciding how to acquire signals. The interpretation depends entirely on the way the widget is programmed: the simplest way would be to interpret the numbers as indices of the pins from which signals should be read (for example, as arguments to <code>analogRead()</code> or <code>digitalRead()</code> in the Arduino language). The parameter takes its name from this idea. However, a more-sophisticated widget might be programmed to do its own digital signal processing, and/or to generate artificial signals in response to external sensor inputs, and the relationship between these signals and the ~~<code>~~SourceChPins~~</code>~~ values may be arbitrary, as long as the number of channels matches the number of ~~<code>~~SourceChPins~~</code>~~ values.		This is a list of integer values, one per channel. The widget interprets these numbers when deciding how to acquire signals. The interpretation depends entirely on the way the widget is programmed: the simplest way would be to interpret the numbers as indices of the pins from which signals should be read (for example, as arguments to <code>analogRead()</code> or <code>digitalRead()</code> in the Arduino language). The parameter takes its name from this idea. However, a more-sophisticated widget might be programmed to do its own digital signal processing, and/or to generate artificial signals in response to external sensor inputs, and the relationship between these signals and the '''SourceChPins''' values may be arbitrary, as long as the number of channels matches the number of '''SourceChPins''' values.

	==States==		==States==

Jhill: /* Widget Programming */

2025-06-16T14:49:18Z

Widget Programming

← Older revision		Revision as of 14:49, 16 June 2025
Line 87:		Line 87:
	** error messages: BCI2000 will issue a fatal error containing the text of any line it receives from the widget if that line begins with <code>{</code> and contains the substring <code>_ERROR_</code> (which is true of any error message sent by the Keyhole library);		** error messages: BCI2000 will issue a fatal error containing the text of any line it receives from the widget if that line begins with <code>{</code> and contains the substring <code>_ERROR_</code> (which is true of any error message sent by the Keyhole library);
	** any other JSON output: BCI2000 will simply ignore any other line beginning with the <code>{</code> character.		** any other JSON output: BCI2000 will simply ignore any other line beginning with the <code>{</code> character.
	** (You can also use the '''SerialInputs''' parameter to recognize strings that do not necessarily have to end with <code>\r\n</code> or <code>\n</code>, as long as you do not include <code>\x01\x00</code> or <code>\x00\x01</code> in the table. However, there's no real advantage to this; since you have control over the widget's firmware, it is better to program it to send event descriptors as text lines.)		** (You can also use the '''SerialInputs''' parameter to recognize strings that do not necessarily have to end with <code>\r\n</code> or <code>\n</code>, as long as you do not include entries beginning with <code>\x01\x00</code> or <code>\x00\x01</code> in the table. However, there's no real advantage to this; since you have control over the widget's firmware, it is better to program it to send event descriptors as text lines.)

	==Widget Timing==		==Widget Timing==

Jhill: /* Widget Programming */

2025-06-16T14:48:13Z

Widget Programming

← Older revision		Revision as of 14:48, 16 June 2025
Line 87:		Line 87:
	** error messages: BCI2000 will issue a fatal error containing the text of any line it receives from the widget if that line begins with <code>{</code> and contains the substring <code>_ERROR_</code> (which is true of any error message sent by the Keyhole library);		** error messages: BCI2000 will issue a fatal error containing the text of any line it receives from the widget if that line begins with <code>{</code> and contains the substring <code>_ERROR_</code> (which is true of any error message sent by the Keyhole library);
	** any other JSON output: BCI2000 will simply ignore any other line beginning with the <code>{</code> character.		** any other JSON output: BCI2000 will simply ignore any other line beginning with the <code>{</code> character.
			** (You can also use the '''SerialInputs''' parameter to recognize strings that do not necessarily have to end with <code>\r\n</code> or <code>\n</code>, as long as you do not include <code>\x01\x00</code> or <code>\x00\x01</code> in the table. However, there's no real advantage to this; since you have control over the widget's firmware, it is better to program it to send event descriptors as text lines.)

	==Widget Timing==		==Widget Timing==