Qtopia Home - Classes - Hierachy - Annotated - Functions - Qt Embedded |

# Qtopia Phone Simulator

- Introduction
- Using the phone simulator
- Peer connections
- GSM 07.10 multiplexing
- XML response file format
- SIM Application Toolkit commands

## Introduction

The "phonesim" program implements an AT command "phone simulator". It accepts AT-style commands on its input and responds with pre-defined responses. The phone simulator is by no means a full replacement for a fully functional phone but it can provide convenient help for debugging many issues.

## Using the phone simulator

Usage: phonesim [-p port] filename

The default port number is 12345.

To use the Qtopia dialer with the phone simulator, you must set the QTOPIA_PHONE_DEVICE environment variable to "sim:hostname" where "hostname" is the name of the host where the simulator resides. Normally this can simply be set to "localhost".

The special phone number "199" can be used to initiate a "dial back". The simulator will immediately hang up and then dial the user back after a few seconds. This can be used to test incoming connections in a single-user environment.

Filename points to the XML response file that the phone simulator should use.

## Peer connections

The phone simulator can support "peer" connections. That is, a user running the phone simulator can "call" another user running their own copy of the phone simulator. This is useful for testing incoming calls.

When the phone simulator starts up, it will print your "phone number", which will be something like "55500nn". I've created simulator phone numbers for everyone in the Brisbane Trolltech office - "nn" is the last part of your IP address (e.g. 10.1.1.13 becomes 5550013). Edit the list in the "peers.xml" file to add new numbers. If "peers.xml" does not exist in the same directory as "troll.xml", then peering will be disabled.

With peering enabled, you should be able to dial "55500nn" and the other user will see an incoming connection on their end which they can accept and process in the usual fashion.

## GSM 07.10 multiplexing

The phone simulator for the 2.x series of Qtopia Phone Editions includes support for GSM 07.10 multiplexing (i.e. AT+CMUX). This removes the previous need to have two phone simulator connections in order to emulate the high-priority and low-priority command channels. To use multiplexing, you only need to set the following environment variable:

export QTOPIA_PHONE_DEVICE=sim:localhost

There is no longer any need to set QTOPIA_PHONE_DEVICE_LOW. Be aware that if you do set both variables, then the simulator will use separate connections rather than GSM 07.10 multiplexing.

Using GSM 07.10 with the phone simulator has the advantage that the high-priority and low-priority channels will share the same state (i.e. state modification commands on one will affect the answer on the other). This is not the case with dual connections.

## XML response file format

The responses are defined by an XML file (e.g. "troll.xml"), with the following format:

tag | description
--- | ---
<simulator> | Root element for the XML document.
<state name="X"> | Define commands that only apply in a specific state.
<chat> | (child of top-level or <state>) Define a chat command/response sequence. A top-level <chat> applies to all states unless there is a state-specific override.
<command> | (child of <chat>) Contains the text of the command to responsd to. "*" at the end can be used to match everything starting with a specific prefix.
<response delay="N" eol="true|false"> | (child of <chat>) Contains the text of the response, with an optional delay before sending it back to the client. The delay is in milliseconds. The sequence "${X}" can be used in a response to indicate "substitute the value of script variable X". If "eol" is "true" (the default), then the response will be followed by an end of line sequence.
<switch name="X"/> | (child of <chat>) Switch into the specified state after issuing the response. An unspecified state name indicates to return to the top-level state. The name "default" can be used to switch back to the default state.

<unsolicited delay="N" switch="X">

(child of top-level or <state>) Indicates an unsolicited response to issue to the client after "N" milliseconds after switching into the current state. The optional "switch" tells the simulator to enter the specified state after sending the unsolicited response (e.g. an unsolicited RING may put the simulator into a different state from the default). The sequence "${X}" can be used in a response to indicate "substitute the value of script variable X".

<set name="X" value="Y"/>

(child of top-level or <chat>) When used at the top level, this sets the default value of a script variable called "X" to "Y". When used within a <chat> element, this will set the value of the script variable "X" when the <chat>'s command is successfully matched. The value "*" can be used for the "*" part of a prefix command match. This allows parameter information to be copied from a command into a variable.

<start name="X"/> | Starting state, if not the same as the top-level state.
<peerconnect/> | (child of <chat>) Initiate a connection to a peer phone simulator, to emulate "dialing" another person.
<peer hangup="FLAG"> | (child of <chat>) Send the contents of the tag to the peer connection, if any. If "FLAG" is "true", then also hangup the peer connection.
<peerinfo number="NUM" host="HOST"/> | Associate the phone number "NUM" with the given "HOST" for peering. Whenever the user dials "NUM", it will cause a peer connection to be initiated to "HOST".
<newcall name="VAR"/> | Allocate a new call identifier and put its number into "VAR".
<forgetcall id="ID"/> | Forget a call with identifier "ID", freeing up the identifier to be allocated to a new call.
<toolkit> | Define a program for the SIM Application Toolkit part of the simulator.

## SIM Application Toolkit commands

The <toolkit> tag can be used to define a simple program that simulates an application running inside the SIM.

tag | description
--- | ---
<label name="NAME"/> | Define a program label, that can be used as the destination for <goto>, <gosub>, and similar commands.
<goto name="NAME"/> | Jump to the point in the program that is defined by the label "NAME".
<gosub name="NAME"/> | Set the return location to the current point in the program and then jump to the point in the program that is defined by the label "NAME". Only one level of subroutine is currently supported.
<return> | Return from the current subroutine.
<set name="NAME" value="VALUE"/> | Set the variable called "NAME" to "VALUE". If "VALUE" contains a term of the form "${X}", then the contents of the variable "X" will be inserted at that position.
<ifeq var="NAME" value="VALUE" goto="LABEL"/> | Compare the contents of the variable "NAME" with "VALUE" and then jump to "LABEL" if they are the same.
<ifne var="NAME" value="VALUE" goto="LABEL"/> | Compare the contents of the variable "NAME" with "VALUE" and then jump to "LABEL" if they are not the same.
<eval var="NAME" left="LEFT" op="OPERATOR" right="RIGHT"/> | Evaluate an arithmetic expression and place the result into the variable "NAME". "OPERATOR" may be one of "+", "-", "*", "/", "%", "&", "|", "^", "~", "<<", ">>", "&&", "||", "!", or "concat".
<mainmenu title="TITLE"> | Define the main program menu with the given "TITLE".
<menu title="TITLE" default="ITEM" [back="LABEL"]> | Define a program menu with the given "TITLE" and default "ITEM". When the user selects "Back", the program will jump to "LABEL".
<item id="ID" name="NAME" [help="HELPLABEL"] goto="LABEL"/> | Define an item within a <mainmenu> or <menu> element. "ID" is a numeric value that identifies the item; "NAME" is the text name to display on the user's screen; "HELPLABEL" is a label to jump to if the user selects "Help" for the item; and "LABEL" is the regular label to jump to when the user selects the item.
<displaytext [autoclear="CLEAR"] [highpriority="HIGH">TEXT</displaytext> | Display "TEXT" on the user's screen. If "CLEAR" is "true", then automatically clear the text after 3 seconds. If "HIGH" is "true", then the text should be displayed with high priority.
<getkey type="TYPE" [help="LABEL"]/> | Ask the user for a single keypress. "TYPE" may be one of "digit", "alpha", or "ucs2". If the user selects "Help", then the program will jump to "LABEL".

<getinput type="TYPE" [help="LABEL"] [echo="ECHO"] [minlength="MIN"] [maxlength="MAX"]/>

Ask the user for a line of input. "TYPE" may be one of "digit", "alpha", or "ucs2". If the user selects "Help", then the program will jump to "LABEL". If "ECHO" is "false", then the characters will not be echoed to the screen (e.g. for passwords). "MIN" and "MAX" define the minimum and maximum text lengths (1 and 255 by default, respectively).

<setupcall number="NUMBER" [subAddress="SUBADDR"] [othercalls="OTHER"] [class="CLASS"]/>

Ask the phone to set up a phone call to "NUMBER" (extension "SUBADDR"). "OTHER" should be one of "notbusy" (the default), "hold", or "hangup". "notbusy" indicates that the call should only be attempted if the user is not busy on another call. "hold" indicates that all other calls should be placed on hold. "hangup" indicates that all other calls should be hung up first. "CLASS" should be one of "voice" (the default), "data", or "fax".

<play tone="TONE" [interval="INTERVAL"]/> | Play the given "TONE" for "INTERVAL" milliseconds. "TONE" should be one of "dial", "busy", "congestion", "radio ack", "dropped", "error", "call waiting", "ringing", "general beep", "positive beep", or "negative beep". If the interval is not supplied, it defaults to 1 second.
<refresh type="TYPE"/> | Inform the phone that a refresh has occurred. "TYPE" should be one of "init and full file change", "file change", "init and file change", "initialization", or "reset".
<sendss>TEXT</sendss> | Tell the user with the message "TEXT" that a supplementary service (SS) change is in progress.
<sendsms>TEXT</sendsms> | Tell the user with the message "TEXT" that an SMS message is being sent.
<sendussd>TEXT</sendussd> | Tell the user with the message "TEXT" that Unstructured Supplementary Service Data (USSD) is being sent.
<setupeventlist type="TYPE"/> | Setup event reporting according to "TYPE", which should be one of "idle", "user", "idle and user", or "cancel".