Sonic Imagination - Sensor Firmware

Firmware for the Imagination wireless head tracking sensor.

Table of Contents

• Sonic Imagination - Sensor Firmware
• Use
  • Wireless connection
  • OSC communication protocol
  • Wired connection (USB MIDI)
  • Button actions
  • Calibration procedure
• Build
  • Hardware
  • Library dependencies
  • Version history

Use

Wireless connection

The sensor acts as a wireless access point. The default network SSID is composed of the SSID body and the sensor index according to the settings in imag_config.h, e.g., ImagSens_7. The default network password is atmospheres. The sensor will offer an IP address to the client via DHCP.

After successful connection, the sensor starts streaming the orientation data to the client. Only one client can be connected at a time.

OSC communication protocol

The orientation data is sent using OSC (OpenSoundControl). Currently, the only message type is /rot x y z w (4 floats), which sends the orientation as a quaternion.

Wired connection (USB MIDI)

When connected to a host via USB, the sensor appears as a MIDI device. The orientation quaternion components are sent as 14-bit controller values using controller numbers 16/48 (w), 17/49 (x), 18/50 (y), 19/51 (z).

The MIDI data is compatible with the IEM MrHeadTracker DIY sensor and works fine with the IEM Plug-in Suite. You may have to switch the orientation convention, see section Button actions below.

Button actions

Refers to the buttons on the Featherwing OLED peripheral board.

• A Toggle display enablement. In any case, display will be switched off after 30 seconds (powersave).
• B Custom north
  • Short press: Set custom north (current front direction will become the new north reference), display will show [cstm].
  • Long press: Reset to magnetic north, display will show [magn].
• C Orientation conventions and calibration
  • Short press: Cycle through orientation conventions, e.g. [imag] (Imagination) or [iem] (MrHeadTracker compatibility).
  • Long press: Enter calibration mode.
  • When in calibration mode:
    • A Clear the currently stored dynamic calibration (experimental).
    • B Discard calibration and leave calibration mode (previous calibration will remain active).
    • C Store calibration and leave calibration mode.

Calibration procedure

Calibration procedure according to the BNO08x sensor documention:

• Enter calibration mode (long-press button C).
• Place the sensor stable and immobile for a few seconds, e.g., by putting on a table (gyroscope calibration).
• Place the sensor in 4..6 different, distinct directions and leave immobile for some seconds, e.g., the six plane areas of a cuboid (accelerometer calibration).
• Rotate the sensor around different axes evenly by 180 degrees and back over approx. 2 sec. per way (magnetometer calibration).
• The Accuracy measure displayed in the bar should become as high as possible.
• Save calibration (short-press button C).

The calibration settings will be persistent across power cycles.

Build

Hardware

The currently used sensor is made of

• Adafruit Feather M0 WiFi (SAMD21 + ATWINC1500)
• SlimeVR BNO085 IMU module
• Adafruit Featherwing OLED 128x64 (Display and button I/O)

The case version shown in the photo above uses an additional custom featherwing carrier board for the SlimeVR IMU module that also replicates the buttons of the OLED featherwing (A, B, C and reset) and adds a powerswitch, such that the case can protect the top of the feather stack for outdoor use.

Earlier prototypes used:

• Adafruit BNO085 IMU Fusion Breakout (I2C connected)

which has a different default I2C address. This can be easily adjusted in imag_config.h.

• Adafruit Featherwing OLED 128x32 (Display and button I/O)

Currently, the 0.5.3 firmware does not support the 128x32 display anymore, but the firmware modularisation that took place after the 0.1.0 version should facilitate creating an imag_display_ssd1306 class that implements the display controller communication and a suitable 128x32 layout similarly to what imag_display_sh1107 does for the 128x64 display.

Library dependencies

The firmware can be compiled using the Arduino IDE.

Please refer to the respective Adafruit documentation for installing the board files and support libraries:

• Feather M0 WiFi
• BNO085 IMU
• 128x64 OLED Featherwing

Additionally, the following libraries are used (installable via Arduino library manager):

• LiteOSCParser
• MIDIUSB
• EasyButton
• Arduino Low Power (currently not used)

Finally, this library needs to be installed manually (copied/checked out to Arduino libraries directory):

• Arduino-Helpers (Quaternion implementation)

Version history

• 0.5.3 simplified and modularised code, various fixes and improvements
• 0.1.0 initial release