Editing SMSCON

Warning: You are not logged in. Your IP address will be recorded in this page's edit history.

Warning: This page is 74 kilobytes long; some browsers may have problems editing pages approaching or longer than 32kb. Please consider breaking the page into smaller sections.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.

Learn more about Contributing to the wiki.

==Preface: Early Development/Release Info==

Info not yet present in regular part of this wiki:
[http://talk.maemo.org/showpost.php?p=1236734&postcount=1213 smscon 0.10.6-1].

Update for 0.9.19++ is in progress for this wiki. In particular section "Usage" still needs updates.

==Introduction==

SMSCON provides complete control of your [[Nokia N900|N900]] by sending SMS commands to it. Other methods are supported as well - we come this is later - but SMS is easiest way and it is the reason why this app is named SMSCON.

Remote controlling your phone is particularly handy in case you cannot find it, for example if it has been lost or even stolen. The first approach to find the phone is giving it a usual phone call awaiting to hear it ringing somewhere in your coat-pocket or the like. If this doesn't help, SMSCON comes into play.
 
SMSCON can't guarantee that you will find your phone again, but it will provide the maximum chance to recover it. If this application ever helps you to recover your phone please tell the story on Maemo.org! The best way is of course to never lose your phone or let it get stolen...

[[SMSCON Editor]] is a GUI helper application to configure and even test SMSCON operation. We recommend normal users of the phone to use [[SMSCON Editor]]. Note that this is a separate application that installs additionally to SMSCOM.

Configuring SMSCON without [[SMSCON Editor]] is possible but you need some experience in unix command line. As almost ever, the command line offers maximum possibilities to adjust the application to your own needs.

'''WARNING:'''
This application can send (multiple) SMS messages automatically (in the background). Be aware that SMS sending is '''not free''' and it's costs depends on the used telephone subscription with your Nokia device. Sending many SMS might be a minor problem for those having a SMS-flat-rate...

=== Where to get more help ===

Please read this wiki first. If you have further questions, suggestions, compliments or bad marks then check the forum
[http://talk.maemo.org/showthread.php?t=60729 SMSCON at talk.maemo.org]. Don't hesitate to post your statement there.

=== How to report bugs ===

Click here to [mailto:schwarz.ware@gmx.de?subject=SMSCON%20BUGREPORT&body=Please%20provide%20the%20following%20information:%0a%0aSMSCON-Version:%0aSMSCON-Editor-Version:%0aProblem%20description:%0aExpected%20result:%0aHow%20to%20reproduce:%0a%0aThank%20you. report a bug] or post them in the [http://talk.maemo.org/showthread.php?t=60729&page=9999 forum].

==Features==

The are a bag full of features offered by SMSCON. Here's an overview:

===General===

* Looking for commands in received SMS messages.
* Asking a remote command server for commands. Details are [[ #Remote command server setup and use | here]].
* Sending notifications, responses and query results by SMS and/or by EMAIL.
* Send help about all currently recognized SMS commands. Details are [[ #List of known sms commands | here]].
* Supports use of multiple SIM cards.
* Detect SIM card change. Details are [[ #SIM card change detection | here]].
* Detect SIM card removal. Details are [[ #SIM card removal detection | here]].
* Optionally turn the phone silent on receiving a known command.
* Stores personal settings encrypted.

===Locating the phone===

* Send notification about current GPS location coordinates via SMS message and/or EMAIL. Those EMAIL have even attached a GoogleMaps picture with your phone's location on it.
* Track the phone's GPS location and location changes by let it automatically send repeated notifications in a selectable time interval.
* Let front camera take pictures and send them via email notification. With a some luck you may see where your phone is or who is using it.
* Send a live front camera video to a different computer on the internet on which is running a video viewer application [available since version 0.9.19].
* Let the phone make a voice call to your controlling phone. Once the call is established you can listen where your phone is.
* Play a pre- and user-defined sound file (only WAV supported). May be used instead of just let the phone ring and let it say a special message.

===Locking and Unlocking===

* Optionally lock the phone on receiving any known command.
* Explicitly lock the phone by command. Nobody can use your locked phone until it receives an unlock command (as long unlock code is unknown, of course).
* Optionally unlock the phone on detection of SIM card change. -- Why unlocking? Well, unlocking makes sense when regular phone owner is more interested on finding the actual device than as keeping its private/sensitive phone data protected/locked. A locked phone prevents even to enter the SIM card PIN. Consequently telephone functions do not work either. This is very secure but makes it almost impossible to contact the phone after booting with unknown SIM card installed. Note that a finder may remove the SD-memory card to read its content.

===Direct control===

* Run directly a pre-defined shell command through SMS message where command output is immediately reported.
* Run a pre-defined (and user-configurable) shell script to start other programs, delete files etc. May be used to wipe out sensitive data from phone. Direct wipe commands are not provided by SMSCON. Writing (and testing) a script doing so is at your own risk.
* Open a (reverse-)SSH connection to your own (home-)server to control the phone at command-line level from your own home (or any other) computer.

===Automatic notifications===

* Detect changing battery charge level and send notification about that.
* Detect keyboard slider movement and send notification about that. Keyboard usage might indicate that somebody has found your phone.

===System===

* Autoloads at boot. This ensures that SMSCON is active (that means is listening for commands) even after device (re)boot. Autoload is enabled by default during installation of a SMSCON package.
* Create and keep a log file on the device. The log file can be queried remotely by SMS command as well as locally via command line or [[SMSCON Editor]].
* Reboot the phone. Albeit this is possible it is not generally recommended if your SIM card has a PIN: If nobody enters the PIN correctly, the phone would boot but could not connect to GPRS network.
* Shutdown the phone. Also just possible but not generally recommended.
* Stop & restart SMSCON activity by SMS command. On trouble, this might be preferred operation instead of rebooting the phone.
* Send notifications if SMSCON crashes on activity. Should this ever happen, you're encouraged to forward them to the SMSCON developer team ([[#How_to_report_bugs |make a bug report]]).

==Installation==

Always install the latest stable version on your phone; previous version can have bugs and have less functionality!

===Where to get from===

The latest stable versions are available in the [[Extras]] repository and can be installed simply using the phones Application Manager (HAM). Therefore, in HAM ensure [[Extras]] repository is enabled then open the "ALL" category and search for "smscon".

Alternatively the packages can be found here: [http://maemo.org/downloads/product/Maemo5/smscon/ SMSCON] and there: [http://maemo.org/downloads/product/Maemo5/smscon-editor/ SMSCON Editor].

If you are willing to try unstable versions and help testing the application, consider to install packages from here: [http://maemo.org/packages/view/smscon/ SMSCON Releases] and there: [http://maemo.org/packages/view/smscon-editor/ SMSCON Editor Releases]. Be warned.

===Incompatibilities===

Read this section to find out applications known to be not perfectly compatible with SMSCON operation:

* The [[http://wiki.maemo.org/Mms fMMS]]: application (send and receive MMS) may cause use of wrong 3G connection. '''Problem''': The MMS related connection usually does allow access to internet in general. '''Solution''': Don't have a MMS related GRPS access point defined (those that fMMS would use). '''Reason''': The phone, if in automatic connection search, may select the wrong 3G connection even if SMSCON is '''not''' installed. So this is not really a SMSCON issue. The solution for proper SMSCON operation is to have only one GPRS/3G APN defined. The pure installation of fMMS is no harm while no additional APN is configured.

===Installation details===

On very first installation, SMSCON generates

* a default settings file with all the user settings of SMSCON.
* an IMSI database to store IMSI numbers of SIM cards allowed. Other SIM cards will cause detection of SIM card change and optionally unlock of the device on boot.
* a default <code>smscon_script</code> file with example code for COM_CUSTOM command.
* a default <code>alarm.wav</code> file for COM_ALARM command.
* a SMSCON logfile.
* a <code>smscon</code> command for use on unix command line.

On installation of update versions (since 0.9.*) , SMSCON

* updates the settings file to disable obsolete settings.
* updates the settings file to add new settings.
* leaves IMSI database untouched.
* leaves <code>smscon_script</code> file untouched.
* leaves <code>alarm.wav</code> file untouched.
* tries to repair previous SMSCON installation. 
* adds entries to SMSCON logfile.
* updates the <code>smscon</code> command.

===Before using SMSCON the first time===

It is highly recommended to review all user settings and adjust them to your needs. Since this is a lot for the first time, there are a few important things for you to setup (no must but recommended):
* All the [[#Email_settings | Email settings]] to enable SMSCON to send EMAIL notifications.
* Personalized [[#Prefix.2Fsuffix_for_all_SMS_command_strings | SMS command code prefix and/or suffix]].
* The so-called [[#SMS_command_source | master number]].
* Last not least, [[#Set_the_phone.27s_lock.2Funlock_code | Set the phones lock code]]. This is not a SMSCON setting but a N900 device setting.

We recommend use of [[SMSCON Editor]] to review and change settings. Alternatively open Xterm and use [[#Configuration |the <code>smscon</code> command]] on unix command line. Do not use both methods at the same time: keep [[SMSCON Editor]] closed while you operate smscon on the command line. Otherwise results are unpredictable.

====Set the master number====

The '''master number''' is a phone number, namely the phone number of the main controlling phone. It ''can'' but '''should not''' be number of your N900 being controlled - this would be nonsense. It can also be left empty if you don't want to use the functionality that master-number offers. Best choice is to use the number of a second phone in your phone-portfolio. The number of your boy- or girlfriend's phone also does. No matter if that is a N900 as well.

'''Controlling your N900 is not restricted to the master number's phone.''' Any phone in the world can be used to send controlling SMS to your N900 and SMSCON sends SMS responses to it. One role of master numbers's phone is to receive a blind copy of all SMS that SMSCON sends to other phones.

Another role of master number comes into play if you start to control your N900 using different methods than SMS. We come to that later.

Further, the master number receives a notification if the password for [[SMSCON Editor]] got changed.

Last not least, the master number serves as a kind of password for some functions. This is also the case if you leave the master number empty. Then the password is just the empty password.

Here is how to set the master number:

* A typo-aware way to set the master number to a particular phone's number is using [[SMSCON Editor]] version 0.9.8 or higher and it goes like this:

# Open [[SMSCON Editor]], ensure daemon runs, quit [[SMSCON Editor]].
# From the particular phone, send a command to your N900. The default SMS message text for COM_CHECK is just <code>Check</code> (note upper/lower case letters!).
# Wait until your N900 received that SMS.
# Again open [[SMSCON Editor]] go to "General" settings page.
# Enter the "last sender" number exactly as shown in the "master number" field above.
# Close "General" settings page and quit [[SMSCON Editor]]

* Set master number directly:
** Open [[SMSCON Editor]] go to "General" settings page, fill in "master number" field. Leave the field empty if you don't want to use master-number features.
** Alternativly, on unix command line do this:
  $ smscon -set MASTERNUMBER +xxyyyyyyyyyy     # or
  $ smscon -set MASTERNUMBER "" # no master number

====Set the phone's lock/unlock code====

The N900 has a standard device locking function which on the phone can be configured at 888 --> Phone settings --> Miscellaneous Settings --> Device lock.

This lock has two settings: (1) Autolock and (2) Lock code. The lock state itself goes locked when (1) the phone is idle and Autolock is enabled or (2) if explicitly locked by user via Main-on/off-Button --> Lock Device.

With SMSCON the lock state can also be controlled remotely by SMS commands.

Fortunately (from users point of view) the N900 device locking function has a feature that prevents a user from accidentally lock out himself: Unless the lock code was explicitly set once in the Device Lock settings, the phone will not lock until the lock code was entered; this means you need the code to even lock the phone. Locking can be canceled at this time! Unfortunately (from SMSCON point of view) this is also true if locking was requested by a SMSCON command.

Obviously locking via SMSCON command makes sense only if the the phone goes locked immediately without asking the current user for a code before.

In order to achieve this, '''each user of SMSCON is encouraged to at least once set an explicit device lock code on his/her phone'''. No matter if the code you choose is the same as the default code 12345 (which re-use is of course not recommended) and no matter if Autolock is enabled or not.

===Phone number format===

All phone numbers should be entered with country prefix. Not only ensures this that SMS are send successfully regardless where your phone actually is located. It further is essential to make phone numbers comparable.

Prevent common mistake: If you receive the same SMSCON reply messages twice on a controlling phone, then check and ensure the MASTERNUMBER you've defined starts with international country prefix.

===After installation===

SMSCON installes to autoload at boot, this can be disabled with the command-line command <code>smscon -unboot</code> and re-enabled by <code>smscon -boot</code> or with [[SMSCON Editor]].

After you made initial settings start SMSCON activity like this:
<pre>
Nokia-N900:~$ smscon -start
INFO: Daemon smscon_daemon requested to start.
INFO: Daemon smscon_daemon started [PID=17137].
</pre>

This starts a background daemon which
* loads the configured user settings file
* stores your current IMSI code in the IMSI code database
* waits for commands until stopped or phone shutdown.

When later a new SIM card is inserted the new IMSI code is verified with the code in the stored in IMSI database. This is how the "SIM card change" will be detected.

==Configuration==

Prior to use SMSCON you have to configure it. Do this by assigning various settings a value. Settings have an internal name, such as MASTERNUMBER. Most settings have useful default values. But some need to be set to personalized values.

To keep your privacy, SMSCON stores personal settings encrypted in the config file. Note that this is not bullet proof to the maximum extend. Experienced hackers are able to decrypt that.

Following is a categorized list of all currently known settings with their internal names and a short description. To get and set the current value of a user setting enter these the commands:
<pre>
$ smscon -get NAMEOFSETTING "default value" # query a setting
$ smscon -set NAMEOFSETTING "the new value" # assign new value
</pre>
If querying a setting that is not known or not set, the default value is displayed. An attempt to assign an invalid value is denied.

===SMS command source===
* 'SENDERNUMBER': SMS number of recent controller. Receives SMS notifications. This setting is automatically updated each time SMSCON receives a known command via SMS message.
* 'MASTERNUMBER': SMS number of master controller (encrypted). This setting is never automatically updated by SMSCON except on upgrading from older version to 0.9.x where it is set to the currently stored SENDERNUMBER.

===List of known sms commands===

These settings define text to trigger the corresponding command. You're encouraged to set them to words which are easy to remember in your language. The text may be set to the empty string which completely disables the command. It's not allowed to set two commands to the same text (except empty string).

A SMS message actually sent must consist of the command text prefixed/suffixed with text defined by SMS_COMPREFIX/SMS_COMSUFFIX settings respectively.

* 'COM_CHECK': Command to ask for help. You may forget all other commands but should keep this and the prefix/suffix in mind.
* 'COM_REBOOT': Command to reboot the phone.
* 'COM_POWEROFF': Command to shutdown the phone.
* 'COM_POWER': Command to ask for phone battery status and many other status information.
* 'COM_LOCATION': Command to ask current GPS location.
* 'COM_REMOTEON': Command to start outgoing ssh connection.
* 'COM_REMOTEOFF': Command to stop outgoing ssh connection.
* 'COM_CAMERA': Command to take a picture or a live video from front camera [video since 0.9.19]. The front camera is used because it has no cover that may be closed.
* 'COM_CALL': Command to start an outgoing call.
* 'COM_LOCK': Command to lock the phone.
* 'COM_UNLOCK': Command to unlock the phone.
* 'COM_TRACKON': Command to start GPS tracking.
* 'COM_TRACKOFF': Command to stop GPS tracking.
* 'COM_CUSTOM': Command to run a predefined [[#Files intended to be edited by user directly | user script]]. The script runs asynchronously until it terminates itself. Version 0.9.18 supports definition of command text that accepts one or more arbitrary text parts. This parts are extracted and passed to the user script. This indirectly adds support for multiple, unlimited number of user scripts. See [[#Variable text parts in command definitions | below]] for details.
* 'COM_CUSTOMLOG': Command to ask for output of last COM_CUSTOM command.
* 'COM_SHELL': The command text must be a unix shell command. It is directly passed to a unix shell for execution. In contrast to COM_CUSTOM, the COM_SHELL command does not execute in background and its output is immediately returned as notification SMS and/or EMAIL. Due to synchronous execution, you should not call commands that run for unpredictable long time (like pure ping). Version 0.9.18 supports the definition of command text that accepts one or more arbitrary text parts. This allows to modify the shell command on a per sms-basis. See [[#Variable text parts in command definitions | below]] for details.
* 'COM_ALARM': Command to play once a predefined [[#Files intended to be edited by user directly | sound file]]. Alarm duration depends on sound file content; there is no command to stop playing the alarm sound.
* 'COM_RESTART': Command to restart the daemon.
* 'COM_LOG': Command to ask for application log.

====Variable text parts in command definitions====

The COM_CUSTOM and COM_SHELL commands allow to define one or more arbitrary text parts. Each of these parts is simply written as a * character (star). Each * is a placeholder for zero or any number of characters as long there is a match with the sms message. In the command definition, the stars of two placeholders must not be consecutive. They must be delimited by at least one (or more) different character. Otherwise it would be completely impossible to say which placeholder covers how many chars of the incoming message.

Should there still be two (or more) consecutive stars in the command definition (like ** or ***), they act as '''one''' placeholder even though. The difference to a single star is, that ** defines an ''optional'' placeholder: All placeholders from the first (leftmost) ** up to the last (rightmost, no matter if this is a * or **) are optional. If they are omitted in the sms-message, their delimiting characters must also be omitted.

Usually the character used to delimit two placeholder can't be part of a placeholders value and there is no way to escape a character from being used as a delimiter. Should this ever become a problem, consider to define a COM_CUSTOM command using one placeholder only and parse the string in the user script.

'''Restriction''': In commands via CHECKHOST it is (currently) not possible to specify values for placeholders. In this case parameter values will be the stars from the command definition.

Examples:
<pre>
 If COM_CUSTOM = mycmd(*/*/*)
 then message mycmd(there/are 3/arguments)
 calls smscon_script with 3 parameters: "there" "are 3" "arguments"

message    mycmd(watch / the / blanks! )
 calls smscon_script with 3 parameters: "watch " " the " " blanks! "

message    mycmd(more/2/3/4/parameters)
 calls smscon_script with 3 parameters: "more" "2" "3/4/parameters"

message    mycmd(less/parameters)
 is not recognized (no match for 2nd /)

If COM_CUSTOM = mycmd(**/*/*)
 then message    mycmd(less/parameters)
 calls smscon_script with 3 parameters: "less" "parameters" ""

message    mycmd(less/)
 calls smscon_script with 3 parameters: "less" "" ""

message    mycmd(less)
 calls smscon_script with 3 parameters: "less" "" ""

message    mycmd()
 calls smscon_script with 3 parameters: "" "" ""

message mycmd(**/*/*)
 calls smscon_script with 3 parameters: "**" "*" "*"
</pre>

You may also use commas or any other chars or combination of chars, even blanks to delimit placeholders:
<pre>
 If COM_CUSTOM = P1=*, P2=**, P3=*
 then message P1=micky, P2=mouse
 calls smscon_script with 3 parameters: "micky" "mouse" ""

message    P1=micky, P2=mouse, P3
 calls smscon_script with 3 parameters: "micky" "mouse, P3" ""

message    P1=micky, P2=mouse, P3=
 calls smscon_script with 3 parameters: "micky" "mouse" ""

message    P1=micky,P2=nope
 is not recognized (no match for blank behind comma)

</pre>

For COM_SHELL the assignment of message chars to placeholders is not important. Placeholder just indicate variable parts of the message here. The unix command being executed consist of the complete message anyway (after message prefix/suffix was stripped away).

====An example user script for COM_CUSTOM====

The smscon_script below demonstrates how to manage multiple user scripts. It is an example that may serve as a basis for your own dispatching script. Note that it does not depend on how COM_CUSTOM is actually defined (unless it has at least 3 placeholders):
<pre>
#!/bin/sh
# @abstract A smscon_script that uses new COM_CUSTOM command features.
# @see SMSCON application, N900, Nokia
# @author yablacky <schwarz.ware@gmx.de>, 2012-05-12
# A smscon_script example that makes use of new COM_CUSTOM command features.
# They allow to define placeholder in the sms-command that accept arbitrary
# text. This text is extracted placeholder by placeholder and is passed to
# this script as positional parameters $1, $2, ...
# This example script checks the first parameter and performs different actions.
trim() { local -; set -f; echo $1; }
CMD=$(trim "${1:-default}")
test $# -gt 0 && shift
echo "Processing '$CMD' from $SMSCON_SENDERNUMBER via $SMSCON_COMMANDORIGIN on $(date)"
case "$CMD" in
""|"*"|"default")
	# A common case getting here is when COM_CUSTOM command is detected by CHECKHOST
	# because (currently) CHECKHOST is not able to specify parameters. 
	echo Process list on $(date):
	ps
	echo netstat:
	netstat -tean
	;;
ps)	ps
	;;
netstat)
	netstat -tean
	;;
smsconset)
	# Set SMSCON settings remotely!
	smscon -set "$@"
	;;
usercmd)
	# Execute any command which is given in remaining parameters.
	# *************************************************************************
	# WARNING: THIS IS VERY POWERFUL BUT IT IS FINALLY A BACKDOOR TO THE DEVICE.
	# *************************************************************************
	# To limit possible desaster, create and change to a temporary directory
	# and execute the command in the context of user rather than root:
	D=/tmp/smscon_script
	test -d "$D" || mkdir "$D" || test -d "$D" || exit
	chmod 777 "$D"
	cd "$D"
	echo Executing: "$*"
	echo "$*" | su user
	cd ..
	rm -fr "$D"
	;;
purge-the-phone)
	# Call a script that removes all private data from the phone.
	# May be called if phone is lost without chance to get it back.
	remove_sensible_private_data.sh "$@"
	;;
do-something-else)
	do_something_else.sh "$@"
	;;
*)
	echo "Unknown command '$CMD'"
	;;
esac

</pre>

====A powerful but dangerous example for COM_SHELL====

Since version 0.9.18 it is possible to define the command text for COM_SHELL as
 sh -c "*"
'''SECURITY NOTE''': Don't do that if you haven't any shadow of what this means. For those who know and are crazy enough to do, it offers amazing possibilities to control the phone via SMS. You should have SMS_COMPREFIX and SMS_COMSUFFIX defined to some reasonable long text.

'''ECONOMY NOTE''': The COM_SHELL command immediately replies by sending SMS messages containing the command output. Be careful with long-time-running commands and/or hugh-output-producing commands.

====COM_CAMERA: How to select picture or video====

The COM_CAMERA command activates the front camera for taking a single picture or a live video stream [video since version 0.9.19]. Once started, a live video stream is continuously sent until explicitly stopped by another COM_CAMERA command. A picture requires only one command per picture.

To select picture or video, the COM_CAMERA command does now accept up to 3 parameters. To specify them in a SMS, you have to define the COM_CAMERA command on your phone to contain at least three (recommended optional) [[ #Variable text parts in command definitions | placeholders]]. The corresponding parameter's meaning is as follows:

$1: Select picture or live stream (case insensitive):
     (empty), P, PIC or IMG: Take single shot image and send it by mail as usual.
     off, 0 or - (minus): Turn live stream off.
     (any other value): Turn live stream on with parameters $2 and $3 as follows: 
 $2: If live stream on: Hostname or IP where to send the live stream to.
 $3: If live stream on: Port number where the given host is listening (default 5000).

Previously COM_CAMERA commands work as before and will take a picture (unless you've defined it containing a * already). You have to change your COM_CAMERA definition to enable live videos. For example,you may set it to

Camera**,*:*

Then SMSCON would accept the following SMS messages (prefix/suffix omitted for simplification):

Camera                           --> request to take a picture
 CameraPIC                        --> ditto
 CameraVID,your-computer.com:4321 --> request to start video being sent to
                                      host your-computer.com on port 4321
 CameraON,your-computer.com:4321  --> ditto
 Camera1,your-computer.com:4321   --> ditto (the 1 behind Camera is a 'one')
 Camera1,your-computer.com        --> ditto, but uses default port 5000
 Camera0,your-computer.com        --> request to stop video (the 0 behind Camera is a 'zero')
 Camera0                          --> ditto
 CameraOFF                        --> ditto

On a successful camera activation (picture as well as video) SMSCON sends a notification email. For pictures, this email has attached the picture taken.

For video is attached a viewer application that can be started to receive and watch the live stream. The viewer application is designed to run on linux systems for now. It requires the gstreamer application which is free. And you need, of course, run the viewer on the host that you specified in the preceding COM_CAMERA command. The usage of viewer application is:

usage: live-viewer.sh [--help] [port-number]
  --help              This help.
  port-number         Port on this host where to listen for incoming
                      live stream. Default port number is 5000.

If the video receiving computer is in a LAN behind a (DSL-)router (and the phone isn't) then you need to configure the router to forward the port for the UDP protocol.

By design SMSCON does not support a pre-configured video receiving host. It must be specified in each COM_CAMERA command explicitly. This gives you a wide range of possible computers where to watch the video.

SMSCON is not able to deliver picture and live video at the same time. A picture request also terminates a running live video (and does not restart it). Surprisingly SMSCON stop/start/restart does not terminate a live video. Reboot does.

'''Beware of network traffic caused by live video!''' If the phone is currently connected via WLAN then the traffic is about 40 kB/second. If a 2G or 3G connection is detected then a smaller image is sent which causes about 10 kB/second. The frame rate is about 15 fps in any case.

===Prefix/suffix for all SMS command strings===
* 'SMS_COMPREFIX': Prefix that must be present before all COM_XXX commands [even COM_SHELL] (encrypted).
* 'SMS_COMSUFFIX': Suffix that must be present behind all COM_XXX commands [even COM_SHELL] (encrypted).

These two settings play the role of passwords to protect your phone from being controlled via SMS by someone else than you. Would you leave all the command codes to their default and prefix and suffix is also empty, then I could shutdown your phone if only I have your number.

Instead of explicitly define all your SMS control commands (COM_xxx) to start with a unique prefix and/or suffix, you simply define a prefix and/or suffix that is implicitly used. If you have very cryptic codes defined you may leave "SMS_COMPREFIX" and/or "SMS_COMSUFFIX" empty. But advantage of using "SMS_COMPREFIX" and "SMS_COMSUFFIX" is:
# Prefix and suffix can be changed easily while embedded COM_xxx codes remain unchanged.
# Prefix and suffix apply to COM_SHELL command as well.

Example for COM_SHELL: With the configuration set to:
 COM_SHELL=uptime
 SMS_COMPREFIX=aaa.
 SMS_COMSUFFIX=.bbb
The recognized SMS command message to execute the shell command "uptime" is:
<code>aaa.uptime.bbb</code>

Note for upgraders: In versions before 0.9.x the command message for COM_SHELL was differently.

===Remote command server===
* 'ENABLECHECKHOST': Enable checking URL for commands.
* 'CHECKHOST': The URL to check (encoded).
* 'CHECKTIME': Minutes between URL checks.

===Email settings===
* 'EMAILADDRESS': Recipient of EMAIL notifications (regular owner of this phone, please contact him!).
* 'USER': SMTP username for EMAILFROM (encrypted).
* 'PASSWORD': SMTP password for EMAILFROM (encrypted).
* 'EMAILFROM': Sender address of EMAIL notification (encrypted).
* 'MAILSERVER': SMTP server hostname or IP (encrypted).
* 'MAILPORT': SMTP server port number.

===SSH settings===
* 'REMOTEHOST': ssh server hostname or IP [to build tunnel] (encrypted).
* 'REMOTEPORT': ssh server port number [to build tunnel].
* 'REMOTEUSER': ssh server username [to build tunnel] (encrypted).
* 'REMOTEPASSWORD': ssh server password [to build tunnel] (encrypted).
* 'REMOTELISTENIP': ssh server IP address [entry of tunnel itself] that will be forwarded to phone (*|localhost|IP).
* 'REMOTELISTENPORT': ssh server port number [entry of tunnel itself] that will be forwarded to phone.
* 'REMOTE2LOCALPORT': Local port number to be forwarded to [exit of tunnel itself] on the phone.

If you want to use the SSH connection feature (COM_REMOTEON and COM_REMOTEOFF commands), you also need a fixed IP address (or a dyndns.org domain name) on your preconfigured remote server for the SSH (default port 22) connection.

===Notification settings===
* 'COMMANDREPLY': Send notification if command accepted (yes|no).
* 'MESSAGESEND': How to send notifications (sms|email|both|none).
* 'ENABLERESEND': On failure try to re-send reply message (yes|no).
* 'RESENDTIME': Minutes between message re-send tries.
* 'RESENDMAXTRY': Maximum number of message re-send tries (0=no limit).
* 'SMS_PARTS_LIMIT': SMS notification produces no more than this number of single SMS (0=no limit).
* 'LOG_TIMEFORMAT': Format to use for timestamps (see strftime).

===GPS settings===
* 'GPSSEND': How to send GPS notifications (sms|email|both). Read further to understand good reasons to report GPS notifications differently then others (of which sending is defined by MESSAGESEND).
* 'GPSTIMEOUT': Seconds until give up acquiring GPS coordinates. Timeout counting restarts after each successfully received coordinate. In order to give the GPS subsystem a chance to download the complete almanac from satellites this could be a reasonable high value. E.g. 600 seconds (5 minutes) or even more.
* 'GPSINTERVAL': Seconds between GPS coordinate acquisitions. Applies to COM_TRACKON and COM_LOCATION commands.
* 'GPSPOLLING': Minimum number of GPS coordinate acquisitions for COM_LOCATION's ''best accuracy of''.
* 'GPSMAXDEVIATION': Meters of minimum accuracy of a GPS coordinate for COM_LOCATION request.

On a '''COM_LOCATION''' command the phone acquires a series of GPS coordinates and reports the best one of them. At least GPSPOLLING coordinates are acquired for no longer than GPSPOLLING x GPSINTERVAL seconds. The timeout is utilized only so far the best coordinate's accuracy exceeds GPSMAXDEVIATION.

On a '''COM_TRACKON''' command the phone repeatedly acquires GPS coordinates and reports them in an almost GPSINTERVAL seconds interval. GPSPOLLING and GPSMAXDEVIATION play no role for COM_TRACKON mode. Repeated reports might be a lot stuff and it could be really expensive if GPSSEND includes sending via SMS. Consider to set GPSSEND accordingly.

A COM_TRACKON command - after a reasonable while - should be followed by a COM_TRACKOFF or COM_LOCATION command to stop the phone from sending further notifications. Otherwise the battery runs out of breath too fast. (To be precise, COM_SHUTDOWN or COM_RESTART also stop things but are obviously not recommended for this purpose).

===Miscellaneous settings===
* 'SILENCEDEVICE': Set phone silent before executing command (yes|no).
* 'AUTODEVICELOCK': Lock phone before executing any command except un/lock (yes|no). This saves you from sending explicit COM_LOCK commands and may be used in conjunction with SIMUNLOCK setting enabled. The scenario is as follows: A finder/thief replaces the SIM card and reboots. SMSCON detects SIM change, unlocks (if locked et all) then connects to GPRS (of new SIM) and sends you a SIM-change notification. As you receive that, you know the new number of your phone. To prevent finder/thief from operating your phone you may immediately send COM_LOCK or - with AUTODEVICELOCK enabled - even any other command to take control of your phone. 
* 'SIMUNLOCK': Automatically unlock phone when new SIM is inserted (yes|no).

===Sensor detections===
* 'KEYBOARDDETECT': Send notification if keyboard is sliding (yes|no).
* 'AUTOBATREPORT': Send notification on battery discharge (yes|no).

==The SMSCON log==

All user action and activity of <code>smscon_daemon</code> will be logged. To query the log file use [[SMSCON Editor]] or enter a <code>smscon -log</code> command like this:

<pre>
Nokia-N900:~$ smscon -log
2012-01-15 00:16:34[SMSCON] INFO: Daemon smscon_daemon requested to start.
2012-01-15 00:16:35[SMSCON] INFO: Daemon smscon_daemon started [PID=17137].
2012-01-15 00:16:35[DAEMON] CRITICAL: smscon_daemon is starting.
2012-01-15 00:16:35[DAEMON] INFO: Successfully loaded "/opt/smscon/smscon_config" file.
2012-01-15 00:16:36[DAEMON] INFO: Found 1 IMSI code(s) in "/opt/smscon/smscon_code" file.
2012-01-15 00:16:36[DAEMON] INFO: Authorized IMSI code found.
2012-01-15 00:16:36[DAEMON] INFO: Phone battery charge is 45%, charging.
2012-01-15 00:16:36[DAEMON] INFO: Preferred GPS query interval is 20 sec.
2012-01-15 00:16:36[DAEMON] INFO: Keyboard slider change detection is off.
2012-01-15 00:16:36[DAEMON] INFO: Battery status change detection is off.
2012-01-15 00:16:36[DAEMON] INFO: (CHECKHOST) After 0 errors since 2012-01-14 23:16:35 GMT: Successfully read remote file.
2012-01-15 00:16:36[DAEMON] INFO: (CHECKHOST) smscon_daemon is deactivated (00) by remote host file.
2012-01-15 00:16:36[DAEMON] INFO: (CHECKHOST) Checkhost is on. Checking each 30.0 minutes.
2012-01-15 00:16:36[DAEMON] INFO: smscon auto-loads at boot. OK.
</pre>

By default <code>smscon -log</code> outputs the log information in a way that privacy data is somehow anonymous. But no guarantee! To view the log containing all data "as is" you need to provide the master number as a password like this:

<pre>
Nokia-N900:~$ smscon -pw "+4912345678901" -log
</pre>
Where the value behind <code>-pw</code> option is your master number.

When having trouble with SMSCON always check the log! Note that the log file itself (<code>smscon.log</code>) is not readable by normal users. You need to use the <code>smscon -log</code> command or use [[SMSCON Editor]] to display it (or be a super user ...).

==Usage==
 
This section explains how to operate in case you need to control your phone remotely. You need at least one of this:
* the ability to send SMS to your phone, or
* access to the remote command server your phone is polling.

To send SMS any phone does. '''Security note''': From a foreign phone, remember to remove all SMS you sent from that phones SMS-sent-history. Otherwise someone else may send them later again. If you're lucky to hold your N900 in hands again, then defining different command prefix/suffix asap is a recommended alternative or additional security option.

Won't miss to say: For using a remote command server, SMSCON and the command server must be setup and configured accordingly ''before'' you lost your phone.

No matter if SMSCON is triggered by a SMS message or by remote command server, it will first and optionally reply an acknowledge message and then execute the command in the background.

Commands usually generate a reponse that SMSCON sends as an SMS-reply, EMAIL, both (SMS and EMAIL) or not et all. If SMS replies are enabled, they go to the phone that sent the command and to the master number if one is defined (only once if both numbers are the same). If the command comes from remote command server and SMS replies are enabled, they go to the master number if one is defined.

===Commands===
The (default) predefined SMS commands are: 
<pre>
Nokia-N900:~$ smscon -sms
COM_ALARM = Alarm /* NEW IN 0.8.1 */
COM_CALL = Call
COM_CAMERA = Camera
COM_CHECK = Help
COM_CUSTOM = Script
COM_CUSTOMLOG = Script.log /* NEW IN 0.9.x */
COM_LOCATION = Location
COM_LOCK = Lock
COM_LOG = Log /* NEW IN 0.9.x */
COM_POWER = Power
COM_POWEROFF = Poweroff
COM_REBOOT = Reboot
COM_REMOTEOFF = Remoteoff
COM_REMOTEON = Remoteon
COM_RESTART = Restart /* NEW IN 0.8.1 */
COM_SHELL = uptime /* CHANGE: Better no i/o redirection since 0.9.x */
COM_TRACKOFF = Trackoff
COM_TRACKON = Trackon
COM_UNLOCK = Unlock
</pre>

These commands can be changed using [[SMSCON Editor]] or in Xterm at the unix command-line with the <code>smscon -set </code> command (see [[#SMSCON command line options | SMSCON command line options]]). Set them to words in your language or something cryptic where only you know what it means, might be a good idea.

For now assume above definitions and empty SMS prefix/suffix (SMS_COMPREFIX and SMS_COMSUFFIX settings). Then when you send a SMS message to the phone which is exactly:

* 'Check' it replies by sending one or more SMS messages back to you with all the available SMSCON commands.
* 'Reboot' will reboot your phone. 
* 'Poweroff' will shutdown your phone.
* 'Location' will send the phone's current position by SMS or EMAIL (or both). 
* 'Remoteon' will enable the SSH connection to your (home-)server.
* 'Remoteoff' will terminate the SSH connection. 
* 'Camera' will take a front camera picture an send it by email.
* 'Call' will issue an outgoing call to you.
* 'Lock' will lock the device, so nobody can use your phone.
* 'Unlock' will remove the device lock.
* 'Trackon' will continuously send SMS or email (or both) with GPS location of the device.
* 'Trackoff' will disable sending GPS locations.
* 'Script' will run a predefined [[#Files intended to be edited by user directly | user shell script]].
* 'uptime' will execute the shell 'uptime' command on your phone and returns the output.
* 'Alarm' will play once a [[#Files intended to be edited by user directly | user defined sound]].
* 'Restart' will stop and start again the smscon_daemon.

===Remote command server setup and use===

To use this functionality you need a file that is accessible via internet and you must be able to change the content of that file somehow. A private or company homepage that allows you to serve a small extra file in some inconsiderable subdirectory might be all you need.

Find out the URL to retrieve the file and test the URL in a web-browser. Then setup SMSCON to query your remote command server as follows:

smscon -set CHECKHOST "http://my-homepage.example.com/privat/phone/control.txt"
 smscon -set CHECKTIME 15                   # minutes
 smscon -set ENABLECHECKHOST yes

Once done, you can trigger any SMS commands by changing the content of the control.txt file (the file referred to by above URL which is an example only).

The file only must contain one of the following codes from 00, 01 to 19 or -1:

<pre>
-1 = COM_RESTART (behaves exactly like 17 since version 0.9.14 )
00 = no command
01 = COM_CHECK
02 = COM_REBOOT
03 = COM_POWEROFF
04 = COM_POWER
05 = COM_LOCATION
06 = COM_REMOTEON
07 = COM_REMOTEOFF
08 = COM_CAMERA
09 = COM_CALL
10 = COM_LOCK
11 = COM_UNLOCK
12 = COM_TRACKON
13 = COM_TRACKOFF
14 = COM_CUSTOM
15 = COM_SHELL
16 = COM_ALARM
17 = COM_RESTART
18 = COM_CUSTOMLOG
19 = COM_LOG
</pre>
This two character code must be contained in the first two characters of the file. Further data is simply ignored but may be transferred with each query. So better keep the file small.

Note that it currently is not possible to specify values for placeholders that may be defined in a sms command (e.g. COM_CAMERA command etc).

SMSCON checks the content of the file and executes the corresponding command if the content '''changed''' since last check. This prevents repeated command execution. On the other hand, to give the same command again explicitly, you have to switch to a "no comand" in between, which has code 00. Don't change the command codes too early. Wait for at least CHECKTIME minutes.

If the phone has problems when reading the file from your server via the http protocol (or the protocol you set), then check the log for ''CHECKHOST'' errors.

The default CHECKTIME is 15 minutes but can be changed via CHECKTIME setting. Note that after giving a command via remote command server, it can take up to CHECKTIME minutes to detect and execute the command.

===SIM card change detection===

The first time an unknown SIM is detected, SMSCON will send a notification. It contains the new SIM card's phone number, IMSI code & telecom operator name. This scenario happens if your phone's finder or thief replaces your SIM by his/hers own SIM card.

An unknown SIM is then entered to the SIM card database and will no longer generate a SIM card change notification.

===SIM card removal detection===

[since version 0.9.19] Each time the phone boots without a SIM card inserted, SMSCON tries to send an email notification (SMS is not possible without SIM). Email might work if the phone has somehow connected to an already known WLAN. The send retry option applies.

If email could be sent without SIM, there is a chance to control the phone at least via remote command server.

'''Note:''' On device boot it is possible to simply skip the SIM-card PIN-code question. To SMSCON this appears the same as SIM card removal. Consequently the email subject sent is "No or skipped SIM".

'''Hint:''' Some user complained about being notified that they use their N900 albeit they use it without SIM in a home WLAN. Well, its not a bug, its a feature. Previously SMSCON versions throw away all possibilities being controlled by terminating itself. Should you use your phone this way and don't want any notifications et all, then do the same thing and stop SMSCON explicitly.

===Example config file===

Shown is an example config file as stored in <code>smscon_config</code>. This is presented for the gentle user only. Normal users never need to see nor edit this directly. Please use smscon command line or SMSCON Editor to edit settings.

<pre>
# smscon user settings (initially written by version 0.9.16)

# smscon configuration file written by:
@APPVERSION      = '0.9.17'

# Send notification on battery discharge (yes|no):
AUTOBATREPORT    = 'no'

# Lock phone before executing any command except un/lock (yes|no):
AUTODEVICELOCK   = 'no'

# The URL to check (encoded):
CHECKHOST        = 'olbwLcsXidpecUsoyn63PzlmI6FcWazAIQzrVsS0qE1CuD0='

# Minutes between URL checks:
CHECKTIME        = '15.0'

# Send notification if command accepted (yes|no):
COMMANDREPLY     = 'no'

# Command to play predefined alarm.wav:
COM_ALARM        = 'Alarm'

# Command to start an outgoing call:
COM_CALL         = 'Call'

# Command to take picture:
COM_CAMERA       = 'Camera'

# Command to ask for help:
COM_CHECK        = 'Check'

# Command to run predefined user script:
COM_CUSTOM       = 'Script'

# Command to ask for user script output:
COM_CUSTOMLOG    = 'Script.log'

# Command to ask current GPS location:
COM_LOCATION     = 'Location'

# Command to lock the phone:
COM_LOCK         = 'Lock'

# Command to ask for application log (encrypted):
COM_LOG          = 'mCJtpl2x/hOmXJvthib0PZe0pA=='

# Command to ask for phone battery status:
COM_POWER        = 'Power'

# Command to shutdown the phone:
COM_POWEROFF     = 'Poweroff'

# Command to reboot the phone:
COM_REBOOT       = 'Reboot'

# Command to stop outgoing ssh connection:
COM_REMOTEOFF    = 'Remoteoff'

# Command to start outgoing ssh connection:
COM_REMOTEON     = 'Remoteon'

# Command to restart the daemon:
COM_RESTART      = 'Restart'

# Command to execute that shell command. Returns output as notification:
COM_SHELL        = 'uptime'

# Command to stop GPS tracking:
COM_TRACKOFF     = 'Trackoff'

# Command to start GPS tracking:
COM_TRACKON      = 'Trackon'

# Command to unlock the phone (encrypted):
COM_UNLOCK       = '5hIkR2JXO5Rh/DKvujfWs3Ixsg=='

# A csv with debugging options (for development use only)
DEBUGFLAGS       = ''

# Recipient of EMAIL notifications (regular owner of this phone, please contact him!):
EMAILADDRESS     = 'to@example.com'

# Sender address of EMAIL notification (encrypted):
EMAILFROM        = 'KgJG37AvcSCzgc+fNB1BbtyMpPHrQadT5gqkM5/zM9bSywc='

# Enable checking URL for commands:
ENABLECHECKHOST  = 'no'

# On failure try to re-send reply message (yes|no):
ENABLERESEND     = 'no'

# Seconds between GPS coordinate acquisitions for COM_TRACKON and COM_LOCATION:
GPSINTERVAL      = 10

# Meters of minimum accuracy of a GPS coordinate for COM_LOCATION request:
GPSMAXDEVIATION  = 50

# Number of minimum GPS coordinate acquisitions for COM_LOCATIONs best of:
GPSPOLLING       = 8

# How to send GPS notifications (sms|email|both):
GPSSEND          = 'sms'

# Seconds until give up acquiring GPS coordinates:
GPSTIMEOUT       = 1800

# Send notification if keyboard is sliding (yes|no):
KEYBOARDDETECT   = 'no'

# Format to use for timestamps (see strftime):
LOG_TIMEFORMAT   = '%Y-%m-%d %H:%M:%S'

# SMTP server port number:
MAILPORT         = 25

# SMTP server hostname or IP (encrypted):
MAILSERVER       = 'R15CnDU7WEzfK0KXN92XMRY1AvHrQadT5gqkM5/zM9bSywc='

# How to send notifications (sms|email|both|none):
MESSAGESEND      = 'sms'

# SMTP password for EMAILFROM (encrypted):
PASSWORD         = '9pfb8B3RUW0HzfsoCPC9ybIkOw=='

# Local port number to be forwarded to [exit of tunnel itself] on the phone:
REMOTE2LOCALPORT = 22

# ssh server hostname or IP [to build tunnel] (encrypted):
REMOTEHOST       = 'mqoUsM3+9k3n5VD+xNYSpTM5WQ1T+fy7Qek0+9iEtxxVjHg='

# ssh server IP address [entry of tunnel itself] that will be forwarded to phone (*|localhost|IP):
REMOTELISTENIP   = 'thMYuBGLYAoSYzwNIGmZtbB6iw=='

# ssh server port number [entry of tunnel itself] that will be forwarded to phone:
REMOTELISTENPORT = 'Fu7Jok9QmKAQNW4D364fISC97A=='

# ssh server password [to build tunnel] (encrypted):
REMOTEPASSWORD   = 'zoaD1+tPV/rjchz5kH49YvTLzA=='

# ssh server port number [to build tunnel]:
REMOTEPORT       = 22

# ssh server username [to build tunnel] (encrypted):
REMOTEUSER       = 'YIRJIwUpcrLjk5NMreAbcxG6tA=='

# Maximum number of message re-send tries (0=no limit):
RESENDMAXTRY     = 10

# Minutes between message re-send tries:
RESENDTIME       = '15.0'

# SMS number of recent controller. Receives SMS notifications:
SENDERNUMBER     = '+0000000000'

# Set phone silent before executing command (yes|no):
SILENCEDEVICE    = 'no'

# Automatically unlock phone when new SIM is inserted (yes|no):
SIMUNLOCK        = 'no'

# Prefix that must be present before all COM_XXX commands [even COM_SHELL] (encrypted):
SMS_COMPREFIX    = 'lCrge4igqhEBwf79LjQemKXTFA=='

# Suffix that must be present behind all COM_XXX commands [even COM_SHELL] (encrypted):
SMS_COMSUFFIX    = 'MQyE8gLfhntAx0LmedKshcfEuA=='

# A SMS notification produces no more than this number of single SMS (0=no limit):
SMS_PARTS_LIMIT  = 10

# SMTP username for EMAILFROM (encrypted):
USER             = 'h90Sc0FT1T+ktlwqlUHyP3nW1Q=='

# SMS number of master controller (encrypted):
MASTERNUMBER     = 'CLS61ljsGhXGsZAMN58l8II96w=='

</pre>

===SMSCON command line options===
The basically available command-line options for SMSCON are as follows. There are more options e.g. to export and import all settings via command line. They are not shown here; should you ever need to use them, use <code>-help2</code> option for help.
 
<pre>
Nokia-N900:~$ smscon -help
== smscon 0.9.13 - Nokia N900 remote control utility ==
usage: smscon [Options]...
 Options:
 -start : Start smscon_daemon
 -restart : Stop & restart smscon_daemon
 -stop : Stop smscon_daemon
 -status : Get smscon_daemon status
 -log : Show log file. Anonymized if no or wrong -pw option seen before.
 -del log : Delete log file
 -sms : Show SMS commands
 -set name "value" : Set user setting (name = "value")
 -config : Show config file
 -script : Show script file
 -scriptlog : Show script.log file
 -del scriptlog : Delete script.log file
 -boot : Enable smscon_daemon to start at phone boot
 -unboot : Disable smscon_daemon to start at phone boot
 -add imsi : Add IMSI code of current SIM to code file
 -remove imsi : Remove IMSI code of current SIM from code file
 -pw password : Password to enable non-anonymized output. MASTERNUMBER is password.
 -version : Show version number
 -help : This help menu
 -help2 : More help (special options, rarely used).
</pre>

===Remote SSH connection===

If SMSCON receives a COM_REMOTEON command (default command code 'Remoteon') it starts a ssh-server on the phone which tries to connect the host defined by REMOTEHOST setting, the "server side" (your own server). Values of REMOTEUSER and REMOTEPASSWORD settings are used to authenticate when contacting REMOTEHOST. This connection is (the reverse) part of the SSH connection tunnel being built.

Once this (reverse-)SSH connection is made you can from the server side (=REMOTEHOST) connect to your Nokia device with the following shell command:

<pre>
ssh -p 8080 localhost -l root
</pre>

The hostname (''localhost'' in this example) was defined by the REMOTELISTENIP setting. The hostname ''localhost'' has special meaning, namely that you have to be logged in at your own server already when giving the above command.

The port number (''8080'' in this example) is a port number on REMOTEHOST and was defined by the REMOTELISTENPORT setting.

Above command contacts your phone at port 22 (or what ever port is defined by REMOTE2LOCALPORT setting). On the phone at this port the ssh-server is listening for incoming 'please open the door at the end of the tunnel' requests.

When you start making experiences with remote SSH connection you should leave all settings to their default, except REMOTEHOST, REMOTEUSER and REMOTEPASSWORD which must suit your own server name, user account on that server and its password.

On top of that, the remote SSH connection is even more powerful: If configured accordingly, it allows to contact the phone not only when you are logged in at REMOTEHOST. It supports connecting the phone from any (or particular) hosts in the internet as long as they are able to contact REMOTEHOST. In this case REMOTEHOST forwards  traffic to/from to the phone. Details on how to do this will follow.

==Files==

This section is a description of what you get when installing SMSCON. This is not a must-read when getting in touch with SMSCON for the first time.

If not otherwise stated, the location of all files mentioned in this section is <code>/opt/smscon</code>.

SMSCON is a command line application whose executables parts are mainly:
* <code>smscon</code>, the command-line control part and
* <code>smscon_daemon</code> the daemon part, running in the background.

SMSCON is highly configurable and all the settings are stored in the <code>smscon_config</code> file. Many settings are stored encrypted, so - from version 0.9.3 on - do not edit the file directly. See below for how to change settings.

===Files intended to be edited by user directly===

* <code>smscon_script</code>, a unix shell script to extend SMSCON functionality. This script is intended to be edited by the gentle user. The installation of SMSCON provides a file with some non-destructive example code. SMSCON executes the script in the background with root-rights when receiving a COM_CUSTOM command. You need to be root to change <code>smscon_script</code>.

* <code>alarm.wav</code>, a WAV-format sound file. SMSCON plays the sound when receiving a COM_ALARM command. A special sound file (suitable to all languages) is provided by default. You're encuraged to replace it by your own sound. Write it to <code>/opt/smscon/alarm.wav</code>. '''Note:''' currently only WAV sound is supported by SMSCON.

===Files used internally===

None of these files are intended to be viewed or even edited by a user directly. So don't do it. Use SMSCON commands to view and change them in a consistent way:

* application program files and libraries
* several log files
* internal configuration files
* temporary files to hold camera pictures, google maps etc.
* last not least, there are some internal files not stored in <code>/opt/smscon</code>.

Names of internal files are not mentioned here by design. They are matter to change without notice as is the existence of this files itself.

===Files from other packages===

The installation of SMSCON via application manager ("HAM") usually installs other software packages implicitly. They are also de-installed on SMSCON's de-installation (via HAM) in case they are no longer referenced otherwise.

Besides '''python2.5''' this is:
<pre>
python-crypto 
python-gobject
python-location
python-dbus
pexpect
gstreamer-tools 
openssh-client
openssh-server
alsa-utils /* NEEDED IN >= 0.8.1 */
</pre>

As said above, regular use of SMSCON does not require knowledge of files nor packages used.

==(More or less) Frequently Asked Questions==

* Q: I don't have a 2g connection. Can the email functionality send via 3G rather than try and connect to gprs? A: That should be no problem. smscon does not handle 2G and 3G connections differently. It you have internet connection et all it's no matter whether it is 3G or 2G. Some telecom networks support both and the phone is even switching between both types every now and then without affecting smscon operation.
* Q: Is there a "stolen mode"? A: No, nothing special. Smscon makes use of the N900's standard device lock function and may
** explicitly lock/unlock the phone on receiving a command or
** automatically on detecting some events.

== Versions ==

More information about each available version is [http://maemo.org/packages/view/smscon/ here].

=== 0.9.19-1 (Current [[Extras-devel]]) ===

'''Changelog'''
 FIX: Fix poor image quality on COM_CAMERA command. SMSCON now uses ambient light sensor to select proper exposure and gain values for camera.

FIX: Fix leaving temp files on smsmcon installation/upgrade.

ADD/CHANGE: SMSCON now keeps running rather than terminating itself if it does not detect a SIM card. This offers a litte chance that the phone connects to the internet via wlan which in turn allows to use CHECKHOST to control the phone. Note: If user skips the SIM code question on device boot, the phone treats this the same as if no SIM is present. SMSCON makes no difference. Now SMSCON makes an attempt to send a notification via email if no SIM was detected.

ADD: The COM_CAMERA command does now accept up to 3 parameters. To use them a user has to define the COM_CAMERA command on his phone to contain at least three (recommended optional) placeholders (a placeholder is written as ** or * char). More details see SMSCON wiki.

=== 0.9.18-1 ([[Extras-testing]]) ===

'''Changelog'''
 ADDED: The SMS to trigger COM_CUSTOM and COM_SHELL commands may now contain arbitrary text which is passed to the script or shell as parameters. This allows for support of multiple custom scripts.
 ADDED: Some environment variables are now setup before executing COM_CUSTOM and COM_SHELL commands:
   ${SMSCON_COMMANDORIGIN} contains info of command origin [SMS, CHECKHOST, CMDLINE]
   ${SMSCON_SENDERNUMBER} contains current sendernumber
   ${SMSCON_MASTERNUMBER} contains masternumber
  MINOR CHANGES: Fixed some typos; Superfluous script file name removed from feedback message.

=== 0.9.17-1 (Current [[Extras]]) ===

'''Changelog'''
 FIX: Notification SMS were sent twice some times due to a too short timeout value. Now a longer timeout will hopefuly fix that.

=== 0.9.16-1 ===

'''Changelog'''
 FIX: Fixed some typos.
 FIX: On some N900 devices the gps location test does not proceed until another test was started. This is fixed now.
 FIX: A GPS Error is now reported rather than it potentially aborts the SMSCON daemon.

=== 0.9.15-1 ===

'''Changelog'''
 FIX: The COM_LOCATION (and COM_TRACKON) command fail if accuracy of a received GPS coord is "not a number".
 FIX: Several issues if GSP device is also used by different application at the same time (GPSJinni, OVI maps, ...) are fixed.
 FIX: Fix behaviour if COM_LOCATION/COM_TRACKON commands are received while the other one is active. Now the mode is just switched.
 CHANGE: The COM_LOCATION command now takes even more than GPSPOLLING samples if best accuracy is above 50 meters and timeout (which is GPSINTERVAL * GPSPOLLING) is not reached yet. The tolerance (50) is configurable via new GPSMAXDEVIATION setting.
 ADD: New setting GPSMAXDEVIATION: Meters of minimim accuracy of a GPS coordinate for COM_LOCATION request. Default is 50 meters.

=== 0.9.14-1 ===

'''Changelog'''
 FIX: Remove double log message on received command.
 FIX: If alarm command changes profile for playing sound, it was not restored after alarm. Now it is restored.
 FIX: No longer treat CHECKHOST commands -1 and 17 differently. They behave the same now and will restart the smscon daemon exactly once (like only -1 did before).
 FIX: Fix missing application homepage URL in package description.
 FIX: On GPS location request, dismiss the very first GPS location delivered by GPS receiver because this sometimes seems to be the last fix from a long-time-ago somewhere-else location.
 ADD: Introduce a 'DEBUGFLAGS' setting to enable/disable generation of debug information in the log (for developer use only).

=== 0.9.12-1 ===

'''Changelog'''
 FIX: Issues on reading smscon settings of older versions and/or invalid settings. <yablacky>
 * Invalid settings now generate a warning on start but are left unchanged and will show up in the editor fields.
 * If user does not change them, they again will generate error messages when editor pages are closed.
 CHANGE: Restructure and modification of text in the General window (minor).
 FIX: Allow characters in the "Listen IP" field; "*" and "localhost" are valid inputs.

=== 0.9.11-2 ===

'''Changelog'''
 FIX: Fixed repeated resending of sms or email in almost zero-time intervals in case resend-time interval was configured to less than 1 minute.
 ADD: Anonymized log files. Can be used to post logs in bug reports etc. Works like this: Logfile shown by command "smscon -log" is now anonymized by default (phone numbers, host names, IP-addresses)
   IMPORTANT NOTE(1): Anonymizing takes place with ABSOLUTELY NO guarantee!
   IMPORTANT NOTE(2): It is NOT A BUG if there is too much or "wrong" anonymizing. If new option "-pw password" was seen on command line before -log, then logfile is shown un-anonymized as before. And of course a super user has not limits anyway.
 CHANGE: Logfile is no longer readable by normal user.
 FIX(MINOR): Fixed typos and added more comments.

=== 0.9.10-1===

'''Changelog'''
 FIX: If called in user mode, prevent -export or -export! option to create/write files that user has no permissin to create or write.
 FIX: Fix crash: TypeError: can only concatenate tuple (not "list") to tuple

=== 0.9.9-1===

'''Changelog'''
 CHANGE: Deamon does no longer need to restart for switching between test mode and normal operation mode.
 FIX: Daemon now reads test command requests from a named pipe and works them off sequentially (allows to quickly start several tests in a short time).
 FIX: Fixed that COM_REMOTEOFF command did not work.
 FIX: Fixed daemon crash ("need more than 3 values to unpack")
 FIX (AGAIN): Force using busybox ps-command to ensure that process information like PID is at expected place.

=== 0.9.8-1===

'''Changelog'''	
 FIX: Fixed problems with daemon process ids on devices with extended "ps" command installed. This bug might prevent power users from using smscon. So this fix is reason for early release of new version.
 FIX: Fixed interchanged message parameters in smscon -init! command output.
 ADD: Added usage hints to initial smscon_script file (minor change).

===0.9.7-1===

'''Changelog'''	
 FIX: Send battery status notification if charge is below 10% AND discharging (not OR discharning). If devices can't tell change/discharge status; discharge is assumed.
 FIX: Don't check for bootloader if in test mode.
 FIX: Wrong error message that daemon did not start on devices with extended "ps" command installed.

===0.9.3-1===

'''Changelog'''

REFACTURING:
           * Extracted common code to a library (smsconlib.py) which is now used by smscon_daemon, smscon control program and smscon-editor.
           * Added a lot of code comments.
           * Encapsulated many code into classes. E.g. the complete encyption stuff is now transparent to smscon control program and smsmcon editor.
           * Restructured code, written new and renamed a lot of old stuff.
           * Moved code from files "smscon" and "smscon_daemon" to pure python-modules (smscon_master.py and smscon_service.py respectively). The original files are now just jackets calling main() in associated python module. This allows to compile the modules and hiding source code.
  NEW:    Encryption now uses salt (formerly encrypted data can be read).
  FIX:    Encryption does no longer fail on text ending with curly open brace.
  NEW:    "MASTERNUMBER" concept: A SMS number stored in the config file that  does NOT change due to SMS commands like "SENDERNUMBER" does. Each SMS is send to both (only once if they are the same numbers, of course). SMS replies to commands which are not introduced by SMS (e.g. via CHECKHOST) are sent to the MASTERNUMBER only. On upgrading, the default MASTERNUMBER is set to the current SENDERNUMBER.
  NEW:    "COM_CUSTOMLOG" command: A SMS command to retreive the output of the last "COM_CUSTOM" command. Will be sent via email only - would send too much SMS...
  NEW:    "COM_LOG" command: A SMS command to retreive the smscon.log file. Will be sent via email only - would send too much SMS...
  NEW:    The output of "COM_SHELL" SMS command is now sent as a command reply. You may have to remove output redirections from your shell command to get non-empty reply.
  NEW:    "SMS_PARTS_LIMIT": A number to limit the number of single SMS that would otherwise be generated to send a too long SMS message. Zero means no limit.
  NEW:    "LOG_TIMEFORMAT": Format to be used in time stamps of SMS and EMAIL messages.
  NEW:    "SMS_COMPREFIX" and "SMS_COMSUFFIX": Instead of explicitly define all your SMS control commands (COM_xxx) to start with a unique prefix and/or suffix, you might now separately define a prefix and/or suffix that is implicitely used. While "SMS_COMPREFIX" and "SMS_COMSUFFIX" are empty, all your commands do as in older versions. Advantage of using "SMS_COMPREFIX" and "SMS_COMSUFFIX":
           * Prefix and suffix can be changed easyly while embedded COM_xxx remain unchanged.
           * Prefix and suffix apply to COM_SHELL command as well. Example:
               With the configuration set to:
                   COM_SHELL=uptime
                   SMS_COMPREFIX=aaa.
                   SMS_COMSUFFIX=.bbb
               The recognized SMS command to execute the shell command "uptime" is:
                   aaa.uptime.bbb
  FIX:    It is no longer possible to define two SMS commands as the same string except the empty string, which means to disable that command being given via SMS.
  FIX:    SMS command recognition is no longer restricted to ASCII characters. The complete GSM 7 bit default alphabet may be used now (but not unicode). This gives you a greather variete of chars to use for your SMS commands.
  NEW:    The config file will now upgrade automagically from any previous version. New options are set to their default, obsolete options are commented out.
  NEW:    New function to export and import settings to/from arbitrary file. (see smscon -export and -import options). smscon editor makes now use of this functions to retrieve a and deploy editable configuration.
  NEW:    The smscon_daemon does no longer need to be restarted explicitly if smscon changes a setting. The daemon detects changes automagically and will read and apply the new configuration automatically.
  NEW:    The smscon_daemon now maintains a "last known good" configuration and uses that as a fallback in case the "official" configuration of smscon can't properly loaded by the daemon.
  NEW:    Camera picture and GSP Location requests do no longer force unconditional switching to GPRS network connection. The current connection will be used if the internet is reachable. Should a GPRS connection be required to reach internet, the GPRS connection is established but the previous network is re-activated after picture and/or location has been replied.
  NEW:    A LOGGER is now used wherever possible. So the smscon.log file becomes really interesting.
  NEW:    The "CHECKHOST" URL is now extended by "?LASTMCD=nn&CHECKTIME=minutes" which will allow the URL being a script that may use this information.
  CHANGE: "CHECKHOST" now works more clear as follows: While polling for commands, a command is executed once, if it differs from the last polled command. The last polled command is initialized to "-1" on daemon start. Code "-1" is "restart daemon" and this obviously is what happened on daemon start. Code "17" (COM_RESTART) is deprecated as a CHECKHOST command. Since it is different from "-1" it may restart the daemon repeatedly. Use code "-1" to restart the daemon via CHECKHOST instead. Of course, before a change to code "-1" is recognized by the daemon, you must have give it a different command code. If in doubt use "01" (COM_CHECK) because it gives you feedback that the command has been seen.
  CHANGE: "CHECKTIME" may now be a float to specify fractional parts of a minute: 0.25 is 15 seconds.  
  NEW:    The "CHECKHOST" URL may now have a protocol prefix and it may be different from "http://". If the URL has no protocol prefix, then "http://" is supplied as default as in former versions (e.g. your config file remains valid in this point as well).
  NEW:    The battery status is logged before a command is about to be executed.
  NEW:    "REMOTELISTENIP", "REMOTELISTENPORT" and "REMOTE2LOCALPORT": These settings give you greather flexibility of setting up a tunnel to remote control your phone via a reverse ssh-connection: Use "REMOTELISTENIP" and "REMOTELISTENPORT" to define the tunnel entry maintained by the remote ssh-server (which must be setup to allow setting LISTENIP and PORT this way). "REMOTELISTENPORT" defaults to 8080 and "REMOTELISTENIP" defaults to "localhost" as in former versions. With these defaults you must be logged in at the ssh-server to start a remote control connection of your phone. While setting up "REMOTELISTENIP" you may even control the phone from somewhere else (in which case the ssh-server act as a proxy or relay). On the tunnel exit side, which is on your phone, the "REMOTE2LOCALPORT" is the port number where your phone's ssh-daemon is listening (usually 22).
  CHANGE: The "smscon -devconfig" command now requires a password to show the uncrypted configuration. The MASTERNUMBER is the password.
  NEW:    "RESENDMAXTRY": This option defines the maximum number of message re-send tries. Applies to SMS and EMAIL as well. (0=no limit) On configuration upgrade this is initialized to 10.
  NEW:    smscon now has a -sendsms option to send SMS immediately. Despite being a nice feature by itself, it makes smscon editor independent from smssend program which requires an extra package.
  NEW:    smscon now allows all options to start with the usual double dash as well.

===Versions 0.8, 0.7, 0.6, 0.5 & 0.4===

Please don't use these anymore. Update to 0.9 or higher.

==Future development ideas==

Feel free to add requests below.

* Add a provision for SMS reception without the UI being notified so that SMSCON control is silent. INFO: Remote command server (CHECKHOST) already offers silent control.
* <del>Saving all <code>smscon_config</code> user variables in gconf database. No need for <code>smscon_config</code> file anymore.</del> (WONT IMPLEMENT)
* <del>Add setting for user's country mobile number prefix.</del> (WONT IMPLEMENT: There is only one place where to specify the prefix anyway; namely the MASTERNUMBER)
* <del>Add setting for alternative number (where alternative is a number sent a command and does not match the default) and </del>option to choose where reply should be send, i.e. default number, alternative or both. <del>Default number should not be replaced.</del> (PARTLY IMPLEMENTED: Since 0.9.x there is a MASTERNUMBER concept. This is a default number that is never replaced.)
* Add setting to choose the default internet connection (WLAN, GPRS, or ANY).
* When the "Camera" command is sent, the process should wait for keyboard action to capture a picture and send the mail. In that way, there will be more chances to get better face portrait of the "new" user.
* <del>Add the ability to run more than one custom command.</del> (IMPLEMENTED SINCE 0.9.18).
* <del>Application must be included in the ROM itself so that it cannot be removed.</del> (CAN'T BE IMPLEMENTED)
* <del>Add a password so that no one else but the legitimate user can send an SMS to the phone and see where the phone is.</del> (IMPLEMENTED since 0.9.x: The SMS_COMPREFIX/SMS_COMSUFFIX settings supply the desired password functionality) 
* Auto remove the received SMS from conversations.
* Disable PhoneSpeakerSwitch on receipt of 'call' command.
* <del>EmailCON: check an specified email inbox, reading it with the program itself and not the built in default mail prog, at a given frequency, paying attention to commands written in the subject and/or body, accepting all the commands that are accepted via SMS.</del> (WONT IMPLEMENT)
* <del>Improve handling of front camera to reduce the odds of crappy or plain blank black pictures being taken.</del> (CAN'T BE IMPLEMENTED)
* When in "stolen" mode, replace the front cam "recording" LED pattern with a on-lighting pattern for stealthiness. (NOTE: The is no 'stolen mode')
* Email, or post online somewhere you choose, any new photography taken with the main camera, geotagging whenever possible, preferably without showing any signs it's happening (if possible with an option to re-dimension the picture before sending).
* There should be an option to send email as text or as multipart html and text. (WHAT'S THE BENEFIT? TEND TO SAY WON'T IMPLEMENT)
* For encryption of user settings secret code key could be based on device serial number (no more predefined key in script); this enhances security.

==Testers needed==
 
Please test this software, I like to hear if it works for you or not. Please post on forum. I only can test the software with two Vodafone SIM cards from The Netherlands, I want to know if it also works with other cards and networks in other countries...

Watch [http://maemo.org/packages/repository/list/fremantle_extras-testing_free_armel/ Packages in QA testing queue] if SMSCON and/or SMSCON Editor is present there. You're encouraged to test and tell your positive or negative feedback there (thumbs up or down). Thereby following the rules of [http://wiki.maemo.org/Extras-testing#Quality_Assurance_criteria Quality Assurance criteria].

Should you find bugs, here's [[#How_to_report_bugs | how to report bugs]].

==License==
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published
by the Free Software Foundation; version 2 only.

==Disclaimer==
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

==Wiki access history==

Some statistics... Updated every now and then.

This page has been accessed 33,640 times. --[[User:yablacky|yablacky]] 00:42, 24 January 2012 (UTC) 
This page has been accessed 33,870 times. --[[User:yablacky|yablacky]] 09:04, 27 January 2012 (UTC) 
This page has been accessed 34,654 times. --[[User:yablacky|yablacky]] 08:43, 4 February 2012 (UTC) 
This page has been accessed 35,120 times. --[[User:yablacky|yablacky]] 07:46, 8 February 2012 (UTC) 
This page has been accessed 36,505 times. --[[User:yablacky|yablacky]] 21:33, 22 February 2012 (UTC) 
This page has been accessed 37,061 times. --[[User:yablacky|yablacky]] 23:26, 28 February 2012 (UTC) 
This page has been accessed 38,145 times. --[[User:yablacky|yablacky]] 08:01, 11 March 2012 (UTC) 
This page has been accessed 39,024 times. --[[User:yablacky|yablacky]] 08:51, 18 March 2012 (UTC) 
This page has been accessed 41,132 times. --[[User:yablacky|yablacky]] 00:57, 13 April 2012 (UTC) 
This page has been accessed 42,375 times. --[[User:yablacky|yablacky]] 15:30, 28 April 2012 (UTC) 
This page has been accessed 43,315 times. --[[User:yablacky|yablacky]] 00:14, 13 May 2012 (UTC) 
This page has been accessed 43,675 times. --[[User:yablacky|yablacky]] 06:51, 16 May 2012 (UTC) wow, 10,000 :)) 
This page has been accessed 44,554 times. --[[User:yablacky|yablacky]] 02:45, 23 May 2012 (UTC) 
This page has been accessed 44,921 times. --[[User:yablacky|yablacky]] 21:33, 24 May 2012 (UTC) 
This page has been accessed 48,809 times. --[[User:yablacky|yablacky]] 21:19, 8 June 2012 (UTC) 
This page has been accessed 55,671 times. --[[User:yablacky|yablacky]] 16:21, 13 July 2012 (UTC) 22,000!! 
This page has been accessed 77,263 times. --[[User:yablacky|yablacky]] 16:37, 20 May 2013 (UTC) 
[[Category:Software]]
[[Category:N900]]

Please note that all contributions to maemo.org wiki may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see maemo.org wiki:Copyrights for details). Do not submit copyrighted work without permission!

Summary:

Cancel | Editing help (opens in new window)

Retrieved from "https://wiki.maemo.org/SMSCON"

@@ Line 219: / Line 219: @@
 These settings define text to trigger the corresponding command. You're encouraged to set them to words which are easy to remember in your language. The text may be set to the empty string which completely disables the command. It's not allowed to set two commands to the same text (except empty string).
-A SMS message actually sent must consist of the command text prefixed/suffixed with text defined by [[#Prefix.2Fsuffix_for_all_SMS_command_strings | SMS_COMPREFIX/SMS_COMSUFFIX]] settings respectively.
+A SMS message actually sent must consist of the command text prefixed/suffixed with text defined by SMS_COMPREFIX/SMS_COMSUFFIX settings respectively.
 * 'COM_CHECK': Command to ask for help.<br/>You may forget all other commands but should keep this and the prefix/suffix in mind.

Personal tools

Navigation

Views

Editing SMSCON