-
-
Notifications
You must be signed in to change notification settings - Fork 408
Add Swift bindings and sample apps #834
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Andrey1994
merged 9 commits into
brainflow-dev:master
from
tsvvladimir:feature-swift-bindings
Aug 2, 2026
Merged
Changes from all commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
22d99a3
Add Swift bindings and sample apps
tsvvladimir 0b913fd
Add Xcode iOS demo project
tsvvladimir 979b412
Address Swift binding review feedback
tsvvladimir 10a7f12
Harden Swift binding validation
tsvvladimir 2199c58
Add Apple XCFramework artifact workflow
tsvvladimir c70c2ea
Align Apple artifacts with SwiftPM binary release guidance
tsvvladimir e4102c3
Address Swift binding review feedback
Andrey1994 3892a76
Apply clang-format to runtime loader
Andrey1994 a98d72f
Sync Swift board ids with native constants
Andrey1994 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| # Agent Notes | ||
|
|
||
| ## Apple XCFramework Artifacts | ||
|
|
||
| Apple binary artifacts are generated build outputs. They contain framework-wrapped XCFrameworks | ||
| for iOS device, iOS simulator, and macOS app integration, plus a generated | ||
| `BrainFlowSwiftBinaryPackage` for app developers. | ||
|
|
||
| Regenerate the artifacts from the repository root: | ||
|
|
||
| ```bash | ||
| tools/apple/regenerate_artifacts.sh | ||
| ``` | ||
|
|
||
| Verify an existing artifact tree: | ||
|
|
||
| ```bash | ||
| tools/apple/verify_xcframeworks.sh build/apple_xcframeworks | ||
| ``` | ||
|
|
||
| The regeneration script builds native BrainFlow Apple slices, packages the XCFrameworks, verifies | ||
| the required core frameworks, and creates: | ||
|
|
||
| - `BrainFlowAppleXCFrameworks.zip` for complete archive downloads. | ||
| - `SwiftPMArtifacts/*.xcframework.zip` with each `.xcframework` at the ZIP root. | ||
| - `BrainFlowSwiftPackageRemote`, a generated URL-based SwiftPM package manifest. | ||
| - `swiftpm-checksums.txt` and `swiftpm-checksums.json` from `swift package compute-checksum`. | ||
|
|
||
| By default, `tools/apple/regenerate_artifacts.sh` and `tools/apple/build_xcframeworks.sh` write to | ||
| `build/apple_xcframeworks`. Do not commit `build/`, `build_apple/`, `swift_package/Artifacts/Apple`, | ||
| or local `installed/` outputs. | ||
|
|
||
| The iOS demo and macOS packaging script default to `build/apple_xcframeworks/XCFrameworks`. | ||
| CI may override artifact paths with | ||
| `BRAINFLOW_APPLE_XCFRAMEWORKS_DIR`. | ||
|
|
||
| When changing Apple artifact generation, regenerate locally and run verification. CI uploads the | ||
| aggregate archive, the individual SwiftPM `.xcframework.zip` assets, checksums, generated remote | ||
| Swift package, and `manifest.json` as the distributable artifact set. Generated framework headers | ||
| and binaries should come from the scripts, not from files copied into the repository. | ||
|
|
||
| For a BrainFlow release or Apple-library refresh, build from the release commit/tag with | ||
| `BRAINFLOW_VERSION` set. Set `BRAINFLOW_APPLE_RELEASE_BASE_URL` when release assets are hosted | ||
| outside the default GitHub Release tag URL. Regenerate artifacts, verify the generated tree, | ||
| smoke-test the generated Swift binary package, validate the iOS/macOS sample apps against the | ||
| regenerated XCFrameworks, and publish the individual SwiftPM ZIPs next to their checksum files. | ||
| Do not manually patch release frameworks after generation; update source and rerun the script. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,74 @@ | ||
| .. _app-store-readiness-label: | ||
|
|
||
| App Store Readiness | ||
| =================== | ||
|
|
||
| This checklist is intentionally separate from the sample source because final App Store submission | ||
| requires a developer account, bundle IDs, certificates, provisioning profiles, App Store Connect | ||
| records, screenshots, and final product metadata. | ||
|
|
||
| Shared | ||
| ------ | ||
|
|
||
| - Build with the current App Store-required SDK in Xcode. | ||
| - Replace placeholder bundle IDs. | ||
| - Add production app icons and screenshots. | ||
| - Keep the synthetic-board demo path available so App Review can exercise the app without external | ||
| hardware. | ||
| - Embed BrainFlow XCFramework products in the app bundle and sign them with the app. | ||
| - Use the generated :code:`BrainFlowSwiftBinaryPackage` for production app integration. Do not rely | ||
| on :code:`BRAINFLOW_LIB_DIR`, local :code:`installed/lib` folders, or loose development dylibs in | ||
| App Store builds. | ||
| - Confirm final privacy answers reflect real-board connectivity, Bluetooth, networking, files, and | ||
| any third-party native dependencies actually shipped. | ||
| - Run an archive build and install it on a physical device or clean Mac before upload. | ||
| - Verify the archive contains only device slices for iOS, with embedded framework install names in | ||
| the form :code:`@rpath/<Framework>.framework/<Framework>`. | ||
|
|
||
| iOS | ||
| --- | ||
|
|
||
| - Use :code:`examples/apps/ios/BrainFlowiOSDemo` as the Xcode app project. | ||
| - Use the generated Swift binary package or embed framework slices from | ||
| :code:`build/apple_xcframeworks/XCFrameworks`. | ||
| - Provide iOS-compatible BrainFlow native binaries through XCFrameworks. The high-level Swift | ||
| package compiles for iOS, but BrainFlow calls can only run when matching native frameworks are | ||
| embedded and signed. | ||
| - For Muse native BLE boards, build BrainFlow native libraries with BLE support enabled for the | ||
| target platform and keep the Bluetooth privacy string in the app plist. | ||
| - Keep permissions minimal. The synthetic-board demo needs no network or file permissions. | ||
| - Test via TestFlight before App Store submission. | ||
|
|
||
| macOS | ||
| ----- | ||
|
|
||
| - Use :code:`swift_package` product :code:`BrainFlowMacDemo` for local development, or package it | ||
| with :code:`tools/apple/package_macos_demo_app.sh` for app-bundle smoke testing. | ||
| - Add the files from :code:`examples/apps/macos/BrainFlowMacDemo`. | ||
| - Enable App Sandbox. | ||
| - Embed and sign BrainFlow XCFramework products. | ||
| - Verify dynamic loading works inside the app bundle, not only with :code:`BRAINFLOW_LIB_DIR`. | ||
|
|
||
| Production Gate | ||
| --------------- | ||
|
|
||
| - Swift package builds. | ||
| - Swift tests pass with native libraries present. | ||
| - CLI smoke test succeeds with the synthetic board. | ||
| - :code:`tools/apple/build_xcframeworks.sh` and :code:`tools/apple/verify_xcframeworks.sh` pass. | ||
| - :code:`tools/apple/regenerate_artifacts.sh` refreshes :code:`build/apple_xcframeworks`, and | ||
| :code:`tools/apple/verify_xcframeworks.sh build/apple_xcframeworks` passes. | ||
| - The Apple release artifact set includes the individual SwiftPM XCFramework zips, | ||
| :code:`swiftpm-checksums.txt`, :code:`swiftpm-checksums.json`, | ||
| :code:`BrainFlowSwiftPackageRemote`, :code:`BrainFlowAppleXCFrameworks.zip`, | ||
| :code:`BrainFlowAppleXCFrameworks.zip.sha256`, :code:`checksums.sha256`, and | ||
| :code:`manifest.json` from the same build. | ||
| - :code:`manifest.json` records the BrainFlow version, source revision, toolchain versions, | ||
| deployment targets, optional native feature flags, SwiftPM release URL base, and binary target | ||
| checksums. | ||
| - A clean app consumes :code:`BrainFlowSwiftBinaryPackage` without building native BrainFlow | ||
| locally. | ||
| - iOS and macOS app targets launch, handle missing native frameworks gracefully, and run the | ||
| synthetic-board workflow when frameworks are embedded. | ||
| - Accessibility labels and dynamic text behavior are reviewed in the sample apps. | ||
| - Crash logs are clean after repeated start, stop, read, and release cycles. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
add all examples to CI as in brainflow dosc https://brainflow.readthedocs.io/en/stable/Examples.html#python
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Addressed in c030c76. I added all documented Swift examples as SwiftPM executable products and added a macOS CI step that runs them all with
BRAINFLOW_LIB_DIR=$GITHUB_WORKSPACE/installed/lib swift run <example>.