-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Loading status checks…
docs: Create package documentation
- Loading branch information
Showing
11 changed files
with
274 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,27 @@ | ||
name: docs | ||
on: | ||
push: | ||
branches: | ||
- main | ||
pull_request: | ||
branches: | ||
- main | ||
permissions: | ||
contents: write | ||
jobs: | ||
Docs: | ||
runs-on: ubuntu-latest | ||
steps: | ||
- uses: actions/checkout@v4 | ||
- uses: actions/setup-python@v5 | ||
with: | ||
python-version: 3.x | ||
- uses: actions/cache@v4 | ||
with: | ||
key: ${{github.ref}} | ||
path: .cache | ||
- name: Install dependencies | ||
run: | | ||
python -m pip install --upgrade pip | ||
pip install mkdocs-material mkdocstrings mkdocs-include-markdown-plugin | ||
- run: mkdocs gh-deploy --force |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
::: mindwave.headset.ConnectionStatus | ||
--- | ||
|
||
::: mindwave.utils.event_manager.EventType | ||
--- | ||
|
||
::: mindwave.session.SessionSignal | ||
options: | ||
show_if_no_docstring: true |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
::: mindwave.connector.ConnectorDataEvent | ||
options: | ||
show_docstring_parameters: false | ||
|
||
--- | ||
|
||
::: mindwave.headset.HeadsetStatusEvent | ||
options: | ||
show_docstring_parameters: false | ||
--- | ||
|
||
::: mindwave.utils.stream_parser.HeadsetDataEvent | ||
options: | ||
show_docstring_parameters: false | ||
--- | ||
|
||
::: mindwave.headset.BlinkEvent | ||
options: | ||
show_docstring_parameters: false | ||
--- | ||
|
||
::: mindwave.headset.SignalQualityEvent | ||
options: | ||
show_docstring_parameters: false | ||
--- | ||
|
||
::: mindwave.headset.TimeoutEvent | ||
options: | ||
show_docstring_parameters: false | ||
--- | ||
|
||
::: mindwave.session.SessionEvent | ||
options: | ||
show_docstring_parameters: false | ||
--- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
::: mindwave.utils.stream_parser.Data | ||
options: | ||
members: false | ||
--- | ||
|
||
::: mindwave.headset.MindWaveMobile2 | ||
options: | ||
show_docstring_functions: true |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
::: mindwave.session.SessionConfig | ||
|
||
::: mindwave.session.Session |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
::: mindwave.connector.ThinkGearConnector |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,109 @@ | ||
## Minimal working example | ||
A minimal example to start a functional data collection session | ||
```python linenums="1" | ||
from pymindwave2 import MindWaveMobile2, Session, SessionConfig | ||
|
||
# Initialize and connect to the headset | ||
headset = MindWaveMobile2() | ||
success = headset.start(n_tries=5, timeout=30) | ||
|
||
if success: # if the headset is connected successfully | ||
# Create a session configuration | ||
sess_config = SessionConfig( | ||
user_name="Ahmed", | ||
classes=["left", "right"] # Define your classification tasks | ||
) | ||
|
||
# Initialize and start the recording session | ||
session = Session(headset, config=sess_config) | ||
|
||
while headset.signal_quality != 100: | ||
pass # wait for the user to wear the headset properly | ||
|
||
session.start() # Start recording data | ||
|
||
while session.is_active: | ||
pass # wait for the session to finish | ||
|
||
session.save() # save the recorded data to disk | ||
``` | ||
--- | ||
## Session Configuration attributes | ||
```python linenums="1" | ||
sess_config = SessionConfig( | ||
user_name="Ahmed", # Name of the user | ||
user_age=0, # Age of the user | ||
classes=["left", "right", "foot"], # Classes used for motor imagery tasks | ||
n_trials=10, # Number of trials for each class | ||
capture_blinks=True, # Whether to capture blinks or not | ||
motor_duration=5, # Duration of each motor imagery task in seconds | ||
) | ||
``` | ||
for the full list of attributes, check [SessionConfig](https://princeegy.github.io/pymindwave2/api/session/#mindwave.session.SessionConfig) | ||
--- | ||
## Event Listeners | ||
An example to subscribe to headset data emitted events | ||
```python linenums="1" | ||
from pymindwave2 import MindWaveMobile2, HeadsetDataEvent | ||
|
||
headset = MindWaveMobile2() | ||
success = headset.start(n_tries=5, timeout=30) | ||
|
||
if sucess: | ||
def meditation_handler(event: HeadsetDataEvent): | ||
print(event.data.meditation) | ||
|
||
subscription = headset.on_data(meditation_handler) | ||
|
||
while some_condition: | ||
pass | ||
|
||
subscription.detach() # Unsubscribe from the event | ||
``` | ||
An example to reconnect to the headset if the connection is lost | ||
```python linenums="1" | ||
... # headset connection | ||
def reconnect_handler(event:HeadsetStatusEvent): | ||
if event.status == ConnectionStatus.CONNECTION_LOST: | ||
headset.start(n_tries=5, timeout=30) | ||
|
||
subscription = headset.on_status_change(reconnect_handler) | ||
``` | ||
|
||
Notify user when the headset is not worn properly | ||
```python linenums="1" | ||
... # headset connection | ||
def signal_quality_handler(event:SignalQualityEvent): | ||
if event.signal_quality < 100: | ||
print("Please wear the headset properly") | ||
|
||
subscription = headset.on_signal_quality_change(signal_quality_handler) | ||
``` | ||
--- | ||
Subscribe to session signals, such as start and end of each trial and phases of the trial. This can be used to build a GUI on top of it to create data collection environment. | ||
```python linenums="1" | ||
... # session and headset connection | ||
def session_handler(event:SessionEvent): | ||
signal = event.signal | ||
if signal == SessionSignal.SESSION_START: | ||
print("Session started") | ||
elif signal == SessionSignal.TRIAL_START: | ||
print("Trial started for class:", event.class_name) | ||
elif signal == SessionSignal.REST: | ||
print("Resting phase") | ||
elif signal == SessionSignal.READY: | ||
print("Ready for the motor imagery task") | ||
elif signal == SessionSignal.CUE: | ||
print("Cue for the motor imagery task") | ||
elif signal == SessionSignal.MOTOR : | ||
print("Motor imagery task") | ||
elif signal == SessionSignal.TRIAL_END: | ||
print("Trial ended") | ||
elif signal == SessionSignal.SESSION_END: | ||
print("Session ended") | ||
|
||
subscription = session.on_signal(session_handler) | ||
``` | ||
for the full list of Session Signals, check [SessionSignal](https://princeegy.github.io/pymindwave2/api/enums/#mindwave.session.SessionSignal) | ||
|
||
for the data collection session workflow, check [Session Workflow](https://princeegy.github.io/pymindwave2/api/session/#mindwave.session.Session) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
{% | ||
include-markdown "../README.md" | ||
start='<!-- Intro -->' | ||
end='<!-- Installation -->' | ||
%} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
{% | ||
include-markdown "../README.md" | ||
start='<!-- Installation -->' | ||
end='<!-- Usage -->' | ||
%} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
{% | ||
include-markdown "../README.md" | ||
start='<!-- Usage -->' | ||
end='<!-- Contributing -->' | ||
%} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,67 @@ | ||
site_name: PyMindWave2 Docs | ||
repo_url: https://github.com/PrinceEGY/pymindwave2 | ||
repo_name: PrinceEGY/pymindwave2 | ||
|
||
theme: | ||
name: material | ||
features: | ||
- toc.title | ||
- search.suggest | ||
- search.highlight | ||
- content.tabs.link | ||
- content.tabs.annotation | ||
- content.code.copy | ||
language: en | ||
|
||
plugins: | ||
- search | ||
- mkdocstrings: | ||
handlers: | ||
python: | ||
import: | ||
- https://docs.python.org/3/objects.inv | ||
|
||
options: | ||
docstring_style: google | ||
members_order: source | ||
merge_init_into_class: true | ||
show_root_heading: true | ||
show_root_full_path: false | ||
show_symbol_type_heading: true | ||
show_symbol_type_toc: true | ||
separate_signature: true | ||
signature_crossrefs: true | ||
show_signature_annotations: true | ||
docstring_options: | ||
ignore_init_summary: true | ||
|
||
- include-markdown | ||
|
||
nav: | ||
- Home: index.md | ||
- Installation: installation.md | ||
- Quick Start: quickstart.md | ||
- Examples: examples.md | ||
- API Documentaion: | ||
- MindwaveMobile2: api/headset.md | ||
- Session: api/session.md | ||
- Events: api/events.md | ||
- Enums: api/enums.md | ||
- ThinkGear Connector: api/tg_connector.md | ||
|
||
markdown_extensions: | ||
- pymdownx.highlight: | ||
anchor_linenums: true | ||
- pymdownx.inlinehilite | ||
- pymdownx.snippets | ||
- admonition | ||
- pymdownx.arithmatex: | ||
generic: true | ||
- footnotes | ||
- pymdownx.details | ||
- pymdownx.superfences | ||
- pymdownx.mark | ||
- attr_list | ||
|
||
copyright: | | ||
© 2024 <a href="https://github.com/PrinceEGY/" target="_blank" rel="noopener">PrinceEGY</a> |