Skip to content

Commit 2216f99

Browse files
Ankit-dhillonAnkit-dhillon
committed
Added documentation for Chords Java
1 parent 0305518 commit 2216f99

File tree

4 files changed

+150
-0
lines changed

4 files changed

+150
-0
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/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)