Skip to content

GUI Release QA Checklist

Jump to bottom
Richard Waltman edited this page Jan 18, 2023 · 10 revisions

GUI Release QA Checklist

The OpenBCI GUI is the official tool for getting started with OpenBCI hardware. It is used to validate the signals coming from the device, visualize data, help users learn about OpenBCI hardware and basic signal processing, make recordings, and help users prototype pipelines via the Networking widget.

System Requirements

Hardware:

  • 1.6 GHz or faster processor
  • 2 GB of RAM
  • 400 MB of hard drive space (minimum)

OpenBCI GUI has been tested on the following platforms:

  • OS X 10.8.5 or later
  • Windows 8.1 and 10 (64-bit)
  • Linux Ubuntu Desktop 18

OpenGL acceleration is required.

GUI Data Location

All Console Logs, Recordings, and Settings files are located in the same location on all operating systems:

  • [Your User Name]/Documents/OpenBCI_GUI/

The GUI Control Panel

When the GUI starts up, it will display the current version. This version will also be displayed in the title bar of the application. The Control Panel class and .pde file is the most exhaustive for this project. This is where we select our options for how we would like to start a session.

Available Data Modes:

  • Cyton
  • Cyton + WiFi
  • Cyton + Daisy
  • Cyton + Daisy + WiFi
  • Ganglion + BLED112 Dongle
  • Ganglion + Native Bluetooth (In Development)
  • Ganglion + WiFi
  • Playback Mode
    • Only plays back CSV files made by the GUI. BDF files can be played back using EDFBrowser (another application).
  • Synthetic Mode
    • 4, 8, and 16 channel modes
  • BrainFlow Streaming Board
    • This is an advanced feature. Example: You can connect to a Cyton using a Python script while specifying a streaming board over local IP and a port. Then, you can access the device data from Python as the primary thread, and also receive and visualize data in the GUI as a secondary thread.

For each Data Source, there is also the option for a BrainFlow Streamer. This allows users to stream data to either a file or over the network, independently of the networking widget. The difference here is that it is formatted to work directly with BrainFlow. By default, we will save data in the same location as GUI CSV data but in the BrainFlow format. This means we are saving data in two formats at the same time.

image3 image2

GUI Widgets

The GUI has a Widget framework which allows users to accomplish a variety and combination of tasks. Visit the GUI Widget Guide for more information. Also, here is a full list of the Widgets in the GUI. Please note, some widgets can only be accessed depending on the data mode selected.

All GUI Widgets listed in the order of instantiation:

  • Time Series
  • FFT Plot
  • Accelerometer
    • AccelerometerCapableBoard
  • Cyton Signal Check
    • BoardCyton
  • Playback History
    • DataSourcePlayback
  • Ganglion Impedance
    • BoardGanglion
  • Focus Widget
  • Networking
  • Band Power
  • Head Plot
  • EMG
  • Spectrogram
  • Pulse Sensor
    • AnalogCapableBoard
  • Digital Read
    • DigitalCapableBoard
  • Analog Read
    • AnalogCapableBoard
  • Packet Loss
    • Board class
  • Template Widget

GUI Console Log

Please refer to the image below which highlights the GUI Console Log button.

image4

Third Party Integrations via Networking

Important documents for working with or testing the Networking Widget:

Networking Protocols and use cases:

  • Serial
    • This can be used to connect to an Arduino or other device.
  • UDP
    • A standard protocol that sends data over a local or remote device.
  • OSC
    • Essentially UDP but used more by artists and musicians for programs such as PureData, MaxMSP, Touch Designer, or Resolume..
  • LSL or Lab Streaming Layer
    • This is the most complicated streaming protocol. It is used by many labs to sync data from multiple devices.

Towards QA Testing the OpenBCI GUI

You should now understand that the number of combinations of features to test is quite daunting. As of GUI 5.1.0, there are no major issues with any individual features that handle data. If you think there is an issue, please review the open issues on GitHub. If it does not exist, please make a new issue or feature request.

Even though there are many options, there are still a few tests that can be done to test the overall stability of crucial functions of the application. Please understand that issues connecting to a board are usually not related to issues with the GUI. Example: BOARD_NOT_READY error when trying to connect to a Cyton or Ganglion. This does not mean that the GUI is “crashed” or “broken”. This particular error probably means the board needs to physically be turned off and back on, as it is not listening. _This is the most important concept to understand when QA testing the GUI: hardware issues are not equal to software issues.

In addition to the GUI Console Log file, there are BrainFlow-specific log files which save data related to the connection between the GUI and an OpenBCI Board. You will find this next to the recording files in a given session folder.

Before beginning any tests, please close other resource-heavy applications such as web browsers (aka the 100 tabs you have open in Chrome) or the Arduino IDE serial monitor (this blocks the serial port).** Processing uses mostly the CPU and memory. We need at least 30 frames per second for the GUI to operate properly. This value is displayed in the title bar of the application.**

Finally, please make sure that you have a fully charged battery plugged into your OpenBCI board(s). Also, please use a USB extender to move the Cyton Dongle away from the computer and try to maintain line-of-sight between Cyton and Dongle.

Basic QA Tests for the OpenBCI GUI

Cyton and Cyton + Daisy using Dongle

  1. Plug in Cyton Dongle.
  2. Leave Cyton Off.
  3. Start GUI.
  4. Click “Cyton (live)” under Data Source in the System Control Panel.
  5. Click “Serial (from Dongle)” under Pick Transfer Protocol.
  6. Click “Start Session” or “Auto-Connect.”
  7. The GUI will try to Auto-Connect to Cyton.
  8. Auto-Connect should fail and show a red message at the bottom of the GUI.
  9. Turn the Cyton On.
  10. Click “Start Session” or “Auto-Connect.”
  11. The GUI will try to Auto-Connect to Cyton.
  12. Auto-Connect should be successful and start a new Session.
  13. Start streaming data.
  14. Open every widget while data is streaming.

Ganglion using BLED112 Dongle

  1. Plug in Ganglion Dongle.
  2. Leave Ganglion Off.
  3. Start GUI.
  4. Click “Ganglion (live)” under Data Source in the System Control Panel.
  5. Click “Bluetooth (BLED112 Dongle)” under Pick Transfer Protocol.
  6. The GUI Helpers Dependency will attempt to search for a Ganglion using the BLED112 dongle. It will show any visible dongles in the “BLE Devices” panel. No Ganglions should show and there should be no errors when attempting to search.
  7. Turn the Ganglion On.
  8. The Ganglion should appear in the “BLE Devices” panel. If it does not, plug in the dongle to another USB port and repeat steps 3 through 5. You may need to restart the computer if you are doing advanced testing and the serial port is “stuck”. This can happen sometimes on older Macs.
  9. Select the Ganglion in the “BLE Devices” menu list panel.
  10. Click “Start Session.”
  11. The GUI will try to connect to Ganglion.
  12. If successful, the GUI will start a new session.
  13. Start streaming data.
  14. Open every widget while data is streaming.
  15. Stop streaming data.
  16. Close the session.

Ganglion using Native Bluetooth

  1. Make sure that this computer has bluetooth capabilities and is turned on.
  2. Leave Ganglion Off.
  3. Start GUI.
  4. Click “Ganglion (live)” under Data Source in the System Control Panel.
  5. Click “Bluetooth (native)” under Pick Transfer Protocol.
  6. The GUI Helpers Dependency will attempt to search for a Ganglion using the built-in bluetooth. No Ganglions should show and there should be no errors when attempting to search.
  7. Turn the Ganglion On.
  8. The Ganglion should appear in the “BLE Devices” panel. If it does not, click the “Start Search” button to try finding the Ganglion again.
  9. Select the Ganglion in the “BLE Devices” menu list panel.
  10. Click “Start Session.”
  11. The GUI will try to connect to Ganglion.
  12. If successful, the GUI will start a new session.
  13. Start streaming data.
  14. Check the Packet Loss widget and stream data for a minute or two.
  15. Open every widget while data is streaming.
  16. Stop streaming data.
  17. Close the session.

Playback Mode

  1. Start GUI.
  2. Select Playback Mode from the menu list in the control panel.
  3. Use sample data file. There is a special button in the control panel which will bring you to the file location. Open the dialog box and select one of the files.
  4. Click “Start Session.”
  5. Start streaming data.
  6. Open every widget while data is streaming.
  7. Stop the session.
  8. The playback history should now be updated to include the last file that was played.
  9. Open a recording file made with Cyton and GUI v5.
  10. Repeat steps 3 through 6.
  11. The playback history should now include the last two files in the correct order.
  12. Open a recording file made with Ganglion and GUI v5.
  13. Repeat steps 3 through 6.
  14. The playback history should now include the last three files in the correct order.
  15. If you were to open the Settings tab in the top right and “Clear All” settings, the playback history would be erased. This can be tested occasionally but seriously does wipe any type of saved settings folders/files for the entire GUI.

Synthetic Mode

  1. Start GUI.
  2. Select Synthetic Mode from the menu list in the control panel.
  3. Select 4 channels.
  4. Click “Start Session.”
  5. Start streaming data.
  6. Open every widget while data is streaming.
  7. Stop the session.
  8. Select 8 channels.
  9. Repeat steps 4 through 7.
  10. Select 16 channels.
  11. Repeat steps 4 through 7.

Filter UI

  1. Start GUI.
  2. Select Synthetic Mode from the menu list in the control panel.
  3. Select 16 channels.
  4. Click “Start Session.”
  5. Start streaming data.
  6. Click the “Filters” button near the “Stop Data Stream” button. This will open the Filters UI.
  7. Click the “Show Channels” expander button. It’s the full width of the UI, though it looks different from a standard button.
  8. Click the same button as step 6 that should now read “Hide Channels.”
  9. Repeat steps 6 and 7 rapidly. This should not crash or freeze. This is an important test on Windows when considering Processing versions and JAVA2D renderer.
  10. Click the “Show Channels” expander button.
  11. Change any settings you like. Make sure to change at least one of each type of setting.
  12. Click the “Save” button to save the changes to a file. A dialog box will open allowing you to give this file a name. Use default location.
  13. Click the “Reset” button to reset the Filter UI to default settings.
  14. Click the “Load” button. A dialog box will open again. Load the file that you saved in step 11.
  15. The Filter UI should successfully revert to the settings adjusted in step 10.
  16. Close and open the entire Filter UI window a few times. You should notice that the custom settings from step 10 persist every time.
  17. You can also play with the filters to confirm that they effectively process the synthetic data on a given channel by looking at the FFT plot.

Please refer to the screenshot below for a look at the Filter UI.

image1

Cyton Hardware Settings

  1. Plug in Cyton Dongle.
  2. Turn the Cyton On.
  3. Start GUI.
  4. Click “Cyton (live)” under Data Source in the System Control Panel.
  5. Click “Serial (from Dongle)” under Pick Transfer Protocol.
  6. Click “Start Session” or “Auto-Connect.”
  7. The GUI will try to Auto-Connect to Cyton.
  8. Auto-Connect should be successful and start a new Session.
  9. Click the “Hardware Settings” button in the top left of the Time Series widget.
  10. Change some settings for any channels. When there is a difference, the channel should highlight blue until successfully sent to the board.
  11. Click “Send” to send the settings to the board. The changed channels should no longer be highlighted blue.
  12. Repeat steps 10 and 11 a few more times.
  13. Now, click the “Save” button to save the Hardware Settings. This is separate from the Session Settings.
  14. Stream data for a few moments.
  15. Stop the data stream and stop the session.
  16. Repeat steps 5 through 9.
  17. When we restart a session, the board settings are reset on the Cyton. This time, click the “Load” button to load the settings saved in step 13.
  18. The channels with a difference should be highlighted blue. Click the “Send” button to send all settings to the board.
  19. Stream data for a few moments again.

Save/Load Session Settings

  1. Start GUI.
  2. Select any data mode from the list.
  3. Click “Start Session.”
  4. The default layout and widgets will start for this mode.
  5. Change the layout and widgets so that it’s noticeably different.
  6. Open the “Settings” tab in the top right of the GUI.
  7. Click “Save” to save the current arrangement and widget dropdown settings to file.
  8. Click “Default” to revert to what was seen in step 4.
  9. Click “Load” to load the settings saved in step 7.
  10. Stop the session.
  11. Navigate to the folder [User]/Documents/OpenBCI_GUI/Settings and make sure there is a [BoardName]DefaultSettings.json file. This file is updated every time a session is started. This policy avoids discrepancies when a widget or setting is added.
  12. Repeat steps 2 through 10 for all data modes and channel counts.
  13. NOTE: If a new widget is created or a new setting is added to a widget, the old settings file will be incompatible with the board and/or number of channels. In this case, the GUI should gracefully catch this and delete the old settings file while alerting the user.

BrainFlow Streaming Board

  1. Connect to an OpenBCI board using a Python script. Make sure it will continue to stream data from the device for a few minutes while this test is running.
  2. In the terminal console, make sure you have the latest BrainFlow Python binding by typing: pip install brainflow -U
  3. Pull up the brainflow_streamingboard_send.py file from the Networking Test Kit and be ready to run it.
  4. Start GUI.
  5. Select “Streaming (from external)” data source.
  6. The IP address and port from the example are 225.1.1.1:6677. If this is mistyped, it will not work properly.
  7. Select “Synthetic” as the Board in the Streaming Board Config panel.
  8. Click “Start Session.”
  9. If the session fails to start, look at the BrainFlow and GUI log files in [User]/Documents/OpenBCI_GUI/Console_Data and share with the software team. The most simple reason this fails is because of a version mismatch between the external process and the GUI. The BrainFlow version is printed at the start of the GUI console log. The Python version of BrainFlow will be mentioned after step 2.
  10. Start streaming data.
  11. Open every widget.
  12. Stop streaming data and close the session.
  13. Repeat this tutorial but use Cyton and Ganglion boards

BrainFlow Streamer (Network)

  1. In the terminal console, make sure you have the latest BrainFlow Python binding by typing: pip install brainflow -U
  2. Pull up the brainflow_streamer_receive.py file from the Networking Test Kit and be ready to run it.
  3. Start GUI.
  4. Select Synthetic data mode.
  5. Select 4 Channels.
  6. In the BrainFlow Streamer box, click “Network”. The default IP and port will be 225.1.1.1:6677.
  7. Click “Start Session.”
  8. Start streaming data.
  9. Run the python script associated with this test: python brainflow_streamer_receive.py.
  10. Wait for 10 seconds while the script is running. After, the data from the GUI should print in the terminal.
  11. Stop streaming data and close the session.
  12. Repeat steps 4 through 11 using eight and sixteen channels.
  13. Modify the Python script to work with Cyton and repeat steps 6 through 11.
  14. Modify the Python script to work with Cyton+Daisy and repeat steps 6 through 11.
  15. Modify the Python script to work with Ganglion and repeat steps 6 through 11.

Cyton Analog and Digital Modes

  1. Plug in Cyton Dongle.
  2. Turn the Cyton On.
  3. Start GUI.
  4. Click “Cyton (live)” under Data Source in the System Control Panel.
  5. Click “Serial (from Dongle)” under Pick Transfer Protocol.
  6. Click “Start Session” or “Auto-Connect.”
  7. The GUI will try to Auto-Connect to Cyton.
  8. Auto-Connect should be successful and start a new Session.
  9. Select a Layout with at least four panels and open the Analog Read, Digital Read, and Pulse Sensor widgets. Leave all of these widgets open to see how they behave when modes are changed.
  10. Press the button at the top left of the Analog Read widget to enable Analog Mode.
  11. Start streaming data. We should now see valid floating data from the external pins. The Pulse Sensor widget should also be active when the Analog Read widget is active
  12. Stop streaming data.
  13. [Optional] Connect a digital button or signal to one of the external Cyton pins.
  14. Press the button at the top left of Digital Read widget to enable Digital Mode.
  15. Start Streaming data.
  16. Note that some of the Digital pins may show a value of 1 while nothing is connected. This is normal.
  17. Stop streaming data.
  18. [Optional] Connect pulse sensor to D11 external pin on the Cyton and connect to finger or earlobe.
  19. Press the button at the top left of the Pulse Sensor widget to enable Analog Mode.
  20. Start Streaming data.
  21. Confirm that data is drawn in both the Analog Read and Pulse Sensor widgets.

Please feel free to contribute tips, tricks and best practices.

Contents

Clone this wiki locally