Sugar.presence

How do I setup a D-Bus Tube?

Let's first look at what conceptually happens to make activity sharing work. The diagram below shows two instances of the same activity: the "Sharing Activity" and the "Joining Activity". The sharing activity is the activity that is initially run and shared with other buddies. The "Joining Activity" refers to other instances of the activity that are created once buddies decide to join an activity that has been shared. You can allow an activity to be shared (making it a sharing activity) by including the standard Sugar Activity Toolbar.

How is data shared between activities through a D-Bus tube?

Communication in Sugar is achieved through several layers of technologies, including Sugar's own Presence Service, the D-Bus service for process communication, and various implementations of the telepathy system used for real time conversations. In order to get activity communication working between activities, your goal is to ultimately create a D-Bus tube that will handle text messaging between activities (there are also stream tubes which are discussed elsewhere).

The figure below shows a simplified conceptualization of what happens after you set up a D-Bus tube correctly.

The activity code for each XO should handle sending text to the tube and also receiving text through a callback method that is supplied to the tube. The Activity developer will also need to define the Tube Object itself, which should be designed to send and receive text appropriately based on the type of sharing that is desired.

Let's consider a simple, but concrete example of how a D-Bus tube is used (assuming it has already been setup correctly). The code below is from a chat application where users type text and send it to others who are sharing the activity. Only the minimal code needed to send and receive text is included for clarity. If you want to know how the tube is set up from start to finish, then read the section on setting up a D-Bus tube. The comments should make clear what code does what in this example.

import telepathy
from dbus.service import method, signal
from dbus.gobject_service import ExportedGObject
from sugar.presence import presenceservice
from sugar.presence.tubeconn import TubeConnection
...
SERVICE = "org.laptop.Sample"
IFACE = SERVICE
PATH = "/org/laptop/Sample"

############## MAIN ACTIVITY CLASS ####################
class SampleActivity(activity.Activity):
    ...
    # Callback method for text received from tube -- update activity state
    def text_received_cb(self, text):
        self._chat += "\nSomeone Else Said" + ":: " + text + "\n"
        self._chat_buffer.set_text(self._chat)

    #### Method: _speak_cb, which is called whenever user decides to send whatever chat text
    # he has written in self._chat_input to the public. 
    def _speak_cb(self, widget, entry):
        nick = profile.get_nick_name()
        nick = nick.upper()
        self._chat += "\n" + nick + ":: " + entry.get_text() + "\n"
        self._chat_buffer.set_text(self._chat)
        if self.chattube is not None:
            self.chattube.SendText(entry.get_text())
        entry.set_text("")

     ...


###################### TUBE CLASS ######################
class ChatTube(ExportedGObject):
    
    def __init__(self, tube, is_initiator, text_received_cb):
        super(ChatTube, self).__init__(tube, PATH)
        ...
        self.text_received_cb = text_received_cb
        self.text = ''
        self.tube.add_signal_receiver(self.sendtext_cb, 'SendText', IFACE, path=PATH, sender_keyword='sender')
        ...        

    # This method is called when the XO receives some text through the D-bus tube
    def sendtext_cb(self, text, sender=None):
        # Ignore any text that this XO sent to itself. 
        if sender == self.tube.get_unique_name():
            return

        self.text = text
        self.text_received_cb(text)

    # This method is used to actually send text to all other XO's who are sharing. 
    @signal(dbus_interface=IFACE, signature='s')
    def SendText(self, text):
        self.text = text
 

Where do I get more information regarding sugar activity sharing and the technologies that support it?

• A brief tutorial on activity sharing for the OLPC laptop.