Neo 1973 and Neo FreeRunner gsm modem

From Openmoko

(Difference between revisions)
Jump to: navigation, search
(Serving Cell Information (2,1): Info on Timing Advance parameter)
m (Serving Cell GPRS Information (2,2): Link)
Line 204: Line 204:
 
|6  || rac || Routing Area Code ||
 
|6  || rac || Routing Area Code ||
 
|-
 
|-
|7  || tav || Timing Advance ||
+
|7  || tav || Timing Advance || See [[GTA01_gsm_modem#Serving_Cell_Information_.282.2C1.29|distance calculation note]]
 
|-
 
|-
 
|8  || dsc || Downlink Signal Counter ||
 
|8  || dsc || Downlink Signal Counter ||

Revision as of 12:47, 20 April 2008

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.

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.

3gpp.org has information about 3G and GSM specifications

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.

Note that the syntax and the interpretation of the output of the commands listed here are only educated guesses and should not be relied on. Part of the proprietary command set has identical or similar usage as on other modems in the market, some of which have fully opened specifications and information about these commands can be taken from their datasheets (some known similar modems with open specs: BenQ M22A and M23A, Enfora Enabler-G II / III and SPT 1834).

AT%VER

Prints the firmware component versions.

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

For a GTA01Bv4 phase 1 phone, produced start of september:

%VER: aci sean non_clearcase   12:32:56 24/08/07
%VER: cc a086 ** NONE **      14:07:10 08/06/07
%VER: dl a086 ** NONE **      14:07:46 08/06/07
%VER: mm a086 ** NONE **      14:11:52 08/06/07
%VER: rr a086 ** NONE **      14:13:01 08/06/07
%VER: sim a086 ** NONE **      14:13:54 08/06/07
%VER: sms a086 ** NONE **      14:14:20 08/06/07
%VER: ss a086 ** NONE **      14:15:52 08/06/07
%VER: alr a086 ** NONE **      14:06:38 08/06/07
%VER: l2r a086 ** NONE **      14:10:36 08/06/07
%VER: ra a086 ** NONE **      14:12:32 08/06/07
%VER: rlp a086 ** NONE **      14:12:40 08/06/07
%VER: fad a086 ** NONE **      14:08:06 08/06/07

For a GTA01Bv3 phase 0 phone:

%VER: aci sean non_clearcase   10:46:06 29/08/06
%VER: cc a086 non_clearcase   14:53:59 28/08/06
%VER: dl a086 non_clearcase   14:54:40 28/08/06
%VER: mm a086 non_clearcase   14:59:25 28/08/06
%VER: rr a086 non_clearcase   15:00:11 28/08/06
%VER: sim a086 non_clearcase   15:00:57 28/08/06
%VER: sms a086 non_clearcase   15:01:23 28/08/06
%VER: ss a086 non_clearcase   15:02:22 28/08/06
%VER: alr a086 non_clearcase   14:53:19 28/08/06
%VER: l2r a086 non_clearcase   14:58:02 28/08/06
%VER: ra a086 non_clearcase   14:59:50 28/08/06
%VER: rlp a086 non_clearcase   14:59:56 28/08/06
%VER: fad a086 non_clearcase   14:55:04 28/08/06
%VER: t30 a086 non_clearcase   15:02:27 28/08/06

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).

AT%A

Print values from an ADC.

This command is not listed in AT+CLAC output but it is triggered by any input that starts with AT%A except AT%ALS (Alternative Line Service) and AT%ATR, which are other proprietary AT commands. So for example AT%ABCD,HELLO will also run this commands. On my Neo modem it prints a line containing nine values of the form ADC <number> = <value>:

AT%A
EXT: I
ADC 0 = e19, ADC 1 = 0, ADC 2 = d, ADC 3 = 6ea, ADC 4 = a25, ADC 5 = 9fc, ADC 6 = 96d, ADC 7 = 0, ADC 8 = 6

It would seem there's an ADC (analog-to-digital converter) module in the modem with nine input lines connected to it and the values on these lines are reported by this command in hexadecimal format. The values change over time. Inputs 1 and 7 always show zero on my modem, input 1 value changes slightly (+/- 20), while values on inputs 3, 4, 5, 6 and 8 change seemingly randomly in the range 0x000 - 0xfff (it would seem the chip is 12-bit).

AT%NRG

The AT%NRG (Network registration and service selection) is an expansion of the AT+COPS command. It allows specifying the service state of the registration, in addition to AT+COPS functionality. It doesn't however allow listing all present operators (use AT+COPS for this).

AT%EM

Execution of Engineering Mode commands. Allows viewing the information accessible to the modem but not available through standard GSM AT commands set such as detailed information on the current Serving Cell (the one we're registered with), its neighbouring cells, the GPRS/EDGE availability and SIM card data.

Citing Enfora Inc. Application Note EDG0108TN01: The purpose of Engineering Mode (EM) is to provide means to observe the behavior of the mobile station and the settings of the network as counterpart and therefore defines a lot of possibilities to analyze the network. The EM can be used for observation of a defined data set during functional test and field test.

Warning: The display of certain parameters is dependent on the wireless network sending the correct information in the System Information Packets. There is no guaranty that the information is always forwarded from the network. At times data may not be present to display in the Engineering Mode responses.

Syntax:

AT%EM=<mode>,<command>

Allowed <mode> values:

  • 2 - AT command mode
  • 3 - PCO mode

I only describe the AT mode commands here. Commands are in range 1 to 13:

AT%EM=2,1  Serving Cell Information
AT%EM=2,2  Serving Cell GPRS Information
AT%EM=2,3  Neighbour Cell Information
AT%EM=2,4  Location and Paging Parameters
AT%EM=2,5  PLMN Parameters
AT%EM=2,6  Ciphering, Hopping, DTX Parameters
AT%EM=2,7  Power Parameters
AT%EM=2,8  Identity Parameters
AT%EM=2,9  Firmware components versions
AT%EM=2,10 GMM Information
AT%EM=2,11 GRLC Information
AT%EM=2,12 AMR Configuration Information
AT%EM=2,13 PDP Information
Serving Cell Information (2,1)

Response format:

%EM: <afrcn>,<c1>,<c2>,<rxlev>,<bsic>,<cell_id>,<dsc>,<txlev>,<tn>,<rlt>,<tav>,<rxlev_f>,<rxlev_s>,<rxqual_f>,<rxqual_s>,<lac>,<cba>,<cbq>,<cell_type_ind>,<vocoder>
Parameter no. Name Meaning Remarks
1 arfcn Current Channel Number See below for frequency calculation
2 c1 Path Loss Criterion C1
3 c2 Cell-reselection Criterion C2
4 rxlev Received Field Strength (rxlev/2)+2 gives the AT+CSQ response value
5 bsic Base Station ID Code
6 cell_id Cell Indentifier
7 dsc Downlink Signaling Counter current counter value
8 txlev Transmit Power Level
9 tn Timeslot Number
10 rlt Radio Link Timeout Counter
11 tav Timing Advance See below for distance calculation
12 rxlev_f Received Field Strength full
13 rxlev_s Received Field Strength sub
14 rxqual_f Received Quality full
15 rxqual_s Received Quality sub
16 lac Location Area Code
17 cba Cell Bar Access
18 cbq Cell Bar Qualifier
19 Cell_type_ind Cell Type Indicator NA/GSM/GPRS
20 vocoder Vocoder Sig/speech/efr/amr/14.4/9.6/4.8/2.4

According to http://www.qrctech.com/freq_chart_24x36.pdf, frequencies can be calculated using the arfcn field like this:

if 172 < arfcn <  252 then freq = 869 + (arfcn -127) x 0.2 MHz    # 850 band 
if 511 < arfcn <  811 then freq = 1930 + (arfcn - 511) x 0.2 MHz  # 1900 band
if   1 < arfcn <  124 then freq = 935 + (arfcn * 0.2) MHz         # 900 band (original alloc)
if 974 < arfcn < 1023 then freq = 925 + (arfcn - 974) x 0.2 MHz   # 900 band E-GSM
if 511 < arfcn <  886 then freq = 1805 + (arfcn - 511) x 0.2 MHz  # 1800 band

Notice the 1800 and 1900 bands have the same channel ids and nearly the same algorithm with a different starting point.

According to this mail the distance from the Base Station can be calculated using the tav field in 550-metre steps. This information together with the list of neighbouring cells could be used for geolocation and potentially yield better results than using Signal-quality values for that.

Serving Cell GPRS Information (2,2)

Response format:

%EM: <nts>,<nmo>,<spgc_ccch_sup>,<priority_access_thr>,<cba>,<rac>,<tav>,<dsc>,<c31>,<c32>,<band_ind>,<pfc_supp_n_w>,<ccn_mode_sts>,<Psi_sts_suppt>,<edge_support>,<epcr_support>,<bep_period>,<bss_paging_coord>
Parameter no. Name Meaning Remarks
1 nts PCCCH_TIMESLOT Number of downlink timeslots
2 nmo Network Mode of Operation
3 spgc_ccch_sup Network Control-spgc_ccch_sup Network support for split paging
4 priority_access_thr Network Control-Priority_Access_Threshold packet access to the NW according to priority level
5 cba Cell Bar Access
6 rac Routing Area Code
7 tav Timing Advance See distance calculation note
8 dsc Downlink Signal Counter
9 c31 Cell-reselect Criterion C31
10 c32 Cell-reselect Criterion C32
11 band_ind Band Indicator
12 pfc_supp_n_w PFC Support
13 ccn_mode_sts CCN Mode
14 Psi_sts_suppt PSI Support
15 edge_support EDGE Support
16 epcr_support EPCR Support
17 bep_period BEP Period
18 bss_paging_coord BSS Paging
Neighbour Cell Information (2,3)

The first line of response is of the format %EM: <number of cells listed>, where the maximum seems to be 6, one cell for each channel. The next sixteen lines list the values of each of the parameters for each of the cells.

Parameter no. Short name Meaning Remarks
1 arfcn BCCH channel
2 c1 Path Loss Criterion C1
3 c2 Cell-reselection Criterion C2
4 rxlev Received Field Strength (rxlev/2)+2 gives the AT+CSQ response value
5 bsic Base Station ID Code
6 cell_id Cell Indentity
7 lac Location Area Code
8 frame_offset Frame Offset
9 time_alignmnt Time Alignment
10 cba Cell Bar Access
11 cbq Cell Bar Qualifier
12 cell_type_ind Cell Type Indicator NA/GSM/GPRS
13 rac Routing Area Code
14 cell_resel_offset Cell-reselection Offset
15 temp_offset Temporary Offset
16 rxlev_acc_min Rxlen access min

My Neo1973 reports:

AT%EM=2,3
%EM: 6
763,766,771,778,780,773
20,8,14,18,17,8
20,8,14,18,17,8
73,46,54,51,13,12
6753,10951,3531,0,1933,1924
100,100,300,300,300,100
80229,961995,0,1166923,0,2715553
3504,724,0,3724,4,1112
0,0,0,0,0,0
0,0,0,0,0,0
2,2,2,2,2,2
0,0,0,0,0,0
0,0,0,0,0,0
0,0,0,0,0,0
10,10,10,10,10,10

OK
Location and Paging Parameters (2,4)

Response format:

%EM: <bs_pa_mfrms>,<t3212>,<mcc[0]><mcc[1]><mcc[2]>,<mnc[0]><mnc[1]><mnc[2]>,<tmsi>
Parameter no. Name Meaning
1 bs_pa_mfrms BS PA MFRMS paging repeat period
2 t3212 Periodic location updating interval
3 mcc Mobile Country Code
4 mnc Mobile Network Code
5 tmsi Temporary Mobile Subscriber Identity (in binary)

The MCC and MNC values are the same values that are used to form the Mobile Operator names used by the standard AT+COPS and AT+COPN commands in numeric format. The TMSI is the same number that AT%EM=2,8 gives, just in a different format.

PLMN Parameters (2,5)

Response format:

%EM: <no_creq_max>,<reest_flag>,<txpwr_max>,<rxlev_min>,<rel_cs>,<sgsnr_rel>,<mscr_rel>,<net_rel>
Parameter no. Name Meaning
1 no_creq_max Max. number or retries for channel requests
2 reest_flag Re-establishment Flag
3 txpwr_max MS TXPWR MAX CCCH
4 rxlev_min Rxlev_access_min
5 rel_cs Release Cause (only the last release cause is remembered)
6 sgsnr_rel SGSNR Release
7 mscr_rel MSCR Release
8 net_rel Network Release Info
Ciphering, Hopping, DTX Parameters (2,6)
TODO: Fill in (See: To-Do List)
Power Parameters (2,7)

The output consits of two lines, first line containing 12 comma-separated values and the second line 18 comma-separated values, such as:

AT%EM=2,7
%EM: 1,1,0,0,0,1,1,0,0,0,1,0
6,0,0,0,0,1,1,1,4,0,0,0,0,1,0,0,0,0

OK

On the first line (called Classmark 2) we have:

Value no. Meaning Remarks
1 Revision Level
2 Controlled Early Classmark Sending 1 means enabled
3 A5/1 Encryption algorithm 0 means available
4 RF Power capability
5 Pseudo-synchronisation capability 1 means present
6 SS Screening Indicator
7 SMS capability
8 Frequency capability
9 Classmark 3 options 1 means supported
10 CM Service Prompt 1 means supported
11 A5/3 Encryption algorithm 1 means available
12 A5/2 Encryption algorithm 1 means available

On the second line (called Classmark 3) we have:

Value no. Meaning Remarks
1 Multiband support
2 A5/7 Encryption algorithm 1 means available
3 A5/6 Encryption algorithm 1 means available
4 A5/5 Encryption algorithm 1 means available
5 A5/4 Encryption algorithm 1 means available
6 Valid Radio capability 2  ??
7 Associated Radio capability 2
8 Valid Radio capability 1  ??
9 Associated Radio capability 1
10 Valid R Support  ??
11 R Support R-GSM Class
12 Valid Multi-slot Class  ??
13 Multi-slot Class
14 Unicode 2 treatment
15 Extended Measurement capability 1 means supported
16 Valid Switch-measure-value  ??
17 Switch-measure-value
18 Switch-measure-switch-value
Identity Parameters (2,8)

Response format:

%EM: <imeisv>
<imsi>
<tmsi>

OK

The IMEISV line contains 20 numbers separated by commas, the numbers on positions 5 to 18 are the digits of the IMEI number as returned by AT+CGSN. The second line contains another 20 numbers and the numbers on positions 5 to 19 form the digits of your SIM card's IMSI number, as returned by the AT+CIMI command. The last line contains the Temporary Mobile Subscriber Identity number in plain format (ten digits).

Firmware components versions (2,9)

Prints version information for different components of the modem's firmware. The format and the scope of the information presented is identical to that in AT%VER output with the exception that only a subset of all of the components are listed:

AT%EM=2,9
%VER: alr a086 ** NONE **      10:15:48 28/03/07
%VER: dl a086 ** NONE **      10:17:34 28/03/07
%VER: rr a086 ** NONE **      10:25:37 28/03/07
%VER: mm a086 ** NONE **      10:23:09 28/03/07
%VER: cc a086 ** NONE **      10:16:39 28/03/07
%VER: ss a086 ** NONE **      10:28:52 28/03/07
%VER: sim a086 ** NONE **      10:26:45 28/03/07
%VER: sms a086 ** NONE **      10:27:21 28/03/07

OK
GMM Information (2,10)
TODO: Fill in (See: To-Do List)
GRLC Information (2,11)
TODO: Fill in (See: To-Do List)
AMR Configuration Information (2,12)
TODO: Fill in (See: To-Do List)
PDP Information (2,13)
TODO: Fill in (See: To-Do List)

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 with 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.

Power On, Power Off, and Reset of the GTA01 GSM Modem

GSM Modem Connections

The GTA01 GSM modem communicates via a standard serial port to the host system. The port operates at 115200 baud, 8 bits, no parity, and requires hardware flow control (RTSCTS) to operate. Due to the fact that the host CPU has only a pair of serial ports but there are three devices that wish to use them, the GSM modem port is actually shared with the serial console (the third device is the GPS chip, which has exclusive use of the second serial port).

A GPIO (General Purpose IO) pin controls the switching of the serial port between the console and the GSM modem. Another GPIO is used to turn on the power to the GSM modem. On older versions of the GTA01 a third GPIO could be used to reset the GSM modem; this signal proved to cause difficulties with the modem, and on all the GTA01 units sold this GPIO line is not connected. The driver combines the the switching of the serial port to the GSM modem and the power-on signal to the modem into a single operation; the two cannot be controlled independently from user-space (at the time of this writing).

It is important to note that the GPIO controlling the power-on of the GSM modem can only signal to the modem to turn itself on -- turning this GPIO off does not power off the GSM modem. Instead, the AT@POFF sequence must be sent to the modem in order to perform a power off.

Further complicating power control of the GTA01 GSM modem is the fact that the modem draws power from the battery/charger side of the power management circuitry -- this means that turning off the power to the host CPU on the GTA01 does not turn off the power to the modem. In real-world operation, this means that unless the shutdown procedure for the host cpu's operating system issues the AT@POFF command to power off the GSM modem, the modem will remain turned on, drawing power from the battery even thought the host CPU is completely powered off.

The Power-On Sequence

The sharing of the serial port between the console and the GSM modem results in the need for a very specific power-on and power-off sequence. Two major problems exist that must be avoided: infinite echos, and RTSCTS lockup.

Avoiding Infinite Echos

By default, the serial port is initialized in "echo" mode -- meaning that any characters sent to the serial port from the console will be echoed back to the console. Upon power-up or reset, the GSM modem also echos back characters it receives. So unless action is taken to disable the serial port's echo before the GSM modem is powered on, an infinite echo will result. The modem will print the standard "Interpretor Ready" message, which will be echoed back to it by the serial port driver, the modem will echo that back to the serial port again (adding some error text to the message), the serial port will echo that again, and this continues until buffers in either or both the serial port and the modem fill up, and one of them ceases to transmit.

Once in this situation, it is difficult for software (such as gsmd) to gain synchronization of commands and responses.

The best solution is to avoid the problem to begin with. Simply ensure that the serial port is set to "no-echo" mode before the GSM modem is enabled and powered up. This sequence illustrates how this is normally done:

stty -F /dev/ttySAC0 -echo
echo "1" >/sys/bus/platform/devices/neo1973-pm-gsm.0/power_on

(Note that the stty command argument syntax is somewhat unusual: "-echo" means "disable echo", while "echo" means "enable echo".)

Avoiding RTSCTS Lockup

Hardware flow control uses additional signals in addition to the serial data in and out signals on the serial port to control the flow of the data. Specifically, when hardware flow control is enabled, a given endpoint is expected to assert its RTS (Request To Send) line when it has data to transmit, and not transit that data until it sees a CTS (Clear TO Send) signal from the other end. In this fashion, buffer overruns and data loss are avoided.

The GSM modem requires that hardware flow control be enabled in order to communicate with the host. However, the console lacks the RTS and CTS signals and thus is unable to communicate if hardware flow control is enabled. But what really makes this problem serious is that if hardware flow control is enabled while the serial port is switched to the console, and the (small) transmit buffer for the port fills (such as a kernel log message), the Linux kernel will lock up, and become completely non-responsive. There is no recovery mechanism for this other than to disconnect the device from its USB port or charger, and remove the battery.

One solution to this is to disable the use of the serial port as a console for the kernel. However, this is greatly inconvenient - the knowledgeable user with a debug board will usually wish to have a console available, and the novice user will probably wish to avoid changing the u-boot variables in order to disable the console. So, a better approach is to avoid this situation by taking great care when powering-up, resetting, or powering-down the modem. The following sequence illustrates how to switch the serial port back to the console mode safely:

stty -F /dev/ttySAC0 -crtscts
echo "0" >/sys/bus/platform/devices/neo1973-pm-gsm.0/power_on

Resetting the GSM Modem

The GSM modem can be effectively reset by changing the state of the Power-On GPIO from off to on -- in other words, just disable the GSM modem and re-enable it. The safe way to accomplish this is to combine the two sequences above:

stty -F /dev/ttySAC0 -crtscts
echo "0" >/sys/bus/platform/devices/neo1973-pm-gsm.0/power_on
stty -F /dev/ttySAC0 -echo
echo "1" >/sys/bus/platform/devices/neo1973-pm-gsm.0/power_on

It should be noted that this reset sequence will also power up the modem if it is not enabled and powered up to begin with. For this reason, the reset sequence above should be used for both power-up and reset purposes.

Powering Off the GSM Modem

Powering off the GSM modem on the GTA01 can only be done by issuing the AT@POFF command to the device. In order to issue this command, it is usually necessary to return it to a known state. So the normal mechanism is to issue the reset operation (above), wait for a short period of time (1 second seems to be sufficient), and send the AT@POFF command. This should be followed by an additional short delay (to allow the text to be transmitted), and then the serial port can be switched back to the console. The following script accomplishes this:

### Reset the modem to place it in a known state
stty -F /dev/ttySAC0 -crtscts
echo "0" >/sys/bus/platform/devices/neo1973-pm-gsm.0/power_on
stty -F /dev/ttySAC0 -echo
echo "1" >/sys/bus/platform/devices/neo1973-pm-gsm.0/power_on

### Now enable hardware flow control, and transmit the sequence
stty -F /dev/ttySAC0 crtscts
sleep 1
echo -e "AT@POFF\r" >/dev/ttySAC0
sleep 1

### Finally, we disable flow control, and switch back the port
stty -F /dev/ttySAC0 -crtscts
echo "0" >/sys/bus/platform/devices/neo1973-pm-gsm.0/power_on

Eliminating echo on the non-neo end of phone calls

Modify your /etc/gsmhandset.state as specified at the end of User:TonyGarnockJones

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.

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.

3gpp.org has information about 3G and GSM specifications

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.

Note that the syntax and the interpretation of the output of the commands listed here are only educated guesses and should not be relied on. Part of the proprietary command set has identical or similar usage as on other modems in the market, some of which have fully opened specifications and information about these commands can be taken from their datasheets (some known similar modems with open specs: BenQ M22A and M23A, Enfora Enabler-G II / III and SPT 1834).

AT%VER

Prints the firmware component versions.

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

For a GTA01Bv4 phase 1 phone, produced start of september:

%VER: aci sean non_clearcase   12:32:56 24/08/07
%VER: cc a086 ** NONE **      14:07:10 08/06/07
%VER: dl a086 ** NONE **      14:07:46 08/06/07
%VER: mm a086 ** NONE **      14:11:52 08/06/07
%VER: rr a086 ** NONE **      14:13:01 08/06/07
%VER: sim a086 ** NONE **      14:13:54 08/06/07
%VER: sms a086 ** NONE **      14:14:20 08/06/07
%VER: ss a086 ** NONE **      14:15:52 08/06/07
%VER: alr a086 ** NONE **      14:06:38 08/06/07
%VER: l2r a086 ** NONE **      14:10:36 08/06/07
%VER: ra a086 ** NONE **      14:12:32 08/06/07
%VER: rlp a086 ** NONE **      14:12:40 08/06/07
%VER: fad a086 ** NONE **      14:08:06 08/06/07

For a GTA01Bv3 phase 0 phone:

%VER: aci sean non_clearcase   10:46:06 29/08/06
%VER: cc a086 non_clearcase   14:53:59 28/08/06
%VER: dl a086 non_clearcase   14:54:40 28/08/06
%VER: mm a086 non_clearcase   14:59:25 28/08/06
%VER: rr a086 non_clearcase   15:00:11 28/08/06
%VER: sim a086 non_clearcase   15:00:57 28/08/06
%VER: sms a086 non_clearcase   15:01:23 28/08/06
%VER: ss a086 non_clearcase   15:02:22 28/08/06
%VER: alr a086 non_clearcase   14:53:19 28/08/06
%VER: l2r a086 non_clearcase   14:58:02 28/08/06
%VER: ra a086 non_clearcase   14:59:50 28/08/06
%VER: rlp a086 non_clearcase   14:59:56 28/08/06
%VER: fad a086 non_clearcase   14:55:04 28/08/06
%VER: t30 a086 non_clearcase   15:02:27 28/08/06

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).

AT%A

Print values from an ADC.

This command is not listed in AT+CLAC output but it is triggered by any input that starts with AT%A except AT%ALS (Alternative Line Service) and AT%ATR, which are other proprietary AT commands. So for example AT%ABCD,HELLO will also run this commands. On my Neo modem it prints a line containing nine values of the form ADC <number> = <value>:

AT%A
EXT: I
ADC 0 = e19, ADC 1 = 0, ADC 2 = d, ADC 3 = 6ea, ADC 4 = a25, ADC 5 = 9fc, ADC 6 = 96d, ADC 7 = 0, ADC 8 = 6

It would seem there's an ADC (analog-to-digital converter) module in the modem with nine input lines connected to it and the values on these lines are reported by this command in hexadecimal format. The values change over time. Inputs 1 and 7 always show zero on my modem, input 1 value changes slightly (+/- 20), while values on inputs 3, 4, 5, 6 and 8 change seemingly randomly in the range 0x000 - 0xfff (it would seem the chip is 12-bit).

AT%NRG

The AT%NRG (Network registration and service selection) is an expansion of the AT+COPS command. It allows specifying the service state of the registration, in addition to AT+COPS functionality. It doesn't however allow listing all present operators (use AT+COPS for this).

AT%EM

Execution of Engineering Mode commands. Allows viewing the information accessible to the modem but not available through standard GSM AT commands set such as detailed information on the current Serving Cell (the one we're registered with), its neighbouring cells, the GPRS/EDGE availability and SIM card data.

Citing Enfora Inc. Application Note EDG0108TN01: The purpose of Engineering Mode (EM) is to provide means to observe the behavior of the mobile station and the settings of the network as counterpart and therefore defines a lot of possibilities to analyze the network. The EM can be used for observation of a defined data set during functional test and field test.

Warning: The display of certain parameters is dependent on the wireless network sending the correct information in the System Information Packets. There is no guaranty that the information is always forwarded from the network. At times data may not be present to display in the Engineering Mode responses.

Syntax:

AT%EM=<mode>,<command>

Allowed <mode> values:

  • 2 - AT command mode
  • 3 - PCO mode

I only describe the AT mode commands here. Commands are in range 1 to 13:

AT%EM=2,1  Serving Cell Information
AT%EM=2,2  Serving Cell GPRS Information
AT%EM=2,3  Neighbour Cell Information
AT%EM=2,4  Location and Paging Parameters
AT%EM=2,5  PLMN Parameters
AT%EM=2,6  Ciphering, Hopping, DTX Parameters
AT%EM=2,7  Power Parameters
AT%EM=2,8  Identity Parameters
AT%EM=2,9  Firmware components versions
AT%EM=2,10 GMM Information
AT%EM=2,11 GRLC Information
AT%EM=2,12 AMR Configuration Information
AT%EM=2,13 PDP Information
Serving Cell Information (2,1)

Response format:

%EM: <afrcn>,<c1>,<c2>,<rxlev>,<bsic>,<cell_id>,<dsc>,<txlev>,<tn>,<rlt>,<tav>,<rxlev_f>,<rxlev_s>,<rxqual_f>,<rxqual_s>,<lac>,<cba>,<cbq>,<cell_type_ind>,<vocoder>
Parameter no. Name Meaning Remarks
1 arfcn Current Channel Number See below for frequency calculation
2 c1 Path Loss Criterion C1
3 c2 Cell-reselection Criterion C2
4 rxlev Received Field Strength (rxlev/2)+2 gives the AT+CSQ response value
5 bsic Base Station ID Code
6 cell_id Cell Indentifier
7 dsc Downlink Signaling Counter current counter value
8 txlev Transmit Power Level
9 tn Timeslot Number
10 rlt Radio Link Timeout Counter
11 tav Timing Advance See below for distance calculation
12 rxlev_f Received Field Strength full
13 rxlev_s Received Field Strength sub
14 rxqual_f Received Quality full
15 rxqual_s Received Quality sub
16 lac Location Area Code
17 cba Cell Bar Access
18 cbq Cell Bar Qualifier
19 Cell_type_ind Cell Type Indicator NA/GSM/GPRS
20 vocoder Vocoder Sig/speech/efr/amr/14.4/9.6/4.8/2.4

According to http://www.qrctech.com/freq_chart_24x36.pdf, frequencies can be calculated using the arfcn field like this:

if 172 < arfcn <  252 then freq = 869 + (arfcn -127) x 0.2 MHz    # 850 band 
if 511 < arfcn <  811 then freq = 1930 + (arfcn - 511) x 0.2 MHz  # 1900 band
if   1 < arfcn <  124 then freq = 935 + (arfcn * 0.2) MHz         # 900 band (original alloc)
if 974 < arfcn < 1023 then freq = 925 + (arfcn - 974) x 0.2 MHz   # 900 band E-GSM
if 511 < arfcn <  886 then freq = 1805 + (arfcn - 511) x 0.2 MHz  # 1800 band

Notice the 1800 and 1900 bands have the same channel ids and nearly the same algorithm with a different starting point.

According to this mail the distance from the Base Station can be calculated using the tav field in 550-metre steps. This information together with the list of neighbouring cells could be used for geolocation and potentially yield better results than using Signal-quality values for that.

Serving Cell GPRS Information (2,2)

Response format:

%EM: <nts>,<nmo>,<spgc_ccch_sup>,<priority_access_thr>,<cba>,<rac>,<tav>,<dsc>,<c31>,<c32>,<band_ind>,<pfc_supp_n_w>,<ccn_mode_sts>,<Psi_sts_suppt>,<edge_support>,<epcr_support>,<bep_period>,<bss_paging_coord>
Parameter no. Name Meaning Remarks
1 nts PCCCH_TIMESLOT Number of downlink timeslots
2 nmo Network Mode of Operation
3 spgc_ccch_sup Network Control-spgc_ccch_sup Network support for split paging
4 priority_access_thr Network Control-Priority_Access_Threshold packet access to the NW according to priority level
5 cba Cell Bar Access
6 rac Routing Area Code
7 tav Timing Advance
8 dsc Downlink Signal Counter
9 c31 Cell-reselect Criterion C31
10 c32 Cell-reselect Criterion C32
11 band_ind Band Indicator
12 pfc_supp_n_w PFC Support
13 ccn_mode_sts CCN Mode
14 Psi_sts_suppt PSI Support
15 edge_support EDGE Support
16 epcr_support EPCR Support
17 bep_period BEP Period
18 bss_paging_coord BSS Paging
Neighbour Cell Information (2,3)

The first line of response is of the format %EM: <number of cells listed>, where the maximum seems to be 6, one cell for each channel. The next sixteen lines list the values of each of the parameters for each of the cells.

Parameter no. Short name Meaning Remarks
1 arfcn BCCH channel
2 c1 Path Loss Criterion C1
3 c2 Cell-reselection Criterion C2
4 rxlev Received Field Strength (rxlev/2)+2 gives the AT+CSQ response value
5 bsic Base Station ID Code
6 cell_id Cell Indentity
7 lac Location Area Code
8 frame_offset Frame Offset
9 time_alignmnt Time Alignment
10 cba Cell Bar Access
11 cbq Cell Bar Qualifier
12 cell_type_ind Cell Type Indicator NA/GSM/GPRS
13 rac Routing Area Code
14 cell_resel_offset Cell-reselection Offset
15 temp_offset Temporary Offset
16 rxlev_acc_min Rxlen access min

My Neo1973 reports:

AT%EM=2,3
%EM: 6
763,766,771,778,780,773
20,8,14,18,17,8
20,8,14,18,17,8
73,46,54,51,13,12
6753,10951,3531,0,1933,1924
100,100,300,300,300,100
80229,961995,0,1166923,0,2715553
3504,724,0,3724,4,1112
0,0,0,0,0,0
0,0,0,0,0,0
2,2,2,2,2,2
0,0,0,0,0,0
0,0,0,0,0,0
0,0,0,0,0,0
10,10,10,10,10,10

OK
Location and Paging Parameters (2,4)

Response format:

%EM: <bs_pa_mfrms>,<t3212>,<mcc[0]><mcc[1]><mcc[2]>,<mnc[0]><mnc[1]><mnc[2]>,<tmsi>
Parameter no. Name Meaning
1 bs_pa_mfrms BS PA MFRMS paging repeat period
2 t3212 Periodic location updating interval
3 mcc Mobile Country Code
4 mnc Mobile Network Code
5 tmsi Temporary Mobile Subscriber Identity (in binary)

The MCC and MNC values are the same values that are used to form the Mobile Operator names used by the standard AT+COPS and AT+COPN commands in numeric format. The TMSI is the same number that AT%EM=2,8 gives, just in a different format.

PLMN Parameters (2,5)

Response format:

%EM: <no_creq_max>,<reest_flag>,<txpwr_max>,<rxlev_min>,<rel_cs>,<sgsnr_rel>,<mscr_rel>,<net_rel>
Parameter no. Name Meaning
1 no_creq_max Max. number or retries for channel requests
2 reest_flag Re-establishment Flag
3 txpwr_max MS TXPWR MAX CCCH
4 rxlev_min Rxlev_access_min
5 rel_cs Release Cause (only the last release cause is remembered)
6 sgsnr_rel SGSNR Release
7 mscr_rel MSCR Release
8 net_rel Network Release Info
Ciphering, Hopping, DTX Parameters (2,6)
TODO: Fill in (See: To-Do List)
Power Parameters (2,7)

The output consits of two lines, first line containing 12 comma-separated values and the second line 18 comma-separated values, such as:

AT%EM=2,7
%EM: 1,1,0,0,0,1,1,0,0,0,1,0
6,0,0,0,0,1,1,1,4,0,0,0,0,1,0,0,0,0

OK

On the first line (called Classmark 2) we have:

Value no. Meaning Remarks
1 Revision Level
2 Controlled Early Classmark Sending 1 means enabled
3 A5/1 Encryption algorithm 0 means available
4 RF Power capability
5 Pseudo-synchronisation capability 1 means present
6 SS Screening Indicator
7 SMS capability
8 Frequency capability
9 Classmark 3 options 1 means supported
10 CM Service Prompt 1 means supported
11 A5/3 Encryption algorithm 1 means available
12 A5/2 Encryption algorithm 1 means available

On the second line (called Classmark 3) we have:

Value no. Meaning Remarks
1 Multiband support
2 A5/7 Encryption algorithm 1 means available
3 A5/6 Encryption algorithm 1 means available
4 A5/5 Encryption algorithm 1 means available
5 A5/4 Encryption algorithm 1 means available
6 Valid Radio capability 2  ??
7 Associated Radio capability 2
8 Valid Radio capability 1  ??
9 Associated Radio capability 1
10 Valid R Support  ??
11 R Support R-GSM Class
12 Valid Multi-slot Class  ??
13 Multi-slot Class
14 Unicode 2 treatment
15 Extended Measurement capability 1 means supported
16 Valid Switch-measure-value  ??
17 Switch-measure-value
18 Switch-measure-switch-value
Identity Parameters (2,8)

Response format:

%EM: <imeisv>
<imsi>
<tmsi>

OK

The IMEISV line contains 20 numbers separated by commas, the numbers on positions 5 to 18 are the digits of the IMEI number as returned by AT+CGSN. The second line contains another 20 numbers and the numbers on positions 5 to 19 form the digits of your SIM card's IMSI number, as returned by the AT+CIMI command. The last line contains the Temporary Mobile Subscriber Identity number in plain format (ten digits).

Firmware components versions (2,9)

Prints version information for different components of the modem's firmware. The format and the scope of the information presented is identical to that in AT%VER output with the exception that only a subset of all of the components are listed:

AT%EM=2,9
%VER: alr a086 ** NONE **      10:15:48 28/03/07
%VER: dl a086 ** NONE **      10:17:34 28/03/07
%VER: rr a086 ** NONE **      10:25:37 28/03/07
%VER: mm a086 ** NONE **      10:23:09 28/03/07
%VER: cc a086 ** NONE **      10:16:39 28/03/07
%VER: ss a086 ** NONE **      10:28:52 28/03/07
%VER: sim a086 ** NONE **      10:26:45 28/03/07
%VER: sms a086 ** NONE **      10:27:21 28/03/07

OK
GMM Information (2,10)
TODO: Fill in (See: To-Do List)
GRLC Information (2,11)
TODO: Fill in (See: To-Do List)
AMR Configuration Information (2,12)
TODO: Fill in (See: To-Do List)
PDP Information (2,13)
TODO: Fill in (See: To-Do List)

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 with 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.

Power On, Power Off, and Reset of the GTA01 GSM Modem

GSM Modem Connections

The GTA01 GSM modem communicates via a standard serial port to the host system. The port operates at 115200 baud, 8 bits, no parity, and requires hardware flow control (RTSCTS) to operate. Due to the fact that the host CPU has only a pair of serial ports but there are three devices that wish to use them, the GSM modem port is actually shared with the serial console (the third device is the GPS chip, which has exclusive use of the second serial port).

A GPIO (General Purpose IO) pin controls the switching of the serial port between the console and the GSM modem. Another GPIO is used to turn on the power to the GSM modem. On older versions of the GTA01 a third GPIO could be used to reset the GSM modem; this signal proved to cause difficulties with the modem, and on all the GTA01 units sold this GPIO line is not connected. The driver combines the the switching of the serial port to the GSM modem and the power-on signal to the modem into a single operation; the two cannot be controlled independently from user-space (at the time of this writing).

It is important to note that the GPIO controlling the power-on of the GSM modem can only signal to the modem to turn itself on -- turning this GPIO off does not power off the GSM modem. Instead, the AT@POFF sequence must be sent to the modem in order to perform a power off.

Further complicating power control of the GTA01 GSM modem is the fact that the modem draws power from the battery/charger side of the power management circuitry -- this means that turning off the power to the host CPU on the GTA01 does not turn off the power to the modem. In real-world operation, this means that unless the shutdown procedure for the host cpu's operating system issues the AT@POFF command to power off the GSM modem, the modem will remain turned on, drawing power from the battery even thought the host CPU is completely powered off.

The Power-On Sequence

The sharing of the serial port between the console and the GSM modem results in the need for a very specific power-on and power-off sequence. Two major problems exist that must be avoided: infinite echos, and RTSCTS lockup.

Avoiding Infinite Echos

By default, the serial port is initialized in "echo" mode -- meaning that any characters sent to the serial port from the console will be echoed back to the console. Upon power-up or reset, the GSM modem also echos back characters it receives. So unless action is taken to disable the serial port's echo before the GSM modem is powered on, an infinite echo will result. The modem will print the standard "Interpretor Ready" message, which will be echoed back to it by the serial port driver, the modem will echo that back to the serial port again (adding some error text to the message), the serial port will echo that again, and this continues until buffers in either or both the serial port and the modem fill up, and one of them ceases to transmit.

Once in this situation, it is difficult for software (such as gsmd) to gain synchronization of commands and responses.

The best solution is to avoid the problem to begin with. Simply ensure that the serial port is set to "no-echo" mode before the GSM modem is enabled and powered up. This sequence illustrates how this is normally done:

stty -F /dev/ttySAC0 -echo
echo "1" >/sys/bus/platform/devices/neo1973-pm-gsm.0/power_on

(Note that the stty command argument syntax is somewhat unusual: "-echo" means "disable echo", while "echo" means "enable echo".)

Avoiding RTSCTS Lockup

Hardware flow control uses additional signals in addition to the serial data in and out signals on the serial port to control the flow of the data. Specifically, when hardware flow control is enabled, a given endpoint is expected to assert its RTS (Request To Send) line when it has data to transmit, and not transit that data until it sees a CTS (Clear TO Send) signal from the other end. In this fashion, buffer overruns and data loss are avoided.

The GSM modem requires that hardware flow control be enabled in order to communicate with the host. However, the console lacks the RTS and CTS signals and thus is unable to communicate if hardware flow control is enabled. But what really makes this problem serious is that if hardware flow control is enabled while the serial port is switched to the console, and the (small) transmit buffer for the port fills (such as a kernel log message), the Linux kernel will lock up, and become completely non-responsive. There is no recovery mechanism for this other than to disconnect the device from its USB port or charger, and remove the battery.

One solution to this is to disable the use of the serial port as a console for the kernel. However, this is greatly inconvenient - the knowledgeable user with a debug board will usually wish to have a console available, and the novice user will probably wish to avoid changing the u-boot variables in order to disable the console. So, a better approach is to avoid this situation by taking great care when powering-up, resetting, or powering-down the modem. The following sequence illustrates how to switch the serial port back to the console mode safely:

stty -F /dev/ttySAC0 -crtscts
echo "0" >/sys/bus/platform/devices/neo1973-pm-gsm.0/power_on

Resetting the GSM Modem

The GSM modem can be effectively reset by changing the state of the Power-On GPIO from off to on -- in other words, just disable the GSM modem and re-enable it. The safe way to accomplish this is to combine the two sequences above:

stty -F /dev/ttySAC0 -crtscts
echo "0" >/sys/bus/platform/devices/neo1973-pm-gsm.0/power_on
stty -F /dev/ttySAC0 -echo
echo "1" >/sys/bus/platform/devices/neo1973-pm-gsm.0/power_on

It should be noted that this reset sequence will also power up the modem if it is not enabled and powered up to begin with. For this reason, the reset sequence above should be used for both power-up and reset purposes.

Powering Off the GSM Modem

Powering off the GSM modem on the GTA01 can only be done by issuing the AT@POFF command to the device. In order to issue this command, it is usually necessary to return it to a known state. So the normal mechanism is to issue the reset operation (above), wait for a short period of time (1 second seems to be sufficient), and send the AT@POFF command. This should be followed by an additional short delay (to allow the text to be transmitted), and then the serial port can be switched back to the console. The following script accomplishes this:

### Reset the modem to place it in a known state
stty -F /dev/ttySAC0 -crtscts
echo "0" >/sys/bus/platform/devices/neo1973-pm-gsm.0/power_on
stty -F /dev/ttySAC0 -echo
echo "1" >/sys/bus/platform/devices/neo1973-pm-gsm.0/power_on

### Now enable hardware flow control, and transmit the sequence
stty -F /dev/ttySAC0 crtscts
sleep 1
echo -e "AT@POFF\r" >/dev/ttySAC0
sleep 1

### Finally, we disable flow control, and switch back the port
stty -F /dev/ttySAC0 -crtscts
echo "0" >/sys/bus/platform/devices/neo1973-pm-gsm.0/power_on

Eliminating echo on the non-neo end of phone calls

Modify your /etc/gsmhandset.state as specified at the end of User:TonyGarnockJones