This memo describes how you can install a plugin from github by either using the npm or git command. Using npm (Method 1) should be the preferred approach for most users.

A typical use case for this is to trial changes made by a developer (possibly on a fork if the original code base) which have not been published in a official package release yet.

Method 1 - Using npm

Npm is able to install a package from github rather than using the package registry. Actually, it will use git internally to fetch the project sources.

1. Make sure you have a released version of the plugin installed. The plugin should already be part of of your pimatic setup and configuration
2. Make sure you have git installed on your raspberry by simply typing the command git. If not found you can install it as follows: sudo apt-get install git
3. Now, perform the steps listed below. Replace <PROJECT-OWNER> with the name of the developer on github, e.g. mwittig, and <PLUGIN-PACKAGE> with name of the plugin, e.g. *pimatic-demo’.

sudo service pimatic stop
cd /home/pi/pimatic-app/node_modules/ 
sudo rm -rf <PLUGIN-PACKAGE>
sudo npm install <PROJECT-OWNER>/<PLUGIN-PACKAGE> --unsafe-perm
sudo service pimatic start

Installing a specific branch

The steps described in the previous section will install the default branch which typically is the “master”. Sometimes, the code snapshot may be located on a different branch, e.g. “development”. If you haven’t installed the snapshot yet, you can simply extend the “npm install” command of the previous section as follows.

sudo npm install <PROJECT-OWNER>/<PLUGIN-PACKAGE>#<BRANCHNAME> --unsafe-perm 

Reverting to the released package

That’s easy! Just follow the steps below.

sudo service pimatic stop
cd /home/pi/pimatic-app/node_modules/ 
sudo rm -rf <PLUGIN-PACKAGE>
sudo npm install <PLUGIN-PACKAGE> --unsafe-perm
sudo service pimatic start

Well, having this said it should be said that some plugins for pimatic 0.9 have been release with “beta” tag. Thus it may be required to use the following install command instead. The developer in charge should give advice on this.

sudo npm install <PLUGIN-PACKAGE>@beta --unsafe-perm

Method 2 - Using git

Installing a snapshot from github

1. Make sure you have a released version of the plugin installed. The plugin should already be part of of your pimatic setup and configuration
2. Make sure you have git installed on your raspberry by simply typing the command git. If not found you can install it as follows: sudo apt-get install git
3. Now, perform the steps listed below. Replace <PLUGIN-PACKAGE> with name of the plugin, e.g. “pimatic-demo” and <URL> with URL of the repostory. You can easily copy the URL of a github repostory by clicking on the copy icon.

sudo service pimatic stop
cd /home/pi/pimatic-app/node_modules/ 
sudo rm -rf <PLUGIN-PACKAGE>
git clone <URL>
cd <PLUGIN-PACKAGE>
npm install
sudo service pimatic start

Checking out a specific branch

The steps described in the previous section will checkout the default branch which typically is the “master”. Sometimes, the code snapshot may be located on a different branch, e.g. “development”. If you haven’t installed the snapshot yet, you can simply extend the “git clone” command of the previous section as follows.

git clone <URL> --branch <BRANCHNAME>

If you need switch the branch at a later point in time you need to perform the following steps.

sudo service pimatic stop
cd /home/pi/pimatic-app/node_modules/<PLUGIN-PACKAGE>
git fetch
git checkout <BRANCHNAME>
git pull
sudo service pimatic start

Updating a snapshot from github

If you have already installed a snapshot from github and the developer has updated files on github you may want to synchronize your local files with the current version on github. As the dependencies defined in the package.json file may have changed you should also run npm install as shown below.

sudo service pimatic stop
cd /home/pi/pimatic-app/node_modules/<PLUGIN-PACKAGE>
git pull
npm install
sudo service pimatic start

Reverting to the released package

That’s easy! Just follow the steps below.

sudo service pimatic stop
cd /home/pi/pimatic-app/node_modules/ 
sudo rm -rf <PLUGIN-PACKAGE>
sudo npm install <PLUGIN-PACKAGE> --unsafe-perm
sudo service pimatic start

Well, having this said it should be said that some plugins for pimatic 0.9 have been release with “beta” tag. Thus it may be required to use the following install command instead. The developer in charge should give advice on this.

sudo npm install <PLUGIN-PACKAGE>@beta --unsafe-perm

One addition to “Checking out a specific branch”.

If there are changes in package.json in the checked out branch, it might be, that you have to run npm install again.

Thanks. Updated.

Updated. I have added using “npm” instead of “github” which may be the preferred approach for most users.

I think there is some mistake in explanation of method 1.
In step 3 there is written 'and <URL> with URL of the repostory’ but there is no URL in the code snippets, instead there is an unexplained <PROJECT-OWNER>

@Heizelmann Thanks for proof-reading and pointing this out!