Birch Data log file format

This is a preliminary file specification.

The file name

The file is created and named when the thumb drive is inserted. This file is kept open and written to until the thumbdrive is removed.

The file name is generated from python using:

datetime.now().strftime("%Y%m%d-%H%M%S")

So a typical example filename would be "20230619-210314" (created at 9:03:14 pm on June 19, 2023).

Note: As of this writing the system date and time are typically very inaccurate because the Birch interface is normally not connected to the internet. This does not affect the accuracy of the tick values -- only the starting date and time of the file creation.

An Example

# This is a timestamp file.
# tick = f632216b File opened. t=0
# tick = f6ef0804 Handheld HHSC-1x4-CL auto-detected. Gains [2, 0, 1, 7, 0, 0, 0, 0] t=0
# tick = f70d3428 Output mode HID_KEY_BYGRT selected. t=0
0.000000 0f8 0
0.187791 0f0 1
2.174126 0f4 0
2.533666 0f0 1
3.548919 0f2 0
3.990385 0f0 1
4.909748 0f1 0
5.278569 0f0 1
# tick = f7e60197 Handheld selection set to None. t=0

Comment lines are begun with the # character.

The "tick" value is a 32 bit unsigned hex count for the number of microseconds elapsed since the count was started.

When a response device is selected a comment is put in the file to help make sense out of the data later.

When the output mode is chosen a comment is added for that, too.

The data are in 3 columns: time, bit pattern, and strobe bit

The strobe bit should just alternate from one line to the next. If you see two zeroes or two ones there it probably means there is an error.

The bit pattern is:

D9	D8	D7	D6	D5	D4	D3	D2	D1	D0	data bits
	TRG	B5	B6	B7	B8	B1	B2	B3	B4	button order

Note that bits not corresponding to buttons (or the trigger) may be high or low and should be ignored.

Automated comment lines

When the user interacts with the Birch interface we try to record those interactions in comments in the timestamp file. And after each of these interactions we reset the human-readable time values to 0, to make it easy to see how long after that interaction it was until the timed events occurred.