External Interfaces/API

Description of Serial Example

The major tasks performed by serialexample are:

1. Define Variables for Serial Port Configuration and Output

The first five statements define variables for configuring the serial port. The first statement defines the baud rate to be 9600, the second defines number of data bits to be 8, and the third defines the number of stop bits to be 1. The fourth statement defines parity to be off, and the fifth statement defines flow control (handshaking) to be off.

• SerialPort_BAUD_9600 = 9600;
  SerialPort_DATABITS_8 = 8;
  SerialPort_STOPBITS_1 = 1;
  SerialPort_PARITY_NONE = 0;
  SerialPort_FLOWCTRL_NONE = 0;
  

The last variable definition sets the terminator character for writing to the serial port, to a carriage return.

• terminator = char(13);
  

2. Create a CommPortIdentifier Object

Instead of constructors, the javax.comm.CommPortIdentifier class has static methods that return an instance of the class. The example calls one of these, getPortIdentifier, to return a CommPortIdentifier object for port COM1.

• commPort = ... 
  javax.comm.CommPortIdentifier.getPortIdentifier('COM1');
  

3. Open the Serial Port

The example opens the serial port, by calling open on the CommPortIdentifier object commPort. The open call returns a SerialPort object, assigning it to serialPort. The first argument to open is the name (owner) for the port, the second argument is the name for the port, and the third argument is the number of milliseconds to wait for the open.

• serialPort = open(commPort, 'serial', 1000);
  

4. Configure the Serial Port

The next three statements call configuration methods on the SerialPort object serialPort. The first statement calls setSerialPortParams to set the baud rate, data bits, stop bits, and parity. The next two statements call setFlowControlMode to set the flow control, and then enableReceiveTimeout to set the timeout for receiving data.

• setSerialPortParams(serialPort, SerialPort_BAUD_9600,...
  SerialPort_DATABITS_8, SerialPort_STOPBITS_1,...
  SerialPort_PARITY_NONE);
  setFlowControlMode(serialPort, SerialPort_FLOWCTRL_NONE);
  enableReceiveTimeout(serialPort, 1000);
  

5. Set Up an Output Stream Writer

The example then calls a constructor to create and open a java.io.OutputStreamWriter object. The constructor call passes the java.io.OutputStream object, returned by a call to the getOutputStream method serialPort, and assigns the OutputStreamWriter object to out.

• out = java.io.OutputStreamWriter(getOutputStream(serialPort));
  

6. Write Data to Serial Port and Close Output Stream

The example writes a string to the serial port, by calling write on the object out. The string is formed by concatenating (with MATLAB [ ] syntax) a command to set the oscilloscope's contrast to 45, with the command terminator that is required by the instrument. The next statement calls flush on out to flush the output stream.

• write(out, ['Display:Contrast 45' terminator]);
  flush(out);
  

Then, the example again calls write on out to send another string to the serial port. This string is a query command, to determine the oscilloscope's contrast setting, concatenated with the command terminator. The example then calls close on the output stream.

• write(out, ['Display:Contrast?' terminator]);
  close(out);
  

7. Open an Input Stream and Determine Number of Bytes to Read

To read the data expected from the oscilloscope in response to the contrast query, the example opens an input stream by calling the static method, InputStream.getInputStream, to obtain an InputStream object for the serial port. Then, the example calls the method available on the InputStream object, in, and assigns the returned number of bytes to numAvail.

• in = getInputStream(serialPort);
  numAvail = available(in);
  

8. Create an Input Stream Reader for the Serial Port

The example then calls a java.io.InputStreamReader constructor, with the InputStream object, in, and assigns the new object to reader.

• reader = java.io.InputStreamReader(in);
  

9. Read Data from Serial Port and Close Reader

The example reads from the serial port, by calling the read method on the InputStreamReader object reader for each available byte. The read statement uses MATLAB array concatenation to add each newly read byte to the array of bytes already read. After reading the data, the example calls close on reader to close the input stream reader.

• result = [];
  for k = 1:numAvail
      result = [result read(reader)];
  end
  close(reader);
  

10. Close the Serial Port

The example closes the serial port, by calling close on the serialPort object.

• close(serialPort);
  

11. Convert Input Argument to a MATLAB Character Array

The last statement of the example uses the MATLAB function, char, to convert the array input bytes (integers) to an array of characters:

• result = char(result);
  

Example - Communicating Through a Serial Port

Running the serialexample Program