Skip to content

Commit 40c7267

Browse files
RupJyotiUXRupJyotiUX
authored
Merge branch 'upsidedownlabs:main' into main
2 parents 8f67aae + 340e139 commit 40c7267

File tree

5 files changed

+246
-36
lines changed

5 files changed

+246
-36
lines changed

‎software/chords/chords-java/index.rst

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
.. _chords-java:
2+
3+
Chords-Java
4+
############
5+
6+
.. youtube:: sQgg8CEn9PY
7+
8+
Overview
9+
********
10+
11+
**Chords Java** is an open-source Java-based project to acquire, visualize, and stream real-time biopotential signals such as **ECG**, **EMG**, **EEG**, and **EOG** from BioAmp hardware. Built with JavaFX and supporting LSL (Lab Streaming Layer), it provides a reliable, low-latency interface for research, prototyping, and educational neuroscience.
12+
13+
Features
14+
********
15+
16+
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
17+
| Feature | Description |
18+
+===========================+==================================================================================================================================================================+
19+
| USB Serial Connection | Detects and connects to compatible development boards over USB using `jSerialComm`. Supports real-time data acquisition without missing samples. |
20+
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
21+
| Real-Time Visualization | Displays multi-channel biopotential data with smooth waveform scrolling using JavaFX LineCharts. |
22+
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
23+
| Sample Miss Detection | Automatically detects and notifies on packet loss or missing samples using packet counters in the firmware. |
24+
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
25+
| LSL Streaming | Streams synchronized multi-channel signals using Lab Streaming Layer (LSL), making it compatible with tools like Chords-LSL-Visualizer, OpenViBE, and Open Ephys |
26+
+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
27+
28+
29+
Software Requirements
30+
*********************
31+
32+
- `Java Development Kit (JDK 17+) <https://www.oracle.com/in/java/technologies/downloads/>`_ – Required for compiling and running the application
33+
- `VS Code <https://code.visualstudio.com/>`_ or any Java-compatible IDE
34+
- `jSerialComm <https://fazecast.github.io/jSerialComm/>`_ (already bundled in the repo)
35+
- `Arduino IDE <https://support.arduino.cc/hc/en-us/articles/360019833020-Download-and-install-Arduino-IDE>`_ - Required to upload firmware into the arduino board
36+
- `Chords-LSL-Visualizer <https://github.com/upsidedownlabs/Chords-LSL-Visualizer/releases/tag/v0.1.0>`_ - for live LSL streaming of data
37+
38+
Hardware Requirements
39+
*********************
40+
41+
To use Chords-Java, you need:
42+
43+
- A development board running `Chords Arduino Firmware <https://github.com/upsidedownlabs/Chords-Arduino-Firmware>`_
44+
- A USB cable
45+
- :ref:`BioAmp Hardware<upsidedownlabs_hardware_home>` and accessories (like electrodes)
46+
47+
Setting up the Hardware
48+
***********************
49+
50+
Connect your BioAmp signal chain:
51+
52+
1. Connect the gel electrodes or dry electrodes according to the type of signal being measured, such as ECG or EMG. For detailed placement guide :ref:`visit<using-gel-electrodes>`.
53+
2. Plug the BioAmp Hardware to the development board (e.g., Arduino UNO R4, ESP32, etc.).
54+
3. Connect the board to your laptop via USB.
55+
4. Upload the firmware (with correct baud rate and protocol) using Arduino IDE.
56+
57+
Uploading the Firmware
58+
**********************
59+
60+
- Go to the `Chords Arduino Firmware <https://github.com/upsidedownlabs/Chords-Arduino-Firmware>`_ repo.
61+
- Find your board in the supported boards table.
62+
- Copy and paste the sketch into the Arduino IDE.
63+
- Select the correct board and COM port under **Tools**.
64+
- Upload the code.
65+
66+
.. _using-chords-java:
67+
68+
Using Chords-Java
69+
******************
70+
71+
To launch and run the Java project:
72+
73+
1. **Download the Repository**:
74+
75+
- Visit `Chords-Java GitHub Repository <https://github.com/upsidedownlabs/Chords-Java>`_
76+
- Or use Git Bash.
77+
78+
.. code-block:: console
79+
80+
git clone https://github.com/upsidedownlabs/Chords-Java.git
81+
82+
2. **Navigate to project folder**:
83+
84+
- Open Windows Terminal by ``Win + X`` and choose **Windows Terminal** from the menu. Alternatively, press ``Win + S``, type *Windows Terminal*, and press **Enter**.
85+
- Use the ``cd`` (change directory) command to go to the folder where your project is located. For example:
86+
87+
.. code-block:: powershell
88+
89+
cd "C:\Users\YourName\Downloads\Chords-Java"
90+
91+
Replace the example path with the actual path to your project directory.
92+
93+
3. **Compile and Run**:
94+
95+
For Comp
96+
- Use the following command to compile the code:
97+
98+
.. code-block:: console
99+
100+
javac -d bin -cp "lib/*" src/ChordsUSB.java examples/ChordsLSLStreamer.java
101+
102+
- Use the following command to run the code:
103+
104+
.. code-block:: console
105+
106+
java '-Djna.library.path=lib' -cp "bin;lib/*" ChordsLSLStreamer
107+
108+
109+
LSL Streaming
110+
*************
111+
112+
To stream data into tools like `Chords LSL Visualizer <https://github.com/upsidedownlabs/Chords-LSL-Visualizer>`_:
113+
114+
1. Upload firmware with LSL support.
115+
2. Run the ``ChordsLSLStreamer.java`` class.
116+
3. Ensure your PC can detect the USB device.
117+
4. A stream named ``Chords_USB_Stream`` will appear in your LSL tool when you click on ``Refresh``.
118+
5. Start the stream and visualize the live data.
119+
120+
.. note::
121+
LSL streaming is essential for running cross-platform applications and tools.
122+
123+
Applications
124+
************
125+
126+
1. Electrocardiography (ECG)
127+
==============================
128+
129+
.. figure:: ./media/ECG_img.*
130+
:align: center
131+
:alt: Interface in Light Mode
132+
133+
- Displays real-time ECG waveform
134+
135+
2. Electromyography (EMG)
136+
==========================
137+
138+
.. figure:: ./media/EMG_img.*
139+
:align: center
140+
:alt: Interface in Light Mode
141+
142+
- Visualizes filtered EMG signal and smooth envelope
143+
- Detects muscle activity in real time
144+
- Supports fine-tuning of RMS window and filtering parameters

‎software/chords/chords-java/media/ECG_img.png

68 KB
Loading

‎software/chords/chords-java/media/EMG_img.png

103 KB
Loading

‎software/chords/chords-python/index.rst

Lines changed: 96 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -62,60 +62,55 @@ Go to tools, select your board, and the correct COM port. Now, hit the upload bu
6262
Opening Chords-Python
6363
*********************
6464

65-
Follow these steps to set up and install Chords-Python:
65+
There are two ways to use Chords-Python:
6666

67-
1. Ensure you have latest version of Python installed.
68-
2. **Download the GitHub repository**:
67+
**A. Using the `chordspy` Python Package (Recommended)**
6968

70-
- You can download the Chords-Python repository from GitHub by visiting the following link: `Chords-Python <https://github.com/upsidedownlabs/Chords-Python/>`_.
71-
- Or, You can clone the repository using Git by running the following command:
69+
**B. Running Scripts Manually from the Repository**
7270

73-
.. code-block:: console
74-
75-
git clone https://github.com/upsidedownlabs/Chords-Python.git
71+
A. Using the chordspy Package
72+
=============================
7673

77-
3. **Create a Virtual Environment**:
78-
79-
A virtual environment allows you to manage dependencies for your project in isolation.
74+
This is the smoothest way to get started. Follow the steps below:
8075

81-
- Open a terminal or command prompt.
82-
- Navigate to the directory where you have cloned the repository.
83-
- Run the following command to create a virtual environment:
76+
1. **Install Python**
77+
Make sure latest version of Python is installed.
8478

85-
.. code-block:: console
86-
87-
python -m venv venv
79+
2. **Create and Activate a Virtual Environment**:
80+
81+
- **On Windows**:
8882

89-
- To activate the virtual environment:
90-
- **On Windows**:
9183
.. code-block:: console
9284
93-
.\venv\Scripts\activate
85+
python -m venv .venv
9486
95-
- **On macOS/Linux**:
96-
.. code-block:: python
97-
98-
source venv/bin/activate
87+
.. code-block:: console
9988
100-
4. **Install the Required Python Libraries**:
89+
.venv\Scripts\activate
10190
102-
Once the virtual environment is activated, you need to install the required libraries for the project.
91+
- **On macOS/Linux**:
10392

104-
- In the terminal or command prompt, run the following command to install the dependencies needed to run the python script listed in the `requirements.txt` file:
93+
.. code-block:: console
94+
95+
python3 -m venv .venv
96+
97+
.. code-block:: console
98+
99+
source .venv/bin/activate
100+
101+
3. **Install the Package**:
105102

106103
.. code-block:: console
107-
108-
pip install -r requirements.txt
109104
110-
- This will install all the necessary Python libraries and dependencies for Chords-Python.
105+
pip install chordspy
111106
112-
5. To launch the Flask server, run the following command :
107+
4. **Launch the Web Interface**:
113108

114-
.. code-block:: python
115-
116-
python app.py
109+
.. code-block:: console
117110
118-
Click on the generated link to open the web interface.
111+
chordspy
112+
113+
A web interface will open where you can connect your device and access applications.
119114

120115
.. figure:: ./media/light-interface.*
121116
:align: center
@@ -129,6 +124,67 @@ Click on the generated link to open the web interface.
129124

130125
Interface in Dark Mode
131126

127+
B. Running Scripts Manually (Alternative)
128+
=========================================
129+
130+
If you prefer running scripts directly (for development, debugging, or customization):
131+
132+
1. **Download the Repository**:
133+
134+
- You can download the Chords-Python repository from GitHub by visiting the following link: `Chords-Python <https://github.com/upsidedownlabs/Chords-Python/>`_.
135+
136+
- Or, you can clone the repository using Git by running the following command:
137+
138+
.. code-block:: console
139+
140+
git clone https://github.com/upsidedownlabs/Chords-Python.git
141+
142+
2. **Create and Activate a Virtual Environment** (if not already):
143+
144+
- **On Windows**:
145+
146+
.. code-block:: console
147+
148+
python -m venv .venv
149+
150+
.. code-block:: console
151+
152+
.venv\Scripts\activate
153+
154+
- **On macOS/Linux**:
155+
156+
.. code-block:: console
157+
158+
python3 -m venv .venv
159+
160+
.. code-block:: console
161+
162+
source .venv/bin/activate
163+
164+
3. **Install Requirements**:
165+
166+
.. code-block:: console
167+
168+
pip install -r requirements.txt
169+
170+
4. **Run the Application**:
171+
172+
Navigate to the `chordspy` folder and run:
173+
174+
.. code-block:: console
175+
176+
python -m chordspy.app # To launch the web interface
177+
python -m chordspy.connection --protocol usb # To start LSL stream via USB
178+
python -m chordspy.connection --protocol ble # To start LSL stream via BLE
179+
python -m chordspy.connection --protocol wifi # To start LSL stream via WiFi
180+
181+
To run any application, open a new terminal:
182+
183+
.. code-block:: console
184+
185+
python chordspy.gui.py # GUI Application
186+
python chordspy.ffteeg.py # EEG with FFT Analysis
187+
132188
Connection
133189
**********
134190

@@ -249,7 +305,7 @@ A GUI window will appear, displaying the real-time ECG signal along with the cal
249305
2. `EMG with Envelope`
250306
======================
251307

252-
.. youtube:: tZud2tc-TGITiDwSQEY2eY&t=23s
308+
.. youtube:: TiDwSQEY2eY
253309

254310
Overview
255311
--------
@@ -323,6 +379,8 @@ A GUI window will appear, displaying the real-time EOG signal along with the Bli
323379
4. `EEG with FFT`
324380
=================
325381

382+
.. youtube:: yVD9KmyZgxA
383+
326384
Overview
327385
--------
328386

@@ -497,6 +555,8 @@ A GUI window will appear that shows the data in real-time.
497555
8. `EOG Keystroke Emulator`
498556
===========================
499557

558+
.. youtube:: ZJmUUtHJj08
559+
500560
Overview
501561
--------
502562

‎software/index.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,11 @@ Chords Software Suite
3030
:text-align: center
3131
:link: chords-lsl-connector
3232
:link-type: ref
33+
34+
.. grid-item-card:: Chords Java
35+
:text-align: center
36+
:link: chords-java
37+
:link-type: ref
3338

3439
Tools
3540
============================
@@ -84,6 +89,7 @@ BioAmp Firmware
8489
chords/chords-web/index
8590
chords/chords-python/index
8691
chords/chords-lsl-connector/index
92+
chords/chords-java/index
8793

8894

8995
.. toctree::

0 commit comments

Comments
 (0)