Editing BitWacker PIC and Other Microcontroller to Java Communications

=== Summary  ===

*Name: BitWacker Java Communications
*Purpose: A family of applications for communication with BitWacker or other serial connected applications.
*Status: some applications running, others in various states including ready for testing.  Downloads available.
*Technology: Java -- should run on many platforms, Windows 98 through Vista, Mac, Linux.
*Author: [[russ_hensel]] ( where you can find an email address to reach me )
*License: not fully determined, but open source and object code.


This is one of a series of articles on Microcontroller Serial Communications, rooted at this site here:  [[Microcontroller Serial Communications Articles]]

== Status ==



June 08 2008
*RS232Probe: ready for test, see download below.
*BitWacker: ready for test, see download below.


== Introduction, Download, and Request for Testers/Users of the Software ==

Note: This code should be useful not only to [[USB Bit Whacker]] users, but to any MicroController users who want RS232 or USB ( virtual RS232 ) communications to their microcontroller.

A new interesting device ( basically an advanced development board with firmware ) is the BitWacker:
[http://www.greta.dhs.org/UBW/ USB Bit Whacker]
From the site:  ''The UBW board is a small board that contains a Microchip PIC USB-capable microcontroller, headers to bring out all of the PICs signal lines (to a breadboard for example), only costs about $15-$20 to build and is powered from the USB connection.''  

There seem to be a fair number of additional projects based on this device.  Google "BitWhacker" or "UBW".

The developer has supported the PC end of the communications with a program in Liberty Basic.  The project based here is to provide communications to the Bitwhacker and similiar microcontrollers using a family of JAVA applications.  The applications range from fairly general ones suitable for many microcontrollers to very specialized ones for
particular applications of the BitWhacker.  The more specialized applications actually turn the BitWacker/PC into entirely new applications.  See below.

We now have some beta level code ( June 04 08 ) and we are looking for testers.  The tester should:

* Have a BitWhacker and cables to connect to a PC. ( or other microcontroller with serial comm ability rs232 or usb )
* PC running XP or Win 98 ( other versions may work, but you would be more on your own )
* Some experience with JAVA or other language installs ( if you have a lot that is ok but please do not bash us on code quality for awhile ).


The contents of this page should change fairly frequently for the next few weeks, check back if you are just lurking.

Download [http://home.comcast.net/~russ_hensel/OC/MCSerialComm/bin08-06-04/MCSerialCommDist.zip] Contains RS232Probe and BitWacker Applications.  See [[RS232/USB Probe]] for the installation. 

For more information contact [[russ_hensel]]


== Application Variations ==

=== First Application: The [[RS232/USB Probe]] === 

Much like a terminal emulator but with some special features to test embedded devices.  Store multiple commands and issue with press of button.  Implement various handshaking/flow control.  [[RS232/USB Probe]]  This is the basic application that works with the widest range of microcontrollers.  Install and try it first, if you cannot get it to run you will not be able to get the others to run either.  Installing it does most of the install for all the other applications.

=== Second Application: [[BitWacker Command GUI]] === 

Fairly direct implementation of the BitWacker Command API with one parameter controlled button for each ( most? ) command.  Ex: button for PO" ( "Pin Output" ) will have GUI edit controls for entry of Port, Pin, and State. GUI will also support display of BitWacker response as appropriate.  [[BitWacker Command GUI]]

=== Third Application: [[Graphical Data Logger]] ===

For low speed logging, up to say 1 measurement per second.  Nice graphical output ( using PtPlot )

=== Fourth Application: Low Speed Logic Analizer ===

For low speed logic ( want to track my various heating zones ), say down to 1 measurement per hour.  Nice graphical output ( using PtPlot )  Really an adaptation of the Graphical Data Logger but with provisions to prevent the various graphs from overlapping thus obsucring the graphs.

=== Fifth Application: [[Smart Battery Charger with Graphical Data Logger]] ===

Basically a peak detecting charger for NiCad and Nickle metal hydride batteries.  After fast charge drops back to trickle charging.  Charging logic is all on the PC, so can be very smart with a nice GUI.  Will require an add-on board with a microcontroller ( BitWacker would be fine ) and a few op amps and transistors.  I have an old version of this which I am using as a starting place for the project.

=== Your Application: Whatever you want ===

Use the source code of the above applications to build your own to control whatever you want.  [[Making Your Own Microcontroller Serial Communications Application]]

== More Information: ==

'''The following generally applies to all the applications.'''

This project will be open source under one of the usual lisences, if there is a push for it I will move to Source Forge at some point.

Here is a feature ( and wish ) list ( add your input on the discussion page and note that once released you can make additions ) and some additional info:


* Java ( which version? was jdk1.6.0_03 seems not to be compatible with windows 98, do we care? Have reverted to 1.4 something or other ) Current testing on XP only.

* Communication using java comm: RS232 emulation over USB.  Not ideal, hard to install, some platform differences, like the naming of comm ports.  In the Java world there does not seem to be a better alternative.

* Support both RS232 and USB  RS232 emulation so framework will work with older RS232 devices.

* Software structured in layers, one layer for  RS232, higher layer models the BitWacker.

* Use Model View Controller pattern.

* Make GUI based, but provide Java Programmers with an API for custom applications, document for reuse.

* Control parameters of application through a property ( text ) file.  Perhaps later add parameter control to GUI.  This file is where port properties are specified.  You can also specify parameters that cause the application to search through all available ports looking for the desired device.

* Include program debugging through log4j framework ( it has be suggested that a newer framework might be used, this may happen but not for the first pass ).

* In the lower level API get away from text for arguments ( Port “A” “B”... ) and move to numerical arguments, this makes abstraction of the hardware easier and allows for easier looping through ports and bits.  Also provide a fairly easy way to think about the hardware in the more traditional text model.

* Include provisions for scaling of analog input data to floating point.

* Include a text file for logging ( some ) operations.

* All code specific to BitWacker will be in a small set of classes ( or 1 class ) so that applications can be switched to other devices ( or versions of BitWacker without much application change.

* Some sort of macro record and play back facility, these can be saved to a file and replayed from there.

* Command protocol: is parameter controlled, so can be varied typically command is printable characters followed by a standard termination character ( typically cr or lf ) waits for a microcontroller response ( a sting of printable characters ), a standard termination character ( typically cr or lf ), or times out, or reaches a maximum length.  Records the reason for the end of the response.

* For some general notes on microcontroller communications see: [[RS232]].

== Software Contributions From Others ==

The software is built on several components that I did not write:  all, I believe, are some variation of open source, except for Java itself.


{| class="wikitable"
|-valign="top"	
|Component
|Source/Credit


<!-------------------------------->
|-valign="top"
|Java
|Sun Microsystems
<!-------------------------------->
|-valign="top"
|Javacomm
|Sun Microsystems  -- seems not to be well supported this will be migrated soon to another package
<!-------------------------------->
|-valign="top"
|PtPlot
|[http://ptolemy.eecs.berkeley.edu/java/ptolemy.plot2.0/ptolemy/plot/index.html Ptplot 2.0 - Java Plotter] [http://ptolemy.eecs.berkeley.edu/  http://ptolemy.eecs.berkeley.edu/]
<!-------------------------------->
|-valign="top"
|EasyLayout
|[http://easylayout.sohlman.com/ EasyLayout]
<!-------------------------------->
|-valign="top"
|Log4j
|need to look up the url
<!--------------------------------
|-valign="top"
|
|
<!--------------------------------
|-valign="top"
|
|
<!--------------------------------
|-valign="top"
|
|
<!-------------------------------->



|}

== Installation Directions For all the Applications ( This is a first cut, more details will follow ) ==

* Configure Java JDK or Java Runtime Environment as it suits you.  I am using version 1_4 to stay compatible with older machines.  You can find it round about [http://java.sun.com/j2se/1.4.2/download.html Download Java 2 Platform, Standard Edition, v 1.4.2 (J2SE)]

* Download and install the JavaComm API for your platform. Sun no longer supports this for windows; ( I will change to some other support soon ) I found it at [ http://wind.lcs.mit.edu/download/ Software Download and Install] Install can be a problem because a bad installation often fails without any messages.  Here are installation directions: [http://www.xpl4java.org/xPL4Java/javacomm.html Javacomm -- Serial and Parallel port access for Java and xPL]

* Download zip file.  [http://home.comcast.net/~russ_hensel/OC/MCSerialComm/bin08-06-04/MCSerialCommDist.zip] Unzip to an installation directory ( c:\RS232Etc for example but in any case avoid directory names with embedded blanks and if you stick to c:\RS232Etc fewer modifications will be required to the bat file. )  Do not un-jar the jar file(s) ( unless you just want to mess around )  Source code will be provided in RS232Etc.jar when it it a bit more stable.  Note that renaming the .jar file to .zip will allow you to extract the files with most zip utilities that do not directly support jar files.

* There is a file called RS32Probe.properties ( for the RS232Probe application or BitWacker.properties for the BitWacker applicaiont etc ).  ( we do it Edit RS32Probe.properties ( or the BitWacker.properties ... ) for your configuration, directions are in the file.

* There is a file named OriginalRunRS32Probe.bat ( and similar files for the other applications )  ( in c:\RS232Etc if you followed my suggestion for installation ), make a copy and name it RunRS32Probe.bat. Edit the  RunRS32Probe.bat file for your configuration ( see directions in bat file ).  We do the rename procedure to protect your version of the bat file against future updates. ( in the future we may just have you save the files in a safe place, this would be easier for me )

* See Start Up section for each application to continue and start the application.  If you have problems I will help you, email me with some details of the problem, include screen shots or detailed discription of error messages.


=== Reinstallation ===

Save your *.bat files and *.properties file in a safe place and download and unzip a new version.  Look at the new *.bat files and *.properties and see if yours need updating before replacing them.

== Coding Standards ==

This is more of a goal than a standard.  It may help in adapting the code to your use, or if you contribute consider them, you may have better ones, but lets discuss [[russ_hensel]] prior to any big changes especially on existing code.

Most development has been done in Netbeans, consider it.

If you make a change make sure everything still compiles, not just the stuff you are interested in.

Code for ease of reading and maintainability, do not abstract much more than necessary, especially as code becomes unreadable, or has many more methods than are actually used.

Lots of white space, preferably with meaning.

Use my as prefix for most instance variables.

Lots of comments, tell intent, do no repeat what can be read from the code.

Limit scope but you need not be a fanatic.

Meaningful variable, method, and class names, no Hungarian notation, but prefix for scope may be useful.

Access instance variables through getters and setters.  Exception: GUI elements.

I still use some deprecated techniques.  Not a high priority to fix, and I still want to run with old versions of Java.

Normally exceptions that can be expected should be managed by the application, eating them sometimes ( bad user input ) logging them other times ( hardware problems ).  Normally the console should not show exceptions thrown all the back to main.

== Example Property File == 

Many of the properties of the application are controlled by the ascii text file called the property file.  This example is given because the documentation of the file is almost entirely in the file.  Note that this is not the final version of the file, expect some expansion and contraction 
to occur.


; BitWacker.properties

; comments indicated by leading ; but on the wiki it makes the lines bold

; ---------------
; debugLevel 10 = lots of debug messages, 0 = none or almost -- this is being phased out in favor of log4j which has its own property file
debugLevel=9

; ---------------
; commPort  set the comm port that the unit will be on
; for USB installations use the device manager ( perhaps under Control Panel -> System -> Hardware )
; to see where your USB connection is installed.
; like COM1, COM2 ...

commPort=COM2

; ---------------
; Parity  even odd everything else is none
; 
; None is the only tested value, and is the standard value for BitWacker 
Parity=none

; ---------------
; Baud  string one of valid baud rates  9600 19200 ...
;
; xxxx is the standard value for BitWacker 
Baud=19200

; ---------------
; DataBits  5 6 7 8
;
; 8 is the only tested value, and is the standard value for BitWacker 
DataBits=8

; ---------------
; FlowControl     none   rtcs_in ... see parms
;
; None is the only tested value, and is the standard value for BitWacker 
FlowControl=none

; ---------------
; StopBits    1 "1.5"  2
;
; 1 is the only tested value, and is the standard value for BitWacker 
StopBits=1

; ---------------
; outputFile  location, name of output file
; can be full path or relative to where the app is running
; 
logFile=BitWackerLog.txt

; ---------------
; time in ms seconds between reading used by logger 
;deltaT=4000
;deltaT=50000
deltaT=1000

; ---------------

; scale the values for analog reading
;	Scale is set by having a high and low value that corresponds to the raw data values of the Bitwacker ( normally 10 bit? )
;   	by having low actually be high we can invert the scales!
;	each data channel also get a name 
; ---------------
; data Channel 0
dataChan0Lo=15
dataChan0Hi=-1
dataChan0Name=Voltage

; ---------------
; data Channel 1
dataChan1Lo=15
dataChan1Hi=-1
dataChan1Name=Current

; ---------------
; averageOver: to improve the analog readings we average ( moving average ) the values.
; measuremenst are running averages over this number of measurements, affects all channels
averageOver=3

; ---------------
; PlotStyle
; defines how data is plotted ( note, to gain flexibility this property will probably be revised in the future )
;   TIME_0: time on the X axis, channel 0 on the Y axis
;   HORZ_0       HORZ_1   VERT_0   VERT_1   XY_01      XY_10    XY_TARG_01 TIME_0 TIME_01


PlotStyle=TIME_01

; ---------------
// PICUnit1   PICUnitSim
//picUnitClassName=PICUnit1
// BitWacker for the BitWacker
// BitWackerSim to simulate the BitWacker 

picUnitClassName=BitWacker

; ---------------


; ===================== end ======================

End Example Property File