Integration using the Ubisense OTW Protocol

Overview

Ubisense provides ‘low level’ integration using a proprietary on-the-wire (OTW) protocol. This protocol is based on UDP and is designed to be easy to implement. The steps to implement the protocol are:

  1. Create a program to listen for UDP messages.

    You need to include the ability to specify the IP address / port number you want to listen on, for example by giving these on the command line.

  2. Prepare your DIMENSION4 system by ensuring you have stopped the Ubisense/Location System/Location sink registration service.

    Note: If you have installed SmartSpace as well as DIMENSION4, you must disable the Ubisense/Location System/Location sink registration service to prevent the registration service setting the sink address back to 0.0.0.0.0 after a short time.

  3. Specify the location cells.

    In the LSC, in the Change all parameters tab, go to Location Cell / V2 Location Sink / Address IPv4. For all the location cells you are interested in, set the value to the IP address / port number that your program is listening on.

    Note: The ability to edit the value of Location Cell / V2 Location Sink / Address IPv4 is only available from DIMENSION4 version 3.4/1.5.

These stages are described in greater detail in the Example OTW Protocol Client section which gives an example of a simple OTW implementation.

Message Format

Your program will receive UDP location messages, if tags are getting located. The message format is a 40-byte data payload with the fields laid out in this order:

Field

Length (bits)

Comment

Protocol ID

16

HEX E298 magic number

Message ID

16

HEX 026B magic number

Tag ID

64

The ID on the tag label

Flags

32

0 if not a valid location reading

X

32

IEEE float X position

Y

32

IEEE float Y position

Z

32

IEEE float Z position

Variance

32

IEEE float variance

Time

64

Timestamp (nanoseconds)

Example OTW Protocol Client

The example provides you with code to read location messages from a UDP socket and print them out, and to send location messages to the client for testing.

You are free to use this code to:

  • Get a better understanding of the OTW protocol so that you can implement it yourself in another language, or
  • Take the DLL containing the protocol implementation and use it directly in your projects as a .NET API to DIMENSION4, or
  • Treat the client programs as a starting point for your applications, or

  • Do anything else you like, for any purpose, as long as you accept the following standard disclaimer for our protection.

    Disclaimer

Before you start, ensure you have DIMENSION4 3.4/1.5 or later installed with all the relevant services.

Follow the instructions below to implement the OTW protocol.

  1. Download and unzip the supplied source code on your PC.

    The source code builds two programs (currently using the .NET Core environment):

    • DIMENSION4_OTW_CLIENT reads location messages from a UDP socket and prints them out
    • DIMENSION4_OTW_SENDER sends test location messages to a socket to test the client

  2. The programs publish to the folder Programs so that you can run them using the following commands:

    dotnet DIMENSION4_OTW_CLIENT.dll 10.42.5.125 47474
    dotnet DIMENSION4_OTW_SENDER.dll 10.42.5.125 47474

    Replace the IP address 10.42.5.125 with your own. You can also change the port from 47474 to a different port number if required.

  3. If you run the commands above you should see the client print lines of this form:

    Time 73BC0C1FD0ADF898: Tag 11CE0011223344 @ (10.000,20.000,30.000) variance 0.500
Time 73BC0C1FD6A81080: Tag 11CE0011223344 @ (10.000,20.000,30.000) variance 0.500
Time 73BC0C1FDCA35080: Tag 11CE0011223344 @ (10.000,20.000,30.000) variance 0.500
Time 73BC0C1FE29CB454: Tag 11CE0011223344 @ (10.000,20.000,30.000) variance 0.500
Time 73BC0C1FE89C330C: Tag 11CE0011223344 @ (10.000,20.000,30.000) variance 0.500
Time 73BC0C1FEEA15DB8: Tag 11CE0011223344 @ (10.000,20.000,30.000) variance 0.500
Time 73BC0C1FF49BB22C: Tag 11CE0011223344 @ (10.000,20.000,30.000) variance 0.500
Time 73BC0C1FFAA29AF0: Tag 11CE0011223344 @ (10.000,20.000,30.000) variance 0.500
Time 73BC0C2000A74450: Tag 11CE0011223344 @ (10.000,20.000,30.000) variance 0.500
Time 73BC0C2006AB4D88: Tag 11CE0011223344 @ (10.000,20.000,30.000) variance 0.500

  4. You can edit the programs using the latest VS 2017, for example to change the output format of the client.

  5. In Service Manager, stop (and undeploy and remove if you wish) the service Ubisense/Location System/Location sink registration which otherwise will overwrite your registered location sink address.

    If you have installed SmartSpace as well as DIMENSION4, you must disable the Ubisense/Location System/Location sink registration service. Otherwise, the registration service will set the sink address back to 0.0.0.0.0 after a short time.

  6. In the LSC, open the Change all parameters tab and edit the Location Cell / V2 Location Sink / Addess IPv4 property setting it to be the ( IP address : port ) you have used for the client (in this example 10.42.5.125:47474).

    Do this for each of the location cells from which you want to receive data.

  7. Having done this, assuming that you are getting location events, the client should start to print actual data like this:

    Time 120E2390E4B1B7D8: Tag 11CE0000000001 @ (1.799,0.462,1.004) variance 0.570
Time 120E2391027F0568: Tag 11CE0000000001 @ (1.804,0.442,1.007) variance 0.568
Time 120E2391204C4F10: Tag 11CE0000000001 @ (1.786,0.443,1.005) variance 0.573
Time 120E23913E19FE48: Tag 11CE0000000001 @ (1.802,0.451,1.003) variance 0.578
Time 120E23915BE7B938: Tag 11CE0000000001 @ (1.812,0.527,1.000) variance 1.500
Time 120E239179B61838: Tag 11CE0000000001 @ (1.856,0.451,1.026) variance 0.570
Time 120E23919793D8B8: Tag 11CE0000000001 @ (1.860,0.464,1.012) variance 0.547
Time 120E239198776E70: Tag 11CE0000000001 @ (1.850,0.466,1.008) variance 0.529
Time 120E23919E6D0920: Tag 11CE0000000001 @ (1.833,0.462,1.010) variance 0.528
Time 120E2391A453A010: Tag 11CE0000000001 @ (1.825,0.466,1.012) variance 0.528