This article shows how to set up a simple Ubisense real-time location
system on Windows, starting at the beginning. Links to explanations of
computing
and other technical terms are included - some are more widely known than
others! If you haven't heard of a specific term before, click the link.
You won't need to read more than the first couple of sentences for a real benefit.
Please report broken links to support@ubisense.net.
When you need to do some
action, this is an example of the format used.
None. You can use this article on its own.
You should have access to the following:
On your server machine, create a folder called something like "Ubisense release", where you will keep your Ubisense software. It is a good idea to keep this separate from any files you might create later, for example backups of your system or log files. There is potentially going to be a lot of data produced by your location system, so it is recommended that you keep things where they are easy to find. Save and extract your download in your new folder.
The first file you should find in the software release is the release note text file. This includes a
list of supported platforms, installation instructions and any changes made since the previous release.
The next file you need to access is the setup executable, located in your download at something similar to
setup/windows/Setup.Exe. Run Setup.Exe by double-clicking on it
(or, equivalently, run UbisenseSetup.msi).
When you run the setup program, you will see something similar to this:
Each item displays a short description when you click on it. The main point to note is that the "Servers"
item might not be selected by default. This is because in general, you will have one server machine and
as many client machines as you want. Select "Servers" to be installed on your machine
The other item that might not be selected by default is "Developer", which you should install if you have
purchased a Ubisense Developer Licence. You will never need to de-select any of the items that are selected by default.
Click through the installer to install the Ubisense software.
By default, the Ubisense software is now installed in something similar to
C:/Program Files/Ubisense 2.1. Shortcuts to the programs with a user-interface are installed
in your start menu folder, so you should access the Ubisense software via Start > All Programs > Ubisense 2.1.
Click on Start > All Programs > Ubisense 2.1 > Platform Control.
This is the only Ubisense program with a
user interface
that will start successfully at this point because it is the program that you use to run
the core services required by other Ubisense software.
One thing you could try at this point is running one of the other Ubisense programs,
for example "Map". You will repeatedly get a warning message and the program
won't start properly. The reason for the warning is that you haven't started any
services
yet. Then, if you get a similar warning in future, you will know why.
The first time you run Platform Control, you will get a warning about licences. Please do not take a screenshot of
the message. The warning message is automatically copied to your clipboard, so you should be able to
use Ctrl-v to paste the message into an email to support@ubisense.net.
When you receive your licence installer, you should save it in or next to the folder where you put the Ubisense
software download for safe keeping. Extract and run the licence installer.
If you restart Platform Control, it should now go straight to the main window without displaying the licence warning. The various controls are described in detail in the help manual, but here is a quick summary of the controls in version 2.1.7, described for new users. Read these through for now without changing anything - instructions will follow after:
ubisense_import_data_collection.
In our simple setup, your "core server" is the
same computer as your "service controller", but you can actually have as many controllers as you need to distribute
the load. After starting only UbisenseServiceController (not UbisenseCoreServer since there can be only one of these)
on other machines on the network, you would use Service Manager to configure this.
You can now install the rest of the services, which will be run on the controller (see next instructions).
Services are installed to your dataset using the Service Installer wizard.
This means that some of the files that you downloaded and saved in your "Ubisense release"
directory are going to be automatically copied into folders within the "dataset" directory
you chose in Platform Control. They will then be run automatically.
Click on Start > All Programs > Ubisense 2.1 > Service Installer.
The download you saved earlier contains the service executables,
so browse to setup/packages and click "Next". You should see a set of packages.
You will probably never need to do anything other than install all the available packages.
Click on "Select All" and then "Next", and click through to "Finish".
As services are installed, you will see the progress bar move. It might take some time, since some of the files
being copied are quite large, in particular in the "UBootstrap.xml" package. This package contains the code that
will run on your sensors.
Service Installer allows you to select any XML
file and attempt to install its package, which may or may not exist, depending on whether you actually
browsed to the Ubisense "packages" directory! If you get any error messages, you probably browsed to
the wrong place.
If you have 4 sensors, a simple configuration is a square with sides in the range of 10-30m. Mount the sensors at the corners of the square, near the ceiling for good line of sight across the tracked space. The sensors should point towards the floor in he middle of the space, and should have no roll. You must use a spirit level across the back of the sensor case to ensure there is no roll.
If your server and sensors are connected to an existing network with a DHCP server, go to the next section.
If you are at all unsure, do not follow the instructions in this section.
You will break the existing network if you run another DHCP server on it. If you continue with this section,
remember to stop the DHCP server before connecting to another network.
Software DHCP servers can be freely downloaded, for example from here. If you use this one, you should read the instructions in the readme, but you should only need a very simple configuration. You need to set it up to use the same subnet mask as the network card on your server, and set the "IPPOOL" to use a range of addresses on the same subnet.
You now need to connect the sensors to your server machine. "Master" and "Slave" sensors are physically the same.
The minimum requirement for your network cables is CAT5e.
Connect them as follows:
We have not connected anything to the other ports on the sensor yet. If your sensors are easily accessible, wait until the section on connecting timing cables. This will make it clear what the cables are for, and what will work, or not, if any of your cables are faulty. If your sensors are less accessible and it would save you time to connect all the cables at the same time, go to the section on timing cables now, then come back here.
You need to add your sensors to a "Location Engine Cell", or "Sensor Cell". This is done in Location Engine
Config (LEC). Click on Start > All Programs > Ubisense 2.1 > Location Engine Configuration.
Create a new Location Engine cell: click on Cell > New. If you plugged in your sensors
correctly, you should see their MAC addresses
in the "Available Sensors" section. Select LocationEngineCell 0001, then
drag the available sensors onto the map (anywhere will do).
Sensors should now start booting (flashing green light). Look at the "Log" tab in LEC
to see log messages coming from the sensors. When they are booted, if you didn't skip ahead and connect timing
cables, the sensor light flashes red/green continuously. This indicates that it is running, but there is no
"timing signal". Look at the "Sensor Status" tab in LEC. Your sensors should be in
the table with an indication that the timing signal is missing, but the "Last Seen" time should be updated
regularly, and the IP address should be as expected from your DHCP settings. If anything doesn't make sense,
check you have done everything in the instructions, and that your cables are connected correctly.
A sensor "flag" refers to a piece of software configuration that tells the sensor what to do. Double-click on a sensor in LEC to open the sensor properties dialog for that sensor. Go to the "Flags" tab. There are 3 flags that you need to know about now:
Factors affecting the choice of master sensor include that it needs to be able to communicate with Ubisense tags
thoughout the cell via a conventional radio channel. Factors affecting the choice of timing source sensor include
that it might need to receive a timing signal from an adjacent cell, wirelessly or via a cable.
Check the "Timing source", "Master" and "Reboot" flags for one of your sensors.
You now need to configure the cell to be the generator of a timing signal:
Double-click on the cell and check the "Generator" flag in the cell properties "Radio" tab.
This means that the cell will generate a timing signal - it doesn't receive it from any other cell.
The chosen sensor should reboot and get a steady green light, and be "Running" in the "Sensor Status" tab in LEC.
Now you should have one sensor with a steady green light and the rest should be flashing red/green/red/green...
This indicates that sensors are not receiving a "timing signal" (more on what this is coming up).
"Timing cables" should be at least shielded
Cat5e. Of the 6 ports on the sensor, the top-right is the "input". Any of the 6 is an identical
"output" from the timing source. Connect timing cables as follows:
Now, all your sensors should have a steady green light and "Running" should be shown in
the "Sensor Status" tab in LEC. Anything else should be treated as requiring some action.
At any time your system is running, any sensor without a
steady green light needs you to do something to fix it.
Now you have connected your sensors, you should really check again that they are level (zero roll) and
pointing sensibly, probably at the middle of the cell. Decide how accurate you want to be: if you are
going to dismantle the system at the end of this guide, just make sure sensors have not moved significantly
since you levelled them before and carry on with the survey. If you are going to leave the system in place
for a while, be more careful and orientate sensors as best you can. If you are setting up a permanent
system or you require good accuracy, practise until you can get the sensors perfectly level and orientated
correctly. You must ensure they cannot move or be knocked into a different orientation by anything.
Finally, tie up cables so they don't pull on the sensor.
A power threshold refers to the UWB
signal received by the sensor. If the received signal strength falls below the threshold, it is
rejected as random noise. Power thresholds have default values that may well work for your simple
setup, or they could produce completely useless results, depending on your radio environment. For
optimum results, you should always follow the instructions in this section to calibrate the thresholds.
Remove any Ubisense tags that are awake from your cell. Only if you have
woken any up by holding the button until the light on the tag goes out - either put them in a metal
box, move them far away, remove their batteries or put them in deep sleep
(LEC "Tags" tab > Tag menu > Battery... > "Deep Sleep" button).
In LEC "Sensor and Cells", right-click on the cell > Incident Power Plot... .
This displays the UWB received at each sensor. You must see no spikes in the graphs for this to work.
Spikes mean there is a Ubisense tag awake in the vicinity of the sensor. If you see only noise,
wait until the "Set Thresholds" button becomes enabled. The threshold
value is shown as a horizontal red line on the graph. Basically, it needs to be above the noise that
is coming in on the graphs. Click "Set Thresholds" to set the thresholds automatically
. Then, if you want, you can bring the tag(s) back to see the spikes in the received
power, and confirm that they are well above the threshold line.
You need to decide on a co-ordinate system. You are going to find the positions
of the sensors and at least one other point in the middle of the cell. These points will be saved in your
dataset. The other information that the system needs will be computed automatically when you calibrate the
cell: the orientation of the sensors and the length of the timing cables.
If you have a total station, go ahead
and measure the positions of the sensors. Get at least one
additional reference point in full view of each sensor. Ideally, this will be one point,
maybe marked on a desk or tripod where you can easily place a tag, in the middle of the cell.
If you only have a laser distance measuring device, LEC provides a mechanism to get your reference points.
To start, you will define (0, 0, 0) at the bottom corner of the room and (x, 0, 0) or (0, y, 0) at an
adjacent corner. Measure the length of the wall to get the second coordinate.
If your wall is 20m along your x-axis, you will have the reference points (0, 0, 0) and (20, 0, 0)
defined at the bottom corners. Take the height of the room if you are more likely to get a line of sight
to the top corners. Always define the floor to be z = 0.
To add a reference point in LEC, in the "Sensor and Cells" tab,
click on Map > Add survey points.... Read the instructions in the dialog
carefully. To add any points for which you already have coordinates, just type in the
coordinates to the "Candidate 1" text boxes, then type in the names
for the survey point group and point names. The group name could be something like
the name of the room you are in. Get into the habit of using unambiguous point names that are marked
on the real-world reference point. Ideally, if you can, you should mark reference points permanently
with a point name label and reflective laser target:
If you are just using a distance measuring device, you will now need to use the LEC tool to compute
the positions of the sensors and your additional reference in the middle of the cell. You might need
to get several intermediate reference points, depending on available lines of sight and required accuracy.
Measure 3 distances from each new point as instructed in the dialog.
For example, to get your first reference point after the room corners, the 3 distances will be to the
2 room corners discussed above, plus the height. Choose the candidate point
that matches, and click on "Add survey point" save it. Repeat until you get
all the sensors and a point in the middle of the cell, double-checked as you require. Again, if you
are going to dismantle the setup once you have finished going through this guide, just make sure the
points are approximately correct.
It might even be interesting to see what happens if you deliberately
get sensor positions wrong, maybe by a few centimetres, then by several metres or so they are incorrectly
swapped. You would see that you always get high accuracy at the point where you calibrate the cell,
which can be very misleading later!
You should now see your survey points in the "Sensor and Cells" tab of LEC. Click on the map and press "3" to go into 3D mode to check both heights and positions are correct.
You need to put the sensors at their surveyed position using the "Sensor Properties" dialog where you set the flags earlier. Double-click on a sensor, and select the "General" tab. This is where you edit the position of the sensor. Click on "Position at surveyed" to select its survey point. You can (but don't do it now) use "Point at surveyed" to set its approximate orientation to point at your survey point in the middle of the cell. Repeat the process to set the (x, y, z) coordinates of all your sensors using your survey points. You should never find yourself needing to type directly into the text boxes to set the sensor position, but to be flexible, you can if you want.
The next piece of information currently missing from your setup should be clear from the map: sensor
orientations. If you haven't changed them, sensors will all be pointing along the x-axis. Orientations
are computed automatically by using one of the calibration wizards in LEC. The basic idea is that you
put a Ubisense tag in a known position, tell LEC what that position is, then it takes readings of the
AoA from the tag and tells you
the orientation of the sensor from the average of set of measurements. If the calibration succeeds,
you save the results. Otherwise, you make sure the sensor can see the tag and try again. You will never
need to average any calibration results yourself - it is all done by one of the services through LEC.
We are going to use the "Orientation calibration" tool to get our sensor orientations.
Make a note of the tag id you are going to use, and make sure the tag is
"awake". Tags are shipped in "deep sleep" mode to save battery life. To wake one up,
press and hold the tag button until the light goes out. The light on the
tag should flash occasionally without you pressing the button when it is awake.
There is another type
of "sleep" mode that a tag can go into when it doesn't move. To disable this whilst we do the calibration,
set the "Disable sleep" flag on the master in the same way you made it the
master in the first place.
Right-click on a sensor and select "Orientation Calibration...". You then
need to follow the instructions in the wizard. When you click through,
as with sensor positions, don't type in coordinates directly - use the survey points you created.
If you followed the instructions all the way through, the selected sensor will now be correctly
orientated on the map. If it looks wrong, try again, reading the instructions both here and in the
wizard dialog carefully. If it looks correct, repeat the orientation calibration for
every sensor.
Right-click on the cell and click "Monitor" so your cell appears in the
"Monitored sensor cells" in LEC. You should see the angles of arrival from the tag to sensors as
green lines on the map. Carry a tag around the cell. If your orientation
calibrations were good, you will see the angles following the tag around and crossing approximately
at the tag location. At this point, you may or may not get a red sphere indicating valid tag locations.
The last essential data we haven't got are the "cable offsets": the length of the timing
cables. Therefore, our TDOA data
is not calibrated yet. To observe this, check the "TDOA" box in LEC to
show the blue curves along which where the system is trying (and probably failing) to put the tag.
Timing cables distribute a timing signal around the cell that is used to compute time differences
at the sensors. Therefore, without knowing cable lengths, the system produces incorrect TDOA curves.
This part is similar to when you calibrated the orientations, except that a cable offset is between
2 sensors. Therefore, the calibration uses 2 sensors: the sensor getting its cable offset plus the
reference sensor, which is ideally the master. Cable offsets are just some arbitrary number indicating
the offset from the master, so the master has a value of zero.
Right-click on a slave sensor and select "Cable Calibration...". You then
need to follow the instructions in the wizard.
If you followed the instructions all the way through, the selected sensor should have at least one
blue curve going through the tag. As you calibrate each sensor, more curves will intersect since
each one corresponds to a combination of 2 sensors. Repeat the cable calibration for
every slave sensor.
Carry the tag around the cell. As mentioned above, you can make some very
big mistakes and end up with perfect locations at the calibration point. You need to check the cell
operation all around the cell to confirm it is working.
A working cell will have AoA
and TDOA data from different
sensors that places the tag at a single point. In the LEC map, green lines are AoAs and depend
on the orientation calibration of the sensor to be correct. Blue curves are TDOAs and depend on
the cable calibration of the 2 sensors that produced the curve to be correct.
This how-to guide takes you through calibrating the sensors in 2 stages: orientation then cable offset. This is simply to illustrate what is happening. You should normally use the "Dual calibration" wizard, which performs both in one step. This produces exactly the same results (apart from random fluctuations which you need not worry about) as we got from doing the orientation and cable calibrations separately:
You should now have a working location engine cell, also known as a sensor cell.
To continue your Ubisense system setup, go to
How to set up a Ubisense system (2).
This will introduce things you haven't seen in this guide, including the following: