Back to contents pageHow to get location events using the API

How to get location events using the API

Summary

This article shows an example that handles location events using the Ubisense .NET API.

Prerequisites

You should know the information in the following article:

How to create a cell hierarchy using Site Manager

Example material

Save this link to get a zip file of the example material

Guide

Multicell callback semantics

Multicell implements a non-standard establish state semantics for the client programmer. The basic idea is that multicell tries to simplify the user's view of the schema by translating establish state events into a set of change events. When a cell is loaded into a multicell schema, the schema will generate an insert event for every object in that cell; when a cell is unloaded, the schema will generate a delete event for every object in that cell; when an establish state event occurs on a cell, the schema will generate insert, update or delete events as appropriate to cover every change made in that cell since the last valid state of the schema.

Handling schema changes

Event handlers are always called with the schema locked by a write transaction, so you should not write any code that is likely to run slowly, and therefore block subsequent updates. This will result in establish events, which are treated in a non-standard way in this example, since a multicell is used.

Do not perform I/O operations in event handlers.

If you want to write location events to a file with real-time behaviour, you need to make a queue of location updates and write the file on a separate thread. Also, you should not use a multicell because you can get spurious event times, and possibly the same times repeated for different events. Instead, you should use Ubisense.ULocation.CellData, which appears in this article.

Do not use a multicell if you require real-time performance.

An alternative way to write location events to a file

The easiest way is to use the ubisense_monitor_receiver command-line program. In versions after 2.1.5, set a registry string value called managed_base_type in
My Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Ubisense 2.1\Platform\Config to the value location. Then use something like ubisense_monitor_receiver -f location -l my_logs_ to get trace from the "location" stream into a set of files, starting with my_logs_00000.txt.

Preparing the schemas

When a Location Cell gets a new location (through its sensor cells) its Location Cell Manager Service updates the Location relation and this triggers a location event. Your application can get notified of those events by using: a) a CellData schema to connect to the Location Cell that generates the events, or b) a Multicell object, whose loaded cells include the Location Cell that generates the events.

For this example, we will use a Multicell object like this:

    // Instantiate a Multicell object
    Ubisense.ULocation.MultiCell multicell = new Ubisense.ULocation.MultiCell();

    // Load all the available cells
    foreach (KeyValuePair<string, Ubisense.ULocation.Cell> cells
        in multicell.GetAvailableCells())
    {
        multicell.LoadCell(cells.Value, true);
    }

Creating the Event handlers

For each type of event, we need to create a method with the correct signature for that event. Most Ubisense event handlers take a row in their parameters list. The type of the row depends on the schema whose events we need to handle. In this case, the row should be of the type Ubisense.ULocation.CellData.Location.RowType. In the case of an update handler we get the old and the new rows:

    private void OnInsert(Ubisense.ULocation.CellData.Location.RowType insertedRow)
    {
        // Add your code here. Note that you cannot write to a file here and expect
        // correct real-time behaviour:
        // Event handlers are called with the schema locked by a write transaction,
        // so don't do anything slow. If your handler code has not finished when
        // another location event happens, the next event will be blocked, resulting
        // in an establish event. In this example, we are using a multicell, which
        // generates insert and update events from the established state.
    }
    private void OnDelete(Ubisense.ULocation.CellData.Location.RowType deletedRow)
    {
        // Add your code here
    }
    private void OnUpdate(Ubisense.ULocation.CellData.Location.RowType oldRow,
        Ubisense.ULocation.CellData.Location.RowType newRow)
    {
        // Add your code here
    }

Assign the handlers to the events of the Location Cells

The handlers will receive the events of the Location Cells that were loaded with Multicell object (If you use a CellData.Schema, the handlers will receive the events of the Location Cells to which you connect the CellData schema).

    // Add the handlers to the location events
    CellData.Location.AddInsertHandler(multicell.Schema, OnInsert);
    CellData.Location.AddUpdateHandler(multicell.Schema, OnUpdate);
    CellData.Location.AddDeleteHandler(multicell.Schema, OnDelete);

The sample application

1) What it does

Gets all the entries from the Naming schema and displays them in a listbox.
When the user selects an item from the listbox, the application sets the selectedObj.
When a location event occurs, the added event handlers will update the position of only the selectedObj in the corresponding labels.

2) Using the sample application

Open the Ubisense Site Manager tool to create and place some objects.
Now use the Simulator tool to create a script that moves any of the created objects.
Run the sample application and select the object in the script from the listbox.
Check how the selected object's position is displayed in the labels.