Remote Task Monitor

  A Task Manager for Windows CE and Windows Embedded devices

How it Works

   

Crash Watch

   

Automation

   

FAQs

   

Download

    

Purchase

   

Support

   
Automation

Remote Task Monitor can be programmed through Python scripts. That means you can write scripts for most of the things you would do through the Remote Task Monitor.

Here is an example script that opens a connections to target device, starts capturing snapshots, and prints the CPU and memory usage, then emails the location of the report.



Write your script in Python 3.2, and load the .py file in the Python tab of Remote Task Monitor. Then hit the Run button.




Overview of API

In your Python script, you start by doing "import rtm" and creating the "main()" function. When you press the Run button in the Python tab of Remote Task Monitor, then this "main()" function in your script will get invoked.

Most of the rtm methods are asyncrhronous. What that means is when you call an asyncronous rtm method, it will return immediately. To check the result of your function, you need to call rtm.wait().

Your script runs in the main thread of the Remote Task Monitor program. That is why it is important that you do not do CPU intensive tasks in your script for long continuous period of time.

RTM functions you can call from Python script

rtm.connect(ip, port)

Attempts to connect to the target device.
Returns 0 if argments (ip and port) are not ok, or connection to target device already exists.
Returns 1 otherwise.
If 1 is returned, then call rtm.wait() immediately to check the status.
Note that you must have a TCP/IP connection from the PC where you run Remote Task Monitor to the target device where cemon for WinCE target is running.

rtm.isconnected()

Returns 1 if connected to target, 0 otherwise

rtm.disconnect()

Returns 0 if not connected to target, 1 otherwise.
If 1 is returned, then call rtm.wait() immediately to check the status.

rtm.startcapture()

Returns 1 always. Call this to start getting system snapshots from the target device.

rtm.stopcapture()

Returns 1 always. Call this to stop getting system snapshots from the target device.

rtm.getcaptureinterval()

Returns the interval in milliseconds between successive snapshots. Remote Task Monitor will request.
the target device for a system snapshot every interval.

rtm.setcaptureinterval(milliseconds)

Returns 1 if interval at which Remote Task Monitor will request system snapshot from target device was set properly.

rtm.getsmtp()

Use this to retrieve your email (SMTP server) configuration
Returns a Python object
{
"ip":<IP>,
"port":<Port>
}

rtm.setsmtp(ip, port)

Use this to configure your email (SMTP server) for sending outgoing email messages

rtm.enablepsmemstats(1|0)

Argument can be 1 or 0.
1 will enable you to get memory usage by each process on the target device. You will get the memory usage when you get the system snapshot data from the target device.
0 will disable getting the memory usage data per process.

rtm.saveondev(1|0)

Argument can be 1 or 0.
1 will start recording rtm file on the device. You can later retrieve the rtm file and load it in Remote Task Monitor to analyze CPU usage on the device. This is useful if you cannot maintain a connection to the device through the session.
0 will stop recording rtm file on the device.

rtm.resetdevice()

Returns 1 always.
It will attempt to power cycle the device.

rtm.getnumprocessors()

Returns the number of processors on the target device.

rtm.gettotalmem()

Returns the total memory in bytes on the target device.

rtm.getavailmem()

Returns the free memory in bytes on the target device.

rtm.gettotalcpu()

Returns the total CPU usage as a percentage on the target device.

rtm.restartcemon()

Attempts to restart cemon executable on the target device. If successful, the current session will terminate and you will get disconnected from the target device.

rtm.killps(pid)

Attempts to kill the process with given ID on the target device.

rtm.startps(path)

Attempts to launch the process at given absolute path on the target device.

rtm.cloneps(pid)

Attempts to launch on the target device another instance of the process with the given ID.

rtm.restartps(pid)

Attempts to kill the process with given ID on the target device, then launch it again.

rtm.getnumps()

Returns the number of processes running on the target device.

rtm.getpss()

Returns a Python list of dictionary objects, each object has information about a process:
{
"pid":<Process ID>,
"name":<process name>,
"cpu":<cpu percentage>,
"avg_cpu":<average cpu percentage>,
"max_cpu":<maximum cpu percentage>,
"mem":<memory usage in bytes>,
"numthreads":<number of threads>
}

rtm.getpsids()

Returns a Python list object containing all the IDs of running processes on the target device.
Returns 0 if unsuccessful.

rtm.getpsname(pid)

Returns the process name by its ID.
Returns 0 if unsuccessful.

rtm.getpspath(pid)

Attempts to get the absolute path of the process by its ID.
Returns 0 if unsuccessful, 1 if successful.
Call rtm.wait() to get the path. The wait function will return a Python dictionary object with the "pspath" field set to the path of the process on target device.

rtm.getpscpu(pid)

Returns the CPU usage of process as a percentage by its ID.
Returns 0 if unsuccessful.

rtm.getpsavgcpu(pid)

Returns the average CPU usage of process as a percentage by its ID.
Returns 0 if unsuccessful.

rtm.getpsmaxcpu(pid)

Returns the maximum CPU usage of process as a percentage by its ID.
Returns 0 if unsuccessful.

rtm.addpstoreport(pid)

Collects CPU and memory usage about the process with given process id and includes them in the session report.
Returns 0 if unsuccessful, 1 if successful.

rtm.addthtoreport(pid, tid)

Collects CPU and memory usage about the thread with given process id and thread id, and includes them in the session report.
Returns 0 if unsuccessful, 1 if successful.

rtm.removepsfromreport(pid)

Stops collecting CPU and memory usage about the process with given process id for the session report.
Returns 0 if unsuccessful, 1 if successful.

rtm.removethfromreport(pid, tid)

Stops collecting CPU and memory usage about the thread with given process id and thread id for the session report.
Returns 0 if unsuccessful, 1 if successful.

rtm.getpsmemused(pid)

Returns the memory usage of process in bytes by its ID.
Returns 0 if unsuccessful.

rtm.getpsnumthreads(pid)

Returns the number of threads in the process.
Returns 0 if unsuccessful.

rtm.getthreads(pid)

Returns a Python list of dictionary objects, each object has information about a thread belonging to process with given ID:
{
"tid":<thread ID>,
"name":<thread name>,
"cpu":<cpu percentage>,
"avg_cpu":<average cpu percentage>,
"max_cpu":<maximum cpu percentage>,
"priority":<thread priority>
}
Returns 0 if unsuccessful.

rtm.getthreadids(pid)

Returns a Python list object containing all the IDs of threads in the process whose ID is given.
Returns 0 if unsuccessful.

rtm.getthreadname(pid, tid)

Returns the name of the thread whose process ID and thread ID are given.
Returns 0 if unsuccessful.

rtm.setthreadname(pid, tid, "<thread name>")

Sets the name of the thread whose process ID and thread ID are given.
Returns 0 if unsuccessful.

rtm.getthreadcpu(pid, tid)

Returns the CPU usage of the thread as a percentage whose process ID and thread ID are given.
Returns 0 if unsuccessful.

rtm.getthreadavgcpu(pid, tid)

Returns the average CPU usage of the thread as a percentage whose process ID and thread ID are given.
Returns 0 if unsuccessful.

rtm.getthreadmaxcpu(pid, tid)

Returns the maximum CPU usage of the thread as a percentage whose process ID and thread ID are given.
Returns 0 if unsuccessful.

rtm.getthreadpriority(pid, tid)

Returns the thread priority for the thread whose process ID and thread ID are given.
Returns 0 if unsuccessful.

rtm.setthreadpriority(pid, tid, priority)

Sets the thread priority for the thread whose process ID and thread ID are given.
Returns 0 if unsuccessful.

rtm.crashwatchps(pid, mapfile)

Puts an already running process on a crash watch whose process ID is given.
You can optionally provide path to map file that was generated using Microsoft Visual Studio 2005 when building this process.
If the process crashes, this map file will be used to decode symbols, and give you function names in the call stack.
After putting a process on crash watch, call rtm.wait() to wait for crash notification. The wait function will return a Python dictionary object with "reason":"crashwatchack" if the watch succeeded, or "reason":"crashwatchnack" if the watch failed.

rtm.crashwatchnewps(pspath, mapfile)

Launches a process whose absolute path is given, and puts it on a crash watch.
You can optionally provide path to map file that was generated using Microsoft Visual Studio 2005 when building this process.
If the process crashes, this map file will be used to decode symbols, and give you function names in the call stack.
After putting a process on crash watch, call rtm.wait() to wait for crash notification.

rtm.cpuwatch(more_than_cpu_percent, for_so_many_seconds)

Starts a CPU watch. If any process takes more_than_cpu_percent for_so_many_seconds, then a notification will be triggered.
After starting a CPU watch, call rtm.wait() to wait for the notification.

rtm.cpuwatchcancel()

This cancels a CPU watch if it was started earlier.

rtm.cpuwatchps(pid, more_than_cpu_percent, for_so_many_seconds)

Starts a CPU watch for the process whose ID is given. If the process takes more_than_cpu_percent for_so_many_seconds, then a notification will be triggered.
After starting a CPU watch, call rtm.wait() to wait for the notification.

rtm.cpuwatchpscancel(pid)

This cancels a CPU watch if it was started earlier for the process whose ID is given.

rtm.cpuwatchth(pid, tid, more_than_cpu_percent, for_so_many_seconds)

Starts a CPU watch for the thread whose process ID and thread ID are given. If the thread takes more_than_cpu_percent for_so_many_seconds, then a notification will be triggered.
After starting a CPU watch, call rtm.wait() to wait for the notification.

rtm.cpuwatchthcancel(pid, tid)

This cancels a CPU watch if it was started earlier for the thread whose process ID and thread ID are given.

rtm.memwatch(less_than_bytes, for_so_many_seconds)

This starts a memory watch. If the total available memory is less_than_bytes for_so_many_seconds, then a notification will be triggered.
After starting a memory watch, call rtm.wait() to wait for the notification.

rtm.memwatchcancel()

This cancels a memory watch if it was started earlier.

rtm.email(to, subject, msg)

This sends out an email.
For this to work, you must have first configured your SMTP server and port.

rtm.wait(timeout)

This makes the Python script wait until Remote Task Monitor is ready to give a notification, or the timeout (in milliseconds) is reached.
You should call this function after any asynchronous call you make, like connect, disconnect, getpspath or starting a watch.
If timeout is -1, then the wait will not return until Remote Task Monitor has a notification for your script.

This function can return a notification as one of these Python dictionary objects with the following keys and values:

{"reason":"quit"}
Remote Task Monitor is quiting

{"reason":"timedout"}
rtm.wait() function timed out

{"reason":"disconnected", "report":<path to HTML report file>}
Got disconnected from target device. The "report" is the path to the generated report for the session.

{"reason":"connected"}
Got connected to the target device

{"reason":"pspath", "pspath":<absolute path of the process>}
Got the process path after a call to rtm.getpspath()

{"reason":"gotsnapshot"}
Got a system snapshot of the target device. At this point you can call one or more of the get CPU and memory functions for the processes and theads.

{"reason":"crashwatchack", "pid":pid, "pspath":<absolute path of the process>}
A crash watch was successfully set

{"reason":"crashwatchnack", "pid":pid, "pspath":<absolute path of the process>}
A crash watch could not be set

{"reason":"exception", "pid":<process ID>, "pspath":<absolute path of the process>, "callstack":<call stack as a string>}
The process on crash watch has crashed

{"reason":"memalert", "msg":<an alert message as a string>}
The memory watch has been triggered

{"reason":"totalcpualert", "msg":<an alert message as a string>}
The total CPU watch has been triggered

{"reason":"pscpualert", "pid":<process ID>, "msg":<an alert message as a string>}
The process CPU watch has been triggered

{"reason":"thcpualert", "pid":<process ID>, "tid":<thread ID>, "msg":<an alert message as a string>}
The thread CPU watch has been triggered