Search form

Documentation

Events and Actions

Overview

The Events and Actions feature is part of the AllJoyn&trade Core, designed to enable creating If-This-Then-That (IFTTT)-based rules logic in the AllJoyn network.

  • Events are used by AllJoyn devices/apps to notify other AllJoyn devices/apps when something of significance occurs in the network.
  • Actions enable specific responses to AllJoyn events detected in the AllJoyn network. In this regard, Events and actions go hand-in-hand. An action is a way for making an application or device do something.

For example, an AllJoyn application can broadcast an event signifying that something has happened, such as movement that was detected by a motion detector. An AllJoyn application can receive this event and respond to it by taking a specific action, such as turning on the security camera.

Events are realized using AllJoyn sessionless signals, while actions are realized using AllJoyn methods. A description element is added to the AllJoyn introspect XML format to provide human readable text for the Events and Actions feature.

The following figure illustrates the context architecture for the Events and Actions feature.

events-actions-arch

Figure: Events and Actions context architecture

Events and actions are advertised in the Announcement signal using the org.allseen.Inrospectable interface. Any advertised object supporting an event-emitting interface or action-receiving interface will include this new interface in the Announcement signal. The Authoring app is an AllJoyn-enabled app that provides a UI for creating IFTTT based rules for automation in the IoE network The Authoring app receives announcement signals from AllJoyn devices that emit events and/or can receive actions. The app introspects those devices to retrieve a human-readable description for events and actions as part of the enhanced introspection XML data.

These human readable text description details can be presented to a user allowing the user to create IFTTT based rules for automation in the IoE network. These IFTTT rules get configured on a Rule Engine which could be on the same device or a different device than the Authoring app.

NOTE: The Rules Engine is beyond the scope of current design and its implementation is left to the ecosystem). The Rules Engine app detects when the event is emitted. Based on the configured IFTTT rules, it executes actions (method call) on the action-receiving devices.

Enhanced introspection XML

The AllJoyn system supports introspection XML format as defined by the D-Bus specification via org.freedesktop.DBus.Introspectable interface. To make events and actions discoverable, an enhanced AllJoyn introspection XML is made available to provide human readable description elements. This XML provides description elements as applicable under Objects, Interfaces, Methods (including parameters), Signals (including parameters) and Properties.

The description element may appear inside the enhanced introspection XML under the elements captured in Elements carrying description element.

Elements carrying description element

XML element Description
node Objects and sub-objects within the tree of objects.
interface Interface element.
method Method element.
property Property element.
signal Signal element.
arg Arguments to signals and methods.

In addition, the enhanced Introspection XML also includes sessionless="true|false" attribute for the signal element to indicate whether or not it is sessionless signal.

The following is an example of enhanced introspection XML format.

<node name="/com/example/LightBulb">
    <description>Your lightbulb</description>
    <interface name="com.example.LightBulb">
        <description>Provides basic lighting functionality</description>
        <method name="ToggleSwitch">
            <description>Invoke this to toggle whether the light is on or off</description>
            <arg name="brightness" type="i" direction="in">
                <description>A value to specify how bright the bulb should shine</description>
            </arg>
        </method>
        <signal name="LightOn" sessless="true">
            <description>Emitted when the light turns on</description>
        </signal>
        <property name="LightState" type="y" access="read">
            <description>The current state of this light bulb</description>
        </property>
    </interface>
    <node name="child">
        <description>Some relevant description</description>
    </node>
</node>

Introspectable interface

The org.allseen.introspectable interface is designed to provide access to the enhanced introspection XML containing the description elements. The following table provides the definition for the org.allseen.introspectable interface which is implemented by all AllJoyn objects.

Introspectable interface methods

Method Description
AttachSession Return the aggregate of the languages for which this object has descriptions. For example, if an object implements two interfaces, X and Y - X has all of its members described in English (en) and French (fr) and Y has some descriptions in English (en) and Chinese (cn), this method will return ["en", "fr", "cn"]. The language tags will comply with IETF language tag standards.
IntrospectWithDescription Returns the XML defined above with descriptions in the specified language (exact match only - no best match). If an element, e.g., method, does not have a description in that language, no description attribute is placed within the element.

Introspectable.AttachSession method parameters

Parameter name Direction Description
languageTags out List of the languages in which this object has descriptions.

Introspectable.IntrospectWithDescription method parameters

Parameter name Direction Description
languageTag in Requested Language.
data out Returned introspection XML.
For future news and updates, please follow or visit https://t.co/MKr1Z9NPji
8 months 2 weeks ago