Libraries, Tutorials

PyOpenSpime 0.2 launched!

Dear developers,

today the OpenSpime library PyOpenSpime v0.2 has been released! This version 0.2 does not fully support the OpenSpime protocol v0.9 yet, however it fully implements the Data Reporting OpenSpime core extension.

The main differences between the previous v0.1 release are:

• a major code refactoring which has substantially improved code useability (for instance, the OpenSpime engine responsible for handling the protocol is now completely separated from the OpenSpime XMPP client code);
• client now runs threaded (so that a GUI such as wxPython may be used);
• the component class has been added;
• it is now extremely easy to build custom OpenSpime protocol extensions for you own needs.

To get you started, especially the new developers, please find here below a tutorial which basically is an updated version of Davide ‘Folletto’ Casali’s original tutorial for the previous release.

Video Tutorial

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, in the ‘Easy Steps for a full tryout’ section.

Background

If you’re reading this, you most probably 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 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. The necessary valid OSIDs (OpenSpime IDentifiers) 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.2 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. You might take a shortcut for the Mac OS X 10.5 (i386) downloadable .egg file: 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 OSIDs on the OpenSpime Developer Netowork.

The ‘My Developer’ page and your OSIDs

As stated before, you’ll need your unique OSIDs, 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 two unique OSpkg: one for your Spime, one for your 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

Here are the steps done in the video here above. 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_basic.py in the tut/ directory and edit the line:

# SNID
SNID = 'dev-scopenode-x@developer.openspime.com/scope'

so that it reflects the name of your ScopeNode ID:

# SNID
SNID = 'dev-scopenode-2@developer.openspime.com/scope'

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

# SpimeID
SpimeID = 'dev-spime-x@developer.openspime.com/spime'

so that it reflects the name of your SpimeID:

# SpimeID
SpimeID = 'dev-spime-2@developer.openspime.com/spime'

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

# SNID [i.e. the ScopeNode receiving data from this spime]
SNID = ‘dev-scopenode-x@developer.openspime.com/scope’

so that it reflects the name of your ScopeNode ID:

# SNID [i.e. the ScopeNode receiving data from this spime]
SNID = ‘dev-scopenode-2@developer.openspime.com/scope’

Doing this, we have set your Spime to send data to your ScopeNode.

Take a closer look at the following code in spime_basic.py:

# add xml data node
dr_reqobj.add_entry(u"""<entry>
		<date>2008-10-09T10:02:22+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>""")
# send request
req_id = self.send_request(dr_reqobj, SNID, encrypt = True, sign = True)

We have added an hardcoded entry in XML format, and this entry will be sent to your ScopeNode encrypted and signed.

Now:

• run scopenode_basic.py: you should see that your ScopeNode connects and states that it is ready.
• run spime_basic.py: you should see that your Spime connects, 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.

To perform this operation, two public RSA keys will automatically be exchanged:

1. the ScopeNode public RSA key which will be sent directly from the ScopeNode to the Spime (this is to allow the Spime to encrypt the outgoing data with the ScopeNode’s public key);
2. the Spime public RSA key which will be sent from the OpenSpime Developer Network SpimeGate’s certification service (services@developer.openspime.com/cert) to the ScopeNode (this is to allow the ScopeNode to verify the digital signature of the Spime).

You may find these keys in the newly created cache/ folder.

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 OSID entity information 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.

The two zip files which can be downloaded from the My Developer page are two valid OSpkg that you can use for your development, which connect to the OpenSpime Developer Network SpimeGate.

Happy spiming! :)

Tags: pyopenspime, python, tutorial