Skip to main content

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., EG4015 (Core) and EG4030 (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:

  • Creating a backup of all eGauge data

  • Exporting data to a CSV (comma-separated-values) file.

  • Updating the device firmware.

  • Ejecting (unmounting) the storage device so it can be removed safely.

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

Back to top