ArduinoPi 1.0 includes an API

Posted on September 4, 2012 by Fritz

UPDATE: New version 1.5 now supports wireless Bluetooth connections!

I updated the ArduinoPi to version v1.0, meaning I finally created a PHP class to handle everything. The basic concept remains the same and the commands aren’t changed at all, but I updated the PHP side, I plan on updating the Arduino side but for now it only has 105 lines of code, no reason for a library. The GitHub with changes is found here.

ArduinoPi 1.0: API overview

The ArduinoPi will now check for a valid port and supports the Arduino Mega 2560, ADK, UNO and Leonardo. In general if you issue the command PWM on a port that doesn’t support it, you will receive an error. Note that the Arduino code uses Serial1, if you use Software Serial library you need to change it yourself!

I’ve also changed the PHP serial class and added better error handling. The functions will now throw a phpSerialException instead of using trigger_error. I also made it a bit faster and fixed/changed some errors/code I found.

Since the ArduinoPi class extends the Serial class all the configuration options (like baud rate) are available using the ArduinoPi class.

Lastly, it’s now also possible to use the keywords “high” and “low” to indicate 0 or 255.

ArduinoPi 1.0: Using POST or GET

To switch ports the user has 2 options, using a POST or a GET. For example to switch port 2 with PWM high a user can go to the following URL (raspberrypi.local points to your Raspberry Pi IP address).

http://raspberrypi.local/api/pwm/2/high

But the user can also use a POST request, making a POST to the following URL:

http://raspberrypi.local/api/

With the variables mode set to “pwm” and data which is an array containing 2 and “high”. The result will be the same, GET is quite handy for debugging purposes.

ArduinoPi 1.0: Configuration

First we need a bit of configuration. For people using Apache you’re in luck, the .htaccess file will take care of URL rewriting. People using lighttpd (like me) add the following line in your lighttpd.conf:

1	url.rewrite-once = ( "^/api/(.*)$" => "/api/index.php?handler=$1" )

Then we open the file index.php located in the api folder. Only one line is important:

1	$arduinopi = new ArduinoPi(MEGA2560);

Change this line to your device, using the keywords: UNO, LEONARDO or ADK. Default the baud rate will be 115200, this can be changed by using the following command. Note that changing the baud rate in PHP means that you also need to change it in your Arduino sketch.

1 2	$arduinopi = new ArduinoPi(MEGA2560); $arduinopi->confBaudRate(57600);

Users more experienced with PHP can open up the arduino_pi.class.php and add their own commands to the API. The process function takes care of all the API handling.

ArduinoPi 1.0: Command Set

Calling commands using the ArduinoPi 1.0 is changed a lot so I will cover the eight default commands. Every command can be called using ether GET or POST. I use jQuery to dynamically call the ArduinoPi API when a user clicks a button.

PWM

The PWM option of the API will check for the right port and checks if the values are between 0-255. The code demonstrates the ArduinoPi 1.0 API request using an AJAX GET request when a user presses a button.

$("#pwm-button").click(function () {

$.get("/api/pwm/2/255");

});

It’s also possible to use a POST request:

$("#pwm-button").click(function () {

$.post("/api/", {mode: "pwm", data:[2, "high"]});

});

The “high” and “low” keywords can also be used in jQuery. Both commands are equal, don’t mix a GET and POST request this will result in unexpected behavior.

Digital

The analog and PWM ports can be used as digital outputs. The ArduinoPi 1.0 only accepts the following values: high, low, 0 or 255. Any other value will throw an exception. The code below will switch port 2 low using an AJAX POST request when clicking on the button.

$("#digital-button").click(function () {

$.post("/api/", {mode: "digital", data: [2, "low"]});

});

Analog

The analog function is only used for reading an analog port. To write an analog port use the digital option of the ArduinoPi 1.0 API. The code below will read port A0 using an AJAX GET, the result is displayed next to the button. Notice that it’s allowed to use A0 for selecting an Analog port. An ArduinoPi 1.0 GET example:

$("#analog-button").click(function() {

$.get("/api/analog/A0", function(data) {

$("#analog-value").html(data);

});

Multiple PWM

The multiple PWM allows a user to switch multiple ports at once using PWM. The ports and values can be written consecutively, creating a long API request. Note that any invalid port/value will be omitted from the request, no error will be reported. An ArduinoPi 1.0 POST example.

$("#multiple-pwm-button").click(function () {

$.post("/api/", {mode:"multiple-pwm", data:[2, 255, 3, 125, 4, 255]});

});

Note: if a GET doesn’t work check that your URL didn’t excite the 2000 char limit, when in doubt just use the POST version.

Multiple digital

Multiple digital works the same way as multiple PWM. The digital ports only accept a value of 0, 255, “low” or “high”. If a port is switched with another value it will be omitted from the API request. An ArduinoPi 1.0 GET example:

$("#multiple-digital-button").click(function () {

$.get("/api/multiple-digital/2/high/3/low/4/high");

});

Multiple Analog

Multiple Analog will read the different analog ports specified and returns the value as an array. Again its possible to use A0 and A1. Note that the Arduino makes up a value if nothing is attached to the port itself. An ArduinoPi 1.0 API POST example:

$("#multiple-analog-button").click(function() {

$.post("/api/", {mode:"multiple-analog", data:["A0", "A1"]}, function (data) {

$("#analog-multiple-value").html(data.result[0]+" - "+data.result[1]);

});

Analog File

The API command will do exactly the same as Analog, but it writes the result back to a specified JSON file. The first parameter is the analog port, the second, the JSON file in the data folder. Note that this file must be created and readable/writable. The extension .json is not allowed in the API call.

$('#analog-file-button').click(function () {

$.post("/api/", {mode: "analog-file", data:[0, "live-data"]});

});

Delete File

The API command will just open the file and clear everything in it. This is useful for starting a new session of data logging on the Arduino. An ArduinoPi 1.0 POST example:

$('#delete-file-button').click(function () {

$.post("/api/", {mode:"delete-file", data:["live-data"]});

});

ArduinoPi 1.0: Error Reporting

All the errors are thrown and catch when using the ArduinoPi API. When using the API functions on their own always catch for Exception and phpSerialException and use your own error handeling to deal with possible exceptions. A little example:

$arduinopi = new ArduinoPi(MEGA2560);

try {

$arduinopi->writePWM(2, 255);

} catch (phpSerialException $e) {

echo $e->getMessage();

} catch (Exception $e) {

echo $e->getMessage();

}

When using the ArduinoPi 1.0 API, all errors are returned in JSON format and can be read using jQuery. When are request is successfully executed the state variable will be “success” if not then it will be “failed”. If we requested an Analog reading the result will be available in the result variable (this can be an array or int). A little example:

$("#analog-button").click(function() {

$.get("/api/analog/A0", function(data) {

if(data.state === "success") {

$("#analog-value").html(data);

} else {

$("#error").html(data.error);

}

});

The error message will be available in the error variable. It’s now possible to give error and feedback to an user using the ArduinoPi API.

Conclusion

I’ve updated the github to include the new changes, almost everything changed. The examples from last time are also updated and use the new ArduinoPi API. For new features or issues please use github issue tracker to let me know. As always feel free to copy/change the code but leave a link back to my blog .

ArduinoPi Web based Controller for Arduino

Posted on August 31, 2012 by Fritz

UPDATE: New version found here: http://www.fritz-hut.com/arduinopi-v1-5-bluetooth-dongle-support/

The ArduinoPi is a web-based controller for the Arduino using the Raspberry Pi. The advantage of using a Raspberry Pi (€28) is that its cheaper than an Ethernet shield (€35) and actually more useful.

I talked about connecting the Raspberry Pi and Arduino over a serial connection and how to install and configure PHP serial class so PHP can talk with the Arduino.

The principal behind ArduinoPi

First a little clarification, the ArduinoPi isn’t really a library or a command set or an out of the box controller, its more a proof of concept using already know programming languages. If you want to use it be ready for some PHP, CSS, HTML, C++ and jQuery!

The principal is as follows: The Arduino is connected as a slave device, meaning it waits for a command, execute it and maybe return a value or something. Everything must be initiated from the web browser. A true slave device.

It’s also possible for the Arduino to execute its own program and the ArduinoPi can then be used as a controller to switch variables. For example I have an automatic light switching system but using the ArduinoPi controller and my web browser I’m able to manually override it.

The command set of the ArduinoPi

The Arduino will check for a valid command. Every command starts with @ and ends with :, variables can be separated with a comma. Of course other commands can be added yourself, I’ve found that these are the basics and cover enough to make some interesting interfaces.

Basic switch-port-high command

@6,255:

This command is sent to the Arduino, for example this will switch port 6 high (255 = HIGH). The first value in this command must be between 0-99, which corresponds to the port number. Note that there is no checking so always see the port is set in OUTPUT mode and you are addressing the right port.

RGB command

I’ve also added a RGB command for LEDs, this is a special command and is constructed as follows:

1	@101,245,23,0:

The 101 indicates the special command mode and the following 3 values are just the RGB values. In my example setup I’ve added 3 RGB LEDs and they all get turned on to the right value using the RGB command.

Read Sensor Command

The last command is the sensor command. It will read an analog sensor value and return it to the PHP script.

@102,6:

The 102 indicate a special command and the following value indicates the port that should be read using analogRead().

My test setup for the ArduinoPi

I’ve used the following components for testing various functions: 3 RGB LEDs + resistors and a light sensor. The example will work with the following configuration. The image does not contain the connection setup with level converter circuit from last time (to cut some space).

The Arduino code for ArduinoPi

int ledstate = LOW;
String cmd;
bool cmdRec = false;
void setup()
{
	//Start the connection with the Raspberry Pi
	Serial1.begin(115200);
	// Start the connection with the Laptop
	Serial.begin(115200);
	for(int i=2; i <= 10; i++) {
		pinMode(i, OUTPUT);
	}
}

void loop()
{
	handleCmd();
}

void serialEvent1() {
	while(Serial1.available() > 0 && Serial1.writeable()) {
		char inByte = (char)Serial1.read();
		if(inByte == ':') {
			cmdRec = true;
			return;
		} else if(inByte == '@') {
			cmd = "";
			cmdRec = false;
			return;
		} else {
			cmd += inByte;
			return;
		}
	}
}

void handleCmd() {
	if(!cmdRec) return;

int data[4];
	int numArgs = 0;

int beginIdx = 0;
	int idx = cmd.indexOf(",");

String arg;
	char charBuffer[16];

while (idx != -1) {
		arg = cmd.substring(beginIdx, idx);
		arg.toCharArray(charBuffer, 16);

// add error handling for atoi:
		data[numArgs++] = atoi(charBuffer);
		beginIdx = idx + 1;
		idx = cmd.indexOf(",", beginIdx);
	}
	// And also fetch the last command
	arg = cmd.substring(beginIdx);
	arg.toCharArray(charBuffer, 16);
	data[numArgs++] = atoi(charBuffer);

// We just want to switch a port so lets change the values
	if(data[0] < 100) {
		execCmd(data);
	} else {
		execCmds(data);
	}
	cmdRec = false;
}

// Select just one port and enable it
void execCmd(int* data) {
	analogWrite(data[0], data[1]);
}

// For advanced function like switch all the leds in RGB
void execCmds(int* data) {
	switch(data[0]) {
	case 101:
		// first the red part of the RGB
		// for me 4,7,10
		analogWrite(4, data[1]);
		analogWrite(7, data[1]);
		analogWrite(10, data[1]);
		// green: 3, 6, 9
		analogWrite(3, data[2]);
		analogWrite(6, data[2]);
		analogWrite(9, data[2]);
		// blue: 2, 5, 8
		analogWrite(2, data[3]);
		analogWrite(5, data[3]);
		analogWrite(8, data[3]);
		break;

case 102:
		// request analog readout!
		int sensor = analogRead(data[1]);
		Serial1.println(sensor);
	}
}

100

101

int ledstate = LOW;

String cmd;

bool cmdRec = false;

void setup()

{

//Start the connection with the Raspberry Pi

Serial1.begin(115200);

// Start the connection with the Laptop

Serial.begin(115200);

for(int i=2; i <= 10; i++) {

pinMode(i, OUTPUT);

}

void loop()

{

handleCmd();

}

void serialEvent1() {

while(Serial1.available() > 0 && Serial1.writeable()) {

char inByte = (char)Serial1.read();

if(inByte == ':') {

cmdRec = true;

return;

} else if(inByte == '@') {

cmd = "";

cmdRec = false;

return;

} else {

cmd += inByte;

return;

}

void handleCmd() {

if(!cmdRec) return;

int data[4];

int numArgs = 0;

int beginIdx = 0;

int idx = cmd.indexOf(",");

String arg;

char charBuffer[16];

while (idx != -1) {

arg = cmd.substring(beginIdx, idx);

arg.toCharArray(charBuffer, 16);

// add error handling for atoi:

data[numArgs++] = atoi(charBuffer);

beginIdx = idx + 1;

idx = cmd.indexOf(",", beginIdx);

}

// And also fetch the last command

arg = cmd.substring(beginIdx);

arg.toCharArray(charBuffer, 16);

data[numArgs++] = atoi(charBuffer);

// We just want to switch a port so lets change the values

if(data[0] < 100) {

execCmd(data);

} else {

execCmds(data);

}

cmdRec = false;

}

// Select just one port and enable it

void execCmd(int* data) {

analogWrite(data[0], data[1]);

}

// For advanced function like switch all the leds in RGB

void execCmds(int* data) {

switch(data[0]) {

case 101:

// first the red part of the RGB

// for me 4,7,10

analogWrite(4, data[1]);

analogWrite(7, data[1]);

analogWrite(10, data[1]);

// green: 3, 6, 9

analogWrite(3, data[2]);

analogWrite(6, data[2]);

analogWrite(9, data[2]);

// blue: 2, 5, 8

analogWrite(2, data[3]);

analogWrite(5, data[3]);

analogWrite(8, data[3]);

break;

case 102:

// request analog readout!

int sensor = analogRead(data[1]);

Serial1.println(sensor);

}

SerialEvent1 gets called every time data is available on the Serial1 interface, the function will check for a valid command, if it found a valid command (meaning it starts with @ and ends with : ) it will switch the Boolean value cmdRec to true, in the loop function we always call handleCmd(); now the cmdRec is set so we process the command. The while loop will split out the values and save them in the data array. Because we also need the last command we repeat the same stuff out of the while loop once more, I should fix that btw.

If the first value has a number lower than 100 we turn the port on with the second value as second parameter, else we process it like a special command. I’ve used a switch so you can add your own special commands as needed.

The web browser interface for the ArduinoPi

As interface I decided to use 4 pages each showcasing the commands. I made use of the following scripts/plugins/blogs/code and I would like to thank the original authors: Bootstrap, jQuery, Farbtastic Color Picker, jQuery color picker using Farbtastic and jQuery UI and flot. The complete source is on Github, I’ll give a short overview of the different pages.

Hover example

The Hover example works as follows, we add a jQuery hover handler over all the buttons. If the user moves over the button we request the value of the button, this value corresponds with the port we want to switch. We then send an ajax call to a PHP script that will handle the communication with Arduino and sending the right command. For a value we use 255. When the mouse leaves the button we do the same but use the value 0 to turn it off.

$(".hover-light > button").hover(function () {

var port = $(this).val();

$.post("php-ajax/cmd.php?mode=hover", {port:port, value:255});

}, function () {

var port = $(this).val();

$.post("php-ajax/cmd.php?mode=hover", {port:port, value:0});

});

Color picker

The color picker works as follows. The user selects the desired color the RGB LEDs should produce and then click on the big square. An AJAX request is then made to a PHP page that will send the special command 101 with the right values for red, green and blue.

$("#swatch").click(function () {

var red = $("#red").slider("value");

var green = $("#green").slider("value");

var blue = $("#blue").slider("value");

$.post("php-ajax/cmd.php?mode=picker", {red:red, green:green, blue:blue});

Basic Sensor Display

This has nothing to do with the Arduino, but remember my light measurements? I always had trouble displaying them and I’ve included an example how you can display graphs really easy using this tool. It’s really useful for offline measurements that are saved on a SD card and then need to be represented in a browser.

Live Sensor Data

This will execute live measurements. A PHP cron job needs to be setup to run every minute as follows:

1 2	root@raspberrypi:/home/pi# crontab -e * * * * * php /opt/www/php-ajax/cron.php

The PHP script will execute a measurement and save the value in a JSON file. On the client side we refresh the graph every minute with an Ajax call. I’ve also include two buttons to clear the log or request your own value.

Conclusion

I gave a bare bone, alpha release of my ArduinoPi controller. This example can be expanded all the way and check the Github source, I’ve added a lot of comments to get people started.

There is one big limitation, the server (Raspberry Pi) always has to request data from the Arduino. It’s not possible to send data from the Arduino to the Raspberry Pi and then magically update the browser. When using for example Processing, it is possible to have a more live connection and build an interface in JAVA. But this web interface is accessible for any smartphone or laptop (assuming you don’t run IE6).

Fritz-Hut

About Electronics and Informatics

Tag Archives: jQuery

ArduinoPi 1.0 includes an API

UPDATE: New version 1.5 now supports wireless Bluetooth connections!

ArduinoPi 1.0: API overview

ArduinoPi 1.0: Using POST or GET

ArduinoPi 1.0: Configuration

ArduinoPi 1.0: Command Set

PWM

Digital

Analog

Multiple PWM

Multiple digital

Multiple Analog

Analog File

Delete File

ArduinoPi 1.0: Error Reporting

Conclusion

ArduinoPi Web based Controller for Arduino

UPDATE: New version found here: http://www.fritz-hut.com/arduinopi-v1-5-bluetooth-dongle-support/

The principal behind ArduinoPi

The command set of the ArduinoPi

Basic switch-port-high command

RGB command

Read Sensor Command

My test setup for the ArduinoPi

The Arduino code for ArduinoPi

The web browser interface for the ArduinoPi

Hover example

Color picker

Basic Sensor Display

Live Sensor Data

Conclusion

UPDATE: New version 1.5 now supports wireless Bluetooth connections!

ArduinoPi 1.0: API overview

ArduinoPi 1.0: Using POST or GET

ArduinoPi 1.0: Configuration

ArduinoPi 1.0: Command Set

PWM

Digital

Analog

Multiple PWM

Multiple digital

Multiple Analog

Analog File

Delete File

ArduinoPi 1.0: Error Reporting

Conclusion

Share this:

UPDATE: New version found here: http://www.fritz-hut.com/arduinopi-v1-5-bluetooth-dongle-support/

The principal behind ArduinoPi

The command set of the ArduinoPi

Basic switch-port-high command

RGB command

Read Sensor Command

My test setup for the ArduinoPi

The Arduino code for ArduinoPi

The web browser interface for the ArduinoPi

Hover example

Color picker

Basic Sensor Display

Live Sensor Data

Conclusion

Share this: