Creating a NodeServer
Polyglot itself is a middleware application that integrates 3rd party devices directly into the ISY. It itself doesn't not speak to these 3rd party devices directly. That is accomplished by plugins otherwise known as NodeServers. Each NodeServer can do any number of things and have many individual nodes. For this example we are going to use the LiFX NodeServer as an example. In this guide we will walk through creating the LiFX NodeServer from the beginning of development all the way through making it available in the NodeServer store on Polyglot. It is important to note that with Polyglot version 2 the MQTT protocol is used as the IPC(inter-process communication). This allows for us to have NodeServers that are NOT local to Polyglot itself. While this is very powerful, most of you will still typically run the NodeServers locally to Polyglot. If you install a NodeServer via the Store, then it will be run locally.
Currently in the works is an API for several different languages, however currently the Python3 API is the only fully functional module. That being said, I will outline the IPC communication standards here that you are welcome to replicate in any language as needed.
Python 3.5+ was chosen specifically to mirror the async nature of this type of application. Python 3.5 comes with similar asynchronous co-routines that Polyglot itself has, and it also avoids the silly Python2 endless loops that can kill CPU's.
The Python 3 API Module is available for your assistance.
Any folder under the ~/.polyglot/nodeservers/ folder is scanned for the files 'server.json' and 'profile.zip'. These two files are required for Polyglot to recognize it as a NodeServer.
The server.json is the description and data for your NodeServer. The important fields are: name, executable and optionally install.
{
"name": "LiFX",**
"docs": "https://www.lifx.com",
"type": "python3",
"executable": "lifx-poly.py",**
"install": "install.sh",**
"description": "Add LIFX control to the ISY994.",
"notice": "\"LIFX\" is trademarked., see http://www.lifx.com for more information. This Node Server is neither developed by nor endorsed by LIFX.",
"credits": [
{
"title": "polylifx: A Python library for LIFX",
"author": "James Milne (Einstein.42)",
"version": "0.1.6",
"date": "November 8, 2017",
"source": "https://github.com/Einstein42/lifx-nodeserver",
"license": "https://github.com/Einstein42/lifx-nodeserver/blob/master/LICENSE"
}
]
}
When you distribute your NodeServer make sure that the executable and install files are bash run-able (aka shebang'd) and that they are chmod 755 (or +x). This allows Polyglot to run them correctly. To test this just run your install script. ./install.sh should work.
The profile.zip file is the node definitions that ISY expects for any node added to it. Here is the documentation from UDI. You must have the nls, editors, and nodedefs created using that format. Look at the LiFX profile.zip as an example.
The install script is located in the main directory and named in the server.json properties. This script should be +x or chmod 755 when distributed. Polyglot will automatically run this script after the NodeServer is installed via the Store. If the NodeServer is installed manually it must be run manually before being added to Polyglot. For the LiFX NodeServer example, we need to have several modules installed in Python for the NodeServer to function properly.
So our install.sh looks like this. I'm telling python 3's pip program to install all the modules in the requirements.txt file at the user level (not globally). Keep in mind this script does NOT run as root.
#!/usr/bin/env bash
pip3 install -r requirements.txt --user
The requirements.txt that the install script references is created by doing pip freeze > requirements.txt in your project folder directory. These should typically be developed in a virtual environment (venv) to make things nice and clean. These are the python requirements for the LiFX NodeServer.
bitstring==3.1.5
click==6.7
lifxlan>=1.1.5
paho-mqtt>=1.3.0
polyinterface>=1.0.5
python-dotenv>=0.6.4
The executable property in the server.json is run via bash in a separate process directly via Polyglot (on local NodeServers) after the install process has completed and the profile.zip has been installed. The shebang (first line of a bash script) is what is called the interpreter for the program. In this case we are using Python 3. So the first line of the executable file 'lifx-poly.py' is
#!/usr/bin/env python3
This is one of the ways Polyglot allows for language agnosticism in it's NodeServers.
Jump over to the polyinterface README to see how to use the Python 3 API.
Now you have your NodeServer built, everything works fine. Time to add it to Polyglot!
Open Polyglot:
Login to Polyglot:
Click on Add NodeServer. Choose type Local, and then you will see a drop down list of all installed NodeServers found by Polyglot. This refreshes every time the page is loaded. Then choose a Profile Number to install it into. You will only see available Profile Numbers. If the ISY already has a slot filled, it will not be available.
Confirm that the ISY will reboot. This step automatically uploads the profile.zip from the NodeServer folder to the ISY and reboots it to take effect. No manual steps required.
Wait 60 seconds for the ISY to reboot. Then Polyglot automatically starts the NodeServer via the executable property in the server.json
Watch the log file in real time via the Log button on the Navigation bar.
Once the NodeServer starts. Check the Dashboard again. Notice it now says connected and shows how many sub-nodes it has.
Click on Details then Nodes and see real time information on the nodes themselves.
Click on Log in the details page to see the real-time log for the NodeServer itself.
Away you go. If you are troubleshooting, you can tail the log file in ~/.polyglot/nodeserver//logs/debug.log or watch it live in the Polyglot frontend. You can start, stop or restart, the NodeServer under Details > Control.
Good luck!