RCAgent - User guide [Work in Progress]

The Setup

I'll use my current setup as an example.

I have the program installed on the SPV M700 (HTC P3600 - HTC Trinity) which is connected directly to the car battery. The connection is via a 3way cigarette lighter adapter with a USB port, so there was no need to modify the smartphone; I simpley used the normal mini-usb cable to keep it permanently connected inside the (back) boot of my car (next to the spare wheel).

I've installed one of the stable and "light" version of a custom rom got from the www.xda-developers.com forum. Once the program was installed and the device is set-up for GPS (GPSID configuration) and data connection, it's ready for commands.

On the other side, I have an Android phone which i use to send sms text commands.
 

Inside RCAgent 

The initial idea was to have multiple "Agents" listening on different services; one agent to monitor and respond to SMS commands, another agent for Email commands, another for Twitter status updates, etc. All of these "Agents" would run simultaneously depending on user preference and settings. All commands are held in a single FIFO (First-in-first-out) queue for later processing.

Due to limitations on the platform and time restrictions, i have only managed to complete the SMS Agent and a "Debug Agent", which is basically a visible interface on the device to simulate SMS commands - The "Debug agent" is switched off when the application is deployed (i.e. on "Release" build).

The application also has what i call "Monitors" which actively monitor the battery level, current location, speed, etc. These monitors can be switched on or off individually and will accept parameters to configure its variables.

It also currently uses GPSID (GPS Intermediate Driver) to retrieve the location from the GPS hardware. The platform needs to be configured to use the correct port, otherwise the program wouldnt receive any data.
There are plans to implement an alternative GPS access method using Serial ports but i was having some problems with the SerialPort class in the emulator while testing. In the meantime GPSID is the preferred method for majority of the cases.

GPS signal and location information sent from the chip is not always accurate due to signal noise so the application has some tolerences set.  In my tests, the speed was also not accurate - e.g it would claim its moving at 2.6knots while it was idle.
The GPS location is deemed to be valid when it meets two conditions; the Horizontal Dilution of Precision (HDOP) is less than 5.0 and there is a minimum of 4 "fixed" satellites.In addition, Internally the application "buffers" some valid locations before acting on the data, depending on the monitor (some capture 10 locations, some 20, etc). I found this to be the best way to ascertain the current location/condition despite some drawbacks.

Currently, most of the settings are saved in the external storage in an XML file. Only the parameters for the monitors are currently saved to this file, the application does NOT switch on the monitors when the program is restarted/rebooted.

All commands are formatted similar to a console based application.
The replies are sent to the original sender -  one instance for each sender. This means multiple alerts can be set for each sender and each sender being able to configure the settings in isolation.
Example: Sender 1 would want to be notified when battery level reaches 40% percent, while Sender 2 may want to be notified when it reaches 20%. Both will be alerted when it reaches the set level.
 

Monitors and alerts

The following monitors are currently implemented:

• Battery Level Monitor (bmon)
  Parameters: switch on/off, Alert level in percentage
  Default: alert level set to 20%

  Alerts the sender when the battery level of the device drops below the alert level. When the device is charged above this level, another message will be sent to indicate this.
   

 

The Remote Commands

"@rc" is the prefix for all SMS commands that will be intercepted by the program. Commands and parameters are separated by spaces and are all in lower case.

• version - Gets the version of the currently running program
  Parameters: None

  Example: @rc version
  Response: Version of the program.
   

• alarm - Sets the volume to high and plays alarm5.wav from the \Windows directory. Volume level is restored after playback.
  Parameters: Repititions (default 3)

  Example:  @rc alarm 4
  Response: N/A. The audio file will be played 4 times.
   

• gp - Get Position - Gets the current location (if available within 5 minutes)
  Parameters: "false" to not apply GPS tolerances (i.e a location will be returned even if HDOP is over 5.0 and satellite count is less than 4).

  Example: @rc gp false
  Response: Current location, even if it's not validated by internal tolerances/rules. Information may be unreliable. 

  Example 2: @rc gp
  Response: Returns a valid location if its available within 5 minutes or a failure message if no valid location is received from the GPS chip. 

  More parameters are planned, to specify length of timeout and the com port number.
   

• callback - Try to call the senders number automatically. This may be useful if you want to hear whatever's going on in the surrounding area.
  Parameters: Phone number

  Example: @rc callback
  Response: N/A. It will try to dial the number that is specified or by default, call the number that sent the command.
   

• reset - Reboot/restart the phone
  Parameters: None

  Example: @rc reset
  Response: N/A. It will force a reboot
   

• exit - Exits out of the program, all monitors switched off.
  Parameters: None

  Example: @rc exit
  Response: N/A. It will switch off all the monitors and exit out of the program.
   

• webupdate - Will download the updater file which will quit the program once an update is available and has been successfully downloaded. Currently, automatic update is only available through this website.
  Parameters: None (yet)

  Example: @rc webupdate
  Response: A text message to indicate whether the updater file was downloaded and executed. Once the updater is active, it will download the latest version of the program and kill the currently running program and restart the new version automatically. Currently, no messages are sent to indicate whether it was able to execute the program. It will, however, add a note in the next response if the app was updated. 
   

• monitors - Batch operation on the monitors. Switch all on/off/reset/status/etc.
  Parameters: on/off/reset/status

  Example: @rc monitors on
  Response: It will respond with the monitors that were loaded and switched on.
  Note: 2 monitors are currently excluded from this list and will not be switched on. Area Monitor and Tracks Monitor will need to switched on manually - this is by design - which i may change in the future. This behaviour can be changed from within the XML settings file (set "OnByDefault" to true). 
   

• msg - Sends a message to the specified number/contact via the device. Will "Echo" by default (message will be sent to the sender).
  Parameters: Recipient phone number, message

  Example: @rc 07800000000 This is a test
  Response: It will send the message "This is a test" to 07800000000
  Note: If the number is omitted, it will be sent back to the sender.
   

• ftpdl - Debug log sent to the set FTP address (currently fixed).
  Parameters: None (yet)

  Example: @rc ftpdl
  Response: A message will be sent back to indicate success or failure
   

• bmon - Battery Monitor settings and status
  Parameters: on/off/status/reset, level

  Example: @rc on 10
  Response: The monitor will be switched and a message indicating that the alert level was set to 10%
   
  Example 2: @rc status
  Response: A message indicating whether the monitor is active and the current alert level
   

• crmon - Call Reboot Monitor settings and status
  Parameters: on/off/status/reset*, phone number, number of rings

  Example: @rc on 07800000000 10
  Response:  The monitor will be switched on and monitor all incoming phone calls. Once a call is received from 07800000000 and rings for 10 seconds, it will force a reboot.
  Note: "status" will send a message back with information about its current settings.
   

• gfmon - Geofence Monitor settings and status
  Parameters: on/off/status/reset*, alert hours (default: whole day)/radius in km, latitude, longitude

  Example: @rc gfmon on 0.5 55.12345 -2.12345
  Response: This will switch on the monitor, set the latitude (55.12345) , longitude (-2.12345) and radius (0.5km or 500 metres) of the virtual "fence". A Message will be sent back to indicate this new information.

  Example 2: @rc gfmon reset
  Response: A message sent back to indicate settings were set to defaults and a new virtual "fence" will be set once a valid location has been determined (with the default radius of 1km).

  Example 3: @rc  gfmon on 21-3
  Response: It will set the alert hours of 9pm to 3am (the following day). Alerts will be generated if they happen between these times. 
   

• gmmon - Geo Movement Monitor settings and status
  Parameters: on/off/status/reset*, alert hours (default: whole day)

  Example: @rc gmmon on 9-17
  Respone: Monitor switched on with alert hours set to 9am to 5pm.
   

• gsmon - Geo Speed Monitor settings and status
  Parameters: on/off/status/reset*, speed limit/level in knots

  Example: @rc gsmon on 60.8
  Response: Monitor switched on, with speed alert set for 60.8 knots (or 70mph).
   

• gamon - Geo Area Monitor Settings and status
  Parameters: on/off/status/reset*, radius in km, latitude, longitude, name/label

  Example: @rc gamon on 0.5 56.12345 -3.12345 Some random location
  Response: A new alert area (with latitude of 56.12345, longitude of -3.12345, radius 50 0metres and the label "Some random location") will be added to the list. When the device enters the area, it will send a message with the area information and the current location (along with the distance) and another message when it leaves the area.
  Note:  "@rc gamon status" switch will send a message back with the list of registered areas.
   

• trackmon - Track Monitor settings and status
  Parameters: on/off/status/reset*, max minutes for log

  Example: @rc on 20
  Response: The monitor will be switched on and will try to capture locations for 20 minutes. The track file (currently KML format) will be saved in the external storage with the current time and date as the filename. The file can be uploaded with the "upsdfile" ("listsd" will list the file names) command below (Warning: it will currently only upload files to this website).  This KML file can be imported into Google Earth to plot the path.
   

• cmd - Special sub-commands - no parameters will return a list of available commands
  • cmd uptime - gets the uptime of the currently running process (RCAgent)
  • cmd deldl - Deletes Debug Log file
  • cmd dloff - Debug Log switched off - no data written to file
  • cmd dlon - Debug Log switched on
  • cmd ction / ctioff - Switches on/off cell tower information in every message
  • cmd listsd - List SD - Lists the files in the root of the storage card and their size - Warning: might be a long list.**
  • cmd ftpsdfile - FTP SD File - Sends the specified file to the set ftp (currently, it will only upload to my ftp)
  • cmd upsdfile - Upload SD File - Uploads the specified file to the set website address (currently, it will only upload to this website)
  • cmd updl - Upload Debug Log - Uploads the Debug Log file to the set website address (currently, a folder on this website)
  • cmd help - A lengthy description of each command.

 

* For all the monitors: "on" and "off" options will switch on/start and off/stop the monitors, respectively. The "Status" option will indicate the current status and settings. and finally, the "Reset" option will set all the settings of the monitor back to its defaults values.

 

** For sanity, long messages are truncated to a maximum of 5 messages (160 characters x 5).