Winter is over, Spring is here, and along with the heat, rains and insects, ModemManager arrives with support for modems using the new MBIM protocol, available through the new cdc-mbim kernel driver in Linux >= 3.8 and a preliminary version of libmbim.
The current implementation provides:
- PIN unlock/change/enable/disable capabilities
- 3GPP modem support (GSM, HSPA, LTE…)
- Basic connectivity support
It doesn’t provide yet most of the side-features available in other modems (e.g. SMS messaging, location…), but it is a good start. If you don’t want to use MBIM just yet, check Bjørn’s list of issues and alternatives.
Where do I get it?
The ‘libmbim’ library can be found in the following Lanedo-maintained gitorious repository:
We also released a tarball in libqmi’s release place:
If you’re part of the freedesktop.org sitewranglers group, please check the still open libmbim project request.
The support is already in ModemManager git master, and will be enabled if libmbim is found during configure. You can also explicitly request to use MBIM support with the new –with-mbim configure switch.
Special thanks go to Lanedo for sponsoring the initial libmbim development, Bjørn Mork for his suggestions and tests with multiple MBIM-capable modems, and Huawei for sending me a E367 with MBIM firmware.
Linux kernel 3.8 comes with a new ‘cdc-mbim‘ driver… let’s see what all this is about…
What is MBIM?
This new USB networking subclass defines two separate new features:
- A new MBIM USB device model, providing multiple IP connections over a single USB interface, and without the need of 802.3 frames (as was the case with ECM and NCM)
- A new MBIM control protocol to talk to modem devices
MBIM message types
The protocol defines different message types with different formats.
Some of them are used to establish the channel of communication with the modem:
- Open Message (Host->Modem): Initialization request.
- Open Done Message (Host<-Modem): Initialization response.
- Close Message (Host->Modem): Close request.
- Close Done Message (Host<-Modem): Close response.
Some of the messages are used to report errors in the protocol; which may be sent either from the host or from the modem:
- Host Error Message (Host->Modem): Host-reported error.
- Modem Error Message (Host<-Modem): Modem-reported error.
And finally, some messages provide access to the different CIDs (Command IDs) defined in each Service.
- Command Message (Host->Modem): Request of a given command.
- Command Done Message (Host<-Modem): Response to a given command.
- Indication Message (Host<-Modem): Unsolicited messages sent by the modem.
These last three messages support protocol-defined fragmentation. If the sender of the message finds out that the message is longer than the maximum control transfer size defined when the communication channel was opened (with an Open Message), it will be able to split it into sorted chunks and send them one by one over the wire. Each of these fragments specify the total amount of fragments expected, as well as the order in the sequence. The receiver of the fragments will therefore need to wait for all fragments to arrive – which should arrive in order – before processing the message.
The protocol defines a basic set of different Services:
- Basic Connect: Which provides the support for basic IP connectivity
- SMS: SMS messaging
- USSD: Unstructured Supplementary Service Data
- Phonebook: Handling contacts and such
- STK: SIM toolkit
- Device Service Stream
Only the Basic Connect one is mandatory in every MBIM device; others are optional. Vendors or even Network Operators can also extend the functionality of the device with other services; for example to support other protocols embedded within MBIM (e.g. QMI or AT within MBIM); or just to provide specific new features.
For each service, MBIM defines a set of Commands (CIDs); and each command can then be divided into 3 actions:
- “Set“: An user-requested action to change the modem state or configuration
- “Query“: An user-requested action to query the modem state or configuration
- “Notification“: An unsolicited report of the modem state or configuration
Not every action is supported by every command. For example, the “Device Caps” command in the “Basic Connect” service only supports the “Query” action, while the “Radio State” command of the same service supports all “Set“, “Query” and “Notification“.
But how does this match with the message types defined before?
- Host-created “Set” and “Query” requests are sent using “Command Messages“.
- Modem-created “Set” and “Query” responses are sent using “Command Done Messages“.
- Modem-created “Notifications” are sent using “Indication Messages“.
MBIM basic types
The protocol not only defines which action is supported in each command; it also defines the contents of the request, response and indication messages. The contents of each message are composed of collections of basic types defined by the protocol:
- Unsigned 32bit integers: Even for the most simple values (e.g. booleans), little-endian 32 bit unsigned integers are used.
- Strings: UTF-16LE encoded strings are always used.
- UUIDs: The protocol defines a special 16-byte-long UUID type, e.g. to define Service IDs
- Arrays: Collection of N values of a given basic type.
- Structs: Sequence of other basic types, given in a specific order.
As you can see, there is not much effort (none, actually) into making the protocol efficient in terms of overhead introduced; more than half of the bytes in each message will very likely end up being NUL bytes. Also, it is assured that each field within a message is aligned in a 32bit boundary, which makes it easier to read independent fields directly from the binary stream.
How does this compare to QMI?
There are quite some differences between this protocol and QMI. To name a few:
- Less basic types in MBIM, specially regarding signed/unsigned integers. QMI defines many more integer types, of different sizes and with different sign.
- Basic strings are given in ASCII in QMI
- Struct types are re-used in MBIM, as opposed to QMI, where each TLV would define the struct contents as it needed.
- There is no ‘client allocation’ needed in MBIM, i.e. the process opening the MBIM port doesn’t need to allocate clients for the different services.
- Fragmentation is built-in in the MBIM protocol; QMI required special TLVs and logic to handle messages that may be longer than the standard message size (e.g. when transferring the PRL list).
- Binary representation of the message is completely different. In QMI you would have a list of TLVs, one after the other. In MBIM, the contents of the message are split into two different sections: one which contains the fixed-size values and one for the variable-size values. For example, a string in MBIM is defined by two values in the fixed-size region (offset and size), while the real string data is within the variable-size section.
The ‘libmbim‘ library is an attempt to write a protocol support library, as previously done with ‘libqmi‘.
The current codebase, GLib/GObject/GIO based, is pretty similar to what libqmi provided, with a ‘MbimDevice‘ GObject to handle the communication through the
/dev/cdc-wdm port, as well as ‘MbimMessage‘ types to handle the creation of commands. Given that there is no need for client allocations in MBIM, there is no ‘MbimClient‘ object needed. Also, given that the contents of each message are pre-defined, it wasn’t considered the need of input and output ‘bundles’ to handle collections of TLVs, as done in libqmi.
Fragmentation of incoming/outgoing messages is handled internally by the ‘MbimDevice‘, which is a nice thing to have, as it simplifies the usage of the API. The user just creates a message, as long as it needs it to be, and the ‘MbimDevice‘ will take care of splitting it into fragments. When receiving a message, the user will also receive already the full message, once all fragments have been combined internally.
The messages and the services are defined in a JSON dictionary, and as with libqmi, all the message handling code is auto-generated from there. The capabilities of the mbim-codegen are still not in pair with those in qmi-codegen yet, though. The generator doesn’t support e.g. “Set” requests with parameters, or “Indication” messages. As previously said, this currently is a proof-of-concept, someday we’ll support all those properly.
The project comes with a command line utility (mbimcli), which allows (will allow) running “Get” or “Set” commands directly from the shell. There aren’t many supported commands yet, so I cannot show many more examples than this one:
$ sudo mbimcli \
-d /dev/cdc-wdm1 \
[/dev/cdc-wdm1] Subscriber ready status retrieved:
Ready state: 'device-locked'
Subscriber ID: 'unknown'
SIM ICCID: '984310311520086950F1'
Ready info: 'unknown'
Telephone numbers: ''
--verbose will show you the raw binary message contents!
Where do I get it?
The ‘libmbim’ library and the ‘mbimcli’ utility are managed in FreeDesktop.org:
Help! Contribute! Sponsor!
If you want to help, or sponsor further development in libmbim, mbimcli or the ModemManager integration, just let me know!
[UPDATE: Included freedesktop.org project link]
The changes in the new wavecom plugin with respect to the generic GSM plugin are:
- AT+CPIN? replies are not ended with OK. A custom regex match was added to support CPIN? replies without OK (also had to hack the generic MM code to handle plugin-provided regular expressions).
- Disabled default power-up comand, AT+CFUN=1. This command does a full software reset in the device, including the USB stack, so the connection is closed. No additional command seems to be needed, as the modem wakes up by default in CFUN=1 (full functionality) mode. Anyway, an additional check was added during initialization so that this mode is ensured.
- Enabled RTS/CTS instead of XOFF/XON flow control.
- Implemented access technology retrieval using AT+WGPRS=9,2 to query network capabilities
- Ensure the modem uses the highest possible mobile class. These modems can be configured to use different mobile classes. For each kind of modem, the best mobile class is the highest one available, in the following order:
- Class A (3G only mode)
- Class B (PS or CS, GPRS/EDGE or GSM)
- Class CG (PS only, GPRS/EDGE)
- Class CC (CS only, GSM)
- Implemented setting and getting allowed mode, for both 2G and 3G based modems (using AT+WWSM command in the 3G case).
- Implemented setting and getting frequency bands for 2G modems (with AT+WMBS) and 3G modems (with AT+WUBS).
Still, the plugin could be improved even more. For example, there is no secondary port handling in the current plugin implementation, which means that signal strength value will not be updated while the modem is in connected state. This kind of modems support setting up virtual ports by multiplexing the serial channel (CMUX), but ModemManager doesn’t handle this yet.
If anyone has one of this Wavecom/SierraWireless modems at home, please test it with latest ModemManager and report any errors found.