<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<?xml-stylesheet href="./_c74_ref.xsl" type="text/xsl"?>

<!--This is an automatically generated file. DO NOT EDIT THIS FILE DIRECTLY. Rather, use the _ref.xml files found in the 'edits' folder.-->
<c74object name="serial" module="max" category="Devices">
	<digest>
		Send and receive from a serial port
	</digest>
	<description />
	<!--METADATA-->
	<metadatalist>
		<metadata name="author">
			Cycling '74
		</metadata>
		<metadata name="tag">
			Max
		</metadata>
		<metadata name="tag">
			Devices
		</metadata>
	</metadatalist>
	<!--INLETS-->
	<inletlist>
		<inlet id="0" type="INLET_TYPE">
			<digest>
				int, list Send Chars, bang Polls Output
			</digest>
			<description>
				TEXT_HERE
			</description>
		</inlet>
		<inlet id="1" type="INLET_TYPE">
			<digest>
				int, list Send Chars, bang Polls Output
			</digest>
			<description>
				TEXT_HERE
			</description>
		</inlet>
	</inletlist>
	<!--OUTLETS-->
	<outletlist>
		<outlet id="0" type="OUTLET_TYPE">
			<digest>
				Output As Integer Characters
			</digest>
			<description>
				TEXT_HERE
			</description>
		</outlet>
		<outlet id="1" type="OUTLET_TYPE">
			<digest>
				Status Signals
			</digest>
			<description>
				TEXT_HERE
			</description>
		</outlet>
	</outletlist>
	<!--ARGUMENTS-->
	<objarglist>
		<objarg name="port" optional="1" type="symbol">
			<digest>
				Serial port
			</digest>
			<description>
				Specifies the serial port to be used by the <o>serial</o> object. If alphabetic shortcuts (a-z) are used, <m>a</m> specifies the first logical serial port in the computer, and <m>b</m>- <m>z</m> are used to specify additional ports.
			</description>
		</objarg>
		<objarg name="portname" optional="0" type="symbol">
			<digest>
				Serial port name
			</digest>
			<description>
				If actual portnames are used, the symbol is the name given by the Operating System to your port. The <m>print</m> to the <o>serial</o> object can be used to create a list of available portnames and alphabetic shortcuts. If the port chosen is currently in use or unavailable when the <o>serial</o> object is instantiated, an error message will be displayed and the object will not function. If no port is specified, the default port is <m>a</m>.
			</description>
		</objarg>
		<objarg name="rate" optional="1" type="int">
			<digest>
				Baud rate
			</digest>
			<description>
				An optional argument may be used after the port name or alphabetic shortcut to specify the baud rate of the serial port (the default rate is 4800 baud). Any value is allowable (although not all ports can be set to all baud rates). Some common rates are 300, 600, 1200, 1800, 2400, 3600, 7200, 9600, 19200, 38400, 57600 and 115200.
			</description>
		</objarg>
		<objarg name="data" optional="1" type="int">
			<digest>
				Data bits
			</digest>
			<description>
				After the baud rate, the next arguments specifies the number of data bits for the serial port (the default is 8 data bits). Other possible values are 5, 6 and 7.
			</description>
		</objarg>
		<objarg name="stop" optional="1" type="int">
			<digest>
				Stop bits
			</digest>
			<description>
				The next argument specifies the number of stop bits for the serial port. The default is 1. Other possible values are 1.5 (Windows only) and 2.
			</description>
		</objarg>
		<objarg name="parity" optional="1" type="int or symbol">
			<digest>
				Parity mode
			</digest>
			<description>
				The next argument specifies the parity for the serial port (the default is no parity, specified by <m>0</m> or <m>no</m>).Other possible values are <m>odd</m>, <m>1</m> (odd), <m>even</m>, and <m>2</m> (odd).
			</description>
		</objarg>
	</objarglist>
	<!--MESSAGES-->
	<methodlist>
		<method name="bang">
			<arglist />
			<digest>
				Output received characters
			</digest>
			<description>
				Sends each character received on the serial port since the last <m>bang</m> message out the <o>serial</o> object's left outlet as an integer in the order that the characters were received. Before output data is sent, the message <m>read</m>, followed by a number specifying the number of bytes received is sent out the right outlet of the <o>serial</o> object.
			</description>
		</method>
		<method name="int">
			<arglist>
				<arg name="input" optional="0" type="int" />
			</arglist>
			<digest>
				Send a number
			</digest>
			<description>
				Sends the number out the serial port accessed by the <o>serial</o> object. Numbers outside the range 0-255 are wrapped to that range using a modulo operator. After the data is sent, the message <m>write</m>, followed by a number specifying the number of bytes sent is sent out the right outlet of the <o>serial</o> object.
			</description>
		</method>
		<method name="float">
			<arglist>
				<arg name="input" optional="0" type="float" />
			</arglist>
			<digest>
				Send a number
			</digest>
			<description>
				Converted to <m>int</m>.
			</description>
		</method>
		<method name="list">
			<arglist>
				<arg name="input" optional="0" type="list" />
			</arglist>
			<digest>
				Send numbers
			</digest>
			<description>
				Sends each number in the list out the serial port, in order. Numbers outside the range 0-255 are wrapped to that range using a modulo operator. After the data is sent, the message <m>write</m>, followed by a number specifying the number of bytes sent is sent out the right outlet of the <o>serial</o> object.
			</description>
		</method>
		<method name="break">
			<arglist />
			<digest>
				Send a break command
			</digest>
			<description>
				Sends a break command to the serial port used by the <o>serial</o> object. After the break has completed, the message <m>break</m> is sent out the object's right outlet.
			</description>
		</method>
		<method name="close">
			<arglist />
			<digest>
				Close the serial connection
			</digest>
			<description>
				Closes an open serial connection, permitting use of the serial port by other applications.
			</description>
		</method>
		<method name="getport">
			<arglist />
			<digest>
				Report the current serial port
			</digest>
			<description>
				Sends the name or shortcut of the currently open serial port out the <o>serial</o> object's right outlet, prepended by the word <m>port</m>.
			</description>
		</method>
		<method name="port">
			<arglist>
				<arg name="port" optional="0" type="list" />
			</arglist>
			<digest>
				Set the serial port
			</digest>
			<description>
				The word port, followed by a symbol, specifies the serial port to be used by the object. If alphabetic shortcuts are used, a specifies the first logical serial port in the computer. b - z specify additional ports. If actual portnames are used, the symbol is the name given by the operating system to your port. See the <m>print</m> message for a way to list available portnames and alphabetic shortcuts. If the port chosen is currently in use or unavailable when the port message is sent, an error message will be displayed and the object will revert to its previously chosen port, or won't function if there was none.
			</description>
		</method>
		<method name="print">
			<arglist />
			<digest>
				Print a list of serial ports
			</digest>
			<description>
				Sends a list of available serial ports to the Max Console, along with their alphabetic shortcuts. The message <m>port [portname] [portname]</m>... is also sent from the object's right outlet, with a list of available ports.
			</description>
		</method>
		<method name="open">
			<arglist />
			<digest>
				Open a serial connection
			</digest>
			<description>
				Opens a new serial connection.
			</description>
		</method>
		<method name="refresh">
			<arglist />
			<digest>
				Refresh the port list
			</digest>
			<description>
				Refreshes the list of known/available serial ports. See the <m>print</m> message for additional information.
			</description>
		</method>
		<method name="reset">
			<arglist />
			<digest>
				Reset the serial port for Basic Stamp
			</digest>
			<description>
				(Mac only) Resets the currently open serial port using the Basic Stamp initialization sequence.
			</description>
		</method>
	</methodlist>
	<!--ATTRIBUTES-->
	<attributelist>
		<attribute name="autoopen" get="1" set="1" type="int" size="1">
			<digest>
				Auto-open flag
			</digest>
			<description>
				Toggles automatically opening the serial port.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Automatically Open Port?" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="onoff" />
			</attributelist>
		</attribute>
		<attribute name="baud" get="1" set="1" type="int" size="1">
			<digest>
				Baud rate
			</digest>
			<description>
				Sets the port's baud rate.
			</description>
			<attributelist>
				<attribute name="basic" get="1" set="1" type="int" size="1" value="1" />
				<attribute name="enumvals" get="1" set="1" type="atom" size="11">
					<enumlist>
						<enum name="300">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="1200">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="2400">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="4800">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="9600">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="14400">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="19200">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="28800">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="38400">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="57600">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="115200">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
					</enumlist>
				</attribute>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Baud Rate" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="enum" />
			</attributelist>
		</attribute>
		<attribute name="bufsize" get="1" set="1" type="int" size="1">
			<digest>
				Input buffer size
			</digest>
			<description>
				Sets the input buffer size used by the <o>serial</o> object.
			</description>
			<attributelist>
				<attribute name="basic" get="1" set="1" type="int" size="1" value="1" />
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Serial Buffer Size" />
			</attributelist>
		</attribute>
		<attribute name="chunk" get="1" set="1" type="int" size="1">
			<digest>
				Data list length
			</digest>
			<description>
				Sets the data chunk size (data list length) for output.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Data Chunk Size" />
			</attributelist>
		</attribute>
		<attribute name="databits" get="1" set="1" type="int" size="1">
			<digest>
				Data bits
			</digest>
			<description>
				Sets the number of data bits (acceptable values are 5, 6, 7, or 8).
			</description>
			<attributelist>
				<attribute name="enumvals" get="1" set="1" type="atom" size="4">
					<enumlist>
						<enum name="5">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="6">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="7">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="8">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
					</enumlist>
				</attribute>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Data Bits" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="enum" />
			</attributelist>
		</attribute>
		<attribute name="defer" get="1" set="1" type="int" size="1">
			<digest>
				Defer Output
			</digest>
			<description>
				TEXT_HERE
			</description>
			<attributelist>
				<attribute name="default" get="1" set="1" type="int" size="1" value="1" />
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Defer Output" />
			</attributelist>
		</attribute>
		<attribute name="drain" get="1" set="1" type="int" size="1">
			<digest>
				Drain enable flag
			</digest>
			<description>
				(Mac only) Toggles drain enable. When enabled, communication waits until all data has been transmitted to the terminal when writing. The default value is 0 (disabled).
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Drain Enable" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="onoff" />
			</attributelist>
		</attribute>
		<attribute name="dtr" get="1" set="1" type="int" size="1">
			<digest>
				DTR (data terminal ready) enable
			</digest>
			<description>
				Enables or disables the DTR (data terminal ready) function of the serial port used by the <o>serial</o> object.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="DTR Enable" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="onoff" />
			</attributelist>
		</attribute>
		<attribute name="parity" get="1" set="1" type="int" size="1">
			<digest>
				Parity
			</digest>
			<description>
				Sets the parity for the port. The options are:
				<br />
				<br />
				0: no parity
				<br />
				1: odd
				<br />
				2: even
			</description>
			<attributelist>
				<attribute name="enumvals" get="1" set="1" type="atom" size="3">
					<enumlist>
						<enum name="no">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="odd">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="even">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
					</enumlist>
				</attribute>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Parity" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="enumindex" />
			</attributelist>
		</attribute>
		<attribute name="poll" get="1" set="1" type="float" size="1">
			<digest>
				Poll Enable/Interval
			</digest>
			<description>
				TEXT_HERE
			</description>
			<attributelist>
				<attribute name="default" get="1" set="1" type="float" size="1" value="0." />
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Poll Enable/Interval" />
			</attributelist>
		</attribute>
		<attribute name="serport" get="1" set="1" type="int" size="1">
			<digest>
				Serial Port
			</digest>
			<description>
				Used by the object Inspector only. Users should use the <m>port</m> message.
			</description>
			<attributelist>
				<attribute name="basic" get="1" set="1" type="int" size="1" value="1" />
				<attribute name="enumvals" get="1" set="1" type="atom" size="2">
					<enumlist>
						<enum name="Bluetooth-Incoming-Port">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="Bluetooth-Modem">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
					</enumlist>
				</attribute>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Serial Port" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="enumindex" />
			</attributelist>
		</attribute>
		<attribute name="stopbits" get="1" set="1" type="int" size="1">
			<digest>
				Stop bits
			</digest>
			<description>
				Sets the number of stop bits used when communicating with the serial port.
			</description>
			<attributelist>
				<attribute name="enumvals" get="1" set="1" type="atom" size="2">
					<enumlist>
						<enum name="1">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
						<enum name="2">
							<digest>
								TEXT_HERE
							</digest>
							<description>
								TEXT_HERE
							</description>
						</enum>
					</enumlist>
				</attribute>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Stop Bits" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="enum" />
			</attributelist>
		</attribute>
		<attribute name="xonxoff" get="1" set="1" type="int" size="1">
			<digest>
				Xon/Xoff enable
			</digest>
			<description>
				Enables Xon/Xoff serial flow control.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Xon / Xoff Enable" />
				<attribute name="style" get="1" set="1" type="symbol" size="1" value="onoff" />
			</attributelist>
		</attribute>
	</attributelist>
	<!--EXAMPLE-->
	<examplelist>
		<example img="serial.png" caption="When the button is clicked, this patch resets the modem, begins polling for a response, and stops polling when a response has been received" />
	</examplelist>
	<!--SEEALSO-->
	<seealsolist>
		<seealso name="match" />
		<seealso name="spell" />
		<seealso name="vdp" />
		<seealso name="communicationschapter02" module="max" type="tutorial" />
	</seealsolist>
	<discussion>
		The <o>serial</o> object works only with ports and devices supported by the standard serial driver. It does not work with USB ports and devices, unless a USB to Serial adaptor is connected.
	</discussion>
	<misc name="Output">
		<entry name="(serial output)">
			<description>
				When a number or list is received in its inlet, <o>serial</o> sends the data out the specified serial port at the current baud rate.
			</description>
		</entry>
		<entry name="int">
			<description>
				When <o>serial</o> receives a <m>bang</m> message and characters have been received in the serial port, the received characters are sent as numbers in the order they were received.
			</description>
		</entry>
		<entry name="list">
			<description>
				When <o>serial</o> receives a <m>bang</m> message, characters have been received in the serial port, and chunking is enabled, the received characters are sent as a list in the order the characters were received. The length of the list is determined by the argument to the <m>chunk</m> message (see the message listing for <m>chunk</m> for more information).
				<br />
				<br />
				Out right outlet: Reports error and status messages.
			</description>
		</entry>
	</misc>
</c74object>
