Get started

Installation

TripLibre is distributed as source code. You build it on a Mac and install it on your own iPhone. No App Store, no TestFlight, no account with us.

Requirements

What	Version / notes
Mac	Any Mac that runs a current Xcode
Xcode	Latest stable, from the App Store. Open it once to accept the licence.
XcodeGen	`brew install xcodegen`. Generates `HHT.xcodeproj` from `project.yml`.
iPhone	iOS 17 or later, with a USB cable
Apple ID	A free one works. A paid Developer Program membership ($99/yr) makes installs last a year.
Python 3 optional	Only for the analysis notebooks/scripts in `analysis/`

First install

Get the code

git clone https://github.com/zyang91/TripLibre.git
cd TripLibre

Sign in to XcodeXcode › Settings › Accounts › + › sign in with your Apple ID.
Set your signing team
DEVELOPMENT_TEAM in project.yml is the maintainer's Team ID. Replace it with yours (Xcode shows it under Accounts). If the bundle ID com.zyang91.hht is already taken on your account, change it to anything unique. Then regenerate the project:
```
make project
```
Prepare the phoneConnect it by cable, tap Trust on "Trust This Computer?", then turn on Settings › Privacy & Security › Developer Mode (the phone restarts).
Build and install
```
make phone
```
When you see ✓ Installed you're done. Alternatively open HHT.xcodeproj, pick your iPhone as the run destination and press ▶.
Trust the developer profileOn the phone: Settings › General › VPN & Device Management › your Apple ID › Trust.
Grant permissionsOpen TripLibre › Allow location & start › allow While Using, then Change to Always Allow when iOS asks. Allow Motion & Fitness too: it noticeably improves mode detection.

✓

Check Settings › TripLibre › Location is Always with Precise Location on. Without "Always", iOS stops the app from recording in the background.

Renewing every 7 days

With a free Apple ID the code signature expires after 7 days. After that the app won't open and won't record. Pick a fixed day each week and reinstall over the existing app:

cd ~/path/to/TripLibre
make phone

Your data lives in the app's container, so reinstalling keeps everything.

Never delete TripLibre from the phone before reinstalling. Deleting the app deletes its database. Always install on top.

Try it in the Simulator

No phone needed. This builds the app, boots a simulator, and launches it with three synthetic Philadelphia days:

make sim                       # defaults to "iPhone 17"
make sim SIM_NAME="iPhone 16"  # or pick another simulator

Simulator builds also have Load demo data in Settings. Demo data never exists in device builds.

Moving to a new iPhone

Restoring a new phone from an iCloud or Finder backup of the old one restores TripLibre's data too, as long as the backup includes the app. To be safe, first export on the old phone (gear › Create export) and copy the folder to your computer. Then repeat steps 4–7 above on the new phone.

Troubleshooting

Symptom	Fix
`No iPhone found`	Check the cable and unlock the phone; tap Trust; make sure Developer Mode is on.
Xcode says "Preparing iPhone…"	Normal on first connection or after an iOS update. Wait a few minutes and rerun.
Signing / provisioning error	Xcode › Settings › Accounts: sign in again (e.g. after a password change), then `make phone`.
Signing error mentioning `group.com.zyang91.hht` or `com.zyang91.hht.widgets`	The widget extension needs the App Groups capability on both targets. Run `make phone` again (it passes `-allowProvisioningUpdates`), or open the project in Xcode once and let Signing & Capabilities register the group under your team.
Widgets say "Open TripLibre"	Open the app once after installing; it writes the summary the widgets read.
"Untrusted Developer"	Settings › General › VPN & Device Management › your Apple ID › Trust.
Installed but not recording	Location must be Always + Precise; Motion & Fitness on; check the 7-day signature hasn't expired.
`xcodegen: command not found`	`xcode-select --install`, then `brew install xcodegen`.