Profiles.txt is a small text file that is placed in Bridgehead's settings folder. You can find this most easily by clicking on the 'Show file' button in the OSC Bridge Settings window. If you've got this far, you probably know this already.
OSC profiles are defined by four or more lines of text separated by a blank line (or the end of the file). Comment lines, that begin with a # character, are not included in this count and can be placed anywhere. Here is an example of a valid profile:
Yaw/Pitch/Roll (learnable)
/[yaw,pitch,roll]
yaw:1,pitch:1,roll:1
local 8000
The first line is the name of this profile as it will appear on the drop-down menu in the OSC Bridge settings.
The second line is an OSC address. It must start with a / character. If a standard well-formatted address is given, such as:
/ypr
then a single composite OSC message, containing an array of floats, will be sent. If certain parts of the address are enclosed in square brackets with comma-separated entries inside, for example:
/[yaw,pitch,roll]
then individual OSC messages will be sent. In the example above, /yaw, /pitch, and /roll will be sent individually.
Sending individual messages is less compact than sending arrays, and is less precise because it won't be obvious to the receiving program where a 'frame' of data begins or ends. There are two reasons why you might prefer them to composite messages:
The third line is a list of parameters separated by commas. These may be either yaw, pitch and roll, or quaternions: not a mixture of the two. The following parameters are accepted:
yaw |
Yaw angle [increasing anticlockwise] in degrees |
pitch |
Pitch angle [increasing upwards] in degrees |
roll |
Roll angle [increasing clockwise] in degrees |
yaw:r |
Yaw angle in radians |
pitch:r |
Pitch angle in radians |
roll:r |
Roll angle in radians |
yaw:0 |
Yaw angle mapped to [0,1] |
pitch:0 |
Pitch angle mapped to [0,1] |
roll:0 |
Roll angle mapped to [0,1] |
yaw:1 |
Yaw angle mapped to [-1,1] |
pitch:1 |
Pitch angle mapped to [-1,1] |
roll:1 |
Roll angle mapped to [-1,1] |
qw |
Real component of quaternion |
qx |
Imaginary component i or x of quaternion |
qy |
Imaginary component j or y of quaternion |
qz |
Imaginary component k or z of quaternion |
0 |
A zero, used by some profiles to pad out unused fields |
s:XXXX |
An unescaped constant string value. This example would send “XXXX”. (v1.26 on) |
Any numbers may be switched in polarity by placing a minus sign before the value (a plus sign is also accepted, but it doesn't do anything).
Angles, in whichever domain, can also be rotated in 90 degree increments (in case your plug-ins don't do what you expect them to do) by adding underscores to the end. For example:
-yaw__
reverses the polarity of yaw (so a clockwise rotation is positive) and rotates the sent value by 180 degrees.
The last line is the IP address (optionally) and port for the OSC, separated by a space. The port may be arbitrary (ports 7120, 8000, and 9000 seem to be common conventionally) or might be specific to a certain toolkit (for example, Facebook 360 used to use port 5125). Not specifying an IP address, or using the text local or localhost, will automatically map the IP address to 127.0.0.1. Otherwise you may specify a remote address using either IPv4 or IPv6 conventions.
Additional lines may be used to supply extra IP addresses or ports: the data will then be transmitted on all specified ports simultaneously.
When you change this file, hit 'Refresh' in the Bridge Pane to reload it manually. If the profile is currently selected, any changes you have made will take effect immediately.
Bridgehead supports the following incoming OSC messages:
/zero |
Zeroes the head tracker. Parameters are ignored. (v1.08 on) |
/travel,i |
Sets travel mode, taking one integer parameter. 0 is off; 1 is slow; 2 is fast. (v1.19 on) |
/connect,i |
Connects or disconnects the head tracker from MIDI. 0 to turn off; 1 to turn on; no parameter to toggle the current state. (v1.33 on) |
The receive port for this channel can be programmed in the profiles file by inserting a line beginning 'rx=' with the port number. For example, to set it to 9010 you would add rx=9010 on its own line. It doesn't matter where you put an rx line, but if it's missing, this feature will be turned off.
In later versions of Bridgehead you have multiple head trackers connected at once. If you want to control a specific one, the first parameter can be a string that refers to the serial number (in the format, for example, "100.414"). Otherwise, all connected head trackers will be affected.
If something goes wrong, you may want to look for a text file that generates in the same folder when Bridgehead tries to read it called ProfileErrors.txt. If a new profile is silently rejected, this will tell you why.
And if something goes terribly wrong, just delete the file, hit the ‘Refresh’ button in Bridgehead, and the default Profiles.txt will reappear.
From version 1.28, Bridgehead allows an IP address and port to be nominated on a line beginning raw=, such as:
raw=local 9900
When this is specified, raw sensor data from all connected head trackers will be sent to the nominated port. This is a fairly large quantity of control data that the head tracker does not otherwise need to send, so it is recommended that you specify a raw data port only if you intend to use it. There are three separate inertial sensors on the head tracker, called near, mid and far, with ‘near’ denoting the sensor nearest the USB connector. The following OSC addresses are used:
/raw/near/acc
/raw/near/gyro
/raw/mid/acc
/raw/mid/mag
/raw/far/acc
/raw/far/gyro
Each of these contains the device’s serial number as a string, and then x, y, and z floats. This is the unprocessed output of the inertial sensors. It is not influenced, for example, when the head tracker is zeroed. It is scaled so the outputs are in g for the accelerometers, degrees per second for the gyroscopes, and gauss for the magnetometer.
The three sensors work asynchronously. Each sensor sends its data at a regular rate similar to the one specified in the Bridge Settings panel. Disparities of a few hertz will have to be accommodated, though, so new data will not be framed in the same order each time.