Contributions:SerialInterface - Revision history

Jhill: /* SkipUnrecognizedBytes */

2026-05-12T17:44:53Z

SkipUnrecognizedBytes

← Older revision		Revision as of 17:44, 12 May 2026
Line 97:		Line 97:
	If the '''SkipUnrecognizedBytes''' parameter is set to false (unchecked), then the data coming from the widget will continue to build into an ever-lengthening unrecognized command: BCI2000 will not recognize another '''SerialInputs''' byte string at all until the SerialInterface is reset (which happens at the start of a run if SerialInterface is running as an Extension, or when Set Config is pressed if you are running SerialWidgetADC).		If the '''SkipUnrecognizedBytes''' parameter is set to false (unchecked), then the data coming from the widget will continue to build into an ever-lengthening unrecognized command: BCI2000 will not recognize another '''SerialInputs''' byte string at all until the SerialInterface is reset (which happens at the start of a run if SerialInterface is running as an Extension, or when Set Config is pressed if you are running SerialWidgetADC).

	If '''SkipUnrecognizedBytes''' is set to true (checked), then it will be possible to discard unrecognized bytes and match a known string, but with the danger that substrings of ''un''recognized commands could be falsely recognized as commands. For example, if you have enabled '''SkipUnrecognizedBytes''', and you have listed the command <code>arm_stimulator</code> in '''SerialInputs''' but ''not'' <code>disarm_stimulator</code>, and the widget then happens to send <code>disarm_stimulator</code>, then BCI2000 will discard the bytes <code>dis</code> and recognize <code>arm_stimulator</code>, leading to the opposite of the intended effect. Clearly, this is a function of how the widget's protocol is designed. To avoid such situations, you must either (a) ensure that the entries in the '''SerialInputs''' table exhaustively cover the repertoire of possible widget outputs (don't worry, if a known longer string gets matched, its substrings will not get matched), or (b) accept the consequences of disabling '''SkipUnrecognizedBytes'''. An even more robust option, if possible, is (c) to leave the '''SerialInputs''' table empty and re-program your widget to send BCI2000 event descriptors directly as text (see the [[#State Variables\|State Variables]] section, below).		If '''SkipUnrecognizedBytes''' is set to true (checked), then it will be possible to discard unrecognized bytes and match a known string, but with the danger that substrings of ''un''recognized commands could be falsely recognized as commands. For example, if you have enabled '''SkipUnrecognizedBytes''', and you have listed the command <code>arm_stimulator</code> in '''SerialInputs''' but ''not'' <code>disarm_stimulator</code>, and the widget then happens to send <code>disarm_stimulator</code>, then BCI2000 will discard the bytes <code>dis</code> and recognize <code>arm_stimulator</code>, leading to the opposite of the intended effect. Clearly, this is a function of how the widget's protocol is designed. To avoid such situations, you must either (a) ensure that the entries in the '''SerialInputs''' table exhaustively cover the repertoire of possible widget outputs (don't worry, if a known longer string gets matched, its embedded substrings will not get matched), or (b) accept the consequences of disabling '''SkipUnrecognizedBytes'''. An even more robust option, if possible, is (c) to leave the '''SerialInputs''' table empty and re-program your widget to send BCI2000 event descriptors directly as text (see the [[#State Variables\|State Variables]] section, below).

	===SerialOutputs===		===SerialOutputs===

Jhill at 17:40, 12 May 2026

2026-05-12T17:40:41Z

← Older revision		Revision as of 17:40, 12 May 2026
Line 116:		Line 116:
	==State Variables==		==State Variables==

	The SerialInterface does not define any State Variables or Events of its own, but will define any Events the widget tells it to define in response to a <code>--PublishCommand</code>.		The SerialInterface does not define any State Variables or Events of its own, but will define any [[#Defining BCI2000 Parameters and Events from the Widget\|Events the widget tells it to define]] in response to a <code>--PublishCommand</code>.

	During a run, a widget may change an Event value at any time by sending an [[Programming_Reference:Events#Descriptor_Syntax\|Event descriptor line]]: usually, this is the name of the event, followed by a space, followed by the value expressed as decimal text, followed by a line-ending. Optionally, an Event descriptor may contain an additional space and a zero, to indicate an instantaneous transient event. For example, <code>TTLExampleSketch.ino</code> will send		During a run, a widget may change an Event value at any time by sending an [[Programming_Reference:Events#Descriptor_Syntax\|Event descriptor line]]: usually, this is the name of the event, followed by a space, followed by the value expressed as decimal text, followed by a line-ending. Optionally, an Event descriptor may contain an additional space and a zero, to indicate an instantaneous transient event. For example, <code>TTLExampleSketch.ino</code> will send

Jhill: /* ElseIf */

2026-05-12T17:37:26Z

ElseIf

← Older revision		Revision as of 17:37, 12 May 2026
Line 112:		Line 112:
	You may choose to process all rows on every sample-block (and potentially send all byte strings, one after the other);		You may choose to process all rows on every sample-block (and potentially send all byte strings, one after the other);
	alternatively, you may choose to stop after the first matching row (so, on any given sample-block, at most one of the byte strings will be sent).		alternatively, you may choose to stop after the first matching row (so, on any given sample-block, at most one of the byte strings will be sent).
			Possible values are 0 ("process all rows") or 1 ("stop at the first match").

	==State Variables==		==State Variables==

Jhill: /* SerialInputs */

2025-06-16T14:39:33Z

SerialInputs

← Older revision		Revision as of 14:39, 16 June 2025
Line 86:		Line 86:
	This matrix parameter gives BCI2000 the limited ability to respond to serial-port messages sent by the widget, even if you cannot re-program your widget.		This matrix parameter gives BCI2000 the limited ability to respond to serial-port messages sent by the widget, even if you cannot re-program your widget.

	If not empty, the matrix must have four columns. The first column contains (backslash-escaped) byte strings that the widget might send to BCI2000. The second column contains names of State Variables that have been declared as [[Programming_Reference:Events\|Events]] (perhaps using [[User_Reference:Operator_Module_Scripting#ADD_EVENT_<name>_<bit_width>_<initial_value>\|<code>ADD EVENT</code>]] in your launcher script). The third column contains the integer value that should be assigned to the Event when the byte string is received. ~~The~~ fourth column should be ~~either~~ left blank (in which case, the Event will remain at the assigned value until it is changed again) or ~~it can be~~ set to 0 (in which case the Event is transient, remaining at the assigned value only for one sample before automatically returning to 0). Thus, the second, third and fourth columns can be read from left to right as a [[Programming_Reference:Events#Descriptor_Syntax\|BCI2000 Event descriptor]], like <code>MyEvent 123</code> or <code>MyEvent 123 0</code>		If not empty, the matrix must have four columns. The first column contains (backslash-escaped) byte strings that the widget might send to BCI2000. The second column contains names of State Variables that have been declared as [[Programming_Reference:Events\|Events]] (perhaps using [[User_Reference:Operator_Module_Scripting#ADD_EVENT_<name>_<bit_width>_<initial_value>\|<code>ADD EVENT</code>]] in your launcher script). The third column contains the integer value that should be assigned to the Event when the byte string is received. In the fourth column, the entry should either be left blank (in which case, the Event will remain at the assigned value until it is changed again) or set to 0 (in which case the Event is transient, remaining at the assigned value only for one sample before automatically returning to 0). Thus, the second, third and fourth columns can be read from left to right as a [[Programming_Reference:Events#Descriptor_Syntax\|BCI2000 Event descriptor]], like <code>MyEvent 123</code> or <code>MyEvent 123 0</code>

	A given byte string is allowed to appear more than once in the table, to trigger multiple Events simultaneously. The Event name (second column) is allowed to be blank, to enable a particular byte string to be recognized but ignored.		A given byte string is allowed to appear more than once in the table, to trigger multiple Events simultaneously. The Event name (second column) is allowed to be blank, to enable a particular byte string to be recognized but ignored.

	Note that the '''SerialInputs''' mechanism is designed to be very generic, and as such it is not necessarily possible to tailor it to the particular protocol your widget uses. For example, BCI2000 will not know how the widget likes to terminate messages unless you explicitly include the terminator bytes (so, if <code>shutdown</code> and <code>shutdown-gracefully</code> are both configured, the longer command will never be recognized: BCI2000 will greedily recognize and obey <code>shutdown</code> before attempting to move on to <code>-gracefully</code>). The limitations of the '''SerialInputs''' table also ~~become very obvious~~ if the widget sends a byte string that you have omitted from the table. Then, one of two compromises must be accepted (see the description of the '''SkipUnrecognizedBytes''' parameter, below).		Note that the '''SerialInputs''' mechanism is designed to be very generic, and as such it is not necessarily possible to tailor it to the particular protocol your widget uses. For example, BCI2000 will not know how the widget likes to terminate messages unless you explicitly include the terminator bytes (so, if <code>shutdown</code> and <code>shutdown-gracefully</code> are both configured, the longer command will never be recognized: BCI2000 will greedily recognize and obey <code>shutdown</code> before attempting to move on to <code>-gracefully</code>). The limitations of the '''SerialInputs''' table also make themselves felt if the widget sends a byte string that you have omitted from the table. Then, one of two compromises must be accepted (see the description of the '''SkipUnrecognizedBytes''' parameter, below). In general, it is not possible to support a serial protocol that includes variable values (unless you create a separate '''SerialInputs''' row for every possible combination of values).

	===SkipUnrecognizedBytes===		===SkipUnrecognizedBytes===

Jhill: /* SerialInputs */

2025-06-16T14:34:40Z

SerialInputs

← Older revision		Revision as of 14:34, 16 June 2025
Line 90:		Line 90:
	A given byte string is allowed to appear more than once in the table, to trigger multiple Events simultaneously. The Event name (second column) is allowed to be blank, to enable a particular byte string to be recognized but ignored.		A given byte string is allowed to appear more than once in the table, to trigger multiple Events simultaneously. The Event name (second column) is allowed to be blank, to enable a particular byte string to be recognized but ignored.

	Note that the '''SerialInputs''' mechanism is designed to be very generic, and as such it is not necessarily possible to tailor it to the particular protocol your widget uses. For example, BCI2000 will not know how the widget likes to terminate messages unless you explicitly include the terminator bytes (so, if <code>shutdown</code> and <code>shutdown-gracefully</code> are both configured, the longer command will never be recognized: BCI2000 will greedily recognize and obey <code>shutdown</code> before attempting to move on to <code>-gracefully</code>). The limitations of the '''~~SerialInterface~~''' table also become very obvious if the widget sends a byte string that you have omitted from the table. Then, one of two compromises must be accepted (see the description of the '''SkipUnrecognizedBytes''' parameter, below).		Note that the '''SerialInputs''' mechanism is designed to be very generic, and as such it is not necessarily possible to tailor it to the particular protocol your widget uses. For example, BCI2000 will not know how the widget likes to terminate messages unless you explicitly include the terminator bytes (so, if <code>shutdown</code> and <code>shutdown-gracefully</code> are both configured, the longer command will never be recognized: BCI2000 will greedily recognize and obey <code>shutdown</code> before attempting to move on to <code>-gracefully</code>). The limitations of the '''SerialInputs''' table also become very obvious if the widget sends a byte string that you have omitted from the table. Then, one of two compromises must be accepted (see the description of the '''SkipUnrecognizedBytes''' parameter, below).

	===SkipUnrecognizedBytes===		===SkipUnrecognizedBytes===

Jhill: /* SerialInputs */

2025-06-16T14:34:13Z

SerialInputs

← Older revision		Revision as of 14:34, 16 June 2025
Line 90:		Line 90:
	A given byte string is allowed to appear more than once in the table, to trigger multiple Events simultaneously. The Event name (second column) is allowed to be blank, to enable a particular byte string to be recognized but ignored.		A given byte string is allowed to appear more than once in the table, to trigger multiple Events simultaneously. The Event name (second column) is allowed to be blank, to enable a particular byte string to be recognized but ignored.

	Note that the '''SerialInputs''' mechanism is designed to be very generic, and as such it is not necessarily possible to tailor it to the particular protocol your widget uses. For example, BCI2000 will not know how the widget likes to terminate messages unless you explicitly include the terminator bytes (so, if <code>shutdown</code> and <code>shutdown-gracefully</code> are both configured, the longer command will never be recognized: BCI2000 will greedily recognize and obey <code>shutdown</code> ~~and then attempt~~ to move on to <code>-gracefully</code>). The limitations of the '''SerialInterface''' table also become very obvious if the widget sends a byte string that you have omitted from the table. Then, one of two compromises must be accepted (see the description of the '''SkipUnrecognizedBytes''' parameter, below).		Note that the '''SerialInputs''' mechanism is designed to be very generic, and as such it is not necessarily possible to tailor it to the particular protocol your widget uses. For example, BCI2000 will not know how the widget likes to terminate messages unless you explicitly include the terminator bytes (so, if <code>shutdown</code> and <code>shutdown-gracefully</code> are both configured, the longer command will never be recognized: BCI2000 will greedily recognize and obey <code>shutdown</code> before attempting to move on to <code>-gracefully</code>). The limitations of the '''SerialInterface''' table also become very obvious if the widget sends a byte string that you have omitted from the table. Then, one of two compromises must be accepted (see the description of the '''SkipUnrecognizedBytes''' parameter, below).

	===SkipUnrecognizedBytes===		===SkipUnrecognizedBytes===

Jhill: /* SkipUnrecognizedBytes */

2025-06-16T14:32:53Z

SkipUnrecognizedBytes

← Older revision		Revision as of 14:32, 16 June 2025
Line 95:		Line 95:
	This boolean parameter determines what happens if you are using the '''SerialInputs''' table to recognize messages from the widget, and the widget sends you a string that is not recognized. Either choice can have unfortunate consequences, depending on your widget's protocol.		This boolean parameter determines what happens if you are using the '''SerialInputs''' table to recognize messages from the widget, and the widget sends you a string that is not recognized. Either choice can have unfortunate consequences, depending on your widget's protocol.

	If the '''SkipUnrecognizedBytes''' parameter is set to false (unchecked), then the data coming from the widget will continue to build into an ever-lengthening unrecognized command: BCI2000 will not recognize another '''SerialInputs''' byte string at all ~~for~~ the ~~rest~~ of ~~this session~~.		If the '''SkipUnrecognizedBytes''' parameter is set to false (unchecked), then the data coming from the widget will continue to build into an ever-lengthening unrecognized command: BCI2000 will not recognize another '''SerialInputs''' byte string at all until the SerialInterface is reset (which happens at the start of a run if SerialInterface is running as an Extension, or when Set Config is pressed if you are running SerialWidgetADC).

	If '''SkipUnrecognizedBytes''' is set to true (checked), then it will be possible to discard unrecognized bytes and match a known string, but with the danger that substrings of ~~unrecognized~~ commands could be falsely recognized as commands. For example, if you have enabled '''SkipUnrecognizedBytes''', and you have listed the command <code>arm_stimulator</code> in '''SerialInputs''' but ''not'' <code>disarm_stimulator</code>, and the widget then happens to send <code>disarm_stimulator</code>, then BCI2000 will discard the bytes <code>dis</code> and recognize <code>arm_stimulator</code>, leading to the opposite of the intended effect. Clearly, this is a function of how the widget's protocol is designed. To avoid such situations, you must either (a) ensure that the entries in the '''SerialInputs''' table exhaustively cover the repertoire of possible widget outputs, or (b) accept the consequences of disabling '''SkipUnrecognizedBytes'''. An even ~~better~~ option, if possible, is (c) to leave the '''SerialInputs''' table empty and re-program your widget to send BCI2000 event descriptors directly as text (see the [[#State Variables\|State Variables]] section, below).		If '''SkipUnrecognizedBytes''' is set to true (checked), then it will be possible to discard unrecognized bytes and match a known string, but with the danger that substrings of ''un''recognized commands could be falsely recognized as commands. For example, if you have enabled '''SkipUnrecognizedBytes''', and you have listed the command <code>arm_stimulator</code> in '''SerialInputs''' but ''not'' <code>disarm_stimulator</code>, and the widget then happens to send <code>disarm_stimulator</code>, then BCI2000 will discard the bytes <code>dis</code> and recognize <code>arm_stimulator</code>, leading to the opposite of the intended effect. Clearly, this is a function of how the widget's protocol is designed. To avoid such situations, you must either (a) ensure that the entries in the '''SerialInputs''' table exhaustively cover the repertoire of possible widget outputs (don't worry, if a known longer string gets matched, its substrings will not get matched), or (b) accept the consequences of disabling '''SkipUnrecognizedBytes'''. An even more robust option, if possible, is (c) to leave the '''SerialInputs''' table empty and re-program your widget to send BCI2000 event descriptors directly as text (see the [[#State Variables\|State Variables]] section, below).

	===SerialOutputs===		===SerialOutputs===

Jhill at 23:34, 13 June 2025

2025-06-13T23:34:14Z

← Older revision		Revision as of 23:34, 13 June 2025
Line 17:		Line 17:
	===Source Code Revisions===		===Source Code Revisions===
	*Initial development: r7523		*Initial development: r7523
	*Known to compile under: ~~r8887~~		*Known to compile under: r8888
	*Broken since: --		*Broken since: --

Jhill: /* State Variables */

2025-06-13T17:32:08Z

State Variables

← Older revision		Revision as of 17:32, 13 June 2025
Line 126:		Line 126:
	Note that it is not necessary for the Event in question to have been defined by the widget itself—it could have been added by one of the other filters and loggers, or in your [[User_Reference:Operator_Module_Scripting\|BCI2000 script]] using [[User_Reference:Operator_Module_Scripting#ADD_EVENT_<name>_<bit_width>_<initial_value>\|an <code>ADD EVENT</code> command]] before the <code>STARTUP SYSTEM</code> line. This means you do not necessarily have to implement the widget's response to a <code>--PublishCommand</code>, even if you are planning to use the widget to log Events.		Note that it is not necessary for the Event in question to have been defined by the widget itself—it could have been added by one of the other filters and loggers, or in your [[User_Reference:Operator_Module_Scripting\|BCI2000 script]] using [[User_Reference:Operator_Module_Scripting#ADD_EVENT_<name>_<bit_width>_<initial_value>\|an <code>ADD EVENT</code> command]] before the <code>STARTUP SYSTEM</code> line. This means you do not necessarily have to implement the widget's response to a <code>--PublishCommand</code>, even if you are planning to use the widget to log Events.

	If you cannot re-program the widget at all, you may still have some (limited) options for triggering Events in response to messages from the widget, via the '''~~SerialInterface~~''' parameter.		If you cannot re-program the widget at all, you may still have some (limited) options for triggering Events in response to messages from the widget, via the '''SerialInputs''' parameter.

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

Jhill: /* State Variables */

2025-06-13T17:31:40Z

State Variables

← Older revision		Revision as of 17:31, 13 June 2025
Line 125:		Line 125:

	Note that it is not necessary for the Event in question to have been defined by the widget itself—it could have been added by one of the other filters and loggers, or in your [[User_Reference:Operator_Module_Scripting\|BCI2000 script]] using [[User_Reference:Operator_Module_Scripting#ADD_EVENT_<name>_<bit_width>_<initial_value>\|an <code>ADD EVENT</code> command]] before the <code>STARTUP SYSTEM</code> line. This means you do not necessarily have to implement the widget's response to a <code>--PublishCommand</code>, even if you are planning to use the widget to log Events.		Note that it is not necessary for the Event in question to have been defined by the widget itself—it could have been added by one of the other filters and loggers, or in your [[User_Reference:Operator_Module_Scripting\|BCI2000 script]] using [[User_Reference:Operator_Module_Scripting#ADD_EVENT_<name>_<bit_width>_<initial_value>\|an <code>ADD EVENT</code> command]] before the <code>STARTUP SYSTEM</code> line. This means you do not necessarily have to implement the widget's response to a <code>--PublishCommand</code>, even if you are planning to use the widget to log Events.

			If you cannot re-program the widget at all, you may still have some (limited) options for triggering Events in response to messages from the widget, via the '''SerialInterface''' parameter.

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