The nice thing about all of this is that I can push a code change to git, and Jenkins can build it, run through all the tests and then deploy to production automatically.

Layout of a pipeline script

Pipeline scripts are written in Groovy, which is a variant of Java. In general, a pipeline script is laid out like this:

node {
    def SOME_CONSTANT = "whatever"
    ...

    stage('some stage name like Build') {
        // Stuff to do as a part of this stage
    }

    stage('another stage') {
        // More stuff
    }

    ...
}

Each stage represents a stage in the pipeline (e.g. building, beta deployment, prod deployment etc.)

Defining some constants

First, a list of constants can be defined that can be used throughout the pipeline so that if the pipeline script gets reused somewhere, only these constants have to be changed. I’m not aware of anything that lets me reuse a pipeline in Jenkins without copying and pasting the code somewhere else so for now I’ll have to live with copying and pasting.

My project uses Maven so I got Jenkins to download its own copy of Maven that it can use to execute builds and have defined it as a constant. The name I’ve given it in the Jenkins Global Tool Configuration is “Maven 3.3.9” exactly. My project also uses Tomcat so there are some Tomcat specific things in there that may or may not be relevant to your use case.

def MAVEN_HOME = tool 'Maven 3.3.9'
    def WORKSPACE = pwd()

    def PROJECT_NAME = "name-of-project"
    def WAR_PATH_RELATIVE = "App/target/${PROJECT_NAME}.war"
    def WAR_PATH_FULL = "${WORKSPACE}/${WAR_PATH_RELATIVE}"
    def TOMCAT_CTX_PATH_BETA = "Tomcat-context-path-for-the-beta-stage"
    def TOMCAT_CTX_PATH_PROD = "Tomcat-context-path-for-the-prod-stage"
    def GIT_REPO_URL = "URL-to-git-repo-ending-in-.git"

Preparation Stage

First, the code has to be retrieved from the repository before it gets built. Jenkins allows storing username/password pairs so that they can be referenced without having to write out the password in plaintext. Jenkins uses a “credential ID” for this.

    stage('Preparation') {
        git branch: "master",
        credentialsId: "credentials-ID-stored-in-Jenkins-that-can-access-the-git-repo",
        url: "${GIT_REPO_URL}"
    }

Build Stage

Next, the code must be built and unit tested. “mvn clean install” will do just that (depending on what you want, you can always put in a different maven goal). The junit command is just there to take the resulting XML that gets generated during the build process and posts a graph of how many tests were run for each build.

    stage('Build') {
        sh "'${MAVEN_HOME}/bin/mvn' clean install"
        junit '**/target/surefire-reports/TEST-*.xml'
    }

Beta Stage

Once the build succeeds, you’ll want to deploy it to a beta environment, so integration tests can happen. The following happens at this stage:

1. Get the right credentials to get permissions to Tomcat
2. Call the deploy method to deploy the war file in Tomcat (more on that later)
3. If the deployment fails for whatever reason, print out the deployment log for debugging and fail the build
4. If the deployment succeeds, run the integration tests (the command to do this may differ based on use case)

    stage('Beta') {
        withCredentials([[$class: 'UsernamePasswordMultiBinding',
            credentialsId: 'credential-id-for-tomcat',
            usernameVariable: 'USERNAME', passwordVariable: 'PASSWORD']]) {
                // Password is available as an env variable, but will be masked 
                // if you try to print it out any which way
                def output = deploy(WAR_PATH_FULL, TOMCAT_CTX_PATH_BETA,
                        env.USERNAME, env.PASSWORD)
                if (output.contains("FAIL - Deployed application at context path " + 
                        "/${TOMCAT_CTX_PATH_BETA} but context failed to start")) {
                    echo "----- Beta deployment log -----"
                    echo output
                    echo "-------------------------------"
                    currentBuild.result = 'FAILURE'
                    error "Beta stage deployment failure"
                }
            }

        echo "Running integration tests"
        sh "'${MAVEN_HOME}/bin/mvn' -Dtest=*IT test"
        junit '**/target/surefire-reports/TEST-*.xml'
    }

The deploy method is what takes care of the actual deployment to Tomcat, which is how the Jenkins build tells Tomcat about the newly built war file. The deploy method is below (be sure to change the server IP and port). Alternatively, I could have built my project as an embedded jar file, but that has a different challenge in figuring out how to get Jenkins to tell the OS to execute the newly built jar file as a particular user.

1. Based on the Tomcat context path, decide whether a beta or production deployment is happening
2. Make a copy of the build war file and add .prod or .beta to the end of it so as to keep the original
3. Set the Spring profile to use on the newly copied war file (more on that later)
4. Call the curl command to do the actual deployment to Tomcat (more on that later)

def deploy(warPathFull, tomcatCtxPath, username, password) {
    def envSuffix = ""
    def isBeta = tomcatCtxPath.contains("beta")
    if (isBeta) {
        envSuffix = "beta"
    } else {
        envSuffix = "prod"
    }
    sh script: "cp ${warPathFull} ${warPathFull}.${envSuffix}" 
    setSpringProfile(warPathFull, isBeta)
    def output = sh script: "curl --upload-file '${warPathFull}.${envSuffix}' " +
            "'http://${username}:${password}@localhost:8081/manager/text/deploy" + 
            "?path=/${tomcatCtxPath}&update=true'", returnStdout: true
    return output
}

In the case of my project, I’m building a single war file that does not have a Spring profile (beta/prod) defined. This means that I have to manually define this before I deploy the app to Tomcat since there are some things that differ between beta and prod like database URL’s. To do this, I wrote a method that opens the war file like a zip (jar/war files are zip files) and adds a line to my application.properties to define a Spring profile.

Admittedly, doing this zip file manipulation seems kind of hacky. Alternatively, I could have defined my build such that I had a separate beta build and a prod build to avoid modifying the zip file, but the drawback is that I’d then have to build my code twice.

def setSpringProfile(warPathFull, isBeta) {
    def zipFileFullPath = warPathFull + "." + (isBeta ? "beta" : "prod")
    def zipIn = new File(zipFileFullPath)
    def zip = new ZipFile(zipIn)
    def zipTemp = File.createTempFile("temp_${System.nanoTime()}", 'zip')
    zipTemp.deleteOnExit()
    def zos = new ZipOutputStream(new FileOutputStream(zipTemp))
    def toModify = "WEB-INF/classes/application.properties"

    for(e in zip.entries()) {
        if(!e.name.equalsIgnoreCase(toModify)) {
            zos.putNextEntry(e)
            zos << zip.getInputStream(e).bytes
        } else {
            zos.putNextEntry(new ZipEntry(toModify))
            zos << zip.getInputStream(e).bytes
            zos << ("\nspring.profiles.active=" + (isBeta ? "beta" : "prod")).bytes
        }
        zos.closeEntry()
    }

    zos.close()
    zipIn.delete()
    zipTemp.renameTo(zipIn)
}

A curl command to Tomcat is what actually does the deployment. To deploy a file to Tomcat, do the following below. This will deploy the war file to Tomcat and instantly run it, thus it will be accessible at the given context path.

curl --upload-file 'path-to-war-file' http://username:password@server-address:port/manager/text/deploy?path=/tomcat-context-path&update=true

Prod Stage

The same kind of stuff happens in the prod stage as in the beta stage with a few exceptions. The following happens at this stage:

1. Get the right credentials to get permissions to Tomcat
2. Call the deploy method to deploy the war file in Tomcat (except this time it is prod)
3. If the deployment fails for whatever reason, print out the deployment log for debugging and roll back the deployment
4. If the deployment succeeds, save the build files, and then the pipeline is finished. Alternatively, smoke tests can be run at this point, but I did not implement this in my project

Rollback is important because if the deployment fails, you don’t want to be stuck with a broken environment. Since build artifacts are saved on successful deployments, these same artifacts can be brought back if future deployments fail. This means they can be redeployed so that the code can be fixed before another deployment happens.

    stage('Prod') {
        withCredentials([[$class: 'UsernamePasswordMultiBinding',
            credentialsId: 'credential-id-for-tomcat',
            usernameVariable: 'USERNAME', passwordVariable: 'PASSWORD']]) {
                // Password is available as an env variable, but will be masked 
                // if you try to print it out any which way
                def output = deploy(WAR_PATH_FULL, TOMCAT_CTX_PATH_PROD, env.USERNAME, env.PASSWORD)
                if (output.contains("FAIL - Deployed application at context path " + 
                        "/${TOMCAT_CTX_PATH_PROD} but context failed to start")) {
                    echo "Prod stage deployment failure, rolling back deployment"
                    echo "----- Prod deployment log -----"
                    echo output
                    echo "-------------------------------"
                    step([$class: 'CopyArtifact',
                            filter: "${WAR_PATH_RELATIVE}",
                            fingerprintArtifacts: true,
                            projectName: "${PROJECT_NAME}",
                            target: "${WAR_PATH_RELATIVE}.rollback"])
                    deploy(WAR_PATH_FULL + ".rollback/" + WAR_PATH_RELATIVE,
                            TOMCAT_CTX_PATH_PROD, env.USERNAME, env.PASSWORD)
                    currentBuild.result = 'FAILURE'
                    error "Prod deployment rolled back"
                } else {
                    archiveArtifacts artifacts: "${WAR_PATH_RELATIVE}*", fingerprint: true
                }
            }
    }

At the end you get to have something like this:

That pretty much sums up the whole Jenkins pipeline that I’ve been using lately for Spring projects!

Using the program was pretty simple.  I just opened it and told it which zip file (in my case the pptx file which I renamed to a zip file), and then the program did all the work and recovered everything.  It was like magic!

This guide presents how to mimic the system used in professional karaoke establishments at home.  The software this system uses revolves around a Taiwanese program called JetKTV.  Much of the content from this guide was drawn from Chinese language websites discussing the usage of this program (scroll all the way down for References).    There is little literature on this subject in English and so this guide presents basically an English version of the reference sites plus a few added notes.

The program used is in Chinese, so people who are not fluent in Chinese may have a hard time navigating through the software.  Those who are brave enough to continue or have a basic knowledge of Chinese with better English fluency may find it helpful to see English instructions.  The Chinese sites on this subject are also written for older versions, and the setup procedure for those older versions are slightly different.

Contents

• Proposed Setup
• Setting Up JetKTV2010
• Inserting A New Song
• Inserting A New Artist
• Testing
• References

Proposed Setup

The proposed setup of all the hardware (TV’s, amps, computer, etc.) is in the diagram below.

The computer will play the chosen Karaoke videos and transmit the video signal to the TV (via extended display like in a dual monitor set up).  The computer’s audio will go to an amplifier or a mixer, which is then transmitted to a set of speakers.  Microphones are plugged into the amplifier/mixer is well so that the speakers can also play the sound picked up by the microphones.  Depending on the hardware, the cables could be different (some TV’s may not have HD output etc.)The  computer is the source of all the signals transmitted to the other devices and must be set up with the Karaoke software.

Setting up JetKTV2010

The PC will use the following software:

• JetKTV2010 (link)
• SongMgr (optional – not helpful on English language PC’s – more on that topic later)

It is helpful to set up the software using a dual monitor setup.  That way, it is easier to test without having to go and plug the computer to the TV each time.

Unzip the contents of the JetKTV2010 program in a folder and open JetKTV2010.exe.  The GUI buttons are for searching through the database (by looking for the artist, song name, etc.) to find the wanted song. Once a song is selected, it will be added to the list of songs to play just like the software at actual Karaoke establishments. The video will play in full screen on one monitor and the song picker GUI will say on another monitor.  To close the program, click on the top left corner of the GUI (hidden button).

Some of the software features in addition to searching and adding songs:

• Skipping songs
• Fast forwarding, pausing, etc.
• Switching from one audio channel to both audio channels (alternating between vocal on/off)

This program reads from a database that contains the song names, artists, language, etc.   Therefore, it does not come with songs.  Songs must be downloaded separately and added on.  These can come from existing DVD’s or YouTube.  The next section will explain how to populate the database.

Populating the Database

The SongMgr program mentioned above can add/remove contents from the database, but there are problems with it when using it on English language PC’s due to problems in encoding some of the Chinese characters.  Even Microsoft AppLocale fails to rectify the problems.  The solution is to use Microsoft Access to open up the database file directly and make changes.

Adding one song can seem like a lengthy process at the first try, but it will get easier as one becomes more familiar with the system.

Inserting A New Song

To insert a new song, one must navigate to the table where the songs are stored and then add an entry to it.

1. Open Song.mdbin the JetKTV program directory
2. When prompted for a password, input “tmwcmgumbonqd” without quotes
3. Navigate to the table Tbl_Song.  This is the table that records all the song entries.

Below is an explanation of each column:

• Song_ID: numerical identifier for each song (the program lists them as 5 digit numbers starting at 10000)
• Song_Title: song title
• Song_Singer: each singer has a unique number associated with them (see next section)
• Song_Singer (2nd one): the name of the artist in text
• Song_Word: number of characters in the song name
• Song_Type: a number representing a language (Mandarin,Taiwanese,Cantonese,Hakka Chinese,English,Japanese,Movies,Cartoons,Other  in that order starting from 1)
• Song_Volume: song volume, but not sure what units they are in.  Default value is 70.
• Song_Channel: the audio channel that does not have the vocal track. (1-Left, 2-Right, 3-Both)
• Song_FileName: filename of the video without the directory
• Song_Path: the directory to the file (could use absolute pathing only, but unsure of whether relative paths work)
• Song_Create: the time that the song was added in
• Song_Count: the play count of a song
• Song_Juyin: the Zhuyin characters representing the song title
• Song_Stroke: number of strokes in the first character of the song name

Some of the columns can be left out, but that means that it will not be possible to find a particular song using the omitted information.  For example, Song_Juyin can be left out for those who dont use the Zhuyin system, and that feature won’t be used for song searching anyway.

To add a song, fill out the following information at the minimum on one row:

• Song_ID (must be a unique number and should have five digits)
• Song_Title
• Song_Singer
• Song_Volume (70 is the default)
• Song_Channel
• Song_FileName
• Song_Path

For the Song_Singer information, refer to the next section.

Inserting A New Artist

Artist information is stored on a different table called Tbl_Singer

1. Open the table called Tbl_Singer
2. Fill out an entire row to add a new singer (see below for the reference for each information column)

Below is an explanation of each column:

• Singer_ID: unique identifier for each singer (this is the unique ID that is to put inserted in the Song_Singer column in Tbl_Song)
• Singer_Sex: singer gender (0-Female, 1-Male, 2-Group/Band)
• Singer_Name: artist name in text
• Singer_Juyin: the Zhuyin characters representing the artist name
• Singer_Stroke: number of strokes in the first character of the artist’s name

Testing

One a song or two has been entered into the database, one can test it by opening up the JetKTV program and trying to pick a song.  It is working when one screen shows the video playing and another screen showing the JetKTV GUI.

One can also try clicking the button labeled “導唱” to test if the audio channels are set up properly (toggling it turns on and off the vocals).

The next step would be to plug in the computer with all the television components and then trying it again.  Once everything works, the system is ready.

References

All reference sites are in Chinese

[1] 動手打造窮人 KTV <http://www.jetktv.ktvdiy.com/> [Update 2022 October: JetKTV seems to be defunct]

[2] [影音相關] JetKTV 輕鬆打造免費 KTV 點唱機 (進階設定篇) <http://www.soft4fun.net/video-related/%E5%BD%B1%E9%9F%B3%E7%9B%B8%E9%97%9C-jetktv-%E8%BC%95%E9%AC%86%E6%89%93%E9%80%A0%E5%85%8D%E8%B2%BB-ktv-%E9%BB%9E%E5%94%B1%E6%A9%9F-%E9%80%B2%E9%9A%8E%E8%A8%AD%E5%AE%9A%E7%AF%87.htm#doublescr>

[3] 峰網誌 JetKTV-DIY電腦點歌機..軟體篇 <http://www.wretch.cc/blog/Linpy/4853370>

Now that I’m not occupied by episode after episode of TV shows, I can finally catch up on my blog rather than keeping a queue of all the things I want to blog about. In my attempt to go somewhere new every weekend, I chose to go to Freiburg im Breisgau last Saturday.

I woke up early in the morning at around 5 and got ready to leave the house at 6:30.  I probably woke up my landlord’s family downstairs from the running water while I showered, but I unfortunately, I can’t really do anything about that.  I figured leaving an hour early to meet up with my friend at a train station that only takes half an hour to get to should give me quite a bit of flex time. Half an hour seemed like a lot to me, until I saw how long I had to wait for my train.  I waited a whole twenty minutes for it.  The worst part about the wait was that I never charged my iPod.  I stood around and silently waited.  Kind of like watching grass grow.  Although in retrospect, I could have left the house a little later, but at least I wouldn’t miss my train.

After meeting up with my friend, I we patiently waited for the train.  From the corner of my eye, I saw something tiny moving around on the tracks.  An animal?  It was a mouse, or a rat.  I don’t know the difference.  I tried my best to catch a picture of it while it zipped around and underneath the train tracks.  It kind of felt like playing that old N64 game, Pokemon Snap.  If this was Pokemon Snap, I would have gotten a low score for that picture.

The train arrived at around 7:30 and it would stop at Karlsruhe.  On the ride there, my friend and I just talked while looking looking out the window.  After we arrived in Karlsruhe, we had to wait a half hour for our connecting train.  The moment I looked out onto the station platforms after stepping out of the train, the sight instantly reminded me of the City 17 train station in Half-Life 2 (everything reminds me of games doesn’t it?)

While walking around the train station trying to kill time, we found a place that sold 5 Berliners for 2 euro.  Although called a Berliner, it clearly has nothing to do with someone from Berlin.  Despite the misleading name, Berliners are a pastry that is like a European version of a doughnut (never ever call it that).  It’s got sugar on top and jam filling on the inside.

After boarding the connecting train, I talked to my friend about how long train rides were.  I don’t know if it’s because English attracts attention, but a random stranger sitting across from us started talking saying how it is perfectly normal for train rides to take a long time.  Since he was German and probably didn’t get a lot of practice with English, he spoke to us with a heavy accent.  He started talking about how sometimes people will commit suicide by train, which causes trains to stop in the middle of nowhere and everyone on board is forbidden to get out.  The weirdest part of it was that train suicides were seasonal.  According to him, more people commit suicide by train in the summer.  After speaking to him a little more, I found that even some Germans read manga.  I didn’t know that manga was that popular.  I even saw Dragon Ball manga translated in German in a bookstore.

Two train transfers and three and a half hours later, we arrived in Freiburg im Breisgau.  According to Wikipedia, it’s the warmest place in Germany.  As usual, the first thing we do upon arriving at a new place is to look for a map to find the tourist information center to get a map.  I had already looked up what sights to see the night before, so all I needed was a map to tell me how to get there.  Even without the map, we could both see the tower of the Freiburger Munster standing tall above every building in its vicinity.  All we needed to do was head in that direction.

Thus far, the Freiburger Munster is the most amazing work of church architecture I have seen, inside and outside (The only place that I think could be better is the Sistine Chapel, but I haven’t been there yet). I would describe it, but I’m terrible at descriptive writing.  Good thing is that a picture is worth a thousand words!

After walking around inside for a little bit, I came across a set of statues in front of a window set up in a way that a group of statues were all looking at the body of Jesus Christ.  When I was looking at these statues, it happened to be around noon, and the sunlight shined through the window and I could see the glare.  It seems as if the scene was designed this way: to have the Light of God shine down.

Walking around some more, I came across a statue that looked suspiciously like Chancellor Palpatine of Star Wars (there’s my nerdiness popping up again).  Who knows, maybe George Lucas got inspiration from this and found an actor that looks like the guy in this statue.

On our way out, we learned that we could visit the church tower.  Despite the popularity of the church tower, there was no elevator (makes sense, since the church is quite old) and had a set of the narrowest spiral staircases ever seen.  Two people could barely pass through each other.  One wrong step would cause one to tumble around and around down to the bottom and bring other people along in a human snowball.  Luckily for me, that did not happen, but it sure was tiring walking up all those steps.  At the top, we had a semi decent view of the town.  I say semi-decent because of the maintenance that was going on.  For three weeks in a row, every main attraction in each city I went to was under maintenance.  There was the Heidelberg Castle, Bebenhausen Abbey, and now this.  In addition to being able to look around town, I also saw the mechanism for the church bells.

On our way out of the cathedral, we smelled a strong scent of bratwurst and because of that, I decided that’s what i was going to have for lunch.  I guess my lunch was like a European hotdog (I have no idea what they call it).  They took a bread roll, cut it in half and put bratwurst and onions inside.  Like everyone else, I added ketchup and mustard.  I don’t think I can go back to eating regular North American sausages again after eating bratwurst.

A unique feature of the city is that water canals run through the town.  Upon first sight, one would think they were some sort of sewage system.  Known as Bachle, they were once used to provide water for firefighting and feed farm animals.  It is said that whoever steps in one must marry a Freiburger.  Around the town are a set of gates.  One of them, the Martinstor, has now been desecrated by McDonald’s.  How they managed to put their brand on such a historic structure is beyond me.

In the city is also a trail that leads up to the mountain, Schlossberg, for a view of the town.  I believe there was also public transportation that took the lazy folks up there.  As if the stairs at the church bell tower wasn’t even enough, we were now faced with yet another seemingly endless set of stairs.  We’d look up the mountain seeing how much further we needed to go every now and then.  Once we reached the top, we realized that it wasn’t really the top.  There was yet another set of staircases leading up.  It’s just that we couldn’t see it before we got all the way up.

On our way home, I came across a vandalized billboard on the side of the street.  The vandals had drawn a Hitler mustache on the peoples faces.  I found it kind of amusing since that doesn’t really happen in North America.  Not Hitler mustaches, anyway.

 On the train ride home yet another random stranger talked to us.  Except that the stranger this time wasn’t German.  He was an American who had just arrived in Stuttgart to work.  Like us, he spent his weekend traveling.  My friend and I were talking about gun control at the time when the guy started talking to us.  Apparently in his state of Virginia, one has the right to shoot someone in self defense to take someone’s life when their own is in danger.  He even told us a story about how someone he knew shot at a guy sneaking around suspiciously in their yard and how a friend of his has a license to carry a concealed weapon around.  It felt kind of nice to hear North American English again.

At the train station, while waiting for a connecting train, a third random stranger started talking to me.  Three in one day.  That has to be a record.  This time it wasn’t because I was speaking English.  This time it was because I’m Chinese.  A Turkish looking fellow looked at me as he walked by pushing a cart of luggage.  He looked at me and said “ni hao”, which is hello in Mandarin.  I was so surprised that I didn’t know how to reply, all I did was smile back in appreciation.  I guess Chinese people are a rare sight around here. 

For some reason, on the train ride home, the train stopped suddenly in the middle of nowhere.  I was reminded by the German fellow I talked to earlier about train suicides and I hoped that it didn’t happen.  Fortunately, it wasn’t anything serious and the train continued on its way after a few minutes.  After a nice day of sightseeing and hiking around, I got home and rested for the next day, which I spent uploading photos, blogging, and random household chores.  Sounds like quite the opposite in excitement compared to the day before.

My photo album for Freiburg im Breisgau

Generally, communication with serial ports involves these steps (in no particular order):

• Searching for serial ports
• Connecting to the serial port
• Starting the input output streams
• Adding an event listener to listen for incoming data
• Disconnecting from the serial port
• Sending Data
• Receiving Data

I wrote an example program that includes all of those steps in it and are each in their own separate method within the class, but first I will go through my hardware set up.

Hardware Setup

My current hardware setup is as follows:

• PC connected to an XBee
• Arduino connected to an XBee

User input is given from the PC through the a Java GUI that contains code for serial communication, which is the code presented here.

The Arduino is responsible for reading this data.  This set up is pretty much using my computer as a remote control for whatever device is on the Arduino end.  It could be a motor control, on-off switch, etc.

Existing Code

The purpose of this post is to discuss serial programming in Java, and not GUI’s.  However, I did create a GUI for testing purposes.  See the Code Downloads section for the actual files.

Above is the picture of the GUI complete with the buttons that I use to interact with the program.  I also added key bindings which I can use to control the throttle.

When the program is first started, none of the GUI elements will work except for the combo box and the connect button.  Once a successful connection is made the controls are enabled.  This is done through the use of the setConnected(true) and the toggleControls() methods shown in the example code that follows.

Imports

The imports i used for this program were as follows:

import gnu.io.*;
import java.awt.Color;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.Enumeration;
import java.util.HashMap;
import java.util.TooManyListenersException;

Depending on the Java IDE it might already know to tell you to use these imports except for the first one.  That first import is specific to RXTX, and all its library methods/classes are in there.

Class Declaration

The code here reads:

public class Communicator implements SerialPortEventListener

I named my class Communicator, but the name is really up to the programmer.  The name pretty much reflects its intended use.

The class should also implement the SerialPortEventListener class.  This is a class in RXTX and is required in order to receive incoming data.

On some IDE’s this may generate a public void method called serialEvent().  This method will be defined later.

Class Variables and Constants

Below are the variables and constants that I defined in my class.  What the variables are for is in the comments but a more detailed explanation will follow.

    //passed from main GUI
    GUI window = null;

    //for containing the ports that will be found
    private Enumeration ports = null;
    //map the port names to CommPortIdentifiers
    private HashMap portMap = new HashMap();

    //this is the object that contains the opened port
    private CommPortIdentifier selectedPortIdentifier = null;

I could have easily put the variable definitions in the constructor but it wouldn’t change anything.

The GUI object is another class that I wrote separate from this one that contains all the GUI elements.  The GUI class extends javax.swing.JFrame.

The HashMap is for mapping each of the ports’ names to the actual object. What that means is that I can associate (put() method) the name of a serial port, say a string that says COM1, to an object in the code.  Later, I can access the name COM1 from the HashMap by using the get() method and it will return the object that it was associated with previously.

The CommPortIdentifiers object is needed to gather the list of ports that are available for connection. by using its getPortIdentifiers() method.

The SerialPort object is for storing the data for the port once a successful connection is made.

The InputStream and OutputStream is the object that is required for sending and receiving data.

The Boolean variable bConnected is just a flag that I use for enabling and disabling elements on the GUI.

The constant TIMEOUT is a number required when opening the port so that it knows how long to try for before stopping.

The constants for the ASCII values are some values that I use to send through the output stream that act as delimiters for data.

The string logText is basically what the comment says.  When stuff happens in the program, the program stores a string in this variable and it will be appended to a text area in the GUI.

Searching for Available Serial Ports

The method below is for searching for available serial ports on the computer.  Code adapted from Discovering Available Comm Ports from the Reference Material.

    //search for all the serial ports
    //pre style="font-size: 11px;": none
    //post: adds all the found ports to a combo box on the GUI
    void searchForPorts()
    {
        ports = CommPortIdentifier.getPortIdentifiers();

        <span style="color: blue;">while (ports.hasMoreElements())
        {
            CommPortIdentifier curPort = (CommPortIdentifier)ports.nextElement();

            //get only serial ports
            <span style="color: blue;">if (curPort.getPortType() == CommPortIdentifier.PORT_SERIAL)
            {
                window.cboxPorts.addItem(curPort.getName());
                portMap.put(curPort.getName(), curPort);
            }
        }
    }

The method getPortIdentifiers() returns an Enumeration of all the comm ports on the computer.  The code can iterate through each element inside the Enumeration and determine whether or not it is a serial port.  The method getPortType() can identify what kind of port it is.  If it is a serial port, then the code will add its name to a combo box in the GUI (so that users can pick what port to connect to).  The serial port that is found should also be mapped to the HashMap so we can identify the object later.  This is helpful because the names listed in the combo box are the actual names of the object (COM1, COM2, etc), and so we can use these names to identify the actual object they are tied to.

Connecting to the Serial Port

The method below is for connecting to the serial port once they have been found (see previous section).  See How to Open A Serial Port in the Reference Material for more information.

    //connect to the selected port in the combo box
    //ports are already found by using the searchForPorts
    //method
    //post: the connected comm port is stored in commPort, otherwise,
    //an exception is generated
    public void connect()
    {
        String selectedPort = (String)window.cboxPorts.getSelectedItem();
        selectedPortIdentifier = (CommPortIdentifier)portMap.get(selectedPort);

        CommPort commPort = null;

        try
        {
            //the method below returns an object of type CommPort
            commPort = selectedPortIdentifier.open("TigerControlPanel", TIMEOUT);
            //the CommPort object can be casted to a SerialPort object
            serialPort = (SerialPort)commPort;

            //for controlling GUI elements
            setConnected(true);

            //logging
            logText = selectedPort + " opened successfully.";
            window.txtLog.setForeground(Color.black);
            window.txtLog.append(logText + "n");

            //CODE ON SETTING BAUD RATE ETC OMITTED
            //XBEE PAIR ASSUMED TO HAVE SAME SETTINGS ALREADY

            //enables the controls on the GUI if a successful connection is made
            window.keybindingController.toggleControls();
        }
        catch (PortInUseException e)
        {
            logText = selectedPort + " is in use. (" + e.toString() + ")";

            window.txtLog.setForeground(Color.RED);
            window.txtLog.append(logText + "n");
        }
        catch (Exception e)
        {
            logText = "Failed to open " + selectedPort + "(" + e.toString() + ")";
            window.txtLog.append(logText + "n");
            window.txtLog.setForeground(Color.RED);
        }
    }

Using the HashMap we can retrieve the CommPortIdentifier object from the string that was mapped earlier.  This is achieved through the HashMap’s get() method.  The object must also be casted as a CommPortIdentifier because the get() method has a return type of Object.

The setConnected method just changes a boolean flag so that the program can store whether or not it is connected to a serial port or not.

The CommPort must also be initialized because the port object will be stored here once a successful connection is made.

The main method of interest here is the open() method.  This instructs the program to open the port, and this method will return the object for the opened port, which I store in in the previously initialized CommPort object.  I then cast this object as a SerialPort and store it as well.  This is helpful for accessing the methods and variables specific to the SerialPort class.

It should also be noted that the open() method requires the use of a try-catch block.  So applying that, I catch two different exceptions.  The PortInUseException is what the name says.  If the port is in use, then this exception is thrown.  The next catch block is just for the generic exceptions that occur.  I never came across that during testing, nor do I know how to replicate that.

I neglected to include any code for setting the baud rate and other settings on the XBee’s (see Hardware Configuration), because I already set those parameters previously using X-CTU (more on setting up XBee’s here).

Initializing the Input and Output Streams

This method is pretty short and is pretty straightforward to read.

    //open the input and output streams
    //pre style="font-size: 11px;": an open port
    //post: initialized input and output streams for use to communicate data
    public boolean initIOStream()
    {
        //return value for whether opening the streams is successful or not
        boolean successful = false;

        try {
            //
            input = serialPort.getInputStream();
            output = serialPort.getOutputStream();
            writeData(0, 0);

            successful = true;
            return successful;
        }
        catch (IOException e) {
            logText = "I/O Streams failed to open. (" + e.toString() + ")";
            window.txtLog.setForeground(Color.red);
            window.txtLog.append(logText + "n");
            return successful;
        }
    }

The streams are initialized by returning the input and output streams of the open serial port.  In order for the serial port object to not be null, it must store the object for the open serial port.

The getInputStream() and getOutputStream() methods both require a try-catch block.  The important exception to catch here is the IOException to signify whether the streams failed to open or not.  For more information see How to Open A Serial Port in the Reference Material.

I also call a method called writeData(0, 0).  This is the method that encapsulates the code required to write serial data.  More on that later.  Right now it is just used to set variables on the microcontroller side to zero.

Setting Up Event Listeners to Read Data

Once the port is open, the serial port must know whenever there is data to be read.  This approach is event driven rather than by polling.  When the event is hit, a special block of code will run.  This is advantageous to polling because polling requires constantly asking if data is available.  The code for the event driven approach is below.  See Event Based Two Way Communication for more information.

    //starts the event listener that knows whenever data is available to be read
    //pre style="font-size: 11px;": an open serial port
    //post: an event listener for the serial port that knows when data is received
    public void initListener()
    {
        try
        {
            serialPort.addEventListener(this);
            serialPort.notifyOnDataAvailable(true);
        }
        catch (TooManyListenersException e)
        {
            logText = "Too many listeners. (" + e.toString() + ")";
            window.txtLog.setForeground(Color.red);
            window.txtLog.append(logText + "n");
        }
    }

The code here is pretty much the whole reason why this class implements SerialPortEventListener.  The parameter for adding the event listener is just the object itself.  The base class has a method called serialEvent(event) that should be overridden before the event code will work.  Overriding that method defines what happens when the event is hit.

The method addEventListener(this) is the event that is always checking for SerialEvents.  It isn’t really important to know what the events actually are, just that the one we’re interested in is the one that tells us whenever data is received.  Adding the event listener is complemented by the method notifyOnDataAvailable(true), which definitely helps us achieve what I mentioned previously.

This code requires a try-catch box.  The exception here is that there may be too many event listeners.  I only use one in the code, so this exception should never be hit.

Disconnecting from the Serial Port

Once all the communication is completed, the serial port must be disconnected.  In some instances, some ports stay stuck open, which isn’t exactly a good thing.

    //disconnect the serial port
    //pre style="font-size: 11px;": an open serial port
    //post: closed serial port
    public void disconnect()
    {
        //close the serial port
        try
        {
            writeData(0, 0);

            serialPort.removeEventListener();
            serialPort.close();
            input.close();
            output.close();
            setConnected(false);
            window.keybindingController.toggleControls();

            logText = "Disconnected.";
            window.txtLog.setForeground(Color.red);
            window.txtLog.append(logText + "n");
        }
        catch (Exception e)
        {
            logText = "Failed to close " + serialPort.getName()
                              + "(" + e.toString() + ")";
            window.txtLog.setForeground(Color.red);
            window.txtLog.append(logText + "n");
        }
    }

The code here requires a try-catch block so there it is.  The exception to catch here is pretty generic.

Before closing the port, I reset the data on the microcontroller.  That step is optional depending on the application.  For example, if the value sent to the microcontroller is controlling the speed of a motor, I’d want the motor to turn off if I turn off the remote control.

The event listener should be removed as it is no longer needed.

The method to close the port is the close() method.

The input and output streams should also be closed via the same method as above.

See How to Close A Serial Port in the Reference section for more information.

Reading Data – The serialEvent Method

This is a follow-up to the section on preparing to Read Data.  It has information on how to process the data that the program reads.

    //what happens when data is received
    //pre style="font-size: 11px;": serial event is triggered
    //post: processing on the data it reads
    public void serialEvent(SerialPortEvent evt) {
        if (evt.getEventType() == SerialPortEvent.DATA_AVAILABLE)
        {
            try
            {
                byte singleData = (byte)input.read();

                if (singleData != NEW_LINE_ASCII)
                {
                    logText = new String(new byte[] {singleData});
                    window.txtLog.append(logText);
                }
                else
                {
                    window.txtLog.append("n");
                }
            }
            catch (Exception e)
            {
                logText = "Failed to read data. (" + e.toString() + ")";
                window.txtLog.setForeground(Color.red);
                window.txtLog.append(logText + "n");
            }
        }
    }

Since we only want to read data if it exists, we test the condition in the if statement above.  This could be redundant because we wouldn’t be in this method if the event never got triggered.

Reading the data requires a try-catch block.  The read() method returns an integer, but the value in it is actually a byte value so this is casted to a byte, in which I store in a variable called singleData.  When I was testing this code before, I noticed that the data being read would always have random new line characters in it, and I never knew why this happened.  I never wrote any new line characters.  Since I don’t want these, I add an if condition saying that if it encounters that, don’t display that data on the screen.

Java also has a nice way of converting bytes to a string.  A byte array can be used as a parameter when initializing a string, which is what I’ve done when I assign a value to logText.

The exception here is just the usual generic one.

Writing Data

Here is the method for writing data.  In my application, I am writing two integers sequentially to my microcontroller.  Data that is sent to the MCU can be used for such things such as controlling motor speeds, which is what I am trying to do here.  I hope to use the data sent do control the PWM duty cycle of the motor for speed control.

    //method that can be called to send data
    //pre style="font-size: 11px;": open serial port
    //post: data sent to the other device
    public void writeData(int leftThrottle, int rightThrottle)
    {
        try
        {
            output.write(leftThrottle);
            output.flush();
            //this is a delimiter for the data
            output.write(DASH_ASCII);
            output.flush();

            output.write(rightThrottle);
            output.flush();
            //will be read as a byte so it is a space key
            output.write(SPACE_ASCII);
            output.flush();
        }
        catch (Exception e)
        {
            logText = "Failed to write data. (" + e.toString() + ")";
            window.txtLog.setForeground(Color.red);
            window.txtLog.append(logText + "n");
        }
    }

The write() method here requires a try-catch block just like many of the other methods used for serial communication.  Using the output stream, I call that method to write an integer value.  I also write a dash and a space to separate the actual data being read.  See the ASCII Table for the values of what these characters should be.  This helps me differentiate the sets of data that is sent back and forth.  The dash separates the two integers being sent and the space separates the entire set.  On the Arduino end, four called to read() can separate the data without mixing things up.  Example of that later.

Putting All the Java Code Together

Once all these methods are setup, they need to be called somewhere in the program so we can put them to use.  When the program starts, the code for searching for serial ports will run so that it can populate the combo box on the GUI.  The GUI buttons also need to be disabled to reflect the fact they should be disabled when there is no connection to a port.  When the connect button is pressed, the input and output streams are started and the event listener is added.  The code for that is shown below.

        private void btnConnectActionPerformed(java.awt.event.ActionEvent evt) {
            communicator.connect();
            if (communicator.getConnected() == true)
            {
                if (communicator.initIOStream() == true)
                {
                    communicator.initListener();
                }
            }
        }

The if statement is needed such that the code will not run if a successful connection was not made.  This is the precondition for the initIOStream() and the initLIstener() methods.

When the user decides to disconnect from the serial port, the user only needs to call the disconnect() method when the disconnect button is pressed.

The up/down arrows on my GUI are set to write data to the serial port when they are pressed.  When data is written to the Arduino, the MCU will send the data back to the Java program, which will signal the event listener to display that data back to the screen.

Arduino Code

The Arduino code is pretty straight forward.  There are just a few calls to the read() method.

Update 6 May 2012: the syntax for the Arduino code has updated since the writing of this article.  Apparently, the lines

Serial.print(separator, BYTE);
Serial.print(space, BYTE);

are no longer valid and have since been replaced by the following:

Serial.write(byte(separator));
Serial.write(byte(space));

The code below hasn’t been edited with this change, but basically the code required for writing a byte value through serial communication has changed.

// this is where we will put our data
int left = 0;
int right = 0;
byte space = 0;
byte separator = 0;

void setup(){
  // Start up our serial port, we configured our XBEE devices for 38400 bps. 
  Serial.begin(9200);
}

void loop(){
  // handle serial data, if any
  if (Serial.available() >= 4){
    left = Serial.read();
    separator = Serial.read();
    right = Serial.read();
    space = Serial.read();
    Serial.flush();

    Serial.print(left);
    Serial.print(separator, BYTE);
    Serial.print(right);
    Serial.print(space, BYTE);
    Serial.print("n");
  }
}

I first declare four variables to reflect the fact that I’m writing four different variables to the serial port.

In the loop method, I added a condition which will check whether there are four pieces of data available before reading them.  This again reflects the fact I’m writing four values.

The four variables initially declared store the values in the order that they are written, and then are just printed to the screen.

The print() method is able to convert the byte value to an actual character by adding a second parameter called BYTE.  The left and right variables don’t need it because the values written were integers to begin with, however, the dash and space characters were written as ASCII values.

For more information about Arduino and Java, and Arduino’s Serial library, please refer to those in the Reference Section.

Code Downloads

Here are the code downloads for the GUI, key bindings and the serial communication.  WordPress doesn’t allow uploads of zip or java files so I uploaded it all to Megaupload.

Link to download: http://www.mediafire.com/?z2l26ncypmzn20z

Other Examples

There are also other sites I looked at which had example code for serial port communication in Java.  The sites are Programming Serial and Parallel Ports and Serial Port Access Using RXTX in Java, which are both in the Reference section.

Reference Material

Below are a bunch of links to reference sites that I used to find some of the information written here.  I mostly referred to bits and pieces of each article to understand the serial code and to come up with the example I present here.  The list is in the order that I referenced them.

Discovering Available Comm Ports

http://rxtx.qbang.org/wiki/index.php/Discovering_available_comm_ports

The code on this page is pretty specific to the title of this heading, and the code is pretty easy to follow.

How to Open A Serial Port

http://embeddedfreak.wordpress.com/2008/08/08/how-to-open-serial-port-using-rxtx/

This page provides a very concise and detailed explanation on what each line of code does in order to get a serial port open.  Definitely work a look if you’re trying to understand the code.

Event Based Two Way Communication

http://rxtx.qbang.org/wiki/index.php/Event_Based_Two_Way_Communication

This page has example code on how to connect to a serial port and how to interact with it.  The code here uses events, rather than polling, to send data back and forth, which means that whenever data is received, the event code is triggered.

How to Close A Serial Port

http://embeddedfreak.wordpress.com/2008/08/08/how-to-close-serial-port-in-rxtx/

This article is written by the same author who wrote the article on how to open serial ports.  Good example code here.

ASCII Table

http://www.asciitable.com/

Having the ASCII Table is quite handy for serial data because data being sent and written are bytes, so being able to know what byte values correspond to what character really helps.

Arduino and Java

http://www.arduino.cc/playground/Interfacing/Java

This article discusses how to use the serial port communication with Java and Arduino, which is exactly what I am after.  It has example code on pretty much the entire process of serial port communication, but it may be too much to read since there is little explanation about the code.

Arduino Serial Class

http://arduino.cc/en/Reference/Serial

A good reference for Arduino’s Serial class methods.  Also has example code to look at.

Programming Serial and Parallel Ports

This article provides a brief introduction to programming serial ports and has information on the steps required to talk to the serial port.  However, the code examples in there may be hard to follow for someone new to serial programming.

Serial Port Access Using RXTX in Java

http://gomultidomain.blogspot.com/2008/06/serial-port-access-using-rxtx-in-java.html

This page also has complete code for serial communication in Java, but what I was looking for here was how to use the write method to send serial data from Java.

For more information about the program, see the original post about it.

Requires Java to be installed.  Link for that here.

SourceForge Page: http://sourceforge.net/projects/aa40battlecalc/

Download: http://sourceforge.net/projects/aa40battlecalc/files/Battle%20Calculator%20Binary/v1.0/BattleCalculator-v1.0.jar/download

Source Code: http://sourceforge.net/projects/aa40battlecalc/files/Battle%20Calculator%20Source/v1.0/src-v1.0.zip/download