EQuIS Live - Getting Started»EQuIS Live Collection Agent - …
  • RSS Feed

Last modified on 5/20/2014 8:41 PM by User.

Tags:

EQuIS Live Collection Agent - Campbell Scientific LoggerNet

Keywords: EQuIS Live, data loading, data collection, Campbell Scientific, csi, loggernet, TOA5, dat

The EQuIS Live Collection Agent for Campbell Scientific LoggerNet is designed to load data that comes directly from data loggers via the LoggerNet software. LoggerNet is a separate software application and is not included in EQuIS Live. Licenses and support for LoggerNet are available from Campbell Scientific. Programming data loggers and setting up LoggerNet to connect to those data loggers is outside the scope of this article. LoggerNet comes in two editions: LoggerNet and LoggerNet Admin. LoggerNet Admin includes all of the functionality of LoggerNet, but is also configured to run as a Windows Service. The EQuIS Live LoggerNet Agent will work with either edition of LoggerNet. If LoggerNet is not running a Windows Service, then the application must be left running continuously to allow for continuous data loading.

LoggerNet Configuration

Scheduled data collection must be configured within LoggerNet for the desired data logger(s). Data from the data logger(s) is downloaded by LoggerNet and written to local files on a specified schedule. The Setup Screen (within LoggerNet) shows each data logger that LoggerNet is connected to. The Schedule tab allows you to enable scheduled data collection for the selected logger and define the Collection Interval. The following image illustrates an example data logger that is scheduled for data collection every fifteen (15) seconds:

The Data Files tab allows you to choose the desired table(s) and chooses an output file name. Be sure to set the File Output Option to Append to End of File and the Output Format option to ASCII Table Data, Long header (TOA5) as shown here:

Installation and Setup

After verifying that LoggerNet is installed and configured correctly, you are ready to install the EQuIS Live LoggerNet Agent. EQuIS Live LoggerNet Agent needs to be installed either on the same machine as LoggerNet, or somewhere with full access to the LoggerNet output files (*.dat). Follow these steps to install and configure EQuIS Live LoggerNet Agent:

  1. Download the EQuIS Live LoggerNet Agent installation file (*.msi) on the intended machine.
  2. Start the installation by running the *.msi
  3. Accept the license agreement.
  4. Select the installation folder (the default folder is C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent).
  5. Complete the installation.

Database Connection

Before using EQuIS Live LoggerNet Agent, you must enter the database connection string (to the EQuIS database) in the *.config file as follows:

  1. Open the EarthSoft.Live.Agents.LoggerNet.exe.config file in a text editor (e.g. Notepad or Wordpad).
  2. In the <connectionStrings> section, find the item with name="databaseConnection"
  3. Set the connectionString value to the appropriate string (server name, user id, password, database).
  4. Set the providerName to either EarthSoft.Common.Data.SqlConnection (Microsoft SQL Server) or EarthSoft.Common.Data.OracleConnection (Oracle Database).
  5. Save and close the *.config file.

Licensing

After installation, you must properly license EQuIS Live LoggerNet Agent before use. Follow these instructions to apply the license:

  1. Open a command prompt (as administrator).
  2. Change to the folder where EQuIS Live LoggerNet Agent is installed (e.g. C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent).
  3. Execute the following command to display the Registration screen:

    EarthSoft.Live.Agents.LoggerNet.exe register
     
  4. Copy the Computer ID value and request the EQuIS Live license key from EarthSoft Help Desk.
  5. After receiving the appropriate license keys, repeat Step 3 to view the Registration screen and save the license keys.

Review Windows Service

After entering the database connection string information and licensing the application, you need to review the Windows Service (Administrative Tools ... Services). EQuIS Live LoggerNet Agent runs as a Windows Service, so that the agent will startup with the operating system and not require user interaction. The installation process will automatically create the Windows Service. Follow these steps to review the Windows Service:

  1. Open the Windows Services console (Administrative Tools ... Services).
  2. Find the EarthSoft.Live.Agents.LoggerNet service.
  3. Verify the Startup Type (should be Automatic) if you want the agent to run unattended.
  4. Verify the Log On As account of the service.
    1. Make sure the account has read/write access to the installation folder (e.g. C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent).
  5. Do not start the service until you have added the desired data logger(s) as explained in the next section.
Note:  If desired, the agent may be run via command line, instead of as a Windows Server.

Add Logger(s)

After installation and licensing, you are ready to start adding data loggers to the system as follows:

  1. Locate the Campbell Scientific LoggerNet Output file (*.dat file) for the desired logger (e.g. C:\Campbellsci\LoggerNet\datalogger_001_Public.dat).
  2. Open a command prompt.
  3. Change to the folder where EQuIS Live LoggerNet Agent is installed (e.g. C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent).
  4. Execute the following command to add the logger to EQuIS Live (use the full path to the *.dat file):

    EarthSoft.Live.Agents.LoggerNet.exe addlogger "C:\Campbellsci\LoggerNet\datalogger_001_Public.dat"
     
  5. Note the LOGGER_ID value that is assigned to the given *.dat file.
  6. Open the DT_LOGGER table and review the values created for this *.dat file (field definitions below).
    1. Set UTC_OFFSET_HRS appropriately (based on the offset of the date/time setting used by the data logger).
    2. (Optional) set FACILITY_ID and SYS_LOC_CODE to associate this logger with a location.
    3. Set LOG_PERIOD_S (seconds) to represent how often the data logger logs data.
    4. Set TRANSMIT_PERIOD_S (seconds) to represent how often the data logger transmits data to LoggerNet.
    5. (Optional) set CUSTOM_FIELD_4 to enable automatic file archiving when the file reaches the specified length.
  7. Repeat Steps 4-5 for additional *.dat files that you want to monitor.

Load Historical Data

The Campbell Scientific LoggerNet *.dat files may contain existing data (from previous data collections). You can load any *.dat file into a given logger, as long as the header lines match. So, for example, you may have historical archived *.dat files with different filenames. As long as the header lines match exactly, then these files may be loaded with the instructions below. Existing data can be loaded into EQuIS Live as follows:

  1. Open a command prompt.
  2. Change to the folder where EQuIS Live LoggerNet Agent is installed (e.g. C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent).
  3. Identify the LOGGER_ID of the *.dat file you want to load.
  4. Execute the following command to load the data from the *.dat file into EQuIS Live (use the correct LOGGER_ID):

    EarthSoft.Live.Agents.LoggerNet.exe loaddata 1 "C:\Campbellsci\LoggerNet\datalogger_001_Public.dat"
     
Note:  Loading large *.dat files may take several minutes.

Continuous Data Loading

After EQuIS Live LoggerNet Agent has been properly installed, licensed, and configured - and the desired data loggers have been added to the system as described in the previous section - the software is ready for continuous data loading. You may start the EarthSoft.Live.Agents.LoggerNet service using Administrative Tools ... Services; or you can start the service from a command line as folows:

  1. Open a command prompt.
  2. Change to the folder where EQuIS Live LoggerNet Agent is installed (e.g. C:\Program Files\EarthSoft\EQuIS Live\LoggerNet Agent).
  3. Start the process by executing the following command:

    EarthSoft.Live.Agents.LoggerNet.exe start

When the application starts, it connects to the EQuIS Live database and searches the DT_LOGGER.LIVE_DATA_SOURCE field for *.dat files located on the local machine. For each applicable *.dat file, the agent establishes a file watch to watch for changes to the *.dat file. Whenever the *.dat file changes (i.e. when LoggerNet performs a scheduled data collection), the agent will scan the file for new records and load the new data into the database. For each *.dat file, the agent maintains a bookmark (saved position within the file) to optimize loading of new data. If errors occur while loading data, the records that caused the errors will be written to a *.dat.errors file (with the same path and filename as the *.dat file).

Command line Options

EarthSoft.Live.Agents.LoggerNet.exe supports the following command line parameters:

  • start: start the Windows Service (only applicable if the executable has been registered as a Windows Service)

    EarthSoft.Live.Agents.LoggerNet.exe start
     
  • stop: stop the Windows Service (only applicable if the executable has been registered as a Windows Service)

    EarthSoft.Live.Agents.LoggerNet.exe stop

     
  • register: show the EarthSoft Registration screen to view/save license keys

    EarthSoft.Live.Agents.LoggerNet.exe register

     
  • hash: generate the hash of the header lines of the given file (see DT_LOGGER.CUSTOM_FIELD_2)

    EarthSoft.Live.Agents.LoggerNet.exe hash "C:\temp\somefile.dat"

     
  • addlogger: create a logger record for the given file (see DT_LOGGER.LIVE_DATA_SOURCE)

    EarthSoft.Live.Agents.LoggerNet.exe addlogger "C:\temp\somefile.dat"

     
  • loaddata: load data from the given file (third parameter) to the given logger (LOGGER_ID = 155 in the example below; DT_LOGGER.CUSTOM_FIELD_2 hash must match given file)

    EarthSoft.Live.Agents.LoggerNet.exe loaddata 155 "C:\temp\somefile.dat"

DT_LOGGER table

The DT_LOGGER table contains the following fields that are used by EQuIS Live LoggerNet Agent:

  • LOGGER_ID: a system-assigned unique identifier for the logger
  • LOGGER_CODE: a user/vendor assigned code that identifies the logger program/configuration
  • LOGGER_DESC: a description of the logger program/configuration
  • START_DATE: the effective start date of this logger program/configuration
  • END_DATE: the effective end date of this logger program/configuration
  • UTC_OFFSET_HRS: the number of hours offset from UTC (this value is added to the date/time value in each TOA5 record to compute UTC time)
  • LIVE_DATA_SOURCE: the path to the LoggerNet output file (*.dat) for this logger
  • REMARK: a remark about this logger
  • FACILITY_ID: the facility with which this logger is associated
  • SYS_LOC_CODE: the location with which this logger is associated
  • DEVICE_CODE: a code (e.g. serial number) that identifies the logger hardware
  • DEVICE_DESC: a description of the logger hardware
  • LOG_PERIOD_S: the number of seconds between each logging event on the data logger (aka how often data is logged on the logger)
  • TRANSMIT_PERIOD_S: the number of seconds between each LoggerNet Data Collection (aka how often data is transmitted from the logger to LoggerNet)
  • SYMBOL_ID: reserved for future use
  • STATUS_FLAG: a status flag to indicate whether or not this logger is active (aka STATUS_FLAG = 'A')
  • CUSTOM_FIELD_1: "TOA5" (the type of file being written by LoggerNet)
  • CUSTOM_FIELD_2: a hash of the file header lines that is used to detect if a logger program has changed (additional parameters, different units, etc.)
  • CUSTOM_FIELD_3: used as a bookmark within the file that indicates the last record that was processed
  • CUSTOM_FIELD_4: If populated as '<max file size in bytes>|<destination folder>', the *.dat file will automatically be truncated and archived to the destination folder when it reaches the specified number of bytes. For example, CUSTOM_FIELD_4 equal to '8192|C:\temp\archive' would archive the *.dat file to the C:\temp\archive folder whenever it exceeds 8192 bytes in length.
  • CUSTOM_FIELD_5: reserved for future use


Return to Top