Get smart things talking with AllJoyn and Kii
Avoid lower-level network protocols and hardware in your Internet of Things projects with AllJoyn open source software.
AllJoyn framework overview
Before jumping into code, you should know a few AllJoyn basics. Any peer participating in an AllJoyn conversation must “talk” via a (relatively low level) bus. Think of it as the highway in which all AllJoyn messages travel. First your app needs to attach to the bus by creating a bus attachment. Through a bus a peer can participate in an AllJoyn conversation but it has to be done through a concrete interface. The interface is created in the bus with the purpose of handling shared objects and signals sent to the objects. In our example the peers will share a chat object in the bus and signals sent to it will be relayed to the other peers as messages.
Next you have to decide whether your app wants to join and use an existing service or advertise one for others to join. Assuming you want to advertise a service, give it a recognizable name. Other peers will try to locate your service using it. Then bind a port (e.g. 27) to create a session over the bus. The steps:
- Create a BusAttachment and connect to the AllJoyn framework to communicate with other AllJoyn applications
- Create an Interface in the Bus and define the Signals that it will handle
- Create a BusObject and pair it with the Interface (after starting the Bus)
- Define a SignalHandler for signals sent to the BusObject
- Register the BusObject with the Bus and connect
- If Advertising:
- Choose a unique identifier. Create a unique name
- Create a Session other applications can join
- Tell other applications you’re there by advertising the service name
- If Joining:
- Find other applications nearby by looking for a name prefix
- Define a BusListener to join a Session once a service name is found
- Join a session that has been found
- Communicate with other applications in your group
Don’t panic. We’ll go through the code needed to achieve all the necessary steps below.
Install and compile AllJoyn
- Install npm and nodejs (alternative install available here)
- Install the AllJoyn npm package
- Install the node-jquery-xhr npm package (required by the Kii js SDK)
- Download the Kii js SDK and place on the same directory where you’ll run your scripts
- Test the example-host.js and example-client.js by Octublu to make sure everything works
- On Mac the scripts are located on /opt/local/lib/node_modules/alljoyn (if you installed globally with -g) and can be run with the node command
Advertise the chat service
Next take a look at our nodejs script. It can run in host mode to advertise a chat service for other peers to join. Or you can run it as a client, which will look for a service advertised by the host on the network by name, and then connect to it. This setup allows as many clients as you want but there must be only one host. The reason for using a single script for host and client is that 95% of the code is shared (see below).
Once connected all peers (host and clients) have the same behavior listening to and showing incoming messages, and allowing you to type messages for other peers to see. As an add-on all hosts and clients log incoming messages on the cloud with Kii for later analysis.
Initialize and authenticate with Kii
Once you created a Kii app at developer.kii.com, write down the app ID and key to initialize Kii:
Once Kii is initialized a sign-in is attempted with the peer name and password passed via the command line. If this fails a first time registration is attempted against the Kii service:
Note that the Kii API provides async method calls (with callbacks) in its methods, which makes control fairly easy and allows you to keep working on your script while a user signs in or registers.
Set up the AllJoyn bus
Some bus setup has to be done in any chat peer that wants to participate in a conversation using AllJoyn:
A chat object is used as a common structure between peers to receive signals. The signal handler will interpret signals as messages.
Advertise the service on the host
After hooking up to an AllJoyn bus the host advertises the service name, combining a session, port and port listener callback:
The host will effectively listen on port 27 for client connections and execute the port listener callback on each connection.
Find the service on the client
The client goes through an identical bus setup as the host. Instead of advertising a service it looks for one (given the same service name):
For the client the bus listener callback is key because it defines what to do when a service name is found. In this case, when the service is found, we tell the client to join a session with the host:
Send, receive and log messages
Sending and receiving messages is done the same way for host and client. First a shared bus object is created on the bus and each peer subscribes to signals sent to it via a signal handler.
In order to send messages the peer takes input from stdin and then sends a signal to the shared chat object:
In order to receive a message each peer has a signal handler that interprets the signal as an incoming message, sends it to the console and does the logging on Kii:
Please note: In order to store Kii data you’ll need to create a KiiObject from an application scope bucket and set all the details of the incoming message as in a key/value store. After that you can save the object on Kii with an async call and use the Kii Data Browser available on developer.kii.com to see stored messages:
That’s about it. Keep in mind that peers interpret messages as text to display on screen but these exchanged messages could be more complex structures, commands, etc. suitable for all kinds of IoT scenarios. Even binary formats could be exchanged and saved on Kii as files.And of course, besides storing data on Kii Cloud you can retrieve it via a powerful query system as easily.
Full source code for both the host and client can be found here. Usage is straightforward:
> node peer.js [MODE] [YOUR_APP_ID] [YOUR_APP_KEY] [USERNAME] [PASSWORD]
MODE is either “host” or “client”. Run in host mode first, then open another shell and run the client mode (if you get errors about the address being in use try from another machine on the network since the embedded AllJoyn daemon is then using the same address). Note that you should run only one host but can have as many clients as you want. The parameters YOUR_APP_ID and YOUR_APP_KEY can be obtained by creating an app at developer.kii.com. And you can freely set your username and password, which will be created the first time if credentials don’t exist on Kii. We recommend using a different username for each running script (otherwise all scripts no matter if they are hosts or clients will do the logging as the same Kii user).
Happy coding 🙂