Click or drag to resize
Serial Class
Creates a .NET serial port and provides a simple set of commands to use it.
Inheritance Hierarchy
SystemObject
  ASCOM.UtilitiesSerial

Namespace: ASCOM.Utilities
Assembly: ASCOM.Utilities (in ASCOM.Utilities.dll) Version: 6.0.0.0 (6.2.0.2774)
Syntax
public class Serial : IDisposable

The Serial type exposes the following members.

Constructors
  NameDescription
Public methodSerial
Initializes a new instance of the Serial class
Top
Properties
  NameDescription
Public propertyAvailableCOMPorts
Returns a list of all available ASCOM serial ports with COMnnn ports sorted into ascending port number order
Public propertyConnected
Gets or sets the connected state of the ASCOM serial port.
Public propertyDataBits
Gets or sets the number of data bits in each byte
Public propertyDTREnable
Gets or sets the state of the DTR line
Public propertyHandshake
Gets or sets the type of serial handshake used on the serial link
Public propertyParity
Gets or sets the type of parity check used over the serial link
Public propertyPort
Gets or sets the number of the ASCOM serial port (Default is 1, giving COM1 as the serial port name).
Public propertyPortName
Sets the ASCOM serial port name as a string
Public propertyReceiveTimeout
The maximum time that the ASCOM serial port will wait for incoming receive data (seconds, default = 5)
Public propertyReceiveTimeoutMs
The maximum time that the ASCOM serial port will wait for incoming receive data (milliseconds, default = 5000)
Public propertyRTSEnable
Gets or sets use of the RTS handshake control line
Public propertySpeed
Gets and sets the baud rate of the ASCOM serial port
Public propertyStopBits
Gets or sets the number of stop bits used on the serial link
Top
Methods
  NameDescription
Public methodClearBuffers
Clears the ASCOM serial port receive and transmit buffers
Public methodDispose
Disposes of resources used by the profile object
Public methodLogMessage
Adds a message to the ASCOM serial trace file
Public methodReceive
Receive at least one text character from the ASCOM serial port
Public methodReceiveByte
Receive one binary byte from the ASCOM serial port
Public methodReceiveCounted
Receive exactly the given number of characters from the ASCOM serial port and return as a string
Public methodReceiveCountedBinary
Receive exactly the given number of characters from the ASCOM serial port and return as a byte array
Public methodReceiveTerminated
Receive characters from the ASCOM serial port until the given terminator string is seen
Public methodReceiveTerminatedBinary
Receive characters from the ASCOM serial port until the given terminator bytes are seen, return as a byte array
Public methodTransmit
Transmits a string through the ASCOM serial port
Public methodTransmitBinary
Transmit an array of binary bytes through the ASCOM serial port
Top
Remarks
This object provides an easy to use interface to a serial (COM) port. It provides ASCII and binary I/O with controllable timeout. The interface is callable from any .NET client.

The platform allows you to control use of the DTR and RTS/CTS lines for a particular COM port and to remove or force listing of individual COM ports in the AvailableComPorts list through configuration in the ASCOM Profile. Please see the Tools and Features section of this help file for further details.

Examples
Example of how to create and use an ASCOM serial port.
ASCOM Serial Port Example
Public Class SerialExamples
    'Define the serial port variable
    Private SerPort As ASCOM.Utilities.Serial

    Sub BasicExample() 'This example shows a simple use of the ASCOM serial port
        'Define variables for strings to be transmitted and received
        Dim TXString, RXString As String

        'Serial port defaults are:  Speed 9600 baud
        '                           Timeout 5 seconds
        '                           Format 8 data bits, no parity, 1 stop bit
        '                           DTR enabled
        '                           No handshaking
        Try
            'Create the serial port
            SerPort = New ASCOM.Utilities.Serial

            'Configure the port, if any defaults are not suitable, set the relevant SerPort properties here
            SerPort.Port = 1 'Change the 1 to the serial port to which your device is connected

            'Connect to the serial port
            SerPort.Connected = True

            'Send a command to the connected device
            TXString = "DeviceCommand" 'Change this to a command to your device that will return a response
            SerPort.Transmit(TXString)

            'Get the response from the device and display it
            RXString = SerPort.Receive
            MsgBox("Sent: " & TXString & " Received back: " & RXString)

            SerPort.Connected = False 'Disconnect and clean up
            SerPort.Dispose()
            SerPort = Nothing

        Catch ex As Exception 'Catch any exceptions and display
            MsgBox("Threw exception: " & ex.ToString)
            SerPort.Dispose()
            SerPort = Nothing
        End Try
    End Sub

    Sub FullExample()
        'Create variables for this example
        Dim ASCIIEncoding As New System.Text.ASCIIEncoding() 'Create an encoding to enable us to convert a string to a byte array
        Dim RxString As String, RxByte, RxBytes(), TxBytes(), TerminatorBytes() As Byte
        Dim AvailablePorts() As String

        'Create a new serial port
        SerPort = New ASCOM.Utilities.Serial

        'Set up the basic port parameters
        'You only need to use one of the Port or PortName options, its your choice as appropriate
        SerPort.Port = 1 'Set to port COM1 - please choose an appropriate value for your setup
        SerPort.PortName = "COM1" 'Achieves same as above but gives flexibility where port name is not of form COMn
        SerPort.Speed = ASCOM.Utilities.SerialSpeed.ps9600 'Set to baud rate 9600, choose an appropriate value for your system
        'You only need to use one of the ReceiveTimeout or ReceiveTimeoutMs options, its your choice as appropriate
        SerPort.ReceiveTimeout = 5 'Set the time (in seconds) that the receive commands will wait before returning a timeout exception
        SerPort.ReceiveTimeoutMs = 5000 'Set the time (in milli-seconds) that the receive commands will wait before returning a timeout exception

        'Set serial format and serial line parameters as required
        'Following values are the defaults so you don't need to set them if they work OK with your device
        SerPort.DataBits = 8 ' Set 8 data bits
        SerPort.Parity = IO.Ports.Parity.None 'Set no parity bit
        SerPort.StopBits = IO.Ports.StopBits.One 'Set one stop bit
        SerPort.DTREnable = True 'Set the DTR line high
        SerPort.Handshake = IO.Ports.Handshake.None 'Don't use hardware or software flow control on the serial line

        'Create the serial port and ready it for use
        SerPort.Connected = True

        'Transmit examples
        SerPort.Transmit("Hello World") 'Send a string message to the device through the serial port
        TxBytes = ASCIIEncoding.GetBytes("Hello World As Byte Array")
        SerPort.TransmitBinary(TxBytes) 'Send a message held in a byte array to the device'

        'Receive examples
        'These will fail if no chacraters have been previously sent to the port
        RxString = SerPort.Receive() '"Get all characters that have been received by the serial port as a atring
        RxByte = SerPort.ReceiveByte() 'Get one character as a byte from the serial port
        RxString = SerPort.ReceiveCounted(5) 'Get 5 characters from the serial port as a string
        RxBytes = SerPort.ReceiveCountedBinary(5) 'get 5 characters from the serial port as a byte array
        RxString = SerPort.ReceiveTerminated("#") 'Get all characters up to and including the # character
        TerminatorBytes = ASCIIEncoding.GetBytes("#") 'Create the terminator byte array from a string value
        RxBytes = SerPort.ReceiveTerminatedBinary(TerminatorBytes) REM Get all characters up to and including the specified terminator bytes as a byte array

        'Utility examples
        AvailablePorts = SerPort.AvailableComPorts 'Get a list of installed COM ports
        SerPort.LogMessage("MyID", "My message") 'Add a custom message to the serial log file
        SerPort.ClearBuffers() 'Use this wherever you want to be sure that the serial port is ready for the next command

        'Clean up and release the serial port
        SerPort.Connected = False 'Disconnect the serial port
        SerPort.Dispose() 'Release serial port resources
        SerPort = Nothing

    End Sub

End Class
See Also