<commit_before>The NeuroServer protocol
as implemented by nsd

by <NAME> (<EMAIL>)

The NeuroServer is a network infrastructure to support a constellation of
data collection, visualization, and feedback devices oriented towards
EEG data.  The EEG data is sent in an EDF-oriented format, which has
already been well specified in, for instance,
http://www.hsr.nl/edf/edf_spec.htm

(n.b. in this document, \n denotes a newline character)

The nsd protocol is TCP-based and line-oriented.  By default, the nsd server
binds to all network addresses and accepts connections on port 8336.  The
nsd prints no welcome banner when new clients connect.  All
commands are a single line of text.  For any command, the server
first returns a line indicating general success or failure:

200 OK

is for successful commands, and any other code should be assumed an error.
At this point, the only error code is

400 BAD REQUEST

After the success/failure code, some commands will produce additional
output.  This output is generally a single line.

Every client that is connected has a current "role" status.  Initially,
it is set to "Unknown."  There are three other roles that may be
assumed, with three different commands:

display       to enter Display role
eeg           to enter EEG role
control       to enter Controller role

In order for a client to determine its current role, it can use the

role          to print out the current role for this client

Another important command available to all roles is

status        to print a table showing the client id numbers and roles for all

For example, if you do
display
status

You will get from the nsd:

200 OK
200 OK
1 clients connected
0:Display

For EEG role devices, these are useful:

setheader <EDFHeaderPacket>\n

For example,
setheader 0                                                                                                                                                                       26.01.0418.36.01768     NEUROSD                                     -1      1       2   Elec 00         Elec 01         Active Electrode                                                                Active Electrode                                                                uV      uV      0       0       1023    1023    0       0       1023    1023    HP: DC; LP:  49 Hz                                                              HP: DC; LP:  49 Hz                                                              2048    2048    Reserved                        Reserved                        \n

Would use a 2048-Hz sampling rate dual-channel format, which ranges from
0 to 1023 in each channel.

Another option for EEG's alone is the data frame command, spelled '!':

! <packetCounter> <channelCount> <sample[0]> <sample[1]> ... \n

For instance,
! 45 2 123 125
Means a sample frame with 2 channels and packet counter 45, with
two data channels: 123 is sampled from one, and 125 from the other.

In order to view data, a Display role must be used.  Display's have
the option to use the watch and unwatch commands:

watch <clientIndex>

You can find the correct client index by using the status command.
Usually, the EEG device is the first client to connect, so it will
be numbered 0.  Therefore, the command
watch 0\n
will be sufficient for simple single-source compatibility.  The opposite
command is called

unwatch <clientIndex>

The "watch" flag toggles whether or not this client receives samples
originating from a particular EEG client.  A Display may watch none,
one, or many different EEG clients.

In order to get the sampling and other header information, the command

getheader <clientIndex>

can be used.  It will write the entire header followed by a line ending.
Here again,
getheader 0\n
can be used for basic testing.

If a Display is watching an EEG, it will receive special messages
whenever a new data frame comes.  These messages will be single lines
of the form:

! <clientIndex> <packetCounter> <channelCount> <sample[0]> <sample[1]> ... \r\n

A Display must be ready to accept these interspersed with any other
command results at any time.

This entire protocol is implemented in the "nsd" NeuroServer component,
and parts are used by every NeuroServer compatible application.  Example
protocol traces are shown in the tests/common.rb source file.

Acknowledgments:
	Helpful comments from the openeeg-software-dev list, particularly
<NAME>, whose concrete suggestions have helped shape this protocol.

<commit_msg>*** empty log message ***<commit_after>The NeuroServer protocol
as implemented by nsd

by <NAME> (<EMAIL>)

The NeuroServer is a network infrastructure to support a constellation of
data collection, visualization, and feedback devices oriented towards
EEG data.  The EEG data is sent in an EDF-oriented format, which has
already been well specified in, for instance,
http://www.hsr.nl/edf/edf_spec.htm

(n.b. in this document, \n denotes a newline character)

The nsd protocol is TCP-based and line-oriented.  By default, the nsd server
binds to all network addresses and accepts connections on port 8336.  The
nsd prints no welcome banner when new clients connect.  All
commands are a single line of text.  For any command, the server
first returns a line indicating general success or failure:

200 OK

is for successful commands, and any other code should be assumed an error.
At this point, the only error code is

400 BAD REQUEST

After the success/failure code, some commands will produce additional
output.  This output is generally a single line.

Every client that is connected has a current "role" status.  Initially,
it is set to "Unknown."  There are three other roles that may be
assumed, with three different commands:

display       to enter Display role
eeg           to enter EEG role
control       to enter Controller role

In order for a client to determine its current role, it can use the

role          to print out the current role for this client

Another important command available to all roles is

status        to print a table showing the client id numbers and roles for all

For example, if you do
display
status

You will get from the nsd:

200 OK
200 OK
1 clients connected
0:Display

For EEG role devices, these are useful:

setheader <EDFHeaderPacket>\n

For example,
setheader 0                                                                                                                                                                       26.01.0418.36.01768     NEUROSD                                     -1      1       2   Elec 00         Elec 01         Active Electrode                                                                Active Electrode                                                                uV      uV      0       0       1023    1023    0       0       1023    1023    HP: DC; LP:  49 Hz                                                              HP: DC; LP:  49 Hz                                                              2048    2048    Reserved                        Reserved                        \n

Would use a 2048-Hz sampling rate dual-channel format, which ranges from
0 to 1023 in each channel.

Another option for EEG's alone is the data frame command, spelled '!':

! <packetCounter> <channelCount> <sample[0]> <sample[1]> ... \n

For instance,
! 45 2 123 125
Means a sample frame with 2 channels and packet counter 45, with
two data channels: 123 is sampled from one, and 125 from the other.

In order to view data, a Display role must be used.  A Display can
use the watch, unwatch, and getheader commands.

watch <clientIndex>

You can find the correct client index by using the status command.
Usually, the EEG device is the first client to connect, so it will
be numbered 0.  Therefore, the command
watch 0\n
will be sufficient for simple single-source compatibility.  The opposite
command is called

unwatch <clientIndex>

The "watch" flag toggles whether or not this client receives samples
originating from a particular EEG client.  A Display may watch none,
one, or many different EEG clients.

In order to get the sampling and other header information, the command

getheader <clientIndex>

can be used.  It will write the entire header followed by a line ending.
Here again,
getheader 0\n
can be used for basic testing.

If a Display is watching an EEG, it will receive special messages
whenever a new data frame comes.  These messages will be single lines
of the form:

! <clientIndex> <packetCounter> <channelCount> <sample[0]> <sample[1]> ... \r\n

A Display must be ready to accept these interspersed with any other
command results at any time.

This entire protocol is implemented in the "nsd" NeuroServer component,
and parts are used by every NeuroServer compatible application.  Example
protocol traces are shown in the tests/common.rb source file.

Acknowledgments:
	Helpful comments from the openeeg-software-dev list, particularly
<NAME>, whose concrete suggestions have helped shape this protocol.


{'fraction_non_alphanumeric': 0.04047909504269713, 'fraction_numerical': 0.02373294887434845, 'mean_word_length': 2.304507145474533, 'pattern_counts': {'":': 0, '<': 35, '<?xml version=': 0, '>': 35, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 42, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5063763', 'n_tokens_mistral': 2347, 'n_tokens_neox': 2114, 'n_words': 1235}