msutils.c File Reference

Microscan MS-3 Barcode Reader Utilities API Code. More...

#include "msutils.h"

Functions
int	MSOpenPort (char *devname)
	Open a serial port connection to Microscan barcode reader.
void	MSClosePort (int portFD)
	Close a barcode reader comm port.
int	MSReadPort (int portFD, char *buf, long timeout)
	Read data from a barcode reader (with timeout),.
int	MSSendQuery (int portFD, char *msqStr, char *msqVal, long timeout)
	Query the barcode reader and wait for a reply.
int	MSSendCommand (int portFD, char *cmdstr, char *errstr)
	Send a command to the barcode reader.
int	MSReadBarcode (int portFD, char *bcstr, long timeout)
	Read a barcode label and return the label text.
int	MSReset (int portFD, char *reply)
	Reset the barcode reader.

---

Detailed Description

Microscan MS-3 Barcode Reader Utilities API Code.

Simple API for operating a Microscan MS-3 CCD barcode reader from within a C/C++ program. See www.microscan.com for basic information about Microscan barcode readers and documentation.

See the msutils.h header file for additional parameters.

Author:

R. Pogge, OSU Astronomy Dept. (pogge@astronomy.ohio-state.edu)

Date:

2004 May 24 (initial version)

Todo:

Add more functionality to access engineering-level functions of the Microscan MS-3 barcode reader. Also add code to parse status queries and interpret them sensibly (i.e., query for the no-decode timeout value). Still pretty primitive, but it gets us going. There may be no good reason to make it super-sophisticated, since these are pretty simple devices.

---

Function Documentation

int MSOpenPort (  char *  devname  )

Open a serial port connection to Microscan barcode reader. Parameters: devname  Device name of the comm port to open Returns: File descriptor of the open comm port connection, or -1 if an error. Performs the necessary initialization functions to open a comm port connected to a Microscan barcode reader. The device name syntax is as follows: /dev/ttyXX# = regular serial port (tty port) host:port = network serial port server address (IP and port #). The former is for a barcode reader connected to a direct serial port, or to a virtual serial port (e.g., on a remote terminal server like a Comtrol DeviceMaster RTS using a virtual serial port device driver). The latter is for a direct network socket connection to a remote serial port server (e.g., a Comtrol RTS configured as a socket server). For socket communications with a network serial port server, we use INET streams (SOCK_STREAM) with a persistent client connection. This is pretty much standard for most devices on the market. For a regular serial port, we set the attributes to 9600 baud, 7 data bits, 1 stop bit, and even parity as required by the Microscan MS-3 series barcode scanner's serial interface. See also: MSClosePort()

void MSClosePort (  int  portFD  )

Close a barcode reader comm port. Parameters: portFD  File descriptor of the comm port (opened with MSOpenPort()) Simple wrapper for close(). Doesn't do much now, but it does provide for future expansion if we want close to do more. See also: MSOpenPort()

int MSReadPort (  int  portFD, char *  buf, long  timeout )

Read data from a barcode reader (with timeout),. Parameters: portFD  File descriptor of the barcode reader port (see MSOpenPort()) buf  Character string to contain the output timeout  Wait timeout seconds for input Returns: The number of characters read, or -1 on error or timeout, with buf containing the error message text. Uses select() to read data from the specified comm port file descriptor with the timeout interval specified. Note that because we could be reading a stream rather than a line-buffered source (e.g., portFD points to a socket stream to a network serial port server like a Comtrol DeviceMaster RTS instead of a regular direct serial port), the data could come in bursts depending on the system state and stream synchronization. As such we read in chunks of data w/o blocking until we have read everything from the port, which means looking for the \r terminator. This makes the logic tricky, but robust against most comm glitches. Use of a timeout allows us to break out of cases where the message is unterminated because of a comm fault, not because of the usual stream buffering/sync issues. The Microscan MS3 barcode reader must be configured to terminate messages with \r (ASCII 13 = Ctrl+M). Note, If select() is interrupted by Ctrl+C, the read is aborted.

int MSSendQuery (  int  portFD, char *  msqStr, char *  msqVal, long  timeout )

Query the barcode reader and wait for a reply. Parameters: portFD  File descriptor of the barcode reader's comm port (see MSOpenPort()) msqStr  Character string with the query command *msqVal  Character string to contain the parameter query response timeout  Wait upt to timeout seconds for input Returns: The number of characters read, or -1 on error or timeout, with the msqVal string containing the error message text. Sends a query command to the barcode scanner, then calls MSReadPort() to get the reply (or timeout), and then strips the parameter value out of the reply string and returns it to the calling program. Since the barcode scanner can return strings, ints, and floats as replies, we hand everything back as a string and let the calling program decide how to decode and utilize the reply. Calls MSReadPort()

int MSSendCommand (  int  portFD, char *  cmdstr, char *  errstr )

Send a command to the barcode reader. Parameters: portFD  File descriptor of the barcode reader's comm port (see MSOpenPort()) cmdstr  Character string with the barcode reader command errstr  Character string to contain any error messages Returns: 0 if successful, -1 if an error, with the error message in errstr. Sends a command to the barcode reader and returns w/o waiting for a reply. Most barcode commands do not generate replies from the reader unless they are query commands (e.g., <K200?>, at which point you should use the MSSendQuery() function). The errstr string argument is used to contain detailed error messages if needed. See also: MSSendQuery()

int MSReadBarcode (  int  portFD, char *  bcstr, long  timeout )

Read a barcode label and return the label text. Parameters: portFD  File descriptor of the barcode reader's comm port (see MSOpenPort()) bcstr  Character string with the barcode label text timeout  Timeout interval to wait for reply Returns: 0 if successful with the barcode text in the bcstr, or -1 if nothing scanned (missing code, bad placement, wrong format), or -2 if the routine itself timed out (failsafe). An error message is in bcstr. Instructs the barcode reader to scan a barcode label. The reader has an internal timeout (factory default is 2sec), after which it will send a NOREAD message back. The barcode reader must be setup for serial trigger with the MS_DOREAD command as defined in msutils.h. Note that for our typical setup, we define the serial trigger character to be a capital X (ASCII 88). This would then be sent with the <> delimiters, and set using the <K201,X> command when the reader is configured for use. When the serial trigger character is received by the barcode reader, it turns on its laser/LEDs and scan for a barcode label in the beam. The scanning proceeds until either (a) it successfully decodes the label and it returns the label text or (b) the "no-decode timeout" interval expires and it returns a "NOREAD" message indicating it failed to successfully decode the label (or it could also mean no label was in the beam). As a failsafe, we wait for the communications timeout interval for a reply to the read request. This allows us to exit gracefully in the case of barcode reader malfunction or the reader not being powered on. In general timeout should be larger than the scanner's no-decode timeout, typically twice as long. The factory default no-decode timeout is 2 seconds, so a sensible application communications timeout interval would be 4 seconds. Calls MSSendQuery()

int MSReset (  int  portFD, char *  reply )

Reset the barcode reader. Parameters: portFD  File descriptor of the barcode reader's comm port (see MSOpenPort()) reply  Reset status message string Returns: 0 if successful, -1 if not. reply has the error condition. Sends a hardware reset () command to the barcode reader, resetting it to its initial state, but do not save any changed settings for future power-up. This is a convenience function so that any higher-level routines don't have to know low-level barcode reader serial instructions. Calls MSSendCommand()

---