Campbell Scientific LoggerNet Server SDK User Manual
A
r
f
r
f
LoggerNet Server
Software Development Kit
Version 4.1
Programmer’s Reference
Revision: 12/11
Copyright © 2004-2011
Campbell Scientific, Inc.
ll rights reserved; no part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form o
by any means, electronics, mechanical, photocopying, recording, or otherwise without either the prior written permission o
the Publisher. This book may not be lent, resold, hired out or otherwise disposed of by way of trade in any form of binding o
cover other than that in which it is published, without the prior written consent of the Publisher. The programs in this manual
have been included for their instructional value. The Publisher does not offer any warranties or representations in respect o
their fitness for a particular purpose, nor does the Publisher accept any liability for any loss or damage arising from their use.
Campbell Scientific, Inc. Software SDK End User License Agreement (EULA)
NOTICE OF AGREEMENT: Please carefully read this EULA. By installing or
using this software, you are agreeing to comply with the terms and conditions
herein. If you do not want to be bound by this EULA, you must promptly
return the software, any copies, and accompanying documentation in its
original packaging to Campbell Scientific or its representative.
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 LoggerNet Server SDK or make changes to one or
more components of other software on which the LoggerNet Server 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.
This LoggerNet Server Software Development Kit software is hereinafter
referred to as the LoggerNet Server SDK. The term "developer" herein refers to
anyone using this LoggerNet Server SDK.
LICENSE FOR USE: Campbell Scientific grants you a non-exclusive, nontransferable, royalty-free license to use this software in accordance with the
following:
1) The purchase of this software allows you to install and use the software on
one computer only.
2) This software cannot be loaded on a network server for the purposes of
distribution or for access to the software by multiple operators. If the
software can be used from any computer other than the computer on which
it is installed, you must license a copy of the software for each additional
computer from which the software may be accessed.
3) If this copy of the software is an upgrade from a previous version, you
must possess a valid license for the earlier version of software. You may
continue to use the earlier copy of software only if the upgrade copy and
earlier version are installed and used on the same computer. The earlier
version of software may not be installed and used on a separate computer
or transferred to another party.
4) This software package is licensed as a single product. Its component parts
may not be separated for use on more than one computer.
5) You may make one (1) backup copy of this software onto media similar to
the original distribution, to protect your investment in the software in case
of damage or loss. This backup copy can be used only to replace an
unusable copy of the original installation media.
6) You may not use Campbell Scientific’s name, trademarks, or service
marks in connection with any program you develop with the LoggerNet
Server SDK. You may not state or infer in any way that Campbell
Scientific endorses any program you develop, unless prior written
approval is received from Campbell Scientific.
7) If the software program you develop requires you, your customer, or a
third party to use additional licensable software from Campbell Scientific,
that software must be purchased from Campbell Scientific or its
representative under the terms of its separate EULA.
8) This license allows you to redistribute the ActiveX (dll) controls and the
communication DLL with the software developed using the LoggerNet
Server SDK. No other Campbell Scientific examples, documentation, or
source code may be distributed with your application.
9) The LoggerNet Server SDK may not be used to develop and publicly sell
or distribute any product that directly competes with Campbell Scientific’s
datalogger support software.
10) 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.
The ActiveX® controls provided with this LoggerNet Server SDK
("LoggerNet Server SDK Controls") include the files: CsiBrokerMap.dll,
CsiCoraScript.dll, CsiDatalogger.dll, CsiDataSource.dll, CsiLogMonitor.dll
and CsiServer.dll. In addition, the LoggerNet server DLL, CORALIB3.DLL,
is included with the LoggerNet Server SDK.
RELATIONSHIP: Campbell Scientific, Inc. hereby grants a license to use
LoggerNet Server SDK Controls 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 LoggerNet Server SDK controls to create as many
applications as desired and freely distribute those applications. Campbell
Scientific, Inc. expects no royalties or any other compensation outside of the
LoggerNet Server SDK purchase price. Developer is responsible for
supporting applications created using the LoggerNet Server SDK Controls.
RESPONSIBILITIES OF DEVELOPER
The Developer agrees:
• To provide a competent programmer familiar with Campbell Scientific,
Inc. datalogger programming and software to write the applications.
• Not to sell or distribute documentation on use of LoggerNet Server SDK
Controls.
• Not to sell or distribute the applications that are provided as examples in
the LoggerNet Server SDK.
• To develop original works. Developers may copy and paste portions of the
code into their own applications, but their applications are expected to be
unique creations.
• Not to sell or distribute applications that compete directly with any
application developed by Campbell Scientific, Inc. or its affiliates.
• To assure that each application developed with LoggerNet Server SDK
Controls 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.
WARRANTIES: 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.
There is no written or implied warranty provided with the LoggerNet Server
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
LoggerNet Server 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 LoggerNet Server 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
LoggerNet Server SDK Controls in any applications developed or distributed
by Developer. CSI shall refund 1/2 of the purchase price within 30 days of
receipt of the materials. In the absence of such return, CSI shall consider
developer in agreement with the herein stated license terms and conditions.
COPYRIGHT: This software is protected by United States copyright law and
international copyright treaty provisions. This software may not be altered in
any way without prior written permission from Campbell Scientific. All
copyright notices and labeling must be left intact.
LoggerNet Server Software
Development Kit 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. LoggerNet Server SDK Overview ............................1-1
1.1 Purpose of the LoggerNet Server SDK................................................. 1-1
1.2 Requirements ........................................................................................ 1-1
1.2.1 Required Campbell Scientific, Inc. Software.............................. 1-1
1.2.2 Development Tools Requirements.............................................. 1-1
1.3 Included Components ........................................................................... 1-2
1.3.1 Files Included in the LoggerNet Server SDK ............................. 1-2
1.3.1.1 ActiveX® Controls (DLLs)............................................... 1-2
1.3.1.2 LoggerNet Server (CORALIB3.DLL)............................... 1-2
1.3.1.3 Manuals ............................................................................. 1-2
1.3.1.4 Example Projects............................................................... 1-2
1.3.2 Adding Controls to a Project....................................................... 1-2
1.3.2.1 Adding a Control to a Visual Basic Project....................... 1-3
1.3.2.2 Adding a Control to a Delphi Project ................................ 1-3
1.3.2.3 Adding a Control to a .NET Project .................................. 1-4
2. CsiServer Control .....................................................2-1
2.1 Purpose of the CsiServer Control ......................................................... 2-1
2.2 CsiServer Interface ............................................................................... 2-1
2.2.1 Properties .................................................................................... 2-2
2.2.2 Methods....................................................................................... 2-2
2.2.3 Events.......................................................................................... 2-2
3. Developing an Application Using the CsiServer
Control....................................................................3-1
3.1 Purpose ................................................................................................. 3-1
3.2 Using the CsiServer Control................................................................. 3-1
3.2.1 Getting Started with the CsiServer Control................................. 3-1
3.2.2 CsiServer Control Application Example..................................... 3-2
4. CsiCoraScript Control ..............................................4-1
4.1 Purpose of the CsiCoraScript Control................................................... 4-1
4.2 Connecting to the Server....................................................................... 4-1
4.3 Using CoraScript Commands ............................................................... 4-1
4.3.1 Setting up a Network................................................................... 4-2
4.3.2 Real-Time Data Display.............................................................. 4-2
4.3.2.1 Table-Data Dataloggers..................................................... 4-3
4.3.2.2 Mixed-Array Dataloggers.................................................. 4-3
i
LoggerNet Software Development Kit Table of Contents
4.4 CsiCoraScript Interface......................................................................... 4-4
4.4.1 Properties..................................................................................... 4-4
4.4.2 Methods....................................................................................... 4-4
4.4.3 Events.......................................................................................... 4-4
5. Developing an Application Using the
CsiCoraScript Control .......................................... 5-1
5.1 Purpose.................................................................................................. 5-1
5.2 Using the CsiCoraScript Control...........................................................5-1
5.2.1 Getting Started with the CsiCoraScript Control ..........................5-1
5.2.2 CsiCoraScript Control Application Example .............................. 5-2
6. CsiBrokerMap Control............................................. 6-1
6.1 Purpose of the CsiBrokerMap Control.................................................. 6-1
6.2 Connecting to the LoggerNet Server..................................................... 6-1
6.3 How Collections Work.......................................................................... 6-2
6.3.1 Visual Basic View of Collections................................................6-2
6.3.1.1 Accessing Collections with For Each ................................6-2
6.3.1.2 Accessing Collections with Indexes and Names................6-2
6.3.2 Delphi/Visual C++ View of Collections ..................................... 6-2
6.4 CsiBrokerMap Interfaces ...................................................................... 6-3
6.4.1 BrokerMap Interface ................................................................... 6-3
6.4.1.1 Properties........................................................................... 6-3
6.4.1.2 Methods .............................................................................6-3
6.4.1.3 Events ................................................................................ 6-3
6.4.2 BrokerCollection Interface.......................................................... 6-3
6.4.2.1 Properties........................................................................... 6-3
6.4.2.2 Methods .............................................................................6-4
6.4.3 Broker Interface........................................................................... 6-4
6.4.3.1 Properties........................................................................... 6-4
6.4.3.2 Methods .............................................................................6-4
6.4.4 Table Collection Interface........................................................... 6-4
6.4.4.1 Properties........................................................................... 6-4
6.4.4.2 Methods .............................................................................6-4
6.4.5 Table Interface............................................................................. 6-4
6.4.5.1 Properties........................................................................... 6-4
6.4.5.2 Methods .............................................................................6-4
6.4.6 ColumnCollection Interface ........................................................6-5
6.4.6.1 Properties........................................................................... 6-5
6.4.6.2 Methods .............................................................................6-5
6.4.7 Column Interface......................................................................... 6-5
6.4.7.1 Properties........................................................................... 6-5
7. Developing an Application Using the
CsiBrokerMap Control.......................................... 7-1
7.1 Purpose.................................................................................................. 7-1
7.2 Using the CsiBrokerMap Control .........................................................7-1
7.2.1 Getting Started with the CsiBrokerMap Control......................... 7-1
7.2.2 CsiBrokerMap Control Application Example ............................. 7-2
ii
LoggerNet Software Development Kit Table of Contents
8. CsiDatalogger ...........................................................8-1
8.1 Purpose of the CsiDatalogger Control.................................................. 8-1
8.2 Connecting to the Server....................................................................... 8-1
8.3 Datalogger Interface ............................................................................. 8-1
8.3.1 Properties .................................................................................... 8-1
8.3.2 Methods....................................................................................... 8-2
8.3.3 Events.......................................................................................... 8-2
9. Developing an Application Using the
Datalogger Control ................................................9-1
9.1 Purpose ................................................................................................. 9-1
9.2 Using the CsiDatalogger Control.......................................................... 9-1
9.2.1 Getting Started with the CsiDatalogger Control ......................... 9-1
9.2.2 CsiDatalogger Control Application Example.............................. 9-2
10. CsiDataSource Control ........................................10-1
10.1 Purpose of the CsiDataSource Control ............................................. 10-1
10.2 Connecting to the Server................................................................... 10-1
10.3 CsiDataSource Interfaces.................................................................. 10-2
10.3.1 Dsource Interface .................................................................... 10-2
10.3.1.1 Properties....................................................................... 10-2
10.3.1.2 Methods......................................................................... 10-2
10.3.1.3 Events ............................................................................ 10-2
10.3.2 Advisor Interface..................................................................... 10-2
10.3.2.1 Properties....................................................................... 10-3
10.3.2.2 Methods......................................................................... 10-3
10.3.3 DataColumnCollection Interface............................................. 10-3
10.3.3.1 Properties....................................................................... 10-3
10.3.3.2 Methods......................................................................... 10-3
10.3.4 DataColumn Interface ............................................................. 10-3
10.3.4.1 Properties....................................................................... 10-3
10.3.5 Record..................................................................................... 10-4
10.3.5.1 Properties....................................................................... 10-4
10.3.5.2 Methods......................................................................... 10-4
10.3.6 RecordCollection .................................................................... 10-4
10.3.6.1 Properties....................................................................... 10-4
10.3.6.2 Methods.......................................................................... 10-4
10.3.7 Value Interface........................................................................ 10-4
10.3.7.1 Properties....................................................................... 10-4
11. Developing an Application Using the
CsiDataSource Control.....................................11-1
11.1 Purpose ............................................................................................. 11-1
11.2 Using the CsiDataSource Control..................................................... 11-1
11.2.1 Getting Started with the CsiDataSource Control..................... 11-1
11.2.2 CsiDataSource Control Application Example......................... 11-2
iii
LoggerNet Software Development Kit Table of Contents
12. CsiLogMonitor Control........................................ 12-1
12.1 Purpose of the CsiLogMonitor Control............................................. 12-1
12.2 CsiLogMonitor Interface................................................................... 12-2
12.2.1 Properties................................................................................. 12-2
12.2.2 Methods................................................................................... 12-2
12.2.3 Events...................................................................................... 12-2
13. Developing an Application Using the
CsiLogMonitor Control .................................... 13-1
13.1 Purpose.............................................................................................. 13-1
13.2 Using the CsiLogMonitor Control .................................................... 13-1
13.2.1 Getting Started with the CsiLogMonitor Control.................... 13-1
13.2.2 CsiLogMonitor Control Application Example ......................... 13-2
14. CsiServer Control Reference .............................. 14-1
14.1 Server Interface................................................................................. 14-1
14.1.1 Properties................................................................................. 14-1
14.1.2 Methods................................................................................... 14-4
14.1.3 Events...................................................................................... 14-5
15. CsiCoraScript Control Reference....................... 15-1
15.1 CoraScript Interface .......................................................................... 15-1
15.1.1 Properties................................................................................. 15-1
15.1.2 Methods................................................................................... 15-3
15.1.3 Events...................................................................................... 15-4
16. CsiBrokerMap Control Reference ...................... 16-1
16.1 BrokerMap Interface......................................................................... 16-1
16.1.1 Properties................................................................................. 16-1
16.1.2 Methods................................................................................... 16-4
16.1.3 Events...................................................................................... 16-5
16.2 BrokerCollection Interface................................................................ 16-7
16.2.1 Properties................................................................................. 16-7
16.2.2 Methods................................................................................... 16-8
16.3 Broker Interface ................................................................................16-9
16.3.1 Properties................................................................................. 16-9
16.3.2 Methods................................................................................. 16-11
16.4 TableCollection Interface................................................................ 16-12
16.4.1 Properties............................................................................... 16-12
16.4.2 Methods................................................................................. 16-12
16.5 Table Interface ................................................................................ 16-14
16.5.1 Properties............................................................................... 16-14
16.5.2 Methods................................................................................. 16-15
16.6 ColumnCollection Interface............................................................ 16-16
16.6.1 Properties............................................................................... 16-16
16.6.2 Methods................................................................................. 16-16
16.7 Column Interface............................................................................. 16-18
16.7.1 Properties............................................................................... 16-18
iv
LoggerNet Software Development Kit Table of Contents
17. CsiDatalogger Control Reference .......................17-1
17.1 Datalogger Interface ......................................................................... 17-1
17.1.1 Properties ................................................................................ 17-1
17.1.2 Methods................................................................................... 17-6
17.1.3 Events.................................................................................... 17-13
18. CsiDataSource Control Reference ......................18-1
18.1 DSource Interface ............................................................................. 18-1
18.1.1 Properties ................................................................................ 18-1
18.1.2 Methods................................................................................... 18-4
18.1.3 Events...................................................................................... 18-5
18.2 Advisor Interface ............................................................................ 18-11
18.2.1 Properties .............................................................................. 18-11
18.2.2 Methods................................................................................. 18-19
18.3 DataColumnCollection Interface .................................................... 18-22
18.3.1 Properties .............................................................................. 18-22
18.3.2 Methods................................................................................. 18-22
18.4 DataColumn Interface..................................................................... 18-25
18.4.1 Properties .............................................................................. 18-25
18.5 Record Interface.............................................................................. 18-25
18.5.1 Properties .............................................................................. 18-25
18.5.2 Methods................................................................................. 18-27
18.6 RecordCollection ............................................................................ 18-29
18.6.1 Properties .............................................................................. 18-29
18.6.2 Methods................................................................................. 18-29
18.7 Value Interface................................................................................ 18-30
18.7.1 Properties .............................................................................. 18-30
19. CsiLogMonitor Control Reference ......................19-1
19.1 LogMonitor Interface........................................................................ 19-1
19.1.1 Properties ................................................................................ 19-1
19.1.2 Methods................................................................................... 19-5
19.1.3 Events...................................................................................... 19-8
Appendix
A. Server and Device Operational Statistics Tables. A-1
A.1 Device History Statistics..................................................................... A-1
A.1.1 Attempts.................................................................................... A-1
A.1.2 Failures...................................................................................... A-1
A.1.3 Retries ....................................................................................... A-1
A.2 Device Standard Statistics................................................................... A-2
A.2.1 Communication Enabled........................................................... A-2
A.2.2 Average Error Rate.................................................................... A-2
A.2.3 Total Retries.............................................................................. A-2
A.2.4 Total Failures ............................................................................ A-2
A.2.5 Total Attempts........................................................................... A-2
A.2.6 Communication Status .............................................................. A-3
A.2.7 Last Clock Check ...................................................................... A-3
A.2.8 Last Clock Set ........................................................................... A-3
A.2.9 Last Clock Difference ............................................................... A-3
v
LoggerNet Software Development Kit Table of Contents
A.2.10 Collection Enabled .................................................................. A-4
A.2.11 Last Data Collection................................................................ A-4
A.2.12 Next Data Collection ............................................................... A-4
A.2.13 Last Collect Attempt................................................................ A-4
A.2.14 Collection State ....................................................................... A-4
A.2.15 Values in Last Collection ........................................................A-5
A.2.16 Values to Collect ..................................................................... A-5
A.2.17 Values in Holes........................................................................ A-5
A.2.18 Values in Uncollectable Holes ................................................ A-6
A.2.19 Line State................................................................................. A-6
A.2.20 Polling Active.......................................................................... A-7
A.2.21 FS1 to Collect.......................................................................... A-7
A.2.22 FS1 Collected ........................................................................... A-7
A.2.23 FS2 to Collect.......................................................................... A-7
A.2.24 FS2 Collected .......................................................................... A-7
A.2.25 Logger Ver ..............................................................................A-7
A.2.26 Watchdog Err........................................................................... A-8
A.2.27 Prog Overrun ........................................................................... A-8
A.2.28 Mem Code ............................................................................... A-8
A.2.29 Collect Retries ......................................................................... A-8
A.2.30 Low Voltage Stopped Count ................................................... A-8
A.2.31 Low Five Volts Error Count.................................................... A-9
A.2.32 Lithium Battery Voltage.......................................................... A-9
A.2.33 Table Definitions State............................................................ A-9
A.3 Server Statistics................................................................................... A-9
A.3.1 Disc Space Available............................................................... A-10
A.3.2 Available Virtual Memory....................................................... A-10
A.3.3 Used Virtual Memory.............................................................. A-10
Figures
Tables
3-1 CsiServer Example ...............................................................................3-2
5-1 CsiCoraScript Example.........................................................................5-2
7-1 CsiBrokerMap Example .......................................................................7-2
9-1 CsiDatalogger Example........................................................................ 9-2
11-1 CsiDataSource Example ................................................................... 11-2
13-1 CsiLogMonitor Example .................................................................. 13-2
1-1. Supported Development Tools ............................................................ 1-1
vi
Section 1. LoggerNet Server SDK Overview
1.1 Purpose of the LoggerNet Server SDK
The LoggerNet Server Software Development Kit (SDK) provides a method to
communicate with a datalogger network through ActiveX
controls provide an abstraction to the server messaging and datalogger
communication protocols. Together these controls encapsulate all of the
messaging between client applications and the LoggerNet server whether the
client resides on a local machine or accesses the LoggerNet server over a
network.
Without these controls, creating custom client applications that communicate
with Campbell Scientific dataloggers would require an implementation of all
the protocol details when sending messages to dataloggers and reading
messages from dataloggers. By using the SDK, developers not only reduce
development time but also insulate their application from future changes with
datalogger communication protocols.
1.2 Requirements
1.2.1 Required Campbell Scientific, Inc. Software
SDK communication requires access to a functioning LoggerNet server. Client
applications use the SDK controls to create connections with dataloggers
through the LoggerNet server DLL. This version of the SDK still allows the
creation of custom software applications that can communicate to an existing
installation of LoggerNet. Alternately, custom software can be created that
starts, stops, and communicates through the included LoggerNet server DLL
(CORALIB3.DLL). The SDK controls communicate with CSI dataloggers
using LoggerNet server version 1.1 or higher.
®
controls. These
1.2.2 Development Tools Requirements
The SDK's ActiveX® controls have been tested with the following
development tools for Microsoft Windows:
TABLE 1-1. Supported Development Tools
Development Tool Examples Available
Visual Basic 6.0 Yes
Delphi 2007 Yes
Visual C++ VS-2010 MFC Yes
C#.NET Yes
VB.NET Yes
1-1
Section 1. LoggerNet Server SDK Overview
NOTE
The C#.NET and VB.NET example code targets the x86
compilation platform to facilitate proper functionality on 64-bit
versions of Windows
platforms should use this compiler directive, since the ActiveX
controls in the SDK must run in a 32-bit process on 64-bit
machines to work properly.
1.3 Included Components
1.3.1 Files Included in the LoggerNet Server SDK
The files included with the LoggerNet Server SDK installation are: ActiveX ®
SDK controls, the LoggerNet server DLL, working examples for several
development controls, licensing information, and the SDK Beginner’s Guide
and Programmer’s Reference. Please note that although simple examples are
provide for reference, the SDK does not contain a complete user interface
software package for creating connections and manipulating data within
datalogger networks. The SDK merely provides all the controls necessary for
development of the user interface software.
1.3.1.1 ActiveX® Controls (DLLs)
The six included ActiveX controls are DLL files that are registered and must
be added to your project. For help adding these controls to your project, see
the next section "Adding the Controls to a Project".
®
. Any new projects created on 64-bit
®
1.3.1.2 LoggerNet Server (CORALIB3.DLL)
The LoggerNet server DLL available in the installed Controls folder can be
started, stopped, and accessed with the included ActiveX Controls. This DLL
does not need to be registered but must be placed in the application folder, in
the PATH environmental variable, or in the Windows system directory.
1.3.1.3 Manuals
The SDK Beginner’s Guide contains information comparing available
Campbell Scientific SDK products. The LoggerNet Server SDK Programmer’s
Reference contains detailed information regarding the use of the LoggerNet
Server SDK. Both manuals are in PDF format.
1.3.1.4 Example Projects
Example projects are included with the SDK. These projects collectively use
all of the controls to demonstrate simple functionality. The example projects
have been written in various development environments.
1.3.2 Adding Controls to a Project
This section describes how to add controls to a project in Visual Basic 6.0,
Delphi, or .NET. Before trying to add any of the SDK controls to your
development project, make sure that the installation program has installed all of
1-2
Section 1. LoggerNet Server SDK Overview
the controls. The standard installation program will register the SDK control
DLLs.
1.3.2.1 Adding a Control to a Visual Basic Project
1. Start Visual Basic.
2. Create a new project (
your choice. "Standard EXE" would be a good choice.
3. Add "Components" to your project (
Check the controls that you would like to add to the project and click
"OK".
4. Select a control on the toolbar by clicking it and draw the control onto the
form by clicking and dragging (creating a rectangle or square).
File -> New Project ) and select the project of
1.3.2.2 Adding a Control to a Delphi Project
1. Start Delphi.
2. Delphi
3. Select a SDK component (e.g., CsiBrokerMap 1.0 Type Library (Version
4. Select the tab Into New Package in the Install window and click on the
Main menu -> Component -> Import ActiveX Control…
1.0)) from the Import Active X window and click on the Install button.
Browse button. Locate the directory where you would like this new
package to reside and assign a name to this new package, e.g.,
CsiBrokerMap. Click on OK button.
Project -> Components...).
1-3
Section 1. LoggerNet Server SDK Overview
5. A confirmation message similar to one below will appear. Click on Yes.
6. A new window titled Information (not shown) will appear informing you
that the package has been installed.
7. Finally you will be asked to save the changes. Click on Yes.
8. Follow the same procedure to obtain the other two ActiveX controls as
icons on the ActiveX palette in Delphi.
1.3.2.3 Adding a Control to a .NET Project
ActiveX controls are imported using the COM Interop wrapper capability in
the .NET development environment. This importing should happen
automatically when the ActiveX DLL is referenced in the project.
1. From the Project menu item choose "Add Reference".
2. Find and select the SDK component to import (e.g. CsiBrokerMap 1.0
Type Library) under the COM tab.
3. Add the component to the project form.
1-4
Section 2. CsiServer Control
2.1 Purpose of the CsiServer Control
The CsiServer Control allows the user to start and stop the included,
LoggerNet server DLL (CORALIB3.DLL). All SDK controls must connect to
and use a LoggerNet server to communicate with Campbell Scientific
dataloggers. Therefore, a LoggerNet server must be running on the network
before the included examples or any custom SDK software will function.
Campbell Scientific sells a complete LoggerNet software package that includes
the LoggerNet server and many complex software clients. This version of
LoggerNet may already be installed and in use on the network where the
custom SDK application will reside. If the LoggerNet software is already
installed and running on the network, it is not necessary to use the CsiServer
control to start another LoggerNet server. However, if a separate version of
LoggerNet has not been started or installed on the network, use the CsiServer
control to start the included CORALIB3.DLL. The included CORALIB3.DLL
must be located in the same folder as the created application, the PATH
environmental variable, or in the Windows system directory before it can be
started.
All of the configuration information and data for the datalogger network will
be stored in the LoggerNet working directory described in the CsiServer
control properties. Only one LoggerNet server at a time can use the network
configuration information contained in the working directory. If a previous
installation of LoggerNet created the network map and configuration
information, the LoggerNet server included in the SDK can point to and use
this configuration information. However, avoid file conflict issues by making
sure only one LoggerNet server accesses the same working directory at a time.
Careful consideration should be given before beginning a project using the
SDK. Consider the type of software application needed. Many developers
merely want to create custom software interfaces that extend a previous
installation of LoggerNet. The CsiServer control won’t be needed for this type
of application. However, if you are interested in creating a complete software
solution that will replace or be used instead of Campbell Scientific’s
LoggerNet software package, make sure a LoggerNet server is not running and
then start the included LoggerNet server DLL with the CsiServer control.
Moreover, an understanding of CoraScript commands, which are discussed in
the next section, is required to set up and manipulate the datalogger network.
2.2 CsiServer Interface
See the Reference section in this manual for detailed descriptions of these
properties, methods, and events.
2-1
Section 2. CsiServer Control
2.2.1 Properties
2.2.2 Methods
2.2.3 Events
• applicationWorkDir As String
• buildDate As String (read-only)
• logFileDir As String
• serverStarted As Boolean (read-only)
• serverVersion As String (read-only)
• serverWorkDir As String (Required)
• tcpPort As Integer
• tcpPortEx As Long
• startServer()
• stopServer()
• onServerFailure(String Reason)
2-2
Section 3. Developing an Application Using the CsiServer Control
3.1 Purpose
This section shows by example how to build an application using the SDK
CsiServer control. The application’s functions are:
1. Start the LoggerNet server (CORALIB3.DLL).
2. Stop the LoggerNet server (CORALIB3.DLL).
3.2 Using the CsiServer Control
3.2.1 Getting Started with the CsiServer Control
The CsiServer SDK control (an ActiveX object) starts and stops the LoggerNet
server (CORALIB3.DLL).
This example assumes that:
• you have registered the CsiServer control correctly
• you will develop the application with Visual Basic 6.0
• the CORALIB3.DLL exists in the folder with the created application, the
PATH environmental variable, or the Windows system directory
• both the CORALIB3.DLL and application you are developing reside on
the same computer
Complete the following steps first:
1. Start Visual Basic 6.0 (Start | Programs | Microsoft Visual Basic 6.0 |
Microsoft Visual Basic 6)
2. Start a new project (File | New Project | Standard EXE | OK) opening a
new, blank form.
3. View the toolbox for this new project (VB 6 Main Menu | View |
Toolbox).
4. Right click on the toolbox area and select Components. A component
window will open and the following SDK controls will appear within the
list if they are registered properly:
CsiBrokerMap 1.0 Type Library
CsiCoraScript 1.0 Type Library
CsiDatalogger 1.0 Type Library
CsiDataSource 1.0 Type Library
3-1
Section 3. Developing an Application Using the CsiServer Control
CsiLogMonitor 1.0 Type Library
CsiServer 1.0 Type Library
Check the box next to the CsiServer 1.0 Type Library, click Apply, and then
close the window. Now an icon for the CsiServer control and other common
controls will appear in the toolbox.
3.2.2 CsiServer Control Application Example
Begin creating an application that will start and stop the LoggerNet server. An
example of a user interface that accomplishes this task is shown in Figure 3-1.
This interface includes the CsiServer control and other objects on the form to
create a functional application that will start and stop the LoggerNet server.
FIGURE 3-1. CsiServer Example
Now that the interface has been designed, the code can be organized to
accomplish the requirements of the application. Initially, the one required
parameter, serverWorkDir, must be set and then the startServer() method can
be called to start the LoggerNet server. A basic example of code used to start
the LoggerNet server is listed in the table below:
Private Sub cmdStart_Click()
'Set the required properties for the LoggerNet Server
CsiServer.serverWorkDir = "c:\campbellsci\loggernet\sys\bin"
'Start the LoggerNet Server
If CsiServer.serverStarted Then
txtServer.Text = "Server Already Started"
Else
CsiServer.startServer
txtServer.Text = "Server Started"
cmdStart.Enabled = False
cmdStop.Enabled = True
End If
End Sub
3-2
Section 3. Developing an Application Using the CsiServer Control
In order to stop the LoggerNet server, use the method stopServer(). A basic
example of code used to stop the LoggerNet server is found in the following
table:
Private Sub cmdStop_Click()
'Stop the LoggerNet Server
If CsiServer.serverStarted Then
CsiServer.stopServer
txtServer.Text = "Server Stopped"
cmdStop.Enabled = False
cmdStart.Enabled = True
Else
txtServer.Text = "Server Already Stopped"
End If
End Sub
Add additional functionality and objects as necessary to meet the specific
requirements of your application. Complete examples using the CsiServer
control are included with the LoggerNet Server SDK installation.
3-3
Section 3. Developing an Application Using the CsiServer Control
3-4
Section 4. CsiCoraScript Control
4.1 Purpose of the CsiCoraScript Control
The CsiCoraScript control provides the power to administer the LoggerNet
server. There are many different settings and commands available with this
control.
Specific LoggerNet server functions and tasks are set by passing CoraScript
commands to the LoggerNet server. CoraScript commands execute LoggerNet
server operations that include adding devices to the network map, data
collection, listing table and datalogger information, and changing settings in
the LoggerNet server and attached devices. CoraScript commands and their
purposes can be found in the Quick Reference help file installed with the
LoggerNet Server SDK.
NOTE
The following CoraScript commands are currently unsupported
in the SDK: connect, disconnect, help, exit, bye, quit, and listcommands.
4.2 Connecting to the Server
There are two basic actions required for this control to connect to the
LoggerNet server:
1. Set server properties:
• serverName - The name or IP address of the LoggerNet server . The
default value is
• serverPort - The port on which the LoggerNet server is running. The
default value is 6789.
• serverLogonName (Optional) - If security has been enabled on the
server, a valid logon name is required.
• serverLogonPassword (Optional) - If security has been enabled on the
server, a valid password that corresponds with a valid logon name is
required.
localhost.
2. Invoke the
serverConnect() method.
4.3 Using CoraScript Commands
CoraScript commands are used to setup and manipulate the LoggerNet server.
A complete listing of these commands can be found in the LoggerNet Server
SDK Quick Reference. A thorough knowledge of these powerful commands is
recommended before attempting to make changes to settings or devices in the
LoggerNet server. The following sections outline some basic commands that
can be used to quickly set up devices and collect data from the network.
4-1
Section 4. CsiCoraScript Control
4.3.1 Setting up a Network
Some of the commands that can be used when initially setting up a datalogger
network on the LoggerNet server include:
• add-device – used to add root ports, dataloggers, and telecommunication
devices to the network map.
• set-device-setting – used to change settings of specific devices in the
network map.
• delete-branch – used to remove a device and any children of a device from
the network map.
• list-devices – shows the devices in the network map
The following example shows the basic CoraScript commands used to set up a
CR10X connected directly to the LoggerNet server via RS232:
add-device com-port COM1 as-child “”;
add-device cr10x CR10X as-child “COM1”;
The following example shows basic CoraScript commands used to set up a
CR9000 connected to the LoggerNet server via Ethernet:
add-device tcp-com-port IPPort as-child “”;
set-device-setting IPPort 5 192.168.1.1:6781;
add-device cr9000 CR9000 as-child “IPPort”;
4.3.2 Real-Time Data Display
Some developers want to display data values as quickly as they change in the
datalogger. Each time a datalogger program executes, new values are written
as input locations. Collecting these input locations provides a snapshot of the
most recent values contained in the datalogger. The DataSource control of the
SDK can be used to set up an advisor that will watch the LoggerNet data cache
and display new or existing data values that are collected. CoraScript
commands are used to set up the collect areas of LoggerNet and to enable
scheduled collection of specific datalogger tables to automate the collection
process.
Please note that although the commands below will enable collection of input
locations from a datalogger, using input locations for real-time comparison of
values can be problematic. When input locations are collected, the collection is
merely a snapshot of the current values that exist in each location. If, for
example, the datalogger program has not completely executed, some of the
values collected may be new while other values may have not changed from
the previous program execution. Please keep this information in mind if input
locations are used in real-time data display or calculations. If correlating
values are necessary, a better approach writes values to Final Storage every
program execution and collects those values as quickly as possible.
4-2
4.3.2.1 Table-Data Dataloggers
The LoggerNet server, by default, creates a collect area for the Public or
InLocs table of table-data dataloggers such as the CR9000 or CR10X-TD. The
basic CoraScript commands that are used to enable collection and establish
scheduled collection are:
set-collect-area-setting – used to enable a device for collection
•
•
set-device-setting – used to activate scheduled collection for a device
If you have added a CR9000 to the datalogger network and you have a program
running on that device, the following command will enable the public table for
collection by activating the collect-area-setting scheduleEnabled (id = 2):
set-collect-area-setting CR9000 public 2 1;
Every time a manual poll or any other collection occurs, data will be collected
for the public table of the CR9000. If a DataSource advisor has been created, it
will trigger and display the new values. If you want to automate the data
collection process, set the device's scheduled collection interval through the
device setting collectSched (id = 5):
Section 4. CsiCoraScript Control
set-device-setting CR9000 5 {1 19900101 300000 120000 3 86400000};
With the above setting, the LoggerNet server will automatically collect all
tables enabled for collection from the CR9000 every 300000 milliseconds.
Once this setting is in place, the activated DataSource advisor will display
updates as they are automatically collected.
4.3.2.2 Mixed-Array Dataloggers
Although the DataSource control can create a temporary data cache to watch
all input locations, mixed-array dataloggers, like the CR7 and CR10X, require
additional commands to create a permanent collect area for input locations.
Input Locations (InLocs) contain values that are usually stored every time the
program executes. However, the LoggerNet server does not create a permanent
data cache by default containing data from InLocs for a mixed-array
datalogger. If a permanent collect area for InLocs is desired or only specific
InLocs are needed, the collect area must be created manually in the LoggerNet
server. The following commands are used to set up a permanent InLocs collect
area for a mixed-array datalogger:
create-inlocs-area – create a collect area containing specified input
•
locations
set-collect-area-setting – used to enable a device for collection
•
•
set-device-setting – used to activate scheduled collection for a device
The following example sets up collection for two input locations of a CR10X
by identifying the station, declaring a name for the collect area, and listing the
input locations to include:
create-inlocs-area CR10X InLocsArea {1 "inlocs1"} {2 {inlocs2}};
4-3
Section 4. CsiCoraScript Control
Collect area names must always be unique. Therefore, if an attempt is made to
create a collect area with exactly the same name as a collect area that already
exists, the LoggerNet server will automatically index the name of the collect
area being created. For example, if collect area InLocsArea already exists and
an attempt is made to create another collect area with the same name, the
LoggerNet server will automatically name the new collect area InLocsArea1.
To activate a collect area for collection and to automate the collection process
use the following commands:
set-collect-area-setting CR10X InLocsArea 2 1;
set-device-setting CR10X 5 {1 19900101 300000 120000 3 86400000};
With the above setting, the LoggerNet server will automatically collect all
tables enabled for collection from the CR10X every 300000 milliseconds.
Once this setting is in place, the activated DataSource advisor will display new
data values as they are collected.
4.4 CsiCoraScript Interface
See the Reference section for descriptions of these properties, methods, and
events.
4.4.1 Properties
4.4.2 Methods
4.4.3 Events
• serverConnected As Boolean (read-only)
• serverLogonName As String
• serverLogonPassword As String
• serverName As String
• serverPort As Long
• executeScript(String script, Long asyncID) As String
• serverConnect()
• serverDisconnect()
• onScriptComplete(Long asyncID, String result)
• onServerConnectStarted()
• onServerConnectFailure(server_failure_type server_failure)
4-4
Section 5. Developing an Application Using the CsiCoraScript Control
5.1 Purpose
This section shows an example of how to build an application using the
CsiCoraScript control. The application’s functions are:
1. Connect to a running LoggerNet server
2. Execute CoraScript commands to administer the LoggerNet server.
5.2 Using the CsiCoraScript Control
5.2.1 Getting Started with the CsiCoraScript Control
The CsiCoraScript SDK control (an ActiveX object) administers the datalogger
network by passing CoraScript commands to the LoggerNet server.
This example assumes that:
• you have registered the CsiCoraScript control correctly
• you are developing the application in Visual Basic 6.0
• a LoggerNet server is running and accessible on the network
Complete the following steps first:
1. Start Visual Basic 6.0 (Start | Programs | Microsoft Visual Basic 6.0 |
Microsoft Visual Basic 6)
2. Start a new project (File | New Project | Standard EXE | OK) opening a
new, blank form.
3. View the toolbox for this new project (VB 6 Main Menu | View |
Toolbox).
4. Right click on the toolbox area and select Components. A component
window will open and the following SDK controls will appear within the
list if they are registered properly:
CsiBrokerMap 1.0 Type Library
CsiCoraScript 1.0 Type Library
CsiDatalogger 1.0 Type Library
CsiDataSource 1.0 Type Library
CsiLogMonitor 1.0 Type Library
CsiServer 1.0 Type Library
5-1
Section 5. Developing an Application Using the CsiCoraScript Control
Check the box next to the CsiCoraScript 1.0 Type Library, click Apply, and
then close the window. Now an icon for the CsiCoraScript control and other
common controls will appear in the toolbox.
5.2.2 CsiCoraScript Control Application Example
You are now ready to begin creating an application that executes CoraScript
commands with the LoggerNet server. An example of a user interface that
accomplishes this task is shown in Figure 5-1. This interface includes the
CsiCoraScript control and other objects on the form to create a functional
application.
5-2
FIGURE 5-1. CsiCoraScript Example
Now that the interface has been designed, the code can be organized to
accomplish the requirements of the application. Initially, the application must
connect to the LoggerNet server using the serverConnect() method. A basic
example of code used to accomplish this task is shown in the table that follows:
Section 5. Developing an Application Using the CsiCoraScript Control
Private Sub cmdConnect_Click()
'Connect using the default logon settings.
CsiCoraScript.serverName = txtServerAddress
CsiCoraScript.serverPort = txtServerPort
CsiCoraScript.serverLogonName = txtUsername
CsiCoraScript.serverLogonPassword = txtPassword
'The following attempts to connect to the LoggerNet server
'and calls the event onServerConnectStarted()if the connection
'starts or the event onServerConnectFailure()if it fails.
CsiCoraScript.serverConnect
End Sub
If the connection succeeds, the onServerConnectStarted() event gets triggered.
Otherwise, the onServerConnectFailure() event gets called if the connection
fails.
In order to execute CoraScript commands on the LoggerNet server, use the
method executeScript(). A basic example of code using this method to execute
CoraScript commands and displaying the results in the interface follows:
Private Sub cmdCoraScript_Click()
Dim corascript As String
'Send CoraScript commands to the LoggerNet Server
'Sample CoraScript commands include:
'list-devices;
'add-device com-port Com1 before "";
'add-device CR10x CR10X_Test as-child Com1;
corascript = CsiCoraScript.executeScript(txtCoraScript.Text, 0)
txtCoraResult.Text = corascript
End Sub
Add additional functionality, error handling, and objects as necessary beyond
the example interface and code listed above to meet the specific requirements
of your application. Complete examples using the CsiCoraScript control are
included in the LoggerNet SDK installation.
5-3
Section 5. Developing an Application Using the CsiCoraScript Control
5-4
Loading...