Compiler API

The Compiler acts as a completely RESTful HTTP service. Simply put, code comes in, binary (or error reports) comes out.

The compiler accepts requests on the following URL:

http://the_url_of_your_compiler/authorizationKey/API_Version

Where authorizationKey is the authorization string you used in your preferences, and API_Version is the compiler's API version that you would like to use (currently, only v1 is supported).

Example:

http://localhost/compiler/myAuthKey/v1

Sending Data

To test the compiler, open http://compiler_url/authorizationKey/API_version with your browser. You should get this error.

{
   "success":false,
   "step":0,
   "message":"Invalid input."
}

In order to send data to your compiler, you send an HTTP POST request to the compilation URL, and set the JSON request as the POST request's content. For more info on the data format, please see the Request and Response sections.

cURL Example

curl -X POST http://compiler_url/authorizationKey/API_version --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"}}'

jQuery Example

$.post("http://compiler_url/authorizationKey/API_version", REQUEST_DATA, function (RESPONSE_DATA) {
	//handle response here, RESPONSE_DATA contains the response
});

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

There are 4 main keys in the JSON request body:

files
libraries
format
version
build

files

files contains an array of the files to be compiled, with one record for each file. Each file is represented as a key-value array itself, with the filename key containing the filename and the content key containing the code.

For example, to represent a single file named myfile and containing the code printf(300);, its representation would be:

{"filename":"myfile","content":"printf(300);"}

and the files key would contain:

[{"filename":"myfile","content":"printf(300);"}]

libraries

libraries contains an array of the libraries used by the sketch, with their corresponding files. Each library is represented as a key-value pair, the key being the name of the library, and the value being an array containing the library's files. In turn, each file is represented as a key-value array itself, with the filename key containing the filename and the content key containing the code.

For example, to represent a single library named myfile and containing the code printf(300);, its representation would be:

{"SPI":[{"filename":"SPI.h","content":"content"},{"filename":"SPI.cpp","content":"content"}]}

format

format contains the output format you would like to request from the compiler. The valid options are:

syntax - performs a syntax check only. used for "Verify".
object - returns an object file (.o) for your code on success
binary - returns a base64-encoded binary file for the target device on success
elf - returns an ELF (.elf) binary file on success
hex - returns a hex-encoded (.hex) binary file for the target device on success

version

version contains the Arduino SDK version that your code will be built with. Valid options are 100, 101, 102, 103, 104 and 105 for Arduino versions 1.0.0-1.0.5 respectively.

build

last but not least, build contains the build parameters for the selected board configuration, which the ones found in the original boards.txt configuration files under the board_name.build.* parameters. The parameters you need to specify are:

mcu - processor's MCU spec
f_cpu - processor's clock speed F_CPU spec
core - Arduino core used for the board
variant - variant used for the board
vid - USB VID (optional, for Leonardo-like USB-enabled devices)
pid - USB VID (optional, for Leonardo-like USB-enabled devices)

Example

Here's an example of the JSON request for verifying (syntax check) a 2-file sketch for Arduino UNO.

{
   "files":[
      {
         "filename":"hello.h",
         "content":"#define HELLO"
      },
      {
         "filename":"hello.ino",
         "content":"#include<SPI.h>\nvoid setup()\n{\n\tint bla, blabla = 5;\n}\n\nvoid loop()\n{\n\n}\n"
      }
   ],
   "libraries":
      {
         "SPI":[
            {
               "filename":"SPI.h",
               "content":"content"
            },
            {
               "filename":"SPI.cpp",
               "content":"content"
            }
         ]
      },
   "format":"syntax",
   "version":"105",
   "build":{
      "mcu":"atmega328p",
      "f_cpu":"16000000L",
      "core":"arduino",
      "variant":"standard"
   }
}

Response

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

success - mandatory
output - used only upon successful compilation (success = true). contains the output in the requested format.
size - used only on successful compilation. contains the size of the generated binary.
time - used only on successful compilation and verification. Contains the time it took for the procedure to be completed.
message - used usually when something went wrong (success = false), to notify the user (i.e. compilation error messages). The message is HTML-encoded, using html <font> tags to color-code various errors.
step - used when something went wrong, used for debugging purposes so that we know at which step the error occurred

Examples

Unsuccessful Verification

{
   "success":false,
   "step":4,
   "message":"<b>hello.ino:4:6: <\/b><b><font style=\"color: red\">error: <\/font><\/b><b>cannot initialize a variable of type 'int' with an lvalue of type 'const char [8]'\n<\/b>        int hello = &quot;ehehehe&quot;;\n<b><font style=\"color: green\">            ^       ~~~~~~~~~\n<\/font><\/b>1 error generated."
}

Successful Verification

{
   "success":true,
   "time":0.54590511322021
}

Successful Compilation

{
   "success":true,
   "time":0.65779185295105,
   "size":"2758",
   "output":"HUGE STRING HERE WITH BASE64 ENCODING OF BINARY AMMAGAAAAAD!!!!!11111oneoneonecos(0)=="
}

Deleting compiler's object cache

To delete all cached objects generated by compiler send the following HTTP POST request:

curl -X POST http://compiler_url/authorizationKey/API_version/delete/all/

Misc

HTTP Monitoring

The compiler offers a special URL that you can hit to monitor the compiler's status and make sure your servers are healthy. You can check that the compiler is working by hitting the following page:

http://the_url_of_your_compiler/status

It should respond with the following JSON output:

{
   "success":true,
   "status":"OK"
}

Notice that you don't need the API key to hit get the compiler's status.

HTTP Testing

In addition to providing a URL for heartbeat monitoring, the compiler allows you to run some basic tests to assure that compilation works as it should, using some built-in examples of arduino sketches to check for expected behavior.

You can send test requests on the following URL: