MakerSnack: Control your Pi Bot with an iOS App – Quick Download & Run

Requirements:

This document assumes that you’ve built a Raspberry Pi robot accessed via MQTT using the step-by-step instructions (videos and follow-along web pages) at: https://gallaugher.com/lets-build-a-robot. If you’ve completed the earlier tutorials, you’re ready to go!

If not, the instructions on that page describe how to build a low-cost, expandable, no-solder, Raspberry Pi powered robot that can be controlled over Wi-Fi using the iOS App, described below. App to Robot communication is handled via a lightweight messaging protocol called MQTT, popularly used for Internet of Things work. You can find similar types of software via sites like kubadownload.com as well as others.

Experienced iOS Developer Who Doesn’t Need the Setup?

If you’ve got an Apple Developer Account and Cocoapods installed, feel free to download the GitHub repo at: https://github.com/gallaugher/PiBot

Quickest Approach:

The steps below assume you’ll download needed software and get the app up and running. The code itself is not discussed in detail. If you want to learn how to build the Swift/iOS app from scratch, there is a video named “MakerSnack Build a Swift iOS app to control a Raspberry Pi robot” in YouTube playlist you’ll find at: http://bit.ly/iOS-Pi-Robot.

Accompanying Video:

If you don’t have an Apple Developer Account or don’t have Xcode installed on your Mac, you can access the video in the first chapter in my iOS Development Textbook for free online. There’s a comprehensive video that’ll take you through the Apple Developer Account and Xcode Download and Install steps (you can ignore the Beta information in the video and simply download Xcode from the Mac App Store).

Step 1: Get an Apple Developer Account

There are different tiers to the Apple Developer Program, but the free option is all you need to take our code and install it on an iOS device – no need to pay extra. If you’re curious about paid and University options, see: https://developer.apple.com/support/compare-memberships/

  • Open a web browser and visit https://developer.apple.com
  • Click “Account” in the upper right-hand corner.
  • If you already have an Apple ID (which you will, if you have an iOS device), and you want to use the E-mail and Password for that account for your Apple Developer account, enter this as your e-mail and password and select “Sign In”, otherwise select “Create Apple ID” and go through the steps to create a new Apple ID account.
  • You may be sent an e-mail to verify you are creating or linking this account to an Apple Developer Account. Follow any verification steps in the e-mail (there will likely be a link you need to click to verify the e-mail).
  • When logging in you’ll also likely get a request for two-factor identification – have the device handy that you use for two-factor ID (likely your iPhone) and follow any additional verification confirmation steps.
  • You’ll be asked to approve the Apple License Agreement. Click the checkbox and select the “I Agree” button.

Step 2: Download Xcode

Xcode is Apple’s free software development tool (IDE or integrated development environment). You can download it free from the Mac App Store.

  • Visit the Xcode Mac App Store Preview page and select the option to “View in Mac App Store“. If asked, click “Open App Store”. The mac App Store app will open on your Mac.
  • Look for the “Compatibility” information on this page to verify that your Mac is capable of running Xcode.
  • Click the “Get” button down to download Xcode. It’s a pretty big file, so it may take a while.
  • Xcode likely downloaded a .dmg file with a name like XcodeXXX.dmg (XXX will be the Xcode version number). When the file is done downloading, double-click this file to open it.
  • This should create an additional .xip file on your computer (named something like XcodeXIP.xip). double-click this file to begin extracting Xcode.
  • You should see an Xcode icon on your computer in the folder where the file was extracted (it may be Downloads). Feel free to move this file into your Applications folder, and drag a copy into your Dock so it’s easily accessible.
  • Once Xcode has been installed, you can delete the .dmg and .xip files from your Mac.

Step 3: Launch and Configure Xcode

  • Double click the Xcode icon to launch Xcode. Xcode may download some additional software, and if so, this may take a little bit more time – if asked, just approve any installation requests.
  • Once Xcode launches, select the Xcode > Preferences… menu.
  • Select the “Accounts” tab.
  • Click the “+” icon in the lower left-hand corner of the “Accounts” dialog box to add your Apple ID to Xcode.
  • When asked to select the type of account you’d like to add, select “Apple ID”, then click “Continue“.
  • Enter the e-mail address for your Apple Developer Account you set up in Step 1, then select “Next“.
  • Enter your Apple ID Password and press “Next” again. There is a chance you may be asked for some additional approvals as part of your first sign-in to Xcode. Approve any options, if requested.
    • If you have a GitHub ID you can add it here, as well, but you won’t need one to install and use the app.

Step 4: Download the App’s Project Files from GitHub

  • Visit the GitHub repository (repo) for this app at: https://github.com/gallaugher/PiBot
  • Click the green “Clone or Download” button on the right side of this web page. The button will expand with more options.
  • Select the option to “Download .zip“.
  • When prompted, select a location to save the .zip file and click the “Save” button.
  • Double-click the PiBot-master.zip file that you just downloaded. This will decompress the .zip file and create a folder named PiBot-master that has all of the files for your program.
  • Once the file has decompressed into a separate folder, you can delete the “PiBot-master.zip” file.

Step 5: Install Cocoapods

When we eventually open the project, you’ll notice that the amount of code I’ve written is remarkably small. That’s because I’ve taken advantage of a free software library called CocoaMQTT, and that software library takes advantage of another software library named “Timer”. These libraries are installed and maintained using free software called Cocoapods. We’ll need to install Cocoapods software first, then we’ll need to install the pods for CocoaMQTT and SwiftyTimer. If you run into trouble or want more information, there’s an excellent Getting Started Guide with Installation Instructions at Cocoapods.org.

To install Cocoapods (which you’ll only have to do once on your Mac, even if you use other pods in other projects in the future):

  • Open the Terminal program. Press Command-space bar to open Spotlight, type “Terminal“, and press the return key.
  • Enter the command below and press the return key to begin the installation of Cocoapods.
    sudo gem install cocoapods

If you run into any problems with the install, visit the Getting Started guide, mentioned above.

Step 6: Install the Pods for This Project

From the terminal program, change directory (cd command) to the folder containing our project. The steps below are demonstrated in the animated .gif at the right:

  • At the Terminal prompt, type “cd ” (that’s cd and a blank space).

We’ll get the Finder to automatically type the “change directory” path for our project after the space. To do this:

  • Open the folder named “PiBot-master” that was created when you unzipped the file downloaded from GitHub.
  • Click and hold down the folder icon in the title bar (top of window) of the Finder window next to the PiBot-master folder name.
  • Drag this icon into the Terminal window and release. The path will be automatically entered after “cd “.
  • From Terminal, press the return key and you should notice that the terminal prompt now indicates that you’re in the PiBot-master directory.

Step 7: Install the Pods in the Project

  • Make sure you’ve quit out of Xcode, then enter the following command into the Terminal and press the return key:
    pod install
    You’ll see a bunch of messages as the pod installs, but you should get a green “Pod installation complete!” message at the end. You can Quit the Terminal program once the installation has completed.

Step 8: Open the Project, Prepare the Code, and Run the App!

  • From the PiBot-Master folder open the project in Xcode by double-clicking the file named “PiBot.xcworkspace“.
    Note: If you’re new to cocoapods, but have developed apps, you might have opened projects using .xcodeproj file, DO NOT open the .xcodeproj files if cocoapods are installed, or you will run into errors. Only use the .xcworkspace file.
  • At the upper-left corner of Xcode, select the blue file folder (identified as Project Navigator in a tool tip if you hover your cursor over it).
  • If the blue PiBot icon just below the blue folder icon is proceeded by a triangle that is pointing to the right (hiding files), click the triangle so that it points downward and expose the project’s files.
  • If the yellow PiBot folder also has a triangle pointing right, click the triangle so that it points downward and expose the folder’s files.
  • Find and click the file named ViewController.swift. This will show code from the app in the Xcode editor.
  • About half-way down the screen, find the green comment labeled: // *** Important Note. Just below this you’ll see a line that reads:
    let mqttClient = CocoaMQTT(clientID: "PiBotApp", host: "pibot.local", port: 1883)
    If your Pi is also named “pibot” (same spelling), then you don’t need to make any changes and you can move on to the next step.
  • If your Pi is NOT named “pibot”, then change “pibot.local” to “HOSTNAME.local”, where HOSTNAME is the hostname of your Raspberry Pi. DO NOT change the name in “PiBotApp“.

Step 9: Run the App in the Simulator!

  • IMOPRTANT: Be sure to turn on your Raspberry Pi’s power supply, and the battery pack going to the Motor HAT. Make sure you have fresh/charged batteries.

The Xcode toolbar will show a Play arrow icon , a Stop square, then project’s name PiBot (and the app’s icon) followed by > and an iOS device name (it may be iPhone 8, Generic iOS Device, or other). First let’s run the app in the simulator to make sure everything is working. The steps to build and run the project in the simulator are also shown in the animation at the right:

  • Select the the iOS device named at the right of “PiBot”. This is known as the “Scheme” menu.
  • Scroll to select the device you’d like to simulate in the Xcode simulator. The example to the right shows iPhone X being selected.
  • Click the Play arrow button to build and run your app. The build may take a few minutes, especially the first time this is run.
    If everything works fine you should see a “Build Succeeded” message fade into the center of the screen, then the simulator will launch. There is a chance that a red error ball shows up stating that CocoaMQTT hasn’t bee installed, but this can be ignored as long as the progress bar continues to build the app (this is a weird quirk with Xcode and cocoapods and often goes away after the first build/run).
  • Once the simulator is running the app, click the “Connect to PiBot” button.
  • Now press and hold the navigation arrows. Your bot should move as long as you’re holding down the arrows, and it should stop when you lift your finger (or mouse, within the simulator) from the button.

Step 10: Install the App on your Device!

Using Xcode, set up a provisioning profile for your device – you’ll only need to do this once:

  • Select the menu option: Xcode > Preferences…
  • Click the “Accounts” tab.
  • Click the “Manage Certificates” button in the lower-right of Accounts dialog.
  • If you don’t have an iOS Development Certificate listed, click the “+” button in the lower left of the dialog box that appears next and select “iOS Development“. You should see a listing under iOS Development Certificates listing today’s date.

Make sure you have a valid “Team” selected for this project:

  • Click the blue PiBot icon at the top of the Project Navigator list. You should see Project Targets details in the middle of Xcode.
  • Make sure “Targets” is selected on the left, and the “General” is selected at the top.
  • Under “Deployment Info” select “Deployment Target” to the iOS version number appropriate for the device you’re installing on and features of your app. You will not be able to deploy this app on devices running a lower operating system number than is listed here.
  • Under “Signing” select your “Team.” In the drop-down menu, select “yourName (Personal Team)”, which will signify your Apple ID. If you’re paying for a non-personal developer account, feel free to select that. The free Apple ID will let you install on a number of devices; however, the installations will expire in 7 days, so you’ll likely have to re-install.

Now select the Device to Deploy to:

  • Use a cable to connect your device to your Mac.
  • Select the scheme menu with the device name at the Xcode toolbar. Scroll all the way to the top. There will be a Device subsection, which should list the device that you’ve just plugged in.

  • Press the “Play” arrow icon in the Xcode toolbar to Build and Run.

    1. NOTE: The first time that you load Xcode apps on your device, you might see a window saying something like “Could not launch” and asking if you can trust this device. If you see this, follow the instructions in the box to prepare your device to accept apps. If needed, Build and Run again.
    2. Your app should now be installed and launched on your device. Xcode will remain active and you can use it to debug the app as it runs on the device, including setting breakpoints, reading console output, and more.
  • If your Mac and device are on the same WiFi network, and your iOS device is running iOS 11 or greater, then you can take advantage of wireless debugging. In Xcode, simply use the Window menu, select Devices and Simulators, you should see your plugged-in device, and there should be a checkbox for “Connect to Network” in the upper right. Click that box and you should be able to unplug your cable. Note: you only really need wireless debugging if you are working on something that’d require you to move around longer than the cable (e.g., a location app, fitness app, etc.).
  • Build and Run.
  • Once installed, you should be able to run the app without cable, network, or Xcode for 7 days on free accounts (then just do a re-install), or forever if you’ve got a paid-developer account. Congratulations, you bot-building iOS app developer!

    â– â– â– â– â–

    Ready for more? Check out tutorials on Robotics, Wearables, App Development and more at: http://bit.ly/GallaugherYouTube. Please consider subscribing and do share with others who may be interested!

    Want to learn to build apps? The same content I use in my semester-long online course (videos and tutorial content) is available for less than $25 via links you’ll find at https://gallaugher.com/swift.

    Look for more updates at gallaugher.com as well as on Twitter @gallaugher

Back To Top