{"id":466,"date":"2017-05-18T11:31:28","date_gmt":"2017-05-18T15:31:28","guid":{"rendered":"http:\/\/www.talariavr.com\/blog\/?page_id=466"},"modified":"2017-05-18T11:31:28","modified_gmt":"2017-05-18T15:31:28","slug":"vive-tracker-documentation-archive","status":"publish","type":"page","link":"http:\/\/www.talariavr.com\/blog\/vive-tracker-documentation-archive\/","title":{"rendered":"Vive Tracker Documentation Archive"},"content":{"rendered":"

This page is outdated. \u00a0I’ve kept it on the site in the event anyone needs it for archival reference, but please direct your attention to <\/span><\/strong>www.talariavr.com\/blog\/vive-tracker-initial-documentation<\/span><\/span><\/a> for up-to-date inf<\/span>ormation<\/span>.<\/span><\/strong><\/span><\/p>\n

The following post was published on 27 March, 2017. \u00a0It was briefly updated on 7 April, 2017.<\/span><\/strong><\/p>\n

\u00a0<\/span><\/strong><\/p>\n

* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0<\/span>* \u00a0* \u00a0* \u00a0* \u00a0*<\/span>
\n<\/span>UPDATE:<\/span><\/strong><\/span><\/p>\n

REDDIT USER \/U\/MATZMANN666 HAS CREATED AN ARDUINO LIBRARY, SEE BOTTOM OF POST FOR MORE INFORMATION<\/span>
\n<\/span>* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0<\/span>* \u00a0* \u00a0* \u00a0* \u00a0*<\/span><\/span>
\n<\/span><\/strong><\/span><\/p>\n

<\/a>
\nHi friends – So I’ve spent the last few days familiarizing myself with (and troubleshooting) USB control of the Vive Tracker. \u00a0I wanted to simply get this information recorded quickly as to enable other developers to send data packets and edit controller state information of the Vive Tracker, and so because I’m prioritizing speed I can guarantee it’s not going to read gracefully. \u00a0I intend to rewrite this in a more properly documented report sometime in the future (I seem to be in a workflow of ~one blog post every other month).<\/span><\/p>\n

So, getting into the documentation: Below is various levels of abstraction on how I altered the Vive Tracker’s inputs. \u00a0All documentation is relevant as of 27 March, 2017<\/span>; it will likely change in the coming months! \u00a0I programmed on an Atmel AVR (the family of microcontrollers used in Arduino<\/span><\/span><\/a>) AT90USB647<\/span><\/span><\/a> chip at 8 MHz and 3.3V with an external 5V power supply to the USB lines. \u00a0It should be noted that the Vive Tracker requires a 5V source to initiate USB\u00a0communications. \u00a0Additionally worth noting, the Tracker does not externally supply\u00a0power, which means accessory makers at this time will need to implement a secondary battery into their USB-driving designs (this means to use a Vive Tracker USB accessory, users will need to charge both the Tracker and the accessory separately, and accessory manufacturing costs will increase due to the need of an independent\u00a0battery).<\/span>
\n
\n<\/span>1. The Feature Report<\/strong><\/span>
\n<\/span><\/p>\n

See Pages 50 – 52 (.pdf\u00a0file pages 60 – 62) of the USB HID Specification 1.11<\/a><\/span><\/span>\u00a0for reference on HID Set_Report requests. \u00a0This is the format for shipping out an HID Feature Report, values specific to the Vive Tracker payloads:<\/span><\/p>\n

bmRequestType<\/em>: 0b00100001 \u00a0 \u00a0 \u00a0\/\/ See Page 50 of HID Spec for bit descriptions<\/span>
\nbRequest<\/em>: \u00a0 \u00a0 \u00a00x09 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0\/\/ Value for SET_REPORT<\/span>
\nwValue<\/em>: \u00a0 \u00a0 \u00a0 \u00a00x0300 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0\/\/ MSB=Report Type (0x03, value for Feature report)<\/span>
\n\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0\/\/ LSB=Report ID (0x00, report IDs not used – Page 51)<\/span>
\nwIndex<\/em>: \u00a0 \u00a0 \u00a0 \u00a02 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \/\/ HTC’s selected Descriptor Index (I think)<\/span>
\nwLength<\/em>: \u00a0 \u00a0 \u00a0 sizeof(payload) \/\/ Size in bytes of the coming payload (Data<\/em> field, next line)<\/span>
\nData<\/em>: \u00a0 \u00a0 \u00a0 \u00a0 \u00a0{Data_Set_ADDR, Length_of_Following_Data, bData[0], bData[1], … , bData[n]}<\/span><\/span><\/div>\n


\nMSB = Most Significant Byte, LSB = Least Significant Byte.<\/span><\/p>\n

Below is an abstracted example for defining an accessory\u00a0connection and sending a payload declaring the trigger held down halfway and menu button pressed. \u00a0Please note that as of 27 March, 2017 the\u00a0bit & byte values on Pages 25 – 26\u00a0of the\u00a0HTC Vive Tracker Developer Guidelines v1.3<\/a><\/span><\/span>\u00a0are incompletely, and in some cases incorrectly, defined (rectified later, below).<\/span><\/p>\n

bmRequestType<\/em>: 0b00100001<\/span>
\nbRequest<\/em>: \u00a0 \u00a0 \u00a00x09<\/span>
\nwValue<\/em>: \u00a0 \u00a0 \u00a0 \u00a00x0300<\/span>
\nwIndex<\/em>: \u00a0 \u00a0 \u00a0 \u00a02<\/span>
\nwLength<\/em>: \u00a0 \u00a0 \u00a0\u00a05<\/span>
\nData<\/em>: \u00a0 \u00a0 \u00a0 \u00a0 \u00a0{0xB3, 3, 0x03, 0x00, 0x00}<\/span><\/span><\/div>\n
bmRequestType<\/em>: 0b00100001
\nbRequest<\/em>: \u00a0 \u00a0 \u00a00x09
\nwValue<\/em>: \u00a0 \u00a0 \u00a0 \u00a00x0300
\nwIndex<\/em>: \u00a0 \u00a0 \u00a0 \u00a02
\nwLength<\/em>: \u00a0 \u00a0 \u00a0\u00a012
\nData<\/em>: \u00a0 \u00a0 \u00a0 \u00a0 \u00a0{0xB4, 10, 0x00, 0b00000100, 0x00, 0x00, 0x00, 0x00, 0x00, 0x7F, 0x00, 0x00}
\n<\/span><\/span>
\n2. Rectified Byte Definitions<\/strong><\/span>
\n<\/span><\/div>\n

The manual fails to mention or make clear that the Data_Set_Address and Data_Count need to be included in the feature report.\u00a0 Bytes in my examples are read left-to-right, indexed at zero. \u00a0Bits are read right-to-left, also indexed at zero.<\/span><\/p>\n

ADDRESS: 0xB3
\nUPCOMING_DATA_COUNT (3)
\n0 – HOST_TYPE (2=PHONE, 3=ACCESSORY)
\n1 – RESERVED (CHARGE ENABLE, can’t be edited yet – Tracker will always leech power from host)
\n2 – RESERVED (OS TYPE, TBD)
\n{ 0xB3, 3, HOST_TYPE, 0x00, 0x00 }<\/span><\/div>\n
ADDRESS: 0xB4
\nUPCOMING_DATA_COUNT (10)
\n0 – NO VISIBLE FUNCTION (TAG INDEX)
\n1 – BUTTONS:
\n1.0 – TRIGGER (OVERRIDES ANALOGUE TRIGGER BYTE TO BE 0xFF, or at least I can confirm this occurs within Unity)
\n1.1 – GRIP
\n1.2 – APPLICATION MENU
\n1.3 – SYSTEM (Yes, it will open the dashboard)
\n1.4 – TOUCHPAD BUTTON (ONLY WORKS IF TOUCHPAD_CONTACT IS WRITTEN TO 1)
\n1.5 – TOUCHPAD_CONTACT (DOES NOT REQUIRE TOUCHPAD AXIS VALUES)
\n1.6 – RESERVED
\n1.7 – RESERVED
\n2 – TOUCHPAD_X_LSB (LSB = Least Significant Byte)
\n3 – TOUCHPAD_X_MSB (MSB = Most Significant Byte)
\n4 – TOUCHPAD_Y_LSB (LSB)
\n5 – TOUCHPAD_Y_MSB (MSB)
\n6 – NO VISIBLE FUNCTION (SHOULD BE TRIGGER_LSB)
\n7 – TRIGGER (SHOULD BE TRIGGER_MSB, OVERRIDES TRIGGER BIT OF BUTTON BYTE IF WRITTEN TO 0xFF. \u00a0Since byte 6 is unused we lose a whole byte of possible data transfer.)
\n8 – RESERVED (BATTERY_LSB?)
\n9 – RESERVED (BATTERY_MSB?)
\n{ 0xB4, 10, 0x00, BUTTONS, PAD_X_LSB, PAD_X_MSB, PAD_Y_LSB, PAD_Y_MSB, 0x00, TRIGGER, 0x00, 0x00 }<\/span>
\n
\n<\/span>3. Library Interfacing<\/strong><\/span>
\n<\/span><\/div>\n

USB protocols are not something you can just throw together in an afternoon – you’re going to want a library to handle all that overhead. \u00a0For the code snippet\u00a0below,\u00a0I used the\u00a0Lightweight USB Framework for AVRs (LUFA)\u00a0library by Dean Camera<\/a><\/span>, building upon the GenericHIDHost<\/span> demo found in …\/LUFA 151115\/Demos\/Host\/LowLevel\/GenericHIDHost<\/span>; coded in C++<\/span>.<\/span><\/p>\n

First I edited the makefile<\/span> to reflect my chip. \u00a0This blog post<\/span><\/span><\/a> by Joonas Pihlajamaa really helped me get started. \u00a0Below are the values I changed:<\/span><\/p>\n

\u00a0 MCU = at90usb647
\nBOARD = USER
\nF_CPU = 8000000<\/span><\/div>\n

I then went into GenericHIDHost.h<\/span> and removed any references to on-board LEDs or a serial output monitor, as my custom board did not have a definitions file for these things. \u00a0Then within GenericHIDHost.c<\/span>, this was the main function to perform the same task that was described at the end of Section 1<\/b> of this post:<\/span><\/p>\n

int main(void)<\/span>
\n{
\n. \u00a0 SetupHardware();
\n. \u00a0 GlobalInterruptEnable();
\n.
\n<\/span><\/span>. \u00a0 for(;;)
\n. \u00a0 {
\n. \u00a0 \u00a0 \u00a0 uint8_t\u00a0payload0xB3[5] = {0xB3, 3, 0x03, 0x00, 0x00};
\n. \u00a0 \u00a0 \u00a0 uint8_t payload0xB4[12] = {0xB4, 10, 0x00, 1 << 2, 0x00, 0x00, 0x00, 0x00, 0x00, 0x7F, 0x00, 0x00};
\n.
\n. \u00a0 \u00a0 \u00a0 WriteNextReport(payload0xB3, 0x00, REPORT_TYPE_FEATURE, 5);
\n. \u00a0 \u00a0 \u00a0 USB_USBTask();
\n.
\n. \u00a0 \u00a0 \u00a0 WriteNextReport(payload0xB4, 0x00, REPORT_TYPE_FEATURE, 12);
\n. \u00a0 \u00a0 \u00a0 USB_USBTask();
\n. \u00a0 }
\n}<\/span><\/span><\/div>\n

I’ve not yet tested how necessary\u00a0it is to write the 0xB3<\/span> report every frame, but I do know this bit got the Tracker to work reliably. \u00a0The other code I had to change was in the function WriteNextReport<\/span>\u00a0at the end of GenericHIDHost.c<\/span>. \u00a0Apparently wIndex<\/i><\/span>\u00a0was set to 0<\/span> by default, however HTC’s Vive Tracker requires wIndex<\/i><\/span> to be 2<\/span>.<\/span><\/p>\n

USB_ControlRequest = (USB_Request_Header_t)
\n{
\n.bmRequestType = 0b00100001,
\n.bRequest \u00a0 \u00a0 \u00a0= 0x09,
\n.wValue \u00a0 \u00a0 \u00a0 \u00a0= 0x0300,
\n.wIndex \u00a0 \u00a0 \u00a0 \u00a0= 2,
\n.wLength \u00a0 \u00a0 \u00a0 = ReportLength,
\n};
\n<\/span>
\n<\/span>4. A Low(er)-Level Look<\/strong><\/span>
\n<\/span><\/div>\n

Solely from picking apart Dean’s library, these would seem to be the primary steps that need to be performed in order to successfully communicate with the Vive Tracker:<\/span><\/p>\n

– Initiate USB as host
\n– Enumerate the attached USB device
\n– Read and process the device’s configuration descriptor
\n– Set the device to its initial configuration (Dean remarks that it’s unlikely to have more than one configuration)
\n> \u00a0 bmRequestType: 0b10000000
\n> \u00a0 bRequest: 0x09
\n> \u00a0 wValue: 1
\n> \u00a0 wIndex: 0
\n> \u00a0 wLength: 0
\n> \u00a0 Data: NULL
\n– At this stage, all the setup is now complete!
\n– To send a report:
\n> \u00a0 Prepare the bus\/pipe
\n> \u00a0 Feed it the header (bmRequestType, bRequest, wValue, etc.)
\n> \u00a0 Feed it the datastream (starting with {0xB_, etc.} )
\n> \u00a0 Return the bus\/pipe to its initial state
\n– Perform any other needed USB host tasks<\/span><\/div>\n

This section isn’t 100% solidified for me, simply because Dean did such a great job at constructing this library that once I was able to format the payload correctly for the Tracker, I had no more\u00a0need to dive into the low-level for troubleshooting. \u00a0If you’re using AVRs for your microcontroller, I highly\u00a0recommend Dean’s LUFA library!<\/span><\/p>\n

I am by no means proficient in USB HID communications, but if you run into any road blocks then feel free to reach out to me, perhaps I’ll be able to offer some advice as a result of my own troubleshooting.<\/span><\/p>\n

I made note of this at the top – if you think that it would be valuable for me to develop this into an library for USB Host-capable Arduino boards, please comment your interest below. \u00a0It could definitely help out if you explain what you would hope to use said library to do with the Vive Tracker.<\/del><\/span><\/p>\n

EDIT: Reddit user \/u\/matzmann666<\/a><\/span><\/span>\u00a0has wonderfully created a library for the Arduino Due ARM-based microcontroller! \u00a0Check out their GitHub page here:\u00a0github.com\/matzman666\/USBHost<\/span><\/span><\/span><\/p>\n

And lastly, I’d like to send a thousand thanks to Dario Laverde from HTC<\/span><\/a>, he was a great help in troubleshooting a lot of the feature report content, and I wouldn’t have Vive Trackers to work with if it weren’t for him. \u00a0Thank you, Dario!<\/span><\/p>\n

Alright, that’s all I’ve got for this quick and dirty documentation. \u00a0Next time you hear from me should be a little more developed, but I really wanted to get this info out there fast! \u00a0I hope some folks out there\u00a0find it useful :)<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"

This page is outdated. \u00a0I’ve kept it on the site in the event anyone needs it for archival reference, but please direct your attention to www.talariavr.com\/blog\/vive-tracker-initial-documentation for up-to-date information. The following post was published on 27 March, 2017. \u00a0It was briefly updated on 7 April, 2017. \u00a0 * \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* \u00a0* UPDATE: REDDIT USER \/U\/MATZMANN666 HAS CREATED AN ARDUINO LIBRARY, SEE BOTTOM OF POST…<\/p>\n

Read More Read More<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":""},"class_list":["post-466","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"http:\/\/www.talariavr.com\/blog\/wp-json\/wp\/v2\/pages\/466","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/www.talariavr.com\/blog\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"http:\/\/www.talariavr.com\/blog\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"http:\/\/www.talariavr.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/www.talariavr.com\/blog\/wp-json\/wp\/v2\/comments?post=466"}],"version-history":[{"count":5,"href":"http:\/\/www.talariavr.com\/blog\/wp-json\/wp\/v2\/pages\/466\/revisions"}],"predecessor-version":[{"id":471,"href":"http:\/\/www.talariavr.com\/blog\/wp-json\/wp\/v2\/pages\/466\/revisions\/471"}],"wp:attachment":[{"href":"http:\/\/www.talariavr.com\/blog\/wp-json\/wp\/v2\/media?parent=466"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}