PeerDeviceNet - Developer API

PeerDeviceNet Router

PeerDeviceNet provides android runtime/api-library to set up secure ad-hoc peer-peer connections among a group of devices and enabling communication among them. Its typical use cases cover mobile, P2P, M2M, IoT applications.

Its API and protocol is very light weight, and covers peer discovery, presence, membership and messaging, similar to MQTT. One major difference from MQTT is that MQTT is client-server model; all devices connect to server to enable communication among each other. PeerDeviceNet enables direct device-device (or peer-peer) connections, logically without server in between.

Its API and protocol include the following primitives:

network detection, connection and disconnection: when device is attached to networks or detached from networks. Currently it supports wifi, wifi-direct and mobile hotspot. because its plugin style implementation, it is easy to add bluetooth or other transport.
peer device discovery: it is designed to enable new ways of peer discovery, for example, use new sensors in mobile devices. On top of it we built apps using multicast, scanning QR code, NFC tapping for peer discovery and connection.
peer device connection, detection of connecting peers and disconnection.
membership: join/leave app specific communication groups and detect peers’s join/leave.
send/receive messages thru groups.

The runtime (Router) runs as an android service in a background process, while apps invoke its APIs thru AIDL, intents or messenger messages.

The runtime (Router) and api library have been published as two jar/aar packages at MavenCentral (http://search.maven.org/#search|ga|1|peerdevicenet). and you can grab them thru maven or gradle as described in JavaAPI doc.

As developers, we find mobile platforms (Android, iOS, Win8) are different from traditional platforms (desktops, servers).

Apps are developed as components glued together thru high level communication / integration mechanisms (intents, custom urls, contracts), which enables ad-hoc reuse and composition of features from different apps.
Cross components API are mostly asynchronous for the responsiveness of apps.
Many issues become prominent in mobile environments such as power conservation, permissions to access device features, network connectivity, etc..

PeerDeviceNet Router internal design and developer API are native to the mobile programming model. Its simple intent API allows adding remote messaging to apps without any library "gluing"; while its IDL interfaces allow apps fine grained control of messaging and connection.

PeerDeviceNet api exposes the following three functional modules to support connected mobile/P2P apps:

Remote intenting. intents and api to enable remote start of activities and services at peer devices, send remote broadcasts.
Group communication. intents and api for group membership and message passing.
Device connection. intents and api for network detection, peer device discovery, peer device connection setup.

Each modules are normally supported in three levels of APIs:

Intent api.

Intent API provides the highest level of access to Router's features. To use this API, all you need is to have PeerDeviceNet (Router) installed on users devices to gain the runtime support. Apps send normal android intents using PeerDeviceNet specific action names and pack message data as intent "extra" data items with PeerDeviceNet specific keys. All the PeerDeviceNet action names are defined at Router.Intent class and "extra" data keys at Router.MsgKey class which you get when you add the client jar file to your project.

IDL api.

PeerDeviceNet's IDL APIs define purely asynchronous methods and callbacks. To access Router services thru these apis, you can use client wrapper classes RouterConnectionClient and RouterGroupClient which also handle some common book-keeping for you. There is also DeviceInfo class and NetInfo class used at idl api which defines information about devices and networks.

Messenger api.

Messenger API is also a high level api for apps using android's standard messaging pattern "Messenger". This api defines a group of PeerDeviceNet specific message ids which can be used with android's Message object. Apps use messengers to send message data as a bundle with data items using the same key names as Intent api. All the PeerDeviceNet message ids are defined at Router.MsgId class and bundle data keys are defined in Router.MsgKey class.