search

NEEOInc / neeo-sdk

NEEO Brain SDK
https://neeoinc.github.io/neeo-sdk/
MIT License
49 stars 17 forks source link
iot neeo nodejs sdk

readme

NEEO SDK Build Status Greenkeeper badge

This is the source code of the NEEO SDK to interact with the NEEO Brain.

If you're looking for examples, take a look at the example repository at https://github.com/NEEOInc/neeo-sdk-examples

Table of Contents

Prerequisite

Windows OS

NEEO-CLI

The NEEO-CLI now lives in a dedicated repository: @neeo/cli

The neeo-sdk cli is deprecated and will be removed in a future version to make the neeo-sdk smaller. We recommend switching to the new CLI as soon as possible.

Why the NEEO-CLI?

One goal of the CLI is to make it easy and simple to run SDK devices without writing any code for non developers. A NEEO-SDK user should be able to run multiple drivers easily without writing code (unlike development that focuses on a single driver at a time). That's where the CLI comes in:

# Example setup:
sdk-drivers/
  node_modules/
    # NEEO SDK drivers installed via npm:
    neeo-driver-lifx/
    neeo-driver-ps4/
    neeo-driver-coffee/
    # ... other modules as well
  package.json

Running neeo-cli start will find and load all 3 drivers (lifx, ps4, coffee). This means you don't have to worry about the folders, the ports or changing any code.

deprecated NEEO-sdk cli

The neeo-sdk cli will be removed in a future version. We recommend using the @neeo/cli.

To use it for your own driver, either update the NPM script:

"scripts": {
  [...]
  "start": neeo-sdk start"
}

This allows you to start your driver with npm start.

By default, the neeo-sdk cli will connect to the first discovered brain within the network. You can change this behaviour by creating a "neeoSdkOptions" property in your project's package.json, and set the "brainHost" property to the Brain IP address. Following parameters are available:

"neeoSdkOptions": {
  "brainHost": "10.0.0.131", // If configured, connect to this IP. Else connect to the first NEEO Brain discovered
}

The Brain lookup uses a default timeout of 5000ms. To change this behaviour, change the environment variable NEEO_BRAIN_LOOKUP_DURATION_MS

SDK Documentation

See https://neeoinc.github.io/neeo-sdk/ for the functions documentation.

Driver export best practices

The NEEO CLI will look for drivers installed in the node_module folder (installed via npm) which export their devices using the following format:

  1. A single file exporting all devices for example index.js: 
    module.exports = {
  devices: [
    // Exports listed here will be detected,
    // these are the objects returned by neeo-sdk.buildDevice()
    exampleDriver,
  ],
};
  2. Your package.json main property points to that file: 
      ...
  "main": "index.js",
  ...
  3. In your package.json use the neeo-driver- prefix for the name property.*

This allows you to place your export where you please as long as you document it in package.json. The CLI will read the main property of the package.json for drivers installed via npm.

This is the recommended setup for exporting devices:

* Previously we looked for the neeo- and `neeoprefixes, these are still detected but we recommendneeo-driver-`_

** In some cases like 2 devices of the same model but different series with slightly different features might share common code, they could then be part of the same module.

You can find an example driver: neeo-driver-example in the neeo-sdk-examples.

See SDK Driver Migration to 0.51.0 for migrating to the @neeo/cli

Running a single driver locally in development mode

When developing a driver it is more convient to directly run a single driver rather than install or link the driver in another folder to use the regular CLI. This also allows attaching a debugger to the process more easiler.

One way to start a driver with the server is to create for example a devStart.js file that looks like this:

"use strict";

const neeoapi = require("neeo-sdk");
const driver = require("./lib/DeviceController");

// IP of your NEEO Brain
const BRAIN_IP = '10.0.0.10';

neeoapi
  .startServer({
    brain: BRAIN_IP,
    port: 6336,
    name: 'debug-server',
    devices: [
      driver,
    ]
  })
  .then(() => console.log('Server Ready'))
  .catch((error) => {
    console.error('ERROR:', error);
    process.exit(1);
});

You can then start your driver with node devStart.js or by adding it to "start": "node devStart.js" in your package.json scripts npm start.

SDK Driver Migration to 0.50.0

To migrate a driver to the driver device export format, follow: Driver migration guide to 0.50.0. Note: We have updated the example code too, take a look there if something is unclear.

SDK Driver Migration to 0.51.0

After 0.50.0 we've decided to move the CLI to a separate repository.

To migrate a driver to the new @neeo/cli, follow: Driver migration guide to @neeo/cli.

Updating device drivers

To tell the NEEO Brain about changes to your device's components you can simply change the driver version (.setDriverVersion). If you for example add new buttons to a device, you can increase the version and this will let the Brain know to fetch the new components.

You do not need to update the version if you do not change the components. When adding the version to a device that was previously not versioned, start with 1. The NEEO Brain will assume it was previously 0 and update. The check for updates happens as soon as the SDK driver is started and registers with the NEEO Brain

 NOTE

Hints

A collection of hints if you create a device driver.

Dynamic Device Builder

If you need to build different devices dynamically (for example to write an SDK driver for a controller that controls lights and switches) you can do that thanks to the updated .enableDiscovery function introduced in the v0.52 release. It static defined device contains the information that it's able to build dynamic devices as soon the discovery function is called.

Quirks

There are some issues on the SDK we will address in the future. To avoid breaking changes we collect them and bulk fix them in a non breaking way in the future.

NEEO Macro Names

The view for a device in the recipe is generated automatically depending on the device capabilities.

See widget documentation for more details on the way default views are generated.

Power Control Capability

If your device supports Power control (power on device, power off device), add this capability - the generated recipe will power on and off your device automatically.

You need to add support for the following buttons (addButton({..):

or just use the shortcut function .addButtonGroup('POWER')

Volume Control Capability

If your device supports Volume control (volume up and down, optional mute toggle), add this capability - the generated recipe will automatically use the volume capability of your device.

You need to add support for the following buttons (addButton({..):

or just use the shortcut function .addButtonGroup('VOLUME')

Favorites View Capability

If you want support for a custom Favorite view, you need to add support for the following buttons (addButton({..):

or just use the helper function .addButtonGroup('Numpad'). The device must be one of the following types:

Numpad Capability

If you want to add a numpad widget to your view, make sure to implement all the DIGIT buttons of the "Favorites View Capability". Supported for TVand DVB devices.

Controlpad Capability

To create a Controlpad capability you need to implement the following buttons (addButton({..):

or just use the helper function .addButtonGroup('Controlpad'). The devicetype must be TV, DVB, GAMECONSOLE, MEDIAPLAYER, VOD, DVD or PROJECTOR.

Color Buttons Capability

To create a Controlpad capability you need to implement the following buttons (addButton({..):

or just use the helper function .addButtonGroup('Color Buttons'). The devicetype must be TV, DVB, GAMECONSOLE, MEDIAPLAYER or PROJECTOR.

MENU Capability

To create a MENU (navigation) capability you need to implement the following buttons (addButton({..):

or just use the helper function .addButtonGroup('Menu and Back'). In most cases it make sense to include the Controlpad capability aswell.

Channel Zapper Capability

To create a Channel Zapper capability (Channel Up/Down) you need to implement the following buttons (addButton({..):

or just use the helper function .addButtonGroup('Channel Zapper').

Transport Capability

If you want to support different transport features (like skip, forward, next) you can include the following buttons (addButton({..):

This works for the devices TV, DVB, GAMECONSOLE, MEDIAPLAYER, VOD, DVD or PROJECTOR.

Record Capability

To create a Record capability you need to implement the following buttons (addButton({..):

or just use the helper function .addButtonGroup('Record'). The devicetype must be TV, DVB. Please note, if you don't have all 3 buttons you can implement only the buttons your device provides.

Input Capability

If you add support for a devicetype TV, PROJECTOR or AVRECIEVER you should provide discrete input change commands depending of your devices features, for example:

Other SDK implementations

Thanks to the contributors for porting the SDK to other platforms.