Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference

Qtopia Phone Simulator

Introduction

Phonesim implements an AT command phone simulator and provides a convenient tool to aid debugging. It accepts AT-style commands as input and returns pre-defined responses, but is not designed as a replacement for a fully functioning phone.

Using the Phone Simulator

The command used to run the Phone Simulator is:

phonesim [-p port] filename

where the default port number is 12345 and filename indicates the XML response file to be used.

To use the Qtopia dialer with the phone simulator, the QTOPIA_PHONE_DEVICE environment variable must be set to:

sim:hostname

where hostname is the name of the host where the simulator resides. For most implementations this is set to localhost.

Special Phone Numbers

The Phone Simulator utilizes the following special phone numbers to simulate events:

Phone Number Function
199 Initiate a Dial Back, that is, the simulator will immediately hang-up and then dial the user back after a delay of a few seconds. This is used to test incoming connections in a single-user environment.
199 Reflect outgoing SMS messages back into the incoming message queue.
177 Simulate a missed call but initiating a dial back and hanging up after a number of retries.
166 Simulate a bad phone number or bad connection by making and outgoing call that does not connect.

GSM 07.10 Multiplexing

The Phone Simulator for the 2.x series of Qtopia Phone Editions includes support for GSM 07.10 multiplexing, that is, AT+CMUX. This removes the requirement for two phone simulator connections to emulate the high-priority and low-priority command channels. The channels will share the same state and state modification commands on one channel will affect the answer on the other channel, which is not the case with dual connections.

To use multiplexing set the following environment variable:

export QTOPIA_PHONE_DEVICE=sim:localhost

The environment variable QTOPIA_PHONE_DEVICE_LOW no longer needs to be set.

Note: If both environment variables are set, the simulator will use separate connections rather than GSM 07.10 multiplexing.

XML Response File Format

Phone Simulator responses are defined by an XML file (for example, 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 respond to. The wildcard character "*" at the end of the text 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 prior to 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.
<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 is used to define a simple program to simulate 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".


Copyright © 2005 Trolltech Trademarks
Qtopia version 2.2.0