Merge pull request #9 from xspanger3770/develop

Develop - 4.7.0

Author: xspanger3770

README.md

@@ -1,10 +1,16 @@
 # ZejfSeis
 
-ZejfSeis is a Java application designed to display data measured by a homemade seismometer. It communicates with [ZejfCSeis](https://github.com/xspanger3770/ZejfCSeis) through a TCP connection and provides real-time data display, browsing of stored data and also displaying nearby earthquakes that might have been detected.
+ZejfSeis is a user-friendly and easy to use Java application that allows for the display and analysis of seismic data captured by a homemade seismometer. With its intuitive interface, users can easily access a range of useful features, including real-time seismic plot display, spectrogram visualization, and browsing of recorded data in a drum-like style. In addition to these functionalities, the application offers a convenient and efficient way to store recorded earthquakes in a local database for later review and analysis. Whether you're a professional seismologist or simply an enthusiast, ZejfSeis is a powerful tool that can help you gain a deeper understanding of the Earth's seismic activity!
 
-## Socket connection
+## Getting started
 
-To connect to a running [ZejfCSeis](https://github.com/xspanger3770/ZejfCSeis) server, go to `Settings->Socket` and enter the IP address and port number of the server.
+To begin your seismology journey, it's recommended that you first review my tutorial on setting up the seismometer itself, which can be found at the following link: [Seismometer tutorial](https://github.com/xspanger3770/ZejfSeis/tree/develop/arduino). This guide provides clear and concise instructions for assembling and calibrating the seismometer, ensuring that it's ready to capture accurate seismic data.
+
+## Data source
+
+There are two ways of connecting ZejfSeis application to a running seismometer. The easiest way is to plug your Arduino directly to your computer's USB port and use `Connection->Serial Port` option in the upper menu, which will establish a direct connection and allow you to view incoming data with ease.
+
+Alternatively, you can opt for the slightly more involved approach of setting up a [ZejfCSeis](https://github.com/xspanger3770/ZejfCSeis) server on a separate device. While this requires a bit more setup time, it provides the benefit of running the project continuously and enabling you to connect to the running server from anywhere by simply entering its address under `Connection->Server`.
 
 ## Realtime tab
 The Realtime tab contains two main features. On the top is an interactive plot of the incoming data, which scales automatically based on the highest amplitude in the given time frame. The default setting for the time frame duration is 5 minutes and can be changed in `Settings->Realtime`.
@@ -13,15 +19,15 @@ The Realtime tab contains two main features. On the top is an interactive plot o
 
 The bottom section of the Realtime tab is a Spectrogram panel, which allows you to analyze the waveform in more detail and helps you distinguish between noise and real earthquakes. You can adjust the colors by setting the Spectrogram gain field in `Settings->Realtime` so that background noise is displayed as a dark blue color.
 
-![](https://user-images.githubusercontent.com/100421968/230724558-52bbcdf1-1ace-4fac-b23d-15c901bb1f0a.png)
+![](https://user-images.githubusercontent.com/100421968/232130962-271493b3-8b2e-41bc-902b-3cf56cbbf69a.png)
 
 ## Drum tab
 
 The Drum tab allows you to browse the recorded data. Each line represents a time interval, with its start labeled on the left side (red numbers indicating hours and gray ones minutes). By default, each line represents 10 minutes of data. For navigation, you can scroll with your mouse, or you can use the buttons on the upper control panel. The `<` button will move the drum by one line, and `<<` will move it by 10 lines. By pressing the `Now` button, you will move the drum to the latest data. To access older data, you can use the `Goto` button and enter a specific date and time. 
 
-The drum can be configured by accessing `Settings->Drum Settings`. By changing the value of `Gain`, you can adjust the scale of the waveform, and you can increase the `Decimate` field to lower the waveform resolution for better performance.
+The drum can be configured by accessing `Settings->Drum`. By changing the value of `Gain`, you can adjust the scale of the waveform, and you can increase the `Decimate` field to lower the waveform resolution for better performance.
 
-![](https://user-images.githubusercontent.com/100421968/230572243-ad604679-4adf-420e-9f8f-30c36f75cf50.png)
+![](https://user-images.githubusercontent.com/100421968/232131108-2ccce048-c082-4465-bd44-5f26395e212f.png)
 
 ### Data explorer
 
@@ -51,4 +57,4 @@ The status can be one of the following: `Unknown`, `Not Detected`, `Broken`, `No
 
 ## Filters
 
-All the data displayed in the application are filtered using a band-pass filter, meaning that frequencies outside the range specified at `Settings->Filter` will get attenuated. Additionally, there is a quick filter selector at the top of the main window. These filters makes it easier seeing earthquakes at different distances by filtering some noise out from the signal.
+All the data displayed in the application are filtered using a band-pass filter, which makes frequencies outside the range will get attenuated. You can configure the filter using the `Filters` menu. You can either select one of the prepared filters or create custom one in `Filters->Custom`. These filters makes it easier seeing earthquakes at different distances by filtering some noise out from the signal.

arduino/ADS1256_Seismo/ADS1256_Seismo.ino

@@ -0,0 +1,118 @@
+#include <ADS1256.h>
+#include <SPI.h>
+#include <filters.h>
+#include <limits.h>
+
+// FILTER
+
+const float cutoff_freq = 20.0;
+const float sampling_time = 1 / 400.0;
+IIR::ORDER order = IIR::ORDER::OD4;
+
+Filter filter(cutoff_freq, sampling_time, order);
+
+// ADC
+
+#define PIN_DRDY 9
+
+float clockMHZ = 7.68; // crystal frequency used on ADS1256
+float vRef = 2.5;      // voltage reference
+
+// Construct and init ADS1256 object
+ADS1256 adc(clockMHZ, vRef, false); // RESETPIN is permanently tied to 3.3v
+
+// SAMPLING
+
+const int SAMPLE_RATES[5] = { 20, 40, 60, 100, 200 };
+
+int sample_rate;
+long sample_time_micros;
+
+// RUNTIME
+
+unsigned long last_time;
+unsigned long current_time;
+
+double reading;
+long double sum;
+int count;
+long value;
+
+byte log_num;
+int shift;
+
+char ch;
+
+void get_sample_rate()
+{
+    int index = 1;
+    Serial.println("Please select sample rate");
+    while (true) {
+        char ch = Serial.read();
+        index = ch - '0';
+        if (index >= 0 && index < 5) {
+            break;
+        }
+    }
+
+    shift = 0;
+    sample_rate = SAMPLE_RATES[index];
+    sample_time_micros = 1000000 / sample_rate;
+
+    Serial.print("Selected ");
+    Serial.print(sample_rate);
+    Serial.println(" sps");
+
+    last_time = 0;
+    sum = 0;
+    count = 0;
+    log_num = 0;
+    shift = 0;
+}
+
+void setup()
+{
+    Serial.begin(115200);
+
+    get_sample_rate();
+
+    adc.begin(ADS1256_DRATE_500SPS, ADS1256_GAIN_64, false);
+}
+
+void loop()
+{
+    if (!(digitalRead(PIN_DRDY))) {
+        reading = filter.filterIn((adc.readCurrentChannel() / (2.0 * vRef)) * 0x7FFFFF);
+        sum += reading;
+        count++;
+    }
+
+    current_time = micros();
+
+    if (abs(current_time - last_time) >= sample_time_micros + shift) {
+        value = round(sum / count);
+        sum = 0;
+        count = 0;
+
+        Serial.print('s');
+        Serial.print(shift);
+        Serial.print('l');
+        Serial.print(log_num);
+        Serial.print('v');
+        Serial.println(value);
+
+        last_time = current_time;
+        log_num++;
+    }
+
+    if (Serial.available()) {
+        ch = Serial.read();
+        if (ch == '-' && shift != INT_MIN) {
+            shift--;
+        } else if (ch == '+' && shift != INT_MAX) {
+            shift++;
+        } else if (ch == 'r') {
+            get_sample_rate();
+        }
+    }
+}

arduino/ADS1263_Seismo/ADS1263_Seismo.ino

@@ -0,0 +1,165 @@
+#include <ADS126X.h>
+#include <SPI.h>
+#include <filters.h>
+#include <limits.h>
+
+// FILTER
+
+float cutoff_freq = 20.0;
+const float sampling_time = 1 / 1200.0;
+IIR::ORDER order = IIR::ORDER::OD4;
+
+Filter filter(cutoff_freq, sampling_time, order);
+
+// ADC
+
+#define PIN_DRDY 9
+#define PIN_CS 10
+
+#define POS_PIN ADS126X_AIN1
+#define NEG_PIN ADS126X_AIN0
+#define ADS_SAMPLE_RATE ADS126X_RATE_1200
+
+ADS126X adc;
+
+// SAMPLING
+
+const int SAMPLE_RATES[5] = { 20, 40, 60, 100, 200 };
+
+int sample_rate;
+long sample_time_micros;
+
+// RUNTIME
+
+#define CALIBRATION_SECONDS 20
+#define IGNORE 20
+
+bool calibrating;
+long offset;
+
+unsigned long last_time;
+unsigned long current_time;
+
+long double sum;
+unsigned int count;
+long value;
+
+byte log_num;
+int shift;
+
+char ch;
+
+void get_sample_rate()
+{
+    int index = 1;
+    Serial.println("Please select sample rate");
+    while (true) {
+        char ch = Serial.read();
+        index = ch - '0';
+        if (index >= 0 && index < 5) {
+            break;
+        }
+    }
+
+    shift = 0;
+    sample_rate = SAMPLE_RATES[index];
+    sample_time_micros = 1000000 / sample_rate;
+
+    cutoff_freq = sample_rate / 2.0;
+    filter.setCutoffFreqHZ(cutoff_freq);
+
+    Serial.print("Selected ");
+    Serial.print(sample_rate);
+    Serial.println(" sps");
+
+    last_time = 0;
+    sum = 0;
+    count = 0;
+    log_num = 0;
+    shift = 0;
+    calibrating = true;
+    offset = 0;
+    Serial.println("Offset calibration start, be patient...");
+}
+
+void setup()
+{
+    Serial.begin(115200);
+
+    get_sample_rate();
+
+    adc.begin(PIN_CS);
+    delay(10);
+    adc.setRate(ADS_SAMPLE_RATE);
+    delay(10);
+    adc.startADC1();
+    delay(10);
+    adc.setGain(ADS126X_GAIN_32);
+    delay(10);
+    adc.setFilter(ADS126X_SINC4);
+    delay(10);
+    adc.setBiasMagnitude(ADS126X_BIAS_MAG_0);
+    delay(10);
+    adc.setReference(ADS126X_REF_NEG_VSS, ADS126X_REF_POS_VDD);
+}
+
+void loop()
+{
+    bool rdy = !(digitalRead(PIN_DRDY));
+    if (rdy) {
+        if (calibrating && count >= IGNORE) {
+            sum += adc.readADC1(POS_PIN, NEG_PIN);
+            count++;
+        } else {
+            sum += filter.filterIn(adc.readADC1(POS_PIN, NEG_PIN)) - offset;
+            count++;
+        }
+    }
+
+    current_time = micros();
+
+    if (calibrating) {
+        if (count % (1200 * 5) == 0 && rdy) {
+            Serial.println("wait...");
+        }
+        if (count >= CALIBRATION_SECONDS * 1200) {
+            calibrating = false;
+            offset = round(sum / count);
+            sum = 0;
+            count = 0;
+            Serial.print("Offset calibration finish, offset = ");
+            Serial.println(offset);
+        }
+    } else if (abs(current_time - last_time) >= sample_time_micros + shift) {
+        value = round(sum / count);
+        sum = 0;
+        count = 0;
+
+        Serial.print('s');
+        Serial.print(shift);
+        Serial.print('l');
+        Serial.print(log_num);
+        Serial.print('v');
+        Serial.println(value);
+
+        last_time = current_time;
+        log_num++;
+    }
+
+    if (Serial.available()) {
+        ch = Serial.read();
+        if (ch == '-' && shift != INT_MIN) {
+            shift--;
+        } else if (ch == '+' && shift != INT_MAX) {
+            shift++;
+        } else if (ch == 'r') {
+            get_sample_rate();
+        } else if (ch == 'c') {
+            adc.calibrateSysOffsetADC1(POS_PIN, NEG_PIN);
+        } else if (ch == 's') {
+            adc.calibrateSelfOffsetADC1();
+        } else if (ch == 'b') {
+            adc.setGain(ADS126X_GAIN_32);
+        }
+    }
+}

arduino/README.md

@@ -0,0 +1,50 @@
+# Seismometer
+
+The seimometer itself is Lehman type seismometer.
+
+A Lehman type seismometer is a device used to detect ground motion caused by seismic activity. It uses a horizontal beam pendulum that is suspended from a stationary frame. The pendulum has a magnet attached to it and a copper coil is positioned nearby. When ground motion occurs, the magnet moves past the copper coil, inducing an electrical current which can be detected and recorded by a sensitive amplifier or data acquisition system. The Lehman seismometer is designed to be very sensitive, able to detect ground motion on the order of a few micrometers.
+
+There are a lot of tutorials online of how you can build one. You can also get an inspiration from my setup:
+
+__TODO insert pictures__
+
+## A few important notes
+
+### Damping
+
+Damping is an essential aspect of seismometer design as it reduces unwanted noise and enhances sensitivity. In my design, a plastic plate is submerged in highly viscous fluid - motor oil. This fluid provides resistance to the pendulum's motion, causing it to come to rest gradually and reducing the amplitude of its oscillations. Without this damping mechanism, the pendulum would continue to swing due to inertia, making it difficult to distinguish between seismic waves and noise. Damping ensures the pendulum settles into a stable position and detects even the smallest ground movements, improving the instrument's precision. Other damping techniques, such as magnets or electrical feedback, may also be used to enhance seismometer sensitivity.
+
+### Frame angle
+
+The angle of the frame relative to the vertical determines the natural period of the pendulum in a seismometer. A lower angle results in a longer period, which allows for more precise detection of long-period waves generated by major earthquakes. However, increasing the period too much can cause the pendulum to become difficult to center, leading to it getting stuck on the sides of the coil. Finding the optimal angle, therefore, requires a careful balancing of these factors. In my case, I was only able to get about 12 seconds of resonant period before the design become unstable.
+
+### The magnets
+
+As you can see, I used two strong neodymium magnets on both sides of the copper coil to increase induction and the instrument's overall gain. It is crucial to ensure that the magnets are correctly oriented with the same poles facing each other. This results in a highly concentrated magnetic field inside the coil while reducing the magnetic field on the outside. The high concentration of the magnetic field inside the coil results in increased sensitivity, allowing the seismometer to detect even the smallest ground movements.
+
+__TODO insert pictures__
+
+While the current design of my seismometer has proven to be effective, there is still room for improvement. One area for enhancement is the use of materials, specifically the wooden beams. Wood has some degree of elasticity, which can cause the vertical beam to bend under the weight of the pendulum. To improve stability and sensitivity, better materials such as aluminum could be used instead. Additionally, the metal string that holds the pendulum may be too rigid, resulting in unwanted forces that deviate it from its central position. This can limit the maximum achievable resonance period and reduce the overall accuracy of the instrument. To overcome this issue, a more flexible string or cable could be used, allowing for smoother and more precise pendulum movements. By addressing these design considerations, the performance and accuracy of the seismometer can be further enhanced.
+
+## ADC
+In my project, an analog to digital converter (ADC) is used to achieve this conversion. The ADC device is wired up to an Arduino microcontroller, which serves as the brain of the system. The Arduino reads the digital data from the ADC and takes care of time synchronization, ensuring that the recorded data is accurately time-stamped. Once the data is prepared by the Arduino, it is sent to ZejfCSeis. This is done via a USB connection, allowing for real-time data transfer and continuous monitoring of seismic activity.
+
+The use of modern digital technology and open-source software tools has greatly improved the accessibility and affordability of seismometers, enabling a wider range of enthusiasts like me to study earthquakes and other seismic events.
+
+Currently, 2 highly accurate ADC's are supported: 24-bit ADS1256 and 32-bit ADS1263 and support for more can be easily added.
+
+### ADS1256
+
+To use the ADS1256 analog to digital converter, you will first need two Arduino libraries: [ADS1256](https://github.com/adienakhmad/ADS1256) and [libFilter](https://github.com/MartinBloedorn/libFilter). Install them as any other Arduino libraries by pasting the folders into Arduino/libraries folder on your computer. After wiring up the ADS1256, use Arduino IDE to upload sketch `ADS1256_Seismo` located in this directory.
+
+Here is the wiring for Arduino Nano - the two wires on the right connect directly to the seimometer main coil:
+
+<img src=https://user-images.githubusercontent.com/100421968/231836782-62f4d2d0-edd1-488e-90dd-6f7269f3b97f.jpg width=600 height=420>
+
+I was using this ADC for about one year and it worked perfectly fine as I was able to detect many earthquakes every day from around the world. Later I switched to the more accurate ADS1263 to push the sensitivity to the limit. 
+
+### ADS1263
+
+Hooking up the ADS1263 is pretty simmilar to the ADS1256. The Arduino library for it can be found here: [ADS126X](https://github.com/Molorius/ADS126X) and after installing it you can upload `ADS1263_Seismo` sketch located in this directory.
+
+__TODO image__

pom.xml

@@ -5,6 +5,12 @@
   <version>0.0.1-SNAPSHOT</version>
 
   <dependencies>
+  		<!-- https://mvnrepository.com/artifact/com.fazecast/jSerialComm -->
+  		<dependency>
+			<groupId>com.fazecast</groupId>
+			<artifactId>jSerialComm</artifactId>
+			<version>2.7.0</version>
+		</dependency>
 		<!-- https://mvnrepository.com/artifact/edu.emory.mathcs/JTransforms -->
 		<dependency>
 			<groupId>edu.emory.mathcs</groupId>