The contents of this repo have moved to

https://github.com/HubitatCommunity/hubitatpackagemanager

and all Pull Requests, etc. should be made there. This repo remains for historical reasons only.

Please don't use any of the links below, since they are not maintained.

hubitat-packagemanager

The Hubitat Package Manager provides tools to install, uninstall, and upgrade 3rd party packages to add to your Hubitat Elevation environment. This document includes information for how to use this app as well as how to contribute your own packages.

Initial Configuration

If you use Hub Security you will need to provide the admin username and password of your hub. If you do not, simply turn the toggle off.

The app will then perform a Match Up. This will automatically search all of the apps and drivers you have installed and compare it to a list of those that have packages. If a match is found, the package manager will begin monitoring that package for updates.

Installing a Package

There are three ways to install a package. You can Search by Keywords, Browse by Tags, or if you know the URL of a package you can choose From a URL

If you choose to Search by Keywords, you will get a textbox where you can enter your search query. When you click Next you will see all matching packages.

If you choose to Browse by Tags, you will see a list of tags to filter by.

If you chose to enter a URL you will be prompted to enter the URL. This is not the URL of a regular Hubitat app/driver. It is the URL of a package JSON. If you do not know what this is, you should probably choose to install from a repository.

If the package includes any optional apps or drivers you will be prompted to choose which ones you'd like to install. If you need to change your decision later you can always return and perform a Modify which will let you change the optional parameters.

After you make your decisions you'll be prompted to confirm by clicking Next. Once you do the package will be installed.

Modifying a Package

If you need to add or remove an optional component from a package later, choose the Modify option. You will be asked to choose which package you'd like to modify.

Choose the components to add and/or remove. You will then be asked to confirm before the changes are made. Click Next to complete the changes.

Repairing a Package

If you accidentally manually uninstall an app or driver that is part of a package, or if an update goes wrong for some reason, use a repair to fix the package. Simply specify the package to repair. Click Next to reinstall the package. Note that this will also update it to the latest version.

Choose the components to add and/or remove. You will then be asked to confirm before the changes are made. Click Next to complete the changes.

Uninstalling a Package

If you'd like to uninstall a package, choose the Uninstall option. Choose the package to uninstall and click Next. You will then be prompted to confirm the components that are to be removed. Note, this option cannot be undone. If you would like the package to be reinstalled you must do so by running an Install and you will have to reconfigure all of your settings again.

Updating Packages

When an author releases a new version of a package, to install it, choose the Update option. If updates are available, choose the packages you wish to update and then click Next. You will then be able to confirm your selections and install the updates by clicking Next.

Match Up

A Match Up will search through all of the apps and drivers you have installed on your hub and attempt to figure out if there are packages available that match these apps and drivers. This isn't an exact science. The Hubitat Package Manager will show you matches it found and allow you to confirm those that appear to be correct. This will then cause the selected apps and drivers to be monitored for updates. Unfortunately, the package manager has no way to know what version of a previously installed app or driver was installed. You have two options. You can either tell the package manager to assume that the version you have installed is up to date, or not. If it is set to assume it is up to date, you will not receive update notifications until the next time a new version is available. If it is set to not be up to date, you can immediately perform an Update which will ensure the latest version is installed.

View Apps and Drivers

This will show you all of the apps and drivers you have installed that are currently being managed by the Hubitat Package Manager. You should Not uninstall or update these apps and drivers manually. You should only modify them using the Hubitat Package Manager. If provided by the developer, you'll also find links to the documentation for a package as well as a link to the community discussion thread for the package.

Package Manager Settings

This is where you can control the settings of the Hubitat Package Manager. You can modify your Hub Security settings, choose which repositories you want to use, enable or disable debug logging, manage updates, and also Add a Custom Repository.

The updates include several options. You can configure when the update checker runs (Note: you should not run the checker during the Hubitat maintenance window at 3am), whether or not you'd like to receive a notification if updates are available, and if the updates should be installed automatically. You can choose to install all updates automatically, or just for certain packages. Additionally you can receive a push notification when an update either succeeds or fails.

Developer Information

The information below is intended for app and driver developers who wish to use Hubitat Package Manager to provide your apps and drivers. Two things are needed, each package must provide a manifest and you must provide a repository that lists your packages. A small little tool called Hubitat Package Manager Tools has been provided which assists in the creation of these files. On Windows simply run the hpm.exe --help to get help, and on MacOS and Linux run ./hpm --help

Package Manifest

The package manifest is a JSON file that lists the apps and drivers that are part of your package. A recommendation when versioning your packages is to use SemVer. This will ensure that the Hubitat Package Manager is always able to detect updates properly. You can either version the entire package as a whole, or each app/driver can be versioned, but don't mix-and-match within the same package.

Example

{
	"packageName": "My Package",
	"minimumHEVersion": "2.1.9",
	"author": "Dominick Meglio",
	"version": "1.0",
	"dateReleased": "2020-04-07",
	"licenseFile": "",
	"releaseNotes": "",
	"apps" : [
		{
			"id" : "67d9cc01-a5cb-453c-832a-e78c5a6b978b",
			"name": "The App",
			"namespace": "abc.theapp",
			"location": "https://raw.githubusercontent.com/app.groovy",
			"required": true,
			"oauth": false
		}
	],
	"drivers" : [
		{
			"id": "22597029-98db-490b-b8b9-c23b972ee5f2",
			"name": "Required Driver",
			"namespace": "abc.reqdriver",
			"location": "https://raw.githubusercontent.com/driver1.groovy",
			"required": true
		},
		{
			"id": "e012ffff-7959-466b-a2ae-3181a33010f9",
			"name": "Optional Driver",
			"namespace": "abc.optdriver",
			"location": "https://raw.githubusercontent.com/driver2.groovy",
			"required": false
		}
	]
}

Commands Used

hpm manifest-create packageManifest.json --name="My Package" --author="Dominick Meglio" --version=1.0 --heversion=2.1.9 --datereleased=2019-04-07
hpm manifest-add-app packageManifest.json --location=https://raw.githubusercontent.com/app.groovy --required=true --oauth=false
hpm manifest-add-driver packageManifest.json --location=https://raw.githubusercontent.com/driver1.groovy --required=true
hpm manifest-add-driver packageManifest.json --location=https://raw.githubusercontent.com/driver2.groovy --required=false

Repository File

The repository file is another JSON file that can be created using the Hubitat Package Manager Tools. This lets you list all of the packages you have available in your repository. When assigning a category to your packages please reference the list below.

Categories & Tags

Categories are being phased out in favor of tags. A complete list of categories and tags can be viewed at https://raw.githubusercontent.com/dcmeglio/hubitat-packagerepositories/master/settings.json If you need additional tags because the existing ones don't cover your use, submit a PR against this file.

Publishing your Repository

When your repository file is ready to go, submit a Pull Request against https://raw.githubusercontent.com/dcmeglio/hubitat-packagerepositories/master/repositories.json which includes the name of your new repository and the location of your repository JSON. Once your pull request is merged it will become available to all Hubitat Package Manager users.

Example

{
	"author": "Dominick Meglio",
	"gitHubUrl": "https://github.com/dcmeglio",
	"payPalUrl": "https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=7LBRPJRLJSDDN&source=url",
	"packages": [
		{
			"name": "Package 1",
			"category": "Integrations",
			"location": "https://raw.githubusercontent.com/package1/packageManifest.json",
			"description": "This is Package 1"
		},
		{
			"name": "Package 2",
			"category": "Convenience",
			"location": "https://raw.githubusercontent.com/package2/packageManifest.json",
			"description": "This is Package 2"
		}
	]
	
}

Commands Used

hpm repository-create repository.json --author="Dominick Meglio" --githuburl=https://github.com/dcmeglio --paypalurl="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=7LBRPJRLJSDDN&source=url"
hpm repository-add-package repository.json --manifest=https://raw.githubusercontent.com/package1/packageManifest.json --name="Package 1" --category=Integrations --description="This is Package 1"
hpm repository-add-package repository.json --manifest=https://raw.githubusercontent.com/package2/packageManifest.json --name="Package 2" --category=Convenience --description="This is Package 2"