This section is intended to provide help to developers of other  programs who would like to interact with DataLink or with the latest version of the AquaCalc Pro Plus.

Output File Changes from Output Version 2.0 to Output Version 2.1 (January 2018, first implemented in firmware 2.4.2)

The AquaCalc Pro Plus (APP) has made changes to the AquaCalc Pro (AQP) version 2.0 output format. The new format is version 2.1and includes small changes. The order of items, the number of characters were kept as close to version 1.5 as possible.

1. Line 2: Changed from: “AquaCalc Pro Plus(tm) by JBS Instruments (c)2012” to “AquaCalc Pro Plus(tm) by AquaCalc LLC (c)2017”
2. Line 6: Changed from “File Version:, V2.0” to ” “File Version:, V2.1”

Output File Changes from Output Version 1.5 to Output Version 2.0

The AquaCalc Pro Plus (APP) has made changes to the AquaCalc Pro (AQP) version 1.5 output format. The new format is version 2.0 and includes small changes. The order of items, the number of characters were kept as close to version 1.5 as possible.

1. Line 2: Changed from: “AquaCalc Pro (tm) by JBS Instruments (c)2002” to “AquaCalc Pro Plus(tm) by JBS Instruments (c)2012”
2. Line 6: Changed from “File Version:, V1.5” to ” “File Version:, V2.0”
3. Line 8: Change from “Gage ID:” to “Sect ID:”
4. Line 20: Line 20 was mislabeled in Output Version 1.5. “Meter Const.C1” changed to “Meter Const.C2”.
5. Line 26: This line was a duplicate with line 48. “Section Diff:” changed to “Line Not Used:”, but this line will be repurposed in future output formats. (Suggestions are welcome).
6. An additional line “<\csv>”was added at the second to last line, (before the End of File character) to close the opening XML tag properly.

Using command codes for automatically downloading the AquaCalc Pro Plus

The AquaCalc Pro Plus (APP) has two way communication when the unit is placed in the Connections screen. This allows for the discovery of the APP using the Send Version Report command, followed by a Section List request for a list of sections measurements, and then finally a Send CSV command that will allow the retrieval of a CSV file containing the full measurement.

In the Connections screen the APP will listen for commands and respond with XML formatted Version reports and Sections Lists and a CSV format Section Output representing the data collected

The AquaCalc Pro Plus (APP) must be in the Connections screen for data exchange commands to work. The APP appears as a serial communications port to a Window computer with the USB Driver installed. Windows will assign the APP a virtual Communications Port (COM Port) and the APP receives standard ASCII over the USB connection at 19200 baud rate using the serial port communications protocol.

• Note: There must be a minimum of 1000 milliseconds (1 second) between commands. There should be a 4000 millisecond (4 second) delay after the Delete Section or Delete Observation commands to allow the AquaCalc Pro Plus to finish processing.

Connections screen commands

Send Version Report  = <sendver>

Send CSV  = <sendcsv>0</sendcsv>

List Sections  = <listsec>

Delete Section  = <delsect>0</delsect>

Delete Observations  = <delobs>0</delobs> (NOT IMPLEMENTED)

Send Version Report

The version report gives the status of an AquaCalc Pro Plus, including the firmware version that is running and the serial number of the unit.

Version Report Sample:

<vr>AquaCalcPro2,2.0.1,2.0.0,04/30/12 14:36,P3000001,BOBSAQUACALC    </vr>

Where:

• AquaCalcPro2 is the model number (an AquaCalc Pro Plus)
• 2.1.0 represents the boot version (not important for downloading),
• 2.0.0 represents the firmware version.
• 04/30/12 14:36 (mm/dd/yy hh:mm) is the date of the firmware version.
• P3000001 is the serial number of the unit.
• BOBAQUACALC is the AquaCalc ID (a user entered value)

• Each command string is followed by a Carriage Return followed by a Line Feed (ASCII character 13 followed by ASCII character 10).

List Sections

Prompts the APP to send an XML formatted list of the sections it has in memory with some basic information about the section in a CSV encoded string.

<listsec> - list the sections:

The items in the string include:

• AquaCalc Memory location (01 through 30 at the present time, may be increased in the future) Note: this memory location is used in the Send CSV command.
• Section ID (alpha-numeric, 16 characters),
• User ID (alpha-numeric, 16 characters)
• Measurement Date and Time (alpha-numeric date time format, 14 characters)
• Number of Verticals in the Section (numeric)
• Total Discharge / Q (numeric with decimal, nn.nn)

• Section List format output example

<sectionlist>

<section>04,YELLOW CREEK,TOM JONES,11/23/10 12:00,22,99.99</section>

<section>05,YELLOW CREEK,TOM JONES,11/24/10 12:00,25,00.99</section>

</sectionlist>

Each section line includes the following:

<section> memory location,SID,User ID,Beginning Time,Number of verticals,discharge </section>

Send CSV

Requests a section measurement be sent in a CSV format from the memory location specified.

<sendcsv>01</sendcsv> – send the active section in memory location 1 using the traditional APP csv format.

Delete Section

This command deletes a complete section measurement, all verticals, and all observations. Typically used after downloading a section to the computer.

<delsect>02</delsect>– delete the entire section in location 2

Delete Observations (NOT IMPLEMENTED)

The delete observations command removes only the observation data but maintains the section information and the vertical locations.

<delobsv>03</delobs> – delete only the observations in location 3

Calling DataLink from Another Program

DataLink 3 can be called from another program and used to download and review AquaCalc measurements. But, since DataLink can be installed and updated directly from our website using Microsoft’s ClickOnce technology, the location of the executable may not be obvious. ClickOnce installs the executable (AquaCalc DataLink 3.exe) into the Users folder. The file path for the executable can be found using registry keys.

We have added a registry keys in the HKEY_CURRENT_USER space to identify the location of the DataLink 3 executable (AquaCalc DataLink 3.exe),

HKEY_CURRENT_USER/JBSEnergy/DataLinkApplicationPath

Accessing the Download Log XML file

AquaCalc DataLink 3.1 and above has the ability to create an optional download log that lists the file names and file paths from the last download in an XML log file. These log files were created at the request of the USGS to aid in importing downloaded measurements to their systems.

We have added a registry key in the HKEY_CURRENT_USER space to identify the location of the DataLink download log file:

HKEY_CURRENT_USER/JBSEnergy/DataLinkDownloadLogPath

This key is not created until a download log is created the first time. To write to the download log file (and create the Registry Keys)

1. In DataLink3.1 and above, the user must first go into “Settings” using the toolbar icon, and select the Options tab, and check the “Write to Download Log File” checkbox. If you would like this log deleted each time DataLink 3 is restarted, check the box “Delete Download Log on Startup” otherwise the log will continue to grow.
2. Initiate a Download Session in DataLink.

In the log, each “Download Session”  begins when the user clicks the Download button, and ends when the Download Section Measurements window is closed. There can be several Download sessions per open and close of DataLink if the user opens and closes the Download Section Measurements screen several times. The log is further delineated by the AquaCalc model, and in the case of the AquaCalc Pro Plus, the serial number of the AquaCalc.

As a developer, you will be looking for the XML tag “<filepath>” in the log to identify a line containing a file path to the downloaded file. The following XML log shows one automated AquaCalc Pro Plus download session, followed by two downloads from an older AquaCalc Pro.
 
<DownloadSession datetime="4/23/2013 1:19:13 PM">
<AquaCalc Pro Plus SN="13020117">
<filepath>C:\Users\Greg\Documents\5___13020117_13020117_030513_1656.csv</filepath>
<filepath>C:\Users\Greg\Documents\031313_0829_13020117_13020117_031313_0830.csv</filepath>
<filepath>C:\Users\Greg\Documents\032213_1226_13020117_13020117_032213_1226.csv</filepath>
</AquaCalc Pro Plus>
</DownloadSession>
<DownloadSession datetime="4/23/2013 1:23:39 PM">
<AquaCalcPro>
<filepath>C:\Users\Greg\Documents\042313_1410___000000_0000.csv</filepath>
</AquaCalcPro>
<AquaCalcPro>
<filepath>C:\Users\Greg\Documents\TEST_GR__040913_1629.csv</filepath>
</AquaCalcPro>
</DownloadSession>
 

If you have additional questions or suggestions, we would be happy to help.