Fritz-Hut

ArduinoPi v1.0 includes an API

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:

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:

$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.

$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 handling 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 :) .