Mask interfering LEDs

@rpavlik rpavlik released this Aug 5, 2016 · 6 commits to master since this release

This release contains a single change over the (just a few artificial moments earlier) previous one: several LEDs that are close to other LEDs and have bright pulses at the same time as their neighbors have been "masked out" - disabled in firmware so they do not turn on. This improves tracking reliability: when two LEDs are bright and close to each other, they often form a single blob on camera, which disrupts the continuous tracking of one or both LEDs, introducing a delay before they are fully re-identified, and in some cases making some LEDs almost impossible to identify in some circumstances. Additionally, this improves tracking range by increasing the distance from the camera achievable before LEDs blend together on camera. The masked LEDs were chosen by an algorithm operating on the patterns and the LED positions together with a cost function (source code is in this repository), then tested and found to provide improved performance.

disabled in v20160805 1

This does mean that when using this firmware with the existing video tracking plugin and calibration tool, some beacons will appear to be "missing" - this is expected and harmless (as noted above, it actually is better than harmless, there are still more than enough beacons to track).

Of course, this firmware does contain the improvements listed for the v20160805.0 release over the shipped/stock firmware as well.


Binary configuration/identification data:

[Sensics IR_LED_DRV (PRODUCTION) Built Aug  5 2016 15:29:27.Delay:5500,Bright:150,Interval:100,Dim:30,Lockout:1000]

Input data producing this mask:
/// 1-based indices WRT the tracking software of beacons we'd like to disable.
static const auto DISABLED_TARGET0_BEACONS = {33, 13, 18, 32, 34, 5};

/// 1-based indices WRT the tracking software of the beacons on the rear that never light up anyway.
static const auto DISABLED_TARGET1_BEACONS = {1, 4};

Masked LEDs determined by BrightNeighbors using distance-cost method, 7 passes (6 LEDs).

About the downloads

All attached binaries include a single, unified Intel hex file for the firmware built for an STM8S003K3 microcontroller (as found on the HDK IR board) with the HDK patterns, containing both the program flash and the EEPROM data: this can be split using a tool like SCat (from srecord tools), or your programming tool may be able to handle it as-is. Other files include the build and config identifier file and the mask description file.

Both the zip and exe (self-extracting 7z) marked "bundle" contain software and a single-step script to split and program the firmware onto the microcontroller. See https://github.com/OSVR/OSVR-Docs/blob/master/Utilities/HDKUpgradeIRBoardFirmware.md for more instructions.

This release is the first upgrade over the shipped firmware included with all known shipped OSVR HDK (at least 1.x) units to date. Substantial improvements include most importantly improved exposure timing and synchronization (using an empirically-determined setback from the sync trigger) with IR camera firmware version 0007, which improves beacon recognition overall and significantly reduces or eliminates loss of tracking during fast motion, especially fast rotation. Fairly in-depth details follow for the curious, but feel free to skip past them, down to the info about the downloads.

Interrupt now waits for rising edge of sync pulse before proceeding

This more closely matches what we've been told about the nature of the sync (that it matches the shutter behavior) and makes timing more consistent. We now proceed only once the falling-edge-triggered interrupt handler sees that the sync line has gone high again. (Triggering the interrupt directly on rising edge did not work, for unknown reasons.)

sync-start-precisely-on-rise

Precise timer-based delay after sync to target flash exposures to a single frame

LED flashes right at the sync pulse or even shortly after end up appearing on multiple output images, as these test images (with a firmware that fires a flash once every 3 sync pulses received, which should result in one frame with LEDs followed by two dark frames) show. In practice, this causes poor tracking in general, and loss of tracking during rapid movements due to ghosting.

flashing-once-every-third-sync-before

Careful experimentation determined a precise delay amount (5500usec, that is, 5.5ms), added as an additional state in the flash process state machine, as well as flash and interval durations that minimized this unwanted behavior. (These parameters are listed in the build ID posted with each binary release, in the file with each production build, and in plaintext in the actual firmware binary, called "Delay", "Bright", "Interval", and "Dim".) The following images are from another firmware built with the "every third sync" test mode as above, but using these final delay parameters: the frames look as expected now.

flashing-once-every-third-sync-after

Lockout period avoiding extraneous sync pulses

Particularly with longer delays, necessary to avoid ghosting, a second or extraneous sync event was sometimes seen during or shortly after the flash pulses. In the "every third sync" images, this manifests itself as the images not lining up neatly in columns, as the extra sync pulse is detected and gets counted as a "sync" without producing a frame on the PC. In operation, this would likely cause tracking loss on all LEDs due to loss of sync. A lockout period was implemented as an additional state following the flash process, during which no new transitions on the sync line are processed. (The duration of this period is also included in the build data like the delay and flash/interval durations, called "Lockout".)

screenshot 365

At least Delay and Lockout are expected to be fairly specific to camera firmware versions - these are tuned to v0007, the latest, and currently the only recommended, firmware for the OSVR HDK's IR camera.


Binary configuration/identification data:

[Sensics IR_LED_DRV (PRODUCTION) Built Aug  5 2016 15:19:37.Delay:5500,Bright:150,Interval:100,Dim:30,Lockout:1000]

Input data producing this mask:
/// No LEDs on target 0 (main HMD body) disabled

/// 1-based indices WRT the tracking software of the beacons on the rear that never light up anyway.
static const auto DISABLED_TARGET1_BEACONS = {1, 4};

About the downloads

All attached binaries include a single, unified Intel hex file for the firmware built for an STM8S003K3 microcontroller (as found on the HDK IR board) with the HDK patterns, containing both the program flash and the EEPROM data: this can be split using a tool like SCat (from srecord tools), or your programming tool may be able to handle it as-is. Other files include the build and config identifier file and the mask description file.

Both the zip and exe (self-extracting 7z) marked "bundle" contain software and a single-step script to split and program the firmware onto the microcontroller. See https://github.com/OSVR/OSVR-Docs/blob/master/Utilities/HDKUpgradeIRBoardFirmware.md for more instructions.