Getting started with Node.js, Code And the NEEO-SDK (v0.6)

To get started and write your own integrations you might think where do i start?! or looking up and have that "Hmmm that's quite a mountain to climb" feeling. Just a few weeks ago i had the same feeling, I never wrote a word in javascript and just looking at it gave me headaches. hopefully i can take that away and have you started building your own killer integration.

changelog:

v 0.1

• Initial post.

v 0.2

• Changed dutch sentences in code snippets to english.
• Changed some wording in the first SDK Installment (about the warnings)
• Added "start a new project"

v 0.3

• Added namings chapter with device type and button names.
• Changed some typo's

v 0.4

• Updated based on the SDK changes.

v 0.5

• Added an image to represent buttons on a TV device.

v 0.6

• Added NodeJs installation on Raspberry Pi, thanks to Gilles van den Hoven

 

What do you need to get started.

Some basic knowledge about programming would definitely help you but do not hold back if you have never done any real programming. If a dyslexic like me can do it you certainly can to. The SDK used Javascript or more precise Node.JS. also called Node or Nodejs.

Start by learning the basics of Node.js / Javascript

This youtube video will learn you what Node is about and provides some examples to inform you about what it blocking code and what is non blocking code. Don't expect to be able to recreate his examples though, just soak up the idear. (you might want to view it later on again, it might make more sense later on. Unfortunately i can't find another video that helped me out with some of the "if this than else loop basics". When i start learning a language that's new to me i use a text document where i place some code snippets. You might want to do the same. view some youtube videos about javascript and or node and write some of these code snippets in. I'll share mine, they might help you.

Get NodeJS for Windows

So to be able to actually run your code and the SDK you will need to install node. I'm coding and running things on my windows computer but any computer including a raspberry will do. Go to https://nodejs.org/en/download/ download and install node. after installation start your command line. On windows: (start, run, type in CMD and click ok)
  

in the command line type in node -v to see if node is successfully installed. you will see Node's installed version number like  v#.#.# when you have installed it.

 

Get NodeJs for RaspberryPi

This section of the tutorial is related to the installation of Node.js on a Raspberry Pi. It requires a Pi system based on the newer ARMv7 or ARMv8 chip such as the Pi 2 or Pi 3.

NodeSource provides Node.js binaries for these newer ARMv7+ architectures, but not for Raspberry Pi systems based on the older ARMv6 architecture such as the Raspberry Pi Model B/B+ or the Raspberry Pi Zero.

Read the writing carefully on your Raspberry Pi circuit board to confirm is says something like “Raspberry Pi 3 Model B” or “Raspberry Pi 2 Model B”. If in doubt, run the following command in the terminal:

$ uname -m

If the result returned starts with “armv6”, you are running a Raspberry Pi based on the older ARMv6 chipset and the next Node.js installation step will not work; otherwise, you are ready for the next step.

Let’s proceed with an installation of the long term support version of Node at the moment which is Node v8.9.2.

$ curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -

The previous command updates our Debian apt package repository to include the NodeSource packages.

Note: It’s generally a good idea from a security perspective to know what commands you are invoking on your system, especially since the command above invokes the script as the root user. If you want the technical details behind this script, you can launch the URL ( https://deb.nodesource.com/setup_8.x ) in your browser and review the code. The script carries out some ceremony to determine the Linux distribution you are running and instructs the Debian apt package system to add the NodeSource package repository as a trusted source for obtaining Debian packages. This enables us to install Node.js now and upgrade to more recent versions of Node.js when they become available.

Now that we have added the NodeSource package repository, we can move on and install Node.js!

$ sudo apt install nodejs

We can then test and see what version of Node we are running and launch the Node REPL as we discussed in the previous article as a quick test to confirm the installation was successful.

$ node -v
v8.9.2

Get a decent IDE

To be able to write some actual code you could use any notepad like application, but i strongly advise you to use a IDE. an IDE is an application that is aware of what you are coding and you can directly start your code. and more importantly pause your code at a specific location so you will be able to look inside variables. As i have written every node code in Microsoft visual Code. i'll advice you to do the same. Download Visual Studio Code

Get the NEEO-SDK examples and the NEEO-SDK itself.

First download the examples here. click on the "Clone or download"  button to download the examples. Extract the files to /Documents/Code/NEEO/examples/ or any other place but i'll use this as a reference. when you have your examples extracted open your command line (as seen in Get node JS). and go to your code/neeo directory.
 

Now lets install the NEEO-SDK !!! :-)
Type in "npm install neeo-sdk" without the quotes and all in lowercase.
 Don't mind the warnings for now (read the topic "start a new project" to learn how you should do this. without the warnings.)

Working with the examples.

Start your file explorer and browse to your examples directory, up to the following directory "neeo-sdk-examples-master\device\simpleDevice" right mouse click somewhere on empty space and select the option "Open with Code"
 
 

Now the Code application will start. You want to start with the index.js file by clicking "index.js" in the filebrowser on the left side of Code.

The index.js file is where you define your device and its capabilities.

Line 3, references to the NEEO-SDK nodejs library.
Line 4, references to the other file named controller.js.

From line 15, the device and its properties is defined.
From line 21, you see that two buttons are defined.

From line 26, the the SDK will discover a neeo brain and start its server.
 

Lets just start this code. by pressing F5 in Code.
notice that a debug window will popup with feedback.

 

Search for your SDK device

now open your NEEO app and add a new device.
Use this to search for your example driver

1. Simple
2. buttons
3. NEEO
4. foo

Notice that these are all defined in index.js and you can find your driver with this.
Now select the driver and actually add it.

 

Accessory devices do not have their own recipes like you are used with other type of devices. this is not a limitation of the sdk but rather the accessory device type.

Start one of your recipies for instance TV. then go to the menu and tap edit shortcuts. now tap Add shortcut, select your device driver (when you haven't provided a name its defaultly named Accessory. then select both Button A and Button B. Go back to the TV recipe, slide to the shortcuts and use the buttons while watching the debug output of code.

Note you will see a text appearing when you press one of the buttons. This is what the driver currently does. it displays text on your computer.

Adding some code to the buttons

Stop your code and open the controller.js file. the onButtonPressed function is called when you press a button.

Now pres just in front of line number 8, a red dot should show just in front of line 8.
Select the index.js file and start your code again by pressing F5.

Now see what happens when you press either Button A or Button B on the remote or APP.

The code will stop at line 8. Placing the red dot will pause the code every time it hits that part of the code. You are now able to see what values the variables deviceid and name contain by hovering your mouse pointer above these variables. Note the content of deviceid and lets place some code to Button A and Button B.

Change the code in controller.js to this:

module.exports.onButtonPressed = function onButtonPressed(deviceid, name) {
  console.log('[CONTROLLER]', name, 'button was pressed!');

  if (deviceid === "button-a") {
    console.log("Add some code here that you want to execute when button A is pressed.");
  }

  if (deviceid === "button-b") {
    console.log("Add some code here that you want to execute when button B is pressed.");
  }

};

Run the code again and use button A and B.

 

Code Snippets.

Variables

Strings

var first_name = 'Niels';
var middle_name = "de";
var last_name = "Klerk";
var full_name = first_name + ' ' + middle_name + ' ' + last_name; // Variables with '' or ""

 

Numbers

var age = 36;
var cost = 2.30;

 

Boolean

var true_or_false = true;
var true_or_false = false;

 

Null

var empty_var = null;

 

Array

var myarry1 = [1,2,3,4,5,6]; //0,1,2,3,4,5
var myarry2 = ['rood','zwart','geel']; //0,1,2
console.log(myarry2[1]); // zwart

 

Objects

var myobject = {"name" : "Niels de Klerk", "age" : 36, "awesome": true};

var myobject = {name: "Niels de Klerk", age: 36, awesome: true};

var myobject = {};
myobject.name = 'Niels de Klerk';
myobject.age = 36;
myobject.awsome = true;

 

Calculations

var number1 = 30;
var number2 = 80;
var number3 = 100;
console.log(number3 - number2);
console.log((number1 + number2) - number3);

number3++;
console.log("nummer " + (number3 + number2));

// -=min +=plus *=keer /=delen %=modulus

var number4 = number2++;
var number4 = ++number2
console.log("nummer " + number4);

var x = 10.345;
var x = x % 4 //% = mudulus
console.log(x);

x+=5; //x = x + 5;

Objects

var myobj = {
  name: "My object",
  value: 7,
  getname: function(){ return this.name; }
}

console.log (myobj.getname());

 

var user = new Object();
user.first = "Niels";
user.last = "de Klerk";
user.getname = function() { return this.first + ' ' + this.last; };

console.log (user.getname())

 

console.log ("\n\n// Objects");
var x = new Number("6");
console.log(x);

var s = myobj.name;
myobj.name = "New name";
console.log (myobj.name);
console.log (myobj.getname());

var name = myobj.getname();
myobj.getname = function() {return this.name;}
console.log (myobj.name);
console.log (myobj.getname());

 

Functions

function my_function(){
  console.log("Hello World!");
}

my_function();

 

function cl(debug_log_text) {
  console.log(debug_log_text)
}

cl("print this text");

 

cl(format("I'm 1337", " So "));
function cl(debug_log_text) {
  console.log(debug_log_text)
}

function format(text, moretext){
  text = "-~= " + text + moretext + " =~-";
  return text;
}

 

If then else case

x="10";
console.log("\n\n");
if (x==10){
  console.log("x has vallue 10");
} else {
  console.log("x is not 10");
}

if (x===10){ //type comparison
  console.log("x is an integer with value 10");
} else {
  console.log("x is no integer or not value 10");
}

if (x==9) {
  console.log("x is 9")
} else if (x==10){
  console.log("x is 10")
} else {
  console.log("x is not 9 and not 10")
}

if (x!=8){ console.log("x is not 8 not even a string 8"); }

if (x!==8){ console.log("x is not 8 or is no integer"); } //type comparison

if (x>=8){ console.log("x is 8 or greater"); }

if (x<11){ console.log("x is smaller then 11"); }

if (x>8 && x<11){ console.log("x is greater than 8 and smaller then 11"); }

if (x==10 || x==11){ console.log("x is 10 or 11"); }

if (!(x==11)){ console.log("x is not 11"); }


//////////////////////

// switch (case)

//////////////////////

x = 10;

switch (x) {
  case 9:
    console.log ("x = 9");
    break; // zonder break zou de vergelijking door alle cases gaan vergelijken.
  case 10:
    console.log ("x = 10");
    break;
  case 11:
    console.log ("x = 11");
    break;
  default:
    console.log("x is geen 9, 10 of 11");
 }

 

Loops

//////////////////////
// while loop
//////////////////////

console.log ("\n// while loop");
x = 10;
while (x>0){
  console.log("Nummer: " + x);
  x--;
}

//////////////////////
// Do while loop
//////////////////////

console.log ("\n// Do while loop");
  var names = ["Siska", 'Niels', 'Pelle', 'Spiderman', 'Batman'];
  var i=0;
do {
  console.log (names[i++]);
} while (names[i] != "Batman");

//////////////////////
// for loop
//////////////////////

console.log ("\n// for loop");
var names = ["Siska", 'Niels', 'Pelle', 'Spiderman', 'Batman'];
var i=0;
for (var i=0; i<=10; i++) {
  console.log (names[i]);
}

//////////////////////
// for loop array
//////////////////////

console.log ("\n// for loop array");
var names = ["Siska", 'Niels', 'Pelle', 'Spiderman', 'Batman'];
for (var i in names) {
  console.log (names[i]);
  if (names[i] == "Pelle") {break;}
}

 

Start a new project.

Lets start a project from scratch. this doesn't mean you can't still copy or use the example code to your new project so please don't hold back.

myProject

First open your command line and add a new directory for your project. as a reference i'll name it myProject. head into the directory and init your project by using "npm init".

This will ask you some basic questions to get your project started.

• The project name must be fully lowercase as shown in the code above.
• type in a version number of the code. i have chosen 0.0.1 in this example.
• provide your project with a description.
• provide the entry point. this is the name of the file that starts your project. default is index.js so i've kept it.
• test command: This is used to start automated testing of your code. my example makes no sense, just leave it blank for now. but remember to give it some attention later on.
• git repository, well i had to start with either the init or the git. leave it blank for now or if you know how to use git then add it. we can add it later on.
• Provide some keywords that match your project.
• Provide the author name, fill in your own name.... not mine....
• licensr: provide a license i.e. ISC or MIT
• Is this ok? well review your answers if your happy with it then enter yes.

Now you have created a package.json file with the minimal required parameters set. this file is just a json formated text file so feel free to edit it.

Github

Now lets create an account on github so you can publish your project.

When you have your account, create a new repository for your project. in this case i named it myProject.

 

When you have created the repository install git on your computer. go to this website and chose the version for your OS follow the installation instructions.

When you have git installed, enter the command line again and go back to your myProject directory.

Now enter the following commands step by step to connect and push your project to git. dont forget to change the git URL to your git URL.

echo "# myProject" >> README.md
git init
git add README.md
git commit -m "first commit"
git remote add origin https://github.com/<your username>/myProject.git
git push -u origin master

Now your empty project is pushed to your git repository.

Installing packages

Packages are small or large portions of code that are shared so everyone can reuse the code for his project. the neeo-sdk is a package so we use this as an example. We want to use the neeo-sdk in myProject so you need to get it and link it to your project as a dependency.

open your command line tool and go inside the project directory. now install the sdk like this:

npm install neeo-sdk -save

the -save part makes sure the dependency for neeo-sdk is added to your package.json. now you don't deed to include the actual neeo-sdk in your code. when someone uses your code they only have to enter "npm install" and the packages that you have used will also be installed without providing them as code to your project.

If you want to automate a specific product with your code, have a search on the internet for a node package, chances are that a package already exists. Install these packages just like the neeo-sdk with the -save option included to have the dependency added to your package.json.

index.js

with the npm init command the entrypoint of your code is made index.js. open visual code inside the myProject folder. add index.js as a file and start coding.

Updating your GIT.

after you made some changes to your code you will see that your code is different from the git code:

 

To commit your code you can enter a message, (this will be visible to git) like fixed bug x. or added feature y. you will commit it by using Ctrl + Enter.

Now you need to push the code changes to git.:

 

Now check your git to see the changes you have made.

 

Naming

Naming is very important with NEEO. Based on the device type and button names the physical buttons will be mapped and control widgets will be made available.

Device types.

The following device types are supported by the SDK, They are all in UPPERCASE.

• ACCESSOIRE

• AVRECEIVER

• DVB

• DVD

• GAMECONSOLE

• LIGHT

• MEDIAPLAYER

• PROJECTOR

• TV

• VOD

The following devices can be hacked in the SDK to add a device with this type to NEEO. Using these device types will result in drivers that have parts that won't work as expected or even cause serious issues. Be aware that these issues will NOT be supported.
 

• AUDIO
  I haven't tested it but expect some issue could occur.

• SOUNDBAR
  I haven't tested it but expect some issue could occur.

• TUNER
  I haven't tested it but expect some issue could occur.

• THERMOSTAT
  Expect major issues. Don't use this one unless you really know what you're doing.

• CLIMA
  Doesn't do much, can be used for shortcuts. but expect issues.

• SONOS
  Expect major issues. Don't use this one unless you really know what you're doing.

 

Capability names (Button names)

There are reserved button names that will be bound to specific widgets or hard buttons.
The following image displays the buttons that will automatically mapped to the hard buttons when the devicetype is TV.
 
(Might be the same or different for other device types.)

 

Mediacontrol button names

• PLAY

• PAUSE

• STOP

• SKIP BACKWARD

• SKIP FORWARD

• FORWARD

• PREVIOUS

• NEXT

• REVERSE

• PLAY PAUSE TOGGLE

• INFO

 

Color button names

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

 

Digit button names

• DIGIT 0

• DIGIT 1

• DIGIT 2

• DIGIT 3

• DIGIT 4

• DIGIT 5

• DIGIT 6

• DIGIT 7

• DIGIT 8

• DIGIT 9

• DIGIT SEPARATOR

• DIGIT ENTER

 

Direction button names

• CURSOR DOWN

• CURSOR LEFT

• CURSOR RIGHT

• CURSOR UP

• CURSOR ENTER

 

Additional buttons

• ENTER

• EXIT

• HOME

• GUIDE

 

Menu buttons

• MENU
• BACK

 

Power button names

• POWER OFF

• POWER ON

• POWER TOGGLE

 

Tuner button names

• CHANNEL UP

• CHANNEL DOWN

 

Format button names

• FORMAT 16:9

• FORMAT 4:3

• FORMAT AUTO

• FORMAT SCROLL

 

Volume button names

• VOLUME UP

• VOLUME DOWN

• MUTE TOGGLE

 

Input button names

• INPUT 1
• INPUT 2
• INPUT AM
• INPUT AUX 1
• INPUT HDMI 1

 

All button names i could find.
These are not necessarily known as a 'special' button by the remote. these are just those that i could find in my API/configuration

• #
• *
• 3D
• ALT-F4
• AUDIO
• BACK
• CANCEL
• CAP LOCK
• CHANNEL DOWN
• CHANNEL UP
• CLEAR
• CLEAR QUEUE
• CLR
• CURSOR DOWN
• CURSOR ENTER
• CURSOR LEFT
• CURSOR RIGHT
• CURSOR UP
• DELETE
• DIGIT 0
• DIGIT 1
• DIGIT 10
• DIGIT 10+
• DIGIT 11
• DIGIT 12
• DIGIT 2
• DIGIT 3
• DIGIT 4
• DIGIT 5
• DIGIT 6
• DIGIT 7
• DIGIT 8
• DIGIT 9
• DIGIT ENTER
• DIGIT SEPARATOR
• DIMMER
• DIRECT TUNE
• DISPLAY
• DVD ANGLE
• DVD AUDIO
• E MANUAL
• EXIT
• FORMAT 16:9
• FORMAT 4:3
• FORMAT AUTO
• FORMAT SCROLL
• FORWARD
• FUNCTION BLUE
• FUNCTION GREEN
• FUNCTION ORANGE
• FUNCTION RED
• FUNCTION YELLOW
• GUIDE
• HOME
• INFO
• INPUT 1
• INPUT 10
• INPUT 11
• INPUT 12
• INPUT 13
• INPUT 1394
• INPUT 14
• INPUT 15
• INPUT 16
• INPUT 17
• INPUT 18
• INPUT 19
• INPUT 2
• INPUT 20
• INPUT 21
• INPUT 22
• INPUT 23
• INPUT 3
• INPUT 4
• INPUT 5
• INPUT 6
• INPUT 7
• INPUT 8
• INPUT 9
• INPUT AM
• INPUT AUX 1
• INPUT BD/DVD
• INPUT BLUETOOTH
• INPUT CABLE/SATELLITE
• INPUT COMPONENT 1
• INPUT COMPONENT 2
• INPUT COMPOSITE 1
• INPUT COMPOSITE 2
• INPUT DVI 1
• INPUT FM
• INPUT GAME
• INPUT HDMI 1
• INPUT HDMI 2
• INPUT HDMI 3
• INPUT HDMI 4
• INPUT NET
• INPUT PC
• INPUT PHONO
• INPUT S VIDEO 1
• INPUT SCART 1
• INPUT SCROLL
• INPUT STREAM BOX
• INPUT TUNER 1
• INPUT TV
• INPUT TV/CD
• INPUT USB 1
• INPUT VGA 1
• INPUT VGA 2
• KIOSK
• LANGUAGE
• LIVE TV
• MENU
• MENU DISC
• MENU DVD
• MENU MAIN
• MENU POP UP
• MENU SMART HOME
• MENU TOP
• MESSENGER
• MODE
• MODE GAME 1
• MODE MOVIE/TV
• MODE MUSIC
• MODE STEREO
• MOUSE
• MUTE TOGGLE
• MUTE UNMUTE
• MY APPS
• MY DISTRIBUTED AUDIO
• MY HOME
• MY LIGHTS
• MY MUSIC
• MY PICTURES
• MY SECURITY
• MY THERMOSAT
• MY TV
• MY VIDEOS
• NEXT
• NEXT TRACK
• OEM1
• OEM2
• ONLINE SPOTLIGHT
• ONLINE SPOTLIGHT PARTNER SPECIFIC APP
• OPEN/CLOSE
• OPTIONS
• OUTPUT RESOLUTION
• PAUSE
• PLAY
• PLAY PAUSE
• PLAY PAUSE TOGGLE
• POWER OFF
• POWER ON
• POWER TOGGLE
• POWER_ALL_OFF
• POWER_OFF
• POWER_ON
• PRESET DOWN
• PRESET UP
• PREVIOUS
• PREVIOUS CHANNEL
• PREVIOUS TRACK
• PRINT
• RADIO
• RANDOM
• REBOOT
• RECORD
• RECORDED TV
• REPEAT
• REPEAT TOGGLE
• REPLAY 10 SEC
• REVERSE
• SEARCH
• SHUFFLE TOGGLE
• SKIP BACKWARD
• SKIP FORWARD
• SLEEP
• SMART HUB
• SPEAKER A
• SPEAKER B
• STOP
• SUBTITLE
• TELETEXT
• TITLE
• TONE
• TONE +
• TONE -
• TOOLS
• TUNING DOWN
• TUNING UP
• UN PAIR
• VOLUME DOWN
• VOLUME UP
• WINDOWS
• WRITE