This demo explores binary 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 binary 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 binary data:
FREAD - Read binary data from instrument. FWRITE - Write binary data to instrument.
These properties are associated with reading and writing binary data:
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.
DatagramTerminateMode - defines how FREAD and FSCANF read
operations terminate.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: 0The 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 FWRITE contains more than 512 bytes, an error is returned and no data is written to the instrument.
In this example 1000 bytes will be written to the instrument. Therefore, the OutputBufferSize is increased to 1000.
>> set(u, 'OutputBufferSize', 1000) >> get(u, 'OutputBufferSize')
ans =
1000
Before 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
Note that the display summary is updated accordingly.
>> u
UDP Object : UDP-daqlab11
Communication Settings
RemotePort: 7
RemoteHost: daqlab11
Terminator: 'LF'% Communication State
Status: open
RecordStatus: off Read/Write State
TransferStatus: idle
BytesAvailable: 0
ValuesReceived: 0
ValuesSent: 0You use the FWRITE function to write binary data to the instrument.
By default, the FWRITE function operates in a synchronous mode. This means that FWRITE blocks the MATLAB command line until one of the following occurs:
By default the FWRITE function writes binary data using the uchar precision. However, the following precisions can also be used:
MATLAB Description 'uchar' unsigned character, 8 bits. 'schar' signed character, 8 bits. 'int8' integer, 8 bits. 'int16' integer, 16 bits. 'int32' integer, 32 bits. 'uint8' unsigned integer, 8 bits. 'uint16' unsigned integer, 16 bits. 'uint32' unsigned integer, 32 bits. 'single' floating point, 32 bits. 'float32' floating point, 32 bits. 'double' floating point, 64 bits. 'float64' floating point, 64 bits. 'char' character, 8 bits (signed or unsigned). 'short' integer, 16 bits. 'int' integer, 32 bits. 'long' integer, 32 or 64 bits. 'ushort' unsigned integer, 16 bits. 'uint' unsigned integer, 32 bits. 'ulong' unsigned integer, 32 bits or 64 bits. 'float' floating point, 32 bits.
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. In the example below, a datagram with 1000 bytes, 4 bytes per integer number, will be sent to the echoserver.
>> fwrite(u, 1:250, 'int32');
When performing a write operation, you should think of the transmitted data in terms of values rather than bytes. A value consists of one or more bytes. For example, one uint32 value consists of four bytes.
The ValuesSent property indicates the total number of values written to the instrument because the object was connected to the instrument.
>> get(u, 'ValuesSent')
ans =
250
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
In the next example, 1000 bytes will be read from the instrument. Configure the InputBufferSize to hold 1000 bytes. Note, the InputBufferSize can be configured only when the object is not connected to the instrument.
>> fclose(u) >> set(u, 'InputBufferSize', 1000) >> get(u, 'InputBufferSize')
ans =
1000
Now that the object is configured to hold the data, you can reopen the connection to the instrument:
>> fopen(u)
You use the FREAD function to read binary data from the instrument.
By default, the FREAD function blocks the MATLAB command line until one of the following occurs:
By default the FREAD function reads data using the uchar precision. However, the following precisions can also be used:
MATLAB Description 'uchar' unsigned character, 8 bits. 'schar' signed character, 8 bits. 'int8' integer, 8 bits. 'int16' integer, 16 bits. 'int32' integer, 32 bits. 'uint8' unsigned integer, 8 bits. 'uint16' unsigned integer, 16 bits. 'uint32' unsigned integer, 32 bits. 'single' floating point, 32 bits. 'float32' floating point, 32 bits. 'double' floating point, 64 bits. 'float64' floating point, 64 bits. 'char' character, 8 bits (signed or unsigned). 'short' integer, 16 bits. 'int' integer, 32 bits. 'long' integer, 32 or 64 bits. 'ushort' unsigned integer, 16 bits. 'uint' unsigned integer, 32 bits. 'ulong' unsigned integer, 32 bits or 64 bits. 'float' floating point, 32 bits.
When performing a read operation, you should think of the received data in terms of values rather than bytes. A value consists of one or more bytes. For example, one uint32 value consists of four bytes.
Read binary data from the instrument. For example, read one datagram consisting of 250 integers from the instrument.
>> fwrite(u, 1:250, 'int32'); >> data = fread(u, 250, 'int32');
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 to the echoserver.
>> fwrite(u, 1:125, 'int32'); >> fwrite(u, 1:125, 'int32');
Because DatagramTerminateMode is off, FREAD will read across datagram boundaries until 250 integers have been received.
>> set(u, 'DatagramTerminateMode', 'off') >> data = fread(u, 250, 'int32'); >> size(data)
ans =
250 1
The ValuesReceived property is updated by the number of values read from the instrument.
>> get(u, 'ValuesReceived')
ans =
250
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