LogMan is a logging service and a remote shell running on Symbian phone intended for debugging and development tasks. The service allows one to send messages through a USB serial or socket connection to PC and issue commands such as file deletion, process listing and starting and terminating processes, through the shell.

Other serial connection methods should work also, but are not supported. Infrared(IrComm), for example. On Symbian simulator, the messages are also logged to %TEMP%\epocwind.out by using RDebug logger, but is mainly useful only if one is not able to get socket connection working with simulator.

The software consists of client and server software. Python(PyS60) is supported with python module(pylogman). a graphical user interface is used to start the service and configure the connection(serial\socket).

The management of connection is handled in separate service process to simplify the client and to avoid problems in the debugged software caused by connection problems. The use of client should be as painless as possible. Use of separate process also allows one to debug multiple applications simultaneously without reserving the serial\socket port for a single application.

Why should I use LogMan?

You need to get debug logs from your code on-device

This is the main purpose of the software. There are not many with access to on-device debugger and even then, there are situations when logging is the way to go. But, I see no restrictions to use it for other message sending tasks also.

You don't like file-based logging

If you have been frustrated with on-device debugging by using log files, this is especially for you. You can send the log to PC and write it to file there instead. No need to copy the log from device or play with memory cards.

You need\want real-time logging output or just snappier logging

File logging is quite slow due to hardware constraints. Serial logging through USB is much faster.

You have used some other logging tool, but it does not fulfill your needs

This is all Open-Source, my friends. If there is some feature missing, feel free to add it yourself.

Why use separate service process?

1. Centralized logging management. External tools can be used to configure the logging system, without worrying about correct serial ports and modules when writing your logging code. Except in rare situations like logging during boot when you cannot configure LogMan server manually before use. You can always do it programmatically from your application though.
2. Reducing risks associated with serial connections.
3. Reducing the size of your application.
4. Your code is faster. By using asynchronous sending, logging does not reduce the responsiveness of your applications as much, since you do not have to wait for the log sending to finish.
5. There are not enough serial ports available, if you want to test two or more applications/threads simultaneously. If the serial connection was handled in your application, you could have only 1 reliable connection. The connection can be shared, but I don't know if that is reliable enough. With separate process, I don't have to care.

Using LogMan

How to use LogMan from C++?

There are 2 ways to use the LogMan service.

Use static RLogMan::Log, which creates a temporary RLogMan instance, connects to service, sends log and cleans up. This is a bit slower, but useful for small debugging tasks.

Example:

#include "LogMan.h" //RLogMan
RLogMan::Log(_L("Hello world"));

Create your own instance. To make it easier to remove logging there are a few helper macros available in "logmanutils.h", but I'll show you how it really happens. Check the macros when you are ready to do some serious logging.

Example:

#include "LogMan.h" //RLogMan

// Store this as a member of your class, for example
RLogMan logman;
// Do this in the constructor.
logman.Connect();
// Do some logging.
logman.Write( _L("Hello world") );
// Do this in the destructor. 
logman.Close();

Q: How to format data like with RDebug::Print.

ex. RDebug::Print(L("%d"), 3 );

A: Use logman.Writef(L("%d"), EFalse, 3) or RLogMan::Log( L("%d"), EFalse, 3 )

Q: What is that EFalse there?

A: You can send messages asynchronously by giving a second argument ETrue to the C++ "Log", "Write", or "Writef" and True for Python's "write" method. When using formatting the mode must be defined before the formatted values. See the " logmanutils.h" how to get around this with macros. The message is added to queue in server, the Active Object handling the asynchronous sending is immediately activated, and the client request ends. Thus the client does not wait for the server to send the message.

How to use LogMan from Python?

import pylogman

# This is the static, slower method
pylogman.Log( "Hello world")

# Using instance.
logman = pylogman.LogMan()
logman.Connect()
logman.write( "Hello world" )
logman.close()

Q: Why 'write' and not 'Write' and why 'close' and not 'Close'?

A: Using Symbian naming conventions in C++, but trying to mimic the Python's stdout interface in Python.

How to redirect 'print' to LogMan?

import sys, pylogman
l = pylogman.LogMan()
l.Connect()
# Replace standard output with LogMan's write method.
sys.stdout.write = l.write

print "Hello!" # 'Hello' is sent to PC

This very handy when combined with logging module.

Q: I get Kern-Exec 0 when trying to write.

A: Remember to Connect. This will be changed in the future.

PC-Requirements

Terminal for receiving data from serial connection.

• HyperTerminal( not found from Vista )
• PuTTy
• Enable 'Implicit CR in every LF' from Terminal settings.

Symbian SDK for building + PyS60 SDK for pylogman

You can retrieve the serial port for your device from Device management->Ports after connecting the phone to PC with USB cable.

Support

Only S60 3rd edition and later supported. The server and client should work the same on UIQ, but the C++ GUI won't. Python manager may be used with PyUIQ. The behavior of serial connection on UIQ is unknown.

Installation

Currently there are unsigned test builds mainly intended for using the Shell. I recommend you get the sources and build it yourself though. Due to inconveniences caused by Symbian Signing and you have to modify the capabilities of the client to match your application anyway. This should be no problem for C++ programmer, for Python user, it propably is. You can also modify the capabilities with ensymble tool.

Building

• Map SDK folder to a drive with 'subst'
• Get the sources to the created drive.
• Go to the root of the sources where the bld.inf is located.
• If you don't have PyS60 sdk installed, remove pylogman from the bld.inf
• Using scons-for-symbian
• For emulator type:
• scons
• For device type:
• scons compiler=gcce key='path to key' cert='path to certificate' dosis=true
• And the result is a sisx package ready to be installed.
• Using MMPs
• !! These may not always be up-to-date, but I try to remember to update them!!!
• bldmake bldfiles
• abld build winscw udeb
• Remember to manually copy the python files.
• abld build gcce urel
• Create installation files and sign.
• See 'install' folder for pkg files.

Installing headers

• There is "install_headers.py" script under install folder, which copies the headers to '%EPOCROOT%\epoc32\include\logman'.

Other

I have used COG for generating some code. It is not required to build the software, but it may be useful, if you wish to add new features.