Gateway Historian User’s Guide
Introduction
The Xantrex Gateway Historian is a Python-based application script that allows a Gateway user to download energy history logs. Hourly, daily and monthly energy logs for each of your Xantrex inverters or chargers are stored by the Gateway for a period spanning up to two years. Using the Historian the user can choose to retrieve either the entire energy history of the Gateway system or simply the most recent hour, day and month log.
Installation
Installation of the Xantrex Gateway Historian is very straight forward; simply double click the GWHistorian_setup.exe icon and follow the onscreen directions.
Use
The Xantrex Gateway Historian has a very simple user interface which is shown in the image below.
The user interface consists of three fields, a check box, a button and one status text line. The fields are the Gateway’s URL, the Gateway password and a target folder which will contain the downloaded log files. The target folder field can be double clicked for access to a ‘browse folders’ dialog window. The checkbox controls whether (all) two years of data is downloaded or just the most recent hour, day and month logs. The button begins the download process. The status text line simply shows the most recent status or error message.
Once you have made your selections you can press the ‘Start Archiving!’ button to begin the downloading process.
Downloading considerations
Before you download Gateway energy logs there are a number of points you should carefully consider.
Current gateway network connections
The Gateway is limited in the number of active network connections it can support at any one time. The user should disable any active widgets or web connections to the Gateway before starting a log download.
The ‘Download all data’ check box
The ‘Download all data’ check box must be used with caution. Firstly, downloading all data can take a very long time, specifically seven minutes per device on the Gateway system network. Secondly, due to the repository nature of the log files, only the most recent data will be logged. What this means is that if you attempt to download all data on a target folder that already contains logs, only the most recent or possibly no data at all will be logged. Typically you only need to download all data for a given Gateway once and on subsequent downloads make sure the ‘Download all data’ checkbox is unchecked.
The target folder
The Gateway Historian will create a file hierarchy in the target folder with a unique folder for each device in the Gateway system. Each of these folders will contain a ‘.csv’ file for each of the device’s hour, day and month logs. Be sure to choose a different target folder for each unique Gateway system, otherwise any log files for devices of the same name (on different systems) will be overwritten.
The target files
As mentioned in the target folder section, log files for each device will be stored in a unique folder. These ‘.csv’ files can be opened with a spreadsheet application like Microsoft Excel. These files must not be altered. If the user wishes to manipulate the data in these files the user must copy the log file to a working folder. The ‘.csv’ log files contained in the target folder hierarchy are treated as a repository; the Gateway Historian examines the modification dates of these files to determine if new data needs to be appended. Modifying these files will confuse the Gateway Historian resulting in inconsistent logging.
Updating of target files
The Gateway Historian will add new data to the target ‘.csv’ log files if the date of newly downloaded data is greater than the last modification date of the log file. In this way the Gateway Historian’s command line back end can be run as a scheduled service to continually and automatically update logs.
Console window
When the user presses the ‘Start Archiving!’ button a console window will appear that shows current download progress and messages. The user can press CTRL-C to terminate the download process.
Command line back end
The gateway historian can be used as a command line utility. The executable for the utility can be found in Program Files/XantrexGatewayHistorian/distCLI/wiPortXML.exe. To use the utility enter the following on the Windows command line:
C:\”Program Files\XantrexGatewayHistorian\distCLI\wiPortXML.exe” –v –p gateway_password –d target_folder –a
Where is replaced with the user’s gateway URL and gateway_password is replaced with the user’s gateway password and target_folder is replaced with the desired target folder.
Be sure to use quotes around any parameter or path that contains space characters!
The –v option is used for verbose status messages (recommended).
The –a option is used to download all two years of logged data (optional).