Custom drivers overview, example to get you started


Level:
Expert
Author:
published:
Modified:

Custom drivers are drivers you write in the web interface, using a web based editor in Javascript. The link to the API is at the bottom of the manual page.


To first get a little idea, a below is a little video clip with an Arduino with a simple LED which runs a custom Arduino sketch, and with an in Javascript (ECMAScript) written custom driver is able to communicate with the server.

What are scripted drivers

As stated scripted drivers are created with javascript and are inserted in the PiDome drivers ecosystem. Normally the setup is like this:
Hardware driver (like for serial connections) -> Software driver -> Devices on the server.
With scripted drivers these scripts are inserted into the Software driver. They take over the part where the translation takes place between the hardware and devices. This creates the following path:
Hardware driver ->Software driver -> (script) -> Software driver-> Devices on the server.

The scripts get access to methods inside the driver which are normally also used when these drivers are created in java, but then in the Javascript way.

The editor

The current implementation is an alpha version meaning the editor is very slimmed down and only includes line numbers and code highlighting. We are investigating other scripting possibilities for PiDome but first want community input for this functionality.

The editor is made up of different parts, basic information with name and description, a debug window, API manual and the editor self.

Name and description
This part is simple, give the script a name which will appear when you connect a piece of hardware. Te description is some text for describing your script.

Debug window
Currently disabled, but this window will give you the possibility to debug your script where you will see information passing by in real time

API Manual
The API manual describes the extra available functionalities next to the default ECMAScript functions. It describes globally assigned variables, how to communicate with devices, utilize the driver and will in the future explanations on how to implement your own device discovery and how to manipulate the web front end.

Editor
In the editor you will modify your code. It supports code highlighting and line numbers. As this feature will grow more functionalities will be added like key shortcuts and improved visuals.

namedescdebug  editor  api

Included example

As with the introduction with this functionality we also included an example. This example is extremely simple it has been already scripted and we also created a simple Arduino setup.

Try the Arduino example out

In the above clip an Arduino with a led and push button is shown with bi-directional communication. The button in the web interface turned on/off the led and the push button on the switched both the led and the button in the web interface. The code of the above clip is the example.

To get started you can download the zip file “pidome-example-driver-impl.zip“. This file contains the Arduino sketch, the schematic as an png image and fritzing file. With this you can built the arduino before attaching it to the server.

Important: If you have a fresh install of the server the script is present on the server. If you have updated the server you need to copy the contents of the file pidome_driver/driver.js and paste it in the editor. Read on how.

If you did a fresh install you can skip this part, if you have upgraded the server, got to “Management > Drivers > Custom drivers”. In the list click on the edit button. In the up following window you will see the editor, copy the contents of the file driver.js in the editor. Click the “Save (and restart)” button.

Connect your Arduino

First build your Arduino according to the schematic found in the zip file and upload the Arduino sketch to you Arduino also found in the zip file.

Now you can connect the Arduino to the server. After connected go to the page “Management > Peripherals > Peripherals”. Here you will see your Arduino connected. Click on it and select the settings like in the below screenshot:

connectarduino

After the Arduino has been connected you only need to add a device to the server. We already have the specific custom device added to the server. Go to the page “Management > Devices > Add/Remove/Settings” and click the Add device button.

Select the device as shown in the screenshot. Give the device a name, and change the address from “null” to number zero “0” (Without the double quote characters (“))

add_device_1

Click add device. Go to the “Control > Devices” page. Click on the just added device, and you are now able to switch the LED on and off. The first command can take some time as it is part of a compilation process, but after the first time it should be a lot faster. Also you can turn on and off the LED with the push button on your breadboard. Also with this the first time can take some time. When you press the push button you will see the button in the web interface change state (on to off and vice verse).

How does this example work

A short explanation of how it all works. The code on the Arduino is leading on how it should be interpreted on the server.

Arduino code

The explanation is limited on the communication format as the code on the Arduino can be a lot more optimized but for now is sufficient to act like an example.

Take a look at this line:

Serial.print("0:set:switchled:");Serial.println((ledState==HIGH)?"true":"false");

Explained:
0: This device’s address, will be explained later, remember that above stated to set the address to zero.
set: This is the command to set a value, there is also get if you want to know the current value on the server.
switchled: The button on the the server is linked to this.
true/false: Switch the state of the button on the server.
println at the end is used to make sure a newline character is added as it is the delimiter for the whole command.

If you take a look at the code on the Arduino for receiving text you will see it is the exact opposite way.

Driver code

The driver code in fact does exactly the same as the Arduino code, but instead of the Arduino way it is written in Javascript. The following code sends data to the hardware:

var address = device.getAddress() ; // The device knows it's own address. 
var controlid = request.getControlId() ; // The request object knows which control has done it.
var value = request.getCommandValueData() ; // The request knows which value data is bound to the controls command.
var toSend    = address + ":set:" + controlid + ":" + value;
sendData(toSend) ;

Do you see the similarities between the arduino code and the driver? Explained:
address: The address of the device, which in this example is “0”
set: A command to set a state on the hardware
controlid: This is the id the hardware uses to identify where the set command was for. In this case “switchled”
value: This is the value to send. In this example the text true or false to turn on/off the LED.

To conclude the command means: Set the led identified with “switchled” to true or false for device at address 0.

Where do the “switchled” and “true/false” come from?

A device on the server does not just appear out of nothing, you have to create it first. Let’s take a look at the device controlling the LED on the server.

Go to the page “Management > Devices > Custom devices”. On this page you see a list of custom devices. A custom device is a device you create yourself if a device is not available on the server. Or if you are maker and only create your own custom devices. Click on the device “Custom serial device”. You are now presented with the device editor.

The device editor

In the device editor you build you device. You add/delete/create device control groups and controls (buttons/sliders/toggle buttons/etc..) Take a look at the two screenshots below to see the similarities:

custom-device-1 add_device_11

Here there is a group called “A group” where the control “swith a led” has been placed.  The groups are used to be able to group specific controls together. Click on the little wrench next to the “Switch a led” control. You will get a popup of this specific toggle button.

Take a look to the screenshot below:

custom-device-control-detail

In this screenshot is marked how the control is identified and what values are send to the hardware. A good try out would be if you add an extra toggle button. and give this the control id: “switchled2”. All the other values are the same as in the screenshot. You can add a toggle button control by drag and drop it from the list on the left to the group on the right.

Take a look at the video above to see how you can see the values being send by enabling the logging. Take a close look to the log file (open a terminal, go to the pidome-server installation directory and execute command “tail -f logs/system/appLog.txt”. The log file will be updated in the terminal in real time.)

When you look at the log you will see what data is being send. Try to modify your arduino code to react on the id “switchled2” and add for example an extra LED.

 The API of the Custom drivers is at the Custom drivers API page

Good luck and have fun with writing your own custom driver or try out the current example and extend it. If you got any questions post them in the forum at the dedicated “Custom drivers” topic:http://forum.pidome.org/viewforum.php?id=21

Latest news/blog

Friends of PiDome

Hubbit.nl
Webshop of the most prominent dutch tech magazines
RFXCOM
Affordable 433Mhz RF transceivers
Atlassian
Products for teams, from startup to enterprise
UniPi.technology
Home-automation hardware manufacturer

Latest added technology

  • SMS
  • Z-Wave
  • PushBullet
  • PlugWise
  • MQTT

Some project stats

Open Hub project report for PiDome Platform

Other

Official NLJUG Member