Update README.md

Examples/SwiftSerialExample/Sources/main.swift

@@ -1,10 +1,14 @@
 import Foundation
-import SwiftLinuxSerial
+import SwiftSerial
 
 print("You should do a loopback i.e short the TX and RX pins of the target serial port before testing.")
 
 let testString: String = "The quick brown fox jumps over the lazy dog 01234567890."
 
+let numberOfMultiNewLineTest : Int = 5
+
+let test3Strings: String = testString + "\n" + testString + "\n" + testString + "\n"
+
 let arguments = CommandLine.arguments
 guard arguments.count >= 2 else {
     print("Need serial port name, e.g. /dev/ttyUSB0 as the first argument.")
@@ -12,9 +16,11 @@ guard arguments.count >= 2 else {
 }
 
 let portName = arguments[1]
-let serialPort: SerialPort = SerialPort(name: portName)
+let serialPort: SerialPort = SerialPort(path: portName)
 
 do {
+
+    print("Attempting to open port: \(portName)")
     try serialPort.openPort()
     print("Serial port \(portName) opened successfully.")
     defer {
@@ -41,6 +47,36 @@ do {
         print("<\(stringReceived)>")
     }
 
+
+    print("Now testing reading/writing of \(numberOfMultiNewLineTest) lines")
+
+    var multiLineString: String = ""
+
+
+    for i in 1...numberOfMultiNewLineTest { 
+        multiLineString += testString + "\n"
+    }
+
+    print("Now writing multiLineString")
+
+    var _ = try serialPort.writeString(multiLineString)
+
+
+    for i in 1...numberOfMultiNewLineTest {
+        let stringReceived = try serialPort.readLine()
+          
+        if testString == stringReceived {
+            print("Received string \(i) is the same as transmitted section. Moving on...")
+        } else {
+            print("Uh oh! Received string \(i) is not the same as what was transmitted. This was what we received,")
+            print("<\(stringReceived)>")
+            break
+        }
+    }
+
+
+    print("We successfully received back \(numberOfMultiNewLineTest) lines")
+
 } catch PortError.failedToOpen {
     print("Serial port \(portName) failed to open. You might need root permissions.")
 } catch {

README.md

@@ -1,2 +1,193 @@
 # SwiftSerial
-A Swift 3 Linux and Mac library for reading and writing to serial ports. 
+A Swift 3 Linux and Mac library for reading and writing to serial ports. This library has been tested to work on macOS Sierra, Linux Mint 18 (based on Ubuntu 16.04) and on the [Raspberry Pi 3 on Ubuntu 16.04](https://wiki.ubuntu.com/ARM/RaspberryPi). Other platforms using Ubuntu like the Beaglebone might work as well.
+
+This library is an improvement over my previous now deprecated library [SwiftLinuxSerial](https://github.com/yeokm1/SwiftLinuxSerial) which was less Swifty and supported only Linux. This library is thanks largely to [Jay Jun](https://github.com/jayjun). His original pull request can be found [here](https://github.com/yeokm1/SwiftLinuxSerial/pull/1).
+
+<p>
+![macOS](https://img.shields.io/badge/os-macOS-green.svg?style=flat)
+<img src="https://img.shields.io/badge/OS-Ubuntu-blue.svg?style=flat" alt="Swift 3.0">
+<a href="https://developer.apple.com/swift"><img src="https://img.shields.io/badge/swift3-compatible-orange.svg?style=flat" alt="Swift 3 compatible" /></a>
+<a href="https://raw.githubusercontent.com/uraimo/SwiftyGPIO/master/LICENSE"><img src="http://img.shields.io/badge/license-MIT-blue.svg?style=flat" alt="License: MIT" /></a>
+
+## Mac OS Preparation
+
+You should have Xcode 8 installed with the command line tools.
+
+## Linux System Preparation
+
+Before using this library, I assume you already have Ubuntu installed and fully updated on your system or single-board computer. To get Ubuntu installed on the Raspberry Pi, use this [link](https://wiki.ubuntu.com/ARM/RaspberryPi). 
+
+### Install Swift 3 on Ubuntu on x86-based machines
+
+Reference instructions obtained from [here](http://dev.iachieved.it/iachievedit/swift-3-0-for-ubuntu-16-04-xenial-xerus/). We will use a Swift binary produced by iachievedit.
+```bash
+#Add the repository key for iachievedit
+wget -qO- http://dev.iachieved.it/iachievedit.gpg.key | sudo apt-key add -
+
+#Add the Xenial repository to sources.list
+echo "deb http://iachievedit-repos.s3.amazonaws.com/ xenial main" | sudo tee --append /etc/apt/sources.list
+
+sudo apt-get update
+sudo apt-get install swift-3.0
+
+nano ~/.profile
+#This command can be added to your bash profile so Swift will be in your PATH after a reboot
+export PATH=/opt/swift/swift-3.0/usr/bin:$PATH
+```
+
+### Install Swift 3 on Ubuntu on Raspberry Pi 3
+Instructions from this section is referenced from this [link](http://dev.iachieved.it/iachievedit/swift-3-0-on-raspberry-pi-2-and-3/).
+
+Since Swift 3 is still rapidly evolving, we should not use the Swift packages provided via the apt package manager if they exist and instead use prebuilt binaries instead. We will also not install Swift 3 to the system-level directories to avoid problems in case we have to update the version.
+
+Go to this [page](http://swift-arm.ddns.net/job/Swift-3.0-Pi3-ARM-Incremental/lastSuccessfulBuild/artifact/) and find what it is the link to the latest Swift compiled `tar.gz` package.
+
+```bash
+#Install dependencies
+sudo apt-get install libcurl4-openssl-dev libicu-dev clang-3.6
+sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-3.6 100
+sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-3.6 100
+
+cd ~
+#Replace the link below with the latest version
+wget http://swift-arm.ddns.net/job/Swift-3.0-Pi3-ARM-Incremental/lastSuccessfulBuild/artifact/swift-3.0-2016-10-13-RPi23-ubuntu16.04.tar.gz	
+mkdir swift-3.0
+cd swift-3.0 && tar -xzf ../swift-3.0-2016-10-13-RPi23-ubuntu16.04.tar.gz	
+
+#This command can be added to your bash profile so Swift will be in your PATH after a reboot
+nano ~/.profile
+export PATH=$HOME/swift-3.0/usr/bin:$PATH
+```
+## Jumping straight into sample code
+
+To get started quickly, you can take a look at my example project [here](Examples/SwiftSerialExample). In order to run the example properly, you need to connect one of your (USB/UART) serial ports in a loopback manner. Basically, you short the TX and RX pins of the serial port.
+
+```bash
+git clone https://github.com/yeokm1/SwiftLinuxSerial.git
+cd SwiftLinuxSerial/Examples/SwiftSerialExample/
+swift build
+#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
+
+#If all goes well you should see a series of messages informing you that data transmitted has been received properly.
+```
+
+## Integrating with your project
+
+Add SwiftSerial as a dependency to your project by editing the `Package.swift` file.
+
+```swift
+let package = Package(
+    name: "NameOfMyProject",
+    dependencies: [
+        .Package(url: "https://github.com/yeokm1/SwiftSerial.git", majorVersion: 0),
+        ...
+    ]
+    ...
+)
+```
+
+Make sure to `import SwiftSerial` in the source files that use my API.
+
+Then run `swift build` to download the dependencies and compile your project. Your executable will be found in the `./.build/debug/` directory.
+
+## API usage
+
+### Initialise the class
+
+```swift
+let serialPort: SerialPort = SerialPort(path: portName)
+```
+Supply the portname that you wish to open like `/dev/ttyUSB0` or `/dev/usbserial`.
+
+### Opening the Serial Port
+
+```swift
+func openPort()
+func openPort(toReceive receive: Bool, andTransmit transmit: Bool)
+```
+Opening the port without any parameters will set the port to receive and transmit by default. You can still choose to receive-only, transmit-only or both. Will throw `PortError.mustReceiveOrTransmit` if you set both parameters to false. Can also throw `PortError.failedToOpen` and `PortError.invalidPath`.
+
+### Set port settings
+
+```swift
+serialPort.setSettings(receiveRate: .baud9600, transmitRate: .baud9600, minimumBytesToRead: 1)
+```
+The port settings call can be as simple as the above. For the baud rate, just supply both transmit and receive even if you are only intend to use one function. For example, transmitRate will be ignored if you specified `andTransmit : false` when opening the port. 
+
+`minimumBytesToRead` determines how many characters Linux must wait to receive before it will return from a [read()](https://linux.die.net/man/2/read) function. If in doubt, just put 1.
+
+This function has been defined with default settings as shown in the function definition.
+
+```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)
+```
+If the default settings do not suit you, just pass in extra parameters to override them.
+
+### Reading data from port
+
+There are several functions you can use to read data. All functions here are blocking till the expected number of bytes has been received or a condition has been met. All functions can throw `PortError.mustBeOpen`.
+
+```swift
+func readString(ofLength length: Int) throws -> String
+```
+This is the easiest to use if you are sending text data. Just provide how many bytes you expect to read. The result will then be returned as a typical Swift String. This function internally calls `readData()`.
+
+```swift
+func readData(ofLength length: Int) throws -> Data
+```
+This function is if you intend to receive binary data. This function internally calls `readBytes()`
+
+```swift
+func readBytes(into buffer: UnsafeMutablePointer<UInt8>, size: Int) throws -> Int
+```
+If you intend to play with unsafe pointers directly, this is the function for you! Will return the number of bytes read. Note that you are responsible for allocating the pointer before passing into this function then deallocate the pointer once you are done.
+
+```swift
+func readLine() throws -> String
+```
+Read byte by byte till the newline character `\n` is encountered. A String containing the result so far will be returned without the newline character. This function internally calls `readUntilChar()`. Can throw `PortError.stringsMustBeUTF8`.
+
+```swift
+func readUntilChar(_ terminator: CChar) throws -> String
+```
+Keep reading until the specified CChar is encountered. Return the string read so far without that value.
+
+### Writing data to the port
+
+There are several functions you can use to write data. All functions here are blocking till all the data has been written. All functions can throw `PortError.mustBeOpen`.
+
+```swift
+func writeString(_ string: String) throws -> Int
+```
+Most straightforward function, String in then transmit! Will return how many bytes actually written. Internally calls `writeData()`
+
+```swift
+func writeData(_ data: Data) throws -> Int
+```
+Binary data in, then transmit! Will return how many bytes actually written. Internally calls `writeBytes()`.
+
+```swift
+func writeBytes(from buffer: UnsafeMutablePointer<UInt8>, size: Int) throws -> Int
+```
+Function for those that want to mess with unsafe pointers. You have to specify how many bytes have to be written. Will return how many bytes actually written.
+
+### Closing the port
+
+Just do `serialPort.closePort()` to close the port once you are done using it.
+
+## External References
+
+This library cannot be written without the amazing reference code I depended on.
+
+1. [Xanthium's Serial Port Programming on Linux](http://xanthium.in/Serial-Port-Programming-on-Linux)
+2. [Chrishey Drick's Reading data from Serial Port](https://chrisheydrick.com/2012/06/17/how-to-read-serial-data-from-an-arduino-in-linux-with-c-part-3/)

Sources/SwiftSerial.swift

@@ -183,6 +183,24 @@ public enum DataBitsSize {
             return tcflag_t(CS8)
         }
     }
+
+}
+
+public enum ParityType {
+    case none
+    case even
+    case odd
+
+	var parityValue: tcflag_t {
+        switch self {
+        case .none:
+            return 0
+        case .even:
+            return tcflag_t(PARENB)
+        case .odd:
+            return tcflag_t(PARENB | PARODD)
+        }
+    }
 }
 
 public enum PortError: Int32, Error {
@@ -215,16 +233,24 @@ public class SerialPort {
             throw PortError.mustReceiveOrTransmit
         }
 
+        var readWriteParam : Int32
+
         if receive && transmit {
-            fileDescriptor = open(path, O_RDWR | O_NOCTTY)
+            readWriteParam = O_RDWR
         } else if receive {
-            fileDescriptor = open(path, O_RDONLY | O_NOCTTY)
+            readWriteParam = O_RDONLY
         } else if transmit {
-            fileDescriptor = open(path, O_WRONLY | O_NOCTTY)
+            readWriteParam = O_WRONLY
         } else {
             fatalError()
         }
 
+    #if os(Linux)
+        fileDescriptor = open(path, readWriteParam | O_NOCTTY)
+    #elseif os(OSX)
+        fileDescriptor = open(path, readWriteParam | O_NOCTTY | O_EXLOCK | O_NONBLOCK)
+    #endif
+
         // Throw error if open() failed
         if fileDescriptor == PortError.failedToOpen.rawValue {
             throw PortError.failedToOpen
@@ -235,16 +261,18 @@ public class SerialPort {
                             transmitRate: BaudRate,
                             minimumBytesToRead: Int,
                             timeout: Int = 0, /* 0 means wait indefinitely */
-                            enableParity: Bool = false,
+                            parityType: ParityType = .none,
                             sendTwoStopBits: Bool = false, /* 1 stop bit is the default */
                             dataBitsSize: DataBitsSize = .bits8,
                             useHardwareFlowControl: Bool = false,
                             useSoftwareFlowControl: Bool = false,
                             processOutput: Bool = false) {
+        
         guard let fileDescriptor = fileDescriptor else {
             return
         }
 
+
         // Set up the control structure
         var settings = termios()
 
@@ -255,12 +283,8 @@ public class SerialPort {
         cfsetispeed(&settings, receiveRate.speedValue)
         cfsetospeed(&settings, transmitRate.speedValue)
 
-        // Set parity enable flag
+        // Enable parity (even/odd) if needed
-        if enableParity {
+        settings.c_cflag |= parityType.parityValue
-            settings.c_cflag |= ~tcflag_t(PARENB)
-        } else {
-            settings.c_cflag &= ~tcflag_t(PARENB)
-        }
 
         // Set stop bit flag
         if sendTwoStopBits {
@@ -312,6 +336,8 @@ public class SerialPort {
         }
 
         //Special characters
+        //We do this as c_cc is a C-fixed array which is imported as a tuple in Swift.
+        //To avoid hardcoding the VMIN or VTIME value to access the tuple value, we use the typealias instead
     #if os(Linux)
         typealias specialCharactersTuple = (VINTR: cc_t, VQUIT: cc_t, VERASE: cc_t, VKILL: cc_t, VEOF: cc_t, VTIME: cc_t, VMIN: cc_t, VSWTC: cc_t, VSTART: cc_t, VSTOP: cc_t, VSUSP: cc_t, VEOL: cc_t, VREPRINT: cc_t, VDISCARD: cc_t, VWERASE: cc_t, VLNEXT: cc_t, VEOL2: cc_t, spare1: cc_t, spare2: cc_t, spare3: cc_t, spare4: cc_t, spare5: cc_t, spare6: cc_t, spare7: cc_t, spare8: cc_t, spare9: cc_t, spare10: cc_t, spare11: cc_t, spare12: cc_t, spare13: cc_t, spare14: cc_t, spare15: cc_t)
         var specialCharacters: specialCharactersTuple = (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0) // NCCS = 32
@@ -356,7 +382,16 @@ extension SerialPort {
         }
 
         let bytesRead = try readBytes(into: buffer, size: length)
-        let data = Data(bytes: buffer, count: bytesRead)
+
+        var data : Data
+
+        if bytesRead > 0 {
+            data = Data(bytes: buffer, count: bytesRead)
+        } else {
+            //This is to avoid the case where bytesRead can be negative causing problems allocating the Data buffer
+       	    data = Data(bytes: buffer, count: 0)
+        }
+
         return data
     }
 
@@ -366,6 +401,7 @@ extension SerialPort {
 
         while remainingBytesToRead > 0 {
             let data = try readData(ofLength: remainingBytesToRead)
+
             if let string = String(data: data, encoding: String.Encoding.utf8) {
                 result += string
                 remainingBytesToRead -= data.count
@@ -384,13 +420,17 @@ extension SerialPort {
             buffer.deallocate(capacity: 1)
         }
 
-        // Read byte by byte
+        while true {
-        while try readBytes(into: buffer, size: 1) > 0 {
+        	let bytesRead = try readBytes(into: buffer, size: 1)
+
+        	if bytesRead > 0 {
         		let character = CChar(buffer[0])
-            if character != terminator {
+                
-                data.append(buffer, count: 1)
+                if character == terminator {
-            } else {
                     break
+                } else {
+                    data.append(buffer, count: 1)
+                }
         	}
         }