Updated README

bcipy/helpers/README.md

@@ -20,7 +20,7 @@ Modules necessary for BciPy system operation. These range from system utilities
 - `system_utils`: utilities for extracting git version, system information and handling of logging
 - `task`: common task methods and utilities, including Trial and InquiryReshaper.
 - `triggers`: methods and data classes defining BciPy internal triggering
-- `validate`: methods for validating experiments and fields 
+- `validate`: methods for validating experiments and fields
 - `visualization`: method for visualizing EEG data collected in BciPy. Used in offline_analysis.py.
 
 
@@ -53,11 +53,11 @@ PREVIEW = "preview"
 
 ### TriggerHandler
 
-You can use the BciPy TriggerHandler to read and write any Triggers! 
+You can use the BciPy TriggerHandler to read and write any Triggers!
 
 ### Writing
 
-You will need three pieces of information to create a new handler for writing: 
+You will need three pieces of information to create a new handler for writing:
 
 1. path where trigger data should be written
 2. name of the trigger file without extension
@@ -85,15 +85,15 @@ handler.close() # this will call write one final time on any triggers added sinc
 
 ### Loading
 
-To load a BciPy triggers.txt file, the TriggerHandler load method can be used. Because it is a staticmethod, the class does not need to be initialized before the load method is used. 
+To load a BciPy triggers.txt file, the TriggerHandler load method can be used. Because it is a staticmethod, the class does not need to be initialized before the load method is used.
 
 ```python
 from bcipy.helpers.triggers import TriggerHandler
 
 path_to_trigger_save_location = './triggers.txt'
 
 triggers = TriggerHandler.load(path_to_trigger_save_location)
-# it will load in data like this: 
+# it will load in data like this:
 # [Trigger: label=[starting_offset] type=[offset] time=[-13149613.488788936], Trigger: label=[x] type=[prompt] time=[4.96745322458446]]
 ```
 
@@ -107,7 +107,7 @@ path_to_trigger_save_location = './triggers.txt'
 # exclude system triggers
 triggers = TriggerHandler.load(path_to_trigger_save_location, exclusion=[TriggerType.SYSTEM])
 
-# apply a 2 second offset to all timestamps loaded 
+# apply a 2 second offset to all timestamps loaded
 triggers = TriggerHandler.load(path_to_trigger_save_location, offset=2.0)
 ```
 
@@ -137,4 +137,41 @@ N target 3493.7257014
 X prompt 3495.4642608
 + fixation 3496.4697921
 Z nontarget 3496.9749562
-```
+```
+
+### Multiple Devices
+
+When multiple devices are in use, each device should provide its own starting_offset trigger. The trigger time should be the timestamp associated with the first sample in the data for that device.
+
+```python
+from bcipy.helpers.triggers import Trigger, TriggerType, offset_label
+
+# label can be any utf-8 compliant string
+eeg_offset = Trigger(offset_label(device_type='EEG'), TriggerType.OFFSET, -3400.0)
+eyetracker_offset = Trigger(offset_label(device_type='EYETRACKER'), TriggerType.OFFSET, -3450.0)
+```
+
+After adding other triggers, the resulting file will look something like:
+
+```
+starting_offset offset -3400.0
+starting_offset_EYETRACKER offset -3450.0
+N prompt 3490.3607581
++ fixation 3491.3668763
+Y nontarget 3491.8722132
+...
+```
+
+Triggers can then be loaded with timestamps relative to a device's start.
+
+```python
+from bcipy.helpers.triggers import trigger_decoder, TriggerType
+
+types, times, labels = trigger_decoder('triggers.txt', device_type='EEG')
+# types == ['prompt', 'fixation', 'prompt']
+# times == [90.36075810000011, 91.36687630000006, 91.8722131999998]
+# labels == ['N', '+', 'Y']
+
+_, times, _ = trigger_decoder('triggers.txt', device_type='EYETRACKER')
+# times == [40.36075810000011, 41.36687630000006, 41.872213199999806]
+```