= Bossa tutorial = == Create a Bossa server == [ServerIntro Install the BOINC software] on a Linux system (or run the [VmServer BOINC virtual server] in a VMWare player on any computer). Use [MakeProject make_project] to create a BOINC project named "test": {{{ > cd boinc/tools > make_project --web_only test }}} Read '''~/projects/test/test.readme''' and do what it says. Let's say your server's domain name is "a.b.c". * Visit http://a.b.c/test/create_account.php and create an account for yourself. * Visit http://a.b.c/test_ops/bossa_admin.php. Follow the instructions to create the Bossa database. == Example application == We'll create an application in which volunteers view images, looking for ellipses on a noisy background. Their task is to click on the center of the ellipse, or to indicate that there is no ellipse. Here's an example: [[Image(bossa_test.png, nolink)]] (this has an ellipse slightly below/left of center). Visit http://a.b.c/test_ops/bossa_ops.php, and create an application with short name "bossa_example". The application is define by three scripts in ~/projects/test/html/: * '''ops/bossa_example_make_files.php''': this creates image files. * '''ops/bossa_example_make_jobs.php''': this creates jobs. * '''inc/bossa_example.inc''': display jobs and handle completed jobs. We'll go through these scripts and explain how they work. To develop your own Bossa applications you'll need to write corresponding scripts. == Creating jobs == To create some jobs, first we'll create some image files using the script [source:/trunk/boinc/html/ops/bossa_example_make_files.php html/ops/bossa_example_make_files.php]. {{{ cd ~/projects/test/html/ops mkdir ../user/example php bossa_example_make_files.php --nfiles 10 --dir example }}} This creates (in the '''examples/''' directory) 10 image files '''0.png''' to '''9.png''', and corresponding "answer" files '''0.ans''' to '''9.ans'''. Roughly half the images will have ellipses (you can specify this probability with '''--ellipse_frac x'''). Now, create jobs using [source:/trunk/boinc/html/ops/bossa_example_make_jobs.php html/ops/bossa_example_make_jobs.php]. {{{ php bossa_example_make_jobs --app_name bossa_example --dir example }}} This makes 10 jobs (one for each image in the directory) and collects them into a "batch". == Displaying jobs == The application is described by a PHP file ([source:/trunk/boinc/html/inc/bossa_example.inchtml/inc/bossa_example.inc]) that contains several functions. The first of these displays a job: {{{ function job_show($job, $inst, $user) { $info = $job->get_info($job); $path = $info->path; page_head("Find the Ellipse"); echo "
Click on the center of the ellipse. If you don't see one, click here:

id>
"; page_tail(); } }}} The second is called when a job is issued: {{{ function job_issued($job, $inst, $user) { $job->set_priority(0); } }}} It sets the job's priority to zero so that no further instances will be issued (unless this one times) out. The next function is called when a job instance is finished. It gets the user's response to the job, and stores it in the instance's app data field. {{{ function job_finished($job, $inst) { $response = null; if (get_str('submit', true)) { $response->have_ellipse = 0; } else { $response->have_ellipse = 1; $response->cx = get_int('pic_x'); $response->cy = get_int('pic_y'); } $inst->update_info($response); } }}} The next function is called when a job times out. It restores the priority to one so that the job will be issued to another volunteer. {{{ function job_timed_out($job, $inst, $user) { $job->set_priority(1); } }}} The remaining functions return short strings that show the app data for jobs, instances, and users on the Admin page: {{{ function job_summary($job) { $info = $job->get_info(); return "path>View image"; } function instance_summary($inst) { $info = $inst->get_info(); if ($info->have_ellipse) { return "($info->cx, $info->cy)"; } else { return "no ellipse"; } } function show_user_summary($user) { } }}}