=== main
=== all
The following commands are available:

at		AT commands to the target
batt		Send MMI_BATTERY_IND primitive to target UI firmware
disable		Disable receiving and display of certain packet types
enable		Enable receiving and display of certain packet types
exit		Exit from fc-shell
key		Send keystroke event to UI firmware on the target
keydown		Send key down event to UI firmware on the target
keyup		Send key up event to UI firmware on the target
poweroff	Send power-off ETM command packet to the target
quit		Alias for exit
send		Send arbitrary RVTMUX packet to the target
sp		Send GPF system primitive to the target
str		Send arbitrary strings to ATI
tch		TCH commands, see help tch
tch-dl		Enable/disable TCH downlink forwarding on the target
tgtreset	Send reset/reboot ETM command packet to the target
unterm		Send unterminated strings to ATI

To get help on any command, type help and the command keyword.

=== at
=== AT
Any fc-shell command input that begins with the characters "at" or "AT" is sent
literally to the AT command interpreter (ATI) in the target firmware via the
FreeCalypso-defined "AT" RVTMUX channel.  Use the str command (see help str) to
send strings to ATI which do not begin with "at" or "AT", e.g., when sending
SMS.

Any time you send anything to ATI, fc-shell automatically performs the
equivalent of an enable ati command so you can see ATI's responses; any
asynchronous output from ATI is also enabled as a side effect.

=== batt
batt <state> <level>

TI's MFW (UI firmware component) uses MMI_BATTERY_IND primitive (in the GPF and
protocol stack sense) to communicate battery events from driver callback
functions to the MMI task.  GPF allows any protocol stack primitive to be
injected externally; sending this MMI_BATTERY_IND primitive from the development
host allows the UI firmware's battery functions to be exercised on development
boards that have no battery or charging hardware.

fc-shell batt command sends an MMI_BATTERY_IND protocol stack primitive with
user-specified parameter bytes; the meaning of these parameter bytes depends on
the firmware version.  In current FC Tourmaline fw the state byte communicates
both durable states and transient events as listed below, whereas the level byte
sets the battery icon level in the [0,4] range or is set to 255 to mean no
battery level information in this event.  Valid states and events for current
FC Tourmaline are as follows:

batt 0 lev	-- no charging activity, lev is in [0,4] range
batt 1 255	-- charging in progress, battery icon becomes animated
batt 2 4	-- charging complete, battery icon full
batt 3 255	-- charger plug transient event

=== disable
=== enable
{dis,en}able ati
{dis,en}able gpf
{dis,en}able tch

fc-shell is fully asynchronous: user commands cause RVTMUX packets to be sent
to the target, whereas incoming packets from the target whose reception and
display is enabled are decoded and displayed.  The disable and enable commands
tell fc-shell to disable or enable receiving and display of the specified
packet types (RVTMUX channels); multiple channels may be listed in a single
command.

=== exit
=== quit
This command is self-explanatory.

=== key
key <key-sequence>

This command sends a GPF system primitive to the MMI entity in the target
firmware that encodes a simulated keystroke or a sequence of simulated
keystrokes.  Digits 0-9 are sent naturally, star and hash keys are sent as
'*' and '#' ASCII characters, and the remaining keys on the D-Sample keypad
are encoded as short all-uppercase ASCII strings as follows:

UP, DOWN, LEFT, RIGHT and CENTER: directional keys
LSOFT and RSOFT: "soft left" and "soft right" keys directly under the LCD
SEND and END: green and red keys, respectively
VOL_PLUS, VOL_MINUS and EXTRA: the 3 side buttons on the D-Sample handset

Both single-character and long-named keys can be run together, for example:

key RSOFT*	-- keypad lock or unlock sequence
key 5551212SEND	-- enter digits 5551212, then SEND button to start the call

=== keydown
=== keyup
keydown <key-name>
keyup <key-name>

The basic key command sends a KEY_SEQUENCE command (encoded via a GPF CONFIG
system primitive) to the MMI entity in the target firmware; TI's firmware
implementation then generates first a key down event, then a key up event for
each key in the transmitted sequence.  TI's firmware also supports similarly-
encoded KEY_PRESS and KEY_RELEASE commands which generate only a single key down
or key up event, respectively; our keydown and keyup commands provide access to
this functionality.  Only single keys can be sent with these commands, not
sequences.

=== poweroff
This command sends a power-off request in the form of an ETM ABB register write
command packet to the target.

=== send
send xx xx xx xx...

This command sends an arbitrary RVTMUX packet to the target, given as raw
hex bytes.

=== sp
sp <dest> <command>

This command sends a GPF system primitive to the target.  The first blank-
delimited word after the sp command keyword is the protocol stack destination
to which the sysprim is to be sent, and the rest of the string is passed
literally to the target.

This command also automatically performs an equivalent of enable gpf so you can
see the response to your sysprim; you may later need to issue a disable gpf
command to stop the occasional asynchronous noise that may be emitted on the
GPF RVTMUX channel by various G23M components.

=== str
str <arbitrary text>

This command sends everything after the str command keyword to the AT command
interpreter (ATI) in the target firmware via the FreeCalypso-defined "AT"
RVTMUX channel.  This command can be used to send strings to ATI which do not
begin with "at" or "AT", as may be needed when sending SMS.

Any time you send anything to ATI, fc-shell automatically performs the
equivalent of an enable ati command so you can see ATI's responses; any
asynchronous output from ATI is also enabled as a side effect.

=== tch
=== TCH
The commands in this set exercise the experimental TCH rerouting feature
implemented in some FreeCalypso GSM firmware versions; these commands have any
effect only when run against one of these specially built fw versions.
The available commands are:

tch dump-raw	Enable or disable the raw dump mode
tch play	Play a file into TCH uplink
tch record	Record TCH downlink in a file
tch status	Show current status of TCH operations

Type help tch <subcmd> to get the detailed description of each of these tch
subcommands.

=== tch:dump-raw
tch dump-raw on|off

This command tells fc-shell what it should do with incoming packets on the
RVTMUX TCH multiplex channel.  If the raw dump mode is off (the default),
fc-shell processes these incoming packets intelligently; if the raw dump mode
is on, fc-shell dumps these packets in raw hex and does nothing more, presenting
the behaviour it had before tch play and tch record commands were implemented.
tch play and tch record cannot be used when the raw dump mode is enabled.

=== tch:play
tch play <filename>	# start TCH UL play
tch play stop		# stop TCH UL play before the end of the UL play file

Please refer to the doc/TCH-bit-access article in the FreeCalypso host tools
source for the details.

=== tch:record
tch record <filename>	# start TCH DL recording
tch record stop		# stop TCH DL recording

Please refer to the doc/TCH-bit-access article in the FreeCalypso host tools
source for the details.

=== tch:status
This command shows the current status of tch record (running or not running),
the current status of tch play (running or not running, outstanding uplink
frame count) and the current state of the raw dump mode (enabled or disabled).

=== tch-dl
tch-dl on|off

This command sends a TCH_CONFIG_REQ packet to the target, requesting that TCH
downlink forwarding be enabled or disabled.  You typically don't need to issue
this command explicitly when you use the higher level tch record functionality,
but it is available nonetheless.

=== tgtreset
This command sends a reset/reboot request ETM command packet to the target.

=== unterm
unterm <arbitrary text>

This command sends everything after the unterm command keyword to the AT command
interpreter (ATI) in the target firmware via the FreeCalypso-defined "AT"
RVTMUX channel.  Unlike the more classic str command, strings sent with unterm
are marked as unterminated, meaning that the receiving code in ATI will not
automatically add the usual terminating CR or ^Z at the end, and will instead
wait for a continuation.  This mechanism allows long command or message strings
to be sent in pieces, with the first and any intermediate pieces sent as unterm
and the last piece sent with str, causing the entire string to be acted upon.
This unterm extension to the AT-over-RVTMUX mechanism was added to our Magnetite
and Selenite firmwares in early 2019, allowing this mechanism to be used for
sending and writing SMS in PDU mode, which requires longer strings than the
maximum that can be sent in one piece over RVTMUX.

Any time you send anything to ATI, fc-shell automatically performs the
equivalent of an enable ati command so you can see ATI's responses; any
asynchronous output from ATI is also enabled as a side effect.