Blog Archives

Changing modes and capabilities in ModemManager

I don’t really recall when my first interaction with ModemManager was, I just remember saying “wait, this modem just works?”. But I do remember one day when I spent a couple of hours trying to understand why my modem wouldn’t switch to 2G-only mode even if I explicitly selected it in the network-manager-applet. Truth be told, I didn’t dig much in the issue that day; I barely knew what ModemManager was, or how it would interface with NetworkManager, or how to really debug it. And here I am possibly 4 years after that day, trying to get that same issue fixed.


ModemManager has always allowed to specify which ‘network type‘ to use; or, rather than network type, ‘allowed and preferred‘ modes as we name them. It basically is a way to tell your modem that you want to use one technology preferred over another (e.g. allow 2G and 3G, but prefer 3G), or even tell the modem to use only one technology type (e.g. 3G only). Even modern phones allow you to turn off 3G support and only use 2G, in order to save battery. The main problem with ModemManager’s way of handling this issue was that there was a predefined set of combinations to select (as exposed by the applet), and that not all combinations are supported by all modems. Even worse, ModemManager may not know how to use them, or the modem itself may not support mode switching at all (which was actually what was happening with my modem 4 years ago). Therefore, the UI would just try to show all the options and hope for the best when launching the mobile broadband connection. And there it comes the next issue; allowing to select mode preferences during the connection setup just makes the modem restart the whole radio stack, and the connection attempt may end up timing out, as the whole network registration process needs to be done from scratch before connecting…

Allowed and Preferred modes

In the new ModemManager interfaces, each Modem object will expose a “SupportedModes” property listing all the mode combinations (allowed + preferred) the modem actually supports. Graphical user interfaces will therefore be able to provide mode switching options listing only those combinations that will work. If a modem doesn’t support mode switching, no such list should be provided, and the user will not get confused. At any time, the Modem object will also expose a “CurrentModes” property, showing which is the currently selected combination of allowed and preferred modes. And the “SetCurrentModes()” method will allow to switch current modes, accepting as input only combinations which are given in “SupportedModes” (or the special allowed=ANY and preferred=NONE).

Also, changing current modes directly when calling Simple.Connect() will no longer be possible. This means that NetworkManager will never request allowed mode switching during a connection attempt (and hence no radio stack reloading in the modem causing timeouts). The logical place to put allowed mode switching is therefore a system configuration application like the GNOME Control Center or similar, which should allow mode switching at any time, not only just during a connection attempt. A good side effect of this change is that the NetworkManager connection settings now contain only connection-related configuration, which in the case of 3GPP devices can be linked to the SIM in use, leaving out all modem-specific configuration.


There was a time when modems were either 3GPP (GSM/GPRS/UMTS/HSPA…) or 3GPP2 (CDMA/EV-DO…). Nowadays, modems with multiple capabilities are pretty common, specially since LTE is around (LTE, even if 3GPP, is also 3GPP2′s blessed 4G technology, instead of the superhero named one which is forgotten by everyone already). ModemManager will now allow to change capabilities in addition to allowed and preferred modes; so a user with a modem which can work both in 3GPP and 3GPP2 networks will be able to switch from one to the other directly from the user interface. Of course, if the modem supports this (currently only QMI-based modems).

The new “SupportedCapabilities” property will expose all capability combinations supported by the modem, while “CurrentCapabilities” will expose which are the current ones being used at any given time. For example, a modem with “gsm-umts”, “cdma-evdo” and “lte” capabilities may support configuring only “cdma-evdo”, or “gsm-umts”+”lte”. Changing current capabilities is now possible through the “SetCurrentCapabilities()” method, which has a logic very similar to that of the “SetCurrentModes()” method. If a modem supports multiple capability combinations as exposed by “SupportedCapabilities”, this method will allow changing between them. The main difference with mode changing is that we will force a device power-cycle when this change is done, so the modem will disappear and reappear again with the new capabilities.

Capabilities and allowed/preferred modes have a lot in common, so much that there is a single interface in QMI based modems to change them. Therefore, when a modem allows changing capabilities, the list of allowed/preferred mode combinations may (and very likely will) be different depending on the current capabilities in the modem. For example, LTE-enabled QMI-powered modems will not be able to switch allowed/preferred modes when they have “lte” among the current capabilities, but they will be able if the capabilities are changed to only “gsm-umts”. This is not a big deal, as mode preference (e.g. 3G preferred) is not applicable when the modem does LTE (there is no way of saying allow 2G, 3G and 4G but prefer 3G).


ModemManager also allows to specify which frequency bands to use in the modem, but unlike with modes and capabilities, the “SupportedBands” property is not a list of all possible band combinations supported. Instead, it’s just a bitmask with all supported bands, without specifying whether an actual combination is going to work in “SetCurrentBands()” or not. Listing combinations instead of just the bitmask would be truly too much… But anyway, changing frequency bands is not a feature that a normal user should play with, so just don’t do it. I actually bricked a Pantech UML290 myself playing with this…


All these updates, plus some other ones, are available in the ‘aleksander/api-breaks‘ branch in the ModemManager git repository, which should hit git master very soon, likely this week. These ones should be the last API breaks done before releasing the new ModemManager, and will be kept stable after that.

ModemManager-powered location indicator for gnome-shell

TL;DR: Show location information retrieved directly from ModemManager in a gnome-shell indicator.

Location Indicator in gnome-shell

I’ve been wanting to try to write a gnome-shell extension from some time, and I ended up finding enough free time during the past weeks. So I ended up writing a gnome-shell extension which would show information about your current location as provided by your modem. Note that this information is not coming from GeoClue; the new ModemManager1 interface is not integrated yet there.

ModemManager exposes these types of information in the Location interface:

  • 3GPP location, which is given as a set of 4 parameters, and specifies which is the current network cell which is giving mobile coverage to the modem:
    • MCC/MNC: Identifies the ‘mobile country code’ and the ‘mobile network code’; i.e. country and operator.
    • LAC and Cell ID: Identifies the ‘location area code’ and ‘cell id’ pair.

    Once all these items are known, a query to an open database of cell IDs can give us the exact location of the tower giving us coverage, and therefore a good approximation of where we are located.

  • GPS location, given if the modem has a built-in GPS. Currently Option/HSO modems are supported, as well as QMI-powered modems with the ‘PDS’ service implemented.
  • CDMA Base Station location, given as Latitude/Longitude coordinates, and available in QMI-powered modems prepared for CDMA networks. As with the 3GPP one, this location information specifies where the station giving coverage to your modem is located, which is a good approximation of where you are located.

Beware! You’ll need ModemManager >= 0.7 (i.e. git master) in order for this extension to work.

You can download and install the extension in the following link:

The sources are kept in a git repository in

If you find the extension itself mostly useless, you may still want to take a look at the source code to see yet another example of how to talk to DBus interfaces from within gnome-shell, including the use of the new standard ObjectManager interface with a Gio.DBusObjectManagerClient.

Integrating the new ModemManager in GNOME3

(C) allenran917@ Flickr – CC by-nc-nd

It was something like September 2011, shortly after the last Desktop Summit in Berlin, when I started the work improving ModemManager with the new DBus API, GDBus-based DBus support, port-type-agnostic implementations, dynamic DBus interfaces, built-in org.freedesktop.DBus.ObjectManager interface support, built-in org.freedesktop.DBus.Properties.PropertiesChanged signal support, the new libmm-glib client library, the new mmcli command line tool… Took me around half a year to port most of the core stuff, and some more months to port all the plugins we had. And then, suddenly, git master wasn’t that unfinished thing any more, and we were even implementing lots of new features like GPS support in the Location interface, improved SMS Messaging capabilities, ability to switch Firmware on supported modems, and last but definitely not least, support for new QMI-enabled modems through the just officially released libqmi

And when I thought it was all done already, I woke up from my dream and realized that not even me was really using the new ModemManager as it wasn’t integrated in the desktop… not even in NetworkManager. So there I was again, with a whole new set of things to fix…

NetworkManager integration

There is already a set of patches available to include integration of the new ModemManager interface in NetworkManager; pending for review in the NM mailing list. This is the second iteration already, after having some of the patches from the first iteration already merged in git master.

This integration is probably the most complex one in the list, as it really has to deal with quite different DBus interfaces, but the overall look of it seems to be quite good from my point of view. With the patches on, NetworkManager exposes a new –with-modem-manager-1 configure switch which defaults to ‘auto’ (compile the MM1 support if libmm-glib found). Note that both the old and new ModemManager would be supported in this case, to easier fallback to the old version if the user experiences problems with the new ModemManager.

All in all, the required changes to NetworkManager are quite well defined, implemented mainly as a new ‘NMModemBroadband’ object and some additional bits to monitor added/removed modems through the org.freedesktop.DBus.ObjectManager interface.

gnome-shell integration

A proper integration in my desktop of choice (gnome-shell based GNOME 3) required to integrate the new interface in the Network indicator of the shell. As in every good day, I first had to deal with several issues I found, but I ended up submitting a patch that properly talks to the new ModemManager1 interface when needed. As with NetworkManager, this patch would support both the old and the new interfaces at the same time.

Not that this was a big change, anyway. The Network indicator only uses the ModemManager interface to grab Operator Name, MCCMNC and/or SID, and signal strength. Something that could even be included directly in the NMDevice exposed by NetworkManager actually…

Right now the only big issue pending here is to properly unlock the modem when it gets enabled, something that I still need to check how to do it or where to do it.

Truth be told, hacking the shell has ended up being quite nice, even with my total lack of knowledge in JavaScript. My only suggestion here would be: get a new enough distribution with a recent enough GNOME3 (e.g. the unreleased Fedora 18) and jhbuild buildone from there. I think I’ve never seen a clean jhbuild from scratch succeed… maybe it’s just bad luck.

And then came the applet…

network-manager-applet integration

Why the hell would Bluetooth DUN not work with my implementation, I was thinking, until I found that even if GNOME3 doesn’t rely on nm-applet, it still uses some of its functionality through libnm-gtk/libnma, like the code to decide which kind of modem we’re dealing with and launch the appropriate mobile connection wizard. Ended up also submitting patches to include the missing functionality in network-manager-applet.

For those not using GNOME3 and gnome-shell; note that I didn’t implement the support for the new ModemManager1 interface in the nm-applet itself; I just did the bluetooth-guess-my-modem-type bits required in libnma. If I feel in the mood I may even try to implement the proper support in the applet, but I wouldn’t mind some help with this… patches welcome! Same goes for other desktops relying on NetworkManager (KDE, xfce…); I wouldn’t mind to update those myself as well, but I truly don’t have that much free time.

gnome-control-center integration

Ok, so gnome-shell integration is more or less ready now; we should be finished, right? Well, not just yet. gnome-control-center also talks to ModemManager, in this case to get Operator Name and Equipment Identifier, which btw were not getting properly loaded and updated. Once that fixed, I finally got a new patch to have the control center talk to the new interface.

Fedora 18 packages

I bet you won’t go one by one to all the patches I linked before and apply them in your custom compiled NetworkManager, gnome-shell, network-manager-applet and gnome-control-center… but for all those brave Fedora 18 users, you can try with the 64-bit packages that I built for me, all available here:

If you want to rebuild these packages yourself, you’ll find the source tarballs here and the packaging repositories here. The packaging is really awful – I suck at it – so you’ll probably need to install the RPMs with –force :-) Note that the git repo for packaging has several git submodules, one for each item packaged, so remember to “git submodule init” and “git submodule update“.

We done yet?

Are these all the patches needed to have the best ModemManager experience in GNOME3? No! The list of pending tasks for this purpose grows a bit every day…


Get every new post delivered to your Inbox.

Join 36 other followers