Skip to content

Commit

Permalink
docs: update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@kulbhushanchand
kulbhushanchand committed May 3, 2021
1 parent ce3274e commit afd5d31
Show file tree
Hide file tree
Showing 7 changed files with 748 additions and 70 deletions.
16 changes: 13 additions & 3 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,20 @@ cache/
# Data files
data/
data_for_algo_analysis/

# FCEUX files
fceux64_old/
fceux64/ROMs

# Docs
docs/
docs_source/

# Misc. files
analysis_old.m
analysis.m
scratchpad.m
analysis/
#analysis_old.m
#analysis.m



.Rproj.user
1 change: 0 additions & 1 deletion BioNES.m
View file
Original file line number Diff line number Diff line change
Expand Up @@ -398,7 +398,6 @@ function togglebutton_startStop_Callback(hObject, eventdata, handles)
if(isBiofeedback && isGameConnected)
% Display HR and HRV
bar = floor((100-abs(perHrvDeviation))/10);

% bar = round(mod(timeSample/10^6, 10));

switch bar
Expand Down
128 changes: 128 additions & 0 deletions CODE_OF_CONDUCT.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
# Contributor Covenant Code of Conduct

## Our Pledge

We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.

## Our Standards

Examples of behavior that contributes to a positive environment for our
community include:

* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
* Focusing on what is best not just for us as individuals, but for the
overall community

Examples of unacceptable behavior include:

* The use of sexualized language or imagery, and sexual attention or
advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email
address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting

## Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.

Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.

## Scope

This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
https://kulbhushanchand.github.io/.
All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the
reporter of any incident.

## Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:

### 1. Correction

**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.

**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.

### 2. Warning

**Community Impact**: A violation through a single incident or series
of actions.

**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.

### 3. Temporary Ban

**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.

**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.

### 4. Permanent Ban

**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.

**Consequence**: A permanent ban from any sort of public interaction within
the community.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.

Community Impact Guidelines were inspired by [Mozilla's code of conduct
enforcement ladder](https://github.com/mozilla/diversity).

[homepage]: https://www.contributor-covenant.org

For answers to common questions about this code of conduct, see the FAQ at
https://www.contributor-covenant.org/faq. Translations are available at
https://www.contributor-covenant.org/translations.
148 changes: 87 additions & 61 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,10 @@
</a>
<h2 align="center">Biofeedback Nintendo Entertainment System (BioNES)</h2>
<p align="center">
A tool to deliver multimodal biofeedback with NES games
A plug-and-play MATLAB based tool to use NES games for multimodal biofeedback
<br />
<a href="https://kulbhushanchand.github.io/BioNES/"><strong>Explore the docs »</strong></a>
<br />
</p>
</p>

Expand All @@ -15,128 +18,151 @@

## Table of Contents

- [About The Project](#about-the-project)
- [About the Project](#about-the-project)
- [Built with](#built-with)
- [Why another acquisition program?](#why-another-acquisition-program)
- [Features](#features)
- [Getting Started](#getting-started)
- [Why this tool?](#why-this-tool)
- [Getting started](#getting-started)
- [Prerequisites](#prerequisites)
- [Installation and Running](#installation-and-running)
- [Usage](#usage)
- [Examples](#examples)
- [Documentation](#documentation)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)
- [Contact](#contact)
- [Acknowledgment](#acknowledgment)
- [Citation](#citation)

## About The Project
## About the project
![screenshot](docs/assets/images/BioNes.jpg)

![screenshot](docs/assets/images/screenshot1.jpg)
BioNES (Biofeedback Nintendo Entertainment System) is an open-source plug-and-play MATLAB-based tool to use NES games for multimodal biofeedback. It can be used to deliver the HRV biofeedback via any game designed for the NES system. It can receive real-time heartbeat interval (RR) values from Arduino + ear-clip PPG sensor (or any sensor capable to send real-time heart rate pulses to Arduino). After the acquisition, it computes real-time heart rate and heart rate variability (HRV), biofeedback parameters and then sends feedback to the FCEUX emulator which is used to play the NES game.
Besides in-game biofeedback, it also offers real-time data visualization in time-series plots and local saving of data for offline analysis. This tool can benefit the researchers (especially from biofeedback or physiological measurement domain) or hobbyist, who want to quickly deploy a biofeedback system, want to explore the NES games for biofeedback, or just want to record the physiological signals.

AfDaq (Arduino Firmata Data Acquisition) is an open-source plug and play MATLAB based tool for biofeedback and arduino based instruments, which offers the capabilities of multi-channel real-time data acquisition, visualization, manipulation, and local saving of data for offline analysis.
The researchers (especially from biofeedback or physiological measurement domain) or hobbyist, who are using MATLAB and want to acquire data from Arduino or to control Arduino based instruments can use this tool. The software tool, data, and analysis that support the findings of this study are released as open-source to support the replicability and reproducibility of research.
### Built with

### Built With

This GUI tool is built using `Guide` tool in [MATLAB-v2017b](https://in.mathworks.com/products/matlab.html). For the hardware any [Arduino](https://www.arduino.cc/) compatible board can be used which is supported by MATLAB.

### Why another acquisition program?

Researchers in the biofeedback domain or working on Arduino based instruments often require a quick-to-deploy system to acquire real-time data from Arduino and for further analysis transfer the data in MATLAB. For this the MATLAB has provided [MATLAB Support Package for Arduino Hardware](https://in.mathworks.com/help/supportpkg/arduinoio/) which ease the data acquisition need from Arduino compatible hardware by automatically updating firmata code on arduino board and providing functions for data acquisition. However, the currently its use in physiological research is limited due to severe timing jitter associated during data acquisition.

This software tool aims to reduce the timing jitter and provides precise time stamps during data acquisition.
- GUI is built using the `Guide` tool in [MATLAB-v2017b](https://in.mathworks.com/products/matlab.html).
- [Arduino](https://www.arduino.cc/) Mega board for hardware.
- [Grove ear-clip sensor](https://wiki.seeedstudio.com/Grove-Ear-clip_Heart_Rate_Sensor/) for photoplethysmograph (PPG) data acquisition.
- [FCEUX](https://github.com/TASVideos/fceux) emulator to play NES game.
- [Super Mario Bros.](https://www.mariowiki.com/Super_Mario_Bros.) game for feedback.

### Features

- Plug and play system (no need to separately upload any code on arduino board).
- Real-time multi-channel data acquisition from supported digital or analog channels.
- Sampling rate of -
- 10 Hz when using all 5 channels simultaneously
- 40 Hz when using single channel acquisition.
- Real-time data visualization (in scroll plot) and data manipulation (with custom functions).
- Local saving of data in `.xlsx` format for offline analysis.
- Plug and play biofeedback system for SMB game (using other NES games may need minor changes).
- Data acquisition sampling rate of 10 Hz to acquire RR intervals from Arduino.
- Feedback is displayed at a fixed refresh rate at 60 Hz.
- Real-time data visualization (in time-series plot).
- Local saving of data in `.mat` format for offline analysis.
- Screenshot of current GUI for reference purpose.
- 3 independent modes of working.
- Data acquisition only
- Gameplay without biofeedback
- Gameplay with biofeedback

### Why this tool?

<!-- GETTING STARTED -->
## Getting Started
Biofeedback therapy has potential benefits for managing stress. However, traditional biofeedback is an expensive and monotonous process. To increase the engagement in biofeedback sessions, video games can be used. But the problem is the limited availability of affordable video-game-based biofeedback solutions.
BioNES is developed keeping in mind the cost-effectiveness and ease of use to deliver biofeedback while simultaneously providing reliability as a research tool and flexibility to allow researchers/developers to modify as per their needs. The efficacy of BioNES is validated using observational study and the paper is currently under review in a reputed journal.

The working with AfDaq is straightforward process. Make sure you have prerequisites available and follow the steps below.

<!-- GETTING STARTED -->
## Getting started

### Prerequisites

- [MATLAB]()
>`MATLAB-ver2017b` was used to develop the AfDaq. It was also tested with `ver2015b` and `ver2018b` for backward and forward compatibility respectively. It may not work with `ver20xx and before` due to the unavailability of compatible `MATLAB Support Package for Arduino Hardware`.
- [MATLAB Support Package for Arduino Hardware]()
- [Arduino](https://www.arduino.cc/) compatible hardware board.
>For the list of supported board, visit documentation [here]().
- [MATLAB](https://in.mathworks.com/products/matlab.html)

>`MATLAB-ver2017b` was used to develop the BioNES. It was also tested with `ver2015b` and `ver2018b` for backward and forward compatibility respectively.
- [Arduino](https://www.arduino.cc/) hardware board.
- [Grove ear-clip sensor](https://wiki.seeedstudio.com/Grove-Ear-clip_Heart_Rate_Sensor/).
- [FCEUX](https://github.com/TASVideos/fceux).
- NES game ROM file. This version of BioNES uses the Super Mario Bros. game without any modification, for other NES games you have to make minor changes to the `BioNES.lua` file.

### Installation and Running
### Installation and running

1. Download the [latest stable release]() and extract contents into your MATLAB working directory. Alternatively, you can also download the latest code from the [repository]().
2. Open `AfDaq.m` in MATLAB.
3. Connect Arduino board to PC with USB cable. If board is pre-configured with Firmata code by MATLAB, a message is shown in the command window.
4. Run `AfDaq.m` and wait for the GUI to appear.
5. In the GUI select the `COM` port for the arduino and press `Connect` button. If the Arduino is not pre-configured with Firmata code by MATLAB, it may take few minutes (It's a one time process OR if the board is re-flashed outside).
6. After successful connection, appropriate settings can be selected and acquisition is manually started.
7. The acquisition runs till set time or can be stopped manually.
8. After successful completion, information panel show various statistics related to acquisition.
9. Data can be saved for offline processing.
1. Download the [latest stable release](https://github.com/kulbhushanchand/BioNES/releases) and extract contents into your MATLAB working directory. Alternatively, you can also download the latest code from the [repository](https://github.com/kulbhushanchand/BioNES).
2. Open `BioNES.m` in MATLAB.
3. Connect Arduino board to PC with USB cable. Upload `BioNES.ino` sketch to Arduino board.
4. Connect the ear-clip sensor to the Arduino board.
4. Run `BioNES.m` and wait for the GUI to appear.
5. In the GUI select the `COM` port for the Arduino and press the `Connect` button.
6. After a successful connection, appropriate settings can be selected.
7. Select the biofeedback checkbook (if biofeedback gameplay is needed) and press the `Connect` button in the `Game` panel. The `FCEUX` window will open with the pre-configured settings.
8. Start the acquisition from the `Start/Stop` button in the `Control` panel.
9. The acquisition runs till a set time or can be stopped manually.
10. After successful completion, the information panel shows various statistics related to the acquisition.
11. Finally, the data can be saved for offline processing.


<!-- USAGE EXAMPLES -->
## Usage

Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources.
Use this space to show useful examples of how a project can be used. Additional screenshots, code examples, and demos work well in this space. You may also link to more resources.
*For more examples, please refer to the [Documentation](https://kulbhushanchand.github.io/BioNES/)*.


### Examples

To be added.


<!-- DOCUMENTATION -->
## Documentation

The documentation is available at https://kulbhushanchand.github.io/BioNES/


<!-- ROADMAP -->
## Roadmap

See the [open issues](https://github.com/kulbhushanchand/AfDaq/issues) for a list of proposed features (and known issues).
See the [open issues](https://github.com/kulbhushanchand/BioNES/issues) for a list of proposed features (and known issues).


<!-- CONTRIBUTING -->
## Contributing

Any contributions you make are greatly appreciated. You can **report a bug**, **request a feature** or **ask any question** by creating an issue on this repository. In case you would like to add your changes to this repository, you can follow the easy steps below -
Any contributions you make are greatly appreciated. You can contribute to this project in the following ways :

- Add new functionality
- Review code
- Raise issues about bugs/features/doubts
- Proof-read the documentation
- Cite if used in a publication
- Star on GitHub
- Share with others

1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
Please note that this project is released with a [Contributor Code of Conduct](https://github.com/kulbhushanchand/BioNES/blob/master/CODE_OF_CONDUCT.md). By contributing to this project you agree to abide by its terms.


<!-- LICENSE -->
## License

Distributed under the GPLv3 License. See [LICENSE](https://github.com/kulbhushanchand/AfDaq/blob/master/LICENSE) for more information.
This project is distributed under the `GPLv3` License. See [LICENSE](https://github.com/kulbhushanchand/BioNES/blob/master/LICENSE) for more information.


<!-- CONTACT -->
## Contact
## Citation

[Kulbhushan Chand](https://kulbhushanchand.github.io/about/)
To be filled

```
citation
```


<!-- ACKNOWLEDGMENTS -->
## Acknowledgment

- [drawio-desktop](https://github.com/jgraph/drawio-desktop)

I would like to thank my PhD supervisor [Prof. Arun Khosla](https://www.nitj.ac.in/index.php/nitj_cinfo/Faculty/38) at Dr B R Ambedkar National Institute of Technology for his guidance and kind support. I also want to acknowledge the open-source tools used in some parts of this project.

## How to cite?
- [FCEUX](https://github.com/TASVideos/fceux) is used as an NES emulator.
- [drawio-desktop](https://github.com/jgraph/drawio-desktop) is used to create the logo and diagrams.

The project is an open data, open code, and replicable research.
- The code is available at [GitHub repository](https://github.com/kulbhushanchand/AfDaq).
- The code, data, and analysis-scripts that support the findings of the study are available at [OSF Repository](https://doi.org/10.17605/OSF.IO/VCTJM).

The paper explaining the design and development, and usage of this work in multimodal biofeedback is published in xxxx. You can cite this work (by citing the paper published for this work) as below -
<!-- CONTACT -->
## Contact

[Kulbhushan Chand](https://kulbhushanchand.github.io/about/)
1 change: 0 additions & 1 deletion fceux64/cheats/Super Mario Bros. (World).cht
View file

This file was deleted.

Loading

0 comments on commit afd5d31

Please sign in to comment.