The following tutorial will teach you how write a BUGswarm application from the ground up. It will take you through the steps of configuring your swarm using the Configuration API and participate in it using the Participation API. If you haven't yet, we would advise that you take a quick look at how these APIs are implemented.
Uh oh! We're out of cookies here at the Bug Labs office and it's up to either John or Andy to go down to the store to buy some more. To decide who has to go, John and Andy have decided to play a game of tag. In order to help them save some energy and avoid disrupting everyone else at work, we've decided to create a virtual game of tag, and what better way to do so than using BUGswarm!
To create this application, we are going to need the following.
To build our application, we are going to use a set of Python-based development tools. If you haven't already, please go ahead and check out the BUGswarm Tools repository from our github page. Be sure to run the init.py script with your Bug Labs account credentials.
./init.py init Username Password
In addition to BUGswarm Tools, we are going to use our JavaScript library for building our monitoring web application. You can find more information about this library on the Libraries page.
But that's enough talking for now. Let's get to it!
Before we can begin producing and consuming information on the platform, we must first create resources to do the producing and consuming, a swarm for them to produce and consume in, and then add those resources to the swarm. You can think of the swarm as a chatroom and the resources as participants in that chatroom.
Using the resources.py BUGswarm Tools script, create a resource using the following command.
./resources.py create John pc -d "This is John"
Output: (Some values will be different of course)
{
"created_at": "2011-11-30T20:07:45.228Z",
"description": "This is John",
"id": "19c2db197ad341215a265063fb7cd989df66c784",
"machine_type": "pc",
"name": "John",
"user_id": "username"
}
Do the same for Andy and our monitoring web resource that we will simply call 'Monitor'. After doing so, running the list method of the resources.py script should produce the following output.
[
{
"created_at": "2011-11-30T20:07:45.228Z",
"description": "This is John",
"id": "19c2db197ad341215a265063fb7cd989df66c784",
"machine_type": "pc",
"name": "John",
"user_id": "username"
},
{
"created_at": "2011-11-30T20:11:20.929Z",
"description": "This is Andy",
"id": "badca6a822f35976ea4c7d9eab2362dfac5f7e9f",
"machine_type": "pc",
"name": "Andy",
"user_id": "username"
},
{
"created_at": "2011-11-30T20:11:39.445Z",
"description": "This is the monitor",
"id": "765a4517de59e18be11d7d9e09864f2de5521a58",
"machine_type": "pc",
"name": "Monitor",
"user_id": "username"
}
]
Well there you go. We have now created the necessary resources for our application. Unfortunately, they are not members of any swarm. In fact, there isn't even a swarm for them to become members of! That's where the next step comes in.
In order for our resources to communicate with each other, we must first create a place for them to communicate. Using the swarms.py script, create a swarm using the following command. Notice that we are creating a private swarm (the -p option). This is an exclusive game of tag and we don't want just anyone to be able to play!
./swarms.py create "Tag Swarm" "The swarm used for playing tag" -p false
Output: (Some values will be different of course)
{
"created_at": "2011-11-30T20:27:03.401Z",
"description": "The swarm used for playing tag",
"id": "de6cabfc8ee26d2bd1f312d5e876f327f9d919f3",
"name": "Tag Swarm",
"public": false,
"resources": [],
"user_id": "username"
}
Great, now we have a swarm to play tag in! Unfortunately, as you can see from the 'resources' field, our swarm is empty. This is because we haven't added John, Andy, or the monitor to the swarm yet. Let's go ahead and do that.
In order for John and Andy to play tag in the swarm, they must first be configured to be members of the swarm. At the same time, if we want to be able to monitor their game of tag, we better go ahead and add the monitor to the swarm as well. To do so, use the add_resource method of the swarms.py script. For instance, to add John to the swarm, run the following command. Notice that the parameters given are the swarm's ID, the resource's ID, and the type of resource it is going to be. For Andy and John, we will be adding them as producers, since they will be doing the tagging. For the monitor, we will be adding it as a consumer, since it is just monitoring the game.
./swarms.py add_resource de6cabfc8ee26d2bd1f312d5e876f327f9d919f3 19c2db197ad341215a265063fb7cd989df66c784 producer
After adding all three resources to the swarm, performing the get_info command of the swarms.py script for our swarm should produce the following output.
{
"created_at": "2011-11-30T20:27:03.401Z",
"description": "The swarm used for playing tag",
"id": "de6cabfc8ee26d2bd1f312d5e876f327f9d919f3",
"name": "Tag Swarm",
"public": false,
"resources": [
{
"member_since": "2011-11-30T20:40:26.727Z",
"resource_id": "19c2db197ad341215a265063fb7cd989df66c784",
"resource_type": "producer",
"url": "http://api.bugswarm.net/resources/19c2db197ad341215a265063fb7cd989df66c784",
"user_id": "username"
},
{
"member_since": "2011-11-30T20:40:35.767Z",
"resource_id": "badca6a822f35976ea4c7d9eab2362dfac5f7e9f",
"resource_type": "producer",
"url": "http://api.bugswarm.net/resources/badca6a822f35976ea4c7d9eab2362dfac5f7e9f",
"user_id": "username"
},
{
"member_since": "2011-11-30T20:40:45.975Z",
"resource_id": "765a4517de59e18be11d7d9e09864f2de5521a58",
"resource_type": "consumer",
"url": "http://api.bugswarm.net/resources/765a4517de59e18be11d7d9e09864f2de5521a58",
"user_id": "username"
}
],
"user_id": "username"
}
If your output looks something like the one above, then we have successfully added our resources to the swarm and we are ready to being building the participation part of our application!
Congratulations! You just learned how to create and configure a swarm.Keep in mind, while we used BUGswarm Tools to do this, you can use anything that implements our RESTful Configuration API, including some of our Libraries, your own implementations, or basic curl commands.
Now that we have configured the resources to talk to each other over BUGswarm, it's time to build the application logic. Let's start with a minimal webpage, which shows the players and any messages sent.
Now the application logic. The JavaScript library has
many optional callbacks, but it is recommended to implement
each of them. The callbacks you really want to pay
attention to are onmessage and
onpresence. These callbacks will drive the
application. Additionally, you may want to add a
console.log(response) in the handlers of these callbacks or
just check over the websocket to see what objects are being
passed around. Note that they are also described in the
Participation API
documentation.
Opening up the page in a browser shows the connected player, which is actually whatever resource id you are using for the JavaScript connection. Once all the players have the page open, it's time to start tagging people. To do this, we will use the BUGswarm Tools produce script.
./produce.py produce SWARM_ID RESOURCE_ID
To update everyone's page to display who is it, make sure your message is in the format:
{ "communication" : "JOHN IS IT!" }
Let the chaotic game of tag begin!
Hoorah! You just learned how to connect resources to a swarm and produce and consume data with them!If you would like to see other examples of how you can use BUGswarm, please visit the Applications page.