How to access FloreantPOS w/ a PC, Phone, or Tablet

By fattire (Twitter:@fat__tire)

The goal:  Access FloreantPOS (aka "Floreant", a neat-o point-of-sale open source package) on a tablet, phone, or PC.... without having to install any complex or proprietary software.  And using only open-source.

Here's a link to my demo:  video

For this tutorial I'm going to assume you're using Ubuntu Linux.  In fact, I wrote a script that will automatically install Floreant for you on Ubuntu... and keep it current as the code is updated.

I've also mirrored source code from Sourceforge.net's subversion repository on github here, although by the time you read this it is likely not up to date, but still might be useful for quick searches or whatever.

My script (assuming it still works) puts the latest build of Floreant on your Desktop in a folder called active_floreantpos, so that's the name I'm going to use in this example.

 

STEP ONE:  INSTALL FLOREANTPOS WITH MY SCRIPT ABOVE

Note:  You must use a 64-bit version of Ubuntu.

So I'm going to assume you've run the script and you've got Floreant ready to go. Now, how to transform it into something that can be accessed by any PC, Mac, tablet, or phone?

 

STEP TWO:  SET UP FLOREANTPOS AS A WEB APP

The secret sauce is Webswing.  It's an open source, HTML5-only (no non-web technologies) web server that serves Java swing apps directly to the web.

Since FloreantPOS is a Java app that uses Swing for its UI, there's not much to it than that!

The goal:  Make FlorantPOS a "web app" that can be accessed via HTTP on any device!  That is, ANY phone, tablet, PC, or whatever-- with a modern web-browser should be able to use this web app.

All they need is the URL and a username/password.  These web apps versions are able to run together simultaneously with traditional FloreantPOS devices.  For lightweight/inexpensive touch devices, it just a lot easier to point a browser at a server rather than installing a full installation of FloreantPOS, which may not be possible.

Webswing is pretty great-- it integrates printing, clipboard, administrator "mirroring", SSL, etc.

To set up Webswing requires minimal computing skills.  No special programming is required.  Just basic installation and file-editing skills.

So, here's what you need to do...

NOTE:  For this example, I have a username of "fattire" so my installation of floreant is in /home/fattire/Desktop/active_floreantpos-- in the instructions below, you should change fattire to whatever your Ubuntu username is.

  1. There are a few dependencies you want to make sure you have installed.  Some of these will already have been installed when you ran my floreant_updater.sh script, but just be sure you have the rest by typing this command (this requires root permissions):

    sudo apt-get install     xvfb libxext6 libxi6 libxrender1

    (I think this is all the packages.  Hopefully I didn't miss any but will update these instructions if I did.)
     
  2. Download a recent build of Webswing, and unzip it to your Desktop to a folder you should call webview.  (Refer to these docs if you need help for the next few sections.)
     
  3. Inside, there's a file called start.sh.  I had to make a few modifications to get this to run "headlessly":

    Add this to the top:

    export DISPLAY=":0.0"

    # Start Xvfb
    if [ -f /usr/X11R6/bin/Xvfb ]; then
    /usr/X11R6/bin/Xvfb :1 -screen 0 1024x768x16
    fi

    Next, change the HOME variable to look like this.  Change fattire below to your username.

    export HOME=/home/fattire/Desktop/webswing

    Finally, comment out with # (or remove) the following lines.  They didn't seem to work for me and everything worked still worked without it.  They start with:

    if [ ! -z `command -v ldconfig` ]; then

    and end with

    fi

    # See how we were called.

  4. You will also need to make sure that start.sh has the privileges to be run as a user.  To do this, type:

    chmod +x start.sh

    from the ~/Desktop/webswing  directory.

  5. Now that the start.sh script is ready, let's add floreant to the list of apps via webswing's Web Interface.  To do this, simply type:

    ./start.sh start

    Now from any computer on your local network, go to a web browser and visit your Ubuntu device's IP address on port 8080 (the default).  For example, if your Ubuntu machine is at 192.168.1.100, you would type http://192.168.1.100:8080 into your browser.

    Hopefully you will be greeted with a login.  The default username is admin and password is pwd.  You should change this at some future point.

    If you have problems logging in, again you can refer to here.  If start.sh crashes, check the script-- you may have commented out the wrong lines (?)  Or perhaps there is a dependency missing that you still need to install.  Review the documentation for clues.

    Assuming you were able to log in, you can now follow the instructions on Webswing's Quick Start Guide for how to add FloreantPOS as a web app.

    To help you with this, here are the relevant settings that were added to my webswing.config file after I added floreant.  You can use these values, but don't forget to change fattire to your own user name.

    (A BUNCH OF STUFF... THEN..)
      }, {
        "name" : "Floreant",
        "icon" : "/home/fattire/Desktop/active_floreantpos/config/logo.png",
        "vmArgs" : "",
        "classPathEntries" : [ "/home/fattire/Desktop/active_floreantpos/floreantpos.jar", "/home/fattire/Desktop/active_floreantpos/lib/*jar" ],
        "homeDir" : "/home/fattire/Desktop/active_floreantpos",
        "theme" : "Murrine",
        "maxClients" : 20,
        "antiAliasText" : true,
        "swingSessionTimeout" : 300,
        "authorization" : false,
        "isolatedFs" : false,
        "debug" : false,
        "authentication" : false,
        "directdraw" : false,
        "allowDelete" : true,
        "allowDownload" : true,
        "allowUpload" : true,
        "allowJsLink" : true,
        "mainClass" : "com.floreantpos.main.Main",
        "args" : ""
      } ],
    (MORE STUFF)

     Again, I am using the default installation directory ~/Desktop/active_floreantpos which is created by my script.
     

  6. When everything is properly set up, you should be able to log in via http://192.168.1.100:8080 and FloreantPOS will appear as an option which you can then run directly from the browser.
     

  7. Once you've got it all ready-- you can customize the settings-- add SSL for secure browser connections, create a dedicated page (See Webswing's README.txt file) to automatically start with FloreantPOS rather than go through the app menu, adjust the screen size in start.sh (that is, /usr/X11R6/bin/Xvfb :1 -screen 0 1024x768x16) to better reflect the size of the tablet or virtual machine you want to use, etc.
     

STEP THREE:  USE A DEDICATED APP TO ACCESS FLOREANT FROM ANDROID (OR iOS OR A PC OR WHATEVER)

While you can now simply access http://192.168.1.100:8080 from a browser on your phone to access FloreantPOS, you will run into a few issues:

My solution: an Android app to:

  1. It presents a full-screen WebView and loads it with the Floreant Web App.  Doesn't include a URL bar, menu bar, or any other "bells and whistles"  Just starts and immediately presents the interface.
  2. Can be used to automatically scale to to "full screen" so you get the whole page scaled to the dimensions of the tablet/phone.
  3. You can change the viewport preferences and URL-related stuff in the settings

Couldn't be more basic.

Update: Per request, I've posted my app source code (released under the GPL). It's called HipPOS and you can grab source code here. I did make a lot of the UI changes that I figured would be useful.

CAVEATS: