Builder API

Builder API

The Builder acts as a completely RESTful HTTP service, just like all other codebender's services. That means you just send in your code in JSON and get the response in the expected format.

---

Local Installation

A local installation of the builder should be able to accept requests in: http://your_local_builder_path/authorizationKey/APIversion

The authorizationKey and APIversion are parameters of the builder Symfony project and should be defined in order to use the builder. Note that only version v1 can be used, since we didn't need to implement any other API version yet.

Sending Data

In order to send data to the builder, you are allowed to only use HTTP POST requests. Sending an empty request to your http://builder/myAuthKey/v1/compile will return something like this:

{
    "success":false,
    "step":0,
    "message":"Invalid input.",
    "additionalCode":
    {
        "providedLibraries":[],
        "fetchedLibraries":[],
        "detectedHeaders":[],
        "foundHeaders":[],
        "notFoundHeaders":[]
    }
}

More information on the data format will be given below.

cURL Example

curl -X POST http://builder/auth_key/API_version/compile --data '{"files":[{"filename":"Blink Example.ino","content":"\/*\n\tBlink\n\tTurns on an LED on for one second, then off for one second, repeatedly.\n\n\tThis example code is in the public domain.\n*\/\n\nvoid setup()\n{\n\t\/\/ initialize the digital pin as an output.\n\t\/\/ Pin 13 has an LED connected on most Arduino boards:\n\tpinMode(13, OUTPUT);\n}\n\nvoid loop()\n{\n\tdigitalWrite(13, HIGH); \/\/ set the LED on\n\tdelay(1000); \/\/ wait for a second\n\tdigitalWrite(13, LOW); \/\/ set the LED off\n\tdelay(1000); \/\/ wait for a second\n}\n"}],"libraries":[],"logging":true,"format":"binary","version":"105","build":{"mcu":"atmega328p","f_cpu":"16000000L","core":"arduino","variant":"standard"}}'

PHP Example

<?php
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, "");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);

    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $request_data);

    $response_data = curl_exec($ch);
    curl_close($ch);
?>

Request

The format of a builder request content is pretty much the same as that of the compiler which can be found here

However, there is one major difference. You only need to use the libraries field of the request if you need to use a library that does not exist in codebender's libraries. This happens because the builder is capable of parsing Arduino projects, detecting necessary dependencies (libraries) and injecting them to your request.

Note that if you send the builder a library that already exists in codebender's libraries, this will prevent the builder from using the library from codebender and use the supplied one instead.

After that, the builder just passes the request to the compiler and gets the response back.

Response

The compiler will respond with a JSON-encoded response, which will contain some of the following keys:

• success Indicates whether the compilation was successful or not
• time The time spent on the compilation process (not including time spent for connections, etc)
• size The size of the binary file output in bytes
• output The actual binary output produced during the compilation in BASE-64 encoding
• log If the logging option was set to true, this key should exist and it's value would be a list of the avr-gcc calls made during the compilation.
• additionalCode Lists the libraries that were fetched/used during the compilation (more info below)

{
    "success":true,
    "time":1.47144198418,
    "size":"1082",
    "output":"DJRhAAyUfgAMlH4ADJR+AAyUfgAMlH4ADJR+AAyUfgAM... THIS ONE IS LONG ...lH4ADJR+AAyUfgAMlHAD5z\/iU\/88=",
    "log":"Commands that got executed during compilation."
    "additionalCode":
    {
        "providedLibraries":[],
        "fetchedLibraries":[],
        "detectedHeaders":[],
        "foundHeaders":[],
        "notFoundHeaders":[]
    }
}

additionalCode explained

• providedLibraries: A list of libraries that were provided to builder.
• fetchedLibraries: A list of the libraries that were detected in the Arduino project and fetched by the builder.
• detectedHeaders: All headers that were detected in the #include statements of the Arduino project.
• foundHeaders: A list of the detected headers that either existed in the project, or were included in one of the libraries that builder fetched.
• notFoundHeaders: Headers that were detected by the builder, but weren't anywhere to be found.