openQCM the Java application for developers

In this post I discuss in detail the development of Java application for the open source quartz crystal microbalance openQCM. This post is intended for developers and contributors of the open source project. The entire project is available on github repository at this link


This is the latest release of openQCM Java software version 0.2. The main feature of this release is the development of a new graphical user interface (GUI) using NetBeans IDE GUI builder. The designer Glenda Torres Guizado and me have worked together for the development of the new graphical user interface . The overall structure of the software project is totally changed in order to use the Swing components of NetBeans. Moreover, it was added a method for smoothing the real time frequency and temperature data.

The main features of the latest openQCM application are:

  1. Connect Arduino find the COM port and set the serial connection between the Arduino board and your PC.
  2. Read Data read the QCM frequency and temperature data available at the connection COM port.
  3. Plot Data plot the QCM frequency and temperature data using a real time chart.
  4. Save Data save the frequency and temperature data in a text file.

System Configuration

The openQCM Java software is developed using Java 8 programming language and NetBeans development environment (IDE). You can download the Java Development Kit JDK 8u31 with NetBeans 8.0.2 at this link  I strongly suggest to uninstall any previous version of Java software in your machine before installing the latest version of JDK.
Download the entire project openQCM as ZIP folder and import the project as zip file in NetBeans IDE

File > Import Project > From zip …

Before compile and run the project you need to configure the RXTX Java library for the Java Runtime Engine JRE

RXTX Library Setting

openQCM Java project uses the RXTX Java library which provides serial communication for the Java Development Kit JDK. You can download the right library for your machine at this link 
Depending on your operating system you have to follow different procedures to correctly install the RXTX library. For more info on setting up the RXTX library see the Arduino and Java post on Arduino Playground and for advanced installation setting the RXTX wiki


Find the directory in which you have installed JDK and navigate to the jre directory:

C:\Program Files (x86)\Java\jdk1.8.0_20\jre

Open the folder containing the RXTX library and copy the following files in the java directories:

RXTXcomm.jar -> …\lib\ext
rxtxSerial.dll -> …\bin

Mac OS X

Copy RXTXcomm.jar from the library folder to /Library/Java/Extensions
Copy the MAC_OS_X/librxtxSerial.jnilib (or, if this version does not work for you, obtain a 64 bit compiled version) and paste into /Library/Java/Extensions
Append the directory containing librxtxSerial.jnilib files into your DYLD_LIBRARY_PATH environment variable, using the following command:

export DYLD_LIBRARY_PATH = /Library/Java/Extensions

You can encounter some issues with Mac OS X permissions and locking port system. In this case follow these instructions:

Open terminal and create the lock directory (as root) by using the following command:

sudo mkdir /var/lock

Apply the right permissions to the /var/lock directory by using these command:

sudo dscl . -append /groups/_uucp GroupMembership username
sudo chgrp uucp /var/lock
sudo chmod 775 /var/lock

Java Application Project

I will discuss in detail the whole openQCM Java software project trying to cover the key features of the source code. This section is intended for developers and contributors of the open source project.

NetBeans Swing GUI Builder

The software project takes advantage of the NetBeans built-in feature for creating graphical user interface the Swing GUI builder
Although many Java programmers dislike this function because you can loose the control of the generated code, in my opinion the Swing GUI builder is the only way for designing an awesome graphical user interface for your project. You can simply drag and drop the swing components from a palette in your frame. Then you are able to align and space the component to design your GUI. Moreover you can build your own Swing components, as I have done for this project by programming a swing component for the real time chart

Third-party Java Libraries

openQCM Java application is designed using the third-party Java libraries:


Ardulink  the open source Java library for control and communication with Arduino boards. The communication protocol of openQCM Java software is based on Ardulink. Ardulink also provides ready Java Swing components able to communicate with Arduino. In particular, it is used the Java Swing component for the serial connection with Arduino and for serial reading of the quartz crystal frequency and temperature data.


JFreeChart the open source Java libraries for displaying chart. openQCM software uses JFreeChart for dynamic displaying real time chart of frequency and temperature data.

Commons Math

Commons Math the Apache commons mathematics library. openQCM uses Commons Math mainly for real-time data processing. In particular the measurement of the quartz crystal frequency is affected by glitches, mainly caused by the algorithm for counting the number of pulses in a fixed interval of time. The frequency data are averaged over an interval of fixed data points for smoothing the glitches.

Connection to the Arduino Board

The openQCM communication protocol is based on Ardulink.
The Link class is the most important Ardulink class for communication between your computer and the Arduino board connected at the serial port portCOM. The connection and communication between the Arduino board and PC is implemented in the sequence of instructions:

// Ardulink link class for communication and connection with Arduino
private final Link link = Link.getDefaultInstance();
// Register a RawDataListener to receive data from Arduino
// Connect to the Arduino board

The Java mainGUI class implements the Ardulink interface RawDataListener The method of the class returns the string read at the serial port

public void parseInput(String id, int numBytes, int[] message) {

// here the custom code


The data string is formatted as “RAWMONITOR_frequency_temperature” . The string starts with “RAWMONITOR” in order to check if the message contains new data, in this way you can avoid any spurious message at the serial port.

Plot Data using Dynamic Chart

The frequency and temperature data read at the serial port are plotted in real time using the CombinedDomainXYPlot class of JfreeChart library. The dynamic chart is implemented in the class  The dynamic chart plot the data versus the current time, using a first axis for the frequency and a secondary axis for the temperature. The ChartPanel is not currently a JavaBean, so you can’t manipulate it with a GUI designer tool (see JfreeChart blog post at this link) I have added the ChartPanel to a Jpanel, so when you compile the project you can use the as a Swing component and manipulate it with the GUI designer.
The ChartDynamicData class was developed implementing these examples on
JFreeChart: Dynamic Data Demo 3: how to dynamically add data to a time series chart.
JFreeChart: Combined XY Plot Demo 4: how to add a second axis to combined XY plot

Data Processing

Data processing concerns mainly in an algorithm for smoothing the real time frequency and temperature data. The main goal of data processing is the smoothing of frequency glitches, which are caused by the algorithm for counting the number of pulses in a fixed interval of time.
To this aim I have used a moving average over a fixed time interval. The moving average is calculated as a standard mean on a FIFO circular buffer, which is implemented in the class

// insert new frequency data in circuar buffer and calculate the mean value
double sum = 0;
for (int i = 0; i < bufferFrequency.size(); i++) {
sum = sum + (int)[i];
double meanFrequency = sum / bufferFrequency.size();

The class was developed based on the work of Brad’s Source Code Blog  which is the most efficient example on circular buffer I have found in the internet (massive congrats and thank you Brad).

Save Data

The frequency and temperature can be saved on a text file in ASCII format. You can select the data file using the JFileChooser in

// open a file chooser
JFileChooser chooser = new JFileChooser();
FileNameExtensionFilter filter = new FileNameExtensionFilter(
"Text Files", "txt", "dat"
int option = chooser.showSaveDialog(this);
if (option == JFileChooser.APPROVE_OPTION) {
sf = chooser.getSelectedFile();

// here the custom code


You can select an existing file or create a new one. Once the data file is selected the software append the new data into the file. The data file is formatted as follows

date (MM/dd/yy)   hour (hh:mm:ss)   frequency(%.1f)   temperature(%.1f)


These are the main resources used for the development of the openQCM Java application plus a summary the references used overall in the post

openQCM open source project
openQCM the open source quartz crystal microbalance
openQCM Java software project repository
openQCM Java project download zip

Java JDK + NetBeans
Download Java Development Kit JDK 8u31 and NetBeans 8.0.2 at this link 

RXTX Java library
Interfacing Arduino and Java 
RXTX wiki

The Java project for the control of Arduino boards
Ardulink  Javadoc

Java chart library for displaying charts

Chart Dynamic Data
Dynamic time series chart
Add a second axis to XY chart

Circular Buffer
How to implement an efficient circular bufer in Java


  • Ben

    Awesome work guys.

    I have a question about the main arduino program (firmware) itself.
    it’s been defined a macro as ” #define ALIAS 8000000″, which for me seems to be redundant. As the “FreqCount” library gives the frequency as output, and this code “frequency = (2 * ALIAS) – count;” does not make sense.


    • Hi Ben thank you for comment ! I appreciate that you have read the firmware carefully, my answer

      The define “#define ALIAS 8000000” is necessary. Actually the “FreqCount” lib is able to read the frequency of a TTL signal up to 8 Mhz by using the 16 MHz clock of Arduino Micro. We have designed openQCM to work with 10 MHz AT-cut quartz crystal, so we are “under sampling” the digital signal in order to correctly measure the quartz vibrations. The code frequency = (2 * ALIAS) – count;” takes into account the under sampling condition.

      This “trick” does not affect the measurement of the variations in frequency. I mean a 1 Hz frequency variations is correctly measured by the under sampling scheme. I hope this helps. I will post something more specific on this topic definitely.


  • disqus_z6QwAdKvtH

    Hi all

    First, just to say ‘thank you’ for such a great concept and open-source product….

    Second, is it possible to tune the software for another frequency?

    Third, is there any way of looking at the frequency harmonics with this system?

    Fourth, is there a possibility of looking at dissipation effects via this system?

    I am now off to purchase one!


    • eMKi

      Hi, did you get your questions answered eventually?

      Thank you!

      • Hi… very sorry, but we lost the last message.
        Relatively the question of WJ., actually the system work well up to 6 MHz and at 10 MHz or 15 MHz, but it is not possible to looking to other harmonics or dissipation. We are working hard in order to release soon a new version with all these functionalities implemented…

        Relatively the dissipation, actually we are already able to do this measure, but to cause the patent protection we can’t sell the system with the ring-down technique. To this reason we are working at a new methodology.
        As soon as we will be ready we will communicate the news on this website.
        Thank you again.