Hire Me!

ogsmd and its modems

written by Mickey on 2008-12-03

Recently, I have been working on adding more support for various types of modems to ogsmd. "Why's that?", I hear you say, "isn't that already done since long?". Yes and no. There are two dimensions where modems might differ:

Both dimensions come with their own set of problems:

Exposing an AT interface

As you might know, there are basically three different means for exporting an AT interface:

  1. A single line without mulitplexing support,
  2. Multiple premultiplexed lines,
  3. A single line with multiplexing mode.

Before we go into the details, some notes about what I mean with multiplexing mode. The 3GPP standard 07.10 defines a binary multiplexing protocol that exposes a number of virtual channels over which you can talk AT as defined in v250, 05.05, 07.07, etc. The concrete number of channels modem-specific -- it usually varies between three and four.

Let's come back to the three ways of exporting an AT interface now:

A single line without multiplexing

A single line without multiplexing support is the easiest, however it is also the most limiting way. The reason for that being that quite a lot of commands might take a long time to complete -- during that time the single line is blocked and you can not perform additional commands nor receive the so-called unsolicited responses from the network. These messages usually inform you about changes in the environmental GSM network condition, but also occur as notifications for incoming SMS or calls. In that scenario you will not be able to handle GPRS and voice calls at the same time.

Multiple premultiplexed lines

In the most simple form, a modem might support two discrete lines, e.g. one for all AT commands, the other one for GPRS connections. Some modems support three, four or even many more lines, however this usually comes with some strings attached. Multiple premultiplex lines usually are non-homogenous, that is you can not perform every AT command on any line, rather there is a line for SIM access, a line for voice calls, a line for network commands, etc.

A single line with multiplexing mode

In contrast to the premultiplxed line, these kinds of modems support an optional multiplexing mode over the single line transport (see explanation above). While this means that you need support code for the demultiplexing, a usually nice side effect is that the multiplexed lines are homogenous, e.g. the application (ogsmd in that case) can chose how to operate the lines. If you have more than two lines, you might want to dedicate one to unsolicited responses only, so you can react to network events even while dialling out. You might want to reserve one line for GPRS data connections and -- if you have a modem that does not buffer SIM access -- you might want to dedicate one line for the (potentially slow) SIM card retrieval commands.

The AT commandset

The second dimension of differences is the set of supported AT commands. The GSM AT command set is relatively "old" (in terms of computer science) and has its root in the (even older) command set (e.g. v25ter / v.250) designed for analogue terminal adapters. The GSM standards such as 3GPP 05.05, 07.07 define commands that serve as addition to the ones defined in v.250.

Unfortunately, the lion's share of these commands has been tagged "optional" -- also some of the GSM functionality is severely underspecified. This can lead to trouble such as follows:

Briefly, some examples:

TI Calypso

The TI Calypso is a 2.5G (no EDGE) modem from Texas Instruments, as found in the Openmoko mobile phones Neo1973 and the FreeRunner. It has a fairly comprehensive AT implementation. All the commands support the query parameter and there are few standard violations. TI invented about 50 extracommands, of which ogsmd is using about 10 -- mainly for extended call progress information and network status.

Freescale Neptune

The Freescale Neptune is a 2.5G (EDGE) custom modem as appearing in the widely successful Motorola EZX Linux mobile phone family. The AT implementation is a nightmare, there are dozens of standard violations, implicit behaviour all over the place, and as if that wasn't enough, it has about 100 completely undocumented custom commands. And yes, 90% of the commands do NOT support the query format...

Cinterion mc75i

The Cinterion (previously SIEMENS) modem is one of the latest in a huge family of industry modems, deployed in millions of stationary and mobile devices. It will appear in the next-generation Openmoko device (codename GTA03). Its AT implementation is conforming to all standards and has been canonically enhanced to fill out the missing spots in the specifications. The documentation is a dream.

Bringing it all together

Supporting an additional modem in ogsmd can take from a day to some weeks, depending on the discussed two dimensions "way of exposing the interface" and "commandset implementation".

By the way, one particular ugly area is the call handling. As I have mentioned, the GSM standard only supports little information here (due to the compatibility with analogue modems), so most vendors have added their own unsolicited commands to take care of that. For those who have not though, we have a generic abstraction in ogsmd that uses timings and additional status requests (+CCLC to the rescue) to overcome this limitation. However, imagine a singleline modem with no vendor supported extra commands blocking during an ATD command... welcome to the dark.

So all this has motivated you to add a new modem abstraction to ogsmd? Excellent, be my guest! It now boils down to first identifying the way how to talk to it and then either chose to derive from the generic 'singleline' or the 'muxed4line' modem class. If the latter, you can adjust the number of individual channels created based on the capabilities of your modem. If your AT interface is premultiplexed, there's nothing else to do but match the channels to the right device nodes. If your AT interface supports a multiplexing mode, use the gsm0710muxd inbetween ogsmd and your modem (take a look at the TI Calypso implementation which is doing that as well).

Second, you need to find out where the standard AT implementation does not work with your modem or is not giving you all the information your modem could provide (think special commands). For such cases, in your new modem class you want to override specific mediators and add new unsolicited handlers. I'll briefly explain what these two are:

Custom Mediators

In ogsmd, a mediator is a small class that encapsulates a dbus command such as:

ogsmd's abstract mediator module (ogsmd/modems/abstract/mediator.py) contains mediators that are using standardized AT commands to perform their job. If your modem does not support these commands -- or has better commands to do that -- you should override said mediator (ogsmd/modems/mediator.py) to issue different commands in the 'trigger' method. Then, collect the results in 'responseFromChannel', and forward it to dbus -- that's all.

Custom Unsolicited Handlers

Unsolicited handlers specify what happens on incoming messages that originate from the GSM network, e.g. a +CRING that informs you about an incoming call. The handler then can perform additional queries or just trigger a dbus signal.

If your modem has additional (non-standard) unsolicited commands (or violates the 3GPP standards, which happens often enough) that you want to process, write a handler function in the unsolicited module (ogsmd/modems/unsolicited.py) for each of these.

Epilogue

I hope you have an idea what it means to add a new modem support class to ogsmd now. If you have more questions or want to help, drop a mail to smartphones-userland@linuxtogo.org.

I hope you enjoyed this months' tech talk ;-)