PySOS is a Python module that connects to a SOS server to provide low-level access to the messaging system of the network. With PySOS you can easily send/receive messages to/from any node on the network. This can be done either through the interactive Python shell or through a Python script.

PySOS is part of our BehaviorScope Studio software suite, utilized in the BehaviorScope project.

Installation

First, download the attached file and untar it, with "tar -zxvf pysos.tar.gz". Then install the PySOS module by running the following commands:

$ cd pysos
$ python setup.py install 

Now you should be able import the PySOS module from the Python prompt. Hence, to test whether everything went well:

$ python
>>> import pysos
>>>

You should see no error messages.

PySOS Control Center (GUI)

Installation

First, cd into the pysos folder that was unzipped during the installation. Then:

$ cd pysoscc
$ ./pysoscc.py

The GUI should pop up. If you get an error, make sure you have PyGTK installed. To utilize the database features, you'll also need the MySQLdb module.

Screenshots

Here are some annotated screenshots. Click them to expand.

Note that PySOS Control Center is installed with PySOS's setup.py and so it can be easily extended to include your own GUI enhancements, by simply importing the pysoscc module and subclassing the pysoscc class.

The screenshots above were taken under Linux, but the GUI should also work in Windows and OS X.

Tips for Windows:

• Use native Python, not Cygwin Python. The modules used in the GUI (such as PyGTK) are easier to install under native Python. Besides, if Python is in your path, Cygwin will be able to see it.
• If you do not want a terminal to automatically open when you click on a .py file, rename the file to .pyw.

PySOS manual

The following is copied/pasted from the PySOS help text:

PySOS version 1.6 - August 13, 2007 
Authors: Thiago Teixeira and Neeraj Singh.

This module allows you to connect to a SOS server on any host
and port, as well as send and receive SOS messages.


INITIALIZATION:
===============
Make sure you are running the SOS server, then create a new instance:

>>> import pysos
>>> srv = pysos.sossrv()    # you may enter host=... and port=... here
>>>                         # localhost and 7915 are default

SENDING MESSAGES:
=================

There are 3 different ways to send messages. They aren't too 
different, and it's up to your personal preference which one to use:

1ST METHOD:
-----------

>>> data = '\00\01\02\03'    # 4 bytes: 00, 01, 02, 03
>>> 
>>> srv.post(daddr = 5,   saddr = 3,  did  = 128, 
...          sid   = 128, type  = 32, data = data)

Any of these can be omitted, in which case the defaults specified 
with set_message_defaults() are utilized. You may also choose to 
use the pack() method, as such:

>>> data = pysos.pack('<LHB', 0, 1, 2)

where '<LHB' stands for a little endian ('<') struct composed of a
uint32 ('L'), uint16 ('H') and uint8 ('B'). For signed integers, use
lowercase letters instead. Of course, the string you feed into the pack()
method depends on your particular data struct.


2ND METHOD:
-----------

This method is largely the same as the previous, but it separates
the message creation from the act of sending it:

>>> m = pysos.msg(daddr = 5,   saddr = 3,  did  = 128, 
...               sid   = 128, type  = 32, data = data)
>>>
>>> srv.post_msg(m) 


3RD METHOD:
-----------

If you prefer to use SOS's post_net syntax, you may do so like this:

>>> srv.post_net(128, 128, 32, 4, data, 0, 5)

In this case, saddr is the one specified with set_message_defaults(),
or 0xFFFE by default. This is because post_net does not let you specify
your saddr in SOS.

Also note that the "length" and "flags" parameters are ignored. 


RECEIVING MESSAGES:
===================

There are 2 different methods you can use. The first one is 
synchronous (blocking) and the 2nd asynchronous -- it allows you to 
register listeners and then run a non-blocking method to start listening 
for messages. You can use both of these methods with the same sossrv.

1ST METHOD (synchronous):
-------------------------

>>> msg = srv.listen(did   = 128,  sid   = 128, 
...                  daddr = 0x14, saddr = 0x16, 
...                  type  = 32,   nreplies = 5, timeout = 3.0)

This method returns the first matching messages. It returns the message as
a dictionary with keys 'did', 'sid', 'daddr', 'saddr', 'type, 'length',
and 'data'. To cast msg['data'] into a tuple, you may use the unpack()
method, as such:

>>> data = pysos.unpack('<LHB', msg['data'])


2ND METHOD (asynchronous):
--------------------------

For this method you register a trigger (i.e. listener). Then a thread
in the background will call a function of your choosing
when the trigger fires.

This is how you specify a trigger:

>>> srv.register_trigger(func,         did   = 128, 
...                      sid   = 128,  daddr = 0x14,
...                      saddr = 0x16, type  = 32)

Where you may omit any parameter (except func) to match all messages,
irrespective of that parameter's value. That is, None is a wildcard.
At any point, you may use the deregister_trigger() method to remove
triggers from the pysos instance. When deregistering a trigger, None
is once again used as wildcard.


RPC-STYLE COMMUNICATIONS:
=========================

You can also do an RPC-style call, which posts a message to the network 
and returns the response message(s):

>>> replylist = srv.post_rpc_msg(m, rtype=36, nreplies=10, timeout=5.0)

The above command creates a message dictionary (through sossrv.msg_dict)
which is sent to all the nodes. We collect up to 10 replies with message
type 36 in the variable msglist. The replies are in a list of message
dicts. If 5 seconds elapse, we just return the messages obtained thus far.

For those who do not wish to first create a message dict (the variable
called 'm' in the example above), there is the post_rpc() method:

>>> post_rpc(did    = 0x97, daddr  = 13, type   = 32,
...          rsid   = 0x97, rsaddr = 13, rtype  = 40,
...          timeout = 3, nreplies = 5)


MORE INFORMATION:
=================

Use each method's help function for more details.