Skip to content

API

Jump to bottom
Rick Companje edited this page May 15, 2017 · 3 revisions

The Doodle3D WiFi-Box makes almost all 3D printers wirelessly controllable through a simple REST API. This means you can control them using your own favourite programming language. Basically any language that can send and receive HTTP requests (AJAX).

So what could you make? You can think of Doodle3D as the first application written on top of the API, it makes 3D printing a simple sketch child's play. Another example is Cura, which uses the API to enable wirelessly sending a print to your printer. Using the WiFi-Box you could control a printer using a Kinect, influence a print with sound input, maybe create a cup designer or adding an embeddable print button to an existing design application.

Doodle3D API

Our API enables you to go to a url, and retrieve a json object with information. Like retrieving status info using the following url:
{ip address of WiFi-Box}/d3dapi/info/status 
This will give you among other things the status of your printer:

{
    data:
    {
        state: "printing",
        hotend: 27,
        hotend_target: 220,
        bed: 30,
        bed_target: 70,
        current_line: 5,
        buffered_lines: 200,
        total_lines: 2000,
        has_control: true,
    },
    status: "success"
}
But you can also set things in motion, you could for example print something by sending G-code in a POST request to the following url:
{ip address of WiFi-Box}/d3dapi/printer/print
A basic example in html:
<html>
<body>
    <form action="http://192.168.5.1/d3dapi/printer/print" 
        enctype="x-www-form-urlencoded" method="POST">
        <textarea name="gcode">G1 X100 Y100</textarea>
        <input type="hidden" name="start" value="true">
        <input type="hidden" name="first" value="true">
        <input type="submit" value="Print" />
    </form>
</body>
</html>
The basic guidelines are:
  • Read-only requests are send as GET, with arguments encoded in the url.
  • State-changing requests are send as POST, with arguments encoded like forms do (similar to GET but transmitted as post data instead).
  • Responses always contain json data as detailed below and always share some basic uniformity (see http://labs.omniti.com/labs/jsend ).

Tip: you can always use the IP address http://192.168.5.1/ when the WiFi-Box is connected to your computer by an ethernet cable.

More technical info can be found at our wiki. You can also browse through our source code for more (up to date) undocumented features:

REST API's

More background on REST API's:

We are not the first to open up a REST API, other examples:

Tools:

Examples

jQuery: request printer status

<html>
<head>
    <script src="http://code.jquery.com/jquery-1.11.0.min.js"></script>
    <script>
    var api = "http://192.168.5.1/d3dapi/"; //you can use this address when using the UTP cable
    $(function() {
        
        //get current status from Doodle3D WiFiBox
        $.ajax({
          url: api+"info/status",
          dataType: 'json',
          success: function(response) {
            $("#divStatus").html("status: " + response.data.state);
          }
        });
    
    });
    </script>
</head>
<body>

    <div id="divStatus"></div>

</body>
</html>

jQuery: generate a list of boxes on your network:

<html>
<head>
    <script src="http://code.jquery.com/jquery-1.11.0.min.js"></script>
    <script>

    var api = "http://connect.doodle3d.com/api/";
    $(function() {
        
        var list = $("#boxes");
        $.ajax({
          url: api+"list.php",
          dataType: 'json',
          success: function(response) {
            var boxes = response.data;
            jQuery.each(boxes, function (index,box) {
                list.append("<li><a href='http://"+box.localip+"'>"+box.wifiboxid+"</a></li>");
            });
          }
        });
    });

    </script>
</head>
<body>

    <ul id="boxes"></ul>

</body>
</html>

Processing: request boxes on your network:

Using the HTTProcessing library (you can import it through the Library manager)

import httprocessing.*;

GetRequest get = new GetRequest("http://connect.doodle3d.com/api/list.example");
get.send(); // program will wait untill the request is completed
println("response: " + get.getContent());

JSONObject response = JSONObject.parse(get.getContent());
println("status: " + response.getString("status"));
JSONArray boxes = response.getJSONArray("data");
println("boxes: ");
for(int i=0;i<boxes.size();i++) {
  JSONObject box = boxes.getJSONObject(i);
  println("  wifiboxid: " + box.getString("wifiboxid"));
}

There are downloadable examples to help you get started with the API through processing or you can download our own library here. Unfortunately we haven't got a importable library yet.

API Reference

Categories

 

Config

The config API allows you to change the settings stored on the Doodle3D WiFi-Box, like the default bed temperature.

Retrieve the list of setting keys and their values

GET: /config/all

response: returns all keys and their values.

{
  data: {
    doodle3d.simplify.minDistance: 3,
    printer.baudrate: "115200",
    printer.bed.height: 220,
    printer.bed.temperature: 70,
    printer.bed.width: 220,
    ....etc.....
    },
    "status": "success"
}
Retrieve the value of a key

GET: /config/?printer.type=

This call returns the value of a certain key (in this case printer.type) from the settings panel.

response: 

{
    data:
    {
        printer.type: "ultimaker"
    },
    status: "success"
}
Change the value of a key

POST: /config
requires: key=value
enctype: x-www-form-urlencoded

Example:

<form action="http://192.168.5.1/d3dapi/config" enctype="x-www-form-urlencoded" method="POST">
<label>Printer temperature:</label>
<input type="text" name="printer.temperature" value="230"/>
<input type="submit"/>
</form>

response:

{
    data:
    {
        more_info: "http://doodle3d.com/api",
        substituted_ssid: "Doodle3D-87354A",
        validation:
        {
            printer.temperature: "ok"
        }
    },
    status: "success"
}

 

Info

Basic info

GET: /info

Implemented since version 0.10.2

response:

{
    data:
    {
        wifibox: Doodle3D-4CC2FE
    },
    status: "success"
}
Get status info

GET: /info/status

Combination of:

  • printer/state
  • printer/temperature
  • printer/progress
  • info/access

response:

{
    data:
    {
        bed: 0,
        bed_target: 0,
        buffered_lines: 0,
        current_line: 0,
        has_control: true,
        hotend: 20,
        hotend_target: 0,
        state: "idle",
        total_lines: 0,
    },
    status: "success"
}

or when there's no printer connected:

{
    data:
    {
        more_info: "http://doodle3d.com/api",
        state: "disconnected",
    },
    status: "success"
}
Download logfiles

GET: /info/logfiles

response:

wifibox-logs.tgz will be returned as a download.

Check whether you are in control of the printing process

GET: /info/access

 

Network

Scan for available wireless networks

GET: /network/scan

List known networks

GET: /network/known

Info about the current network

GET: /network/status

Connect to an existing WiFi network

POST: /network/associate

ssid: (string) (required) name of WiFi network
phrase: (string) (optional) password of WiFi network
recreate: (bool) (optional) should the configuration be recreated or just updated?

Disconnects from the current WiFi network
Activate a Wireless AccessPoint

POST: /network/openap

Activate an accesspoint using the ssid and key stored in /config/?network.ap.ssid= and /config/?network.ap.key=
Remove a network from known networks

POST: /network/remove

ssid: (string) (required)

Signin at connect.doodle3d.com

GET: /network/signin

When connected to the internet through an existing WiFi network you can use this method to signin at connect.doodle3d.com.

Check if WiFi-Box is alive

GET: /network/alive

This method will always return 'alive' when it is called. It's meant to be a light-weight way of checking if the browser can still reach the WiFiBox.

 

Printer

Control the 3D printer.

Request the printer temperatures

GET: /printer/temperature

Request the progress of a print

GET: /printer/progress

Response fields
  • current_line: the line currently being printed, reset to 0 when the G-Code buffer is cleared
  • buffered_lines: the amount of lines currently buffered (lines that have been printed are removed from the buffer)
  • total_lines: the total amount of lines that have been added since the last buffer clear or, if set, the total number of lines to be sent as specified in a printer/print call (introduced in v0.10.10-a)
  • buffer_size: the current amount of bytes in the buffer (introduced in v0.10.10-a)
  • max_buffer_size: the maximum size (in bytes) of the buffer, note that this might be a dynamic value (introduced in v0.10.10-a)
  • seq_number: the last sequence number accepted by the print server, -1 if not set; reset to -1 when the G-Code buffer is cleared (introduced in v0.10.10-d)
  • seq_total: the total number of chunks the print server is expecting to be receiving, -1 if not set; reset to -1 when the G-Code buffer is cleared (introduced in v0.10.10-d)

GET: /printer/state

Possible printer states:

  • unknown: not sure what's going on
  • disconnected: printer disconnected
  • connecting: printer connecting (printer found, but driver has not yet finished setting up the connection)
  • idle: printer found and ready to use, but idle
  • buffering: printer is buffering (recieving) data, but not yet printing
  • printing: the printer is printing
  • stopping: when you stop (abort) a print it prints the endcode
Request all supported printer types

GET: /printer/listall

Make the printer heatup to the heatup temperature

POST: /printer/heatup

This heatup temperature is stored in config

Make the printer print something

POST: /printer/print

gcode: (string) (required) See: G-Code (please limit the amount of GCODE to 500 lines).
clear: (bool) (optional) (default: false) Normally gcode chunks will be concatenated, but if you set this to true the buffer is cleared first.
first: (deprecated since v0.10.10-a) An alias for the 'clear' parameter.
start: (bool) (optional) (default: false) Only when this argument is true will printing be started.
total_lines: (int) (optional) The total number of lines that is going to be sent; if sent, this will be used as the total when reporting progress, otherwise the amount of lines sent so far is reported. (introduced in v0.10.10-a)
seq_number: (int) (optional) See sequence numbering below.
seq_total: (int) (optional) See sequence numbering below.
 
By sending G-Code you can instruct the printer to do something.
Note that sequence numbering and the fail message which notifies the G-Code buffer is full have been introduced in v0.10.10-a.
 
Example:
<html>
<body>

    <form action="http://192.168.5.1/d3dapi/printer/print"
        enctype="x-www-form-urlencoded" method="POST">
        <textarea name="gcode">G1 X100 Y100</textarea>
        <input type="hidden" name="start" value="true">
        <input type="hidden" name="first" value="true">
        <input type="submit" value="Print" />
    </form>

</body>
</html>
Sequence numbering

The WiFi-Box supports doing basic consistency checks on chunks of G-Code sent to it, which can in some cases be useful to detect problems for example with a busy or unstable network. In practice however, this is not needed. To use the mechanism, supply the total number of chunks to be sent as seq_total and number each consecutive chunk in seq_number, starting at 0 (so the highest chunk number is the total - 1).

Associated failure codes are: seq_num_missing (number was sent before but not this time), seq_num_mismatch (number did not increment by 1, or is >= the total), seq_ttl_missing (...), seq_ttl_mismatch (not last one), seq_src_missing and seq_src_mismatch (the box expected to receive data from another IP address which was already sending its G-Code).

G-Code buffer full

Apart from a regular OK response, or the failures associated with sequence numbering, the box can also respond with buffer_full. This means that it first needs to print G-Code that has already been sent, to make room for new code. It is advisable to wait a few minutes before retrying to send data; in the future, the maximum buffer size will be reported in the status endpoint (under info), so it becomes possible to wait 'more intelligently'.

Response fields
  • gcode_clear: true if 'clear' was set in the request and if the buffer has been cleared successfully
  • gcode_print: true if 'start' was set in the request and if the print has been started successfully
  • gcode_append: the number of G-Code lines that have been added in this request
  • seq_number: the last sequence number accepted by the print server, -1 if not set; reset to -1 when the G-Code buffer is cleared (introduced in v0.10.10-d)
  • seq_total: the total number of chunks the print server is expecting to be receiving, -1 if not set; reset to -1 when the G-Code buffer is cleared (introduced in v0.10.10-d)
Example responses
/* Example response when both the 'clear' and 'start' fields were set to true in the request. */
{
    data:
    {
        gcode_append: 21485,
        gcode_clear: true,
        gcode_print: true,
        seq_number: 0,
        seq_total: 352
    },
    status: "success"
}

/* Example response when the G-Code buffer is full */
{
data:
{
seq_number: 137,
seq_total: 352,
status: "buffer_full"
},
msg: "could not add gcode (buffer_full)",
status: "fail"
}
Make the printer stop the running print

POST: /printer/stop

gcode: (string) (optional) See: G-Code (please limit the amount of GCODE to 500 lines)

Stops the current print as soon as possible and clears the G-Code buffer. You can also add some G-Code for a finishing move.

 

Sketch

Manage the sketches saved on the WiFi-Box.

GET: /sketch/?id=1

POST: /sketch

data: (string) (required)

GET: /sketch/status

POST: /sketch/clear

 

System

GET: /system/fwversions

 

Update

GET: /update/status

POST: /update/download

POST: /update/install

POST: /update/clear

Clone this wiki locally