Public Lab Research note


Getting your WheeStat set up.

by JSummers | July 04, 2014 17:40 04 Jul 17:40 | #10658 | #10658

What I want to do

This research note is intended to explain how to setup a WheeStat potentiostat.

Stuff you need to do:

Install Drivers: The WheeStat is based on the Stellaris or Tiva microcontroller development board from Texas Instruments. The first thing you will need to do is download and install drivers. Of course, you will need the drivers that are compatible with your operating system. Texas Instruments only provides drivers that are compatible with windows and that is all that I have direct experience with. Drivers for Windows: Windows drivers for the In-Circuit-Debug-Interface (ICDI) can be downloaded from this web page found here. At the same web page is a link to instructions for installing the drivers on windows machines. I recommend you print out the instructions and have them handy when installing the drivers.
Problems with Windows 8 I was recently informed that there are issues loading the TI drivers on computers running Windows 8. A user named Randy told me of his problems and how he overcame them in the following; "_Ends up that Windows 8.1 has a requirement for all drivers to be signed. Here is a way to reset that on this web site: https://learn.sparkfun.com/tutorials/disabling-driver-signature-on-windows-8

Note that I was not able to get to the restart section in recovery in Windows 8.1 and had to go to a command prompt and use : shutdown /r /o This forced it to go to the section where I could enter Trouble shooting and then deactivate the driver signature requirement. After the normal tripple reboot that seems to be part of the Windows world; all the drivers loaded. I noticed on the search that the Arduino community is also experiences this problem." If you are having troubles with Windows8.1, there are some further suggestions under the "Hacking the WheeStat GUI" section, below. Drivers for the Mac As described above, TI does not have Tiva drivers on their web page for Mac or Linux. I have seen postings on web forums where people talk about using the LaunchPad with the Mac but despite my searching, I have not seen a description of how the drivers were installed, until now. When I brought this issue up with PublicLab's Mathew, he responded that "it was actually really straightforward-- after i decided to ignore TI's instructions-- I downloaded the Mac version of Energia and it automatically asked if I wanted to install the driver afterwords." OK, so that doesn't sound too bad. Drivers for Linux I am in contact with a guy named Daniel who was able to get the WheeStat working on a Raspberry Pi. He wrote: “About drivers for linux, it's actually quite easy to setup. In any ubuntu based environment you only have to install a few packages for the msp430 processor and you're good to go (they are easily installed using apt-get). After you connect the wheestat it becomes available within a serial port (usually /dev/ttyACM0) and doing the rest is quite straight forward. ”_ The msp430 was a less advanced, earlier version of the LaunchPad. If you would like me to ask Daniel for more information, just leave a comment below.
Install GUI Application Files You should be able to get this software from our GitHub page (here. You will need the application file (.exe) and the folders containing the source code, the libraries, and the data files (all found here). These will all need to be in one folder on your computer. Please note that the GUI and the microcontroller code work together and an earlier version of one may not work with a later version of the other. The current version of the GUI (WheeStat5_4_2) works with the current version of the microcontroller code (WheeStat5_4b) and not with earlier software versions. Get or Make Electrodes We have a research note here describing how to make electrodes at low cost. If you want to do metal ion analysis at very low concentrations, I think you will need to invest in a higher quality working electrode. When we need to detect low concentrations of metals, we use something called "glassy carbon" as our working electrode and work in acidic solutions. When working in acid, the cheap graphite rods appear to undergo a reaction that interferes with the analysis. The cheapest source of glassy carbon electrodes that I have found is CH Instruments. At the time I wrote this, you could get an appropriate electrode for $88 from found here.

Stuff you don't necessarily need to do:

Loading Energia code onto the microcontroller Before you do anything else, plug the USB cable from the WheeStat into your computer. Sometimes it takes a while for a computer to identify the appropriate drivers. While we envision shipping kits with the code already programmed into the microcontroller, there will be cases where someone might like to re-install, update, or just plain hack the code. For those events, you will need to download the Energia program from www.enerrgia.nu and get the Energia source code. If you buy a kit from us, it should come with a usb memory stick that has the source code. If you don't have this, you can download the code from our GitHub site, here. As of July 9, 2014, the most recent version was WheeStat5_4b, which can be found here. The program is comprised of ten files (filename.ino) that all need to be in a folder with the name "WheeStat5_4b". When you open the Energia program, the top left corner of the window should look like this:

upperLeftCorner.png

Going to the File dropdown, select open, then navigate around until you fine the file "WheeStat5_4a" and open it. You should see something like the figure below. Notice that the figure has a number of tabs, including WheeStat5_4a, DiffPulse, Open_Circuit, etc. If all the tabs don't show up, write me a comment (below) and I will figure out what went wrong and let you know how to fix it.

EnergiaWheeStatScreenshot1.png

If everything is OK, you should be able to compile the program by clicking on the red button with the check mark at the top of the window. Unfortunately, it did not compile and there is a list of error messages at the bottom of the window. The first thing to look at is the lower corner of the Energia window. It should look something like this:

EnergiaBoardSpec.png

If it says something like "LaunchPad w/ msp430..." instead of "StellarPad w/lm4f ..." then you are set up on the wrong microcontroller. Go to the "Tools" dropdown, click on "Board" and select "StellarPad w/ lm4f ...". That should change the text in the bottom right.

Now, when you click on the check button, you will get a new list of error messages. Prominent among these are references to something called "altSPI". You got these error messages because you did not download the altSPI folder into your Sketchbook. OK, so first of all you need to figure out where your Sketchbook is located on your computer. From the Energia window, under the File tab, clicking on "Preferences" will open this dialog box:

EnergiaPreferences.png

Notice that the first line tells you where the Sketchbook is located. Now open a window and find the Sketchbook. Inside the Sketchbook there should be a folder called "libraries". If there isn't one there, make one. Inside the libraries folder, make a folder called altSPI. Inside that folder, you need the following files; altSPI.h and altSPI.cpp. Go back to the GitHub site (here) and click on the altSPI link. You will find the files you need there. Once you have these files installed, you should be able to compile the microcontroller code for the WheeStat. To upload the source code to the microcontroller, you first need to establish communications. Under the "Tools" dropdown, select Serial Port. There should be at least one com port to select. If there is more than one, unplug your WheeStat and see which com port goes away. Once selected, you should see the port specified on the lower right corner of the Energia window. To upload the code, click on the button next to the check button, it is the one with the arrow pointing to the right.

Hacking the WheeStat GUI:

To modify the user interface you will need to download the program Processing from www.processing.org. You will also need to download a couple of libraries (gicentreUtils and controlP5a). These need to be in the libraries folder in your Processing sketchbook. You can download the libraries from here and here, respectively. These files should be unzipped and placed into a folder titled "libraries" inside the processing folder. It is kind of important that your files are structured the way Processing expects to see them. On my computer it goes C:\Users\Summers\Documents\Processing\libraries . Inside the libraries folder there should be folders called controlP5 and gicentreUtils.
Once you have this setup, open Processing and use it to open the GUI source code. As of January 2015, the most recent version is WheeStat5_4_2.pde. If you bought a WheeStat kit, the source code should be on a flash drive that came with the kit. Otherwise, the most recent version should be on our GitHub site. Once you have the source code open, you should be able to run the program by clicking on the "play" triangle icon on the Processing GUI. To generate an application (.exe) file, go to File and select Export Application. This will open a dialog box that allows you to select to create Windows, Mac, or Linux applications. When you execute the command, it will generate a new file in your source code file that contains the executable application file. Randy tells me that the following are necessary to get jar files to run when using Windows 8.1: "4. Open notepad and create a new file in the same folder as the .exe you want it to run. Type in the command: "C:\Program Files\Java\jre1.8.0_25\bin\javaw.exe" -Djava.ext.dirs=lib -Djava.library.path=lib WheeStat5_4'

I got this idea from postings on: forum.processing.org/two/discussion/780/why-execute-not-run-processing-2-1/p1

(Note: make sure you use your own path to the javaw.exe file. I included the "" around it because there is a space in the path name).

  1. Save this file with a .bat extension using "save as" and make sure you click to use "all files". Note pad will default to txt file and the bat will not run. Make sure you put it in the same folder as the .exe you want it to run.

  2. Double click on the bat file and "Bob's your uncle" the program runs."

Let me know if you have troubles.

Calibration of the WheeStat: Batch to batch variation in electronic components introduces some error in measured current values. These errors may be compensated for by adjusting certain parameters in the WheeStat code. We should stress that this step is not necessary for routine use, since absolute numbers are not generally reported for currents. To calibrate the potentiostat, you will need to download make a series of measurements, enter your results into the source code, and upload the modified code to your instrument.

Instructions to calibrate the instrument follow. Attach the green and red leads to one side of a resistor (Rtest) and the black lead to the other side. Set the values of the ‘current gain and current offset’ in the GUI to 0 and select ‘ramp’ from the mode dropdown. If the instrument is functioning ‘ideally’, then running a ramp experiment should give a straight line that runs through the origin (0 current, 0 mV) and both should have a slope equal to 1/Rtest. In short, Ohm's Law requires that the two data sets should overlap, regardless of the gain setting. Typical behavior of an instrument that is out of calibration is presented in the figure below. The noisier of the two was recorded with a gain value of 2, while the other was recorded with a gain of 10. While both show linear behavior, their slopes and intercept values are incorrect. This deviation will be greatest at the extremes of the allowed current gain settings (close to either 0 or 30).
calibration1.png The data sets do not overlap because resistance values assumed by the software are inaccurate. The difference in the slopes of the two plots can be corrected by adjusting the value of the resW parameter on line 23 of the Energia code. It will look something like this:

resWlocation.png Change the value (1.2 in this case) to a larger value, say 2.0. Close the GUI, upload the modified Energia code to your instrument, re-start the GUI and record another set of voltammagrams with the gain set, first at 10 and then at 2, as described above. If the slope of the voltammagram with gain = 2 more closely resembles that with gain = 10, then you have gone in the correct direction. If not, then try again with decreased value of resW. Continue this process until the two voltammagrams give parallel lines.
Minor differences in intercept can be adjusted using the "corr" parameter. Once the data sets are co-linear, the absolute slope is adjusted to equal 1/Rtest by changing "res6". The absolute slope of your data can be determined in a spreadsheet program such as excel. To get the data into a spreadsheet, save it as "filename.csv". This will allow you to open the file with excel.

More than you ever wanted to know:

Current amplification is determined by setting resistance values on digital potentiometers in the WheeStat. The ‘current gain’ value from the GUI determines the resistance values that are loaded for any given experiment. Accepted values for gain parameter can range from 0 to 30. If a value greater than 30 is entered, the value is reset to 30 in the GUI program. Negative values are reset to zero. Incrementing the gain results in an increase in amplification of approximately 1 dB. Calculated values of amplification as a function of gain value are presented in Figure _. The trend line in this figure presents the equation: Amplification = 700*10(gain/10) Calculated amplifications for each gain value are presented as open diamonds. This calculation assumes ideal behavior of the 50 Kohm linear potentiometers and 10 Kohm resistor. We note that batch-to-batch deviations from nominal resistance values are reported to be as high as 20% by electronic component manufacturers. Due to large amplifications of uncertainties in offset voltages, greatest accuracy in measuring current values will be obtained with offset set to zero.

gainGraph.png

Theory: The current passed (i) is related to the measured output voltage (Vout), the offset voltage (Voff), instrument voltage (vcc) and three resistances (R4, R5, R6) according to the equation: I = (R5 / (R4R6)) * {Vout – Voff(1 + R6/R5) + vcc(R6/(2R5))} Of the above variables, vcc and R6 can be measured with your multimeter. Values of R4 and R5 are determined by the ‘current gain’ parameter from the GUI. R6 can be measured when the instrument is not receiving power from your computer. The value of vcc is measured when the power is applied.

The slope of the ramp should be determined by three resistors, R4, R5, and res6, with R4 and R5 being variable resistors determined by the gain value: Slope = R4res6 / R5 R4 = resPot * (128-N0)/128 + resW R5 = resPot * N1/128 + resW Since the value of resW is much less than resPot (75 ohms versus 50 Kohms), the former does not usually contribute significantly to values of either R4 or R5 (Exceptions arise at the two extremes of amplification, when either N0 = 128 or N1 = 0). For the usual case, amplification is determined by: Slope = (128-N0)res6 / N1 Notice that since resPot appears in both the numerator and denominator, it does not show up in the equation. Thus, we have opted to use the nominal value of resPot provided by the component manufacturer, 50 Kohm. Values of N0 and N1 for each value of ‘current gain’ are presented in Table 1, below.

gainTable.png

Questions and next steps

Let me know if you have questions.

Why I'm interested

just tryin' to get it out there.


12 Comments

Jack, this is fantastic. Very clear explanation! Could we have a follow-up note at some point soon re: e.g. how you might use the WheeStat potentiostat to assess the presence of a heavy metal in water? That would be really cool, too! And is there a link to where to get a WheeStat? Great stuff!

Is this a question? Click here to post it to the Questions page.

Reply to this comment...


Hi Don, Glad to hear that you liked the explanation.
I hope to get around to measuring some metals in water before long and once I do, I will publish research notes. Right now, however, I am trying to focus on production and user support (like the user's manual and this setup tutorial). I am hopeful that we will be able to sell kits from the Public Lab store before the end of summer (2014). I am in the process of getting a run of boards professionally fab'd, so we should be able to get these to market before long. In the mean time, if you know anyone who wants a kit (or a finished instrument) have them email me, summers at wcu dot edu.
Best, Jack

Reply to this comment...


Dear Dr. Summers,

I still get the same error after doing everything I could:

WheeStat5_4b.ino: In function 'void setup()': WheeStat5_4b:122: error: 'PWMWrite' was not declared in this scope WheeStat5_4b.ino: In function 'void loop()': WheeStat5_4b:135: error: 'PWMWrite' was not declared in this scope Chronoamperometry.ino: In function 'void chronAmp()': Chronoamperometry:10: error: 'PWMWrite' was not declared in this scope DiffPulse.ino: In function 'void diffPulse()': DiffPulse:21: error: 'PWMWrite' was not declared in this scope DiffPulse.ino: In function 'void cleanDepos()': DiffPulse:52: error: 'PWMWrite' was not declared in this scope Open_Circuit.ino: In function 'void openCircuit()': Open_Circuit:9: error: 'PWMWrite' was not declared in this scope normalPulse.ino: In function 'void normPulse()': normalPulse:14: error: 'PWMWrite' was not declared in this scope ramp.ino: In function 'void ramp()': ramp:14: error: 'PWMWrite' was not declared in this scope ramp.ino: In function 'void pRamp(int)': ramp:39: error: 'PWMWrite' was not declared in this scope ramp.ino: In function 'void nRamp(int)': ramp:68: error: 'PWMWrite' was not declared in this scope reset.ino: In function 'void status()': reset:16: error: 'NVIC_APINT' was not declared in this scope reset:16: error: 'HWREG' was not declared in this scope reset:16: error: 'NVIC_APINT_VECTKEY' was not declared in this scope reset:16: error: 'NVIC_APINT_SYSRESETREQ' was not declared in this scope

Need help please! Thank you!

Reply to this comment...


I responded to Kloots' comment (above) by email, but by the time he got it he had already diagnosed and fixed the problem. As I understand it, the problem arose from having the wrong microcontroller board assigned in Energia. If you encounter this issue, please read the text in this research note under the heading "Stuff you don't necessarily need to do", starting below the second figure. Best,

Jack

Reply to this comment...


Jack, I'm not able to get the Wheestat's port to recogize on a mac-- Processing won't recognize the USB Port-- I can only select bluetooth.

Screen_Shot_2014-09-25_at_7.40.30_PM.png

Reply to this comment...


Ok. Can you see the port from Energia? That will tell us whether it is a mac / energia issue or a mac / processing issue. Jack

Is this a question? Click here to post it to the Questions page.

Reply to this comment...


Hi Mathew, My guess it that this is going to be a processing issue. My next guess is that there is a problem on line 13 of the Dropdown_Lists tab. The line says: comList = serialPort.list(); try changing that to the following and see if that fixes things: comList = Serial.list(); I think the serialPort.list() comes from controlP5 but Serial.list() comes with Processing. Either command works with windows, but I dont have a mac here to try it on.

Let me know if this works. If it doesn't, I will look some more. Jack

Reply to this comment...


Hi Jack,

I am also trying to connect a Raspberry Pi to the Wheestat with the TM4C123G launchpad. Could you (or Daniel) add an extra bit to the Linux drivers section explaining how to do so please?

Thanks in advance,

Sean

Is this a question? Click here to post it to the Questions page.

Reply to this comment...


Hi Sean, Sorry about the delay in getting back to you. I was out of town. I sent Daniel an email asking him for more info and I will look into this some more in the next few days. Best, Jack

Reply to this comment...


This is the link to the Public Lab product page for the WheeStat if folks would like to purchase one.

http://store.publiclab.org/collections/new-kits/products/wheestat-potentiostat

Reply to this comment...


Dear Dr. Summers,

I ordered WheeStat 5.1 potentiostat from OSH Park and built a potentiostat system as described here. Everything seems fine except when I'd like to use the Wheestat software (at first testing with the resistor) I get very random data points, without any relation. The voltage range of these data points is also different from set voltage range (-400 - 400 mV), it vary between 1100-1600 mV. I tried to use newer software version, but the results were the same. Do you have idea what is the problem or have you met a problem like this before?

Thanks in advance! László

Is this a question? Click here to post it to the Questions page.

Reply to this comment...


I ordered a WheeStat from the Public Lab Store. The board is stamped "WheeStat 5". I'm running Ubuntu 16.10 (64-bit) and just wanted to share the easy steps I took to run the software.

  • I didn't have to install any system software, although other information about the Tiva C Series LaunchPad controller suggests that you might need to install libusb. This was already installed on my system. I checked by running: dpkg -l | grep libusb.
  • The USB drive that came with my kit only contained the Windows executable for the Processing code for WheeStat GUI. I cloned the WheeStat6_0d repository from GitHub.
  • There is a shell script that can be run to open the GUI program, application.linux64/Wh eeStat6_0d, but I first had to make it executable by running chmod u+x ./application.linux64/Wh eeStat6_0d.
  • I connected the controller to my computer using the USB cable. I confirmed that the computer detected the controller by running dmesg. This is the output related to connecting the controller:

    [18390.432107] cdc_acm: USB Abstract Control Model driver for USB modems and ISD N adapters [18456.074920] usb 1-2: USB disconnect, device number 7 [18468.801784] usb 1-2: new full-speed USB device number 8 using xhci_hcd [18468.986832] usb 1-2: New USB device found, idVendor=1cbe, idProduct=00fd [18468.986851] usb 1-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3 [18468.986863] usb 1-2: Product: In-Circuit Debug Interface [18468.986873] usb 1-2: Manufacturer: Texas Instruments [18468.986882] usb 1-2: SerialNumber: 0E20AEDE [18468.989924] cdc_acm 1-2:1.0: ttyACM0: USB ACM device

The last line of output tells me that the device will be available at /dev/ttyACM0.

  • Finally, I ran the GUI software. I had to run it using sudo in order for the device to be found, i.e. sudo ./application.linux64/WheeStat6_0d.

Reply to this comment...


Login to comment.