hs.serial
ModuleCommunicate with devices connected to serial ports (RS-232, USB-serial adapters, etc).
IMPORTANT NOTE: This module is not currently very well tested with real hardware. Please provide feedback (positive or negative!) via GitHub Issues.
Enumerate available ports with availablePortNames()/availablePortPaths(), then create a
port object with createPortNamed()/createPortAtPath(). The returned object is not open
until you call open() on it.
- Example:
const port = hs.serial.createPortNamed(hs.serial.availablePortNames()[0])
port.baudRate = 9600
port.setCallback((event, data) => {
if (event === "received") {
console.log("Received: " + data)
}
}).open()
port.sendData("AT\r\n")
Types
This module provides the following types:
Properties
This module has no properties.
Methods
hs.serial.availablePortNames() -> string[]
Returns the names of all currently connected serial ports.
Declaration
hs.serial.availablePortNames() -> string[]Returns
string[]
An array of port name strings (e.g. `"usbserial-1420"`)
Example
console.log(hs.serial.availablePortNames())hs.serial.availablePortPaths() -> string[]
Returns the device paths of all currently connected serial ports.
Declaration
hs.serial.availablePortPaths() -> string[]Returns
string[]
An array of path strings (e.g. `"/dev/cu.usbserial-1420"`)
Example
console.log(hs.serial.availablePortPaths())hs.serial.availablePortDetails() -> [String: [String: Any]]
Returns IOKit registry details for all currently connected serial ports.
Declaration
hs.serial.availablePortDetails() -> [String: [String: Any]]Returns
[String: [String: Any]]
An object keyed by port name, whose values are objects containing that port's IOKit registry properties.
Example
const details = hs.serial.availablePortDetails()
Object.keys(details).forEach(name => console.log(name, details[name]))hs.serial.createPortNamed(name) -> HSSerialPort
Creates a serial port object for a port discovered via `availablePortNames()`.
Declaration
hs.serial.createPortNamed(name) -> HSSerialPortParameters
| Name | Type | Description |
|---|---|---|
| name | string | The port name, as returned by `availablePortNames()` |
Returns
HSSerialPort
A new `HSSerialPort`, or `null` if no port with that name is currently connected
Example
const port = hs.serial.createPortNamed("usbserial-1420")hs.serial.createPortAtPath(path) -> HSSerialPort
Creates a serial port object for an arbitrary device path.
Unlike `createPortNamed()`, the path does not need to correspond to a port
currently discoverable via IOKit — it is only validated when you call `open()`.
Declaration
hs.serial.createPortAtPath(path) -> HSSerialPortParameters
| Name | Type | Description |
|---|---|---|
| path | string | The device path (e.g. `"/dev/cu.usbserial-1420"`) |
Returns
HSSerialPort
A new `HSSerialPort`
Example
const port = hs.serial.createPortAtPath("/dev/cu.usbserial-1420")hs.serial.addWatcher(listener) -> None
Register a listener for serial port connection and disconnection events.
The listener is called with two arguments: the event type string (`"added"` or `"removed"`)
and a port-info object with `name` and `path` fields.
Declaration
hs.serial.addWatcher(listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| listener | function | The function to call when a serial port is added or removed |
Returns
None
Example
hs.serial.addWatcher((event, port) => console.log(event + ": " + port.name))hs.serial.removeWatcher(listener) -> None
Remove a previously registered serial port event listener.
Declaration
hs.serial.removeWatcher(listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| listener | function | The function originally passed to `addWatcher` |
Returns
None
Example
hs.serial.removeWatcher(myHandler)