USB thumb-drive functionality

eGauge Core/Pro have USB and thumb-drive storage functionality

Automated USB Export and Upgrade scripting file

Introduction

Starting with firmware v3.4, eGauge firmware supports USB Mass-Storage devices on hardware with USB ports (e.g., EG4115 (Core) and EG4130 (Pro)).  Both Windows VFAT and Linux EXT3 filesystems are supported.  When the eGauge device detects a valid storage device, it will automatically bring up a USB Storage menu on the LCD screen.  From there, it is possible to select various operations, such as:

For flexibility and to simplify operations when it is necessary to perform the same USB Storage task on multiple devices, the firmware also supports a script file called auto.run.  When this file is present in the top-level directory (root folder) of the USB storage device, it will be executed as soon as the USB storage device is detected by the firmware.  The details of how this file is executed are specified below.

 

Scripting Language

The auto.run file consists of a sequence of text lines, each line containing a command.  Commands are executed in sequence, one by one.  If a command fails for any reason, script execution stops and the most recent error is displayed on the LCD screen.  The operator needs to acknowledge the error by pushing the multiswitch button and, once that is done, the USB Storage menu is displayed.

In the absence of errors, script execution stops upon reaching the end of the script file or after execution of an "eject" command (see below).  After reaching the end of the script, the USB storage menu is displayed on the LCD.  After an "eject" command, the LCD screen reverts to normal operation.  The USB storage device is then no longer accessible until the USB storage device is removed and reinserted into the USB port or the device is rebooted (e.g., power cycled or rebooted via firmware).

Script files may contain line-comments that start with a hash character (#).  The hash character and any following characters up to the end of the line are ignored.

 

Script Commands

In the following descriptions, square brackets are used to indicate optional parts of a command. Italics is used as place-holders for variable content.


backup [FILENAME_TEMPLATE]

Backup the eGauge device data to the file specified by FILENAME_TEMPLATE.  This string may contain references to variables that are expanded as follows:

Variable Reference

Expands to

Example

${DEVNAME}

eGauge device name

eGauge1234

${SN}

eGauge serial number

1701260002

${TIME}

current date and time

20180411-1310

 

If FILENAME_TEMPLATE is omitted, the template:

backup-${DEVNAME}-${TIME}.bin

is used by default.


export [PERIOD [GRAN [FILENAME_TEMPLATE]]]

Export eGauge device data to the file specified by FILENAME_TEMPLATE.  The data is saved in comma-separated-values (CSV) format.  The file-name template may use the same variables as the backup command.  In addition, the following variables are supported:

Variable Reference

Expands to

Example

${PERIOD}

export time-period

ytd

${GRAN}

export granularity

hour

PERIOD specifies the time period of the data to be exported:

Period specified

Time range covered

day

Most recent 24 hours of data are exported.

month

Most recent 31 days of data are exported.

year

Most recent 366 days of data are exported.

all

All data is exported.

dtd

day-to-date: export data from midnight up to current time

mtd

month-to-date: export data from start of month up to current time

ytd

year-to-date: export data from start of year up to current time

GRAN specifies the granularity (resolution) with which the data is exported:

Granularity specified

Resolution

sec

Second resolution (or best available).

min

Minute resolution (or best available).

quarter

15-minute resolution (or best available).

hour

Hour resolution (or best available).

day

Day resolution.

Note that the eGauge device database internally uses varying granularity to balance storage requirements with the ability to retain data for long time periods.  Specifically, second-by-second data is typically retained only for the most recent hour, then dropping to minute-granularity, until at last day-by-day data is available for the longest amount of time (e.g., 60 years).  The granularity specified in the export command is the finest resolution to be used during the export.  If the database doesn't have the data available in the desired resolution, it will automatically exported in the best available resolution.

Also worth mention is that day-granularity data is captured every day at midnight UTC.  The date and time exported in the CSV file is converted to the device's time-zone, which means the hour seen in the exported data may be one or the other, depending on whether or not daylight savings is in effect.  For example, in US/Mountain time-zone, day-granularity data is captured at 6pm (18:00) during the summer months and at 5pm (17:00) during the winter months.


update_fw [[PATH] force]

Update the device firmware using the file specified by PATH.  If PATH is omitted, the file fw.bin will be used.

The update will be performed only if the file contains a firmware newer than the one that is currently installed.  However, if option "force" is specified after the file path, the update will be performed regardless of the version currently installed on the eGauge device.

After a successful update, the LCD screen will indicate that the device needs to be rebooted.  The operator needs to confirm this by pushing in the multiswitch button and that point, the eGauge device reboots itself to activate the new firmware.


eject

This command ejects (unmounts) the USB storage device and stops script execution.  Once the command has finished, the LCD screen returns to normal operation and it is safe to remove the USB storage device from the USB port at that point.

 


 

Example Script

In the following example, let's assume the device name is "eGauge1234" and the commands are all executed on April 1st, 2018, at 1:14pm (13:14).

# This is a comment.  It has no effect on execution.

# OK, let's do a backup first:
backup # will be saved in "backup-eGauge1234-20180401-1314.bin"

# Export data to "data-eGauge1234-ytd-hour.csv":
export ytd hour data-${DEVNAME}-${PERIOD}-${GRAN}.csv

# Eject USB storage and return eGauge device to normal operation:
eject

 

USB Data Exports through LCD

Data can be exported directly from eGauge 4xxx meters using a USB mass storage device. These exports automatically contain day-granular data. All data from epoch (the date set in "Date and Time Recording Started" under Settings -> General Settings) until the date and time the export was initiated is copied. 

To select a specific granularity or time range (or otherwise automate USB exports), an auto.run file must be created and loaded on the USB mass storage device (this article has more information).

To begin the process, insert a mass storage device formatted as EXT3 or VFAT. The "Storage Menu" will appear. Menu navigation is performed using the multiswitch button. Moving the switch left or right will change the selected option. Pushing the multiswitch in will confirm the selection. "Export data" should be highlighted by default. To begin the export, push the multiswitch in:

Once the export has begun, the screen will read "export started". The export process takes a variable amount of time depending on the amount of data present on the eGauge.

Once the export has finished, the screen will read "export finished". The "OK" option will be highlighted. Push the multiswitch in to acknowledge.

After acknowledging the export, the "Storage Menu" will appear again. Move the switch left or right until "Exit & Eject" is highlighted. Push the multiswitch in to select this option.

Once the main LCD menu appears, the USB mass storage device can be safely removed.

Formatting a USB stick on Windows 10

These instructions may not work for all versions of Windows and are provided as-is. eGauge Support cannot provide additional troubleshooting or support on formatting USB sticks. An adequate understanding of using the Windows operating system and file explorer may be necessary to complete these instructions.

This will permanently erase all data on the selected drive or USB stick. Incorrect usage can cause permanent data loss on the wrong drive.

1) Connect a USB stick to a PC running the latest version of Windows 10.

2) Click on the Start Menu and type in "this pc" and open the "This PC" app.

image-1622141210699.png

3) In the "This PC" window, right-click the USB stick and choose "Format..."

image-1622141320231.png

4) Ensure the "File system" is set to FAT32, and "Quick Format" is checked. The "Volume label" does not matter. Press "Start".

image-1622141347791.png

5) When complete, the USB stick is ready for use with an eGauge.

If copying files such as auto.run and fw.bin, open another explorer window to where the files are downloaded on your computer, and open the USB drive. Select the file(s) and drag the files to the explorer window of the USB stick.

image-1622141555421.png

6) After the files are copied, click the "back" button on the USB stick window, right-click the USB stick drive and choose "Eject".

image-1622141610887.png

7) Remove the USB stick. It is now ready for use with the eGauge meter.