-
Notifications
You must be signed in to change notification settings - Fork 3
/
tutorial.html
385 lines (321 loc) · 13.2 KB
/
tutorial.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang="en">
<head>
<meta name="generator" content=
"HTML Tidy for Linux (vers 25 March 2009), see www.w3.org">
<title>BUGswarm Developers</title>
<link rel="stylesheet" href="bootstrap/bootstrap.css" type=
"text/css">
<link rel="stylesheet" href="css/this.css" type="text/css">
<link rel="stylesheet" href=
"js/google-code-prettify/prettify.css" type="text/css">
<script src="http://code.jquery.com/jquery-1.5.2.js" type=
"text/javascript">
</script>
<script src="js/google-code-prettify/prettify.js" type=
"text/javascript">
</script>
<script src="js/application.js" type="text/javascript">
</script>
<script src="js/google-analytics.js" type="text/javascript">
</script>
</head>
<body>
<!-- NAVIGATION-->
<div class="topbar">
<div class="topbar-inner">
<div class="container">
<h3><a id="banner" href="index.html" name=
"banner"><img src="images/bs_logo.png"></a></h3>
<ul class="nav">
<li class="dropdown nav-dropdown">
<a href="documentation.html" class=
"dropdown-toggle">Documentation</a>
<ul class="dropdown-menu">
<li><a href=
"configuration_api.html">Configuration</a></li>
<li><a href=
"participation_api.html">Participation</a></li>
</ul>
</li>
<li><a href="tools.html">Tools</a></li>
<li><a href="libraries.html">Libraries</a></li>
<li><a href="tutorial.html">Tutorial</a></li>
<li><a href="applications.html">Applications</a></li>
<li><a href="hardware.html">Hardware</a></li>
<li><a href="contact.html">Contact</a></li>
</ul>
</div>
</div>
</div><!-- CONTAINER-->
<div class="container">
<!-- Path-->
<div class="page-header">
<a href="index.html">Home</a> → Tutorial
</div><!-- Header-->
<h1>Tutorial</h1>
<p>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 <a href=
"configuration_api.html">Configuration API</a> and participate
in it using the <a href="participation_api.html">Participation
API</a>. If you haven't yet, we would advise that you take a
quick look at how these APIs are implemented.</p>
<div class="page-header"></div><!-- The Application-->
<h2>The Application</h2>
<p>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!</p>
<p>To create this application, we are going to need the
following.</p>
<ul>
<li><strong>Resources representing John and
Andy</strong></li>
<li><strong>A resource used for monitoring the
game</strong></li>
<li><strong>A swarm for them to play virtual tag
in</strong></li>
</ul>
<p>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 <a href=
"https://github.com/buglabs/bugswarm-tools">BUGswarm Tools</a>
repository from our github page. Be sure to run the
<strong>init.py</strong> script with your Bug Labs account
credentials.</p>
<pre class="prettyprint">
./init.py init Username Password
</pre>
<p>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
<a href="libraries.html">Libraries</a> page.</p>
<p>But that's enough talking for now. Let's get to it!</p>
<div class="page-header"></div><!-- Configuration-->
<h3>Configuration</h3>
<p>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.</p>
<ul>
<li>
<h4>Creating the Resources</h4>
<p>Using the <strong>resources.py</strong> BUGswarm Tools
script, create a resource using the following command.</p>
<pre class="prettyprint">
./resources.py create John pc -d "This is John"
</pre>
<p>Output: (Some values will be different of course)</p>
<pre class="prettyprint language-javascript">
{
"created_at": "2011-11-30T20:07:45.228Z",
"description": "This is John",
"id": "19c2db197ad341215a265063fb7cd989df66c784",
"machine_type": "pc",
"name": "John",
"user_id": "username"
}
</pre>
<p>Do the same for Andy and our monitoring web resource
that we will simply call 'Monitor'. After doing so, running
the <strong>list</strong> method of the
<strong>resources.py</strong> script should produce the
following output.</p>
<pre class="prettyprint language-javascript">
[
{
"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"
}
]
</pre>
<p>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.</p>
</li>
<li>
<h4>Creating the Swarm</h4>
<p>In order for our resources to communicate with each
other, we must first create a place for them to
communicate. Using the <strong>swarms.py</strong> 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!</p>
<pre class="prettyprint language-javascript">
./swarms.py create "Tag Swarm" "The swarm used for playing tag" -p false
</pre>
<p>Output: (Some values will be different of course)</p>
<pre class="prettyprint language-javascript">
{
"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"
}
</pre>
<p>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.</p>
</li>
<li>
<h4>Adding Resources to the Swarm</h4>
<p>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
<strong>add_resource</strong> method of the
<strong>swarms.py</strong> 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.</p>
<pre class="prettyprint language-javascript">
./swarms.py add_resource de6cabfc8ee26d2bd1f312d5e876f327f9d919f3 19c2db197ad341215a265063fb7cd989df66c784 producer
</pre>
<p>After adding all three resources to the swarm,
performing the <strong>get_info</strong> command of the
<strong>swarms.py</strong> script for our swarm should
produce the following output.</p>
<pre class="prettyprint language-javascript">
{
"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"
}
</pre>
<p>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!</p><strong>Congratulations! You just
learned how to create and configure a swarm.</strong>
<p>Keep in mind, while we used BUGswarm Tools to do this,
you can use anything that implements our RESTful <a href=
"configuration_api.html">Configuration API</a>, including
some of our <a href="libraries.html">Libraries</a>, your
own implementations, or basic curl commands.</p>
</li>
</ul>
<div class="page-header"></div><!-- Participation-->
<h3>Participation</h3>
<ul>
<li>
<h4>Creating the Webpage</h4>
<p>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.</p><script src=
"https://gist.github.com/bugvish/7402709.js?file=tutorial_application.html"
type="text/javascript">
</script>
</li>
</ul>
<ul>
<li>
<h4>Creating the Application</h4>
<p>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 <code>onmessage</code> and
<code>onpresence</code>. 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
<a href="participation_api.html">Participation API</a>
documentation.</p><script src=
"https://gist.github.com/bugvish/7402709.js?file=tutorial_application.js"
type="text/javascript">
</script>
</li>
</ul>
<ul>
<li>
<h4>Starting to Talk</h4>
<p>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.</p>
<pre class="prettyprint language-javascript">
./produce.py produce SWARM_ID RESOURCE_ID
</pre>
<p>To update everyone's page to display who is
it, make sure your message is in the format:</p>
<pre class="prettyprint language-javascript">
{ "communication" : "JOHN IS IT!" }
</pre>
<p>Let the chaotic game of tag begin!</p><strong>Hoorah!
You just learned how to connect resources to a swarm and
produce and consume data with them!</strong>
<p>If you would like to see other examples of how you can
use BUGswarm, please visit the <a href=
"applications.html">Applications</a> page.</p>
</li>
</ul>
</div>
</body>
</html>