diff --git a/_data/navigation.yml b/_data/navigation.yml index 2b65aa9a..0028504d 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -106,6 +106,8 @@ wiki: url: /wiki/common-platforms/ros2-navigation-for-clearpath-husky/ - title: Hello Robot Stretch RE1 url: /wiki/common-platforms/hello-robot + - title: Building an iOS App for ROS 2 Integration + url: /wiki/common-platforms/ros2-ios-app-with-swift/ - title: Configure VS Code for ROS 2 url: /wiki/common-platforms/configure-vscode-for-ros2/ - title: Building ROS2 Custom Packages diff --git a/wiki/common-platforms/index.md b/wiki/common-platforms/index.md index bf63f47c..560dc944 100644 --- a/wiki/common-platforms/index.md +++ b/wiki/common-platforms/index.md @@ -14,6 +14,9 @@ We encourage contributions to further enhance the knowledge base in this section - **[Asctec UAV Setup Guide](/wiki/common-platforms/asctec-uav-setup-guide/)** A detailed tutorial for setting up the Asctec Pelican UAV for autonomous waypoint navigation using ROS. Covers configuring network settings, flashing firmware, and running the ROS package on the onboard Atomboard. +- **[Building an iOS App for ROS 2 Integration](/wiki/common-platforms/ros2-ios-app-with-swift/)** + A step-by-step guide on building an iOS application integrated with ROS 2 using the SwiftROS2 framework, covering project setup, node configuration, and SwiftUI interface development. + - **[Building a Custom Drone for the DARPA Triage Challenge](/wiki/common-platforms/building-custom-drone-for-darpa-triage-challenge/)** A comprehensive guide to designing and building UAVs for disaster scenarios. Covers both modified commercial platforms and fully custom designs, including hardware selection, electrical integration, and software configuration. @@ -96,6 +99,11 @@ Here is a compiled list of external resources referenced in the subsections: - [Universal Robots ROS Driver](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver) - [MoveIt Setup for UR5e](http://moveit.ros.org/) +10. **ROS 2 iOS Integration** + - [SwiftROS2 Framework](https://github.com/strapsai/swift-ros2) + - [Fast RTPS Documentation](https://fast-dds.docs.eprosima.com/en/latest/) + - [Apple SwiftUI Documentation](https://developer.apple.com/documentation/swiftui) + ## Development Needs We seek contributions in the following areas: - Detailed guides for setting up and integrating additional platforms like Boston Dynamics robots or custom robotic arms. diff --git a/wiki/common-platforms/ros2-ios-app-with-swift.md b/wiki/common-platforms/ros2-ios-app-with-swift.md new file mode 100644 index 00000000..0969c151 --- /dev/null +++ b/wiki/common-platforms/ros2-ios-app-with-swift.md @@ -0,0 +1,247 @@ +--- +date: 2025-04-29 +title: Building an iOS App for ROS 2 Integration +--- + +This document provides a detailed, step-by-step guide on building an iOS application integrated with ROS 2 using the SwiftROS2 framework. In this guide, you will learn how to set up the project, configure ROS 2 nodes, implement publishers and subscribers to exchange messages via DDS, and build a SwiftUI-based user interface for operating ROS 2 functionality. In addition, this guide offers an in-depth explanation of the dependency packages and how the DDS mechanism is implemented to support ROS 2 communication. This guide assumes you have a basic understanding of Swift and iOS development. By the end, you will be able to create and run an iOS app that seamlessly interacts with ROS 2 nodes. + +The complete code can be found at . + +## Table of Contents +- [Introduction](#introduction) +- [Background and Key Concepts](#background-and-key-concepts) +- [Step-by-Step Tutorial: Building an iOS App for ROS 2](#step-by-step-tutorial-building-an-ios-app-for-ros-2) + - [1. Project Setup and Dependencies](#1-project-setup-and-dependencies) + - [2. Creating the ROS 2 Node](#2-creating-the-ros-2-node) + - [3. Implementing Publishers and Subscribers](#3-implementing-publishers-and-subscribers) + - [4. Building the User Interface](#4-building-the-user-interface) + - [5. Running and Testing the App](#5-running-and-testing-the-app) +- [Detailed Explanation of Dependencies](#detailed-explanation-of-dependencies) + - [swift-ros2](#swift-ros2) + - [FastRTPSSwift](#fastrtpsswift) + - [ros2msg](#ros2msg) +- [Understanding the DDS Mechanism](#understanding-the-dds-mechanism) +- [Usage Instructions](#usage-instructions) +- [Summary](#summary) +- [See Also](#see-also) +- [Further Reading](#further-reading) +- [References](#references) + +## Introduction +This tutorial explains how to build an iOS app that leverages ROS 2 capabilities using the SwiftROS2 framework. In this guide you will learn to initialize a ROS 2 node, set up publishers and subscribers via a DDS-based system, and construct a simple user interface with SwiftUI to operate core functionalities including initialization, message publishing, and node shutdown. + +## Background and Key Concepts +Before diving into the code, it is useful to understand these key concepts: +- **ROS 2 (Robot Operating System 2):** A set of libraries and tools for building robot applications, which employs nodes, topics, and messaging to facilitate robust communication. +- **DDS (Data Distribution Service):** A middleware protocol used in ROS 2 for real-time, scalable, and high-performance data exchange. It allows configuration of Quality of Service (QoS) parameters such as reliability and latency. +- **Nodes:** The computational executables in ROS 2 that handle processing and communication. +- **Publishers and Subscribers:** Mechanisms for sending (publishing) and receiving (subscribing) messages across nodes. +- **SwiftROS2:** A simulated Swift library that provides interfaces to create ROS 2 nodes, publishers, and subscribers. +- **iOS Development using SwiftUI:** SwiftUI is utilized for building modern, responsive user interfaces on iOS. + +## Step-by-Step Tutorial: Building an iOS App for ROS 2 + +### 1. Project Setup and Dependencies +1. **Clone the Repository:** + Begin by cloning the codebase. Your repository key directories are: + - `/ROS2iOS`: Contains the main source code. + - `/ROS2iOSAppTests`: Holds unit tests. + - `/Preview Content`: Contains sample packages and resources. + +2. **Install Dependencies:** + This project uses Swift Package Manager. Open your Xcode workspace (e.g. `ROS2iOS.xcodeproj`) and ensure the following packages are correctly resolved: + - [swift-ros2](https://github.com/LiaoChiawen/swift-ros2) + - [FastRTPSSwift](https://github.com/kabirkedia/FastRTPSSwift) + - [ros2msg](https://github.com/LiaoChiawen/ros2msg) + + Verify that your `Package.resolved` file lists the correct versions. + +3. **Configure Xcode:** + In Xcode, set the deployment target to iOS 17.0 and ensure proper code signing configurations. + +### 2. Creating the ROS 2 Node +The heart of the app is the ROS 2 node. The `CentralNode` class encapsulates ROS 2 functionalities including initialization and resource management. + +- **Initialization:** + In `ContentView.swift`, the `initialize()` function performs the following: + - Retrieves the device IP using `getWiFiIPv4Address()`. + - Creates a new `CentralNode` instance with a domain ID and IP address. + - Calls asynchronous initialization on the node and associated publishers. + +```swift +// Example snippet from ContentView.swift: +func initialize(){ + Task { + configViewIP = getWiFiIPv4Address() ?? "127.0.0.1" + observableCentralNode.centralNode = CentralNode( + domainID: 0, + ipAddress: configViewIP + ) + + guard let cn = observableCentralNode.centralNode else { + logger.error("Central Node is not ready/available. Cannot initialize.") + return + } + await cn.initialize() + await publisherModel.initialize(centralNode: cn) + } +} +``` + +### 3. Implementing Publishers +Communication between nodes is achieved by creating both publishers and subscribers. + +- **Publishing:** + The `PublisherModel.swift` file demonstrates setting up a publisher. + +```swift +// Excerpt from PublisherModel.swift: +public func sendString() { + guard let publisher = self.publisher else { + logger.error("Publisher is not initialized.") + return + } + + let ros2str = ROS2String() + ros2str.data = "Hello World!" + + let ddsMsg = DDSString(val: ros2str) + + Task { + await publisher.publish(ddsMsg) + logger.info("Published \(ros2str.data)") + } +} +``` + + +### 4. Building the User Interface +The UI is built using SwiftUI and consists of three main buttons: +- **Initialize:** Sets up the ROS 2 node and publishers. +- **Publish Message:** Sends a test message. +- **Destroy Node:** Tears down the node and cleans up. + +```swift +// Example snippet from ContentView.swift: +var body: some View { + VStack(spacing: 20) { + Button("Initialize") { + initialize() + } + .font(.headline) + .frame(width: 140, height: 44) + .padding() + .background(Color.orange) + .foregroundColor(.white) + .cornerRadius(8) + + Button("Publish Message") { + publisherModel.sendString() + } + .font(.headline) + .frame(width: 140, height: 44) + .padding() + .background(Color.blue) + .foregroundColor(.white) + .cornerRadius(8) + + Button("Destroy Node") { + destroyNode() + } + .font(.headline) + .frame(width: 140, height: 44) + .padding() + .background(Color.red) + .foregroundColor(.white) + .cornerRadius(8) + } + .padding() +} +``` + +### 5. Running and Testing the App +- **Build the Project:** + Use Xcode to build the project ensuring that all dependencies are properly integrated. +- **Run on Simulator or Device:** + Launch the app on an iOS device or Simulator. Use the buttons to initialize the ROS 2 node, publish a message, and destroy the node. +- **Testing:** + Verify the functionality by checking Xcode console logs and running unit tests located in `/ROS2iOSAppTests`. + +## Detailed Explanation of Dependencies + +### swift-ros2 +- **Purpose:** + Provides a high-level Swift interface to interact with ROS 2, allowing creation of nodes, publishers, and subscribers. +- **Usage:** + Classes such as `CentralNode` use this package to encapsulate ROS 2 operations and expose easy-to-use methods to initialize nodes and create communication channels. +- **Implementation:** + Utilizes Swift’s async/await for asynchronous operations and error-handling mechanisms for reliable integration with ROS 2 middleware. + +### FastRTPSSwift +- **Purpose:** + Bridges ROS 2 DDS functionalities by leveraging the Fast RTPS (Real-Time Publish-Subscribe) protocol. +- **Usage:** + Manages low-level DDS operations such as registering writers (publishers) and readers (subscribers) and handles QoS settings (e.g., reliability, durability). +- **Implementation:** + Wraps the native C/C++ Fast RTPS libraries into Swift-friendly APIs, abstracting the complexity involved in direct DDS communications. + +### ros2msg +- **Purpose:** + Defines message types and data structures used in ROS 2 communications. +- **Usage:** + Provides message models like `ROS2String` to package data and ensure proper serialization and deserialization using Swift’s Codable protocol. +- **Implementation:** + Structures messages in a way that aligns with ROS 2 standards, facilitating seamless interaction between different nodes and platforms. + +## Understanding the DDS Mechanism +DDS (Data Distribution Service) underpins the efficient and reliable exchange of data between ROS 2 nodes. Key points include: +- **DDS Communication Model:** + Uses a publish/subscribe model where publishers send messages to topics and subscribers receive them based on topic subscriptions. +- **Quality of Service (QoS):** + DDS allows customization of parameters (e.g., reliability, durability, latency) ensuring high-performance communication even in real-time applications. +- **Fast RTPS Integration:** + The FastRTPSSwift package bridges the Fast RTPS library with SwiftROS2, managing: + - **Participant Creation:** The ROS 2 node (CentralNode) acts as a participant joining a DDS domain. + - **Writer and Reader Registration:** Publishers (writers) and subscribers (readers) are registered with the DDS participant. + - **Message Routing:** DDS middleware routes messages efficiently between registered writers and readers, applying QoS policies. +- **Abstraction in SwiftROS2:** + SwiftROS2 simplifies these complex operations into easy-to-use Swift classes and methods, allowing developers to focus on application logic rather than low-level protocol details. + +## Usage Instructions +1. **Clone and Open the Project:** + Clone the repository and open `ROS2iOS.xcodeproj` with Xcode. +2. **Resolve Dependencies:** + Ensure that the Swift packages (swift-ros2, FastRTPSSwift, ros2msg) are downloaded and configured. +3. **Build and Run:** + Build the project and run the app on the desired iOS simulator or device. +4. **Interact with the App:** + - Tap **Initialize** to set up the ROS 2 node. + - Tap **Publish Message** to send a test ROS 2 message. + - Tap **Destroy Node** to gracefully shut down the ROS 2 node. +5. **Review Logs:** + Monitor the Xcode console for log messages confirming successful node initialization, message publishing, and node destruction. + +## Summary +This guide provided a comprehensive walkthrough for building an iOS app integrated with ROS 2: +- Project setup, dependency resolution, and Xcode configuration. +- Initializing a ROS 2 node with `CentralNode` and configuring communication via DDS. +- Implementing publishers and subscribers to exchange messages. +- Designing a user interface with SwiftUI and testing the functionality. +- Detailed insights into the core dependency packages and DDS integration research. + +## See Also +- [ROS 2 Official Documentation](https://docs.ros.org/) +- [Fast RTPS Documentation](https://fast-dds.docs.eprosima.com/en/latest/) +- [Swift Package Manager Documentation](https://swift.org/package-manager/) +- [SwiftUI Tutorials](https://developer.apple.com/tutorials/swiftui) + +## Further Reading +- Advanced DDS configuration and Quality of Service (QoS) settings. +- Detailed tutorials on integrating C/C++ libraries with Swift. +- Comprehensive studies of ROS 2 communication patterns and best practices. + +## References +1. Y. Hu, "swift-ros2 – ROS2-like node that supports subscription and publication of DDS messages in ROS2 message format," GitHub Repository, . +2. ROS Documentation, "Getting Started with ROS 2," available at . +3. Fast RTPS Documentation, available at . +4. Apple Developer Documentation, "SwiftUI," available at .