diff --git a/EmotiBitDataParser_reference_manual.md b/EmotiBitDataParser_reference_manual.md new file mode 100644 index 0000000..7ecf002 --- /dev/null +++ b/EmotiBitDataParser_reference_manual.md @@ -0,0 +1,155 @@ +# EmotiBit DataParser +The DataParser is used to convert the raw recorded data into parsed data files.
+Start by opening the EmotiBit DataParser on your computer. If you need more help with opening the Emotibit DataParser, +you may refer to the instructions on the [Getting Started](./Getting_Started.md/#Running-EmotiBit-software) page. + +## Parse raw data using EmotiBit DataParser + +### Transfer file from SD-Card to computer +The data recorded using EmotiBit is stored on the SD-Card. You can transfer the data from the EmotiBit to the computer in 2 ways. +1. **Using SD card reader** + - Remove the SD card from the EmotiBit. + - Plug it into the provided SD-Card reader provided with the Essentials kit or All-in-one-bundle. + - Plug the SD card reader into the computer. Once the Card is detected on the computer, you can simply copy the files to a location on your computer. +2.
Using a FTP server on EmotiBit (**only available on ESP32 Feather Huzzah**) + + - With the EmotiBit switched on and running, plug it into the computer using the provided USB cable. + - Make sure the EmotiBit is not recording data. + - Open a Arduino Serial monitor. For more details, check out this [FAQ](https://www.reddit.com/r/EmotiBit/comments/vmtz6w/how_i_use_the_arduino_serial_monitor_with_emotibit/). + - Select `baud rate`=2000000 and `No line ending` from the dropdown options. + - Type `F` into the input message bar and press Enter. + - You will see that the EmotiBit will enter FTP mode (red, blue, and yellow LEDs light up on EmotiBit). + - + - You you can trasnfer the files from EmotiBit using an FTP client. + - Download and install [Filezilla Client](https://filezilla-project.org/), if you do not already have it. + - Open Filezilla and follow the connection setup instructions as shown in this [link](https://mischianti.org/simple-ftp-server-library-now-with-support-for-wio-terminal-and-sd/#Configure_client) + - The `Host` IP address will be printed on the serial monitor. + - The default **user name** is `ftp` and the default **password** is `ftp`. You can change these values in the firmware. In the future, these credentials will be accessible using the `config` file. + - Once you connect to the FTP server, you can then drag any file from EmotiBit to any location on your computer (inside the FileZilla interface), and it will we copied over the WiFi! + - + - Reset the EmotiBit to exit the FTP mode and enter normal operation. +
+ + +### Parse raw data file + +The steps below describe how you can use the DataParser to parse the raw data file to generate individual parsed data files. +- Click on the `Load file` button to open a file browser. Navigate to the raw data(**csv**) file which you want to parse and select that file. +- The parser will show the progress as it parses the data. The DataParser quits automatically on completion. +- The parsed data files are created in the same directory as the original **raw data file**. + +![][EmotiBit-DataParser] + +For more details on the file types check out the section [below](). + + +### Parsed data file format +- The parsed data is stored in the following format + +|LocalTimestamp | EmotiBitTimestamp | PacketNumber | DataLength | TypeTag | ProtocolVersion | DataReliability | Data | +|---------------|---------------|---------------|---------------|---------------|---------------|---------------|---------------| +|Epoch time in seconds | EmotiBit time in milli-seconds (emotibit time resets everytime emotibit is rebooted) | Packet number the data point was extracted from (sequentially increases) | Number of data points in the packet | TypeTag of the data (see below) | Reserved for future extensibility | Reserved for future extensibility | Data points | + +- The format of the parsed data file can be changed by modifying the `parsedDataFormat.json` file. + -
parsedDataFormat.json file location + + - On Windows: `C:\Program Files\EmotiBit\EmotiBit DataParser\data` + - On macOS: `EmotiBitSoftware-macOS/EmotiBitDataParser.app/Contents/Resources` + - On Linux: `EmotiBitSoftware-linux/ofxEmotiBit/EmotiBitDataParser/bin/data` +
+ - **Note: If this file is erroneously modified, for example, the modified file does not conform to JSON standard (a missing `,` or `[` or `{`), the EmotiBitDataparser will skip loading this file. The parsed output, in this case, will be missing the `LocalTimestamp` column.** + +-
Adding LSL timestamp column by modifying parsedDataFormat + + To include the appropriate LSL time in the parsed output, just set the **addToOutput** to `true` in the `parsedDataFormat.json` file. + Note: LSL timestamps are only relevant if you are using a [LSL marker stream with EmotiBit Oscillosocpe](#timesync-with-lsl-using-marker-stream). + - Setting **LslLocalTimestamp** to `true` adds timestamps acording to the time on the local LSL clock of the system. + - Setting **LslMarkerSourceTimestamp** to `true` adds timestamps according to the time set on the +marker source generator system. + For example, if you want to add the timestamps as per your local LSL clock (the clock on the system running the EmotiBit Oscilloscope), the file should look like as shown below. + ``` + { + "timestampColumns": [ + { + "identifier": "TL", + "columnHeader": "LocalTimestamp", + "addToOutput": true + }, + { + "identifier": "LC", + "columnHeader": "LslLocalTimestamp", + "addToOutput": true + }, + { + "identifier": "LM", + "columnHeader": "LslMarkerSourceTimestamp", + "addToOutput": false + } + ] + } + ``` + When **addToOutput** is set to `true`, an additional column is added to the parsed output, with the column header set as the `columnHeader` specified in the file above. +
+ +See below for a sample of the a parsed file of typetag AX (Accelerometer X axis) +-
Parsed data file example + + ``` + LocalTimestamp,EmotiBitTimestamp,PacketNumber,DataLength,TypeTag,ProtocolVersion,DataReliability,AX + 1726714786.598369,531473.000,17305,3,AX,1,100,-0.436 + 1726714786.598369,531473.000,17305,3,AX,1,100,-0.434 + 1726714786.598369,531473.000,17305,3,AX,1,100,-0.433 + 1726714786.638383,531513.000,17322,3,AX,1,100,-0.434 + 1726714786.678397,531553.000,17322,3,AX,1,100,-0.433 + 1726714786.718411,531593.000,17322,3,AX,1,100,-0.434 + 1726714786.758425,531633.000,17337,2,AX,1,100,-0.437 + 1726714786.798439,531673.000,17337,2,AX,1,100,-0.436 + 1726714786.838453,531713.000,17354,3,AX,1,100,-0.432 + 1726714786.878467,531753.000,17354,3,AX,1,100,-0.434 + 1726714786.918481,531793.000,17354,3,AX,1,100,-0.435 + 1726714786.958495,531833.000,17370,2,AX,1,100,-0.432 + 1726714786.998509,531873.000,17370,2,AX,1,100,-0.435 + 1726714787.038523,531913.000,17388,3,AX,1,100,-0.434 + 1726714787.078537,531953.000,17388,3,AX,1,100,-0.436 + 1726714787.118551,531993.000,17388,3,AX,1,100,-0.434 + 1726714787.158565,532033.000,17402,2,AX,1,100,-0.434 + 1726714787.198579,532073.000,17402,2,AX,1,100,-0.433 + 1726714787.238593,532113.000,17419,3,AX,1,100,-0.435 + 1726714787.278607,532153.000,17419,3,AX,1,100,-0.432 + 1726714787.318621,532193.000,17419,3,AX,1,100,-0.434 + 1726714787.358635,532233.000,17435,2,AX,1,100,-0.435 + 1726714787.398649,532273.000,17435,2,AX,1,100,-0.433 + 1726714787.438663,532313.000,17455,3,AX,1,100,-0.435 + 1726714787.478677,532353.000,17455,3,AX,1,100,-0.434 + ``` +
+ +### Batch parsing +- The parser can currently be run from the command line with the filename (to be parsed) passed as an argument. +- We have created a [shell script](https://github.com/EmotiBit/ofxEmotiBit/blob/master/EmotiBitDataParser/bin/EmotiBitDataParser.sh) to leverage this functionality and "batch parse" multiple files in 1 go. + - Just grab the script from the repository and run it with the correct arguments. +- As an example, you can place all your raw files in a folder, let's say `data`. + - Then you can run the script as `./EmotiBitDataParser.sh -x "C:\\Program Files\\EmotiBit\\EmotiBit DataParser\\EmotiBitDataParser.exe" -d "path\\to\\data"` + - The parser will then parse all the files present in the data folder. +- We plan to further bake this into the software by making this a part of the GUI and it will be rolled out in a future release. + +### A note on Timesyncs +- We use periodic timesyncs from the EmotiBit Oscilloscope to improve the accuracy of the data timestamps on EmotiBit.The time syncing mechanism helps in correcting for any drift that may be introduced by the microcontroller clock. +- Timesync pulses are transmitted to Emotibit periodically, as long as the EmotiBit Oscilloscope is connected to EmotiBit. These timesyncs are written with the raw data on the SD-Card to help the DataParser with time calibration. +- The DataParser uses the timesyncs with the shortest Round-Trip-Times(RTT) to calibrate timestamps. The calibration works best if the raw data contains multiple timesyncs spaced throughout the recording. At minimum, the calibration requires 2 timesyncs. +- However, since timesyncs are only recorded while the EmotiBit is connected to the Oscilloscope, it is possible that the recorded data has fewer than 2 timesyncs. A scenario where the Oscilloscope was closed immediately after starting a recording session can lead to this situation. +- In cases where the EmotiBit DataParser finds fewer than 2 timesyncs, a warning will be displayed to the user after the file is parsed making them aware of the effect of having fewer than 2 timesyncs on the timestamp accuracy. + - +-
What to expect when you have 0 timesync events in the recorded file + + - **The values in the LocalTimeStamp will start from 0**. This is because the data does not have any timesyncs to create a relation between + EmotiBitTime and LocalTime. + - The data parser needs at least 2 timesync events to interpolate/extrapolate LocalTime. Hence, there will be no time correction to + any drift experienced by the emotibit clock. +
+-
What to expect when you have 1 timesync event in the recorded file + + - The values in the LocalTimeStanp column **will start form the Local Time corresponding to the moment the recording was initiated**. + - The data parser needs at least 2 timesync events to interpolate/extrapolate LocalTime. Hence, there will be no time correction to + any drift experienced by the emotibit clock. +
diff --git a/EmotiBitOscilloscope_reference_manual.md b/EmotiBitOscilloscope_reference_manual.md new file mode 100644 index 0000000..0960056 --- /dev/null +++ b/EmotiBitOscilloscope_reference_manual.md @@ -0,0 +1,401 @@ +# EmotiBit Oscilloscope +EmotiBit Oscilloscope offers the ability to stream data in real-time from EmotiBit to your computer along with an array of other features. + +Start by opening the EmotiBit Oscillosocpe on your computer. If you need more help with opening the Emotibit Oscilloscope, +you may refer to the instructions on the [Getting Started](./Getting_Started.md/#Running-EmotiBit-software) page. + +## EmotiBit Oscilloscope features +- The Oscilloscope offers the following features: +![][EmotiBit-Oscilloscope] + + -
Connecting to EmotiBit + + - The Oscilloscope displays all available EmotiBits on the network in a list. + - You can click on any EmotiBit in the list to connect to it. +
+ + -
Streaming real-time Data + + - The moment you connect to an EmotiBit, the EmotiBit Ocsilloscope will display the data being transmitted by the EmotiBit. + - Once a connection between the Oscilloscope and EmotiBit has been established, the EmotiBit Blue LED turns ON. + - The EmotiBit Blue LED stays on as long as the EmotiBit is connected to an Oscilloscope. +
+ + -
Recording Data + + - Select an EmotiBit from the list of available EmotiBits. + - You can initiate a record session by clicking on the record button. When a record session is initiated, the EmotiBit will start recording the data on the onboard SD-Card as well as stream it on the Oscilloscope. + - The EmotiBit Red LED starts blinking once a recording session has been initiated. + - You are free to move in/out of the network, close the Oscilloscope, or connect to a new Oscilloscope. + - We recommend using the EmotiBit in-network as much as possible, connected to the Oscilloscope. This helps in generating more time-syncs which improves timestamp accuracy. +
+ + -
Log note(labeling data) + + - Users can annotate data by adding labels/notes in real time. + - Type in the Note in the `Log Note` text box and click on the `Log Note` button to add notes to the data being recorded. +
+ + -
Power Modes + + The EmotiBit has 4 power modes. All modes can be accessed using the EmotiBit Oscilloscope. + - **Normal Mode**: In normal mode, the EmotiBit works with complete functionality, being able to record and transmit data. + - **Low Power Mode**: In Low power mode, the EmotiBit can record but cannot transmit data in real-time. It, however, continues to get the time-sync pulses. + - **WiFi Off**: The onboard WiFi shield is shut down in this mode. This saves power and enables longer recording sessions. + - A `short press` of the [EmotiBit button](https://github.com/EmotiBit/EmotiBit_Docs/blob/master/Getting_Started.md#emotibit-leds-and-buttons) toggles `normal mode` and `WiFi off mode`. + - If using the EmotiBit in `WiFi off` mode, we recommend toggling the EmotiBit to `normal mode` (short EmotiBit Button press) towards the end of the recording. Once in `normal mode` you can reconnect to the EmotiBit using the EmotiBit Oscilloscope and stream data for ~30 seconds to collect timesync pulses towards the end of the recording. + - **Sleep**: In sleep mode, EmotiBit stops any tasks it is performing and goes to sleep. + - A `long press` of the [EmotiBit button](https://github.com/EmotiBit/EmotiBit_Docs/blob/master/Getting_Started.md#emotibit-leds-and-buttons) can activate the sleep mode. + - We recommend switching the EmotiBit into `Sleep mode` instead of un-plugging the EmotiBit battery when not in use for short periods. + - If the EmotiBit is being left un-used for a long duration, it is best to flip the Hibernate Switch to `HIB`. + - Refer [EmotiBit LEDs and buttons section](./Learn_more_about_emotibit.md#LEDs-and-Buttons) for more information on the Hibernate switch. +
+ + -
DC/DO counter + + `Data Clipping` and `Data Overflow` are metrics that are used to determine data integrity. + + - `Data Clipping`: A clipping event occurs when the data recorded by any sensor goes out of the predefined bounds. + - `Data Overflow`: An overflow event occurs when the internal data buffers overflow, which results in loss of data samples. +
+ + -
Battery Level Indicator + + - The Battery Level indicator displays the charge available in the battery as a percentage. + - We recommend not letting the battery fall below 10% as it might begin to interfere with the sensor data acquisition. +
+ +## Using EmotiBit Oscilloscope to Record Data +Once you have succesfully set up your EmotiBit, you can start recording data using the EmotiBit Oscilloscope. If you have +not yet set up your EmotiBit, check our guide on the [Getting Started](./Getting_Started.md/#Running-EmotiBit-software) page. + + +### Active recording session indicator +You can check if a recording session is currently active by either checking the EmotiBit or the EmotiBit Oscilloscope. +- **Indication on the EmotiBit** + - You will notice that the EmotiBit RED LED starts blinking if a recording session is active. + - The EmotiBit RED LED will continue to blink till the active recording session has been stopped using the EmotiBit Oscillosocpe. +- **Indication on the EmotiBit Oscilloscope** + - When you open the Oscilloscope, all available EmotiBits on the network will be listed under the `device list`. Select the EmotiBit you are interested in from the device list. + - If a recording session is currently active, the name of the file being recorded appears below the `Record Button`. This name indicates the time when the recording was started. + - *Pro-tip: You can check the length of active recording by subtracting the current time from the time displayed in the `Recording section` on the Oscillosocpe.* + +[Click here to learn how to use the DataParser](#Parse-raw-data-using-EmotiBit-DataParser) to convert the raw data into parsed data files. +
If you want to learn about all the features offered by the EmotiBit Oscilloscope, check out the section [below](#EmotiBit-Oscilloscope-features). + + +### Output List +- The output list shows the options available to transmit the data out of the EmotiBit Oscilloscope. +- Each output protocol uses settings specified in the unique file name, defined in the sections below. +- Depending on your operating system, the settings file can be found in the locations listed below + - Windows: `C:\Program Files\EmotiBit\EmotiBit Oscilloscope\data\` + - macOS: `EmotiBitOscilloscope/Contents/resources/` + - Linux: `EmotiBit Oscilloscope/bin/data/` - +-
OSC + + - **EmotiBit Oscilloscope v1.2.0 and up** support the ability to transmit incoming data from an EmotiBit to a user-defined output channel using the OSC protocol. + - To enable OSC, just click on the `Output List` dropdown in the EmotiBit Oscilloscope and enable `OSC`. + - The EmotiBit Oscilloscope reads in and transmits out the data according to the specifications provided in the `oscOutputSettings.xml` file. + - You can find the settings file in the path mentioned above. + - You can modify the contents of this file to control the behavior of the OSC output stream. + - A snippet of the default contents are shared below + ``` + + + + EmotiBit + + + OSC + localhost + 12345 + + + + + PR + /EmotiBit/0/PPG:RED + + + PI + /EmotiBit/0/PPG:IR + + + PG + /EmotiBit/0/PPG:GRN + + + + ``` + - As you can see, the `input` is set to an EmotiBit, which is streaming data to the oscilloscope. + - The Oscilloscope takes this data and relays it over the IP-Address and Port specified. + - A `patch` connects an input stream to an output stream. In the snippet above, the input `PR` (PPG Red channel) stream is patched to the output stream called `/EmotiBit/0/PPG:IR` + - The `` tag should contain the Typetag of the data you want to relay. The available typetags can be found in the [section below](#EmotiBit-data-types). + - The `` tag should contain the name of the OSC stream you want to relay the data as. + - For example, to add SCR (Skin conductance response) metrics to OSC, you would add the following lines to the relevant section of the `oscOutputSettings.xml` file. + ``` + + SA + /EmotiBit/0/SCR:AMP + + + SR + /EmotiBit/0/SCR:RIS + + + SF + /EmotiBit/0/SCR:FREQ + + ``` + - When using the OSC protocol, at the receiver, you must use the same IP-Address, Port number, and label name you used as the output label here. To get started, check out this example of [OSC Oscilloscope as a receiver](https://github.com/produceconsumerobot/ofxOscilloscope/tree/master/oscOscilloscopeExample). If you have enabled OSC data transmission on the Emotibit Oscilloscope, you can run the example in the above link to plot the data being relayed by the EmotiBit oscilloscope. +
+ +-
UDP + + - **EmotiBit Oscilloscope v1.7.1 and up** support the ability to transmit incoming data from an EmotiBit to a user-defined output channel using the UDP protocol. + - To enable UDP, just click on the `Output List` dropdown in the EmotiBit Oscilloscope and enable `UDP`. + - The EmotiBit Oscilloscope reads in and transmits out the data according to the specifications provided in the `udpOutputSettings.xml` file. + - You can find the settings file in the path mentioned above. You can modify the contents of this file to control the behavior of the UDP output stream. + - A snippet of the default contents are shared below + ``` + + + + EmotiBit + + + UDP + localhost + 12346 + + + + + + ``` +
+ +-
LSL + + - **EmotiBit Oscilloscope v1.11.1 and up** support the ability to transmit incoming data from an EmotiBit to a user-defined LSL stream. + - To enable UDP, just click on the `Output List` dropdown in the EmotiBit Oscilloscope and enable `LSL`. + - The LSL stream details are provided in the `lslOutputSettings.json` file. You can find this settings file in the operating-system-specific location mentioned above. Modifying the contents on this file updates the LSL stream details being transmitted by the EmotiBit. + - The **patchcords** section in the documentation ties the input EmotiBit stream to the name of the output LSL stream. A complete list of EmotiBit data typetags can be found [here](#EmotiBit-data-types). +
+ +## EmotiBit Oscilloscope settings + +### Settings files location + +Based on the operating system, users can find the settings files in the following locations: +- For Windows users(Users will also need to give the file "write privileges". Check out this [FAQ](https://www.reddit.com/r/EmotiBit/comments/urp7dq/how_do_i_edit_files_installed_by_emotibit/) to learn how): + - `C:\Program Files\EmotiBit\EmotiBit Oscilloscope\data\` +- For mac users + - `EmotiBitSoftware-macOS/EmotiBitOscilloscope.app/Contents/Resources/` + - Note: Users need to right-click the `EmotiBitOscilloscope` application (*inside the software bundle just downloaded*) and click on `Show Package Contents`. You can then find the files in `Contents > Resources` +- For linux users + - `EmotiBitSoftware-linux/ofxEmotiBit/EmotiBitOscilloscope/bin/data/` + +### EmotiBit Oscilloscope network settings +The software release `v1.4.11` adds the ability for users to tweak their network settings using the `emotibitCommSettings.json` file. +Refer the [section above](#Settings-files-location) to locate this file on your system. + +-
emotibitCommSettings.json + + - `sendAdvertisingInterval_msec` allows users to specify how frequently (time in mS) they want the Oscilloscope to ping the network to find EmotiBit. The default setting should work in most cases and we recommend +changing this setting only if it is required by your network admin. + - `checkAdvertisingInterval_msec` allows users to specify how frequently (time in mS) they want the Oscilloscope to search for EmotiBit responses on the network. +Again, we recommend changing this setting only if it is required by your network admin. + - Users can now choose between `broadcast` vs `unicast` advertising. You can also specify ip ranges to ping for unicast! This will be beneficial for users that: + - are working with routers that block broadcast(ex: iPhone hotspot). Check out the note below for using the latest Oscilloscope(v1.4.11) with iPhone hotspot. + - perform poorly with unicast. The oscilloscope now uses broadcast by default, so it should just work... and work better! + - Specifically in `unicast mode` there are 2 more options available. Most users will never have to change these settings, but if you are working +in a constrained network environment, these settings may help to conform to network admin requirements. + - `nUnicastIpsPerLoop` specified the number of IPs you want to ping at time. + - `unicastMinLoopDelay_msec` specifies the min time to wait before trying to ping IPs on the network again. + - Ability to exclude or include networks while looking for EmotiBits. + - `excludeList`: If you don't want EmotiBit Oscilloscope to look for EmotiBit in a particular network, add it to the excludeList + - `includeList`: If you want EmotiBit Oscilloscope to look for EmotiBits ins specific networks, add it to the includeList + + **Special note for iPhone hotspot users** + + iPhone does not allow broadcasting on its hotspot. Since the new Oscilloscope(v1.4.11+) uses broadcast(for advertising) by default, users will have to make the following change in the emotibitCommSettings.json to use EmotiBit on iPhone hotspot. + 1. Locate the file (as suggested above) based on your operating system. + 2. change "broadcast" -> "enabled" to false + 3. change "unicast" -> "enabled" to true + 4. Save the file. + 5. Run the Oscilloscope app! + + The modified file should look like the snippet shown below. + ``` + { + "wifi": { + "advertising": { + "sendAdvertisingInterval_msec": 1000, + "checkAdvertisingInterval_msec": 100, + "transmission": { + "broadcast": { + "enabled": true + }, + "unicast": { + "enabled": true, + "ipMax": 254, + "ipMin": 2, + "nUnicastIpsPerLoop": 1, + "unicastMinLoopDelay_msec": 3 + } + } + }, + "network": { + "excludeList": [ "" ], + "includeList": [ "*.*.*.*" ] + } + }, + "lsl": { + "marker": { + "name": "", + "sourceId": "" + } + } + } + + ``` +
+ +### Using LSL with EmotiBit Oscilloscope +#### LSL output +You can use the EmotiBit Oscilloscope to relay incoming EmotiBit data to output LSL streams. Check out the [output list section](#Output-List) aboce for more details. + +#### Timesync with LSL using marker stream +EmotiBit oscillosocpe can ingest an LSL marker stream and use that stream to timestamp +EmotiBit data being recorded to LSL time. A marker stream is specified by a `name` and `sourceId`. By default the EmotiBit Oscilloscope searches for a LSL marker stream with the name `DataSyncMarker` and sourceId `12345`. You can create this stream by referring this [example](https://github.com/EmotiBit/ofxLSL/#example-for-generating-marker-stream). + +If you want the Oscilloscope to search for a different marker stream, please refer the steps below. + +-
Specifying LSL marker stream for EmotiBit Oscilloscope + + You need to specify the marker stream information in the `emotibitCommSettings.json` file. +Refer the [section above](#Settings-files-location) to locate this file on your system. + + For Example, an LSL marker stream with **name** `DataSyncMarker` and **source_id** `12345` can be specified in the `emotibitCommSettings.json` as shown below + ``` + { + "wifi": { + "advertising": { + "transmission": { + "broadcast": { + "enabled": true + }, + "unicast": { + "enabled": false, + "ipMax": 254, + "ipMin": 2 + } + } + }, + "network": { + "excludeList": [ "" ], + "includeList": [ "*.*.*.*" ] + } + }, + "lsl": { + "marker": { + "name": "DataSyncMarker", + "sourceId": "12345" + } + } + } + ``` + With the stream information specified, when you open the EmotiBit Oscilloscope, you can find the same information on the status bar (at the bottom of the Oscilloscope). The EmotiBit Oscilloscope will continue to search for the stream till it is detected. + + + Once detected, the EmotiBit starts receiving markers from the stream and displays a `markers received` count on the status bar. You need at least 2 markers during the recording to generate LSL timestamps. + + + Check out this [section](#Parsing-EmotiBit-timestamps-to-LSL-time) to enable the DataParser to add LSL timestamps in the parsed data. + + **Note: Please make sure that your marker stream has both a **name** and a **source_id**. Connecting to a stream that only has the **name** specified + can cause the Oscilloscope to crash, if the marker stream disconnects un-expectedly. This however, does not affect any data being recorded on the EmotiBit!** +
+ +### EmotiBit Oscilloscope display settings +Users can use the `ofxOscilloscopeSettings.xml` file to change other Oscillocsope settings. +Refer the [section above](#Settings-files-location) to locate this file on your system. + +-
Using ofxOscilloscopeSettings.xml file + + Each datastream is a `plot` on a `scope panel`. The example below shows the settings available for each scope. + ``` + + 25.000000000 ## represents the sampling rate of the signal + 10.000000000 ## duration of time represented in the scope + 0.000000000 ## min. signal threshold for display + 0.000000000 ## max. signal threshold for display + 0.000000000 ## min. allowed (yMax-yMin) + + 0 ## Plot ID. !! DO not change this. It should always follow the information specified in inputSettings.xml + PPG:RED ## Plot name displayed on the screen + ## Plot color in RGB channels + 255 + 69 + 78 + + + + ``` + Close any running Oscilloscope window. Change any setting in this file. Reopen EmotiBit Oscilloscope to see the changes take effect. + + As an example, if you are using the 100Hz PPG example, then the PPG plot settings look something like: + ``` + + 100.000000000 + 10.000000000 + 0.000000000 + 0.000000000 + 0.000000000 + + 0 + PPG:RED + + 255 + 69 + 78 + + + + + 100.000000000 + 10.000000000 + 0.000000000 + 0.000000000 + 0.000000000 + + 1 + PPG:IR + + 128 + 75 + 181 + + + + + 100.000000000 + 10.000000000 + 0.000000000 + 0.000000000 + 0.000000000 + + 2 + PPG:GRN + + 120 + 209 + 192 + + + + ``` +
+ +[EmotiBit-Oscilloscope]: ./assets/Visualizer_green_800px.gif "EmotiBit-Oscilloscope" diff --git a/Getting_Started.md b/Getting_Started.md index bc1eb32..fee3d01 100644 --- a/Getting_Started.md +++ b/Getting_Started.md @@ -1,120 +1,182 @@ # Getting Started with EmotiBit -[comment]: <> ([alt text][SideView]) +Welcome to EmotiBit! This guide will walk you through unboxing, setting up your hardware, and visualizing data for the first time. +Follow these steps in order to validate that your hardware is working perfectly. Even if you don't plan to use the Oscilloscope or record data immediately for your specific project, completing this walkthrough ensures your entire ecosystem is fully functional. # Table of Contents -- [ELECTRICAL SHOCK WARNING](#ELECTRICAL-SHOCK-WARNING) -- [Stack, Sense and Stream](#Stack-Sense-and-Stream) - - [EmotiBit Forum](#EmotiBit-Forum) - - [Unboxing](#Unboxing) - - [EmotiBit](#EmotiBit) - - [Essentials Kit](#Essentials-Kit) - - [Electrodes Kit](#Electrode-Kit) - - [All-in-One Bundle](#All-in-one-bundle) - - [Assembling your EmotiBit](#Assembling-your-EmotiBit) - - [Assembly step-1: Adding WiFi credentials](#Assembly-step-1-Adding-WiFi-credentials) - - [Assembly step-2: Stack your EmotiBit!](#Assembly-step-2-Stack-your-EmotiBit) - - [Compatible Feather Modules](#Compatible-Feather-Modules) - - [Installing EmotiBit Software](#Installing-EmotiBit-Software) - - [Install drivers](#Install-drivers) - - [Running EmotiBit Software](#Running-EmotiBit-software) - - [On Windows](#On-Windows) - - [On macOS](#On-macOS) - - [On Linux](#On-Linux) -- [Installing EmotiBit Firmware](#Installing-EmotiBit-Firmware) - - [Using the EmotiBit Firmware Installer](#Using-the-EmotiBit-Firmware-Installer) - - [Prerequisites](#Prerequisites) - - [Run EmotiBit Firmware Installer](#Run-EmotiBit-Firmware-Installer) - - [For Linux and Advanced Users](#For-Linux-and-Advanced-Users) -- [EmotiBit Bootup](#EmotiBit-Bootup) -- [Next Steps: Connecting to EmotiBit and Recording EmotiBit Data](#next-steps-connecting-to-emotibit-and-recording-emotibit-data) - - [1. EmotiBit Oscilloscope Network Connection](#1-emotibit-oscilloscope-network-connection) - - [2. Granting Network Permissions (Crucial Step)](#2-granting-network-permissions-crucial-step) - - [2.1 Permissions on Windows](#21-permissions-on-windows) - - [2.2 Permissions on macOS](#22-permissions-on-mscos) -- [After connecting to emotibit and recording data](#after-connecting-to-emotibit-and-recording-data) -- [Using EmotiBit Oscilloscope](#Using-EmotiBit-Oscilloscope) -- [EmotiBit: LEDs and Buttons](#EmotiBit-LEDs-and-Buttons) -- [Next Steps](#Next-Steps) -- [Troubleshooting](#Troubleshooting) - - -# ELECTRICAL SHOCK WARNING -EmotiBit should NEVER be worn while electrically connected to any device that's attached to A/C wall power. Connecting EmotiBit USB or any other pin to another device can be a shock risk hazard and should ONLY be done when EmotiBit is NOT in physical contact with the body. - - -# Stack, Sense and Stream - - - -- Follow the steps below for more information on downloading EmotiBit software and connecting to WiFi. - -## EmotiBit Forum - - -The [EmotiBit forum](http://forum.emotibit.com) is a great place to get answers to all things EmotiBit!
-- Find answers to questions you may have about using EmotiBit. -- Share your experience working with EmotiBit or the latest signal processing tools. -- Take a glance at the [EmotiBit FAQ](https://www.reddit.com/mod/EmotiBit/wiki/index/faqs). *Great minds think alike! If you have a question, the FAQ page probably has an answer.* -- Share your latest publication with the community or start a discussion about the future of biometric sensing! - -## Unboxing +- [Getting Started with EmotiBit](#getting-started-with-emotibit) +- [Table of Contents](#table-of-contents) +- [Learn About EmotiBit](#learn-about-emotibit) + - [What's in the Box? (Unboxing Component Guide)](#whats-in-the-box-unboxing-component-guide) + - [Compatible Feather Modules](#Compatible-Feather-Modules) + - [Understanding the Hardware: EmotiBit vs. Feather](#understanding-the-hardware-emotibit-vs-feather) + - [How EmotiBit Works & Communicates](#how-emotibit-works--communicates) +- [Setup Steps](#setup-steps) + - [1. Download and Install the Software Bundle](#1-download-and-install-the-software-bundle) + - [2. Install Drivers](#2-install-drivers) + - [3. Prepare the SD Card](#3-prepare-the-sd-card) + - [3.1 Adding WiFi credentials](#31-adding-wifi-credentials) + - [4. Stack your EmotiBit!](#4-stack-your-emotibit) + - [4.1 Pre-Assembly Configuration](#41-pre-assembly-configuration) + - [4.2 Stacking the Boards](#42-stacking-the-boards) + - [Understanding the LEDs and buttons on EmotiBit and the Feather](#understanding-the-leds-and-buttons-on-emotibit-and-the-feather) + - [5. Installing EmotiBit firmware](#5-installing-emotibit-firmware) + - [5.1 Run EmotiBit Firmware Installer](#51-run-emotibit-firmware-installer) +- [EmotiBit Bootup](#emotibit-bootup) +- [Next Steps: Connecting to EmotiBit and Streaming EmotiBit Data](#next-steps-connecting-to-emotibit-and-streaming-emotibit-data) + - [Permissions on Windows](#permissions-on-windows) + - [Permissions on macOS](#permissions-on-macos) +- [After connecting to emotibit and streaming data](#after-connecting-to-emotibit-and-streaming-data) +- [Troubleshooting](#troubleshooting) + +> [!CAUTION] +> **ELECTRICAL SHOCK WARNING**
+> **EmotiBit should NEVER be worn while electrically connected to any device that's attached to A/C wall power.** Connecting EmotiBit USB or any other pin to another device can be a shock risk hazard and should ONLY be done when EmotiBit is NOT in physical contact with the body. + + +# Learn About EmotiBit + +## What's in the Box? (Unboxing Component Guide) +Before you begin, make sure you have all the components included in your EmotiBit package: The following sections explain the contents of each item available for purchase at the [shop.EmotiBit.com](http://shop.emotibit.com/): -### EmotiBit +| Item | Contents | Image | +| :---: | :--- | :---: | +| **EmotiBit** | | | +| **Essentials Kit** | The Essentials kit contains everything you will need to get started with EmotiBit! In the box you will find:

| | +| **Electrodes Kit** | The electrodes kit has been designed for users who use multiple EmotiBits for research and intend to frequently swap out the electrodes. The electrodes kit includes:

| | +| **All-in-One Bundle** | If you purchased the All-in-One Bundle, you will receive the **EmotiBit**, **Essentials Kit**, and **Electrodes Kit** components detailed above. | *(Includes all items pictured above)* | -- **1x EmotiBit** with finger loop Emoti-stretch strap - - Depending on your purchase, you may either have an EmotiBit MD or an EmotiBit EMO -- **1x Emoti-genic barrier** (provides an additional hygienic layer and sweat protection) -- **2x EDA electrodes (Ag/AgCl)** attached to the EmotiBit -- **2x EmotiBit stickers** +#### Compatible Feather Modules + +> [!WARNING] +> If you are using your EmotiBit with a Feather **not included** as a part of the All-in-One Bundle or the Essentials Kit, please verify that you are using one of the 2 compatible Feathers. **Using EmotiBit with any other Feather module will not work.** + +-
Click this drop-down to see the compatible feathers + + | Adafruit Feather ESP32 Huzzah | Adafruit Feather M0 WiFi | + | :---: | :---: | + | Feather ESP32 Huzzah | Feather M0 WiFi | + +
+ + +## Understanding the Hardware: EmotiBit vs. Feather + +To get the most out of your device, it helps to understand how the two core boards work together as a team: +* **The EmotiBit** is the sensor module. It contains the dedicated biometric circuitry, specialized analog-to-digital converters, and high-fidelity sensors. It also features its own dedicated status LEDs and control buttons. +* **The Adafruit Feather** is the controller (MCU). It provides the main microprocessor, handles the software firmware execution, and manages the wireless network communication (WiFi) or local storage. It also has its own onboard LEDs and buttons distinct from the EmotiBit.
+Combining these two components creates a **stacked EmotiBit**. + + +### How EmotiBit Works & Communicates +EmotiBit is designed for real-time wireless data streaming, requiring an established local network connection between the hardware and the software host to function. + +1. **The EmotiBit Device:** The firmware running on the Feather board (stacked EmotiBit) processes raw sensor data from the EmotiBit and packages it. +2. **The Network Bridge:** The EmotiBit device transmits this data wirelessly over the local WiFi network. +3. **The EmotiBit Oscilloscope:** Your computer runs the **EmotiBit Oscilloscope** software. The Oscilloscope listens to the network, automatically detects the EmotiBit host, and streams the biometric data onto your screen in real time. + +> [!IMPORTANT] +> **Network Dependence:** Because the data passes through your local network, both your computer (running the EmotiBit Oscilloscope) and the EmotiBit must be connected to the exact same WiFi network. If your network has security settings that block device-to-device communication (common on enterprise or university networks), the data will not reach the screen. Don't worry—we will walk you through configuring and troubleshooting this during the setup phase! + +--- + +# Setup Steps + +## 1. Download and Install the Software Bundle + +The software utilities required to interface with EmotiBit are distributed as a unified release bundle. - +* **1.1** Navigate to the [EmotiBit GitHub Releases Page](https://github.com/EmotiBit/ofxEmotiBit/releases/latest) and download the asset bundle compatible with your operating system. + +* **1.2 OS-Specific Installation Instructions:** + + -
Installation Instructions For Windows Users + + * **Note:** EmotiBit software is supported only on Windows 10+. + * After downloading `EmotiBitSoftware-Windows.zip`, extract the zip file by right-clicking the file and selecting **Extract All...**. + * Open the extracted folder and double-click the `.exe` installer to run it. + * If the Windows Defender SmartScreen warning appears, click on **More Info**. + * Click **Run Anyway**. + * + * Follow the setup wizard prompts. Click **Close** once the installation is complete. + * Shortcuts for `EmotiBit Oscilloscope`, `EmotiBit DataParser`, and `EmotiBit FirmwareInstaller` will be created in your Start Menu . + * **Note:** The installation process may be blocked by active anti-virus software. If you encounter issues, verify your anti-virus settings permit third-party installations. You will also need to grant firewall permissions later to allow data streaming over your Wi-Fi network. +
+ + -
Installation Instructions For Mac Users + + * Download `EmotiBitSoftware-macOS.zip` from the release page. + * Move the downloaded zip file to your preferred directory. Double-click the `.zip` file to extract it. + * The applications are located directly inside the extracted folder. +
+ + -
Installation Instructions For Linux Users + + * Follow the dedicated installation instructions provided directly on the GitHub release page. +
+ + +## 2. Install Drivers + +> [!IMPORTANT] +> You must install the Virtual COM Port (VCP) drivers included in the software bundle to enable serial communication with the hardware via USB. + +* **2.1 OS-Specific Driver Installation:** + + -
On Windows 10 + + * Ensure you have extracted `EmotiBitSoftware-Windows.zip`. + * Navigate to `EmotiBitSoftware-Windows` > `CP210x_Windows_Drivers`. + * Double-click to execute `CP210xVCPInstaller_x64.exe`. + * Follow the on-screen instructions to complete the driver installation. +
-------------------------------- + -
On Windows 11 -### Essentials Kit + * Ensure you have extracted `EmotiBitSoftware-Windows.zip` (`Right-click > Extract All...`). + * Navigate to `EmotiBitSoftware-Windows` > `CP210x_Universal_Windows_Driver`. + * Right-click on `silabser.inf` (Setup Information file) and select **Show more options** > **Install**. *(Note: If the install option is missing, verify the zip file was fully extracted).* + * Grant any requested administrative or firewall permissions required by your system configurations. + * Once the process completes, the required drivers are installed. +
-The Essentials kit contains everything you will need to get started with EmotiBit! In the box you will find: -- **Adafruit Feather M0 WiFi** or **Adafruit Feather ESP32 Huzzah** -- **400mAh Lithium ion battery** -- **High-speed microSD card** -- **MicroSD card reader** -- **Micro USB cable** -- **3x Emoti-stretch straps** of different lengths (to wear EmotiBit nearly anywhere on the body, ranging from a child’s wrist to an adult's head) -- **Plastic spudger** (used to easily toggle the hibernate switch and EmotiBit button) + -
On macOS - + * Ensure you have extracted `EmotiBitSoftware-macOS.zip`. + * Navigate to the `EmotiBitSoftware-macOS` folder. + * Double-click `SiLabsUSBDriverDisk.dmg` to mount the disk image in Finder. + * Double-click `Install CP210x VCP driver` to launch the installer. + * Follow the on-screen prompts to complete the installation. +
-------------------------- -### Electrodes Kit -The electrodes kit has been designed for users who use multiple EmotiBits for research and intend to frequently swap out the electrodes. The electrodes kit includes: -- **10x EDA electrodes (Ag/AgCl)** -- **4x solder-cup snaps** (to add your own EDA leads) -- **5x Emoti-genic barriers** (provides an additional hygienic layer and sweat protection) - +## 3. Prepare the SD Card ---------------------------- -### All-in-One Bundle -If you purchased the All-in-One Bundle, you will receive the [EmotiBit](#EmotiBit), [Essentials Kit](#Essentials-Kit) **and** [Electrodes Kit](#Electrode-Kit). +### 3.1 Adding WiFi credentials ------------------- -## Assembling your EmotiBit +> [!IMPORTANT] +> EmotiBit requires a local Wi-Fi network to initialize and establish communication with the EmotiBit Oscilloscope application. You must add valid network credentials to the microSD card configuration file before using emotibit. See the following FAQs for more details. +> - For information on supported network options, see the [Network Options FAQ](https://www.reddit.com/r/EmotiBit/comments/11hjv49/what_are_the_available_network_options_to_use/). +> - For further contextual architecture details, see the [Oscilloscope Requirement FAQ](https://www.reddit.com/r/EmotiBit/comments/uqz726/do_i_require_emotibit_oscilloscope_to_start_a/). -### Assembly step-1: Adding WiFi credentials +* **3.1.1 Standard Configuration Procedure:** -- We first need to add the WiFi credentials to the SD card. EmotiBit needs a WiFi network to get started and connect to the EmotiBit Oscilloscope. See this [FAQ for more details](https://www.reddit.com/r/EmotiBit/comments/uqz726/do_i_require_emotibit_oscilloscope_to_start_a/). -- Check out this [FAQ](https://www.reddit.com/r/EmotiBit/comments/11hjv49/what_are_the_available_network_options_to_use/) to see some available network options to choose from. -- Plug in the MicroSD card reader loaded with the SD card into the computer. -- Download the config file from https://www.emotibit.com/files/config. -- Open the config file in any text editor (e.g. Notepad on Windows or text edit on macOS). -- Add your WiFi credentials by replacing `YOUR_WIFI_NAME_GOES_HERE` to the name of your WiFi network and change `YOUR_WIFI_PASSWORD_GOES_HERE`to the password for your WiFi network. - - -- Save the file onto your microSD card. Eject the SD card from your computer. + 1. Insert the microSD card into the provided reader and connect it to your computer. + 2. Download the default configuration file from [emotibit.com/files/config](https://www.emotibit.com/files/config). + 3. Open the downloaded configuration file using a standard text editor (e.g., Notepad on Windows or TextEdit on macOS). + 4. Locate the placeholder entries and replace `YOUR_WIFI_NAME_GOES_HERE` with your exact Wi-Fi network SSID and `YOUR_WIFI_PASSWORD_GOES_HERE` with your network password. + * + 5. Save the file onto your microSD card. Then safely eject the card from your computer. + +> [!NOTE] +> ```diff +> - EmotiBit only supports the 2.4GHz band for WiFi +> ``` +> Both the host computer and the EmotiBit need to be on the same 2.4GHz network. Initial experimental support for enterprise networks (that require a login/password after connecting) is available only for ESP32 Feathers. *The EmotiBit codebase uses several Arduino libraries to unlock different features, for example, establishing and maintaining a WiFi connection. The limitations around the support for enterprise wifi, for example, lack of support for Feather M0, are therefore dictated by these libraries and lie outside the scope of the emotibit ecosystem.* --
Multiple WiFi credentials +*
3.1.2 Multiple WiFi credentials - If you use multiple WiFi networks and want your EmotiBit to automatically connect to whichever one is in range, simply add both networks to the WifiCredentials array in the config file like this:
``` @@ -141,9 +203,9 @@ If you purchased the All-in-One Bundle, you will receive the [EmotiBit](#EmotiBi ```
--
Adding credentials using Serial Monitor +*
3.1.3 Adding credentials using Serial - - The EmotiBit firmware also provides a provision to enter WiFi credentials through serial interface. To use this provision, you will need to download and install Arduino IDE. You will also need to upload the EmotiBit firmware to the device. [Stack your EmotiBit](#stack-your-emotibit) and check out the section to learn how to use the [EmotiBit Firmware Installer](#installing-emotibit-firmware). Once you have installed the firmware and ArduinoIDE, proceed to the next steps. + - The EmotiBit firmware also provides a provision to enter WiFi credentials through serial interface. To use this provision, you will need to download and install Arduino IDE. You will also need to upload the EmotiBit firmware to the device. [Stack your EmotiBit](#4-stack-your-emotibit) and check out the section to learn how to use the [EmotiBit Firmware Installer](#5-installing-emotibit-firmware). Once you have installed the firmware and ArduinoIDE, proceed to the next steps. - Open Arduino IDE. Under `Tools > Port` notice the ports available, if any. - Make sure you have a stacked EmtotiBit and connect the Feather to the computer using the provided USB cable. - Once connected, check `Tools > Port` again in Arduino IDE. A new port will have appeared. Select that port. @@ -182,14 +244,7 @@ If you purchased the All-in-One Bundle, you will receive the [EmotiBit](#EmotiBi - The EmotiBit will restart and you will see Setup messages being printed on the Serial Monitor again.
- -**Note: Currently EmotiBit only supports the 2.4GHz band for WiFi. Both the host computer and the EmotiBit need to be on the same 2.4GHz network.** Initial experimental support for enterprise networks (that require a login/password after connecting) is available only for ESP32 Feathers. *The EmotiBit codebase uses several Arduino libraries to unlock different features, for example, establishing and maintaining a WiFi connection. The limitations around the support for enterprise wifi, for example, lack of support for Feather M0, are therefore dictated by these libraries and lie outside the scope of the emotibit ecosystem.* - -
Adding Enterprise WiFi credentials (only supported for ESP32 Feather) - - ```diff - -- Support for ENTERPRISE WIFI is still experimental. Connectivity and usability will vary and depend on your network conditions and rules. - ``` +*
3.1.4 Adding Enterprise WiFi credentials - Enterprise WiFi network details are added to the config.txt file in the following format. - If no `username` is provided, `userid` will be used as `username` @@ -225,119 +280,102 @@ If you purchased the All-in-One Bundle, you will receive the [EmotiBit](#EmotiBi - ESP32 takes a substantially long time to connect to an enterprise network (>10 secs as per our limited testing). - Since the ESP core is still under heavy development, there are some unexplained behaviors with enterprise connectivity. Through our testing, we discovered that using a software `restart` command before trying to connect to the enterprise network helps with connectivity. Therefore, if an enterprise network credential is added to the config file, the defined behavior is for the ESP to restart if a network connection is not made within a set timeout. - Unlike personal networks, enterprise networks can allocate devices on different subnets. For example, if your computer is on `192.168.100.150`, your EmotiBit may be allocated an IP `192.168.101.68`. Notice that they are on different subnets (`100` and `101`). For finer control over the subnets the Oscilloscope considers for device discovery, you can use the `includeList` section in the **emotibitCommSettings.json** file. You can find more information on that file in this [FAQ](https://www.reddit.com/r/EmotiBit/comments/urpucl/how_do_i_use_the_emotibitcommsettingsjson_file/). By default, all subnets are a part of the `includeList`. -
+
-### Assembly step-2: Stack your EmotiBit! +--- -- On the EmotiBit - - Insert the SD card into the EmotiBit. - - Make sure the sliding switch (*Hibernate switch*) is set to the active (not HIB) position as shown *(Available on only EmotiBit version V4+. The version is listed on the unique EmotiBit serial number attached to the back of EmotiBit.)*. - - ```diff - - CAUTION: Excessive force can break the HIB switch. Handle with care! - - ``` - - +## 4. Stack your EmotiBit! +## 4.1 Pre-Assembly Configuration + -- Plug the battery into the Feather (**ensure the connector is firmly pushed all the way into the Feather connector**) -- Stack the Feather with EmotiBit (*12 pin connector goes into the 12 pin socket and the 16 pin connector goes into the 16 pin socket*) +1. Insert the SD card into the EmotiBit. +2. Make sure the sliding switch (*Hibernate switch*) is set to the active (not HIB) position as shown *(Available on only EmotiBit version V4+. The version is listed on the unique EmotiBit serial number attached to the back of EmotiBit.)*. -![][EmotiBit-stackup] +> [!IMPORTANT] +> If the HIB switch is left in the HIB position, the device programming will fail in the next steps! -#### Compatible Feather Modules -- Currently EmotiBit supports 2 Adafruit Feathers, the [Feather ESP32 Huzzah](https://www.adafruit.com/product/3619) and the [Feather M0 WiFi](https://www.adafruit.com/product/3044). -

- - -

- -⚠️ If you are using your EmotiBit with a Feather **not included** as a part of the All-in-One Bundle or the Essentials Kit, please verify that you are using one of the 2 compatible Feathers. **Using EmotiBit with any other Feather module will not work.** ⚠️ +> [!CAUTION] +> ```diff +> - Excessive force can break the HIB switch. Handle with care! +> ``` -## Installing EmotiBit Software -[Download the EmotiBit Software](https://github.com/EmotiBit/ofxEmotiBit/releases/latest). --
Installation Instructions For Windows Users - - - _**Note:** EmotiBit software is supported only for Windows 10+._ - - After you download `EmotiBitSoftware-Windows.zip`, you need to `extract` the zip file. You can extract it by `Right-Click > Extract All...`. - - You will find an `.msi` installer inside the extracted folder. Run the installer by double-clicking. - - If the Windows Defender SmartScreen pops up, click on `More Info`. - - Then click on `Run Anyway`. - - - - Follow through the setup. Click on `Close` once the setup is complete and the EmotiBit Software has been installed. - - You will notice that shortcuts to `EmotiBit Oscilloscope`, `EmotiBit DataParser` and `EmotiBit FirmwareInstaller` have been created in the start menu and on the desktop. - - **Note: The EmotiBit Software installation process is sometimes blocked by any anti-virus tool you might have installed on your system. If you face any issues with installation, make sure to check that the appropriate settings are enabled on your anti-virus software to allow third-party installs. You will likely also need to allow firewall permissions to allow streaming data on your WiFi networks.** -
+## 4.2 Stacking the Boards --
Installation Instructions For Mac Users - - - Download `EmotiBitSoftware-macOS.zip` from the release page. - - Move the downloaded zip file to a folder location you desire. Double click on the .zip file to extract it. - - You will find the Applications in the extracted folder. + --
Installation Instructions For Linux Users - - - Follow the instructions on the release page. -
+1. Align the female header pins of the EmotiBit board with the male headers on the Adafruit Feather. +2. Gently press the boards together until the pins are fully seated. +3. **Ensure the connector is firmly pushed all the way into the Feather connector** -### Install drivers -Install the drivers provided with the downloaded EmotiBitSoftware bundle. +> [!IMPORTANT] +> At this point, the following checklist **must** be complete +> - [x] EmotiBit has the configured sd card inserted +> - [x] The HIB switch is not on "HIB" +> - [x] The battery is inserted into the Feather +> - [x] The EmotiBit and Feather have a secure fit + +
+
+
- -
On Windows 10 +--- - - If you have not done so already, extract the `EmotiBitSoftware-Windows.zip`. - - Navigate to `EmotiBitSoftware-Windows` > `CP210x_Windows_Drivers`. - - Double click to run `CP210xVCPInstaller_x64.exe` - - Follow the on-screen instructions to complete driver installation. -
+### Understanding the LEDs and buttons on EmotiBit and the Feather + - -
On Windows 11 +> [!NOTE] +> This image is for reference only. Status LEDs illuminate independently and at different stages during normal operation. - - Please make sure you have extracted the downloaded zip file `EmotiBitSoftware-Windows.zip`. To extract, `Right-click > Extract All...`. - - Navigate to `EmotiBitSoftware-Windows` > `CP210x_Universal_Windows_Driver`. - - Right click on `silabser.inf` (Setup Information) > `Show more options` > `Install`. (If you did not see this option, make sure you extracted the downloaded zip file). - - Depending on your firewall/antivirus settings you will likely need to grant permissions for the installation. - - Once completed, the required drivers should be installed on your Windows 11 machine. -
+
+
+
+
+
+
+
+
+
+
+
+
- -
On macOS - - If you have not done so already, extract the `EmotiBitSoftware-macOS.zip`. - - Navigate to `EmotiBitSoftware-macOS`. - - Double click on the `SiLabsUSBDriverDisk.dmg`. The contents will open in a new finder window. - - Double click on `Install CP210x VCP driver` to run the installer. - - Follow the on-screen instructions to complete the driver installation. -
+--- + -## Running EmotiBit software -Based on your operating system, follow the steps below: -### On Windows -You can click on the start menu and search for the name of the application you want to run, e.g.`EmotiBitFirmwareInstaller`. The application should pop up in the search. Double-click on the application to run it! -### On macOS -You can find the EmotiBit applications in the folder you just extracted (*as mentioned in the steps in the previous section*). +## 5. Installing EmotiBit firmware -### On Linux -Build the application from source. You can find instructions in the `ReadMe` provided with the zip file downloaded in the previous step. +> [!IMPORTANT] +> **Mandatory Action Required**
+> To start using your EmotiBit, you must first install the latest EmotiBit firmware onto the Feather. Because EmotiBit devices ship completely blank without any pre-installed firmware, the hardware will not function until this installation step is completed. +> [!IMPORTANT] +> If you did not order an **Essentials Kit** or an **All-In-One bundle**, you will need a [compatible Feather](#Compatible-Feather-Modules) to get starter. You can grab [Feather M0 WiFi](https://www.adafruit.com/product/3044) or the [Feather ESP32 Huzzah!](https://www.adafruit.com/product/3619) from the Adafruit online store. -# Installing EmotiBit Firmware -To start using EmotiBit, you will first need to install the latest EmotiBit firmware on the Feather. -- If you did not order an Essentials Kit, Basic-Kit (*Kickstarter*) or Research-Kit (*Kickstarter*), you will need to -get one to start using EmotiBit. You can grab [Feather M0 WiFi](https://www.adafruit.com/product/3044) or the [Feather ESP32 Huzzah!](https://www.adafruit.com/product/3619) from the Adafruit online store. +> [!IMPORTANT] +> **Prerequisites** +> Install required drivers, as explained in the [section above](#2-install-drivers). -## Using the EmotiBit Firmware Installer +### 5.1 Run EmotiBit Firmware Installer -### Prerequisites -- Install required drivers, as explained in the [section above](#Install-drivers). + -### Run EmotiBit Firmware Installer -- You will need the `EmotiBit FirmwareInstaller`, which comes with the EmotiBit software bundle. - - If you have not done so already, follow [these steps to grab the latest EmotiBit software](#Installing-EmotiBit-Software). -- Open the `EmotiBit FirmwareInstaller`. - - Follow the instructions mentioned in the [section above](#Running-EmotiBit-software) to start using `EmotiBit FirmwareInstaller` +- Open the `EmotiBit FirmwareInstaller` (downloaded as a part of the software bundle above). - After you start the application, follow the on-screen instructions to complete installing the firmware. -- Screengrab from `EmotiBitFirmwareInstaller` - - + +> [!TIP] +> If your firmware installation fails, confirm the following 3 are as expected +> 1. The ESP32 Drivers are installed as described in the [section above](#2-install-drivers). +> 2. Ensure you are using a data-capable USB cable. Charge-only cables will cause detection failures. The cable included in the EmotiBit bundles is tested to be data-capable. +> 3. Confirm that the HIB switch on the EmotiBit board is set to 'On' (not in HIB). + +
+
+
+ -
Installing custom firmware - The `EmotiBit FirmwareInstaller` installs the stock firmware provided in the software bundle. @@ -354,70 +392,74 @@ get one to start using EmotiBit. You can grab [Feather M0 WiFi](https://www.adaf Installing incompatible firmware may lead to unexpected behavior, or worse, may brick your device.
-## For Linux and Advanced Users --
Installing Emotibit Firmware on Feather M0 WiFi - - - **Note**: on macOS, you will need to give the `EmotiBit FirmwareInatller` application permissions to run the contained executables. To do so, right click on the `EmotiBit FirmwareInstaller` app and click on Open. This will open the application but you may close it to proceed below. - - The FirmwareInstaller essentailly performs 3 actions: - 1. Uploads the firmware updater sketch to prep the Feather for WINC updater - 2. Updates the WINC WiFi module FW to version 19.6.1 - 3. Uploads the latest EmotiBit FW onto the Feather, after the WINC has been updated - - We use the [`bossac`](http://manpages.ubuntu.com/manpages/bionic/man1/bossac.1.html) command line tool to upload binary files to the feather. - - There are 2 requirements to run bossac - - COM port on which the Feather is detected - - The bin file (*provided in the software release*). If your flavor of Linux doesn't work with the provided bin file, you'll have to download/compile `bossac` yourself, but ***WARNING: THAR BE DRAGONS*** - - Check out these [instructions on installing bossac](https://learn.adafruit.com/adafruit-feather-m0-express-designed-for-circuit-python-circuitpython/uf2-bootloader-details#running-bossac-on-the-command-line-2929769-30). ***PLEASE NOTE*** that with bossac version 1.9 or later, you must give an --offset parameter on the command line to specify where to start writing the firmware in flash memory. ***FAILING TO DO SO WILL BRICK YOUR FEATHER!*** - - To perform the operations manually, follow the listed steps below: - - Navigate to the `data` folder located inside the EmotiBit software directory. - - On Linux the path to the data folder should look like `EmotiBitSoftware-linux/ofxEmotiBit/EmotiBitFirmwareInstaller/bin/data` - - On macOS the path should look like `EmotiBitSoftware-macOS/EmotiBitFirmwareInstaller.app/Contents/Resources` - - On Windows the path will be `C:\Program Files\EmotiBit\EmotiBit FirmwareInstaller\data` - - Open a `cmd prompt` window for Windows or `terminal` for Linux/Mac at this location - - Connect the Feather to the computer using a data-capable USB cable - - **The Feather should NOT be stacked with EmotiBit** (to enable the programmer mode LED) - - Double-press the reset button to set the Feather in programmer mode. - - You should see the RED LED on the Feather pulsating! - - [ToDo: add gif] - - **WARNING: DO NOT UNPLUG OR RESET FEATHER WHILE UPLOAD/UPDATE IS IN PROGRESS. YOU COULD BRICK YOUR FEATHER!** - - Upload the firmware updater sketch by running the following command (*use .\bossac.exe for Windows*, *use ./bossac for macOS*) - - `./bossac_linux -i -d --port=YOUR_FEATHER_COM_PORT -U true -i -e -w -v ./WINC/FirmwareUpdater.ino.feather_m0.bin -R` - - [For Linux] If you get a `permission denied` error, run the command `chmod u+x ./bossac_linux`, to make the file executable. - - Update the WINC by running (*use .\FirmwareUploader.exe for Windows*, *use ./FirmwareUploader for macOS*) - - `./WINC/FirmwareUploader_linux -port YOUR_FEATHER_COM_PORT -firmware ./WINC/m2m_aio_3a0.bin` - - [For Linux] If you get a `permission denied` error, run the command `chmod u+x ./WINC/FirmwareUploader_linux` , to make the file executable. - - ONLY AFTER the FirmwareUploader command completes, double-press the reset button to set the Feather in programmer mode again - - Upload the EmotiBit FW using (*use .\bossac.exe for Windows*, *use ./bossac for macOS*) - - `./bossac_linux -i -d --port=YOUR_FEATHER_COM_PORT -U true -i -e -w -v EmotiBit_stock_firmware.ino.feather_m0.bin -R` -
- --
Installing Emotibit Firmware on Feather ESP32 Huzzah - - - **Note**: on macOS, you will need to give the `EmotiBit FirmwareInatller` application permissions to run the contained executables. To do so, - right click on the `EmotiBit FirmwareInstaller` app and click on Open. This will open the application but you may close it to proceed below. - - The FirmwareInstaller essentailly uploads the latest EmotiBit FW onto the Feather - - We use the [`esptool`](https://github.com/espressif/esptool/releases/tag/v3.3) command line tool to upload binary files to the feather. - - There are 2 requirements to run esptool - - COM port on which the Feather is detected - - The esptool bin file (*provided in the software release*). - - To perform the operations manually, follow the listed steps below: - - Navigate to the `data` folder located inside the EmotiBit software directory. - - On Linux the path to the data folder should look like `EmotiBitSoftware-linux/ofxEmotiBit/EmotiBitFirmwareInstaller/bin/data` - - On macOS the path should look like `EmotiBitSoftware-macOS/EmotiBitFirmwareInstaller.app/Contents/Resources` - - On Windows the path will be `C:\Program Files\EmotiBit\EmotiBit FirmwareInstaller\data` - - Open a `cmd prompt` window for Windows or `terminal` for Linux/Mac at this location - - Connect the Feather to the computer using a data-capable USB cable. - - The Feather should show up as a COM port on the system. - - On `Windows`: The device appears with a name similar to `COM X` (where `X` is a number) - - On `Mac/Linux`: You may find the COM port by running the terminal command `ls -la /dev/tty*` - - Pro-tip for Linux: the Feather may likely show up as `/dev/ttyUSB0` - - **WARNING: DO NOT UNPLUG OR RESET FEATHER WHILE UPLOAD/UPDATE IS IN PROGRESS. YOU COULD BRICK YOUR FEATHER!** - - replace **YOUR_FEATHER_PORT** with the COM port you detected in the previous step in the following command and run it to upload the firmware. - - `./exec/linux/esptool --chip esp32 --port YOUR_FEATHER_PORT --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 80m --flash_size 4MB 0x1000 ./esp32/EmotiBit_stock_firmware.ino.bootloader.bin 0x8000 ./esp32/EmotiBit_stock_firmware.partitions.bin 0xe000 ./esp32/boot_app0.bin 0x10000 ./EmotiBit_stock_firmware.ino.feather_esp32.bin` - - [For Linux] If you get a `permission denied` error, run the command `chmod u+x ./exec/esptool`, to make the file executable. - - [For Windows] replace `./exec/linux/esptool` with `.\exec\win\esptool.exe`. You will also need to change all file paths to `.\esp32\name-of-file` - - [For macOS] replace `./exec/linux/esptool` with `./exec/mac/esptool`. -
+- **Linux and Advanced Users** + -
Installing Emotibit Firmware on Feather M0 WiFi + + - **Note**: on macOS, you will need to give the `EmotiBit FirmwareInatller` application permissions to run the contained executables. To do so, right click on the `EmotiBit FirmwareInstaller` app and click on Open. This will open the application but you may close it to proceed below. + - The FirmwareInstaller essentailly performs 3 actions: + 1. Uploads the firmware updater sketch to prep the Feather for WINC updater + 2. Updates the WINC WiFi module FW to version 19.6.1 + 3. Uploads the latest EmotiBit FW onto the Feather, after the WINC has been updated + - We use the [`bossac`](http://manpages.ubuntu.com/manpages/bionic/man1/bossac.1.html) command line tool to upload binary files to the feather. + - There are 2 requirements to run bossac + - COM port on which the Feather is detected + - The bin file (*provided in the software release*). If your flavor of Linux doesn't work with the provided bin file, you'll have to download/compile `bossac` yourself, but ***WARNING: THAR BE DRAGONS*** + - Check out these [instructions on installing bossac](https://learn.adafruit.com/adafruit-feather-m0-express-designed-for-circuit-python-circuitpython/uf2-bootloader-details#running-bossac-on-the-command-line-2929769-30). ***PLEASE NOTE*** that with bossac version 1.9 or later, you must give an --offset parameter on the command line to specify where to start writing the firmware in flash memory. ***FAILING TO DO SO WILL BRICK YOUR FEATHER!*** + - To perform the operations manually, follow the listed steps below: + - Navigate to the `data` folder located inside the EmotiBit software directory. + - On Linux the path to the data folder should look like `EmotiBitSoftware-linux/ofxEmotiBit/EmotiBitFirmwareInstaller/bin/data` + - On macOS the path should look like `EmotiBitSoftware-macOS/EmotiBitFirmwareInstaller.app/Contents/Resources` + - On Windows the path will be `C:\Program Files\EmotiBit\EmotiBit FirmwareInstaller\data` + - Open a `cmd prompt` window for Windows or `terminal` for Linux/Mac at this location + - Connect the Feather to the computer using a data-capable USB cable + - **The Feather should NOT be stacked with EmotiBit** (to enable the programmer mode LED) + - Double-press the reset button to set the Feather in programmer mode. + - You should see the RED LED on the Feather pulsating! + - [ToDo: add gif] + - **WARNING: DO NOT UNPLUG OR RESET FEATHER WHILE UPLOAD/UPDATE IS IN PROGRESS. YOU COULD BRICK YOUR FEATHER!** + - Upload the firmware updater sketch by running the following command (*use .\bossac.exe for Windows*, *use ./bossac for macOS*) + - `./bossac_linux -i -d --port=YOUR_FEATHER_COM_PORT -U true -i -e -w -v ./WINC/FirmwareUpdater.ino.feather_m0.bin -R` + - [For Linux] If you get a `permission denied` error, run the command `chmod u+x ./bossac_linux`, to make the file executable. + - Update the WINC by running (*use .\FirmwareUploader.exe for Windows*, *use ./FirmwareUploader for macOS*) + - `./WINC/FirmwareUploader_linux -port YOUR_FEATHER_COM_PORT -firmware ./WINC/m2m_aio_3a0.bin` + - [For Linux] If you get a `permission denied` error, run the command `chmod u+x ./WINC/FirmwareUploader_linux` , to make the file executable. + - ONLY AFTER the FirmwareUploader command completes, double-press the reset button to set the Feather in programmer mode again + - Upload the EmotiBit FW using (*use .\bossac.exe for Windows*, *use ./bossac for macOS*) + - `./bossac_linux -i -d --port=YOUR_FEATHER_COM_PORT -U true -i -e -w -v EmotiBit_stock_firmware.ino.feather_m0.bin -R` +
+ + -
Installing Emotibit Firmware on Feather ESP32 Huzzah + + - **Note**: on macOS, you will need to give the `EmotiBit FirmwareInatller` application permissions to run the contained executables. To do so, + right click on the `EmotiBit FirmwareInstaller` app and click on Open. This will open the application but you may close it to proceed below. + - The FirmwareInstaller essentailly uploads the latest EmotiBit FW onto the Feather + - We use the [`esptool`](https://github.com/espressif/esptool/releases/tag/v3.3) command line tool to upload binary files to the feather. + - There are 2 requirements to run esptool + - COM port on which the Feather is detected + - The esptool bin file (*provided in the software release*). + - To perform the operations manually, follow the listed steps below: + - Navigate to the `data` folder located inside the EmotiBit software directory. + - On Linux the path to the data folder should look like `EmotiBitSoftware-linux/ofxEmotiBit/EmotiBitFirmwareInstaller/bin/data` + - On macOS the path should look like `EmotiBitSoftware-macOS/EmotiBitFirmwareInstaller.app/Contents/Resources` + - On Windows the path will be `C:\Program Files\EmotiBit\EmotiBit FirmwareInstaller\data` + - Open a `cmd prompt` window for Windows or `terminal` for Linux/Mac at this location + - Connect the Feather to the computer using a data-capable USB cable. + - The Feather should show up as a COM port on the system. + - On `Windows`: The device appears with a name similar to `COM X` (where `X` is a number) + - On `Mac/Linux`: You may find the COM port by running the terminal command `ls -la /dev/tty*` + - Pro-tip for Linux: the Feather may likely show up as `/dev/ttyUSB0` + - **WARNING: DO NOT UNPLUG OR RESET FEATHER WHILE UPLOAD/UPDATE IS IN PROGRESS. YOU COULD BRICK YOUR FEATHER!** + - replace **YOUR_FEATHER_PORT** with the COM port you detected in the previous step in the following command and run it to upload the firmware. + - `./exec/linux/esptool --chip esp32 --port YOUR_FEATHER_PORT --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 80m --flash_size 4MB 0x1000 ./esp32/EmotiBit_stock_firmware.ino.bootloader.bin 0x8000 ./esp32/EmotiBit_stock_firmware.partitions.bin 0xe000 ./esp32/boot_app0.bin 0x10000 ./EmotiBit_stock_firmware.ino.feather_esp32.bin` + - [For Linux] If you get a `permission denied` error, run the command `chmod u+x ./exec/esptool`, to make the file executable. + - [For Windows] replace `./exec/linux/esptool` with `.\exec\win\esptool.exe`. You will also need to change all file paths to `.\esp32\name-of-file` + - [For macOS] replace `./exec/linux/esptool` with `./exec/mac/esptool`. +
+ # EmotiBit Bootup +> [!IMPORTANT] +> The EmotiBit bootup sequence can only be followed IF the firmware was successfully installed in the previous step. + When EmotiBit is booting up, the LEDs are used to indicate the steps in the process. If EmotiBit gets stuck prior to fully connecting to your WiFi, you can use the below table to assess what went wrong and how to fix it. |LED State|**LED Indicator**|**What to do?**| @@ -425,24 +467,20 @@ When EmotiBit is booting up, the LEDs are used to indicate the steps in the proc |Feather RED LED ON||Write a post describing your steps on http://forum.emotibit.com/ | |Feather RED LED turns ON for a few seconds and then stays OFF||Check if SD card is correctly inserted| |EmotiBit RED LED ON||Check if config file is present on the SD card
AND
config file is formatted correctly (A missing `"` or missing bracket `{}`,`[]` can cause a parsing failure.)| -|EmotiBit BLUE LED solid ON||Verify correct WiFi credentials in config file (see [Adding WiFi credentials](#Adding-WiFi-credentials))| +|EmotiBit BLUE LED solid ON||Verify correct WiFi credentials in config file (see [Adding WiFi credentials](#31-adding-wifi-credentials))| |EmotiBit BLUE LED BLINKING||Huzzah! EmotiBit is connected to your WiFi! Open EmotiBit Oscilloscope to start streaming biometric data!| -# Next Steps: Connecting to EmotiBit and Recording EmotiBit Data -This section outlines the procedure for connecting to, streaming, and recording data from your EmotiBit using the EmotiBit Oscilloscope application. - -### 1. EmotiBit Oscilloscope Network Connection -The EmotiBit Oscilloscope communicates with the EmotiBit device over a WiFi network connection. For this communication to function, the Oscilloscope requires permission from your computer's operating system to access and use the local network. +# Next Steps: Connecting to EmotiBit and Streaming EmotiBit Data -### 2. Granting Network Permissions (Crucial Step) -The very first time you launch the EmotiBit Oscilloscope on your computer, your operating system (Windows or macOS) will prompt you to grant network access permissions to the application. +- The EmotiBit Oscilloscope communicates with the EmotiBit device over a WiFi network connection. For this communication to function, the Oscilloscope requires permission from your computer's operating system to access and use the local network. +- The very first time you launch the EmotiBit Oscilloscope on your computer, your operating system (Windows or macOS) will prompt you to grant network access permissions to the application. -Action Required: **You must grant the appropriate network permissions when prompted.** - -⚠️ ATTENTION: Without these explicit permissions, the EmotiBit Oscilloscope cannot detect or communicate with the EmotiBit connected to your network. Data streaming will fail. -The sections that follow provide a visual guide on how to navigate the permissions screen for your specific operating system. +> [!IMPORTANT] +> **Action Required: You must grant the appropriate network permissions when prompted.**
+> Without these explicit permissions, the EmotiBit Oscilloscope cannot detect or communicate with the EmotiBit connected to your network. Data streaming will fail. +> The sections that follow provide a visual guide on how to navigate the permissions screen for your specific operating system. -#### 2.1 Permissions on Windows +#### Permissions on Windows - When you open the EmotiBit Oscilloscope, the following pop-up will be displayed on your screen. -
Windows Security Alert pop-up (Windows Defender Firewall) @@ -450,7 +488,7 @@ The sections that follow provide a visual guide on how to navigate the permissio If you have an Antivirus program installed, make sure the appropriate settings are enabled to grant the EmotiBit Oscilloscope network access. -
-- You can update the Windows Defender Firewall settings at any time. In your Start menu, search for "Allow an app through firewall". +- You can update the Windows Defender Firewall settings at any time. -
Update Windows Defender permissions (Windows Defender Firewall) - Open the Setting that shows up on the Start menu. @@ -459,7 +497,7 @@ If you have an Antivirus program installed, make sure the appropriate settings a -
-#### 2.2 Permissions on macOS +#### Permissions on macOS -
Opening Software in mscOS Catalina and newer - Right-click on the application you want to run. Choose **Open**. @@ -472,14 +510,14 @@ If you have an Antivirus program installed, make sure the appropriate settings a - Click on `Allow` on the dialog box that appears. This will open the application. ![][macOS-Catalina-Allow_emotibit]
--
Opening Software in mojave - - - Right-click on the application you want to run. Choose **Open**. - - If this is the first time you are using this application, a dialog box might appear asking you to `Allow` this application. Click on `Allow`. - - You will see the EmotiBit Application start. -
-# After connecting to emotibit and recording data +> [!TIP] +> **Check out the following FAQs if you cannot stream EmotiBit data to the EmotiBit Oscilloscope** +> - [Help! I'm having trouble connecting to EmotiBit!](https://www.reddit.com/r/EmotiBit/comments/11hbme1/help_im_having_trouble_connecting_to_emotibit/) +> - [What are the available network options to use with EmotiBit?](https://www.reddit.com/r/EmotiBit/comments/11hjv49/what_are_the_available_network_options_to_use/) +> - [Why isn't my EmotiBit connecting to my phone's WiFi hotspot?](https://www.reddit.com/r/EmotiBit/comments/t4hchv/why_isnt_my_emotibit_connecting_to_my_phones_wifi/) + +# After connecting to emotibit and streaming data By this point, you're ready to be an EmotiBit rockstar!! Check out the following links to learn more about EmotiBit! - EmotiBit Oscilloscope - [Learn more about streaming and recording data using the EmotiBit Oscilloscope](./Working_with_emotibit_data.md/#EmotiBit-Oscilloscope) @@ -488,10 +526,6 @@ By this point, you're ready to be an EmotiBit rockstar!! Check out the following - [Visualizing Data](./Working_with_emotibit_data.md/#Visualize-parsed-data) - [Keep EmotiBit up to date](./Keep_emotibit_up_to_date.md) - [Contributing to the EmotiBit Community](./Contributing_to_emotibit_community) -- [Learn more about EmotiBit](./Learn_more_about_emotibit.md) - -# EmotiBit: LEDs and Buttons -Learn [More about the LEDs and buttons on EmotiBit](./Learn_more_about_emotibit.md#LEDs-and-Buttons) # Troubleshooting diff --git a/Working_with_emotibit_data.md b/Working_with_emotibit_data.md index 6c22bc5..4c02485 100644 --- a/Working_with_emotibit_data.md +++ b/Working_with_emotibit_data.md @@ -1,57 +1,223 @@ -# Working with EmotiBit Data - # Table of Contents -- [Overview](#Overview) -- [EmotiBit Oscilloscope](#EmotiBit-Oscilloscope) - - [Using EmotiBit Oscilloscope to Record Data](#Using-EmotiBit-Oscilloscope-to-Record-Data) - - [Active recording session indicator](#Active-recording-session-indicator) - - [EmotiBit Oscilloscope features](#EmotiBit-Oscilloscope-features) - - [Settings files location](#Settings-files-location) - - [EmotiBit Oscilloscope network settings](#EmotiBit-Oscilloscope-network-settings) - - [Using LSL with EmotiBit Oscilloscope](#Using-LSL-with-EmotiBit-Oscilloscope) - - [LSL output](#LSL-output) - - [Timesync with LSL using marker stream](#Timesync-with-LSL-using-marker-stream) - - [EmotiBit Oscilloscope display settings](#EmotiBit-Oscilloscope-display-settings) -- [EmotiBit DataParser](#EmotiBit-DataParser) - - [Parse raw data using EmotiBit DataParser](#Parse-raw-data-using-EmotiBit-DataParser) - - [Transfer file from SD-Card to computer](#Transfer-file-from-SD-Card-to-computer) - - [Parse raw data file](#Parse-raw-data-file) - - [Raw data format](#Raw-data-format) - - [Parsed data file format](#Parsed-data-file-format) - - [Parsing EmotiBit timestamps to LSL time](#Parsing-EmotiBit-timestamps-to-LSL-time) - - [Batch Parsing](#Batch-parsing) - - [A note on Timesyncs](#A-note-on-Timesyncs) - - [EmotiBit file types](#EmotiBit-file-types) - - [EmotiBit data types](#EmotiBit-data-types) - - [Data type sampling rates](#Data-type-sampling-rates) -- [Visualize parsed data](#Visualize-parsed-data) - - [Visualization tools](#Visualization-tools) -- [Next steps](#Next-steps) -# Overview - -On this page, we will talk about using EmotiBit to record data. We will also talk about various functions available in the -EmotiBit software suite. - - - -The EmotiBit workflow can be described as follows: -- Set up the EmotiBit as described in the Getting Started page. -- Use the EmotiBit Oscilloscope to record data. - - The raw data is recorded as a single file on the SD-Card. -- Copy raw data files from SD-Card to computer. -- Use the EmotiBit DataParser to parse this raw data. - - The DataParser generates one parsed data file for each data type. -- After the recorded data has been parsed, visualize the data. - -# EmotiBit Oscilloscope -EmotiBit Oscilloscope offers the ability to stream data in real-time from EmotiBit to your computer along with an array of other features. - -Start by opening the EmotiBit Oscillosocpe on your computer. If you need more help with opening the Emotibit Oscilloscope, -you may refer to the instructions on the [Getting Started](./Getting_Started.md/#Running-EmotiBit-software) page. - -## Using EmotiBit Oscilloscope to Record Data -Once you have succesfully set up your EmotiBit, you can start recording data using the EmotiBit Oscilloscope. If you have -not yet set up your EmotiBit, check our guide on the [Getting Started](./Getting_Started.md/#Running-EmotiBit-software) page. +* [How to Use EmotiBit](#how-to-use-emotibit) + * [Placement on the Body](#placement-on-the-body) + * [How to Verify a Good Placement](#how-to-verify-a-good-placement) +* [The Data Ecosystem](#the-data-ecosystem) + * [Sensors and Signals](#sensors-and-signals) + * [Data type sampling rates](#data-type-sampling-rates) + * [Expected Data Format](#expected-data-format) + * [Local SD Card data format](#local-sd-card-data-format) + * [Parsed Data File Format](#parsed-data-file-format) +* [Accessing EmotiBit Data](#accessing-emotibit-data) + * [EmotiBit Oscilloscope: The Basics](#emotibit-oscilloscope-the-basics) + * [1. Record data on the SD-Card](#1-record-data-on-the-sd-card) + * [2. Stream data to another location (Using Output List)](#2-stream-data-to-another-location-using-output-list) + +> [!IMPORTANT] +> If you are reading this page, it means you have already successfully streamed data from your EmotiBit hardware to the EmotiBit Oscilloscope. +If you have not yet successfully streamed data or if you need help with the initial setup, please head back to the [**Getting Started**](./Getting_Started.md) page before proceeding with this document. + +# How to Use EmotiBit + +Getting reliable biometric data depends heavily on how the EmotiBit is positioned and secured. + +### Placement on the Body + +For the best data collection results, make sure the EmotiBit is properly secured to the body: +- **Securing the Device**: Use the provided strap to attach the device. It should be snug enough to prevent it from shifting while you move, but comfortable enough that it doesn't restrict blood flow. +- **Placement Options**: For a deeper look at different placement spots and how they affect your data, check out this reference blog post: [Sensing Biometrics from Anywhere on the Body](https://www.emotibit.com/sensing-bio-metrics-from-anywhere-on-the-body/). +> [!TIP] +> The EmotiBit has slots for straps on all 4 sides. This enables you to strap the EmotiBit in both orientations. + +### Using the Oscilloscope for Feedback +Treat the EmotiBit Oscilloscope as your real-time feedback loop. As you adjust the sensor placement, use the live signal stream to guide your adjustments. +To help you gauge your signal quality, the following sections illustrate what good, clean data looks like for each sensor. + +# The Data Ecosystem + +Understanding the relationship between the physical sensors, the signals they generate, and how they are structured is key to successfully analyzing EmotiBit data. + +## Sensors and Signals + +Each data type represents a unique signal captured by EmotiBit and is represented by a unique `TypeTag`. The most up-to-date list of TypeTags can always be found in the [EmotiBit Packet Repository](https://github.com/EmotiBit/EmotiBit_XPlat_Utils/blob/master/src/EmotiBitPacket.cpp). + +Below is a quick reference guide for the available data types. This table is updated periodically as the EmotiBit firmware grows. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeTagSignal & DescriptionHow a Good Signal LooksHow a Bad Signal Looks
EAEDA - Electrodermal ActivityGood-data-EDABad-data-EDA
PI
PR
PG		PPG Infrared
PPG Red
PPG Green		Good-data-PPGGood-data-PPG
T1Temperature
THTemperature via Medical-grade Thermopile (EmotiBit MD only)
AX, AY, AZAccelerometer (X, Y, Z axes)
GX, GY, GZGyroscope (X, Y, Z axes)
MX, MY, MZMagnetometer (X, Y, Z axes)
SA
SR
SF		SCR Amplitude (Skin Conductance Response)
SCR Rise Time
SCR Frequency		Good-data-eda-derivatives
HR
BI		Heart Rate
Heart Inter-beat Interval		Good-data-HR
+ +> [!TIP] +> Additional details about the data stream (*such as units, sampling rate, data format, and averaging*) can be found in the `_info.json` file created automatically with each recording session. + +## Data type sampling rates +The following table shows the sampling rates at which the sensors operate with the stock EmotiBit firmware. You can also find a link to each sensor datasheet. + +| Function |Data Type| Sensor IC | Sampling Rate (samples per second)| +|----------|---------|-----------|--------------| +| Motion |`AX` `AY` `AZ` `GX` `GY` `GZ` `MX` `MY` `MZ`|[BMI160](https://www.bosch-sensortec.com/products/motion-sensors/imus/bmi160/)+[BMI150](https://www.bosch-sensortec.com/products/motion-sensors/magnetometers/bmm150/)|25| +|PPG |`PI` `PG` `PR`| [MAX30101](https://www.analog.com/en/products/max30101.html)|25| +|Temperature |`T0` / `TH`|[MAX30101](https://www.analog.com/en/products/max30101.html) / [MLX90632](https://www.melexis.com/en/product/MLX90632/Miniature-SMD-Infrared-Thermometer-IC) |7.5| +|EDA|`EA` `EL` `ER`|[ADS1114](https://www.ti.com/product/ADS1114)|15| + +## Expected Data Format + +### Local SD Card data format +> [!IMPORTANT] +> You need to start a recording session using the EmotiBit Oscilloscope to record data and store it locally on the SD Card. +``` +531386,17296,1,RB,1,100,2024-09-18_22-59-45-827135 +531388,17297,4,EM,1,100,RS,RB,2024-09-18_22-59-45-827135.csv,PS,MN +531473,17298,3,PI,1,100,112870,112866,112867 +531473,17299,3,PR,1,100,26870,26855,26857 +531473,17300,3,PG,1,100,3720,3704,3717 +``` +`EMOTIBIT_TIMESTAMP`,`PACKET#`,`NUM_DATAPOINTS`,`TYPETAG`,`VERSION`,`RELIABILITY`,`PAYLOAD` +- `EMOTIBIT_TIMESTAMP`: milliseconds since EmotiBit bootup +- `PACKET#`: sequentially increasing packet count +- `NUM_DATAPOINTS`: Number of data points in the payload +- `TYPETAG`: [type of data](#sensors-and-signals) being sent +- `VERSION`: packet protocol version +- `RELIABILITY`: data reliability score out of 100 (for future use) +- `PAYLOAD`: data points + +
Sample raw data file + + ``` + 531386,17296,1,RB,1,100,2024-09-18_22-59-45-827135 + 531388,17297,4,EM,1,100,RS,RB,2024-09-18_22-59-45-827135.csv,PS,MN + 531473,17298,3,PI,1,100,112870,112866,112867 + 531473,17299,3,PR,1,100,26870,26855,26857 + 531473,17300,3,PG,1,100,3720,3704,3717 + 531459,17301,2,EA,1,100,0.030269,0.030269 + 531459,17302,2,EL,1,100,26425.000000,26425.000000 + 531452,17303,1,T1,1,100,33.037 + 531467,17304,1,TH,1,100,29.770 + 531473,17305,3,AX,1,100,-0.436,-0.434,-0.433 + 531473,17306,3,AY,1,100,-0.015,-0.015,-0.015 + 531473,17307,3,AZ,1,100,0.967,0.968,0.970 + 531473,17308,3,GX,1,100,-0.275,-0.244,-0.275 + 531473,17309,3,GY,1,100,0.732,0.793,0.732 + 531473,17310,3,GZ,1,100,-0.061,-0.061,-0.092 + 531473,17311,3,MX,1,100,37,38,37 + 531473,17312,3,MY,1,100,-56,-57,-56 + 531473,17313,3,MZ,1,100,-56,-56,-57 + ``` +
+ +### Parsed Data File Format +> [!IMPORTANT] +> You need to run the EmotiBit Data Parser to convert raw data recordings into parsed files. See the DataParser section to learn more about how to use the EmotiBit Data Parser. +``` +LocalTimestamp,EmotiBitTimestamp,PacketNumber,DataLength,TypeTag,ProtocolVersion,DataReliability,PI +1781122022.609306,565464.000,24431,3,PI,1,100,169093 +1781122022.609306,565464.000,24431,3,PI,1,100,169120 +1781122022.609306,565464.000,24431,3,PI,1,100,169140 +1781122022.649304,565504.000,24448,3,PI,1,100,169136 +``` +* `LocalTimestamp`: Epoch time in seconds +* `EmotiBitTimestamp`: EmotiBit time in milli-seconds (emotibit time resets everytime emotibit is rebooted) +* `PacketNumber`: Packet number the data point was extracted from (sequentially increases) +* `DataLength`: Number of data points in the packet +* `TypeTag`: TypeTag of the data (see table above) +* `ProtocolVersion`: Reserved for future extensibility +* `DataReliability`: Reserved for future extensibility +* `Data`: Sinlge data-point + +# Accessing EmotiBit Data +EmotiBit offers two distinct methodologies to capture your data. +Both methods utilize the **EmotiBit Oscilloscope** application as a core tool. Therefore, this is the perfect spot to briefly introduce how to interact with the Oscilloscope before setting up your first recording session. + +### EmotiBit Oscilloscope: The Basics + +The EmotiBit Oscilloscope is your central hub for monitoring data quality and device status in real-time. + +1.
Connecting to EmotiBit + + - The Oscilloscope displays all available EmotiBits on the network in the `EmotiBit Device List`. + - You can click on any EmotiBit in the list to connect to it. +
+ +2.
Streaming real-time Data + + - The moment you connect to an EmotiBit, the EmotiBit Ocsilloscope will display the data being transmitted by the EmotiBit. + - Once a connection between the Oscilloscope and EmotiBit has been established, the EmotiBit Blue LED turns ON. + - The EmotiBit Blue LED stays on as long as the EmotiBit is connected to an Oscilloscope. +
+ +3.
Recording Data + + - Select an EmotiBit from the list of available EmotiBits. + - You can initiate a record session by clicking on the record button. When a record session is initiated, the EmotiBit will start recording the data on the onboard SD-Card as well as stream it on the Oscilloscope. + - The EmotiBit Red LED starts blinking once a recording session has been initiated. + - You are free to move in/out of the network, close the Oscilloscope, or connect to a new Oscilloscope. + - We recommend using the EmotiBit in-network as much as possible, connected to the Oscilloscope. This helps in generating more time-syncs which improves timestamp accuracy. +
+ +### 1. Record data on the SD-Card To start a record session, follow these steps: - Select the EmotiBit from the `EmotiBit Device List`. @@ -61,895 +227,37 @@ To start a record session, follow these steps: - Once a recording session has been started, the `Record Button` section becomes red. - To end a recording, toggle the Recording button by clicking on it again. -### Active recording session indicator -You can check if a recording session is currently active by either checking the EmotiBit or the EmotiBit Oscilloscope. -- **Indication on the EmotiBit** - - You will notice that the EmotiBit RED LED starts blinking if a recording session is active. - - The EmotiBit RED LED will continue to blink till the active recording session has been stopped using the EmotiBit Oscillosocpe. -- **Indication on the EmotiBit Oscilloscope** - - When you open the Oscilloscope, all available EmotiBits on the network will be listed under the `device list`. Select the EmotiBit you are interested in from the device list. - - If a recording session is currently active, the name of the file being recorded appears below the `Record Button`. This name indicates the time when the recording was started. - - *Pro-tip: You can check the length of active recording by subtracting the current time from the time displayed in the `Recording section` on the Oscillosocpe.* - -[Click here to learn how to use the DataParser](#Parse-raw-data-using-EmotiBit-DataParser) to convert the raw data into parsed data files. -
If you want to learn about all the features offered by the EmotiBit Oscilloscope, check out the section [below](#EmotiBit-Oscilloscope-features). - -## EmotiBit Oscilloscope features -- The Oscilloscope offers the following features: -![][EmotiBit-Oscilloscope] - -[ToDo:Update the Gif above to represent the new oscilloscope] - -
Connecting to EmotiBit - - - The Oscilloscope displays all available EmotiBits on the network in a list. - - You can click on any EmotiBit in the list to connect to it. -
- - -
Streaming real-time Data - - - The moment you connect to an EmotiBit, the EmotiBit Ocsilloscope will display the data being transmitted by the EmotiBit. - - Once a connection between the Oscilloscope and EmotiBit has been established, the EmotiBit Blue LED turns ON. - - The EmotiBit Blue LED stays on as long as the EmotiBit is connected to an Oscilloscope. -
- - -
Recording Data - - - Select an EmotiBit from the list of available EmotiBits. - - You can initiate a record session by clicking on the record button. When a record session is initiated, the EmotiBit will start recording the data on the onboard SD-Card as well as stream it on the Oscilloscope. - - The EmotiBit Red LED starts blinking once a recording session has been initiated. - - You are free to move in/out of the network, close the Oscilloscope, or connect to a new Oscilloscope. - - We recommend using the EmotiBit in-network as much as possible, connected to the Oscilloscope. This helps in generating more time-syncs which improves timestamp accuracy. -
- - -
Log note(labeling data) - - - Users can annotate data by adding labels/notes in real time. - - Type in the Note in the `Log Note` text box and click on the `Log Note` button to add notes to the data being recorded. -
- - -
Power Modes - - The EmotiBit has 4 power modes. All modes can be accessed using the EmotiBit Oscilloscope. - - **Normal Mode**: In normal mode, the EmotiBit works with complete functionality, being able to record and transmit data. - - **Low Power Mode**: In Low power mode, the EmotiBit can record but cannot transmit data in real-time. It, however, continues to get the time-sync pulses. - - **WiFi Off**: The onboard WiFi shield is shut down in this mode. This saves power and enables longer recording sessions. - - A `short press` of the [EmotiBit button](https://github.com/EmotiBit/EmotiBit_Docs/blob/master/Getting_Started.md#emotibit-leds-and-buttons) toggles `normal mode` and `WiFi off mode`. - - If using the EmotiBit in `WiFi off` mode, we recommend toggling the EmotiBit to `normal mode` (short EmotiBit Button press) towards the end of the recording. Once in `normal mode` you can reconnect to the EmotiBit using the EmotiBit Oscilloscope and stream data for ~30 seconds to collect timesync pulses towards the end of the recording. - - **Sleep**: In sleep mode, EmotiBit stops any tasks it is performing and goes to sleep. - - A `long press` of the [EmotiBit button](https://github.com/EmotiBit/EmotiBit_Docs/blob/master/Getting_Started.md#emotibit-leds-and-buttons) can activate the sleep mode. - - We recommend switching the EmotiBit into `Sleep mode` instead of un-plugging the EmotiBit battery when not in use for short periods. - - If the EmotiBit is being left un-used for a long duration, it is best to flip the Hibernate Switch to `HIB`. - - Refer [EmotiBit LEDs and buttons section](./Learn_more_about_emotibit.md#LEDs-and-Buttons) for more information on the Hibernate switch. -
- - -
DC/DO counter - - `Data Clipping` and `Data Overflow` are metrics that are used to determine data integrity. - - - `Data Clipping`: A clipping event occurs when the data recorded by any sensor goes out of the predefined bounds. - - `Data Overflow`: An overflow event occurs when the internal data buffers overflow, which results in loss of data samples. -
+> [!TIP] +> **Active recording session indicator:** You can check if a recording session is currently active by either checking the EmotiBit or the EmotiBit Oscilloscope.
+> - **Indication on the EmotiBit** +> - You will notice that the EmotiBit RED LED starts blinking if a recording session is active. +> - The EmotiBit RED LED will continue to blink till the active recording session has been stopped using the EmotiBit Oscillosocpe. +> - **Indication on the EmotiBit Oscilloscope** +> - When you open the Oscilloscope, all available EmotiBits on the network will be listed under the `device list`. Select the EmotiBit you are interested in from the device list. +> - If a recording session is currently active, the name of the file being recorded appears below the `Record Button`. This name indicates the time when the recording was started. The Record button and the file name appear with a red background. - -
Battery Level Indicator - - - The Battery Level indicator displays the charge available in the battery as a percentage. - - We recommend not letting the battery fall below 10% as it might begin to interfere with the sensor data acquisition. -
-### Output List -- The output list shows the options available to transmit the data out of the EmotiBit Oscilloscope. -- Each output protocol uses settings specified in the unique file name, defined in the sections below. -- Depending on your operating system, the settings file can be found in the locations listed below - - Windows: `C:\Program Files\EmotiBit\EmotiBit Oscilloscope\data\` - - macOS: `EmotiBitOscilloscope/Contents/resources/` - - Linux: `EmotiBit Oscilloscope/bin/data/` - --
OSC - - - **EmotiBit Oscilloscope v1.2.0 and up** support the ability to transmit incoming data from an EmotiBit to a user-defined output channel using the OSC protocol. - - To enable OSC, just click on the `Output List` dropdown in the EmotiBit Oscilloscope and enable `OSC`. - - The EmotiBit Oscilloscope reads in and transmits out the data according to the specifications provided in the `oscOutputSettings.xml` file. - - You can find the settings file in the path mentioned above. - - You can modify the contents of this file to control the behavior of the OSC output stream. - - A snippet of the default contents are shared below - ``` - - - - EmotiBit - - - OSC - localhost - 12345 - - - - - PR - /EmotiBit/0/PPG:RED - - - PI - /EmotiBit/0/PPG:IR - - - PG - /EmotiBit/0/PPG:GRN - - - - ``` - - As you can see, the `input` is set to an EmotiBit, which is streaming data to the oscilloscope. - - The Oscilloscope takes this data and relays it over the IP-Address and Port specified. - - A `patch` connects an input stream to an output stream. In the snippet above, the input `PR` (PPG Red channel) stream is patched to the output stream called `/EmotiBit/0/PPG:IR` - - The `` tag should contain the Typetag of the data you want to relay. The available typetags can be found in the [section below](#EmotiBit-data-types). - - The `` tag should contain the name of the OSC stream you want to relay the data as. - - For example, to add SCR (Skin conductance response) metrics to OSC, you would add the following lines to the relevant section of the `oscOutputSettings.xml` file. - ``` - - SA - /EmotiBit/0/SCR:AMP - - - SR - /EmotiBit/0/SCR:RIS - - - SF - /EmotiBit/0/SCR:FREQ - - ``` - - When using the OSC protocol, at the receiver, you must use the same IP-Address, Port number, and label name you used as the output label here. To get started, check out this example of [OSC Oscilloscope as a receiver](https://github.com/produceconsumerobot/ofxOscilloscope/tree/master/oscOscilloscopeExample). If you have enabled OSC data transmission on the Emotibit Oscilloscope, you can run the example in the above link to plot the data being relayed by the EmotiBit oscilloscope. -
- --
UDP - - - **EmotiBit Oscilloscope v1.7.1 and up** support the ability to transmit incoming data from an EmotiBit to a user-defined output channel using the UDP protocol. - - To enable UDP, just click on the `Output List` dropdown in the EmotiBit Oscilloscope and enable `UDP`. - - The EmotiBit Oscilloscope reads in and transmits out the data according to the specifications provided in the `udpOutputSettings.xml` file. - - You can find the settings file in the path mentioned above. You can modify the contents of this file to control the behavior of the UDP output stream. - - A snippet of the default contents are shared below - ``` - - - - EmotiBit - - - UDP - localhost - 12346 - - - - - - ``` -
- --
LSL - - - **EmotiBit Oscilloscope v1.11.1 and up** support the ability to transmit incoming data from an EmotiBit to a user-defined LSL stream. - - To enable UDP, just click on the `Output List` dropdown in the EmotiBit Oscilloscope and enable `LSL`. - - The LSL stream details are provided in the `lslOutputSettings.json` file. You can find this settings file in the operating-system-specific location mentioned above. Modifying the contents on this file updates the LSL stream details being transmitted by the EmotiBit. - - The **patchcords** section in the documentation ties the input EmotiBit stream to the name of the output LSL stream. A complete list of EmotiBit data typetags can be found [here](#EmotiBit-data-types). -
- -## EmotiBit Oscilloscope settings - -### Settings files location - -Based on the operating system, users can find the settings files in the following locations: -- For Windows users(Users will also need to give the file "write privileges". Check out this [FAQ](https://www.reddit.com/r/EmotiBit/comments/urp7dq/how_do_i_edit_files_installed_by_emotibit/) to learn how): - - `C:\Program Files\EmotiBit\EmotiBit Oscilloscope\data\` -- For mac users - - `EmotiBitSoftware-macOS/EmotiBitOscilloscope.app/Contents/Resources/` - - Note: Users need to right-click the `EmotiBitOscilloscope` application (*inside the software bundle just downloaded*) and click on `Show Package Contents`. You can then find the files in `Contents > Resources` -- For linux users - - `EmotiBitSoftware-linux/ofxEmotiBit/EmotiBitOscilloscope/bin/data/` - -### EmotiBit Oscilloscope network settings -The software release `v1.4.11` adds the ability for users to tweak their network settings using the `emotibitCommSettings.json` file. -Refer the [section above](#Settings-files-location) to locate this file on your system. - --
emotibitCommSettings.json - - - `sendAdvertisingInterval_msec` allows users to specify how frequently (time in mS) they want the Oscilloscope to ping the network to find EmotiBit. The default setting should work in most cases and we recommend -changing this setting only if it is required by your network admin. - - `checkAdvertisingInterval_msec` allows users to specify how frequently (time in mS) they want the Oscilloscope to search for EmotiBit responses on the network. -Again, we recommend changing this setting only if it is required by your network admin. - - Users can now choose between `broadcast` vs `unicast` advertising. You can also specify ip ranges to ping for unicast! This will be beneficial for users that: - - are working with routers that block broadcast(ex: iPhone hotspot). Check out the note below for using the latest Oscilloscope(v1.4.11) with iPhone hotspot. - - perform poorly with unicast. The oscilloscope now uses broadcast by default, so it should just work... and work better! - - Specifically in `unicast mode` there are 2 more options available. Most users will never have to change these settings, but if you are working -in a constrained network environment, these settings may help to conform to network admin requirements. - - `nUnicastIpsPerLoop` specified the number of IPs you want to ping at time. - - `unicastMinLoopDelay_msec` specifies the min time to wait before trying to ping IPs on the network again. - - Ability to exclude or include networks while looking for EmotiBits. - - `excludeList`: If you don't want EmotiBit Oscilloscope to look for EmotiBit in a particular network, add it to the excludeList - - `includeList`: If you want EmotiBit Oscilloscope to look for EmotiBits ins specific networks, add it to the includeList - - **Special note for iPhone hotspot users** - - iPhone does not allow broadcasting on its hotspot. Since the new Oscilloscope(v1.4.11+) uses broadcast(for advertising) by default, users will have to make the following change in the emotibitCommSettings.json to use EmotiBit on iPhone hotspot. - 1. Locate the file (as suggested above) based on your operating system. - 2. change "broadcast" -> "enabled" to false - 3. change "unicast" -> "enabled" to true - 4. Save the file. - 5. Run the Oscilloscope app! - - The modified file should look like the snippet shown below. - ``` - { - "wifi": { - "advertising": { - "sendAdvertisingInterval_msec": 1000, - "checkAdvertisingInterval_msec": 100, - "transmission": { - "broadcast": { - "enabled": true - }, - "unicast": { - "enabled": true, - "ipMax": 254, - "ipMin": 2, - "nUnicastIpsPerLoop": 1, - "unicastMinLoopDelay_msec": 3 - } - } - }, - "network": { - "excludeList": [ "" ], - "includeList": [ "*.*.*.*" ] - } - }, - "lsl": { - "marker": { - "name": "", - "sourceId": "" - } - } - } - - ``` -
- -### Using LSL with EmotiBit Oscilloscope -#### LSL output -You can use the EmotiBit Oscilloscope to relay incoming EmotiBit data to output LSL streams. Check out the [output list section](#Output-List) aboce for more details. - -#### Timesync with LSL using marker stream -EmotiBit oscillosocpe can ingest an LSL marker stream and use that stream to timestamp -EmotiBit data being recorded to LSL time. A marker stream is specified by a `name` and `sourceId`. By default the EmotiBit Oscilloscope searches for a LSL marker stream with the name `DataSyncMarker` and sourceId `12345`. You can create this stream by referring this [example](https://github.com/EmotiBit/ofxLSL/#example-for-generating-marker-stream). - -If you want the Oscilloscope to search for a different marker stream, please refer the steps below. - --
Specifying LSL marker stream for EmotiBit Oscilloscope - - You need to specify the marker stream information in the `emotibitCommSettings.json` file. -Refer the [section above](#Settings-files-location) to locate this file on your system. - - For Example, an LSL marker stream with **name** `DataSyncMarker` and **source_id** `12345` can be specified in the `emotibitCommSettings.json` as shown below - ``` - { - "wifi": { - "advertising": { - "transmission": { - "broadcast": { - "enabled": true - }, - "unicast": { - "enabled": false, - "ipMax": 254, - "ipMin": 2 - } - } - }, - "network": { - "excludeList": [ "" ], - "includeList": [ "*.*.*.*" ] - } - }, - "lsl": { - "marker": { - "name": "DataSyncMarker", - "sourceId": "12345" - } - } - } - ``` - With the stream information specified, when you open the EmotiBit Oscilloscope, you can find the same information on the status bar (at the bottom of the Oscilloscope). The EmotiBit Oscilloscope will continue to search for the stream till it is detected. - - - Once detected, the EmotiBit starts receiving markers from the stream and displays a `markers received` count on the status bar. You need at least 2 markers during the recording to generate LSL timestamps. - - - Check out this [section](#Parsing-EmotiBit-timestamps-to-LSL-time) to enable the DataParser to add LSL timestamps in the parsed data. - - **Note: Please make sure that your marker stream has both a **name** and a **source_id**. Connecting to a stream that only has the **name** specified - can cause the Oscilloscope to crash, if the marker stream disconnects un-expectedly. This however, does not affect any data being recorded on the EmotiBit!** -
- -### EmotiBit Oscilloscope display settings -Users can use the `ofxOscilloscopeSettings.xml` file to change other Oscillocsope settings. -Refer the [section above](#Settings-files-location) to locate this file on your system. - --
Using ofxOscilloscopeSettings.xml file - - Each datastream is a `plot` on a `scope panel`. The example below shows the settings available for each scope. - ``` - - 25.000000000 ## represents the sampling rate of the signal - 10.000000000 ## duration of time represented in the scope - 0.000000000 ## min. signal threshold for display - 0.000000000 ## max. signal threshold for display - 0.000000000 ## min. allowed (yMax-yMin) - - 0 ## Plot ID. !! DO not change this. It should always follow the information specified in inputSettings.xml - PPG:RED ## Plot name displayed on the screen - ## Plot color in RGB channels - 255 - 69 - 78 - - - - ``` - Close any running Oscilloscope window. Change any setting in this file. Reopen EmotiBit Oscilloscope to see the changes take effect. - - As an example, if you are using the 100Hz PPG example, then the PPG plot settings look something like: - ``` - - 100.000000000 - 10.000000000 - 0.000000000 - 0.000000000 - 0.000000000 - - 0 - PPG:RED - - 255 - 69 - 78 - - - - - 100.000000000 - 10.000000000 - 0.000000000 - 0.000000000 - 0.000000000 - - 1 - PPG:IR - - 128 - 75 - 181 - - - - - 100.000000000 - 10.000000000 - 0.000000000 - 0.000000000 - 0.000000000 - - 2 - PPG:GRN - - 120 - 209 - 192 - - - - ``` -
- -# EmotiBit DataParser -The DataParser is used to convert the raw recorded data into parsed data files.
-Start by opening the EmotiBit DataParser on your computer. If you need more help with opening the Emotibit DataParser, -you may refer to the instructions on the [Getting Started](./Getting_Started.md/#Running-EmotiBit-software) page. - -## Parse raw data using EmotiBit DataParser - -### Transfer file from SD-Card to computer -The data recorded using EmotiBit is stored on the SD-Card. You can transfer the data from the EmotiBit to the computer in 2 ways. -1. **Using SD card reader** - - Remove the SD card from the EmotiBit. - - Plug it into the provided SD-Card reader provided with the Essentials kit or All-in-one-bundle. - - Plug the SD card reader into the computer. Once the Card is detected on the computer, you can simply copy the files to a location on your computer. -2.
Using a FTP server on EmotiBit (**only available on ESP32 Feather Huzzah**) - - - With the EmotiBit switched on and running, plug it into the computer using the provided USB cable. - - Make sure the EmotiBit is not recording data. - - Open a Arduino Serial monitor. For more details, check out this [FAQ](https://www.reddit.com/r/EmotiBit/comments/vmtz6w/how_i_use_the_arduino_serial_monitor_with_emotibit/). - - Select `baud rate`=2000000 and `No line ending` from the dropdown options. - - Type `F` into the input message bar and press Enter. - - You will see that the EmotiBit will enter FTP mode (red, blue, and yellow LEDs light up on EmotiBit). - - - - You you can trasnfer the files from EmotiBit using an FTP client. - - Download and install [Filezilla Client](https://filezilla-project.org/), if you do not already have it. - - Open Filezilla and follow the connection setup instructions as shown in this [link](https://mischianti.org/simple-ftp-server-library-now-with-support-for-wio-terminal-and-sd/#Configure_client) - - The `Host` IP address will be printed on the serial monitor. - - The default **user name** is `ftp` and the default **password** is `ftp`. You can change these values in the firmware. In the future, these credentials will be accessible using the `config` file. - - Once you connect to the FTP server, you can then drag any file from EmotiBit to any location on your computer (inside the FileZilla interface), and it will we copied over the WiFi! - - - - Reset the EmotiBit to exit the FTP mode and enter normal operation. -
- -### Raw data format -The raw data is stored in the following format. The following steps discuss using the EmotiBit DataParser to parse raw data files.
+### 2. Stream data to another location (Using Output List) -`EMOTIBIT_TIMESTAMP`,`PACKET#`,`NUM_DATAPOINTS`,`TYPETAG`,`VERSION`,`RELIABILITY`,`PAYLOAD` -- **EMOTIBIT_TIMESTAMP:** milliseconds since EmotiBit bootup -- **PACKET#:** sequentially increasing packet count -- **NUM_DATAPOINTS:** Number of data points in the payload -- **TYPETAG:** [type of data](#motibit-data-types) being sent -- **VERSION:** packet protocol version -- **RELIABILITY:** data reliability score out of 100 (for future use) -- **PAYLOAD:** data points - -A sample of the raw data file is shown below. --
Sample raw data file - - ``` - 531386,17296,1,RB,1,100,2024-09-18_22-59-45-827135 - 531388,17297,4,EM,1,100,RS,RB,2024-09-18_22-59-45-827135.csv,PS,MN - 531473,17298,3,PI,1,100,112870,112866,112867 - 531473,17299,3,PR,1,100,26870,26855,26857 - 531473,17300,3,PG,1,100,3720,3704,3717 - 531459,17301,2,EA,1,100,0.030269,0.030269 - 531459,17302,2,EL,1,100,26425.000000,26425.000000 - 531452,17303,1,T1,1,100,33.037 - 531467,17304,1,TH,1,100,29.770 - 531473,17305,3,AX,1,100,-0.436,-0.434,-0.433 - 531473,17306,3,AY,1,100,-0.015,-0.015,-0.015 - 531473,17307,3,AZ,1,100,0.967,0.968,0.970 - 531473,17308,3,GX,1,100,-0.275,-0.244,-0.275 - 531473,17309,3,GY,1,100,0.732,0.793,0.732 - 531473,17310,3,GZ,1,100,-0.061,-0.061,-0.092 - 531473,17311,3,MX,1,100,37,38,37 - 531473,17312,3,MY,1,100,-56,-57,-56 - 531473,17313,3,MZ,1,100,-56,-56,-57 - ``` -
- - -### Parse raw data file - -The steps below describe how you can use the DataParser to parse the raw data file to generate individual parsed data files. -- Click on the `Load file` button to open a file browser. Navigate to the raw data(**csv**) file which you want to parse and select that file. -- The parser will show the progress as it parses the data. The DataParser quits automatically on completion. -- The parsed data files are created in the same directory as the original **raw data file**. - -![][EmotiBit-DataParser] - -For more details on the file types check out the section [below](). - -### Parsed data file format -- The parsed data is stored in the following format - -|LocalTimestamp | EmotiBitTimestamp | PacketNumber | DataLength | TypeTag | ProtocolVersion | DataReliability | Data | -|---------------|---------------|---------------|---------------|---------------|---------------|---------------|---------------| -|Epoch time in seconds | EmotiBit time in milli-seconds (emotibit time resets everytime emotibit is rebooted) | Packet number the data point was extracted from (sequentially increases) | Number of data points in the packet | TypeTag of the data (see below) | Reserved for future extensibility | Reserved for future extensibility | Data points | - -- The format of the parsed data file can be changed by modifying the `parsedDataFormat.json` file. - -
parsedDataFormat.json file location - - - On Windows: `C:\Program Files\EmotiBit\EmotiBit DataParser\data` - - On macOS: `EmotiBitSoftware-macOS/EmotiBitDataParser.app/Contents/Resources` - - On Linux: `EmotiBitSoftware-linux/ofxEmotiBit/EmotiBitDataParser/bin/data` -
- - **Note: If this file is erroneously modified, for example, the modified file does not conform to JSON standard (a missing `,` or `[` or `{`), the EmotiBitDataparser will skip loading this file. The parsed output, in this case, will be missing the `LocalTimestamp` column.** - --
Adding LSL timestamp column by modifying parsedDataFormat - - To include the appropriate LSL time in the parsed output, just set the **addToOutput** to `true` in the `parsedDataFormat.json` file. - Note: LSL timestamps are only relevant if you are using a [LSL marker stream with EmotiBit Oscillosocpe](#timesync-with-lsl-using-marker-stream). - - Setting **LslLocalTimestamp** to `true` adds timestamps acording to the time on the local LSL clock of the system. - - Setting **LslMarkerSourceTimestamp** to `true` adds timestamps according to the time set on the -marker source generator system. - For example, if you want to add the timestamps as per your local LSL clock (the clock on the system running the EmotiBit Oscilloscope), the file should look like as shown below. - ``` - { - "timestampColumns": [ - { - "identifier": "TL", - "columnHeader": "LocalTimestamp", - "addToOutput": true - }, - { - "identifier": "LC", - "columnHeader": "LslLocalTimestamp", - "addToOutput": true - }, - { - "identifier": "LM", - "columnHeader": "LslMarkerSourceTimestamp", - "addToOutput": false - } - ] - } - ``` - When **addToOutput** is set to `true`, an additional column is added to the parsed output, with the column header set as the `columnHeader` specified in the file above. -
- -See below for a sample of the a parsed file of typetag AX (Accelerometer X axis) --
Parsed data file example - - ``` - LocalTimestamp,EmotiBitTimestamp,PacketNumber,DataLength,TypeTag,ProtocolVersion,DataReliability,AX - 1726714786.598369,531473.000,17305,3,AX,1,100,-0.436 - 1726714786.598369,531473.000,17305,3,AX,1,100,-0.434 - 1726714786.598369,531473.000,17305,3,AX,1,100,-0.433 - 1726714786.638383,531513.000,17322,3,AX,1,100,-0.434 - 1726714786.678397,531553.000,17322,3,AX,1,100,-0.433 - 1726714786.718411,531593.000,17322,3,AX,1,100,-0.434 - 1726714786.758425,531633.000,17337,2,AX,1,100,-0.437 - 1726714786.798439,531673.000,17337,2,AX,1,100,-0.436 - 1726714786.838453,531713.000,17354,3,AX,1,100,-0.432 - 1726714786.878467,531753.000,17354,3,AX,1,100,-0.434 - 1726714786.918481,531793.000,17354,3,AX,1,100,-0.435 - 1726714786.958495,531833.000,17370,2,AX,1,100,-0.432 - 1726714786.998509,531873.000,17370,2,AX,1,100,-0.435 - 1726714787.038523,531913.000,17388,3,AX,1,100,-0.434 - 1726714787.078537,531953.000,17388,3,AX,1,100,-0.436 - 1726714787.118551,531993.000,17388,3,AX,1,100,-0.434 - 1726714787.158565,532033.000,17402,2,AX,1,100,-0.434 - 1726714787.198579,532073.000,17402,2,AX,1,100,-0.433 - 1726714787.238593,532113.000,17419,3,AX,1,100,-0.435 - 1726714787.278607,532153.000,17419,3,AX,1,100,-0.432 - 1726714787.318621,532193.000,17419,3,AX,1,100,-0.434 - 1726714787.358635,532233.000,17435,2,AX,1,100,-0.435 - 1726714787.398649,532273.000,17435,2,AX,1,100,-0.433 - 1726714787.438663,532313.000,17455,3,AX,1,100,-0.435 - 1726714787.478677,532353.000,17455,3,AX,1,100,-0.434 - ``` -
- -### Batch parsing -- The parser can currently be run from the command line with the filename (to be parsed) passed as an argument. -- We have created a [shell script](https://github.com/EmotiBit/ofxEmotiBit/blob/master/EmotiBitDataParser/bin/EmotiBitDataParser.sh) to leverage this functionality and "batch parse" multiple files in 1 go. - - Just grab the script from the repository and run it with the correct arguments. -- As an example, you can place all your raw files in a folder, let's say `data`. - - Then you can run the script as `./EmotiBitDataParser.sh -x "C:\\Program Files\\EmotiBit\\EmotiBit DataParser\\EmotiBitDataParser.exe" -d "path\\to\\data"` - - The parser will then parse all the files present in the data folder. -- We plan to further bake this into the software by making this a part of the GUI and it will be rolled out in a future release. - -### A note on Timesyncs -- We use periodic timesyncs from the EmotiBit Oscilloscope to improve the accuracy of the data timestamps on EmotiBit.The time syncing mechanism helps in correcting for any drift that may be introduced by the microcontroller clock. -- Timesync pulses are transmitted to Emotibit periodically, as long as the EmotiBit Oscilloscope is connected to EmotiBit. These timesyncs are written with the raw data on the SD-Card to help the DataParser with time calibration. -- The DataParser uses the timesyncs with the shortest Round-Trip-Times(RTT) to calibrate timestamps. The calibration works best if the raw data contains multiple timesyncs spaced throughout the recording. At minimum, the calibration requires 2 timesyncs. -- However, since timesyncs are only recorded while the EmotiBit is connected to the Oscilloscope, it is possible that the recorded data has fewer than 2 timesyncs. A scenario where the Oscilloscope was closed immediately after starting a recording session can lead to this situation. -- In cases where the EmotiBit DataParser finds fewer than 2 timesyncs, a warning will be displayed to the user after the file is parsed making them aware of the effect of having fewer than 2 timesyncs on the timestamp accuracy. - - --
What to expect when you have 0 timesync events in the recorded file - - - **The values in the LocalTimeStamp will start from 0**. This is because the data does not have any timesyncs to create a relation between - EmotiBitTime and LocalTime. - - The data parser needs at least 2 timesync events to interpolate/extrapolate LocalTime. Hence, there will be no time correction to - any drift experienced by the emotibit clock. -
--
What to expect when you have 1 timesync event in the recorded file - - - The values in the LocalTimeStanp column **will start form the Local Time corresponding to the moment the recording was initiated**. - - The data parser needs at least 2 timesync events to interpolate/extrapolate LocalTime. Hence, there will be no time correction to - any drift experienced by the emotibit clock. -
- -# EmotiBit file types -There are 3 types of files associated with EmotiBit -- Raw data file(**csv**) - - Every recording sessions generates 1 raw data file. - - This file is named with the start time of the recording session. Ex: `2019-01-30_11-57-13-492.csv` -- Information file(**json**) - - Along with the raw data file, each recording session generates 1 `info` file. - - It contains information like sampling rates and other important settings for each sensor/stream. - - It shares the name of the raw file. For example, the `info` file for the above raw file will be named `2019-01-30_11-57-13-492_info.json` - -
sample _info.json file +- The output list shows the options available to transmit the data out of the EmotiBit Oscilloscope. +- Each output protocol uses settings specified in the unique file name. +- The available output options are + - OSC + - UDP + - LSL - ``` - [{ - "info": { - "name": "EmotiBitData", - "type": "Multimodal", - "source_id": "EmotiBit FeatherWing", - "hardware_version": "V05c", - "sku": "MD", - "device_id": "MD-V5-0000410", - "feather_version": "Adafruit Feather HUZZAH32", - "feather_wifi_mac_addr": "54:66:cc:7e:dc:0c", - "firmware_version": "1.12.1", - "firmware_variant": "EmotiBit_stock_firmware", - "created_at": "2024-11-14_11-54-36-135729" - } - }, { - "info": { - "name": "Accelerometer", - "type": "Accelerometer", - "typeTags": ["AX", "AY", "AZ"], - "channel_count": 3, - "nominal_srate": 25, - "channel_format": "float", - "units": "g", - "setup": { - "range": 8, - "acc_bwp": 2, - "acc_us": 2 - } - } - }, { - "info": { - "name": "Gyroscope", - "type": "Gyroscope", - "typeTags": ["GX", "GY", "GZ"], - "channel_count": 3, - "nominal_srate": 25, - "channel_format": "float", - "units": "degrees/second", - "setup": { - "range": 1000, - "gyr_bwp": 2, - "gyr_us": 2 - } - } - }, { - "info": { - "name": "Magnetometer", - "type": "Magnetometer", - "typeTags": ["MX", "MY", "MZ"], - "channel_count": 3, - "nominal_srate": 25, - "channel_format": "float", - "units": "microhenries", - "setup": {} - } - }, { - "info": { - "name": "ElectrodermalActivity", - "type": "ElectrodermalActivity", - "typeTags": ["EA"], - "channel_count": 1, - "nominal_srate": 15, - "channel_format": "float", - "units": "microsiemens", - "setup": { - "eda_series_resistance": 0, - "adc_bits": 16, - "enable_digital_filter": false, - "samples_averaged": 5, - "oversampling_rate": 75, - "eda_transform_slope": 722.0528564, - "eda_transform_intercept": 1.4121972e7 - } - } - }, { - "info": { - "name": "SkinConductanceResponseAmplitude", - "type": "ElectrodermalActivity", - "typeTags": ["SA"], - "channel_count": 1, - "channel_format": "float", - "units": "microsiemens" - } - }, { - "info": { - "name": "SkinConductanceResponseFrequency", - "type": "ElectrodermalActivity", - "typeTags": ["SF"], - "channel_count": 1, - "nominal_srate": 3, - "channel_format": "float", - "units": "count/min" - } - }, { - "info": { - "name": "SkinConductanceResponseRiseTime", - "type": "ElectrodermalActivity", - "typeTags": ["SR"], - "channel_count": 1, - "channel_format": "float", - "units": "secs" - } - }, { - "info": { - "name": "Temperature1", - "type": "Temperature", - "typeTags": ["T1"], - "channel_count": 1, - "nominal_srate": 7.5, - "channel_format": "float", - "units": "degrees celcius", - "sensor_part_number": "MAX30101", - "setup": { - "samples_averaged": 1, - "oversampling_rate": 7.5 - } - } - }, { - "info": { - "name": "Thermopile", - "type": "Temperature", - "typeTags": ["TH"], - "channel_count": 1, - "nominal_srate": 7.5, - "channel_format": "float", - "units": "degrees celcius", - "setup": { - "samples_averaged": 1, - "oversampling_rate": 7.5 - } - } - }, { - "info": { - "name": "PPG", - "type": "PPG", - "typeTags": ["PI", "PR", "PG"], - "channel_count": 3, - "nominal_srate": 25, - "channel_format": "float", - "units": "raw units", - "setup": { - "LED_power_level": 47, - "samples_averaged": 16, - "LED_mode": 3, - "oversampling_rate": 400, - "pulse_width": 215, - "ADC_range": 4096 - } - } - }, { - "info": { - "name": "HeartRate", - "type": "PPG", - "typeTags": ["HR"], - "channel_count": 1, - "channel_format": "int", - "units": "bpm" - } - }, { - "info": { - "name": "InterBeatInterval", - "type": "PPG", - "typeTags": ["BI"], - "channel_count": 1, - "channel_format": "float", - "units": "mS" - } - }] - ``` -
- -- Parsed data files(**csv**) - - the raw file is converted to parsed files by running the DataParser. - - Each parsed file contains data for a specific data type. - - The name for each parsed file is created by joining the `TypeTag` of the data type to the raw file name. - - Ex: After running the data parser on `2019-01-30_11-57-13-492.csv`, the parsed data file containing the data for `PPG IR channel` - will be called `2019-01-30_11-57-13-492_PI.csv` - - For more details on data types, see [EmotiBit Data Types](#emotibit-data-types) (below). - -![][EmotiBit-File-Types] - - -# EmotiBit data types -Each data type represents a unique signal captured by EmotiBit and is represented by a unique `TypeTag`. The most up-to-date list of TypeTags can be found in https://github.com/EmotiBit/EmotiBit_XPlat_Utils/blob/master/src/EmotiBitPacket.cpp - -For a quick look at the available data types, you can check out the table below. We periodically update this table as the EmotiBit firmware grows. **Additional details about the data stream (*units, sampling rate, data format, averaging etc*) can be found in the `_info.json` file created with each recording session.** - --
Biometric TypeTags - - |TypeTag | Description | - |:-----:|----------------------| - |EA |EDA- Electrodermal Activity | - |EL |EDL- Electrodermal Level | - |ER |EDR- Electrodermal Response (EmotiBit V4+ combines ER into EA signal) | - |PI |PPG Infrared | - |PR |PPG Red | - |PG |PPG Green | - |T0 |Temperature (only on EmotiBit Alpha/Beta V1, V2, V3) | - |T1 |Temperature | - |TH |Temperature via Medical-grade Thermopile (only on EmotiBit MD) | - |AX |Accelerometer X | - |AY |Accelerometer Y | - |AZ |Accelerometer Z | - |GX |Gyroscope X | - |GY |Gyroscope Y | - |GZ |Gyroscope Z | - |MX |Magnetometer X | - |MY |Magnetometer Y | - |MZ |Magnetometer Z | - |SA |Skin Conductance Response (SCR) Amplitude | - |SR |Skin Conductance Response (SCR) Rise Time | - |SF |Skin Conductance Response (SCR) Frequency | - |HR |Heart Rate | - |BI |Heart Inter-beat Interval | - |H0 |Humidity (only on EmotiBit Alpha/Beta V1, V2, V3) | - -
- --
General Typetags - - |TypeTag | Description | - |:-----:|:----------------------------------| - |EI |EmotiBit Info Json | - |DC |Data Clipping, TypeTag in Payload | - |DO |Data Overflow, TypeTag in Payload | - |B% |Battery Percentage Remaining | - |BV |Battery Voltage | - |D% |SD card percent capacity filled | - |RD |Request Data, TypeTag in Payload | - |PI |Ping | - |PO |Pong | - |RS |Reset | - -
- --
Computer to EmotiBit TypeTags - - |TypeTag | Description | - |:-----:|:----------------------------------| - |GL |[GPS latitude and Longitude][GPS] | - |GS |[GPS Speed][GPS] | - |GB |[GPS Bearing][GPS] | - |GA |[GPS Altitude][GPS] | - |TL |Local Computer Timestamp | - |TU |UTC Timestamp | - |TX |Crosstime, used for timestamp comparison | - |LM |LSL Marker/message | - |RB |Record begin (Include timestamp in Data) | - |RE |Record End | - |UN |User Note | - |MH |Mode Hibernate | - |HE |Hello EmotiBit, used to establish communication | - -
- --
Payload labels - - |TypeTag | Description | - |:-----:|:----------------------------------| - |LM |LSL_MARKER_SRC_TIMESTAMP - The LSL time in the marker generator system | - |LR |LSL_MARKER_RX_TIMESTAMP - The LSL time in the receiver system. This is a calculated value derived from LM and time correction (a constant created by the LSL architecture) | - |LD |LSL_MARKER_DATA - the data stored by the LSL marker| - |LC |LSL_LOCAL_CLOCK_TIMESTAMP - The LSL time on the local computer the EmotiBit Oscilloscope is running on| - -
- -### Data type sampling rates -The following table shows the sampling rates at which the sensors operate with the stock EmotiBit firmware. -| Function |Data Type| Sensor IC | Sampling Rate (samples per second)| -|----------|---------|-----------|--------------| -| Motion |`AX` `AY` `AZ` `GX` `GY` `GZ` `MX` `MY` `MZ`|[BMI160](https://www.bosch-sensortec.com/products/motion-sensors/imus/bmi160/)+[BMI150](https://www.bosch-sensortec.com/products/motion-sensors/magnetometers/bmm150/)|25| -|PPG |`PI` `PG` `PR`| [MAX30101](https://www.analog.com/en/products/max30101.html)|25| -|Temperature |`T0` / `TH`|[MAX30101](https://www.analog.com/en/products/max30101.html) / [MLX90632](https://www.melexis.com/en/product/MLX90632/Miniature-SMD-Infrared-Thermometer-IC) |7.5| -|EDA|`EA` `EL` `ER`|[ADS1114](https://www.ti.com/product/ADS1114)|15| -# Visualize parsed data -Visualization tools can often help answer some immediate questions and hence, can be very useful when working with time-series data. Below we have outlined a number of tools that we think can be very successful. -## Visualization tools -- Text Editors - - Notepad++(on Windows) - - Text Edit(on mac) -- Spreadsheet softwares - - Microsoft Excel - - Google Sheets -- [EmotiBit python data viewer](https://github.com/EmotiBit/EmotiBit_Biometric_Lib/tree/master/py/examples/dataviewer_example) - - A tool created for visualizing all data channels in one window. - - ![][EmotiBit-PythonDataViewer] - -# Next Steps - -- EmotiBit Firmware variants - - Once you are familiar with the EmotiBit data collection workflow, you may want to look at available firmware variants to adapt EmotiBit to your needs. - - A good example is the EmotiBit 100Hz PPG variant! Check out more details [here](./Learn_more_about_emotibit.md/#emotibit-firmware-variants). +# Next steps +- To learn more about the EmotiBit software, checkout the following reference manuals + - [EmotiBit Oscilloscope](./EmotiBitOscilloscope_reference_manual.md) + - [EmotiBit DataParser](./EmotiBitDataParser_reference_manual.md) [EmotiBit-Oscilloscope]: ./assets/Visualizer_green_800px.gif "EmotiBit-Oscilloscope" [EmotiBit-File-Types]: ./assets/EmotiBit_File_Types.png "EmotiBit-File-Types" [EmotiBit-DataParser]: ./assets/DataParser.png "EmotiBit-Dataparser" [EmotiBit-PythonDataViewer]: ./assets/PythonDataViewer.jpg "EmotiBit-PythonDataViewer" +[Good-data-PPG]: ./assets/Good-data-ppg.png "Good-data-PPG" +[Good-data-EDA]: ./assets/Good-data-eda.png "Good-data-EDA" +[Good-data-HR]: ./assets/Good-data-hr.png "Good-data-HR" +[Good-data-eda-derivatives]: ./assets/Good-data-eda-derivatives.png "Good-data-eda-derivatives" diff --git a/assets/Bad-data-eda.png b/assets/Bad-data-eda.png new file mode 100644 index 0000000..7900882 Binary files /dev/null and b/assets/Bad-data-eda.png differ diff --git a/assets/Bad-data-ppg.png b/assets/Bad-data-ppg.png new file mode 100644 index 0000000..dd1bd5f Binary files /dev/null and b/assets/Bad-data-ppg.png differ diff --git a/assets/EmotiBit-stack-LED.png b/assets/EmotiBit-stack-LED.png new file mode 100644 index 0000000..91b1b73 Binary files /dev/null and b/assets/EmotiBit-stack-LED.png differ diff --git a/assets/EmotiBitFirmwareInstaller.gif b/assets/EmotiBitFirmwareInstaller.gif new file mode 100644 index 0000000..7ed419b Binary files /dev/null and b/assets/EmotiBitFirmwareInstaller.gif differ diff --git a/assets/Good-data-eda-derivatives.png b/assets/Good-data-eda-derivatives.png new file mode 100644 index 0000000..e46e0d2 Binary files /dev/null and b/assets/Good-data-eda-derivatives.png differ diff --git a/assets/Good-data-eda.png b/assets/Good-data-eda.png new file mode 100644 index 0000000..6e31a50 Binary files /dev/null and b/assets/Good-data-eda.png differ diff --git a/assets/Good-data-hr.png b/assets/Good-data-hr.png new file mode 100644 index 0000000..28ef82f Binary files /dev/null and b/assets/Good-data-hr.png differ diff --git a/assets/Good-data-ppg.png b/assets/Good-data-ppg.png new file mode 100644 index 0000000..160be2a Binary files /dev/null and b/assets/Good-data-ppg.png differ