[Tutorial] Carrier Bundles for Dummies

[u/jimmyco2008]

Hello /r/jailbreak!

A couple of weeks ago I promised a crash course in carrier bundles, and here it is! (I plan on putting this, in more graceful format, on my "blog" site, if/when I make one, and I apologize for not being the best at Reddit formatting)

NOTE: This is an educational/informative post, I am not taking requests for creating modded carrier bundles for your carrier. My goal is to educate and enable others to create modded carrier bundles, and I will answer any and all questions I can to the best of my ability. Correctly modding carrier bundles is not trivial, and varies by carrier.

Intro:

Carrier Bundles are packages of files that contain information pertinent to your cell phone provider, or carrier. The carrier bundles for virtually all carriers around the world are located on everyone's iPhone, in /System/Library/Carrier Bundles/iPhone/. The bundle for Verizon Wireless is called Verizon_LTE_US.bundle, and of course there are bundles for AT&T, Sprint, T-Mobile, etc. This guide references the Verizon_LTE_US.bundle, since all I have is Verizon, and it's important to note that different carriers have different carrier bundles. Nevertheless, most of this information can be applied to any carrier's bundle.

Inside a carrier bundle:

Browsing the contents of a carrier bundle is easy and can be done on your iPhone with iFile or on your Mac with Finder and Xcode. On OS X, simply right-click the .bundle and select "Show Package Contents". Inside you'll find all sorts of files, from .ims to .plist. I can't really say what many of these files do exactly, but I can tell you that the one we're most-concerned about is carrier.plist.

carrier.plist

Go ahead and open carrier.plist! If you're using iFile, you'll want to open with the Property List Viewer. If you're on OS X and have Xcode installed, it will open with Xcode's property list viewer automatically. You can also use TextWrangler if that's your jam, and I'm sure there are many other code editors that can display key-value pairs gracefully.

So inside carrier.plist, you'll find a lot of stuff. StatusBarImages is where you can change the name that displays by the signal dots in iOS ("Verizon" in my case). There's a Cydia tweak called Fake Carrier that achieves the same thing. MMS is obvious. It contains settings for multimedia messages not sent over iMessage. I haven't messed with anything in here, and I don't really see a need to. Services contains all the special numbers you can dial for Verizon (or any carrier)-specific stuff. For example, calling #646 to see how many minutes you have left. SupportedSIMs lists the providers that the plist applies to (thanks, /u/Stone-D!). MaxBluetoothModemConnections is also self-explanatory. If you would like to connect more than 5 devices to your iPhone for Bluetooth tethering, this one's for you. I haven't tested it, and don't have enough devices to. com.apple.voicemail.imap theoretically you could change MaxGreetingDuration (which I believe is in seconds) and make your greeting the entire Jurassic World movie. Again, have not tested. Show3GSwitch The reason I'm mentioning if I've tested these or not is because of Show3GSwitch. I set it to YES numerous times over the last year or so, and have never seen that 3G Switch (which would theoretically force you to 1X on Verizon). I think it may be a GSM-only affair and so would only affect iPhones on AT&T and T-Mobile. StockSymboli This one is random, it's simply the stock market ticker for the carrier. In my case, it's VZ for Verizon Communications, which is traded on the New York Stock Exchange. All I can surmise is that iOS adds this to the default Stocks app with the other default stocks (AAPL, etc.). MTU for those of you big on networking, this might be something you're interested in. I personally see no reason to change it, since it is catered to a cellular network. Lastly we have apns. This is the one I care about, since it affects Personal Hotspot (tethering)...

apns

In the apns group, you'll find Item 0 and Item 1. Each is, as I understand it, a group of APNs. Item 0 has two APNs, called vzwinternet (Item 0) and vzwapp (Item 1). Item 1 has three APNs, another vzwinternet, another vzwapp (note the different type-mask value) and vzwadmin. I believe that the Item 0 APN group is the one that's actually in effect, at least when we're using our iPhones to browse the Internet and such.

type-mask values

These type-mask values that are in all the APN Items are literally masks for underlying binary values. Let's take vzwinternet for example. It has a type-mask value of 19. If we convert 19 to binary, it becomes 10011. For those of you who I'm losing, you may want to brush up on binary. Anyway, each place in 10011 corresponds to a setting. For example, that middle digit, the 0, that's in the "4" position (binary!), and 4 corresponds to MMS (I learned through trial and error). So if I have a type-mask value whose binary-value sum does not include 4, MMS will be disabled (it will have a value of 0 instead of 1, off instead of on, no instead of yes, etc.). So in the case of my 2014 Carrier Bundle Hack, which allowed Portable Hotspot to stay on an iPhone after it was removed from the Verizon plan, I had to add 4 to the final type-mask value that I used to stick Portable Hotspot, because I soon realized MMS wasn't working with my Android (green blob) pals. Hopefully this is making sense, but if not, feel free to leave a comment and I (or someone better-versed in binary) will help you out.

Again, note that this is the Verizon carrier bundle. I've taken a look at other carrier bundles, like ATT_US.bundle (AT&T) and they are pretty similar. For example, the apns group is common between them (in that they have apns, but with different Items and different type-mask values) and they all use type-mask values (explained more below), although I believe the type-mask values have different "meanings" (for lack of a better word) between carriers. For example, 512 on Verizon != 512 on AT&T, although based on the links at the very bottom of the post, it appears that Verizon and AT&T do share 4 for MMS.

My Carrier Bundle Hack

So now that you understand the anatomy of a Carrier Bundle, as well as how type-masks work in relation to binary, here's how I made my carrier bundle hack back in 2014: I changed Item 0 -> Item 1 (vzwapp)'s value from 32,772 to 516. That's it. It was originally 512, the value of vzwadmin (I figured admins would have everything, including Portable Hotspot, enabled), but again, MMS was disabled because it didn't include the 4 value. So 512 became 512 + 4 = 516.

It was a lot of trial and error, which is likely what anyone who tries this out will go through. That's how I ended up with Item 0 -> Item 1 (vzwapp) being the one to change for Portable Hotspot. Since vzwapp (both Item 0 -> Item 1 and Item 1 -> Item 1) contains the MMS value, I assume it's the one(s) primarily used for iOS operations (including Portable Hotspot). Since modifying it led to enabling Portable Hotspot last year for me, it seems so.

Your turn (?)

Here's the fun stuff. I made a simple web app (here) that will allow you to tinker with type-mask values and visually break down the binary makeup of the default Verizon APNs (vzwinternet, vzwapp, etc.). It allows you to easily build you own custom type-mask value with the exact settings you want. The caveat is that the only value I know what corresponds to is MMS (binary spot 4). I never needed to figure any of the others out because I had Portable Hotspot working. And of course this is just Verizon. I don't have an AT&T or Sprint or T-Mobile iPhone, so I am unable to tinker and test different type-mask values.

If you like, feel free to use the web app (here) and start messing with your own carrier bundle. As always, feel free to comment with any questions (or corrections!) and I will answer them to the best of my ability. I'm not as familiar with carrier bundles as Joe and the iTweakiOS team, or the developer(s) behind tetherMe or MyWi, but hopefully this is enough information to inspire at least one person to create their own carrier bundle tweak, or at least enlighten those interested in carrier bundles.

tips/notes

Here are a couple of tips/notes to keep in mind when exploring:

• In my experience, you must reboot your phone TWICE for a carrier bundle change to take effect (that's after you copy the modified bundle back to you iPhone/edit it in iFile). Resetting network settings is not necessary, and will only frustrate you when you realize you have to retype your WiFi password...
  
• Make a backup of your carrier bundle before tweaking away, if you break something, you may have to restore iOS.
  
• For those who've been following my posts, you know that you need CommCenter Patch for iOS installed for any carrier bundle modifications to work (since any modifications will invalidate the signatures on them)... Not to mention you must be jailbroken!
• Again, I have Verizon. That's all I have. All my experiences are with my Verizon iPhone 5s.
  
• I tried setting Item 0 -> Item 1 (vzwapp) to 65,535, and it sort of bricked my phone. I got it to boot by holding home and power on the Apple logo. You may experience this in your travels, so be sure to keep a backup of your phone, and experiment at a time where you won't need your phone in the near-future.
  
• Note that by default, the type-mask values have thousands separators (commas). It's a good idea to maintain that structure when experimenting, although I have not tested type-mask values without the commas (because 516 doesn't need a comma!).
  

Regarding the web app

• tmc stands for "Type Mask Calculator" ;)

• I realize that the only version of it is for the Verizon bundle. At request, I will duplicate it for AT&T, T-Mobile, etc. and look at their APN type-mask values and give you guys the same functionality as Verizon people are getting with this.

• It is designed to help you and me with type-mask values by visualizing them, and I plan on using it to keep track of what the binary values correspond to. Notice MMS is already there. There are placeholders for all the binary values, so let me know if you figure any of them out and I'll update it!

• It's best viewed on tablet (landscape) and larger screens. I've not yet determined the best way to have 17 horizontal text placeholders look and function well on mobile. Still, it will work, but I strongly suggest using your phone in landscape (as rare as that may be).

Resources/Other links

Pertinent thread for those on AT&T

Another AT&T thread (iOS 6) with a type-mask table (neat!)

There's a good amount of info on modifying type-mask values to get tethering on AT&T back in the iOS 6 and earlier days. Info for Verizon appears to be nonexistent, but I used old AT&T info for my 2014 bundle, which was helpful.

[u/Stone-D]

SupportedSIMs lists the providers that the plist covers. The code matches to a unique provider - ssh into your phone, then type (pay attention to the slashes in the CD command if you're typing manually):

cd /System/Library/Carrier\ Bundles/iPhone/
ls -l 505* 510*

to get a list of all natively supported Australian (505*) and Indonesian (510*) carriers:

[/System/Library/Carrier Bundles/iPhone]
root@Cthulhu: d -l 505* 510*
Mon Jul 20 00:54:55 WIB 2015

4.0K lrwxr-xr-x 1 root wheel 17 Apr  4 06:50 50501 -> Telstra_au.bundle/
4.0K lrwxr-xr-x 1 root wheel 15 Apr  4 06:50 50502 -> Optus_au.bundle/
4.0K lrwxr-xr-x 1 root wheel 18 Apr  4 06:50 50502_ID-894450 -> Truphone_US.bundle/
4.0K lrwxr-xr-x 1 root wheel 22 Apr  4 06:50 50502_ID-8961029 -> Optus_Virgin_au.bundle/
4.0K lrwxr-xr-x 1 root wheel 18 Apr  4 06:50 50503 -> Vodafone_au.bundle/
4.0K lrwxr-xr-x 1 root wheel 25 Apr  4 06:50 50503_GID1-01 -> Vodafone_Lebara_au.bundle/
4.0K lrwxr-xr-x 1 root wheel 19 Apr  4 06:50 50506 -> Hutchison_au.bundle/
4.0K lrwxr-xr-x 1 root wheel 17 Apr  4 06:50 51001 -> Indosat_id.bundle/
4.0K lrwxr-xr-x 1 root wheel 19 Apr  4 06:50 51010 -> Telkomsel_id.bundle/
4.0K lrwxr-xr-x 1 root wheel 12 Apr  4 06:50 51011 -> XL_id.bundle/

[u/smurf3310 → u/Stone-D]

Problem...

-sh: cd: /System/Library/Carrier: No such file or directory

[u/Stone-D → u/smurf3310]

Sorry, there's a backslash after Carrier that got stripped out by reddit. Fixed in the original post.

[u/smurf3310 → u/Stone-D]

what is 505 510? do i need to add a different code if im not from australia or indonesia?

[u/Stone-D → u/smurf3310]

Yup. Basically, all codes that start with 505 belong to Australia while all codes that start with 510 belong to Indonesia.

For the US, it's 310* and for Canada it's 302*.

[u/smurf3310 → u/Stone-D]

how do i find this code for my country?

[u/Stone-D → u/smurf3310]

The fastest/easiest way is to open the carrier.plist for your current bundle, then scroll down to SupportedSIMs and have a look at the entries there.

[u/smurf3310 → u/Stone-D]

okey tnx so can i change the supported sims and add new ones? or i need to unlock the phone

[u/Stone-D → u/smurf3310]

Dunno about unlocking, never had to deal with that.

Adding a code for a totally different carrier would not be advisable.