Repetier-Server API description

Introduction

Repetier-Server consists of several modules. The main module is the server it self. It is a small programm written in C++ that manages all the tasks. It runs as a background service and normally starts with your os. The objective of this server is to communicate with the printers configured, manage files and call other modules. To allow communication with other modules like the web frontend, it has a build in web server. It does not matter if you control the server over a web site or a gui written in Python, C# or whatever you want. The only fact that matters is to use the proper protocol.

The server is normally reachable over port 3344 also this can be changed in the configuration file. It serves 3 types of files.

All data and files have to be UTF-8 encoded! Using other encodings can cause strange things to happen.

Static files

Static files are stored in the www directory beneath the installation directory. If you add your own files, put them into a subfolder modules/<your module name>.

Single dynamic requests

These requests are all of the form

http://localhost:3344/printer/<cmd group>/<slug>?a=<action>&sess=<session key>
or
http://localhost:3344/printer/<cmd group>/<slug>?a=<action>&apikey=<api key>
or
http://localhost:3344/printer/<cmd group>/<slug>?a=<action>
    x-api-key: <your api key here>
    
The first is the standard way you should use if you are logged in with a session over a websocket. If you have no sesseion, beacuse of a missing web socket, you can create a ad hoc session for a singe request including authorization if you include a valid api key. You can add it as parameter apikey, which should be avoided, since proxys etc may store it. Better is to include it as header field x-api-key. slug is the internal name of your printer. All printer data is stored in a directory named like the slug. You will later see how to get all printer names including the internal slug name, which is used everywhere to reference a special printer. sess is your session key. You get a session key if you open a websocket. In general, you can only use these pages as long as you have a valid session. Remember to url encode the session key! In case of an error you get a response like this:
{"error":"Authorization required"}

info

http://localhost:3344/printer/info
Returns basic infos about the server. These can be called even without a api-key and if there is use rprotection it even reveals the key. Answer:
{
    "apikey": "c43686f3-867c-4c08-88b7-aaaaaaaaaaaa",
    "name": "Rolands Server",
    "version": "0.75.2",
    "printers": [
        {
            "active": true,
            "name": "DeltaTest",
            "online": 1,
            "slug": "DeltaTest"
        },
        {
            "active": false,
            "name": "Felix",
            "online": 0,
            "slug": "Felix"
        },
        {
            "active": true,
            "name": "Marlin RAMPS",
            "online": 1,
            "slug": "Marlin_RAMPS"
        }
    ]
}

list

This command group requires no action. It returns a json formatted list of all printers. You should prefer the websocket command.

layeranalysis

If you uploade a g-code to the server it gets analysed and the server creates some extra files. 2 files are for a fast preview of the uploaded g-code. The first you call is layeranalysis:
http://localhost:3344/printer/layeranalysis/<slug>?id=<g-code id>&sess=<session key>

You get the g-code id from the list of g-code models available. The result is a json-string like shown below. It contains the volume where all print moves fit into. Here the radius is the required radios for a print bed with origin at 0,0. This way a delta printer can test if it fits inside printable radius. The speeds array lists all used speeds. Extruders array list all used extruders. layers array gives informations about each layer. Here each index contains 5 informations:


{
    "xmin": -42.3,
    "xmax": 42.3,
    "ymin": -36.62,
    "ymax": 36.65,
    "zmin": 0,
    "zmax": 10.1,
    "radius": 44.55,
    "speeds": [
        1800,
        1920,
        2100,
        2220,
        2400,
        2700,
        3120,
        3600,
        9000
    ],
    "extruders": [
        0
    ],
    "layers": [
        {
            "h": 0,
            "t": 0,
            "p": 24,
            "g": 0,
            "l": 1
        },
        {
            "h": 0.3,
            "t": 108,
            "p": 18912,
            "g": 34589,
            "l": 1191
        },
        {
            "h": 0.5,
            "t": 214,
            "p": 42848,
            "g": 69729,
            "l": 2376
        },
        {
            "h": 0.7,
            "t": 306,
            "p": 65960,
            "g": 103759,
            "l": 3524
        },
        {
            "h": 0.9,
            "t": 359,
            "p": 88968,
            "g": 148133,
            "l": 5032
        },
        {
            "h": 1.1,
            "t": 391,
            "p": 95744,
            "g": 164479,
            "l": 5596
        },
        {
            "h": 1.3,
            "t": 423,
            "p": 102512,
            "g": 180754,
            "l": 6159
        },
        {
            "h": 1.5,
            "t": 455,
            "p": 109208,
            "g": 196767,
            "l": 6713
        },
        {
            "h": 1.7,
            "t": 487,
            "p": 115952,
            "g": 212980,
            "l": 7273
        },
        {
            "h": 1.9,
            "t": 520,
            "p": 122712,
            "g": 229158,
            "l": 7835
        },
        {
            "h": 2.1,
            "t": 552,
            "p": 129360,
            "g": 245002,
            "l": 8383
        },
        {
            "h": 2.3,
            "t": 584,
            "p": 136024,
            "g": 260909,
            "l": 8933
        },
        {
            "h": 2.5,
            "t": 616,
            "p": 142600,
            "g": 276496,
            "l": 9472
        },
        {
            "h": 2.7,
            "t": 648,
            "p": 149216,
            "g": 292224,
            "l": 10016
        },
        {
            "h": 2.9,
            "t": 680,
            "p": 155848,
            "g": 307972,
            "l": 10562
        },
        {
            "h": 3.1,
            "t": 713,
            "p": 162424,
            "g": 323571,
            "l": 11101
        },
        {
            "h": 3.3,
            "t": 745,
            "p": 169016,
            "g": 339256,
            "l": 11642
        },
        {
            "h": 3.5,
            "t": 777,
            "p": 175584,
            "g": 354862,
            "l": 12180
        },
        {
            "h": 3.7,
            "t": 809,
            "p": 182200,
            "g": 370585,
            "l": 12724
        },
        {
            "h": 3.9,
            "t": 841,
            "p": 188784,
            "g": 386213,
            "l": 13264
        },
        {
            "h": 4.1,
            "t": 873,
            "p": 195376,
            "g": 401881,
            "l": 13805
        },
        {
            "h": 4.3,
            "t": 905,
            "p": 201944,
            "g": 417494,
            "l": 14343
        },
        {
            "h": 4.5,
            "t": 937,
            "p": 208496,
            "g": 433033,
            "l": 14879
        },
        {
            "h": 4.7,
            "t": 969,
            "p": 215072,
            "g": 448668,
            "l": 15418
        },
        {
            "h": 4.9,
            "t": 1001,
            "p": 221656,
            "g": 464324,
            "l": 15958
        },
        {
            "h": 5.1,
            "t": 1033,
            "p": 228248,
            "g": 480008,
            "l": 16499
        },
        {
            "h": 5.3,
            "t": 1065,
            "p": 234832,
            "g": 495660,
            "l": 17039
        },
        {
            "h": 5.5,
            "t": 1098,
            "p": 241416,
            "g": 511321,
            "l": 17579
        },
        {
            "h": 5.7,
            "t": 1130,
            "p": 247992,
            "g": 526943,
            "l": 18118
        },
        {
            "h": 5.9,
            "t": 1162,
            "p": 254592,
            "g": 542667,
            "l": 18660
        },
        {
            "h": 6.1,
            "t": 1194,
            "p": 261200,
            "g": 558399,
            "l": 19203
        },
        {
            "h": 6.3,
            "t": 1226,
            "p": 267784,
            "g": 574073,
            "l": 19743
        },
        {
            "h": 6.5,
            "t": 1258,
            "p": 274376,
            "g": 589757,
            "l": 20284
        },
        {
            "h": 6.7,
            "t": 1290,
            "p": 280960,
            "g": 605415,
            "l": 20824
        },
        {
            "h": 6.9,
            "t": 1322,
            "p": 287544,
            "g": 621077,
            "l": 21364
        },
        {
            "h": 7.1,
            "t": 1354,
            "p": 294096,
            "g": 636623,
            "l": 21900
        },
        {
            "h": 7.3,
            "t": 1386,
            "p": 300648,
            "g": 652170,
            "l": 22436
        },
        {
            "h": 7.5,
            "t": 1418,
            "p": 307208,
            "g": 667741,
            "l": 22973
        },
        {
            "h": 7.7,
            "t": 1450,
            "p": 313800,
            "g": 683412,
            "l": 23514
        },
        {
            "h": 7.9,
            "t": 1482,
            "p": 320472,
            "g": 699397,
            "l": 24065
        },
        {
            "h": 8.1,
            "t": 1514,
            "p": 327064,
            "g": 715069,
            "l": 24606
        },
        {
            "h": 8.3,
            "t": 1547,
            "p": 333728,
            "g": 731029,
            "l": 25156
        },
        {
            "h": 8.5,
            "t": 1579,
            "p": 340432,
            "g": 747132,
            "l": 25711
        },
        {
            "h": 8.7,
            "t": 1611,
            "p": 347080,
            "g": 763019,
            "l": 26259
        },
        {
            "h": 8.9,
            "t": 1643,
            "p": 353864,
            "g": 779415,
            "l": 26824
        },
        {
            "h": 9.1,
            "t": 1675,
            "p": 360672,
            "g": 795893,
            "l": 27392
        },
        {
            "h": 9.3,
            "t": 1707,
            "p": 367520,
            "g": 812513,
            "l": 27965
        },
        {
            "h": 9.5,
            "t": 1739,
            "p": 374336,
            "g": 829025,
            "l": 28534
        },
        {
            "h": 9.7,
            "t": 1818,
            "p": 398280,
            "g": 864224,
            "l": 29719
        },
        {
            "h": 9.9,
            "t": 1896,
            "p": 421512,
            "g": 898706,
            "l": 30885
        },
        {
            "h": 10.1,
            "t": 1975,
            "p": 445264,
            "g": 933115,
            "l": 32056
        }
    ]
}

layer

This command returns a json-string containing the description of an area of your code. layeranalysis gives the possible start/end positions in it's p parameter for each layer.

http://localhost:3344/printer/layer/<slug>?id=<g-code id>&sess=<session key>&start=<start pos>&end=<end pos>

The json result is a large array of objects. Every object has a value t which defines the meaning of the objects. Currently the following types are defined:

gcode

This command returns a section of your g-code file. Use the g-positions from layeranalysis to get the right start and end position. The code will look like this:

http://localhost:3344/printer/gcode/<slug>?id=<g-code id>&sess=<session key>&start=<start pos>&end=<end pos>

log

The server creates a log for each print. With this link, you can download one of these logs.

http://localhost:3344/printer/log/<slug>?a=download&sess=<session key>&l=<log name>

model

This group handles g-code files stored in the model list (in contrast to print list). The following url shows how to upload it. The file should be in parameter filename. Format is multipart/form-data.

http://localhost:3344/printer/model/<slug>?a=upload&sess=<session key>&name=<file name>

pconfig

Commands in this group handle printer configurations.

Action: download

Downloads a printer configuration as a single xml file. No extra parameter required.

http://localhost:3344/printer/pconfig/<slug>?a=download&sess=<session key>
Action: upload

Uploads a previously downloaded configuration file. The file can create a new printer or replace a existing printer. Parameters:

http://localhost:3344/printer/pconfig?a=upload&sess=<session key>&slug=<slug>mode=<mode>&name=<name>

User websocket commands directly

In the websocket chapter you will see all the small commands you normally use while you are displaying server status. Soem of them might also be useful for simple apps just wanting to show some informations. For these we offer a access over the REST api. The only thing that does not work are events as they are reported to open sockets only.

http://localhost:3344/printer/api/<slug>?a=<websocket command>&data=<json object properly url-escaped>&apikey=<API key>>

The above schema can be used to send any websocket command as REST call. Use GET or POST just as you like. For bigger data POSt should be preferred. You can replace apikey with sess, but you would normally do this only if you have no session open, so apikey is the normal way to use it.

Websockets

Websockets are the first way to go when communicating with the server. They are fast and allow a bi-directional communication. This is important, because the server sends messages from time to time on it's own to inform the user about changes. It is also the only way to establish a session. Each frame in either direction is a valid json string. Requests must be smaller then 8kb. The URL of the websocket is

ws://localhost:3344/socket/?lang=<Language ID>&sess=<session id>
lang can be omitted. sess can also be omitted it you have no running session. This will of course require authentication if users are defined. If no users are defined also no authentication is needed. If you have a apikey you can also add &apikey=your key to authenticate directly. Otherwise use the login command to authenticate.
Lets first start with events send from the server. They look like this:

{"callback_id":-1,
  "data":[
        {"data":{"O":0.0000000000000000,"S":0.0000000000000000,"T":25.500000000000000,"id":0,"t":1420482089539},"event":"temp","printer":"MyPrinter"},
        {"data":{"O":0.0000000000000000,"S":0.0000000000000000,"T":25.100000381469727,"id":1,"t":1420482089539},"event":"temp","printer":"MyPrinter"}],
  "eventList":true}

All returned messages are in form of an object. First you see callback_id which is a reference to a command send. Since it is initiated by the server the reference is -1 meaning no reference. eventList means we got a list of events. When it is the servers time to send data it sends all events unsent so far. The events are contained in the data array. Each event is a single object having 3 fields:

Sending data is also very easy. Lets take the ping example. Some implementations do not send a explicit close or can not do, because internet connection got broken. Therefore the server disconnects any websocket that ha snot send a ping within 5 seconds. So for safety the web frontend sends a ping every second. Here is how it looks like:

{"action":"ping","data":{},"printer":"MyPrinter","callback_id":545}

As you see, each command is a json-object with 4 fields.

The important part here is callback_id. It must be a positive integer that is unique to all unanswered requests. At some point you get an answer from the server which contains the same callback_id. That way you know the answer is meant for that request. Our ping answer would look like this:

{"callback_id":545,"data":{},"session":"mPa7e7!g0F!$y40NSirj@QsvCvPxTuSc"}

Here data would contain, what ever that function thinks it should return.

ping

Parameter: None.

Response

{}

Sends a keep alive ping to the server. If the server does not a ping in time, it will disconnect the websocket. Default timeout is 10 seconds and it can be increased with extendPing.

extendPing

Parameter: timeout (int) = new timeout for ping.

Response

{}

Some operations take longer and could prevent sending ping, e.g. uploading from webbrowsers. In such cases extend the timout before you upload and the go down to 0 = default after upload is finished.

login

Parameter: login (string) = login, password (string) = user password, rememberMe (bool, optional) = create long lived session.

Response

{"ok":true,"permissions":31,"login":"your name",settings:{}}

Authenticates a user. Password is MD5(sessionId + MD5(login + password)) so it never goes in clear text over the line. If authentication is required, you get a loginRequired event directly after connecting to the socket.

logout

Parameter: None.

Response

{}

Unsets the user for the session.

listPrinter

Parameter: None

Response

[ { "active": true, "job": "none", "name": "DeltaTower", "online": 0, "slug": "delta" }, { "active": false, "job": "none", "name": "Azteeg X3 Pro very long name is this", "online": 0, "slug": "delta2" }, { "active": true, "job": "none", "name": "iRapid", "online": 1, "slug": "irapid" }, { "active": false, "job": "none", "name": "iRapid BLACK", "online": 0, "slug": "irapid3" }, { "active": true, "job": "none", "name": "Ordbot", "online": 0, "slug": "Ordbot" }, { "active": false, "job": "none", "name": "Schrotty", "online": 0, "slug": "Schrotty" }, { "active": false, "job": "none", "name": "Test", "online": 0, "slug": "Test" }, { "active": false, "job": "none", "name": "iRapid WHITE", "online": 0, "slug": "white" } ]

Lists all configured printer with their state.

send

Parameter: cmd (string) = g-code to execute

Response

{}

Sends a g-code directly to the printer.

stateList

Parameter: includeHistory (bool) include complete temperature history.

Response

{ "irapid": { "activeExtruder": 0, "debugLevel": 6, "extruder": [ { "history": [ { "O": 0, "S": 0, "T": 25.5, "t": 1420570143740 }, { "O": 0, "S": 0, "T": 25.39999961853027, "t": 1420570144751 }, { "O": 0, "S": 0, "T": 25.39999961853027, "t": 1420570145759 }

        ], "output": 0, "tempRead": 25.5, "tempSet": 0 }, { "history": [ { "O": 0, "S": 0, "T": 25.5, "t": 1420570143740 }, { "O": 0, "S": 0, "T": 25.39999961853027, "t": 1420570144751 }, { "O": 0, "S": 0, "T": 25.5, "t": 1420570145759 }
        ], "output": 0, "tempRead": 25.5, "tempSet": 0 } ], "fanOn": false, "fanVoltage": 0, "firmware": "Repetier_0.92", "firmwareURL": "https://github.com/repetier/Repetier-Firmware/", "flowMultiply": 100, "hasXHome": false, "hasYHome": false, "hasZHome": false, "heatedBed": { "history": [], "output": 0, "tempRead": 0, "tempSet": 0 }, "layer": 0, "numExtruder": 2, "powerOn": false, "sdcardMounted": true, "speedMultiply": 100, "x": -21, "y": 0, "z": 0 } }

Polls the detailed printer state with or without a complete temperature history.

response

Parameter: filter (int) log entries to return, start (int) start at this id.

Response

{ "lastid": 2997, "lines": [ { "id": 1998, "text": "N532 M105", "time": "19:55:50", "type": 1 }, { "id": 1999, "text": "ok 532", "time": "19:55:50", "type": 2 }, { "id": 2000, "text": "T:25.47 /0 @:0 T0:25.47 /0 @0:0 T1:25.47 /0 @1:0", "time": "19:55:50", "type": 2 }, { "id": 2001, "text": "wait", "time": "19:55:51", "type": 2 }, { "id": 2002, "text": "N533 M105", "time": "19:55:51", "type": 1 }, { "id": 2003, "text": "ok 533", "time": "19:55:51", "type": 2 }, { "id": 2004, "text": "T:25.35 /0 @:0 T0:25.35 /0 @0:0 T1:25.47 /0 @1:0", "time": "19:55:51", "type": 2 }
        ], "state": { "activeExtruder": 0, "debugLevel": 6, "extruder": [ { "output": 0, "tempRead": 25.4, "tempSet": 0 }, { "output": 0, "tempRead": 25.39999961853027, "tempSet": 0 } ], "fanOn": false, "fanVoltage": 0, "firmware": "Repetier_0.92", "firmwareURL": "https://github.com/repetier/Repetier-Firmware/", "flowMultiply": 100, "hasXHome": false, "hasYHome": false, "hasZHome": false, "heatedBed": { "output": 0, "tempRead": 0, "tempSet": 0 }, "layer": 0, "numExtruder": 2, "powerOn": false, "sdcardMounted": true, "speedMultiply": 100, "x": -21, "y": 0, "z": 0 } }

Polls the last printer communication. Also returns the last state. A better solution to get logs is to ask for logging events.

move

Parameter: x (float) = x movement, y (float) = y movement, z (float) = z movement, e (float) = extruder movement, speed (float) = speed in mm/s, relative (bool = true) = positions are relative.

Response

{}

Moves the printer or extruder to the given position or the given distance. All parameter are optional.

messages

Parameter: none

Response

[{"id":msgId,"msg":"Message","link":"finishLink","slug":printer,"date":"Date ISO 8601","pause":false}]

List of currrently open messages.

removeMessage

Parameter: id (int) = message id, a (string) = empty or unpause

Response

{}

Removes a message from the message list.

removeModel

Parameter: id (int) = id of g-code that will be deleted.

Response

{}

Removes a g-code files from th elist of g-code files.

listModels

Parameter: None

Response

{ "data": [
  { "analysed": 1, "created": 1358524426000, "extruderUsage": [ 2010.364379882812, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], "filamentTotal": 2010.364379882812, "id": 5, "layer": 201, "length": 1953388, "lines": 49218, "name": "Spool holder", "printTime": 6444.183673505804, "printed": 3, "state": "stored", "volumeTotal": 4835.493005891309, "volumeUsage": [ 4835.493005891309, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ] },
  { "analysed": 1, "created": 1359390329000, "extruderUsage": [ 7143.321011926979, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], "filamentTotal": 7143.321011926979, "id": 7, "layer": 103, "length": 2372545, "lines": 83196, "name": "idler_pla", "printTime": 8297.007454602446, "printed": 38, "state": "stored", "volumeTotal": 17181.70056018542, "volumeUsage": [ 17181.70056018542, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ] }
] }

Lists all g-code files for the given printer. The response also contains some statistical data.

copyModel

Parameter: id (int) = g-code to copy into print queue.

Response

{}

Copies a g-code to the list of print jobs.

listJobs

Parameter: None

Response

{ "data": [ { "analysed": 1, "created": 1377942678000, "extruderUsage": [ 178.3384707110235, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], "filamentTotal": 178.3384707110235, "id": 2, "layer": 48, "length": 48927, "lines": 1755, "name": "wall_0_83", "printTime": 435.9966997422252, "printed": 0, "printedTimeComp": 0, "state": "stored", "volumeTotal": 0, "volumeUsage": [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ] }, { "analysed": 1, "created": 1381658340000, "extruderUsage": [ 7143.321011926979, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], "filamentTotal": 7143.321011926979, "id": 3, "layer": 103, "length": 2372545, "lines": 83196, "name": "idler_pla_irapid.gcode", "printTime": 6992.575336368939, "printed": 0, "printedTimeComp": 0, "state": "stored", "volumeTotal": 0, "volumeUsage": [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ] } ] }

Lists all print jobs.

startJob

Parameter: id (int) = print job to start.

Response

{}

Starts a print.

stopJob

Parameter: none

Response

{}

Stops the running print!

continueJob

Parameter: none

Response

{}

Continues the paused print!

removeJob

Parameter: id (int) = print job to remove.

Response

{}

Deletes a print job that must not be the one beeing printed.

getPrinterConfig

Parameter: printer (string) = slug of printer from which you want the config. Omit it to get the config of current printer.

Response

{ "connection": { "serial": { "baudrate": 250000, "device": "/dev/tty.usbmodemfa1321", "inputBufferSize": 127, "pingPong": false, "protocol": 0 } }, "extruders": [ { "acceleration": 6000, "cooldownPerSecond": 0.5, "eJerk": 40, "extrudeSpeed": 2, "filamentDiameter": 1.75, "heatupPerSecond": 1.5, "lastTemp": 185, "maxSpeed": 20, "maxTemp": 250, "offsetX": 0, "offsetY": 0, "retractSpeed": 20, "temperatures": [ { "name": "PLA 185°C", "temp": 185 }, { "name": "PLA 190°C", "temp": 190 }, { "name": "PLA 200°C", "temp": 200 }, { "name": "PLA 205°C", "temp": 205 }, { "name": "PLA 210°C", "temp": 210 } ] }, { "acceleration": 6000, "cooldownPerSecond": 1, "eJerk": 40, "extrudeSpeed": 2, "filamentDiameter": 1.75, "heatupPerSecond": 1.5, "lastTemp": 0, "maxSpeed": 20, "maxTemp": 260, "offsetX": 0, "offsetY": 0, "retractSpeed": 20, "temperatures": [ { "name": "PLA 185°C", "temp": 185 }, { "name": "PLA 190°C", "temp": 190 }, { "name": "PLA 200°C", "temp": 200 }, { "name": "PLA 205°C", "temp": 205 }, { "name": "PLA 210°C", "temp": 210 } ] } ], "general": { "active": true, "eepromType": "repetier", "fan": true, "firmwareName": "Repetier-Firmware", "heatedBed": true, "name": "iRapid", "printerVariant": "cartesian", "sdcard": true, "slug": "irapid", "softwarePower": false, "tempUpdateEvery": 1 }, "heatedBed": { "cooldownPerSecond": 1, "heatupPerSecond": 1, "installed": true, "lastTemp": 1, "maxTemp": 120, "temperatures": [ { "name": "PLA 60°C", "temp": 60 }, { "name": "ABS 110°C", "temp": 110 } ] }, "movement": { "allEndstops": true, "maxXYSpeed": 200, "maxZSpeed": 100, "movebuffer": 16, "timeMultiplier": 1, "xEndstop": true, "xHome": 0, "xMax": 250, "xMin": 0, "xyJerk": 30, "xyPrintAcceleration": 250, "xySpeed": 100, "xyTravelAcceleration": 250, "yEndstop": true, "yHome": 0, "yMax": 150, "yMin": 0, "zEndstop": true, "zHome": 0, "zJerk": 0.3, "zMax": 90, "zMin": 0, "zPrintAcceleration": 100, "zSpeed": 100, "zTravelAcceleration": 100 }, "quickCommands": [], "shape": { "basicShape": { "color": "#e5e5e5", "radius": 100, "shape": "rectangle", "x": 0, "xMax": 250, "xMin": 0, "y": 0, "yMax": 150, "yMin": 0 }, "gridColor": "#000000", "gridSpacing": 10, "marker": [] }, "webcam": { "dynamicUrl": "http://192.168.1.100:8000/?action=stream", "method": 0, "reloadInterval": 2, "staticUrl": "http://192.168.1.100:8000/?action=snapshot", "timelapseInterval": 11, "timelapseMethod": 0 } }

Returns the printer configuration as json string. Use the same or modified version to save changes. That way you keep the data structure intact even you did not know about new parameter.

setPrinterConfig

Parameter: json string from getPrinterConfig including your modifications.

Response

{}

Updates the printer configuration. Uses the current printer as recipient. Triggers printerListChanged event.

getScript

Parameter: name (string) = script name.

Response

{ "name": "start", "script": ";Start script" }

Returns the content of a script. Possible script names are start, end, kill and pause.

setScript

Parameter: name (string) = script name, script (string) = script content.

Response

{}

Stores the new content of a printer script. Scripts should be limited to 20kb.

activate

Parameter: printer (string) = slug name of the printer.

Response

{}

Activates a printer. Only activated printer will try to connect to a printer.

deactivate

Parameter: printer (string) = slug name of the printer.

Response

{}

Deactivates a printer. Only activated printer will try to connect to a printer. Deactivate it if you need to connect to the printer with a different programm, e.g. for uploading a new firmware.

communicationData

Parameter: None.

Response

{ "bytesReceived": 272294, "bytesSend": 29997, "linesSend": 4283, "resendErrors": 0 }

Returns statistics about the data exchanged between printer and server.

getEeprom

Parameter: None.

Response

{}

Initalizes the polling of eeprom settings from the firmware. Works only with Repetier-Firmware. As a result you should get a eepromClear event followed by a number of eepromData events for each data stored in eeprom. The responses look like this:

{"pos":"75","text":"Baudrate","type":"2","value":"250000","valueOrig":"250000"}

setEeprom

Parameter: eeprom (array) = List of objects to set. Each object must look like this:

{"pos":"73","type":"3","value":"80","valueOrig":"88"}

Response

{}

Uploads all changed values to eeprom. You need to provide the old and new value! You can omit unchanged values.

listExternalCommands

Parameter: None.

Response

[ { "confirm": "", "id": 0, "name": "Start webcam streamer" }, { "confirm": "Really shutdown?", "id": 1, "name": "Shutdown" } ]

Lists all available external commands. Some commands should ask a question to confirm it.

runExternalCommand

Parameter: id (int) = Command to run.

Response

{}

Starts a command by command id.

createConfiguration

Parameter: name (string) = printer name, slug (string) = printer slug name.

Response

{}

Creates a new printer configuration.

removeConfiguration

Parameter: slug (string) = printer slug name.

Response

{}

Deletes a printer with all assiciated files.

getSettings

Parameter: None.

Response

{ "BetaMessage": "## Beta version ##\n\nThis is a beta version of the Repetier-Server and therefore no license is required.\nOnce the test period ends, you may require a valid license to continue to use all functions of the software.\nThe basic functions for printing will stay free. \n", "BuildAvailable": 36, "IgnoreBuild": 35, "VersionMessage": "## What is new ##\n\n### 0.50 ###\n* G-code preview\n* Accurate printing time prediction\n* Show current layer during print\n* Easy configuration\n", "VersionName": "0.50.3", "VersionTested": 1, "defaultLanguage": "en", "g_push_active": true, "g_push_group": "RQ2I8-80Z3B-BVJJD-ZDCQV-9SCPL", "g_push_print_error": true, "g_push_print_finished": true, "g_push_print_paused": true, "g_push_print_started": true, "g_push_print_stopped": true, "g_push_url": "", "lastRunBuild": 36, "pricing": { "currency": "EUR", "filaments": [ { "n": "ABS", "p": 20, "u": "mrJ2A9uQnv", "w": 1.35 }, { "n": "PLA", "p": 25, "u": "w28d9JK7K9", "w": 1.3 } ], "map": { "0_Test": "mrJ2A9uQnv", "0_delta": "w28d9JK7K9", "0_irapid3": "w28d9JK7K9" }, "perHour": 0.3, "perPrint": 5 } }

Fetches a object with the public global settings.

updateSettings

Parameter: Settings object with changed settings.

Response

{}

Updates the global settings given.

updateUserSettings

Parameter: Settings object with changed settings.

Response

{}

Updates the user settings given.

userlist

Parameter: None.

Permissions required: configure

Response

{ "loginRequired": true, "users": [ { "id": 1, "login": "repetier", "permissions": 15 } ] }

Returns a list of users and their permissions.

createUser

Parameter: login (string), password (string), permissions (int).

Permissions required: configure

Response

{"success":true}

Creates a new user with given permissions. permissions is a bitfield with the following permissions:

updateUser

Parameter: login (string), password (string, optional), permissions (int).

Permissions required: configure

Response

{}

Changes the user permissions and updates password if one is given. The current user can not unset his own permissions. Only new permissions can be added.

deleteUser

Parameter: login (string).

Permissions required: configure

Response

{"success":true}

Deletes the given user. You can delete the current user only if it is the last existing user.

listPorts

Parameter: None.

Response

[ "/dev/tty.Bluetooth-Incoming-Port", "/dev/tty.Bluetooth-Modem", "/dev/tty.usbmodemfa1321" ]

Returns a list of currently existing serial ports.

updateAvailable

Parameter: None.

Response

{ "betaActive": false, "downloadUrl": "http://www.repetier-server.com", "fetaures": 4095, "free": true, "ignoreBuild": 35, "message": "## Beta version ##\n\nThis is a beta version of the Repetier-Server and therefore no license is required.\nOnce the test period ends, you may require a valid license to continue to use all functions of the software.\nThe basic functions for printing will stay free. \n", "messageHtml": "\n\n", "updateAvailable": false, "versionBuild": 36, "versionMessage": "## What is new ##\n\n### 0.50 ###\n* G-code preview\n* Accurate printing time prediction\n* Show current layer during print\n* Easy configuration\n", "versionMessageHtml": "", "versionName": "0.50.3" }

Checks if a update is available.

ignoreUpdate

Parameter: None.

Response

{}

Sets ignoreBuild to the latest available update. That information should be used to stop the user from bugging with update requests.

testPushMessage

Parameter: None.

Response

{"send":true}

Tries to send a push message to your smartphone.

listFirmwareNames

Parameter: None.

Response

{ "firmwareNames": [ "Repetier-Firmware", "Marlin" ] }

Lists all firmware variants the server is configured to work with.

startUpdateFirmwareSettings

Parameter: None.

Permissions required: configure

Response

{}

Starts automatic detection of some firmware data. Wait a few seconds and then continue with getFirmwareSettings to receive the result.

getFirmwareSettings

Parameter: None.

Permissions required: configure

Response

{ "settings": { "XLength": 250, "XMin": 0, "XStepsPerMM": 102, "YLength": 150, "YMin": 0, "YStepsPerMM": 102, "ZLength": 90, "ZMin": 0, "ZStepsPerMM": 102, "baudrate": 250000, "extrAcceleration[0]": 10000, "extrAcceleration[1]": 10000, "extrJerk[0]": 50, "extrJerk[1]": 50, "extrMaxSpeed[0]": 100, "extrMaxSpeed[1]": 100, "extrStepsPerMM[0]": 150, "extrStepsPerMM[1]": 150, "extruderCountSend": 2, "fanInstalled": true, "maxXSpeed": 200, "maxXYSpeed": 200, "maxYSpeed": 200, "maxZSpeed": 100, "printerType": 1, "sdInstalled": true, "xPrintAcceleration": 250, "xTravelAcceleration": 250, "xyJerk": 30, "xyPrintAcceleration": 250, "xyTravelAcceleration": 250, "yPrintAcceleration": 250, "yTravelAcceleration": 250, "zJerk": 0.3, "zPrintAcceleration": 100, "zTravelAcceleration": 100 } }

Returns the last firmware settings from printer we could determine.

getFirmwareData

Parameter: None.

Response

{ "firmware": { "eeprom": "repetier", "firmware": "Repetier_0.92", "firmwareURL": "https://github.com/repetier/Repetier-Firmware/", "name": "Repetier-Firmware" } }

Returns basic data read from printer firmware.

listLogs

Parameter: None.

Response

{ "active": "connected", "logs": [ { "name": "connected", "size": 58620, "time": 1420741228 }, { "name": "idler_pla_irapid.gcode", "size": 5078661, "time": 1381661665 }, { "name": "Rollenhalter Bein", "size": 784997, "time": 1377881206 }, { "name": "spoolholder_b.gcode", "size": 5101792, "time": 1377881152 }, { "name": "thinwall.gcode", "size": 951, "time": 1377880154 } ] }

Shows available logs for active printer.

removeLog

Parameter: log (string) = Name of the log file.

Response

{}

Removes the given log.

setLogLevel

Parameter: level (int) = logging level you want events for.

Response

{}

Select which logging messages you want to get as log events. Bit values for level types are:
1 : Commands
2 : ACK responses like ok, wait, temperature
4 : Other responses
8 : Non maskable messages

sendMoves

Parameter: None.

Response

{}

Starts sending move events for your printer.

hideMoves

Parameter: None.

Response

{}

Stops sending move events to your printer.

setSpeedMultiply

Parameter: speed (int) = speed multiplier in percent.

Permissions required: print

Response

{}

Changes the speed multiplier.

setFlowMultiply

Parameter: speed (int) = flow multiplier in percent.

Permissions required: print

Response

{}

Changes the flow multiplier.

emergencyStop

Parameter: none

Permissions required: print

Response

{}

Runs a emergency stop sequence. This is not only sending M112 but also trying to reset the printer for a faster response. Available since 0.75

sendMoves

Parameter: none

Permissions required: none

Response

{}

Tells server to send a event for each printer move. Only moves for the active printer get send. Do not enable it, if you do not need the moves, so you reduce traffic a lot.

hideMoves

Parameter: none

Permissions required: none

Response

{}

Stops sending printer move messages.

version

Parameter: None.

Response

{ "build": 36, "major": 0, "minor": 50, "name": "Repetier-Server 0.50.3", "patch": 3 }

Returns the server version, build number and name.

getPrinterSetting

Parameter: key (string) = key to search, def (string) = default value

Response

{value:"current value"}

Changes the flow multiplier.

setPrinterSetting

Parameter: key (string) = key name, value (string) = new value.

Permissions required: config

Response

{}

Updates the given key to given value for the set printer.

getPrinterSettings

Parameter: None.

Response

{key1:"value1",key2:"value2"}

Returns a map with all printer settings.

Group related commands

Since 0.75.2 you can assign groups to uploaded g-codes. The following commands handle group listing and management. New uploads can define a group to assign them. The group "#" is the default group and should be named so in the current language. Each printer has a own list of groups.

listModelGroups

Parameter: None.

Response

{ "groupNames": [ "#", "My Robot" ], "ok": true }

Returns a list with group names. ok = true/false depending on success.

addModelGroup

Parameter: groupName (string) = Group name to create

Response

{ "ok": true }

Creates a new group with given name. Returns ok = true/false depending on success. Triggers "modelGroupListChanged" event to notify all connected clients about the change.

delModelGroup

Parameter: groupName (string) = Group name to delete, delFiles = 0 = move files to default, 1 = delete contained files.

Response

{ "ok": true }

Deletes a group with given name. Files are moved to default group (undeleteable) or get deleted depending on delFiles parameter. Returns ok = true/false depending on success. Triggers "modelGroupListChanged" event to notify all connected clients about the change.

moveModelFileToGroup(

Parameter: groupName (string) = Group name to delete, id = file id to move.

Response

{ "ok": true }

Moves a g-code model file with given id to a existing group groupName. Returns ok = true/false depending on success. Triggers "jobsChanged" event to notify all connected clients about the change.

Folder related commands

0.75 introduced browsable folders on the server computer. The following commands handle usage of these commands.

listFilesystemFolders

Parameter: root (string) = Start directory, next (string) = Next directory.

Response

{ "folders": [ { "name": ".vol", "path": "/.vol" }, { "name": "Applications", "path": "/Applications" }, { "name": "bin", "path": "/bin" }, { "name": "cores", "path": "/cores" }, { "name": "data", "path": "/data" }, { "name": "dev", "path": "/dev" }, { "name": "Developer", "path": "/Developer" }, { "name": "Downloads", "path": "/Downloads" }, { "name": "etc", "path": "/etc" }, { "name": "Handbücher & Informationen", "path": "/Handbücher & Informationen" }, { "name": "home", "path": "/home" }, { "name": "Library", "path": "/Library" }, { "name": "net", "path": "/net" }, { "name": "Network", "path": "/Network" }, { "name": "opt", "path": "/opt" }, { "name": "private", "path": "/private" }, { "name": "sbin", "path": "/sbin" }, { "name": "System", "path": "/System" }, { "name": "tmp", "path": "/tmp" }, { "name": "Users", "path": "/Users" }, { "name": "usr", "path": "/usr" }, { "name": "var", "path": "/var" }, { "name": "Volumes", "path": "/Volumes" } ], "ok": true, "root": "/" }

Required permission: configure

This command is used to select directors to use for folders. Start with root="". next is normally empty or ".." to go a level up.

getFolders(

Parameter: none

Response

{ "folders": [ { "dir": "/", "id": 1, "name": "All" }, { "dir": "/Users/littwin/Documents/RepRap/gcodes", "id": 2, "name": "G-Codes" } ], "ok": true }

Returns the list of implemented folders. These can be used later to browse throug and upload files.

setFolders(

Parameter: folders (array of objects) = new list of folders.

Response

{ "ok": true}

Required permission: configure

Defines a new list of folders. The folders parameter must be similar to the returned list from getFolders, just with the modifications you want (added, removed, renamed objects). Triggers "foldersChanged" event.

browseFolder(

Parameter: folder (int) = folder id, root (string) = start position ,next (string) mod to root}

Response

{ "files": [ { "isDir": false, "name": ".DS_Store", "path": "/.DS_Store", "size": 6148 }, { "isDir": true, "name": "delta", "path": "/delta" }, { "isDir": true, "name": "felix", "path": "/felix" }, { "isDir": true, "name": "irapid", "path": "/irapid" }, { "isDir": true, "name": "irapidmini", "path": "/irapidmini" }, { "isDir": true, "name": "Laser", "path": "/Laser" }, { "isDir": true, "name": "ordbot", "path": "/ordbot" }, { "isDir": true, "name": "pharaoh", "path": "/pharaoh" }, { "isDir": true, "name": "slicerdata", "path": "/slicerdata" }, { "isDir": true, "name": "Stacker", "path": "/Stacker" } ], "ok": true, "root": "/" }

List all files and directories in a folder. Folders start with "" as root. next is normally not needed. Just use "path" as next root to browse through directories.

importURL

Parameter: folder (string) = model group to import, files (array of objects) = List if files to import

Response

{ "msgId": "78234823-dsfgds-242-fsd", "ok": true}

This command imports one or more files from a url. There is a special notion for files in folders, so this can be used as a general import command. All files get downloaded in a seperate thread, so the call immediately returns. The return parameter msgId allows it to track import progress. During import you get events with name "progressUpdate" and a content like this:

{"progress":55, "finished": false}

This allows it to show a progressbar or you can ignore it, just as you want.

The files parameter is a array, where each object contains the following parameter:

{
        "name":"name after import",
        "url":"url to the file",
        "job":false
    }

"name" is the imported name. Can be left empty if you just want the last name from url.
"url" is the url to the file. Make sure it starts correctly with http or https. For import from folders use the format "folder://folderId/pathtofile". So if file is /robot/arm.gcode in folder 3 it would be "folder://3/robot/arm.gcode"
"job" sets if you want to print the file directly (true) or store it in the model list (true).

Events

loginRequired

Payload: None.

A authorized user was required. Login with user credentials. You get this message only once when you establish the socket connection.

logout

Payload: None.

Gets send as response on a logout request. The event is send to all instances sharing the same session.

userCredentials

Payload: {"login":"Login name","permissions":15,"settings":{}}

When you reconnect a still existing session no login is required. As a first event you get the credentials of

printerListChanged

Payload: List of printers like in listPrinters response.

Gets triggered when a printer was added, deleted or modified.

messagesChanged

Payload: None.

Gets triggered when a new message gets available. That way you do not need to poll for new messages, only once at the connection start.

move

Payload: {"x":1,"y":1,"z":0,"e":67.233,"de":0.023}

When moves are enabled (sendMoves action) you will get a event for every move the printer does. This can be used to provide a live preview of what the printer does.

log

Payload: {"id":1,"time":14535345345,"text":"ok","type":2}

When the proper log level is set, you get events for each new log line you wish to see. Type indicates one of the following: 1 : Commands
2 : ACK responses like ok, wait, temperature
4 : Other responses
8 : Non maskable messages

jobsChanged

Payload: None.

Gets triggered if a printer has a change in it's stored g-file list.

jobFinished (0.60.2)

Payload: {start:unixTime,duration:seconds,end:unixTime,lines:linesOfJob}

Gets send after a normal job has finished.

jobKilled (0.60.2)

Payload: {start:unixTime,duration:seconds,end:unixTime,lines:linesOfJob}

Gets send after a normal job has been killed.

jobStarted (0.60.2)

Payload: {start:unixTime}

Gets send after a normal job has been started.

printqueueChanged

Payload: None.

Gets triggered if a printer has a change in it's list of waiting prints.

foldersChanged

Payload: None.

Gets triggered if the list of folders has changed.

eepromClear

Payload: None.

Gets triggered when eeprom load is started. Old values should be discarded and new values stored afterwards.

eepromData

Payload: One eeprom parameter description.

Gets triggered after eeprom load is started. Gets send for each eeprom entry the firmware sends to server.

state

Payload: State data for one printer.

Gets triggered when a state changes.

config

Payload: Config data for one printer.

Gets triggered when a configuration changes.

firmwareChanged

Payload: New firmware data.

Gets triggered when new firmware data were fetched from firmware.

temp

Payload: { "O": 0, "S": 0, "T": 24, "id": 1, "t": 1423671195610 }

New temperature entry. O = Output, S = Set temperature, T = Measued temperature, id = Extruder number, t = Timestamp

settingChanged

Payload: List of new settings

Gets triggered when a global setting variable got changed.

printerSettingChanged

Payload: {key:"key",value:"new value"}

Gets triggered everytime a printer setting gets changed.

modelGroupListChanged

Payload: none

Gets triggered if a printer changes the list of groups for g-codes stored. Clients should use this to update their lists.

Demo application

We know that it is hard to get used to a new API, so we made a simple demo application. To get most of it, it has 2 purposes. At first it should show how to connect, receive events and send commands. The second is helping to understand the API. So what it does is connect and allow you to send any command and data you like. Then it will show the result. Below that you see the latest event. If you want to analyse the event response for a longer while you can also pause the event update with a check button. We used this little tool to create this documentation and it was really helpfull. So if you have doubts on what we meant, just try it and see what happens. Everything runs inside your webbrowser, so you can use the online app to test your local server.

Test Demo App

Download Demo App