Install File Format
This section describes the format of the install.txt file used for installing plugins. Note that the files in the zip file must all be at the same level, sub directories in the zip file are not supported. The destination of the file can be in a sub directory however.
The install.txt file tells the system where to copy included files. Normally you are simply copying a file to a sub folder such as the bin folder, the HomeSeer folder, or the html folder.
Note that for HS4 you can only copy files to the following folders:
html/pluginID/
bin/pluginID/
HomeSeer program folder (but only your EXE plugin file and EXE config file)
Data/pluginID
images/pluginID
Files should not be copied into any other folders. They may interfere with other plugins and will not be removed when the plugin is uninstalled.
Summary of available commands:
| Command | Description |
|---|---|
| (default) | Copy a file or delete a single file |
| [CHECKVERSION] | Require a specific version of HomeSeer (or higher) |
| [LOCALCOPY] | Copy a local file from one place to another under the HomeSeer directory structure |
| [LOCALCOPYNONFATAL] | Instruct the updater to not fail on error copying local files |
| [INIADD] | Add to an existing INI key entry |
| [INIADDPARM] | Add a parameter to an existing INI key entry (comma separated) |
| [INI] | Modify (replace) or add a new key to an INI file |
| [DELFILES] | Delete all of the files in a directory |
| [DELALL] | Delete a directory and all of the files and subdirectories in the directory |
| [UNZIP] | Unzip a zip archive to a directory, do not overwrite existing files |
| [UNZIPOVER] | Unzip a zip archive to a directory, overwrite existing files |
CHECKVERSION
Require a specific version of HomeSeer (or higher)
Parameter 1: (not used)
Parameter 2: [CHECKVERSION]
Parameter 3: 4 position dotted decimal version to check for.
This feature should be the first line in your install.txt file so that none of the remaining installation commands take place.
Example:
To require version 1.6.182 or higher of HomeSeer for your package:
xxxx,[CHECKVERSION],1.6.0.182
Copy
Parameter 1: The filename of the file to install such as weather.txt.
Parameter 2: The destination directory for the file. This is always relative to the root HomeSeer directory. To install a plug-in file to the HomeSeer directory, use ".". To install a file into the scripts directory, use ".\Scripts".
Parameter 3: This value is a numeric bit field that describes options that should be applied to the install. The value entered here is the decimal representation of the bits. The bits available are:
bit 4 = &h10 = 16 | Do not install the file if the file already exists. |
bit 5 = &h20 = 32 | Delete the file if it exists. |
Set this parameter to 0 if the file does not require any of the above options.
Bits may be "ORED" together to represent multiple options.
Examples:
weather.txt,.\scripts,0
hspi_Plugin.exe,.,0
DELALL
Delete a directory and all of the files and subdirectories in the directory.
Parameter 1: (not used)
Parameter 2: [DELALL]
Parameter 3: The path and name of the directory you wish to have deleted with extreme prejudice. (Relative to the HS directory)
Examples:
xxx,[DELALL],.\scripts\includes\myapp
xxx,[DELALL],.\html\includes\myapp
DELFILES
Delete all of the files in a directory.
Parameter 1: (not used)
Parameter 2: [DELFILES]
Parameter 3: The path and name of the directory you wish to have emptied. (Relative to the HS directory)
Examples:
xxx,[DELFILES],.\scripts\includes\myapp\dir1
xxx,[DELFILES],.\scripts\includes\myapp\dir2
xxx,[DELFILES],.\html\includes\myapp\dir1
xxx,[DELFILES],.\html\includes\myapp\dir2
INI
Modify (replace) or add a new key to an INI file.
Parameter 1: The INI file section name to be modified/added to.
Parameter 2: [INI]
Parameter 3: (not used)
Parameter 4: The KEY to add a value to in the INI file.
Parameter 5: The value to add to the key. See the note above about commas.
Parameter 6: (optional): If provided, the name of the INI file in the CONFIG directory to modify. If this parameter is not provided, SETTINGS.INI is assumed.
Examples:
hspi_HAI,[INI],xxx,MyText,The only text for this key,MyFile.ini
(This would write “The only text for this key” as the value of the MyText key in the hspi_HAI section of the MyFile.ini file.
INIADD
Add to an existing INI key entry.
Parameter 1: The INI file section name to be modified/added to.
Parameter 2: [INIADD]
Parameter 3: (not used)
Parameter 4: The KEY to add a value to in the INI file.
Parameter 5: The value to add to the key. See the note above about commas.
Parameter 6: (optional): If provided, the name of the INI file in the CONFIG directory to modify. If this parameter is not provided, SETTINGS.INI is assumed.
Examples:
hspi_HAI,[INIADD],xxx,MyText,even more text to add to this entry,MyFile.ini
(This would add even more text to add to this entry to whatever was already set as the value of the MyText key in the hspi_HAI section of the MyFile.ini file.
INIADDPARAM
Add a parameter to an existing INI key entry. (Comma separated)
Parameter 1: The INI file section name to be modified/added to.
Parameter 2: [INIADDPARM]
Parameter 3: (not used)
Parameter 4: The KEY to add a value to in the INI file.
Parameter 5: The value to add to the key.
Parameter 6: (optional): If provided, the name of the INI file in the CONFIG directory to modify. If this parameter is not provided, SETTINGS.INI is assumed.
Examples:
settings,[INIADDPARM],,io_interfaces,test plugin
(This would add "test plugin" to whatever was already set as the value of the io_interfaces key in the settings section of the settings.ini file. If there is a value already present, then a comma will be added before the new value is appended. If the value is empty or does not exist, then the new value will be set for the key.
LOCALCOPY
Copy a local file from one place to another under the HomeSeer directory structure. (This is useful for making backup copies of existing files when updated versions are being installed.)
Parameter 1: Source file name
Parameter 2: [LOCALCOPY]
Parameter 3: Destination file name
Parameter 4: (optional): File copy attributes as for normal installer copy operations minus the file delete attribute.
Source and Destination file names are referenced from the HomeSeer root directory WITHOUT the leading .\ as is used in other updater commands. Destination directories that do not exist will be created.
Example:
html\TouchPad\Button.gif,[LOCALCOPY],html\TouchPad\Saved\Button.gif,16
LOCALCOPYNONFATAL
Set the option in the updater for whether or not errors with the LOCALCOPY function will terminate the installation script.
Parameter 1: (not used)
Parameter 2: [LOCALCOPYNONFATAL]
Parameter 3: True or False
Example:
,[LOCALCOPYNONFATAL],True
The above sets the option to True, so copy errors will not abort the installation.
UNZIP
Unzip a zip archive to a directory, do not overwrite existing files.
Parameter 1: The zip archive to process.
Parameter 2: [UNZIP]
Parameter 3: The destination directory for the zip archive. Note that if the archive was created with directory information, then it will be unzipped starting at (destination directory) as the root and will be unzipped with the directory structure in tact. Files that already exist will NOT be overwritten.
Examples:
Webhelp.zip,[UNZIP],.\html\PLUGINID\webhelp
UNZIPOVER
Unzip a zip archive to a directory, overwriting existing files.
Parameter 1: The zip archive to process.
Parameter 2: [UNZIPOVER]
Parameter 3: The destination directory for the zip archive. Note that if the archive was created with directory information, then it will be unzipped starting at (destination directory) as the root and will be unzipped with the directory structure in tact. Files that already exist will NOT be overwritten.
Examples:
Webhelp.zip,[UNZIPOVER],.\html\PLUGINID\webhelp