Main Content

serialportfind

Find serial port connections

Since R2024a

collapse all in page

Syntax

serialportfind
S = serialportfind(Name=Value)

Description

example

S = serialportfind finds existing persistent serial port connections and returns an array of serialport objects corresponding to each connection.

example

S = serialportfind(Name=Value) finds connections with property values matching those specified by one or more name-value arguments. For instance, S = serialportfind(Tag="Scope") returns existing serial connections whose Tag property is set to "Scope".

Examples

collapse all

When you have a serialport connection that exists in the MATLAB® workspace or is saved as a class property or app property, the serialport object might not be accessible in a different function or app callback. In this case, you can use serialportfind to find and delete the connection. 

S = serialportfind
S = 

  Serialport with properties:

                 Port: "COM3"
             BaudRate: 9600
                  Tag: ""
    NumBytesAvailable: 0

To close this connection, delete S.

delete(S)

This command deletes the serialport object and disconnects the device. If you subsequently want to reconnect to the device, you must create a new interface with serialport.

After the deletion, calling serialportfind confirms that there are no existing connections.

serialportfind
ans =

     []

Note that the variable S is still present in the workspace, but it is now an invalid handle. 

S
S = 

  handle to deleted Serialport

The variable persists after deletion of the interface because serialport is a handle object. (For more information about this type of object, see Handle Object Behavior.) You can use clear to remove the invalid handle from the workspace.

clear S

You can assign a tag to a connection and use that tag with serialportfind to access the connection later. Such tags are useful when you have multiple serial port connections to keep track of across several functions. Tags are also useful for locating and accessing connections in app callbacks. To set the tag value, use the Tag property of serialport.

Create two serial port connections, assigning values to the Tag property.

c1 = serialport("COM3",9600,Tag="Arduino");
c2 = serialport("COM5",14400,Tag="Power");

Find connections with the tag "Arduino".

S = serialportfind(Tag="Arduino")
S = 

  Serialport with properties:

                 Port: "COM3"
             BaudRate: 9600
                  Tag: "Arduino"
    NumBytesAvailable: 0

Input Arguments

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: serialportfind(Tag="Scope",BaudRate=14400) returns existing serial connections whose Tag property is set to "Scope" and have baud rate of 14400.

For serialportfind, you can use one or more properties of the serialport object as name-value arguments to specify characteristics of the connections you want to find.

Output Arguments

collapse all

Serial port connections, returned as a serialport object or an array of serialport objects. If you call serialportfind with no Name=Value pairs, S contains all existing connections. Otherwise, S contains all connections whose properties match the values you specify with Name=Value pairs.

S is empty if:

  • There are no existing serial port connections.

  • No existing connections match the specified property values. For instance, if you specify Tag="Scope", and there is no existing connection whose Tag property is "Scope", then S is empty.

  • You try to match a property that doesn't exist in serialport. For instance, serialportfind(Speed=14400) returns an empty array, because serialport does not have a Speed property.

Tips

  • serialportfind finds existing serialport connections. To get a list of all available serial ports whether or not connections exist, use serialportlist.

Version History

Introduced in R2024a

See Also

|