Tutorial

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.

The Application

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.

Resources representing John and
Andy

A resource used for monitoring the
game

A swarm for them to play virtual tag
in

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!

Configuration

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.

Creating the Resources

Using the resources.py BUGswarm Tools
script, create a resource using the following command.

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.

Creating the Swarm

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

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.

Adding Resources to the Swarm

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.

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.

Participation

Creating the Webpage

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.

Creating the Application

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.

Starting to Talk

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.