Neo 1973 and Neo FreeRunner gsm modem

From Openmoko

Revision as of 06:57, 17 October 2007 by Kousue (Talk | contribs)

Jump to: navigation, search

This page is about the Neo1973 GTA01 (and GTA02) GSM Modem, based on the Ti Calypso chipset.

Contents

AT command interface

Sending Commands

To send commands to the GSM modem, you may use cu -l /dev/ttySAC0 or use gsmd and libgsmd-tool for a less direct method.

If you connect directly (via cu) you must `chown uucp.uucp /dev/ttySAC0` first since cu is picky about permissions, and if you're on a GTA01 you cannot be ssh'd in, since the USB port which the ethernet runs over uses the first serial port and that will conflict.

libgsmd-tool is less functional than the direct raw connection to the modem.

Note: If you use cu -l /dev/ttySAC0 to enter commands, type "~." to quit

Standard AT commands

The GSM modem follows GSM TS07.05, 07.07 and 07.10 very closely.

FIXME: Describe how those documents can be obtained.

TI proprietary AT commands

there are a few of them, but none of them are really required for regular operation of the device. Due to NDA issues, OpenMoko cannot provide a reference documentation to those commands. Using the standards-compliant AT+CLAC, you will notice that the non-standard commands also show up in the command listing.

You will also notice that those non-standard commands are prefixed with AT% rather than AT+ for the standards-compliant commands.

Thus, we welcome our user and developer community to play with those commands and document them here. Since we never have released any NDA documentation to our community, there is no legal issue.

AT%VER

Prints the firmware components version.

The modem's response looks like this on an un-updated phase-0 GTA01Bv4 phone:

%VER: aci sean non_clearcase   15:11:24 17/04/07
%VER: cc a086 ** NONE **      10:16:39 28/03/07
%VER: dl a086 ** NONE **      10:17:34 28/03/07
%VER: mm a086 ** NONE **      10:23:09 28/03/07
%VER: rr a086 ** NONE **      10:25:37 28/03/07
%VER: sim a086 ** NONE **      10:26:45 28/03/07
%VER: sms a086 ** NONE **      10:27:21 28/03/07
%VER: ss a086 ** NONE **      10:28:52 28/03/07
%VER: alr a086 ** NONE **      10:15:48 28/03/07
%VER: l2r a086 ** NONE **      10:21:37 28/03/07
%VER: ra a086 ** NONE **      10:25:01 28/03/07
%VER: rlp a086 ** NONE **      10:25:12 28/03/07
%VER: fad a086 ** NONE **      10:18:09 28/03/07
%VER: t30 a086 ** NONE **      10:29:01 28/03/07

The second column lists firmware component names (e.g. aci = AT Command Interface). The third column is the user name of the engineer who last modified given component. The rightmost column is probably the last time someone worked on it (Please note that the name 'sean' here is not Sean Moss-Pultz :) while a086 is an anonymous TI engineer's nick, meaning that the component has not been modified at FIC).

GSM Modem OpenMoko commands

The Ti calypso GSM Modem firmware has been extended by OpenMoko specific AT commands. This page documents those commands.

AT@POFF

Powers off the GSM Modem. No parameters/options.

AT@ST

configure the sidetone level for voice calls generated inside the GSM Modem. This should normally be off, since the sidetone in GTA01/GTA02 is generated inside the the wolfson audio codec.

AT@ST?
+ST: -5
OK
AT@ST=?
@ST: (-26,-23,-20,-17,-14,-11,-8,-5,-2,1)
OK
AT@ST="-26"
OK

-26 means turn off the sidetone totally.

AT@AUL

audio table load.

AT@AUL="0"
OK
AT@AUL=?
@AUL:(0)

This audio table is a collection of audio parameters for GSM calibrated by hardware engineers,

Mode of microphone
Gain of microphone
FM PGA gain setting
Bias setting for microphone
FIR coefficients
ANR parameters
Level of side tone
AEC parameters
Echo suppressor
Mode of speaker
Gain of speaker
Extra gain for AUDIO_SPEAKER_HANDSET and AUDIO_SPEAKER_HANDFREE modes
Enable/Disable filter
Enable/Disable high-pass filter
FIR coefficients
IIR uplink/downlink coefficients
Limiter parameters
Level of speaker
Mode of speaker
State of speaker
Sampling frequency
Level of volume 
AGC parameters
DRC parameters

The audio table will be stored in the flash file system within GSM modem, you can load it through this command.

For now, we only provide one configuration, that is "0".

If AT@AUL="0" responds ERROR, it means there's no audio table existing and the GSM firmware will use default values.

Wakeup of CPU from GSM Modem

Problem description

For power management reasons, it is absolutely neccessary that only the minimal required parts of the device are powered at any given time. If you carry your Neo in your pocket, then all it should do is stay online with the GSM network, and notify you in case there's an incoming call/sms (like other phones).

During that time, the Neo1973 Application Processor (s3c24xx) is suspended, i.e. not powered at all. The SDRAM is in self-refresh mode.

In this suspend mode (which Samsung calls by the funny name of POWER_OFF), the processor is not able to receive any data from the GSM Modem. Nor is it able to detect incoming characters and wake up the CPU. The only wake up sources are a certain set of external interrupts (EINT).

Thus, the GSM Modem GPIO line IO1 was connected with the Samsung EINT1, and the GSM Modem firmware contains some special logic to generate an interrupt (and thus wake-up event) to the CPU.

Logic for problem solution

Preconditions

  1. The default state of GSM Modem output IO1 is logical LOW.

Anytime the modem has pending data on the MODEM-UART channel, it

  1. checks if CTS_MODEM permits sending of data
    1. if CTS_MODEM permits sending of UART data, go to '4.2'
  2. [implicit: CTS_MODEM does not permit sending of UART data]
    1. set IO1 line to logical HIGH level
    2. buffer modem data [until buffer is full, after which data gets discarded]
  3. wait until CTS_MODEM permits sending of UART data
  4. as soon as CTS_MODEM permits sending of UART data,
    1. set IO1 back to logical LOW level
    2. start sending of UART data
  5. once all data is transmitted, return to idle state. When next data item is to be transmitted, start again from '1'

Software implementation

NOTE: This is the plan, it has not been fully implemented yet


  1. a firmware post may-16-2007 needs to be present in the gsm modem. This is true for all phones bought during phase 1 in the online shop. However, I currently don't really know what firmware version was present in the GTA01Bv4 that we sent to phase 0.
  2. the suspend code probably still needs to correctly configure the RTS/CTS lines (i.e. put them in GPIO mode, and set them to their desired "don't send any more characters" level)

So in this case, any data from the GSM modem will wake up the cpu for processing of that data. The GSM modem has some internal buffer (I don't know how big right now) that should be sufficient for buffering the data until the CPU is alive.

This also means that gsmd will eventually have to re-program the GSM modem to make sure only relevant unsolicited response codes are sent during suspend. You usually don't want a signal level change to cause a CPU wake up, only things like incoming message / call.

Upgrading the modem's firmware is technically possible but no proper software is currently legally available to users outside OpenMoko staff.

Personal tools

This page is about the Neo1973 GTA01 (and GTA02) GSM Modem, based on the Ti Calypso chipset.

AT command interface

Sending Commands

To send commands to the GSM modem, you may use cu -l /dev/ttySAC0 or use gsmd and libgsmd-tool for a less direct method.

If you connect directly (via cu) you must `chown uucp.uucp /dev/ttySAC0` first since cu is picky about permissions, and if you're on a GTA01 you cannot be ssh'd in, since the USB port which the ethernet runs over uses the first serial port and that will conflict.

libgsmd-tool is less functional than the direct raw connection to the modem.

Note: If you use cu -l /dev/ttySAC0 to enter commands, type "~." to quit

Standard AT commands

The GSM modem follows GSM TS07.05, 07.07 and 07.10 very closely.

FIXME: Describe how those documents can be obtained.

TI proprietary AT commands

there are a few of them, but none of them are really required for regular operation of the device. Due to NDA issues, OpenMoko cannot provide a reference documentation to those commands. Using the standards-compliant AT+CLAC, you will notice that the non-standard commands also show up in the command listing.

You will also notice that those non-standard commands are prefixed with AT% rather than AT+ for the standards-compliant commands.

Thus, we welcome our user and developer community to play with those commands and document them here. Since we never have released any NDA documentation to our community, there is no legal issue.

AT%VER

Prints the firmware components version.

The modem's response looks like this on an un-updated phase-0 GTA01Bv4 phone:

%VER: aci sean non_clearcase   15:11:24 17/04/07
%VER: cc a086 ** NONE **      10:16:39 28/03/07
%VER: dl a086 ** NONE **      10:17:34 28/03/07
%VER: mm a086 ** NONE **      10:23:09 28/03/07
%VER: rr a086 ** NONE **      10:25:37 28/03/07
%VER: sim a086 ** NONE **      10:26:45 28/03/07
%VER: sms a086 ** NONE **      10:27:21 28/03/07
%VER: ss a086 ** NONE **      10:28:52 28/03/07
%VER: alr a086 ** NONE **      10:15:48 28/03/07
%VER: l2r a086 ** NONE **      10:21:37 28/03/07
%VER: ra a086 ** NONE **      10:25:01 28/03/07
%VER: rlp a086 ** NONE **      10:25:12 28/03/07
%VER: fad a086 ** NONE **      10:18:09 28/03/07
%VER: t30 a086 ** NONE **      10:29:01 28/03/07

The second column lists firmware component names (e.g. aci = AT Command Interface). The third column is the user name of the engineer who last modified given component. The rightmost column is probably the last time someone worked on it (Please note that the name 'sean' here is not Sean Moss-Pultz :) while a086 is an anonymous TI engineer's nick, meaning that the component has not been modified at FIC).

GSM Modem OpenMoko commands

The Ti calypso GSM Modem firmware has been extended by OpenMoko specific AT commands. This page documents those commands.

AT@POFF

Powers off the GSM Modem. No parameters/options.

AT@ST

configure the sidetone level for voice calls generated inside the GSM Modem. This should normally be off, since the sidetone in GTA01/GTA02 is generated inside the the wolfson audio codec.

AT@ST?
+ST: -5
OK
AT@ST=?
@ST: (-26,-23,-20,-17,-14,-11,-8,-5,-2,1)
OK
AT@ST="-26"
OK

-26 means turn off the sidetone totally.

AT@AUL

audio table load.

AT@AUL="0"
OK
AT@AUL=?
@AUL:(0)

This audio table is a collection of audio parameters for GSM calibrated by hardware engineers,

Mode of microphone
Gain of microphone
FM PGA gain setting
Bias setting for microphone
FIR coefficients
ANR parameters
Level of side tone
AEC parameters
Echo suppressor
Mode of speaker
Gain of speaker
Extra gain for AUDIO_SPEAKER_HANDSET and AUDIO_SPEAKER_HANDFREE modes
Enable/Disable filter
Enable/Disable high-pass filter
FIR coefficients
IIR uplink/downlink coefficients
Limiter parameters
Level of speaker
Mode of speaker
State of speaker
Sampling frequency
Level of volume 
AGC parameters
DRC parameters

The audio table will be stored in the flash file system within GSM modem, you can load it through this command.

For now, we only provide one configuration, that is "0".

If AT@AUL="0" responds ERROR, it means there's no audio table existing and the GSM firmware will use default values.

Wakeup of CPU from GSM Modem

Problem description

For power management reasons, it is absolutely neccessary that only the minimal required parts of the device are powered at any given time. If you carry your Neo in your pocket, then all it should do is stay online with the GSM network, and notify you in case there's an incoming call/sms (like other phones).

During that time, the Neo1973 Application Processor (s3c24xx) is suspended, i.e. not powered at all. The SDRAM is in self-refresh mode.

In this suspend mode (which Samsung calls by the funny name of POWER_OFF), the processor is not able to receive any data from the GSM Modem. Nor is it able to detect incoming characters and wake up the CPU. The only wake up sources are a certain set of external interrupts (EINT).

Thus, the GSM Modem GPIO line IO1 was connected with the Samsung EINT1, and the GSM Modem firmware contains some special logic to generate an interrupt (and thus wake-up event) to the CPU.

Logic for problem solution

Preconditions

  1. The default state of GSM Modem output IO1 is logical LOW.

Anytime the modem has pending data on the MODEM-UART channel, it

  1. checks if CTS_MODEM permits sending of data
    1. if CTS_MODEM permits sending of UART data, go to '4.2'
  2. [implicit: CTS_MODEM does not permit sending of UART data]
    1. set IO1 line to logical HIGH level
    2. buffer modem data [until buffer is full, after which data gets discarded]
  3. wait until CTS_MODEM permits sending of UART data
  4. as soon as CTS_MODEM permits sending of UART data,
    1. set IO1 back to logical LOW level
    2. start sending of UART data
  5. once all data is transmitted, return to idle state. When next data item is to be transmitted, start again from '1'

Software implementation

NOTE: This is the plan, it has not been fully implemented yet


  1. a firmware post may-16-2007 needs to be present in the gsm modem. This is true for all phones bought during phase 1 in the online shop. However, I currently don't really know what firmware version was present in the GTA01Bv4 that we sent to phase 0.
  2. the suspend code probably still needs to correctly configure the RTS/CTS lines (i.e. put them in GPIO mode, and set them to their desired "don't send any more characters" level)

So in this case, any data from the GSM modem will wake up the cpu for processing of that data. The GSM modem has some internal buffer (I don't know how big right now) that should be sufficient for buffering the data until the CPU is alive.

This also means that gsmd will eventually have to re-program the GSM modem to make sure only relevant unsolicited response codes are sent during suspend. You usually don't want a signal level change to cause a CPU wake up, only things like incoming message / call.

Upgrading the modem's firmware is technically possible but no proper software is currently legally available to users outside OpenMoko staff.