Serial Devices
From Xojo Documentation
Contents
A serial device is a device that communicates by sending and/or receiving data in serial. This means that it is either sending data or receiving data at any one moment. It doesn’t send and receive at the same time. In fact all USB devices are serial devices of some kind (USB stands for Universal Serial Bus).
To communicate with a serial device you configure an instance of a Serial class, open the serial port to make the connection, read and/or write data to and/or from the serial device connected to one of your serial ports, and finally close the serial port when you are ready to disconnect from the serial device.
Setting Up
The first step is to add a Serial class to your project. The easiest way to do this is to drag a Serial controller from the Library to your Window. You can also drag the Serial controller to the Navigator to create a subclass that you can instantiate in your code.
Before you can begin communicating with a serial device, you need to tell the Serial controller the port to use, the speed of the communication and other settings. If you’ve added the Serial controller to your window you can change these properties using the Inspector.
The specifics for how you configure these properties depends completely on the device you are using. You should consult the documentation for your device to determine the settings it supports.
Opening the Port
Once you have configured the Serial controller, you can open the serial port to initiate communications with the serial device. This is done by calling the Open method of class. This method returns True if the connection is opened and False if it is not. For example, suppose you have a Serial controller whose name is “SerialDevice”. You can open the serial port with the following code:
MessageBox("Opened serial port.")
Else
MessageBox("Could not open serial port.")
End If
Once you have successfully opened the serial port, it will be unavailable to all other applications (and to other Serial controllers as well) until it is closed. To close the Serial port, call the Close method:
Reading Data
When the serial device sends data back to the Serial controller that is connected to it, the data that has been sent back goes into a place in the computer’s memory called a buffer. The buffer is simply a place to store the data that has been sent by the serial device because most serial devices don’t have much memory of their own. When new data arrives in the buffer, the DataAvailable event handler of the Serial controller is called.
In the DataAvailable event handler, you use the Read or ReadAll methods to get some or all of the data in the buffer. This data is returned as a String. Use the Read method when you want to get a specific number of bytes (characters) from the buffer. If you want to get all the data in the buffer, use the ReadAll method. In both cases, the data returned from the buffer is removed from the buffer to make room for more incoming data. If you need to examine the data in the buffer without removing it from the buffer, you can use the LookAhead method instead.
This code in the DataAvailable event appends incoming data to a TextArea:
You can clear all data from the buffer without reading it by calling the Flush method.
Both the Read and ReadAll methods can take an optional parameter that enables you to specify the encoding. Use the Encodings object to get the desired encoding and pass it as a parameter. For example, the code above has been modified to specify that the incoming text uses the ANSI encoding, a standard on Windows:
You may need to specify the encoding when text is coming from another platform or is in another language. For information about text encoding, see the UserGuide:Encodings topic.
Writing Data
You can send data to the serial device at any time as long the serial port is open. You send data using the Write method. The data you wish to send must be a string.
The Write method is performed asynchronously. This means that your application does not wait for the Write method to finish before continuing with the next line of code. This behavior allows your application to remain responsive.
This code sends the text in a TextArea out to the Serial device:
If you would rather wait for all data to be sent before continuing with the next line of code, call the XmitWait method before calling Write:
SerialDevice.Write(TextArea1.Text)
Changing the Serial Configuration
There may be times when you need to change the Serial controller behavior properties while the serial port is open. While you can change these properties, the changes won’t take effect until you close the serial port and reopen it. If you need the behavior properties to update immediately, call the Poll method.
This updates all properties immediately and calls the DataAvailable event handler immediately if there is any data waiting in the buffer.
Closing the Port
Once you are finished communicating with a serial device, you must close the serial port to end the communications session and make the port available to other Serial controllers or other apps.
To close the Serial port, call the Close method using the same Serial controller that opened the port:
Communicating with USB, FireWire and Bluetooth Devices
Generally speaking, USB, FireWire and Bluetooth devices uses a completely different interface that often requires drivers in order to communicate with them. With that said, many of these devices have a chip in them that makes them appear and behave as if they were a serial device. This chip is often an FTDI chip, for which drivers are available.
If your device is not recognized as a serial device, then you should investigate using the MonkeyBread Software plugin which has some USB support for specific types of devices.
USB Background
USB wraps up several things into one:
- A cable interconnect specification (what the cable connectors need to look like)
- A low-level packet oriented protocol, so the OS can figure out what driver to load and talk to the USB device to identify it
- A vendor API, i.e., HID device like a mouse, keyboard, or mass storage device
Just because something uses a USB cable doesn’t mean you can talk to it. Some device types are very common so the OS vendors have the drivers built in. This includes HID devices (e.g., mice and keyboards) and mass storage devices like hard disks. If it’s one of those, they will work without any additional work.
Almost anything else requires a driver from the vendor. If you’d like to control such a device, you will need to obtain a shared library from the manufacturer or write your own. Try to contact the manufacturer to see if they have a library. If the manufacturer has a library for USB communications, you can communicate with the library using Declare statements.
Using Serial with Web Apps
Web apps can use the Serial class to communicate with serial devices that are attached to the web server. The Serial class cannot be used to communicate with serial devices on the user’s computer.
Example Projects
- Examples/Communication/Serial/Line State Change Tester
- Examples/Communication/Serial/Serial Port Bar Code Reader Example
- Examples/Communication/Serial/SerialLineIndicator
See Also
Serial class; UserGuide:Framework, GettingStarted:Serial Port Tutorial topics