3 · Put the app on your iPhone

This is the main event. We'll download the app's code, do one short setup step, then press Run in Xcode to install it on your phone. Do the steps in order and you'll be fine: most of it is pointing and clicking.

Almost no typing

We use a free app called GitHub Desktop to download the code (no commands), and Finder to move one file. There is exactly one step that uses the Terminal, and it's spelled out word-for-word when we get there.

Step 1: Download the code

The app comes in two parts that must sit next to each other: faBolus (the app) and TandemKit (a helper library it's built on). The easiest way to download both, and everything they need, is GitHub Desktop, a free app from GitHub.

What's GitHub? What's a repository?

GitHub is a website where code is stored and shared. A repository (or "repo") is just a project folder on GitHub. "Cloning" a repo means downloading a copy to your Mac. GitHub Desktop does this with a button instead of commands.

GitHub Desktop → File → Clone Repository → paste the URL

1. Download GitHub Desktop from desktop.github.com and open it. (You can sign in with a free GitHub account, or skip sign-in; either works for downloading.)
2. In the menu bar: File → Clone Repository… → click the URL tab.
3. Paste this and set the Local Path so it saves into a folder called faBolus inside your Documents, for example ~/Documents/faBolus/TandemKit:

   https://github.com/faBolus-app/TandemKit
   

   Click Clone and wait for it to finish.
4. Do it again for the second project: File → Clone Repository… → URL, and this time paste:

   https://github.com/faBolus-app/faBolus
   

   Save it right next to the first one: ~/Documents/faBolus/faBolus.

Success looks like: inside Documents → faBolus you now have two folders: TandemKit and faBolus, side by side.

Advanced: prefer the Terminal? (optional)

If you'd rather use the command line, this does the same thing (the --recurse-submodules part is what GitHub Desktop does automatically):

mkdir -p ~/Documents/faBolus && cd ~/Documents/faBolus
git clone --recurse-submodules https://github.com/faBolus-app/TandemKit.git
git clone https://github.com/faBolus-app/faBolus.git

Step 2: Add the Garmin helper file (optional)

Only do this step if you want to use a Garmin watch or cycling computer as a remote. If you don't, skip straight to Step 3: the build script notices the Garmin SDK isn't there and builds the app without Garmin. (You can always add Garmin later by doing this step and re-running Step 3.)

To include Garmin, you download one file from Garmin once and drop it into a folder. No commands.

1. Go to the Garmin Connect IQ SDK page and download the Connect IQ Companion (Mobile) SDK for iOS. (You'll make a free Garmin account and accept their license.)
2. In your Downloads, double-click the zip to unzip it. You'll get a folder named something like connectiq-companion-app-sdk-ios-1.8.0.
3. Open Finder → go to your Documents folder → make a new folder called vendor (right-click → New Folder).
4. Drag the unzipped Garmin folder into that vendor folder.

Success looks like: Documents → vendor contains the connectiq-companion-app-sdk-ios-1.8.0 folder. (So Documents now has both a faBolus folder and a vendor folder.)

Skipped this step? That's fine: the build in Step 3 will simply leave Garmin out, and inside the app the Remotes & devices settings section shows a note that it was built without the Garmin SDK.

If you saved things somewhere else

The app looks for the Garmin folder two levels up from itself, in a vendor folder. If you put your projects somewhere other than Documents/faBolus, either move things to match the layout above, or open faBolus/project.yml in TextEdit, find the line under ConnectIQ: that starts with path:, and change it to the full path of your Garmin folder. (Re-do Step 3 afterward.)

Step 3: Create the project (the one Terminal step)

The project is described by a small text file, and a short script (which uses a tiny free tool called XcodeGen) turns it into the file Xcode opens. The script automatically detects whether you added the Garmin SDK in Step 2 and builds with or without Garmin accordingly. This is the only step that uses the Terminal. It's two commands: just copy, paste, and press Return.

What's the Terminal?

The Terminal is a Mac app where you type commands instead of clicking. Find it in Applications → Utilities → Terminal. You don't need to understand the commands; copy each one, paste it in, and press Return. It's safe.

Paste each line, press Return, wait for it to finish before the next

3a. Install XcodeGen (one time). This uses Homebrew, the standard way to install small Mac tools. Paste this line and press Return; if it asks for your Mac password, type it (you won't see the characters, that's normal) and press Return:

brew install xcodegen

\"command not found: brew\": install Homebrew first (one time)

If you've never used Homebrew, install it by pasting this line, pressing Return, and following the prompts, then run brew install xcodegen again:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3b. Create the project. Now point the Terminal at your app folder and run XcodeGen. The easiest way to avoid typing the folder path: type cd and a space, then drag the faBolus folder from Finder into the Terminal window (it fills in the path for you), then press Return:

cd ~/Documents/faBolus/faBolus
./scripts/generate-project.sh

Success looks like: the Terminal prints something like "Created project at …faBolus.xcodeproj", and a new faBolus.xcodeproj file appears in the faBolus folder.

Step 4: Open the project in Xcode

In Finder, open Documents → faBolus → faBolus and double-click faBolus.xcodeproj. Xcode opens.

Give it a minute: a bar near the top says it's "resolving packages" (downloading the helper library). Wait for that to finish.

Step 5: Choose your Team (signing)

"Signing" is Xcode proving the app is yours. This trips people up, so go slowly.

Signing & Capabilities → tick "Automatically manage signing" → pick your Team

1. In the tall left panel, click the blue faBolus icon at the very top.
2. In the list that appears, under TARGETS, click faBolus.
3. Along the top of the middle area, click the Signing & Capabilities tab.
4. Tick the box Automatically manage signing.
5. In the Team dropdown, pick your name (the account from Step 1).

Then do the same Team choice for the other row in the TARGETS list: faBolusWidgets.

\"Identifier is not available\"? Set your own bundle ID (it's one line)

Every App ID and App Group must be unique across all of Apple, so the project's default com.fabolus.app belongs to the faBolus team and can't be reused by your account. Point the build at an ID that's yours: you only change one value:

1. In the faBolus folder, find LocalConfig.xcconfig.example. Make a copy of it in the same folder and rename the copy to LocalConfig.xcconfig (just drop the .example).
2. Open LocalConfig.xcconfig in TextEdit and set two values. Set APP_BUNDLE_ID to a reverse-domain string unique to you, e.g. com.janesmith.fabolus (based on a domain or name you control); the widgets and the shared App Group are all derived from this automatically, so you don't touch them. Set DEVELOPMENT_TEAM to your 10-character Team ID (or leave it blank and pick your Team in Xcode's Signing tab).
3. Save, then re-do Step 3b (./scripts/generate-project.sh) and reopen the project.

LocalConfig.xcconfig stays on your machine (it's gitignored), so your details are never committed or shared. This is a normal one-time setup.

Free account and widgets

Free accounts sometimes can't set up the widgets. If a widget row shows a signing error, you can still install the main app: just build faBolus for now and add widgets later on a paid account.

Step 6: Turn on Developer Mode on your iPhone

Newer iPhones need "Developer Mode" switched on before they'll run an app you built.

Settings → Privacy & Security → Developer Mode → on → Restart

1. On the iPhone, open Settings → Privacy & Security.
2. Scroll to the bottom and tap Developer Mode.
3. Turn the switch on (green), tap Restart, and after it reboots choose Turn On.

Don't see \"Developer Mode\"?

It only appears after your phone has been connected to Xcode at least once. If it's missing, plug your phone into the Mac with Xcode open (Step 7), then come back here.

Step 7: Plug in your iPhone and press Run

Pick your iPhone in the bar at the top, then click the ▶ button

1. Connect your iPhone to the Mac with a cable.
2. The first time, the phone shows Trust This Computer?: tap Trust and enter your passcode.
3. Near the top-middle of Xcode, click the device menu and choose your iPhone (listed under "iOS Device").
4. Click the ▶ (Run) button at the top-left, or press ⌘ + R.

The first build takes a few minutes; let it work. If Xcode says "Device isn't registered," click to register it (your Mac needs to be online); this is a one-time thing.

Step 8: Let your phone trust the app

The first time, iOS won't open an app from a developer it doesn't recognize yet; that developer is you. You just tell it that's OK.

Settings → General → VPN & Device Management → tap your profile → Trust

1. On the iPhone: Settings → General → VPN & Device Management.
2. Under Developer App, tap your Apple account name.
3. Tap Trust, then confirm.

Step 9: Open it and allow Bluetooth

Tap the faBolus icon on your Home Screen. The first time you tap Connect, iOS asks to use Bluetooth: tap Allow. (Without Bluetooth the app can't find your pump.)

🎉 You did it: the app is on your iPhone. Until you pair a pump it shows a waiting screen. Next:

• Pair it with your pump →
• Optional: add a Garmin
• Learn what everything does

The app will stop opening after a while: that's normal

Free account: after 7 days. Paid account: after 1 year. Fixing it takes about a minute; see Keeping the app running.