DEVICE: How To: Serial Port Communication [25287]

This article applies to:

E-Prime 3.0

E-Prime 2.0

E-Prime 1.x

Detail

What Device am I Using?
A Serial Port is a physical interface on a computer that can send information from one object to another. Unlike a Parallel Port, a Serial Port can send information from one device to another one bit at a time. This device also supports a wider range of communication options than a Parallel Port.

The first important thing to keep in mind when identifying a port as a Serial port is that Serial ports often come in a variety of shapes and sizes.

For example, a serial port can have 25 pins that can be used to send varying types of information to an external device. The name, DB25 relates to how many pins the Serial port uses to communicate with an external device. Other Serial port configurations have fewer pins but are still able to send and receive the same signals.

Regardless of the specific configuration of your Serial port, there are a few important pieces of information you will want to pull from the device on your computer in order facilitate communication with this device in E-Prime.

Specific Information about This Device
To communicate through a Serial port in E-Prime you will need a few important pieces of information about your Serial port. The information necessary to successfully communicate with the Serial port is the COM Port address, Bits per second, Data Bits, Parity, and Stop Bits. All this information reflects required fields for a Serial Device in E-Prime. To find this information you will have to first open your computer’s Control Panel. Under the computer’s Control Panel, please select the Hardware and Sound Category. The Hardware and Sound category should contain a link called Device Manager, please click on that link to access your computer’s Device Manager. The computer’s Device Manager, on most computers, can only be accessed by the computer’s Administrator.

Once you have accessed the computer’s Device Manager, please locate the category called “Ports COM & LPT”. This is where the information from the Serial port is held. Please click on this category to expand it and its values. Depending on the type of hardware that you have installed on your computer, the values found under this “Ports COM & LPT” category will look different. Regardless of the number of hardware communication devices found under this category, the Serial port is immediately recognizable because the name of the device will be followed by a COM number.

Once you have located the Serial port in E-Prime’s Device Manager, you will need to access the properties of this device. To do this, please either double click on it or right click and select “Properties”.

Where does this information go in E-Prime?
Adding a Serial Device
Now that you have gathered the necessary information about the Serial port, you will need to use this information in E-Prime. To utilize this information, you will first want to add a Serial Port Device into your E-Prime experiment. You can do this by first opening your experiment in E-Studio and clicking on the Experiment object at the top of E-Studio’s Structure window. This will open the experiment’s Properties pages. In the experiment’s Properties pages, please click on the Devices tab. Under the Devices tab, you will want to add a Serial Port device by clicking on the “Add…” button at the bottom of the window.

After clicking the “Add…” button you will be taken to the Add Devices page. Please click on the Serial Device and click the OK button. The Serial Device will now be added to the list of enabled devices for your experiment.

Once you have added a Serial Device to your experiment, the last thing you will have to do to enable communication is to use the information found in the last section and input in to the Serial Device’s Properties page. To do this, please either double click on the Serial Device or click on it once and click on the “Edit…” button at the bottom of the Devices tab. I
Once you have set up the Serial Device’s properties as shown above you will need to use this Serial device to send signals.

How to send a signal using a Serial port
There are several ways to send signals to a Serial port. Before beginning to write script or adding devices to your experiment to send signals, it is important to determine what type of signals you are sending. First, take into consideration what device you are communicating with. Many such as EEG devices and even some response boxes listen for a very specific signal, string or set of numbers in order to accomplish that device’s specific task. Because of these device-specific stipulations, the first step in determining what signal to send through a Serial port should always be to check the type of signal your device is listening for. Once this is established, determining what Serial method is best becomes easy.

There are several ways to send information to a Serial port. The following chart shows all of the possibilities of signals along with a brief description of these. Each one of these sections, including syntax can be found in a short paragraph under the table:

Method	Description
WriteBytes	Writes an array of bytes to the Serial device.
WriteByte	Writes a byte to the Serial device.
WriteInteger	Writes integer data to the Serial device.
WriteLong	Writes Long data to the Serial device.
WriteString	Writes String data to the Serial device.

Not only can Serial information be sent through standard means of scripting, but it can also be sent through a Task Event of an object (E-STUDIO: Using Task Events [22862]). To do this, an Event must be added to an object. Then a Serial Task needs added with an Action (e.g., WritieLong). Lastly, Task Event's parameters need specified.

WriteBytes
The most important thing to keep in mind about using the WriteBytes command is that it sends an array of integers across the Serial device. Unlike the WriteInteger and WriteLong methods that only sends one Integer or Long of information at a time, this method sends multiple instances of Integer data at a time.

Syntax
SerialDevice.WriteBytes arrData, nCount

arrData – This parameter is the array of integers that you would like to send to the Serial Device.
nCount – This parameter is optional and represents the number of elements from the array that you would like to send to the Serial port. If this parameter is excluded, E-Prime will send the entire array’s worth of data to the Serial device.

Example

Dim arrData(2) As Integer

arrData(0) = 1
arrData(1) = 2
arrData(2) = 3

Serial.WriteBytes arrData, 1

In this example script, an array named arrData is declared. Since array definition begins at 0, this array has three seats to it. The script below this defines the integer values at each seat of the array. In this case, the array information that will be sent to the Serial device is 1, 2 and 3. The final part of this sample demonstrates the proper syntax of using the WriteBytes command on a Serial Device called Serial to send only the first two seats of the array to the Serial port. In this instance, only the 1 and 2 will be sent the Serial port.

WriteByte
This command writes only one Byte worth of information across the Serial device.

Syntax
SerialDevice.WriteByte nData

nData – This parameter is the integer that is going to be written to the computer’s Socket. This information can be a variable (as demonstrated), attribute, or integer.

Example

Serial.WriteByte 255

This sample demonstrates how to send a signal of 255 to a Serial device named Serial. In this sample the nData parameter is an Integer data type. Only a single byte is sent. It is also possible to use a variable or use the “c.GetAttrib” statement to write an attribute to the Serial.

WriteInteger
This command writes only one Integer’s worth of information across the Serial port. This integer is two bytes worth of data.

Syntax
SerialDevice.WriteInteger nData

nData – This parameter is the integer that is going to be written to the computer’s Serial Port. This information can be a variable (as demonstrated), attribute or integer.

Example

Serial.WriteInteger 255

This sample demonstrates how to send a signal of 255 to a Serial device called Serial. In this sample the nData parameter is simply an Integer, but it is also possible to use a variable or use the “c.GetAttrib” statement to write an attribute to the Serial port.

WriteLong
Writes a Long’s worth of data to the Serial port. Long data represents four bytes worth of data.

Syntax
SerialDevice.WriteLong nData

nData – This parameter is the integer that is going to be written to the computer’s Serial Port. This information can be a variable (as demonstrated), attribute or integer.

Example

Serial.WriteLong 854775807

This sample demonstrates how to send a signal of 854,775,807 to a Serial device called Serial. In this sample the nData parameter is simply a Long, but it is also possible to use a variable or use the “c.GetAttrib” statement to write an attribute to the Serial port.

WriteString
Unique to the Serial port, you are actually able to write strings worth of information to an external device using E-Prime. This method writes whatever string you wish to the Serial port.

Syntax
SerialDevice.WriteString StrData, nCount

StrData – This parameter is the string data that will be sent across the Serial port. This necessary parameter needs to be contained within quotation marks. This is how E-Prime determines that the signal is String data.
nCount - This parameter is optional and determines how many characters of the String will be sent to the Serial port.

Example

Serial.WriteString "Send DoNotSend", 4

In this sample, String data is being sent to a Serial Device called Serial. This sample contains the nCount parameter. In this case, only the first 4 characters of this String will be sent across the Serial port. This way, the signal will look like this “Send” instead of the full “Send DoNotSend” string.

How to receive a signal using a Serial port
A powerful feature of E-Prime is its ability to not only send signals to external devices but to receive signals as well. Just like sending signals to an external device, it is important to keep in mind what signals you will be receiving from this external device. This is especially important when receiving signals from an external device because it is important to tell E-Prime exactly what signal it is supposed to be listening for. The following chart shows all of the possibilities of signals along with a brief description of these. Each one of these sections, including syntax can be found in a short paragraph under the table:

Method	Description
ReadBytes	Reads Integer data from the Serial device and inputs it directly into an array
ReadInteger	Reads Integer data from the Serial device
ReadLong	Reads Long data from the Serial device
ReadString	Reads String data from the Serial device

ReadBytes
This method reads integer data from the Serial port’s input cue and loads it into an array. Each element of this array represents one byte worth of data that is going to be read into the experiment. If the requested amount of bytes is more than what is available, only elements in the array available are filled with data.

Syntax
nRead = SerialDevice.ReadBytes (arrData, nCount)
nRead – is the value returned from the WriteBytes method that represents the actual number of bytes that have been read into the array.
arrData – an array of integers that represents the array to which the data that has been read from the Serial port’s input cue will be written.
nCount - an optional parameter that specifies how many bytes to store into the array. If this optional parameter is omitted, the entire array size is required.

Example

Dim nRead As Integer
Dim arrData(3) As Integer

nRead = Serial.ReadBytes( arrData, 2)

This sample first defines two very important variables called “nRead” and “arrData”. The “nRead” variable will hold the number of bytes that are written to the Serial port and the “arrData” variable is an array that will hold the values that are sent into the Serial port. The remainder of this sample demonstrates how to use each of these parameters to read Bytes of data that are sent to the Serial port. The important thing about this sample is that it will only read instances 0, 1 and 2 that come into the Serial port because of the “nCount” parameter at the end of the statement.

ReadInteger
This method reads only one integer from the Serial port’s input queue into a variable in the experiment. If the integer that comes into the Serial device is less than the required two bytes, only one byte will be received.

Syntax
nRead = SerialDevice.ReadInteger( nData)

nRead – returns an integer representing the actual number of bytes that have been read from the Serial port’s input queue.
nData – returns the integer that has been written to the Serial port’s input queue.

Example

Dim nData As Integer
Dim nRead As Long

nRead = Serial.ReadInteger(nData)

This sample first defines two very important variables. The first variable is “nData”. This variable represents the Integer data that the external device is sending to E-Prime. The “nRead” variable will hold the number of bytes of the signal that has been sent through the Serial port. The remainder of the sample demonstrates how to use these variables to read the Integer information that is sent through the Serial port.

ReadLong
This method will read a Long’s worth of data from the Serial port’s input queue into a variable in the experiment. If the Long that comes into the Serial device is less than the required four bytes, all available data will be retrieved.

Syntax
nRead = SerialDevice.ReadLong( nData)

nRead – returns an integer representing the actual number of bytes that have been read from the Serial port’s input queue.
nData – returns the Long that has been written to the Serial port’s input queue

Example

Dim nData As Long
Dim nRead As Integer

nRead = Serial.ReadLong(nData)

This sample first defines two very important variables. The first variable is “nData”. This variable represents the Long data that the external device is sending to E-Prime. The “nRead” variable will hold the number of bytes of the signal that has been sent through the Serial port. The remainder of the sample demonstrates how to use these variables to read the Long information that is sent through the Serial port.

ReadString
The ReadString method reads a string of bytes from the serial device’s input queue. Each character in the string that is sent over represents a byte read from the serial device’s input queue. Along with this method, there is also the opportunity to use the Mid and Asc functions to return an integer representation for the data read from the Serial device’s input queue.

Syntax
nRead = SerialDevice.ReadString( strData, nCount)

nRead – returns an integer representing the actual number of bytes that have been read from the Serial port’s input queue.
strData – is an array of integers representing the array to whch the data read will be stored.
nCount – an optional integer specifying how many bites to retrieve. If omitted, then 1K (1024 bytes) is requested

Example

Dim strData(5) As String
Dim nRead As Integer

nRead = Serial.ReadString(strData)

This sample first defines two very important variables. The first variable is “strData”. This variable is an array that will hold the String data sent from the Serial port. In this case, it will hold 5 bytes of data. The “nRead” variable will hold the number of bytes of the signal that has been sent through the Serial port. The remainder of the sample demonstrates how to use these variables to read the String information that is sent through the Serial port. Please notice that the nCount parameter has been omitted from this example. This means that E-Prime will request roughly 1024 bytes from the Serial port’s input queue.

For further information on scripting using E-Basic, please refer to the E-Prime Command Reference (https://pstnet.com/ecr).

Articles in this section

Comments

Articles in this section

Related articles