W3cubDocs

hs.serial

Communicate with external devices through a serial port (most commonly RS-232).

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

API Overview

Functions - API calls offered directly by the extension

availablePortDetails
availablePortNames
availablePortPaths
deviceCallback

Constructors - API calls which return an object, typically one that offers API methods

newFromName
newFromPath

Methods - API calls which can only be made on an object returned by a constructor

baudRate
callback
close
dataBits
dtr
isOpen
name
open
parity
path
rts
sendData
shouldEchoReceivedData
stopBits
usesDTRDSRFlowControl
usesRTSCTSFlowControl

API Documentation

Functions

availablePortDetails

Signature	`hs.serial.availablePortDetails() -> table`
Type	Function
Description	Returns a table of currently connected serial ports details, organised by port name.
Parameters	None
Returns	A table containing the IOKit details of any connected serial ports, organised by port name.
Source	extensions/serial/libserial.m line 655

availablePortNames

Signature	`hs.serial.availablePortNames() -> table`
Type	Function
Description	Returns a table of currently connected serial ports names.
Parameters	None
Returns	A table containing the names of any connected serial port names as strings.
Source	extensions/serial/libserial.m line 631

availablePortPaths

Signature	`hs.serial.availablePortPaths() -> table`
Type	Function
Description	Returns a table of currently connected serial ports paths.
Parameters	None
Returns	A table containing the names of any connected serial port paths as strings.
Source	extensions/serial/libserial.m line 683

deviceCallback

Signature	`hs.serial.deviceCallback(callbackFn) -> none`
Type	Function
Description	A callback that's triggered when a serial port is added or removed from the system.
Parameters	callbackFn - the callback function to trigger, or nil to remove the current callback
Returns	None
Notes	The callback function should expect 1 argument and should not return anything: `devices` - A table containing the names of any serial ports connected as strings.
Source	extensions/serial/libserial.m line 1161

Constructors

newFromName

Signature	`hs.serial.newFromName(portName) -> serialPortObject`
Type	Constructor
Description	Creates a new `hs.serial` object using the port name.
Parameters	portName - A string containing the port name.
Returns	An `hs.serial` object or `nil` if an error occurred.
Notes	A valid port name can be found by checking `hs.serial.availablePortNames()`.
Source	extensions/serial/libserial.m line 525

newFromPath

Signature	`hs.serial.newFromPath(path) -> serialPortObject`
Type	Constructor
Description	Creates a new `hs.serial` object using a path.
Parameters	path - A string containing the path (i.e. "/dev/cu.usbserial").
Returns	An `hs.serial` object or `nil` if an error occurred.
Notes	A valid port name can be found by checking `hs.serial.availablePortPaths()`.
Source	extensions/serial/libserial.m line 558

Methods

baudRate

Signature	`hs.serial:baudRate([value], [allowNonStandardBaudRates]) -> number \| serialPortObject`
Type	Method
Description	Gets or sets the baud rate for the serial port.
Parameters	value - An optional number to set the baud rate. [allowNonStandardBaudRates] - An optional boolean to enable non-standard baud rates. Defaults to `false`.
Returns	If a value is specified, then this method returns the serial port object. Otherwise this method returns the baud rate as a number
Notes	This function supports the following standard baud rates as numbers: 300, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400, 57600, 115200, 230400. If no baud rate is supplied, it defaults to 115200.
Source	extensions/serial/libserial.m line 783

callback

Signature	`hs.serial:callback(callbackFn) -> serialPortObject`
Type	Method
Description	Sets or removes a callback function for the `hs.serial` object.
Parameters	`callbackFn` - a function to set as the callback for this `hs.serial` object. If the value provided is `nil`, any currently existing callback function is removed.
Returns	The `hs.serial` object
Notes	The callback function should expect 4 arguments and should not return anything: `serialPortObject` - The serial port object that triggered the callback. `callbackType` - A string containing "opened", "closed", "received", "removed" or "error". `message` - If the `callbackType` is "received", then this will be the data received as a string. If the `callbackType` is "error", this will be the error message as a string. `hexadecimalString` - If the `callbackType` is "received", then this will be the data received as a hexadecimal string.
Source	extensions/serial/libserial.m line 591

close

Signature	`hs.serial:close() -> serialPortObject`
Type	Method
Description	Closes the serial port.
Parameters	None
Returns	The `hs.serial` object.
Source	extensions/serial/libserial.m line 765

dataBits

Signature	`hs.serial:dataBits([value]) -> number \| serialPortObject`
Type	Method
Description	Gets or sets the number of data bits for the serial port.
Parameters	value - An optional number to set the number of data bits. It can be 5 to 8.
Returns	If a value is specified, then this method returns the serial port object. Otherwise this method returns the data bits as a number. The default value is 8.
Source	extensions/serial/libserial.m line 1091

dtr

Signature	`hs.serial:dtr([value]) -> boolean \| serialPortObject`
Type	Method
Description	Gets or sets the state of the serial port's DTR (Data Terminal Ready) pin.
Parameters	value - An optional boolean.
Returns	If a value is specified, then this method returns the serial port object. Otherwise this method returns a boolean.
Notes	The default value is `false`. Setting this to `true` is most likely required for Arduino devices prior to opening the serial port.
Source	extensions/serial/libserial.m line 972

isOpen

Signature	`hs.serial:isOpen() -> boolean`
Type	Method
Description	Gets whether or not a serial port is open.
Parameters	None
Returns	`true` if open, otherwise `false`.
Source	extensions/serial/libserial.m line 1122

name

Signature	`hs.serial:name() -> string`
Type	Method
Description	Returns the name of a `hs.serial` object.
Parameters	None
Returns	The name as a string.
Source	extensions/serial/libserial.m line 707

open

Signature	`hs.serial:open() -> serialPortObject \| nil`
Type	Method
Description	Opens the serial port.
Parameters	None
Returns	The `hs.serial` object or `nil` if the port could not be opened.
Source	extensions/serial/libserial.m line 743

parity

Signature	`hs.serial:parity([value]) -> string \| serialPortObject`
Type	Method
Description	Gets or sets the parity for the serial port.
Parameters	value - An optional string to set the parity. It can be "none", "odd" or "even".
Returns	If a value is specified, then this method returns the serial port object. Otherwise this method returns a string value of "none", "odd" or "even".
Source	extensions/serial/libserial.m line 834

path

Signature	`hs.serial:path() -> string`
Type	Method
Description	Returns the path of a `hs.serial` object.
Parameters	None
Returns	The path as a string.
Source	extensions/serial/libserial.m line 725

rts

Signature	`hs.serial:rts([value]) -> boolean \| serialPortObject`
Type	Method
Description	Gets or sets the state of the serial port's RTS (Request to Send) pin.
Parameters	value - An optional boolean.
Returns	If a value is specified, then this method returns the serial port object. Otherwise this method returns a boolean.
Notes	The default value is `false`. Setting this to `true` is most likely required for Arduino devices prior to opening the serial port.
Source	extensions/serial/libserial.m line 1001

sendData

Signature	`hs.serial:sendData(value) -> none`
Type	Method
Description	Sends data via a serial port.
Parameters	value - A string of data to send.
Returns	None
Source	extensions/serial/libserial.m line 1140

shouldEchoReceivedData

Signature	`hs.serial:shouldEchoReceivedData([value]) -> boolean \| serialPortObject`
Type	Method
Description	Gets or sets whether the port should echo received data.
Parameters	value - An optional boolean.
Returns	If a value is specified, then this method returns the serial port object. Otherwise this method returns a boolean.
Notes	The default value is `false`.
Source	extensions/serial/libserial.m line 1030

stopBits

Signature	`hs.serial:stopBits([value]) -> number \| serialPortObject`
Type	Method
Description	Gets or sets the number of stop bits for the serial port.
Parameters	value - An optional number to set the number of stop bits. It can be 1 or 2.
Returns	If a value is specified, then this method returns the serial port object. Otherwise this method returns the number of stop bits as a number.
Notes	The default value is 1.
Source	extensions/serial/libserial.m line 1058

usesDTRDSRFlowControl

Signature	`hs.serial:usesDTRDSRFlowControl([value]) -> boolean \| serialPortObject`
Type	Method
Description	Gets or sets whether the port should use DTR/DSR Flow Control.
Parameters	value - An optional boolean.
Returns	If a value is specified, then this method returns the serial port object. Otherwise this method returns a boolean.
Notes	The default value is `false`.
Source	extensions/serial/libserial.m line 916

usesRTSCTSFlowControl

Signature	`hs.serial:usesRTSCTSFlowControl([value]) -> boolean \| serialPortObject`
Type	Method
Description	Gets or sets whether the port should use RTS/CTS Flow Control.
Parameters	value - An optional boolean.
Returns	If a value is specified, then this method returns the serial port object. Otherwise this method returns a boolean.
Notes	The default value is `false`.
Source	extensions/serial/libserial.m line 944