H.A.L.B.E.R.T. is Open-Source Home Automation Software running Node.js for the Raspberry Pi.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
env
feature-tests
persist
system
test
.eslintignore
.eslintrc.js
.gitattributes
.gitignore
.yarnclean
README.md
gulpfile.js
halbert.config.json
halbert.jpg
halbert.svg
index.js
package.json
yarn.lock

README.md

halbert logo

H.A.L.B.E.R.T.

Open-Source Home Automation running Node.js on a Raspberry Pi

license release node version npm downloads

What is H.A.L.B.E.R.T.

H.A.L.B.E.R.T. is a little Node.js project, that is supposed to run on the Raspberry Pi. It is designed to be easily expendable using modules that are simple and easy to write. The name is a combination of the HAL-9000 computer from 2001: A Space Odyssey and the stereotypical butler's name Albert.

Halbert has the following features:

  • Web-Interface with a customizable Dashboard
  • Voice-Control using API.ai for language processing
  • Apple Home-Kit integration (for use with Siri etc.)
  • Easily extendable using modules and a powerful API
  • Based on a simple to understand Trigger-Action-Principle

Getting Started

To get started, download the Halbert-CLI from npm

npm install -g halbert-cli

or using yarn.

yarn global add halbert-cli

Then, create a new H.A.L.B.E.R.T. Instance using. This will create a new folder with the given name, and then create default files and folders.

halbert new <directory-name>

You can then change the directory into the newly created one. After that, you can start the system using halbert start. (If the npm install process failed, you may have to do that manually before starting.)

cd <directory-name>
halbert start

Structure

When you create a new H.A.L.B.E.R.T. Instance, you get a folder structure resembling this:

your-directory
  halbert.config.json
  modules/
  node_modules/
  package.json
  persist

halbert.config.json - This is the config file. It's features are documented here. This file stores the main config for the system itself but also all of its modules.

modules/ - This is the folder where you can put in your own modules. You can either create them yourself or download them from other sources.

node_modules/ - Your NPM Modules folder.

package.json - Your package.json file. Used to install the halbert-core.

persist/ - Used to store data that is persistant over launches of the system.

Config

This is what an example config looks like:

  {
    "device": {
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
    "weather": {
      "openWeatherMapApiKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "server": {
      "port": 3000,
      "cacheTemplates": false
    },
    "modules": {
      "switches": {
        "gpio": {
          "remote": 15
        },
        "available": [
          {
            "id": "desk-leds",
            "name": "Desk LED",
            "hotwords": ["desk led", "desk leds", "leds on the desk"],
            "type": "remote",
            "protocol": "intertechno",
            "code": "A1"
          },
          {
            "id": "desk-light",
            "name": "Desk Light",
            "hotwords": ["desk light", "desk lamp", "lamp on the desk", "light on the desk"],
            "type": "remote",
            "protocol": "intertechno",
            "code": "A2"
          }
        ]
      },
      "ifttt": {
        "apiKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "webhookSecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }

Config Documentation

Coming soon

Modules

Modules are the primary source of logic for Halbert. There are multiple built-in modules, providing basic funcitonality. But the main purpose of this system, is so users can create and share their own modules.

How to make a module

Create a new folder with the desired module name (it should be lowercase and no spaces). Inside that folder, create an index.js file. This will be your entry point. A boilerplate index.js file would look like this:

module.exports = function (builder) {
  // Your Code in here
};

The builder object is a utility which gives you access to the underlying systems such as widgets, api routes, actions or triggers.

Builder

The Builder consists of multiple different sub-objects.

builder.accessories

This builder enables you to create accessories to be used by Apple's Home Kit. Since Halbert deploys a HomeKit-Bridge, you can make the things you're building controllable via the iOS Home App.

.createAccessory(name, id) -> Accessory

Create an accessory and return it. If you want to know, how to further work with these Accessory Objects, see HAP-NodeJS.

.getAccessories() -> Array

Get a list of this module's registered accessories.

builder.actions

This builder enables you to create actions to be used by other modules, widgets etc. You can chain these calls.

.createAction(actionId) -> ActionBuilder

Create an actions with the supplied id.

.setMeta(name, sentence) -> ActionBuilder

Set the action's meta data. This means the Action title and the sentence. The sentence part should fit into the sentence 'If trigger, then [X]'.

.setCallback() -> ActionBuilder

Set the callback for an action call. The callback will be supplied with an input-argument. E.g.

.setCallback(function (input) {
  console.log(input.temperature);
});
.getActions() -> Array

Get a list of this module's actions.

About the Code

The Code is formatted using JLongster's prettier.