nklerk/neeo-sdk

NEEO Brain SDK

NEEO SDK

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

• NEEO SDK
  • Prerequisite
    • Windows OS
  • NEEO-SDK CLI
    • Install / expose a third party driver
  • SDK Documentation
• NEEO Macro Names
  • Power Control Capability
  • Volume Control Capability
  • Favorites View Capability
  • Numpad Capability
  • Controlpad Capability
  • Color Buttons Capability
  • MENU Capability
  • Channel Zapper Capability
  • Transport Capability
  • Record Capability
  • Input Capability

Prerequisite

• You must have at least Node.js v6 installed, see http://nodejs.org

Windows OS

• If you use the SDK on Windows we suggest to install Apple iTunes (or the Bonjour SDK for Windows, available from the https://developer.apple.com site). Windows versions < 10 seems to miss multicast DNS support (aka. Bonjour/Zeroconf). This means the Brain discovery find's a NEEO Brain but you cannot connect to the NEEO Brain (as the discovery fails). You can test if multicast DNS works on your machine when you try to ping NEEO-xxxxxxxx.local (replace xxxxxxxx with the unique hostname of your NEEO Brain).

NEEO-SDK CLI

The SDK is bundled with a CLI tool allowing to start a SDK instance and load device drivers automatically. 🚀 This makes it very easy to run multiple SDK drivers. Check the npm start command in the neeo-sdk-examples repository.

To use it, either update the NPM script:

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

or it directly (in your project's folder, with the SDK installed) with the start parameter, for instance:

./node_modules/.bin/neeo-sdk start

Then, in your driver project, you need to have a directory called 'devices' at the root, where your devices are located. The folder can be configured through the environment variable NEEO_DEVICES_DIRECTORY (for instance NEEO_DEVICES_DIRECTORY="./lib/devices"). To expose your devices to the CLI, you need to export them like so:

const lifx = neeoapi.buildDevice('My Smart Light')
  .setManufacturer('LIFX')
 [...]

module.exports = {
  devices: [lifx]
};

It's important to note that the CLI doesn't search the directories recursively in order to find devices. This means that if you want to separate your devices using directories, you need to create an index.js file inside each one of them and export the device(s) from there.

It's also possible to explicitly exclude directories from the devices search, by adding them to the NEEO_DEVICES_EXCLUDED_DIRECTORIES environment variable, for instance: NEEO_DEVICES_EXCLUDED_DIRECTORIES=["lifx-cloud"]

by default, the 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 the brain through its IP. Otherwise, connect to the first discovered one.
  "brainPort": 3001, // The Brain port. Only relevant when brainHost is defined. Default to 3000
  "serverName": "myServer", // The name of the SDK server. Default to 'default'
  "serverPort": 6637, // The port of the SDK server. Default to 6636
}

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

Install / expose a third party driver

The CLI is also able to run third-party devices, along with locally developed ones.

The exposed devices just need to be exported in an index file in the devices/ directory, the same way as documented above. Note that in order to be detected during the start of an SDK instance, your driver needs to be named with a 'neeo-' or 'neeo_' prefix. For instance: 'neeo-simple-accessory'.

The installation of a third-party driver is done through a simple npm install.

SDK Documentation

See https://neeoinc.github.io/neeo-sdk/

NEEO Macro Names

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

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({..):

• POWER ON
• POWER OFF

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({..):

• VOLUME UP
• VOLUME DOWN
• optionally MUTE TOGGLE

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({..):

• DIGIT 0
• DIGIT 1
• DIGIT 2
• DIGIT 3
• DIGIT 4
• DIGIT 5
• DIGIT 6
• DIGIT 7
• DIGIT 8
• DIGIT 9

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

• TV
• DVB (aka Satellite box, digital receiver)
• TUNER (audio tuner)

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({..):

• CURSOR ENTER
• CURSOR UP
• CURSOR DOWN
• CURSOR LEFT
• CURSOR RIGHT

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({..):

• FUNCTION RED
• FUNCTION GREEN
• FUNCTION YELLOW
• FUNCTION BLUE

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({..):

• MENU
• BACK

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({..):

• CHANNEL UP
• CHANNEL DOWN

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({..):

• PLAY, PAUSE, STOP (helper function: .addButtonGroup('Transport'))
• REVERSE, FORWARD (helper function: .addButtonGroup('Transport Search'))
• PREVIOUS, NEXT (helper function: .addButtonGroup('Transport Scan'))
• SKIP SECONDS BACKWARD, SKIP SECONDS FORWARD (helper function: .addButtonGroup('Transport Skip'))

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({..):

• MY RECORDINGS
• RECORD
• LIVE

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:

• INPUT HDMI 1
• INPUT HDMI 2
• INPUT VGA 1
• INPUT SCART 1