Bossa tutorial

Create a Bossa server

Install the BOINC software on a Linux system (or run the BOINC virtual server in a VMWare player on any computer).

Use 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:

(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 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 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 (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 "
        <form method=get action=bossa_job_finished.php>
        Click on the center of the ellipse.
        If you don't see one, click here:
        <input type=submit name=submit value=None>
        <br><br>
        <input type=hidden name=bji value=$inst->id>
        <input type=image name=pic src=$path>
        </form>
    ";
    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 "<a href=".URL_BASE."$info->path>View image</a>";
}

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) {
}