WIP initial commit for issue 327: Add Swift binding

docs/BuildBrainFlow.rst

@@ -127,6 +127,47 @@ Rust
         cd brainflow
         cargo build --features generate_binding
 
+Swift
+-------
+
+The following instructions are tested on a MacBook Pro M1 using Xcode 13.4 and macOS Monterey 12.3.1. 
+
+The Xcode build scheme is for destination "My Mac (Rosetta)". The dylibs are universal (built for macos-arm64_x86_64.) The target build architecture is set to $(ARCHS_STANDARD).
+
+High level steps:
+- Build the universal dylibs
+- Copy the entire BrainFlow package from swift-package into the top level folder of your Xcode project.
+- Copy the BrainFlowBindings subfolder from the package into your target app group.
+- Set the briding header
+- Compile the package
+- Set the package dependency
+- Build
+
+Assumptions:
+- the BrainFlow repo is cloned to /Users/myusername/brainflow
+- your Xcode project is located at /Users/myusername/myproject
+- within your Xcode project is a group named myapp
+
+Detailed steps:
+- in a shell such as iTerm2:
+
+  cd /Users/myusername/brainflow/swift-package
+  ./build_package_macOS.sh
+
+- Copy the BrainFlow folder and its entire contents from /Users/myusername/brainflow/swift-package to /Users/myusername/myproject.
+- In Xcode select the top-level project and then click File->Add Packages...Add Local...
+- Select /Users/myusername/myproject/BrainFlow. Click Open.
+- Drag-and-drop the BrainFlowBindings subfolder from myproject/Packages/BrainFLow/Sources into myproject/myapp. 
+- A dialog will pop up. In the dialog check the "Copy items if needed" box, select "Create groups", and check the box(es) next to your target(s).
+- In the build settings of your build target, search for "bridging". Set the Objective-C Bridging Header to "BrainFlow/BrainFlow.h".
+- In the scheme selector at the top of the window, select the BrainFlow scheme for "My Mac (Rosetta)".
+- Press Command-B (build) to build the package.
+- In the General settings of your build target, scroll down to Frameworks, Libraries and Embedded Content.
+- Click the plus button and select the BrainFlow package under the Workspace group.
+- In the scheme selector at the top of the window, select the myapp scheme for "My Mac (Rosetta)".
+- Press Command-B (build) to build the target.
+
+
 Docker Image
 --------------
 

docs/Examples.rst

@@ -492,3 +492,9 @@ Notebooks
    ./notebooks/brainflow_mne
    ./notebooks/denoising
    ./notebooks/band_power
+
+Swift
+------
+
+.. literalinclude:: ../swift-package/BrainFlow/Tests/BrainFlowTests/BrainFlowCITests.swift
+   :language: swift

docs/UserAPI.rst

@@ -159,3 +159,13 @@ Example:
 
 .. literalinclude:: ../rust_package/brainflow/examples/get_data.rs
    :language: rust
+
+Swift API Reference
+---------------------
+
+The Swift bindings call the C++ API via Objective-C. The public headers are resolved by Xcode via a bridging header (see build instructions for details.)                        
+Example:
+
+.. literalinclude:: ../swift-package/examples/Headset.swift
+   :language: swift
+

swift-package/.gitignore

@@ -0,0 +1,7 @@
+.DS_Store
+/.build
+/Packages
+/*.xcodeproj
+xcuserdata/
+DerivedData/
+.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata

swift-package/BrainFlow/BrainFlow.h

@@ -0,0 +1,13 @@
+//
+//  Created by Scott Miller on 4/9/22.
+//
+
+#ifndef BrainFlow_h
+#define BrainFlow_h
+
+#include <board_controller.h>
+#include <data_handler.h>
+#include <board_info_getter.h>
+#include <ml_module.h>
+
+#endif /* BrainFlow_h */

swift-package/BrainFlow/Package.resolved

@@ -0,0 +1,16 @@
+{
+  "object": {
+    "pins": [
+      {
+        "package": "swift-numerics",
+        "repositoryURL": "https://github.com/apple/swift-numerics.git",
+        "state": {
+          "branch": null,
+          "revision": "0a5bc04095a675662cf24757cc0640aa2204253b",
+          "version": "1.0.2"
+        }
+      }
+    ]
+  },
+  "version": 1
+}

swift-package/BrainFlow/Package.swift

@@ -0,0 +1,50 @@
+// swift-tools-version:5.3
+import PackageDescription
+
+let package = Package(
+    name: "BrainFlow",
+    platforms: [
+        .macOS(.v10_15), .iOS(.v13)
+    ],
+    products: [
+        // Products define the executables and libraries a package produces, and make them visible to other packages.
+        .library(name: "BrainFlow",
+                 targets: ["BrainFlow", "BoardController", "DataHandler", "MLModule", "BrainBitLib"])
+    ],
+    dependencies: [
+        .package(name: "swift-numerics",
+                 url: "https://github.com/apple/swift-numerics.git", .upToNextMajor(from: "1.0.0"))
+    ],
+    targets: [
+        .target(
+            name: "BrainFlow",
+            dependencies: [.product(name: "Numerics", package: "swift-numerics"),
+                           .target(name: "BoardController")]
+        ),
+        .binaryTarget(
+            name: "BoardController",
+            path: "BoardController.xcframework"
+        ),
+        .binaryTarget(
+            name: "DataHandler",
+            path: "DataHandler.xcframework"
+        ),
+        .binaryTarget(
+            name: "MLModule",
+            path: "MLModule.xcframework"
+        ),
+        .binaryTarget(
+            name: "BrainBitLib",
+            path: "BrainBitLib.xcframework"
+        ),
+        .testTarget(
+            name: "BrainFlowTests",
+            dependencies: ["BrainFlow", .product(name: "Numerics", package: "swift-numerics")],
+            sources: ["BoardShimTests.swift",
+                      "BrainFlowCItests.swift",
+                      "BrainFlowTests.swift",
+                      "DataFilterTests.swift"]
+        )
+    ]
+)
+

swift-package/BrainFlow/README.md

@@ -0,0 +1,4 @@
+# BrainFlow
+
+Swift bindings for the BrainFlow C++ API. Contributed by Scott Miller for Aeris Rising, LLC.
+

swift-package/BrainFlow/Sources/BrainFlow/dummy.swift

@@ -0,0 +1,7 @@
+
+import Foundation
+
+struct dummy {
+    let num = 1
+}
+

swift-package/BrainFlow/Sources/BrainFlowBindings/BoardDescription.swift

@@ -0,0 +1,47 @@
+//
+//  BoardDescription.swift
+//  a Swift reimagining of BrainFlow's board_description data type
+//
+//  Created by Scott Miller for Aeris Rising, LLC on 8/23/21.
+//
+import Foundation
+//import BrainFlow
+
+struct BoardDescription: Codable, Equatable {
+    let package_num_channel: Int32
+    let timestamp_channel: Int32
+    let accel_channels: [Int32]?
+    let ecg_channels: [Int32]?
+    let eeg_channels: [Int32]?
+    let eeg_names: String?
+    let emg_channels: [Int32]?
+    let eog_channels: [Int32]?
+    let marker_channel: Int32?
+    let name: String?
+    let num_rows: Int32?
+    let sampling_rate: Int32?
+    let battery_channel: Int32?
+    let eda_channels: [Int32]?
+    let gyro_channels: [Int32]?
+    let ppg_channels: [Int32]?
+    let resistance_channels: [Int32]?
+    let temperature_channels: [Int32]?
+
+    // decode the input JSON into self:
+    init(_ descriptionJSON: String) throws {
+        guard descriptionJSON != "" else {
+            throw BrainFlowException("Nil board description JSON", .JSON_NOT_FOUND_ERROR)
+        }
+
+        let decoder = JSONDecoder()
+        let jsonData = Data(descriptionJSON.utf8)
+
+        do {
+            let json = try decoder.decode(type(of: self), from: jsonData)
+            self = json
+        } catch {
+            try? BoardShim.logMessage(.LEVEL_CRITICAL, "board description JSON decoding error:\n \(error)")
+            throw BrainFlowException("Invalid board description JSON", .NO_SUCH_DATA_IN_JSON_ERROR)
+        }
+    }
+}