API

Are you looking to build your plugin for VR  Tracker ? Include it in your project ? Good then, here is how to connect to the system to retrieve 3D positions !

VR Tracker Ecosystem - large
Here you can see that VR Tracker is made of 3 main components talking to each other :

– The Tags, mainly infrared LEDs that will be seen by the cameras

– The Cameras, analyzing the images and sending 2D coordinates of each Tag to the Gateway

– The Gateway, calculating 3D positions and controlling all the system

Now when you want to retrieve the 3D positions of your Tags, you have to connect to the Gateway, either from a PC, a smartphone, or even an ESP8266 ! All of those things, when connected to the Gateway, are considered as Users.

What’s great with this is that you don’t have to understand how the Cameras, Tags and Gateway work, all you need to know is how a User talks with the Gateway. That seems easier, isn’t it?

Here we will go through the connection protocol, we will see how to assign a Tag to a User and retrieve its 3D position.

Communication Protocol

To connect to the Gateway you have to create a Websocket Client. This is famous way to communicate with other devices, often used in video games too.

Here is a list of library to implement a websocket client in different languages. I haven’t tested all of them, so feel free to recommend other libraries 😉

You can find our Unity plugin here :

Unity Plugin V2

And some getting started project here :

https://github.com/VR-Tracker/Examples

 

All you have to implement is connectiondisconnectionsend datacallback to receive data

NOTE : for faster transfer we are using non secured WebSocket

 

Life of a User

Birth

 

Create a non secure websocket client to this URL address

“ws://vrtracker.local:7777/user/”

SEND your Unique ID (MAC address)

“cmd=mac&uid=ABC123”
uid : String (User’s Unique ID)

NOTE

The unique ID is very important to identify the device over multiple network (multiple gateway environnement), or to load parameters previously saved

 

Handle Tags

 

SEND Assign me Tag X

“cmd=tagassign&uid=TAG_ID”
uid : String (Tag’s ID you want to assign to you)
This will assign the Tag specified by its ID to you (the User)

SEND Assign a Tag

“cmd=assignatag”
This will assign a connected Tag to the user

SEND Assign all Tags

“cmd=assignalltag”
This will assign all the connected Tags to the User

RECEIVE Info Assignment success

“cmd=info&msg=assignmentsuccess&uid=tag_mac”
uid : String (Tag’s ID that was assigned to you)
Once you ask to assign a tag, you will receive the message containing the mac address of the tag if it was not sent to the gateway. And if the assignment was successful, you will receive this message

NOTE

The Tag Unique ID is printed on the Tag sticker, under the QR Code. It can also be retrieved by scanning the QR Code, or the NFC tag in the Sticker.
You can assign more than  one Tag to a user.

SEND Unassign Tag X

“cmd=tagunassign&uid=TAG_ID”
uid : String (Tag’s ID you want to unassign from you)
This will remove the link between the Tag, specified by its ID, and you (the User)

SEND Unassign all Tags

“cmd=tagunassignall”
This will remove the link between all Tags that were assigned to you (the User)

 

 

SEND Get Tag X informations

“cmd=taginfos&uid=TAG_ID”
uid : String (Tag’s ID you want the informations from)
This will ask the Tag to send you its informations like battery level, state (lost, found…)

RECEIVE Get Tag X informations

“cmd=taginfos&uid=TAG_ID&battery=47&status=lost”
uid : String (Tag ID)
battery : int (0-100)
status : String (“lost”, “tracking”, “unassigned”)
Those informations will be sent by the Gateway even if not requested by the User when the Tag gets lost and when it gets found again. This will allow you to display an information to tell the User to go back to the covered area.

 

 

RECEIVE Tag X position

“cmd=position&uid=TAG_ID&x=120.8&y=12.21&z=329.0&ox=27.9&oy=89.0&oz=12.2&ax=1.89&ay=0.012&az=0.21”
uid : String (Tag ID)
x : float (X position in world coordinates)
y : float (Y position in world coordinates)
z : float (Z position in world coordinates)
ox : float (X orientation, only if orientation is enabled)
oy : float (Y orientation, only if orientation is enabled)
oz : float (Z orientation, only if orientation is enabled)
ax : float (X acceleration, only if acceleration is enabled)
ay : float (Y acceleration, only if acceleration is enabled)
az : float (Z acceleration, only if acceleration is enabled)
Those informations will be sent by the Gateway at a certain frame rate as soon as the Tag is detected.

 

SEND Enable Tag X orientation

“cmd= orientation&orientation=true&uid=TAG_ID”
uid : String
orientation  : String (“true”, “false”)

 

SEND Enable Tag X acceleration

“cmd= acceleration&acceleration=true&uid=TAG_ID”
uid : String
acceleration  : String (“true”, “false”)

 

SEND Set Tag X color

“cmd= color&r=23&g=245&b=10&uid=TAG_ID”
r : int (0-255) red
: int(0-255) green
: int(0-255) blue
uid
 : String
This allows you to control the RGB Led on the Tag

 

SEND Tag X Special Command

“cmd=specialcmd&uid=TAG_ID&data=myspecialdata”
uid : String (Tag ID)
data : String
Those are special commands that can be defined by the user in the Tag software. This is used when the Tag has been modified into a controller (see below).

RECEIVE Tag X Special Command

“cmd=specialcmd&uid=TAG_ID&data=myspecialdata”
uid : String (Tag ID)
data : String
Those are special commands that can be defined by the user in the Tag software. This is used when the Tag has been modified into a controller (see below).

Miscellaneous

 

SEND User Battery

“cmd=usrbattery&battery=86”
(replace “86” with your User battery level in %)
This is only useful for the Master interface. Non mandatory.

Death

 

Think about disconnecting the Websocket client properly once you are done, and not just kill your app. It will notify the Gateway the User is leaving, and the Gateway will be able to handle that properly.

The disconnection will take care of removing the assignment to all Tags.

The secret Master

 

One interface has not been shown in the diagram above, it’s the Master interface. This is still a work in progress therefore we cannot disclose too much information about it before it is stable.

In a few words, the Master interface allows to get informations on the system. For example the battery level of every Tag, Camera and every User (if they share it). It gives

 

Build your Controller

 

Soon we will add informations on how to build your controller using the Tag ! You will be able connect buttons and stuff to turn a simple Tag into a LaserTag weapon by adding a trigger, or a Wand to move objects around in your VR environnement, the limit is your imagination !