Campbell Bmp5 direct sdk User manual

BMP5 Direct SDK

Revision: 12/11

Campbell Scientific, Inc.

License For Use

This BMP5 Direct Software Development Kit software, hereinafter referred to

as the BMP5 Direct SDK, is protected by both United States copyright law and

international copyright treaty provisions. The installation and use of this

software constitutes an agreement to abide by the provisions of this license

agreement. The term "developer" herein refers to anyone using this BMP5

Direct SDK.

By accepting this agreement, you acknowledge and agree that Campbell

Scientific may from time-to-time, and without notice, make changes to one or

more components of the SDK or make changes to one or more components of

other software on which the SDK relies. In no instance will Campbell

Scientific be responsible for any costs or liabilities incurred by you or other

third parties as a result of these changes.

The core operational files included with this BMP5 Direct SDK (hereinafter

referred to as “BMP5 Direct Binaries”) include the files: SimplePB.DLL and

coralib3d.dll. Developer may distribute or sell their software including the

BMP5 Direct Binaries subject to the terms hereafter set forth.

RELATIONSHIP

Campbell Scientific, Inc. hereby grants a license to use BMP5 Direct Binaries

in accordance with the license statement above. No ownership in Campbell

Scientific, Inc. patents, copyrights, trade secrets, trademarks, or trade names is

transferred by this Agreement. Developer may use these BMP5 Direct

Binaries to create as many applications as desired and freely distribute them.

Campbell Scientific, Inc. expects no royalties or any other compensation.

Developer is responsible for supporting applications created using the BMP5

Direct Binaries.

RESPONSIBILITIES OF DEVELOPER

The Developer agrees:

•To provide a competent programmer familiar with Campbell Scientific,

Inc. datalogger programming to write the applications.

•Not to sell or distribute documentation on use of the BMP5 Direct

Binaries.

•Not to sell or distribute the applications that are provided as examples in

the BMP5 Direct SDK.

•Developers may copy and paste portions of the code into their own

applications, but their applications are expected to be unique creations.

•This Agreement does not give Developer the right to sell or distribute any

other Campbell Scientific, Inc. Software (e.g., PC200W, VisualWeather,

LoggerNet or any of their components, files, documentation, etc.) as part

of Developer's application. Distribution of any other Campbell Scientific,

Inc. software requires a separate distribution agreement.

•Not to develop applications that compete directly with any application

developed by Campbell Scientific, Inc. or its affiliates.

•To assure that each application developed with BMP5 Direct Binaries

clearly states the name of the person or entity that developed the

application. This information should appear on the first window the user

will see.

WARRANTY

There is no written or implied warranty provided with the BMP5 Direct SDK

software other than as stated herein. Developer agrees to bear all warranty

responsibility of any derivative products distributed by Developer.

TERMINATION

Any license violation or breach of Agreement will result in immediate

termination of the developer's rights herein and the return of all BMP5 Direct

SDK materials to Campbell Scientific, Inc.

MISCELLANEOUS

Notices required hereunder shall be in writing and shall be given by certified or

registered mail, return receipt requested. Such notice shall be deemed given in

the case of certified or registered mail on the date of receipt. This Agreement

shall be governed and construed in accordance with the laws of the State of

Utah, USA. Any dispute resulting from this Agreement will be settled in

arbitration.

This Agreement sets forth the entire understanding of the parties and

supersedes all prior agreements, arrangements and communications, whether

oral or written pertaining to the subject matter hereof. This Agreement shall

not be modified or amended except by the mutual written agreement of the

parties. The failure of either party to enforce any of the provisions of this

Agreement shall not be construed as a waiver of such provisions or of the right

of such party thereafter to enforce each and every provision contained herein.

If any term, clause, or provision contained in this Agreement is declared or

held invalid by a court of competent jurisdiction, such declaration or holding

shall not affect the validity of any other term, clause, or provision herein

contained. Neither the rights nor the obligations arising under this Agreement

are assignable or transferable.

If within 30 days of receiving the BMP5 Direct SDK product developer does

not agree to the terms of license, developer shall return all materials without

retaining any copies of the product and shall remove any use of the BMP5

Direct Binaries in any applications developed or distributed by Developer. In

the absence of such return, CSI shall consider Developer in agreement with the

herein, stated license terms and conditions.

Limited Warranty

The following warranties are in effect for ninety (90) days from the date of

shipment of the original purchase. These warranties are not extended by the

installation of upgrades or patches offered free of charge:

Campbell Scientific warrants that the installation media on which the software

is recorded and the documentation provided with it are free from physical

defects in materials and workmanship under normal use. The warranty does not

cover any installation media that has been damaged, lost, or abused. You are

urged to make a backup copy (as set forth above) to protect your investment.

Damaged or lost media is the sole responsibility of the licensee and will not be

replaced by Campbell Scientific.

Campbell Scientific warrants that the software itself will perform substantially

in accordance with the specifications set forth in the instruction manual when

properly installed and used in a manner consistent with the published

recommendations, including recommended system requirements. Campbell

Scientific does not warrant that the software will meet licensee’s requirements

for use, or that the software or documentation are error free, or that the

operation of the software will be uninterrupted.

Campbell Scientific will either replace or correct any software that does not

perform substantially according to the specifications set forth in the instruction

manual with a corrected copy of the software or corrective code. In the case of

significant error in the installation media or documentation, Campbell

Scientific will correct errors without charge by providing new media, addenda,

or substitute pages. If Campbell Scientific is unable to replace defective media

or documentation, or if it is unable to provide corrected software or corrected

documentation within a reasonable time, it will either replace the software with

a functionally similar program or refund the purchase price paid for the

software.

All warranties of merchantability and fitness for a particular purpose are

disclaimed and excluded. Campbell Scientific shall not in any case be liable for

special, incidental, consequential, indirect, or other similar damages even if

Campbell Scientific has been advised of the possibility of such damages.

Campbell Scientific is not responsible for any costs incurred as a result of lost

profits or revenue, loss of use of the software, loss of data, cost of re-creating

lost data, the cost of any substitute program, telecommunication access costs,

claims by any party other than licensee, or for other similar costs.

This warranty does not cover any software that has been altered or changed in

any way by anyone other than Campbell Scientific. Campbell Scientific is not

responsible for problems caused by computer hardware, computer operating

systems, or the use of Campbell Scientific’s software with non-Campbell

Scientific software.

Licensee’s sole and exclusive remedy is set forth in this limited warranty.

Campbell Scientific’s aggregate liability arising from or relating to this

agreement or the software or documentation (regardless of the form of action;

e.g., contract, tort, computer malpractice, fraud and/or otherwise) is limited to

the purchase price paid by the licensee.

Campbell Scientific may from time-to-time, and without notice, make changes

to one or more components of the SDK or make changes to one or more

components of other software on which the SDK relies. In no instance will

Campbell Scientific be responsible for any costs or liabilities incurred by you

or other third parties as a result of these changes. There is no written or implied

warranty provided with the SDK software other than as stated herein.

Developer agrees to bear all warranty responsibility of any derivative products

distributed by Developer.

BMP5 Direct SDK Table of Contents

PDF viewers note: These page numbers refer to the printed version of this document. Use

the Adobe Acrobat® bookmarks tab for links to specific sections.

1. BMP5 Direct SDK Overview .....................................1-1

1.1 General Notes on BMP5 Direct SDK Usage ........................................ 1-1

1.2 Datalogger Program Table Structure .................................................... 1-1

2. SimplePB.DLL Reference.........................................2-1

2.1 OpenPort() ............................................................................................ 2-1

2.2 ClosePort()............................................................................................ 2-1

2.3 OpenIPPort()......................................................................................... 2-2

2.4 CloseIPPort() ........................................................................................ 2-2

2.5 GetClock() ............................................................................................ 2-2

2.6 SetClock() ............................................................................................. 2-3

2.7 GetValue() ............................................................................................ 2-4

2.8 SetValue()............................................................................................. 2-5

2.9 GetData() .............................................................................................. 2-6

2.10 GetDataHeader()................................................................................. 2-7

2.11 GetCommaData()................................................................................ 2-8

2.12 File_Send() ......................................................................................... 2-9

2.13 GetAddress()..................................................................................... 2-10

2.14 GetStatus() ........................................................................................ 2-11

2.15 GetTableNames().............................................................................. 2-12

2.16 GetDLLVersion().............................................................................. 2-13

2.17 GetLastResults() ............................................................................... 2-13

2.18 FileControl() ..................................................................................... 2-13

Appendix

A. Sample Program Table Structure .......................... A-1

Section 1. BMP5 Direct SDK Overview

The BMP5 Direct Software Development Kit (SDK) is a programming

interface that facilitates simple and direct communication with a single

datalogger containing a PakBus operating system. This SDK uses a simple

call-level API (SimplePB.DLL) that does not need to be registered on the PC.

However, the SimplePB.DLL wrapper accesses and therefore requires the

included communications engine, CORALIB3D.DLL, to be installed in the

same folder.

The BMP5 Direct SDK allows the creation of basic BMP5 application packets

that are sent to PakBus dataloggers over the PakBus network. Examples and

controls are installed by default in C:\Campbellsci\BMP5DirectSDK.

1.1 General Notes on BMP5 Direct SDK Usage

In order to communicate with the datalogger, a direct connection must be

created using the SimplePB.DLL. The BMP5 Direct SDK allows a connection

to a single datalogger through either an IP port or a COM port using the

OpenIPPort() or OpenPort() command.

Opening the COM or IP port starts the CORALIB3D.DLL. Therefore, the

COM port or IP port opened by the application must be closed before exiting

the application or the CORALIB3D.DLL will crash. Use the functions

CloseIPPort() or ClosePort() before the application exits to stop the

CORALIB3D.DLL and to properly close the connection. Starting the

CORALIB3D.DLL creates a working directory including log files by default in

C:\Campbellsci\SimplePB.

Once a connection is established, additional commands can be used to access

and administer the datalogger. A datalogger program can be sent, the clock can

be checked or set, values can be set, and data can be collected. Use a

combination of the commands found in the SimplePB.DLL to accomplish the

desired task.

1.2 Datalogger Program Table Structure

One default table in a PakBus datalogger is the Status table. The datalogger

may also include either a Public table or an Inlocs table. The Status table

contains values describing the datalogger and datalogger program and the

Public or Inlocs table stores all public variables or input locations. The user

defines any additional tables in the program sent to the datalogger.

When using the SimplePB.DLL to access specific tables and fields in a

datalogger program, the table number and the field number are implied by their

respective positions. For example, table number one is the first table in the

datalogger program and field number one is the first field following the

mandatory record number and timestamp fields within the table. The user must

understand the table structure of the program running in the datalogger because

table and field names and numbers are used to identify and access specific

tables and fields in several of the SimplePB.DLL commands.

1-1

Section 1. BMP5 Direct SDK Overview

1-2

Section 2. SimplePB.DLL Reference

The SimplePB.DLL is a call-level API that does not need to be registered on

the PC. However, the SimplePB.DLL wrapper accesses and therefore requires

the included communications engine, CORALIB3D.DLL, to be installed in the

same folder. The SimplePB wrapper provides an easy interface through the

CORALIB3D.DLL communications engine to access a single datalogger. The

following commands are available in the SimplePB.DLL:

2.1 OpenPort()

Opens a COM port to allow a direct connection to the datalogger.

Syntax

OpenPort(com_port_no, baud)

Parameters

com_port_no: Integer – The COM port to open.

baud: Integer – The baud rate used by the COM port.

Return Codes

0: Integer – Successful.

-1: Integer – COM port failed to open or is already open.

2.2 ClosePort()

Closes the previously opened COM port.

Syntax

ClosePort()

Return Codes

0 = Successful.

-1 = COM port failed to close or was not open.

2-1

Section 2. SimplePB.DLL Reference

2.3 OpenIPPort()

Opens an IP port to allow a connection to a datalogger.

Syntax

OpenIPPort(ip_address, tcp_port)

Parameters

ip_address: String – A valid IP address for the datalogger.

tcp_port: Integer – The port that will be used when communicating with the

datalogger.

Return Codes

0 = Successful.

-1 = IP port failed to open or is already open.

2.4 CloseIPPort()

Closes the previously opened IP port.

Syntax

CloseIPPort()

Return Codes

0 = Successful.

-1 = IP port failed to close or was not open.

2.5 GetClock()

Query the datalogger for its current date and time.

Syntax

GetClock(pakbus_address, device_type, return_data, return_data_len)

Parameters

pakbus_address: Integer – The PakBus address of the datalogger.

2-2

Section 2. SimplePB.DLL Reference

device_ type: Integer – The type of datalogger:

•1=CR200

•2=CR10XPB, CR23XPB, CR510PB

•3=CR1000

•4=CR3000

•5=CR800, CR850

return_data: Char – The location in memory where the data returned from the

datalogger exists.

return_data_len: Integer – Number of bytes in the data returned from the

datalogger.

Return Codes

0 = Successful.

-1 = Communication timed out.

-2 = Port is not open.

Example of data returned by function call

14:12:35 04/16/2004

2.6 SetClock()

Sets the date and time of the datalogger to match the PC clock.

Syntax

SetClock(pakbus_address, device_type, return_data, return_data_len)

Parameters

pakbus_address: Integer – The PakBus address of the datalogger.

device_type: Integer – The type of datalogger:

•1=CR200

•2=CR10XPB, CR23XPB, CR510PB

•3=CR1000

•4=CR3000

•5=CR800, CR850

2-3

Section 2. SimplePB.DLL Reference

return_data: Char – The location in memory where the data returned from the

datalogger exists.

return_data_len: Integer – Number of bytes in the data returned from the

datalogger.

Return Codes

0 = Successful.

-1 = Communication timed out.

-2 = Port is not open.

Example of data returned by function call

14:22:51 04/16/2004 (Old Time Old Date)

14:22:27 04/16/2004 (New Time New Date)

2.7 GetValue()

Query the datalogger for a value or group of values.

Syntax

GetValue(pakbus_address, device_type, swath, table_name, field_name,

return_data, return_data_len)

Parameters

pakbus_address: Integer – The PakBus address of the datalogger.

device_type: Integer –The type of datalogger:

•1=CR200

•2=CR10XPB, CR23XPB, CR510PB

•3=CR1000

•4=CR3000

•5=CR800, CR850

swath: Integer – The range within an indexed variable array to collect starting

at the location described in the field_name parameter. The requested swath

must be within the bounds of the indexed array or an error will occur.

table_name: String – The name of the table in the datalogger to collect.

field_name: String – The name of the field in the table where collection of

values should start.

return_data: Char – The location in memory where the data returned from the

datalogger exists.

2-4

Section 2. SimplePB.DLL Reference

return_data_len: Integer – Number of bytes in the data returned from the

datalogger.

Return Codes

0 = Successful.

-1 = Communication timed out.

-2 = Port is not open.

Example of data returned by function call

12.753,111.9,1.239 (Swath of 3 values from fields)

2.8 SetValue()

Set a value in the datalogger.

Syntax

SetValue(pakbus_address, device_type, table_name, field_name, value)

Parameters

pakbus_address: Integer – The PakBus address of the datalogger.

device_type: Integer – The type of datalogger:

•1=CR200

•2=CR10XPB, CR23XPB, CR510PB

•3=CR1000

•4=CR3000

•5=CR800, CR850

table_name: String – The name of the table in which the field will be set.

field_name: String – The field that will be set with the new value.

value: String – The value used to set the field.

Return Codes

0 = Successful.

-1 = Communication timed out.

-2 = Port is not open.

2-5

Section 2. SimplePB.DLL Reference

2.9 GetData()

Query the datalogger for column names and data from one of its tables.

Syntax

GetData(pakbus_address, device_type, table_no, record_no, return_data,

return_data_len)

Parameters

pakbus_address: Integer – The PakBus address of the datalogger.

device_type: Integer – The type of datalogger:

•1=CR200

•2=CR10XPB, CR23XPB, CR510PB

•3=CR1000

•4=CR3000

•5=CR800, CR850

table_no: Integer – The number of the table from which to collect data.

record_no: Integer – The record number where data collection will start. All

records following this record number will be included in the collection.

Therefore, if the record number is set to 0, all records in the table will be

collected. In addition, if the record number specified does not exist in the

datalogger, all existing records from the oldest to the newest will be returned.

However, if the record number is set to a negative number, only the most

recent record in the table will be collected. There is not a way to specify and

collect a single record from a table using this command unless that record is the

most recent record in the table.

return_data: Char – The location in memory where the data returned from the

datalogger exists.

return_data_len: Integer – Number of bytes in the data returned from the

datalogger.

Return Codes

0 = Successful.

1 = Success but more data to collect.

-1 = Communication timed out.

-2 = Port is not open.

2-6

Section 2. SimplePB.DLL Reference

Example of data returned by function call

"2004-04-16 14:18:03",1 (Time stamp, Record number)

1,OSversion,v03A (Field number, Field name, Field value)

2,OSDate,06-Jan-04

3,ProgName,BATT.CR2

4,ProgSig,54451

5,CalOffset,2.625

6,PakBusAddress,1

7,RfInstalled,424

8,RfNetAddr,0

9,RfAddress,0

10,RfHopSeq,0

11,RfPwrMode,RF1_Sec

12,Rf_ForceOn,0

13,RfSignalLevel,0

14,RfRxPakBusCnt,0

15,VarOutOfBounds,0

16,SkipScan,0

17,TrapCode,0

18,WatchDogCnt,0

19,ResetTables,0

20,BattVoltage,12.3943

2.10 GetDataHeader()

Query the datalogger for only the header information from one of its tables.

Syntax

GetData(pakbus_address, device_type, table_no, return_data, return_data_len)

Parameters

pakbus_address: Integer – The PakBus address of the datalogger.

device_type: Integer – The type of datalogger:

•1=CR200

•2=CR10XPB, CR23XPB, CR510PB

•3=CR1000

•4=CR3000

•5=CR800, CR850

table_no: Integer – The number of the table from which to collect data.

return_data: Char – The location in memory where the data returned from the

datalogger exists.

2-7

Section 2. SimplePB.DLL Reference

return_data_len: Integer – Number of bytes in the data returned from the

datalogger.

Return Codes

0 = Successful.

1 = Success but more data to collect.

-1 = Communication timed out.

-2 = Port is not open.

Example of data returned by function call

"TIMESTAMP","RECORD", OSVersion, OSDate, OSSignature

2.11 GetCommaData()

Query the datalogger for only the values of a record and display those values in

a comma-separated format.

Syntax

GetData(pakbus_address, device_type, table_no, record_no, return_data,

return_data_len)

Parameters

pakbus_address: Integer – The PakBus address of the datalogger.

device_type: Integer – The type of datalogger:

•1=CR200

•2=CR10XPB, CR23XPB, CR510PB

•3=CR1000

•4=CR3000

•5=CR800, CR850

table_no: Integer – The number for the table from which to collect data.