This demo explores ASCII read and write operations with a UDP object.
The information obtained for this demonstration was prerecorded. Therefore, you do not need an actual instrument to learn about ASCII read and write operations using a UDP object. The instrument used was an echoserver on a Linux O/S PC. An echoserver is a service available from the O/S that returns to the sender's address and port, the same bytes it receives from the sender.
These functions are used when reading and writing text:
FPRINTF - Write text to instrument.
FSCANF - Read data from instrument and format as
text.These properties are associated with reading and writing text:
ValuesReceived - Specifies the total number of values
read from the instrument.
ValuesSent - Specifies the total number of values
sent to the instrument.
InputBufferSize - Specifies the total number of bytes
that can be queued in the input buffer
at one time.
OutputBufferSize - Specifies the total number of bytes
that can be queued in the output buffer
at one time.
Terminator - Character used to terminate commands
sent to the instrument.To begin, create a UDP object associated with the host name daqlab11, port 7. The host name is assigned by your network administrator. Port 7 is the port number for the echoserver.
>> u = udp('daqlab11', 7);
>> uUDP Object : UDP-daqlab11
Communication Settings
RemotePort: 7
RemoteHost: daqlab11
Terminator: 'LF'% Communication State
Status: closed
RecordStatus: off Read/Write State
TransferStatus: idle
BytesAvailable: 0
ValuesReceived: 0
ValuesSent: 0Before you can perform a read or write operation, you must connect the UDP object to the instrument with the FOPEN function. If the object was successfully connected, its Status property is automatically configured to open.
>> fopen(u) >> get(u, 'Status')
ans =
open
You use the FPRINTF function to write ASCII data to the instrument. For example, write a string to the echoserver.
>> fprintf(u, 'Request Time')
By default, the FPRINTF function operates in a synchronous mode. This means that FPRINTF blocks the MATLAB command line until one of the following occurs:
By default the FPRINTF function writes ASCII data using the %s\n format. All occurrences of \n in the command being written to the instrument are replaced with the Terminator property value. When using the default format, %s\n, all commands written to the instrument will end with the Terminator character.
For the previous command, the linefeed (LF) is sent after 'Request Time' is written to the instrument, thereby indicating the end of the command.
You can also specify the format of the command written by providing a third input argument to FPRINTF. The accepted format conversion characters include: d, i, o, u, x, X, f, e, E, g, G, c, and s.
For example, the display command 'Request Time' previously shown can be written to the instrument using two calls to FPRINTF.
>> fprintf(u, '%s', 'Request '); >> fprintf(u, '%s\n', 'Time');
The Terminator character indicates the end of the command and is sent after the last call to FPRINTF.
The OutputBufferSize property specifies the maximum number of bytes that can be written to the instrument at once. By default, OutputBufferSize is 512.
>> get(u, 'OutputBufferSize')
ans =
512
If the command specified in FPRINTF contains more than 512 bytes, an error is returned and no data is written to the instrument.
The ValuesSent property indicates the total number of values written to the instrument since the object was connected to the instrument.
>> get(u, 'ValuesSent')
ans =
26
Now, remove any data that was returned from the echoserver and captured by the UDP object.
>> flushinput(u);
UDP sends and receives data in blocks that are called datagrams. Each time you write or read data with a UDP object, you are writing or reading a datagram. For example, a datagram with 13 bytes (12 ASCII bytes plus the LF terminator) is sent to the echoserver.
>> fprintf(u, 'Request Time');
The echoserver will send back a datagram containing the same 13 bytes.
You use the FSCANF function to read ASCII data from the instrument.
>> data = fscanf(u)
data =
Request Time
By default, the FSCANF function reads data using the '%c' format and blocks the MATLAB command line until one of the following occurs:
You can also specify the format of the data read by providing a second input argument to FSCANF. The accepted format conversion characters include: d, i, o, u, x, X, f, e, E, g, G, c, and s.
For example, the string '0.80' sent to the echoserver can be read into MATLAB as a double using the %f format string.
>> fprintf(u, '0.80') >> data = fscanf(u, '%f')
data =
0.8000
>> isnumeric(data)
ans =
1
The DatagramTerminateMode property indicates whether a read operation should terminate when a datagram is received. By default DatagramTerminateMode is on, which means that a read operation terminates when a datagram is received. To read multiple datagrams at once, you can set DatagramTerminateMode to off. In this example, two datagrams are written. Note, only the second datagram sends the Terminator character.
>> fprintf(u, '%s', 'Request Time'); >> fprintf(u, '%s\n', 'Request Time');
Since DatagramTerminateMode is off, FSCANF will read across datagram boundaries until the Terminator character is received.
>> set(u, 'DatagramTerminateMode', 'off') >> data = fscanf(u)
data =
Request TimeRequest Time
The InputBufferSize property specifies the maximum number of bytes that you can read from the instrument. By default, InputBufferSize is 512:
>> get(u, 'InputBufferSize')
ans =
512
The ValuesReceived property is updated by the number of values read from the instrument, including the terminator.
>> get(u, 'ValuesReceived')
ans =
30
If you are finished with the UDP object, disconnect it from the instrument, remove it from memory, and remove it from the workspace.
>> fclose(u); >> delete(u); >> clear u