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.

Thumbdrive format

Data will be logged in button box modes whenever a properly formatted thumbdrive is detected. (Data are not logged in joystick or mouse modes at this time.)

The Birch interface is a a bit inflexible about the thumbdrive format: it is looking for a block device with no partitions, which would appear in a linux system $lsblk listing as, for example, /dev/sda rather than /dev/sda1 or /dev/sda2.

Linux thumbdrive setup

It is vital in the steps that follow that you know which drive is your thumbdrive and you take care not to do these steps on other drives in your system. Doing this wrong could lead you to format your main drive which is usually disastrous, so please be careful.

First use lsblk to identify the thumbdrive ($lsblk) by inserting and removing the thumbdrive and running the command once in each condition.

Here's an example with no thumbdrive plugged in:

$ lsblk
NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
sda      8:0    0 111.8G  0 disk 
├─sda1   8:1    0     1M  0 part 
├─sda2   8:2    0   513M  0 part /boot/efi
└─sda3   8:3    0 111.3G  0 part /
sdb      8:16   1   1.5M  0 disk /media/bdugan/NODE_L552ZE

And here's that command again with the thumbdrive plugged in:

$ lsblk
NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
sda      8:0    0 111.8G  0 disk 
├─sda1   8:1    0     1M  0 part 
├─sda2   8:2    0   513M  0 part /boot/efi
└─sda3   8:3    0 111.3G  0 part /
sdb      8:16   1   1.5M  0 disk /media/bdugan/NODE_L552ZE
sdc      8:32   1  57.8G  0 disk 
└─sdc1   8:33   1  57.8G  0 part /media/bdugan/USB DISK

So in this case we're dealing with a device /dev/sdc, and it has one partition called /dev/sdc1.

Since it appears as here in the lsblk listing with a partition then you will first need to run gparted to delete the partition. Again, note that gparted might show drives other than your thumbdrive in its list so be careful.

Once the thumbdrive appears as just /dev/sdc (or it might be /dev/sda or something else in your case), run $sudo mkfs.vfat /dev/sdc to format it. At this point it will work for logging with Birch.