Featured, Libraries, Tutorials

PyOpenSpime 0.1: Getting Started

The most difficult part in any task is to start. So, I’ve prepared a tutorial to get you started with the OpenSpime infrastructure and PyOpenSpime 0.1, the first release of the Python OpenSpime library.

If you’re reading this, most probably you already know what a spime is: a technologically enabled device that interacts both with the physical and the digital environment, aware of its location and with an history about itself.

The OpenSpime network is the first open infrastructure designed to bring the spimes to life. For a technical introduction on OpenSpime please refer to this video. You may also prefer to read the exhaustive documentation that is available on the OpenSpime.org website.

The PyOpenSpime library is written in Python, therefore it should be easy for you to get it working thanks to Python’s cleanness and the simple design of the library.

Setup the development environment

To work with PyOpenSpime you need four things:

1. Python 2.5 (download it here).
2. The PyOpenSpime package (download it here).
3. The M2Crypto library (download it here).
4. A valid OSID (an OpenSpime IDentifier) on a SpimeGate server.

Download and install Python 2.5 if needed. Recent versions of Mac OSX and linux may skip this step.

The PyOpenSpime 0.1 library is distributed via Google Code with a GPL 3.0 license, just unzip the downloaded package. Inside it you’ll find:

• The PyOpenSpime library and some required dependencies, under the lib/ folder.
• The commented-source tutorials, under the tut/ folder.
• The full documentation of the library built with Epydoc, under the docs/ folder.

Download and install the M2Crypto library. This library isn’t included in the package since it requires a platform-specific compiled runtimes, and also because it’s subject to the U.S. Export Administration Regulations.
On the official website however there are some pre-compiled binaries for Windows and Mac which might match your development machine.
About the Mac OS X 10.5 (i386) downloadable .egg file: you might take a shortcut. Just download it, rename it to zip and uncompress it. Take the M2Crypto/ folder and copy it inside the lib/ folder of the PyOpenSpime package.

Now let’s get your OSID on the OpenSpime Developer Netowork.

The ‘My Developer’ page and your OSID

As stated before, you’ll need your unique OSID, so this steps requires a registration on the OpenSpime Developer Network SpimeGate. It’s simpler than you think, since the creation of the unique OSID is linked to the registration to the Developer Network. Yes, this site.

If you are already a registered developer you may skip steps 1-6.

1. Open developer.openspime.com if you’re reading this tutorial from another location or printed page.
2. On the top-right corner locate the “Login” button and click on it.
3. The login page appears, click on “Register” at the end of the form.
4. Here you just have to choose an username, specify your password and agree to the Terms of Service (be sure to read them). Now click on “Register”.
5. You should get a “Registration complete” message. Now check your e-mail for the password and login.
6. Done! Now go back to the developer.openspime.com home page.
7. On the same line where before you found the “Login” button now a “My Developer” button appeared. It will take you to the My Developer page.
8. Here you’ll find everything you need to develop on the OpenSpime network: the PyOpenSpime library and also your own OSpkg: one for a Spime, one for a ScopeNode.

An OSpkg, aka an OpenSpime package, is a simple folder structure that contains the identity of an entity on the OpenSpime network. On your My Developer page, you’ll see that two have already been created for you. Download both OSpkg, the one for your Spime, and the one for your ScopeNode.

Easy Steps for a full tryout

This video shows the necessary steps to try out in a few minutes a full data reporting cycle on your machine, using the PyOpenSpime library. For your convenience, the steps done in the video are also reported below.

Here are the steps done in the video. First, unzip both OSpkg in the tut/ directory of PyOpenSpime. You will have now two additional directories which look like:

dev-spime-x@developer.openspime.com/spime
dev-scopenode-x@developer.openspime.com/scope

Now open the file scopenode_normal.py in the tut/ directory and edit the line:

c = Client(osid_or_osid_path = 'scopenode@developer.openspime.com/scope', log_callback_function = log.log)

so that it reflects the name of your ScopeNode ID:

c = Client(osid_or_osid_path = 'dev-scopenode-x@developer.openspime.com/scope', log_callback_function = log.log)

Doing this, we have set the ScopeNode to connect with your ScopeNode ID. Now open the file spime_normal.py and edit the lines:

c = Client(osid_or_osid_path = 'spime@developer.openspime.com/spime', log_callback_function = log.log)

so that it reflects the name of your SpimeID:

c = Client(osid_or_osid_path = 'dev-spime-x@developer.openspime.com/spime', log_callback_function = log.log)

Doing this, we have set the Spime to connect with your Spime ID. finally, edit the line

c.send_stanza(iq, 'scopenode@developer.openspime.com/scope', encrypt = True, sign = True)

so that it reflects the name of your ScopeNode ID:

c.send_stanza(iq, 'dev-scopenode-x@developer.openspime.com/scope', encrypt = True, sign = True)

Doing this, we have set your Spime to send an encrypted and signed message to your ScopeNode.

Now:

• run scopenode_normal.py: you should see that your ScopeNode connects and states that it is ready.
• run spime_normal.py: you should see that your ScopeNode connect, then sends a message.
• check on your ScopeNode terminal: you’ll see that an XML has been printed on screen. That is the data reporting message that has been transfered encrypted and digitally signed from your Spime to your ScopeNode.

Your first easy tryout is now done! Let’s get deeper. What’s an OSpkg?

OSpkg

The OpenSpime Package, or OSpkg, is a simple folder structure that contains the identity of an entity on the OpenSpime network.

While your source code might do any kind of work and might be written in any kind of language, the OSpkg is a simple structure that holds the identity informations of a specific spime.

In XMPP, the backbone of OpenSpime, each client is identified by a full JID (OSID on the OpenSpime Network), which is something that looks like this:

name@server/resource

The OSpkg has the same structure, but it’s mapped to a folder:

name@server/
    resource/

This allows a good separation of the entity OSID from the source code.

Inside each resource folder there’s a conf.xml file, describing the spime properties and an optional keys/ folder containing its private and public keys to allow encoded communication and digital signature.

So, the two zip files from the My Developer page are two valid OSpkg that you can use for your development.

Write a custom spime

Create a new folder and put inside it:

• The content of the lib/ folder from the PyOpenSpime package, including M2Crypto if you installed it there.
• The unzipped OSpkg of the OSID of the spime.
• The certification-authorities.conf file from the tut/ folder.
• An empty spime.py file.

Then open the spime.py file, we will work inside of it.

First of all, we need to import the OpenSpime Client and we’ll initialize it:

from pyopenspime.core import Client
c = Client('spime-tutorials@developer.openspime.com/tutorial-1')
c.connect()

As you can see, the only required parameter for the Client() initialization is the full OSID name. It automatically checks if the OSpkg exists and loads it. Here you have of course to use the spime name matching the OSpkg taken from the My Developer page. The last line connects the spime to the SpimeGate (in this case, developer.openspime.com).

Then, you’ve got to prepare the data that will be sent to the ScopeNode:

import pyopenspime.extension.datareporting
dr = pyopenspime.extension.datareporting.ExtObj()
dr.add_entry(u"""<entry>
        <date>2008-06-16T06:16:00+01:00</date>
        <exposure>outdoor</exposure>
        <lat>45.475841199050905</lat>
        <lon>9.172725677490234</lon>
        <ele unit='m'>120.0</ele>
        <ppm>176.4</ppm>
    </entry>""")
iq = dr.build('iq')

This is the rough part of the 0.1 library, since you’ll see a bit of the underlying infrastructure (it will be cleaned up in a future release).
The class pyopenspime.extension.datareporting.ExtObj is one of the possible extensions of the OpenSpime protocol and it handles the spimes data reporting layer.
On the first line we import it and then we initialize one DataReporting container, adding a XML data entry to it with the add_entry() method.
The last line will build a XMPP <iq> stanza. If you don’t want to read the full OpenSpime protocol take it for granted for now, but ‘iq’ must be used when a confirmation receipt is requested.

Of course, here we’ll be using some dummy data. In a real program date, latitude, longitude, elevation and ppm will all be calculated.

We’re quite done: the spime is connected and we’ve got some data to send!

def on_success(stanza_id, stanza):
    print(u'data with id \'%s\' succesfully received by recipient.' % stanza_id)
c.set_iq_handlers(on_success)

c.send_stanza(iq, 'spime-tutorials@developer.openspime.com/tutorial-2')

while c.loop():
    pass

This code will create an handler function and attaches it to the client using the set_iq_handlers() method. It triggers when a XMPP <iq> XML has been received. This means that it will be called when the data has been successfully received, without errors.

The send_stanza() method will send the iq object we created before to the specified ScopeNode, identified by its full OSID. Always remember to use your own OSID from the ScopeNode OSpkg, not this one.

In the end the while loop puts the OpenSpime client on listen. Without this we’ll never know if the data has been received, since the spime will not be listening.

Write a custom ScopeNode

Writing a spime is nice, but you also want to see the full pipeline. So, now we’ll see the ScopeNode, the entity that will receive the data from the spimes all around the world.

Exactly like the spime, we import the OpenSpime client and we’ll initialize it:

from pyopenspime.core import Client
c = Client('spime-tutorials@developer.openspime.com/tutorial-2')
c.connect()

No differences here, both the Spime and the ScopeNode are two clients, from a XMPP perspective.
Here you should use the OSID from the scopenode OSpkg, the same you used before as the destination for the spime-generated data. In the end you’ll have the whole roundtrip completed!

def on_data_received(extname, extobj, stanza):
    if extname == 'datareporting':
        print extobj.entries[0]
        c.send_stanza(extobj.accepted(), stanza.getFrom())

c.on_data_received = on_data_received

while c.loop():
    pass

The ScopeNode doesn’t have to build the data, so this is simpler: we build an handler, attaching it to the client using the on_data_received() method. This will be triggered any time the ScopeNode will receive data.
We just have to add a simple check to ensure that the data we received is from a Data Reporting type of XML and then we could just parse the received XML. In this tutorial we’ll just print it for explanation purposes.

Then, we put the ScopeNode on listen, with the same while loop from before. Done!

Now, run the ScopeNode and a few seconds later fire also the Spime.
The two should show you that they completed a successful data reporting.

Ending

This tutorial explains the basic structure of OpenSpime entities communication and shows the elements required to build a Spime and a ScopeNode.

Even if it’s a 0.1 release, most of the OpenSpime protocol is implemented and it already has a simple and plain interface. I’ve covered just the basics of the PyOpenSpime library, if you want just go deeper in the documentation, and maybe read the source code.

See you soon, for the 0.2 release! :)

Tags: pyopenspime, python, tutorial