SwiftSerial

https://github.com/yeokm1/swiftserial
Admin
SwiftSerial is a Swift library for macOS and Linux that enables reading and writing data to serial...
Tokens:6,128
Snippets:63
Trust Score:9.8
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Run SwiftSerialExample loopback test

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Build and run the loopback test example. Requires connecting a serial port's TX and RX pins in a loopback manner. On Linux, root access is needed and the port name must be replaced; on Mac, root is not required. Successful execution prints messages confirming received data.

```bash
git clone https://github.com/yeokm1/SwiftSerial.git
cd SwiftSerial/Examples/SwiftSerialExample/
swift build

#For Linux: You need root to access the serial port. Replace /dev/ttyUSB0 with the name of your serial port under test
sudo ./.build/debug/SwiftSerialExample /dev/ttyUSB0

#For Mac: Root is not required
./.build/debug/SwiftSerialExample /dev/cu.usbserial

#If all goes well you should see a series of messages informing you that data transmitted has been received properly.
```

--------------------------------

### Run SwiftSerialIM chat app between 2 machines

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Build and run the chat application example. Requires two machines connected via a null-modem cable or two USB-Serial adapters with TX-RX pins connected. Run a copy on both machines to enable chatting. Linux needs root access; Mac does not.

```bash
git clone https://github.com/yeokm1/SwiftSerial.git
cd SwiftSerial/Examples/SwiftSerialIM/
swift build

#For Linux: You need root to access the serial port. Replace /dev/ttyUSB0 with the name of your serial port under test
sudo ./.build/debug/SwiftSerialIM /dev/ttyUSB0

#For Mac: Root is not required
./.build/debug/SwiftSerialIM /dev/cu.usbserial
```

--------------------------------

### SerialPort init(path:)

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Initializes a SerialPort instance with a given path.

```APIDOC
## [SDK] SwiftSerial SerialPort

### Description
Initializes a new SerialPort instance with the specified path.

### Method
init(path:)

### Parameters
- **path** (String) - Required - The path to the serial port, e.g., `/dev/ttyUSB0` or `/dev/cu.usbserial`.

### Example
```swift
let serialPort: SerialPort = SerialPort(path: portName)
```
```

--------------------------------

### Run SwiftSerialBinary binary loopback test

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Build and run the binary loopback test, which verifies that the 0x0D bit is not converted to another character during binary data transfer. Requires a loopback connection. Linux needs root access; Mac does not. Successful execution prints confirmation messages.

```bash
git clone https://github.com/yeokm1/SwiftSerial.git
cd SwiftSerial/Examples/SwiftSerialBinary/
swift build

#For Linux: You need root to access the serial port. Replace /dev/ttyUSB0 with the name of your serial port under test
sudo ./.build/debug/SwiftSerialBinary /dev/ttyUSB0

#For Mac: Root is not required
./.build/debug/SwiftSerialBinary /dev/cu.usbserial

#If all goes well you should see a series of messages informing you that data transmitted has been received properly.
```

--------------------------------

### Initialize SerialPort with path

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Initialize a SerialPort instance with the desired port name, e.g., /dev/ttyUSB0 or /dev/cu.usbserial. On Macs, only /dev/cu.* ports are supported because blocking is enabled.

```swift
let serialPort: SerialPort = SerialPort(path: portName)
```

--------------------------------

### Set serial port settings with full parameters

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Full setSettings signature with default parameters. Override any of the defaults by passing extra arguments.

```swift
func setSettings(receiveRate: BaudRate,
                 transmitRate: BaudRate,
                 minimumBytesToRead: Int,
                 timeout: Int = 0, /* 0 means wait indefinitely */
                 parityType: ParityType = .none,
                 sendTwoStopBits: Bool = false, /* 1 stop bit is the default */
                 dataBitsSize: DataBitsSize = .bits8,
                 useHardwareFlowControl: Bool = false,
                 useSoftwareFlowControl: Bool = false,
                 processOutput: Bool = false)
```

--------------------------------

### setSettings()

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Functions to configure serial port settings with optional parameters.

```APIDOC
## [SDK] setSettings(receiveRate:transmitRate:minimumBytesToRead:)

### Description
Sets the serial port settings with default values for other parameters.

### Method
setSettings(receiveRate:transmitRate:minimumBytesToRead:)

### Parameters
- **receiveRate** (BaudRate) - Required - Baud rate for receiving.
- **transmitRate** (BaudRate) - Required - Baud rate for transmitting.
- **minimumBytesToRead** (Int) - Required - Minimum bytes to read before returning from read().

### Example
```swift
serialPort.setSettings(receiveRate: .baud9600, transmitRate: .baud9600, minimumBytesToRead: 1)
```
```

```APIDOC
## [SDK] setSettings(receiveRate:transmitRate:minimumBytesToRead:timeout:parityType:sendTwoStopBits:dataBitsSize:useHardwareFlowControl:useSoftwareFlowControl:processOutput:)

### Description
Sets the serial port settings with full configuration options.

### Method
setSettings(receiveRate:transmitRate:minimumBytesToRead:timeout:parityType:sendTwoStopBits:dataBitsSize:useHardwareFlowControl:useSoftwareFlowControl:processOutput:)

### Parameters
- **receiveRate** (BaudRate) - Required - Baud rate for receiving.
- **transmitRate** (BaudRate) - Required - Baud rate for transmitting.
- **minimumBytesToRead** (Int) - Required - Minimum bytes to read before returning from read().
- **timeout** (Int) - Optional - Timeout in seconds; 0 means wait indefinitely. Default: 0.
- **parityType** (ParityType) - Optional - Parity type. Default: .none.
- **sendTwoStopBits** (Bool) - Optional - Whether to send two stop bits. Default: false.
- **dataBitsSize** (DataBitsSize) - Optional - Data bits size. Default: .bits8.
- **useHardwareFlowControl** (Bool) - Optional - Enable hardware flow control. Default: false.
- **useSoftwareFlowControl** (Bool) - Optional - Enable software flow control. Default: false.
- **processOutput** (Bool) - Optional - Process output. Default: false.

### Example
```swift
serialPort.setSettings(receiveRate: .baud9600, transmitRate: .baud9600, minimumBytesToRead: 1, timeout: 5, parityType: .none, sendTwoStopBits: false, dataBitsSize: .bits8, useHardwareFlowControl: false, useSoftwareFlowControl: false, processOutput: false)
```
```

--------------------------------

### openPort() and openPort(toReceive:andTransmit:)

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Functions to open the serial port with optional receive/transmit configuration.

```APIDOC
## [SDK] openPort()

### Description
Opens the serial port with default receive and transmit enabled. Can throw `PortError.mustReceiveOrTransmit`, `PortError.failedToOpen`, or `PortError.invalidPath`.

### Method
openPort()

### Parameters
None.

### Example
```swift
serialPort.openPort()
```
```

```APIDOC
## [SDK] openPort(toReceive:andTransmit:)

### Description
Opens the serial port with specified receive and transmit flags. Throws `PortError.mustReceiveOrTransmit` if both are false.

### Method
openPort(toReceive:andTransmit:)

### Parameters
- **receive** (Bool) - Required - Whether to enable receiving.
- **transmit** (Bool) - Required - Whether to enable transmitting.

### Example
```swift
serialPort.openPort(toReceive: true, andTransmit: false)
```
```

--------------------------------

### Set serial port baud rates and minimum bytes

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Set the baud rates and minimum bytes to read. Both transmit and receive rates must be supplied even if only one direction is used. minimumBytesToRead controls how many characters the system waits for before read() returns; use 1 if unsure.

```swift
serialPort.setSettings(receiveRate: .baud9600, transmitRate: .baud9600, minimumBytesToRead: 1)
```

--------------------------------

### Add SwiftSerial dependency to Package.swift

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Add SwiftSerial as a dependency in your Package.swift file. Use the package URL and version from: 0.1.2.

```swift
let package = Package(
    name: "NameOfMyProject",
    dependencies: [
        .package(url: "https://github.com/yeokm1/SwiftSerial.git", from: "0.1.2"),
        ...
    ]
    ...
)
```

--------------------------------

### writeData(_ data: Data) throws -> Int

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Writes binary data to the serial port. Blocks until all data is written and returns the number of bytes written.

```APIDOC
## writeData(_ data: Data) throws -> Int

### Description
Writes binary data to the serial port. Blocks until all data has been written and returns the number of bytes actually written. Internally calls `writeBytes()`.

### Method
writeData

### Parameters
- **data** (Data) - Required - The binary data to write to the serial port.

### Return Value
- **Int** - The number of bytes actually written.

### Throws
- `PortError.mustBeOpen` if the port is not open.

### Example
```swift
let data = Data([0x01, 0x02, 0x03])
let bytesWritten = try serialPort.writeData(data)
```
```

--------------------------------

### Open serial port with optional receive/transmit flags

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Open the serial port. The no-argument version enables both receive and transmit. The parameterized version allows receive-only, transmit-only, or both. Throws PortError.mustReceiveOrTransmit if both parameters are false, and can also throw PortError.failedToOpen and PortError.invalidPath.

```swift
func openPort()
func openPort(toReceive receive: Bool, andTransmit transmit: Bool)
```

--------------------------------

### writeChar(_ character: UnicodeScalar) throws -> Int

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Writes a single Unicode character to the serial port. Returns 1 if successful.

```APIDOC
## writeChar(_ character: UnicodeScalar) throws -> Int

### Description
Writes a single Unicode character to the serial port. Returns `1` if successful. Internally calls `writeString()`.

### Method
writeChar

### Parameters
- **character** (UnicodeScalar) - Required - The character to write.

### Return Value
- **Int** - Returns `1` if successful.

### Throws
- `PortError.mustBeOpen` if the port is not open.

### Example
```swift
let result = try serialPort.writeChar("A")
```
```

--------------------------------

### Read string of given length

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Read a string of the specified length. This is the easiest for text data and internally calls readData(). Throws PortError.mustBeOpen.

```swift
func readString(ofLength length: Int) throws -> String
```

--------------------------------

### writeString(_ string: String) throws -> Int

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Writes a string to the serial port. Blocks until all data is written and returns the number of bytes written.

```APIDOC
## writeString(_ string: String) throws -> Int

### Description
Writes a string to the serial port. This is the most straightforward function for writing data. It blocks until all data has been written and returns the number of bytes actually written. Internally calls `writeData()`.

### Method
writeString

### Parameters
- **string** (String) - Required - The string to write to the serial port.

### Return Value
- **Int** - The number of bytes actually written.

### Throws
- `PortError.mustBeOpen` if the port is not open.

### Example
```swift
let bytesWritten = try serialPort.writeString("Hello, world!")
```
```

--------------------------------

### Read a single byte

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Read a single byte. Works best when minimumBytesToRead is set to 1. Internally calls readBytes(). Throws PortError.mustBeOpen.

```swift
func readByte() throws -> UInt8
```

--------------------------------

### Read binary data of given length

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Read binary data of the specified length. Internally calls readBytes(). Throws PortError.mustBeOpen.

```swift
func readData(ofLength length: Int) throws -> Data
```

--------------------------------

### closePort()

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Closes the serial port. Should be called when done using the port.

```APIDOC
## closePort()

### Description
Closes the serial port once you are done using it.

### Method
closePort

### Parameters
None.

### Return Value
None.

### Example
```swift
serialPort.closePort()
```
```

--------------------------------

### writeBytes(from buffer: UnsafeMutablePointer<UInt8>, size: Int) throws -> Int

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Writes raw bytes from an unsafe mutable pointer to the serial port. Blocks until all data is written and returns the number of bytes written.

```APIDOC
## writeBytes(from buffer: UnsafeMutablePointer<UInt8>, size: Int) throws -> Int

### Description
Writes raw bytes from an unsafe mutable pointer to the serial port. Blocks until all data has been written and returns the number of bytes actually written.

### Method
writeBytes

### Parameters
- **buffer** (UnsafeMutablePointer<UInt8>) - Required - Pointer to the buffer containing the bytes to write.
- **size** (Int) - Required - The number of bytes to write.

### Return Value
- **Int** - The number of bytes actually written.

### Throws
- `PortError.mustBeOpen` if the port is not open.

### Example
```swift
var bytes: [UInt8] = [0x01, 0x02, 0x03]
let bytesWritten = try bytes.withUnsafeMutableBufferPointer { buffer in
    return try serialPort.writeBytes(from: buffer.baseAddress!, size: buffer.count)
}
```
```

--------------------------------

### Read a single character

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Read a single character as a UnicodeScalar. Works best when minimumBytesToRead is set to 1. Internally calls readByte(). Throws PortError.mustBeOpen.

```swift
func readChar() throws -> UnicodeScalar
```

--------------------------------

### Read until a specific character

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Read until the specified CChar is encountered. Returns the string read so far without that character. Throws PortError.mustBeOpen.

```swift
func readUntilChar(_ terminator: CChar) throws -> String
```

--------------------------------

### Reading Data

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Functions to read data from the serial port.

```APIDOC
## [SDK] readString(ofLength:)

### Description
Reads a string of the specified length. Blocking until the expected number of bytes is received. Can throw `PortError.mustBeOpen`.

### Method
readString(ofLength:)

### Parameters
- **length** (Int) - Required - Number of bytes to read.

### Returns
String - The read string.

### Example
```swift
let str = try serialPort.readString(ofLength: 10)
```
```

```APIDOC
## [SDK] readData(ofLength:)

### Description
Reads binary data of the specified length. Blocking until the expected number of bytes is received. Can throw `PortError.mustBeOpen`.

### Method
readData(ofLength:)

### Parameters
- **length** (Int) - Required - Number of bytes to read.

### Returns
Data - The read data.

### Example
```swift
let data = try serialPort.readData(ofLength: 10)
```
```

```APIDOC
## [SDK] readBytes(into:size:)

### Description
Reads bytes into a provided buffer. Blocking until the expected number of bytes is received. Can throw `PortError.mustBeOpen`.

### Method
readBytes(into:size:)

### Parameters
- **buffer** (UnsafeMutablePointer<UInt8>) - Required - Pointer to the buffer to read into.
- **size** (Int) - Required - Number of bytes to read.

### Returns
Int - Number of bytes read.

### Example
```swift
var buffer = [UInt8](repeating: 0, count: 10)
let count = try serialPort.readBytes(into: &buffer, size: 10)
```
```

```APIDOC
## [SDK] readLine()

### Description
Reads until a newline character is encountered. Blocking. Can throw `PortError.mustBeOpen` or `PortError.stringsMustBeUTF8`.

### Method
readLine()

### Parameters
None.

### Returns
String - The read line without the newline character.

### Example
```swift
let line = try serialPort.readLine()
```
```

```APIDOC
## [SDK] readUntilChar(_:)

### Description
Reads until the specified character is encountered. Blocking. Can throw `PortError.mustBeOpen`.

### Method
readUntilChar(_:)

### Parameters
- **terminator** (CChar) - Required - The character to stop reading at.

### Returns
String - The read string without the terminator.

### Example
```swift
let str = try serialPort.readUntilChar(10) // newline
```
```

```APIDOC
## [SDK] readByte()

### Description
Reads a single byte. Blocking. Can throw `PortError.mustBeOpen`.

### Method
readByte()

### Parameters
None.

### Returns
UInt8 - The read byte.

### Example
```swift
let byte = try serialPort.readByte()
```
```

```APIDOC
## [SDK] readChar()

### Description
Reads a single character. Blocking. Can throw `PortError.mustBeOpen`.

### Method
readChar()

### Parameters
None.

### Returns
UnicodeScalar - The read character.

### Example
```swift
let char = try serialPort.readChar()
```
```

--------------------------------

### Write Data to Serial Port

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Writes binary Data to the serial port. Blocking until all data is written. Returns the number of bytes written. Throws PortError.mustBeOpen if the port is not open. Internally calls writeBytes().

```swift
func writeData(_ data: Data) throws -> Int
```

--------------------------------

### Read a line until newline

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Read byte by byte until a newline character is encountered. Returns the string without the newline. Internally calls readUntilChar(). Can throw PortError.stringsMustBeUTF8 and PortError.mustBeOpen.

```swift
func readLine() throws -> String
```

--------------------------------

### Write Bytes from Unsafe Pointer

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Writes bytes from an unsafe pointer to the serial port. Blocking until all data is written. Returns the number of bytes written. Throws PortError.mustBeOpen if the port is not open.

```swift
func writeBytes(from buffer: UnsafeMutablePointer<UInt8>, size: Int) throws -> Int
```

--------------------------------

### Write String to Serial Port

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Writes a String to the serial port. Blocking until all data is written. Returns the number of bytes written. Throws PortError.mustBeOpen if the port is not open. Internally calls writeData().

```swift
func writeString(_ string: String) throws -> Int
```

--------------------------------

### Read bytes into unsafe pointer

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Read bytes directly into an unsafe pointer. Returns the number of bytes read. You are responsible for allocating and deallocating the pointer. Throws PortError.mustBeOpen.

```swift
func readBytes(into buffer: UnsafeMutablePointer<UInt8>, size: Int) throws -> Int
```

--------------------------------

### Write Character to Serial Port

Source: https://github.com/yeokm1/swiftserial/blob/master/README.md

Writes a single UnicodeScalar character to the serial port. Returns 1 if successful. Throws PortError.mustBeOpen if the port is not open. Internally calls writeString().

```swift
func writeChar(_ character: UnicodeScalar) throws -> Int{
```
Tokens:
Raw