Programming Reference:Events - Revision history

Mellinger: /* Example */

2022-08-12T14:35:19Z

Example

← Older revision		Revision as of 14:35, 12 August 2022
Line 62:		Line 62:
	BCIEvent(PrecisionTime::Now()+5) << "Event3 " << currentValue; // Event3 is time stamped here with a delayed time stamp		BCIEvent(PrecisionTime::Now()+5) << "Event3 " << currentValue; // Event3 is time stamped here with a delayed time stamp
	...		...
	} // MyEvent and Event3 are sent here		} // MyEvent and Event3 are sent here

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

Mellinger: /* Limitations */

2022-08-12T14:31:22Z

Limitations

← Older revision		Revision as of 14:31, 12 August 2022
Line 22:		Line 22:
	==Limitations==		==Limitations==
	*Time stamps have millisecond resolution. Up to sampling rates of 1kHz, this is not a practical restriction though.		*Time stamps have millisecond resolution. Up to sampling rates of 1kHz, this is not a practical restriction though.
	*~~The~~ upper limit of temporal resolution is determined by the amplifier's maximum sampling rate.		*Apart from the 1kHz limit given by time stamp resolution, the upper limit of temporal resolution is determined by the amplifier's maximum sampling rate.
	*Association of event time stamps with sample positions cannot be more accurate than [[User Reference:Timing\|time stamps assigned to data blocks]] by the data acquisition module. If data transmission latency between data acquisition hardware, and its associated jitter, are large compared to a single sample's duration, then event positions cannot be expected to be precise. Still, for data acquisition devices that are connected directly to the machine running the data acquisition module (i.e., not over a network connection), and for sampling rates below 1kHz, transmission latency and jitter may be expected to be below a sample's duration.		*Association of event time stamps with sample positions cannot be more accurate than [[User Reference:Timing\|time stamps assigned to data blocks]] by the data acquisition module. If data transmission latency between data acquisition hardware, and its associated jitter, are large compared to a single sample's duration, then event positions cannot be expected to be precise. Still, for data acquisition devices that are connected directly to the machine running the data acquisition module (i.e., not over a network connection), and for sampling rates below 1kHz, transmission latency and jitter may be expected to be below a sample's duration.
	*Event time stamps must refer to the same physical time base that is used to stamp acquired data packets. This limits the use of events to BCI2000 modules that run on the same machine as the data acquisition module. To ensure correct operation also in situations where processing modules are distributed across multiple machines in a network, the event API may be used only in data acquisition modules.		*Event time stamps must refer to the same physical time base that is used to stamp acquired data packets. This limits the use of events to BCI2000 modules that run on the same machine as the data acquisition module. To ensure correct operation also in situations where processing modules are distributed across multiple machines in a network, the event API may be used only in data acquisition modules.

Mellinger: /* Extended Syntax */

2022-06-07T18:09:49Z

Extended Syntax

← Older revision		Revision as of 18:09, 7 June 2022
Line 43:		Line 43:
	==Extended Syntax==		==Extended Syntax==
	bcievent is actually a macro hiding the definition of an object of type BCIEvent. You may create such an object yourself, which is useful if you want to define the time stamp to use rather than have it taken automatically for you.		bcievent is actually a macro hiding the definition of an object of type BCIEvent. You may create such an object yourself, which is useful if you want to define the time stamp to use rather than have it taken automatically for you.

	BCIEvent(PrecisionTime::Now()) << "MyEvent " << value;		BCIEvent(PrecisionTime::Now()) << "MyEvent " << value;
			will match the default behavior: The event is initialized with the current time stamp at creation.
	will ~~do exactly~~ the ~~same as~~ the ~~first example~~.

	BCIEvent(PrecisionTime::Now() + 5) << "MyEvent " << value;		BCIEvent(PrecisionTime::Now() + 5) << "MyEvent " << value;

	will delay the event by 5ms. Be warned, however, that time stamps extending beyond the sample block currently digitized will not work properly, due to the way how events are aligned with data in time.		will delay the event by 5ms. Be warned, however, that time stamps extending beyond the sample block currently digitized will not work properly, due to the way how events are aligned with data in time.

Mellinger: /* Descriptor Syntax */

2022-06-07T18:08:43Z

Descriptor Syntax

@@ Line 40: / Line 40: @@
 *The value field must specify an unsigned integer value that "fits into" the number of bits reserved for the corresponding state variable.
 *Currently, the duration must either be omitted, or 0. When mapping the event to a state variable, a duration of 0 means that the state variable is set to the specified value for a single sample only, and to zero for subsequent samples. A non-specified duration means that the state variable is changed, and keeps its value for subsequent samples.
 ==Example==

Mellinger: /* Example */

2022-06-07T18:06:55Z

Example

← Older revision		Revision as of 18:06, 7 June 2022
Line 53:		Line 53:
	bcievent << "MyEvent " << currentValue; // MyEvent is time stamped here		bcievent << "MyEvent " << currentValue; // MyEvent is time stamped here
	bcievent << "AnotherEvent " << currentValue << std::flush; // AnotherEvent is time stamped and sent here		bcievent << "AnotherEvent " << currentValue << std::flush; // AnotherEvent is time stamped and sent here
			BCIEvent(PrecisionTime::Now()+5) << "Event3 " << currentValue; // Event3 is time stamped here with a delayed time stamp
	...		...
	} // MyEvent is sent here		} // MyEvent and Event3 are sent here

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

Mellinger: /* Example */

2022-06-07T17:43:26Z

Example

← Older revision		Revision as of 17:43, 7 June 2022
Line 44:		Line 44:
	In this example, an event "MyEvent" will be created, its value field set to <tt>currentValue</tt>, and its duration field empty.		In this example, an event "MyEvent" will be created, its value field set to <tt>currentValue</tt>, and its duration field empty.
	Please note that the name is followed with a space character separating name and value.		Please note that the name is followed with a space character separating name and value.
	The event will be time stamped ~~either~~ when ~~the stream~~ is ~~flushed explicitly~~, ~~as indicated for the "AnotherEvent" event, or~~ when ~~the <tt>bcievent</tt> object~~ goes out of scope, ~~as indicated for the "MyEvent" event~~. Unless there is time-consuming code between ~~the <tt>bcievent</tt> statement~~, and the ~~next closing brace~~, there is no need to explicitly ~~flush the <tt>bcievent</tt> stream object~~.		The event will be time stamped when it is created, and will be sent when it goes out of scope, or is flushed explicitly. Unless
			there is time-consuming code between event creation, and the end of scope, there is no need to flush it explicitly.
	#include "BCIEvent.h"		#include "BCIEvent.h"
	~~...~~
	~~using namespace std;~~
	...		...
	{		{
	int currentValue;		int currentValue;
	...		...
	bcievent << "MyEvent " << currentValue;		bcievent << "MyEvent " << currentValue; // MyEvent is time stamped here
	bcievent << "AnotherEvent " << currentValue << flush; // AnotherEvent is time stamped here		bcievent << "AnotherEvent " << currentValue << std::flush; // AnotherEvent is time stamped and sent here
	...		...
	} // MyEvent is ~~time stamped~~ here		} // MyEvent is sent here

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

Nluczak: added clarification on the upper limit of sampling rate

2021-05-28T15:27:44Z

added clarification on the upper limit of sampling rate

← Older revision		Revision as of 15:27, 28 May 2021
Line 22:		Line 22:
	==Limitations==		==Limitations==
	*Time stamps have millisecond resolution. Up to sampling rates of 1kHz, this is not a practical restriction though.		*Time stamps have millisecond resolution. Up to sampling rates of 1kHz, this is not a practical restriction though.
			*The upper limit of temporal resolution is determined by the amplifier's maximum sampling rate.
	*Association of event time stamps with sample positions cannot be more accurate than [[User Reference:Timing\|time stamps assigned to data blocks]] by the data acquisition module. If data transmission latency between data acquisition hardware, and its associated jitter, are large compared to a single sample's duration, then event positions cannot be expected to be precise. Still, for data acquisition devices that are connected directly to the machine running the data acquisition module (i.e., not over a network connection), and for sampling rates below 1kHz, transmission latency and jitter may be expected to be below a sample's duration.		*Association of event time stamps with sample positions cannot be more accurate than [[User Reference:Timing\|time stamps assigned to data blocks]] by the data acquisition module. If data transmission latency between data acquisition hardware, and its associated jitter, are large compared to a single sample's duration, then event positions cannot be expected to be precise. Still, for data acquisition devices that are connected directly to the machine running the data acquisition module (i.e., not over a network connection), and for sampling rates below 1kHz, transmission latency and jitter may be expected to be below a sample's duration.
	*Event time stamps must refer to the same physical time base that is used to stamp acquired data packets. This limits the use of events to BCI2000 modules that run on the same machine as the data acquisition module. To ensure correct operation also in situations where processing modules are distributed across multiple machines in a network, the event API may be used only in data acquisition modules.		*Event time stamps must refer to the same physical time base that is used to stamp acquired data packets. This limits the use of events to BCI2000 modules that run on the same machine as the data acquisition module. To ensure correct operation also in situations where processing modules are distributed across multiple machines in a network, the event API may be used only in data acquisition modules.

Mellinger: /* Descriptor Syntax */

2011-11-08T14:10:01Z

Descriptor Syntax

← Older revision		Revision as of 14:10, 8 November 2011
Line 36:		Line 36:
	<name> <value> [<duration>]		<name> <value> [<duration>]
	Currently, events are mapped to state variables, so the following restrictions apply:		Currently, events are mapped to state variables, so the following restrictions apply:
	*The name field must match the name of a state variable, and that state variable must exist in the system before it appears in an event.		*The name field must match the name of an event kind state variable defined within BEGIN_EVENT_DEFINITIONS/END_EVENT_DEFINITIONS, and that state variable must exist in the system before it appears in an event.
	*The value field must specify an unsigned integer value that "fits into" the number of bits reserved for the corresponding state variable.		*The value field must specify an unsigned integer value that "fits into" the number of bits reserved for the corresponding state variable.
	*Currently, the duration must either be omitted, or 0. When mapping the event to a state variable, a duration of 0 means that the state variable is set to the specified value for a single sample only, and to zero for subsequent samples. A non-specified duration means that the state variable is changed, and keeps its value for subsequent samples.		*Currently, the duration must either be omitted, or 0. When mapping the event to a state variable, a duration of 0 means that the state variable is set to the specified value for a single sample only, and to zero for subsequent samples. A non-specified duration means that the state variable is changed, and keeps its value for subsequent samples.

Mellinger: /* Implementation */

2011-11-07T18:13:11Z

Implementation

← Older revision		Revision as of 18:13, 7 November 2011
Line 13:		Line 13:
	==Implementation==		==Implementation==
	In the current version of BCI2000, events are mapped to [[BCI2000 Glossary#State\|state variables]]. By comparing an event's time stamp to data acquisition time stamps, it is possible to associate events with single samples, and to map an event to a change in a state variable's value.		In the current version of BCI2000, events are mapped to [[BCI2000 Glossary#State\|state variables]]. By comparing an event's time stamp to data acquisition time stamps, it is possible to associate events with single samples, and to map an event to a change in a state variable's value.

			In order to make events available for writing, they must be first declared as in the following example:
			BEGIN_EVENT_DEFINITIONS
			"MyEvent 10 0 0 0",
			END_EVENT_DEFINITIONS
			Here, an event's definition follows the rules applying to the definition of state variables: first, the name is given, then follow bit width and initial value. At the end, a pair of zeros needs to be added.

	==Limitations==		==Limitations==

Mellinger: /* Limitations */

2011-11-07T18:09:09Z

Limitations

← Older revision		Revision as of 18:09, 7 November 2011
Line 17:		Line 17:
	*Time stamps have millisecond resolution. Up to sampling rates of 1kHz, this is not a practical restriction though.		*Time stamps have millisecond resolution. Up to sampling rates of 1kHz, this is not a practical restriction though.
	*Association of event time stamps with sample positions cannot be more accurate than [[User Reference:Timing\|time stamps assigned to data blocks]] by the data acquisition module. If data transmission latency between data acquisition hardware, and its associated jitter, are large compared to a single sample's duration, then event positions cannot be expected to be precise. Still, for data acquisition devices that are connected directly to the machine running the data acquisition module (i.e., not over a network connection), and for sampling rates below 1kHz, transmission latency and jitter may be expected to be below a sample's duration.		*Association of event time stamps with sample positions cannot be more accurate than [[User Reference:Timing\|time stamps assigned to data blocks]] by the data acquisition module. If data transmission latency between data acquisition hardware, and its associated jitter, are large compared to a single sample's duration, then event positions cannot be expected to be precise. Still, for data acquisition devices that are connected directly to the machine running the data acquisition module (i.e., not over a network connection), and for sampling rates below 1kHz, transmission latency and jitter may be expected to be below a sample's duration.
	*Event time stamps must refer to the same physical time base that is used to stamp acquired data packets. This limits the use of events to BCI2000 modules that run on the same machine as the data acquisition module. ~~While the event API is available to all BCI2000 modules, it is advisable to use events in data acquisition modules only, thereby ensuring~~ correct operation also in situations where processing modules are distributed across multiple machines in a network.		*Event time stamps must refer to the same physical time base that is used to stamp acquired data packets. This limits the use of events to BCI2000 modules that run on the same machine as the data acquisition module. To ensure correct operation also in situations where processing modules are distributed across multiple machines in a network, the event API may be used only in data acquisition modules.
	*The <tt>bcievent</tt> asynchronous stream interface should only be called between "StartRun" and "StopRun". Logging events with <tt>bcievent</tt> outside of a run could result in delayed state logging through the <tt>bcievent</tt> interface.		*The <tt>bcievent</tt> asynchronous stream interface should only be called between "StartRun" and "StopRun". Logging events with <tt>bcievent</tt> outside of a run could result in delayed state logging through the <tt>bcievent</tt> interface.