Inside the Ultimaker 3 - Day 2 - Remote access (part 1)

9
Daid Team Ultimaker Points: 6188
Posts: 4670

Posted by
Daid

Posted Oct 20, 2016 - 10:57 AM • Edited  Oct 21, 2016 - 1:52 PM  

This is day 2 of "Inside the Ultimaker 3", Remote access.

-

Other days:

Day 1 - GCode

Day 3 - Remote access (part 2)

-

A new day, a new piece of information. Yesterday we took a quick look at the changes in gcode files. Which is the core of pretty much any 3D print.

Today, we will look at the remote access trough the network. The remote API is designed to allow control of the machine trough the network. It is what Cura uses to control and monitor the machine remotely.

-

Even if you are not a software engineer, there is added value for you here. So do not stop reading yet!

The technology behind the API

The API is a REST interface using JSON. That could be 3 new words for you right there. Don't worry.

  • API: Application Programming Interface. Simply meaning it's an thing designed so that applications can talk to eachter. Does not mean we cannot use it as an user. But the end goal is for other applications.
  • REST: Representational State Transfer. Just a fansy way of saying that every "request" you do to the printer is "stateless". Also, just a standardized way of doing things. The really cool part here is that is done trough HTTP.
  • JSON: Javascript Object Notation. A standadized way to represent data. This makes it easier for applications to understand each other. Nothing to worry here, it is quite easy to read by humans.
  • HTTP: Hyper Text Transfer Protocol. For those that missed it, I introduced this term in the REST term. If you are now like "I have seen this before, but where?" that is most likely true. Http is the way your browser talks to a webserver.

So, in a nutshell. Our remote access on the printer is actually just a website acting in a standarized way so applications (like Cura) can understand it.

Example time!

You most likely don't have your fansy Ultimaker 3 yet. But I do. Now, first things you need to do is connect your printer to a network. As it's not really possible to access something remotely without access. So setup that WiFi or just plug in a cable.

-

Next you need your IP address. You can find it in the {SYSTEM}->{Network}->{Connection status} menu. It is those 4 numbers with dots in between. For this example, I'll be using 10.180.1.71, as that is my printer.

-

Now, you don't need any tool. As you already have the tool for basic viewing of data. You are looking at it. It is your browser. You have this fancy location bar at the top of your browser.

And if we enter http://10.180.1.209/api/v1/system/firmware there, we will see the result:

"3.4.12.20161017"

That is your firmware version. Could not be simpler. Just so you know, the firmware version is build out of [major].[minor].[revision].[date], every version we use, even internally for testing, gets a new number for tracebility.

-

I picked a simple example for a reason, so we could look into this at a bit more detail first. The address you entered. Or URL as it is called in fancy computer terms is made up out of these parts:

  • http://: This means we are using http. Part of REST remember?
  • 10.180.1.209: The IP address we looked up on the printer.
  • /api/v1: This means we are accessing our API, and the first version of it. If we ever need to make incompattible changes, we will have a v2 here and keep the v1 for a long as we can.
  • /system: We are accessing the "system" part. System contains things that are not really 3d printer specific. Any device could have these properties.
  • /firmware: We are requesting the "firmware" part of system. Which is defined are returning the firmware version.

Having that made clear, in the system we have the following parts:

http://10.180.1.209/api/v1/system/platform - Returns the linux version that we are running on, who cares right?

http://10.180.1.209/api/v1/system/hostname - Returns the hostname of the printer. This is not user configurable and will remain the same unless electronics are replaced. So you can use this to uniquely identify the printer.

http://10.180.1.209/api/v1/system/name - This is the user configurable name. You are asked to configure this during the WiFi setup.

http://10.180.1.209/api/v1/system/firmware - As explained, the current firmware version.

http://10.180.1.209/api/v1/system/memory/used - The amount of memory in use by the system.

http://10.180.1.209/api/v1/system/memory/total - The amount of memory available in total.

http://10.180.1.209/api/v1/system/memory/log - The system keeps a log of many state changes, this API accesses that log. More on it later.

http://10.180.1.209/api/v1/system/memory/language - The configured language, we are preparing for providing the printer in your native language as well. But we decided not to delay the release for this. So this is always empty right now.

http://10.180.1.209/api/v1/system/memory/country - 2 letter country code, if configured. This is done during the WiFi setup. WiFi hardware needs to be configured for your region to make sure the proper WiFi channels are used. If you don't use WiFi this is most likely empty.

-

However, if you want all of these in a single go. You can just request:

http://10.180.1.209/api/v1/system

Which will respond with:

{"country": "", "firmware": "3.4.12.20161017", "hostname": "ultimakersystem-ccbdd3000229", "language": "en", "log": ["...", "..."], "memory": {"total": 1057030144, "used": 125394944}, "name": "Ultimaker-000229", "platform": "Linux-4.2.0-rc7-opinicus-00001-g63c264e-armv7l-with-debian-8.1"}

Note that I cut out the log data, the rest is a JSON response. It looks a bit hard to read, but computers have no problem in reading it. There are however, tools to format it in a more readable way:

{
    "country": "",
    "firmware": "3.4.12.20161017",
    "hostname": "ultimakersystem-ccbdd3000229",
    "language": "en",
    "log": [
        "...",
        "..."
    ],
    "memory": {
        "total": 1057030144,
        "used": 125394944
    },
    "name": "Ultimaker-000229",
    "platform": "Linux-4.2.0-rc7-opinicus-00001-g63c264e-armv7l-with-debian-8.1"
}

There is http://10.180.1.209/log.html currently on the printer that uses /api/v1/system/log to view the latest log data in a more readable format. It was quickly put together and I'm sure we will expand to a better web interface for the printer in the future.

But, it is a 3D printer!

Yes yes. It is a 3D printer. So we want 3D printer data. And we have that. There are 2 basic important start points:

http://10.180.1.209/api/v1/printer

http://10.180.1.209/api/v1/print_job

The first contains a lot of information about the printer itself. And all of those things can be accessed in the same way as the system part.

The second contains information about the currently running print job. If no job is running, you will get a "not found" error. For the technical people, this includes status code 404.

/api/v1/printer

Let us look at the /api/v1/printer first. This as the following sub parts:

/api/v1/printer/led - Part to access the printer casing leds.

/api/v1/printer/heads - Part to access the printer head (more on this one later)

/api/v1/printer/bed - Part to access information of the printer bed, limited to current and target temperature.

/api/v1/printer/status - Best thing to look at first. Basic status of the printer. This could be "idle", "printing", "error", "maintenance" or "booting". Will explain in a bit.

/api/v1/printer/beep - Nothing to read from here. Can be written to to make the printer beep.

/api/v1/printer/diagnostics - Different diagnostic functions. Retreiving this part does not do anything, but it has sub parts that are not collected in the /api/v1/printer that can be used for in depth diagnostic functions. We WILL go over this for sure.

/api/v1/printer/network - Contains the WiFi and Ethernet information. Mostly usefull to see if it is cable of WiFi connected. But the WiFi setup process uses this to connect to a network and to see which networks are available.

/api/v1/printer/status

The main status of the printer, can be:

  • idle: Printer is doing nothing and ready for action.
  • printing: Printer is actively printing something, or still needs to be emptied, print_job needs to be retreived for details.
  • error: Something is wrong with the printer, and requires action at the printer itself to be corrected.
  • maintenance: Someone is actively doing things with the printer, for example changing materials or PrintCores.
  • booting: Printer is still starting up. This only lasts for a few seconds.

/api/v1/printer/heads

The printer has a single head. However, the API is prepared for possible futures, so it accounts for multiple heads already. Do not take this as a reason to think we are developing multi head printers. It just good engineering practice to have this in place when it costs almost no effort.

-

So, the actual part that we need to access for print head information is:

http://10.180.1.209/api/v1/printer/heads/0

Software engineers are mighty annoying, as we start counting at 0. So the first head is identified by 0. The first hotend is identified by 0 and the second one with 1.

-

In here we have some basic settings like acceleration values, maximum speeds, the current position and linked extruders with their hotends. Feel free to explore.

As you are all in love with the current hotend temperature, I will show you that one:

http://10.180.1.209/...0/hotend/temperature

http://10.180.1.209/...1/hotend/temperature

For the first and second extruder. But, by sheer magic, we also know what type of PrintCore you have in the machine, which can be seen from:

http://10.180.1.209/...xtruders/0/hotend/id

In my case, it returns "AA 0.4"

There is the fan entry:

http://10.180.1.209/api/v1/printer/heads/0/fan

Which contains the print cooling fan speed in 0% to 100% (not 0 to 255 as you see in GCode). The head cooling fan state is not accessible, but directly linked to the hotend temperatures.

Small note of warning

There is http://10.180.1.209/...active_material/GUID. However, this breaks with the rest of the API and will be removed. Use the lower case http://10.180.1.209/...active_material/guid instead.

/api/v1/printer/diagnostics

Currently, the only intressing part here is:

http://10.180.1.209/.../temperature_flow/10

The last number can be changed up to 20000, but that might take a while to load. The printer takes about 10 samples per second.

The result of this is:

[
["Time", "temperature0", "target0", "heater0", "flow_sensor0", "flow_steps0", "temperature1", "target1", "heater1", "flow_sensor1", "flow_steps1", "bed_temperature", "bed_target", "bed_heater"],
[62868.34765625, 23.100000381469727, 0.0, 0.0, 0.0, 0.0, 23.0, 0.0, 0.0, 0.0, 0.0, 18.299999237060547, 0.0, 0.0],
[62868.453125, 23.100000381469727, 0.0, 0.0, 0.0, 0.0, 23.0, 0.0, 0.0, 0.0, 0.0, 18.700000762939453, 0.0, 0.0],
[62868.5625, 23.100000381469727, 0.0, 0.0, 0.0, 0.0, 23.0, 0.0, 0.0, 0.0, 0.0, 18.399999618530273, 0.0, 0.0],
[62868.671875, 23.100000381469727, 0.0, 0.0, 0.0, 0.0, 23.0, 0.0, 0.0, 0.0, 0.0, 18.399999618530273, 0.0, 0.0],
[62868.78125, 23.100000381469727, 0.0, 0.0, 0.0, 0.0, 23.0, 0.0, 0.0, 0.0, 0.0, 18.399999618530273, 0.0, 0.0],
[62868.890625, 23.100000381469727, 0.0, 0.0, 0.0, 0.0, 23.0, 0.0, 0.0, 0.0, 0.0, 18.5, 0.0, 0.0],
[62869.00390625, 23.100000381469727, 0.0, 0.0, 0.0, 0.0, 23.0, 0.0, 0.0, 0.0, 0.0, 18.299999237060547, 0.0, 0.0],
[62869.11328125, 23.100000381469727, 0.0, 0.0, 0.0, 0.0, 23.0, 0.0, 0.0, 0.0, 0.0, 18.700000762939453, 0.0, 0.0],
[62869.22265625, 23.100000381469727, 0.0, 0.0, 0.0, 0.0, 23.0, 0.0, 0.0, 0.0, 0.0, 18.5, 0.0, 0.0],
[62869.328125, 23.100000381469727, 0.0, 0.0, 0.0, 0.0, 23.0, 0.0, 0.0, 0.0, 0.0, 18.0, 0.0, 0.0]
]

It is a history of temperature data for both hotends, and the bed. There is the current temperature, the target temperature and the amount of heating output. There is also something in there called "flow", but that returns 0 for you. Sorry.

Now, this data is a bit hard to parse. But lucky for you, if you want to save this data you can do so very easy, by adding ?csv=1 behind it. Note that this is the only API part that supports this download.

http://10.180.1.209/...rature_flow/10?csv=1

However, like this you can store it for later viewing, or do all kinds of crazy math and graphing with it, as microsoft-excel or libreoffice-calc can both import this file with relative ease.

-

There is http://10.180.1.209/temperature.html currently on the printer that uses this data to plot a real-time temperature graph. It is not an official feature of the printer and something we used during development. But it is damn cool.

I'm a 100% sure will will expand this diagnostics part later with more data collection. So stay tuned for firmware updates.

/api/v1/print_job

http://10.180.1.209/api/v1/print_job

That's the part that returns the currently active print job. Or it returns:

{"message": "Not found"}

If there is no print job running. It does not return a whole lot of information, but I think it is the most important information that you can have about the printer. So I will go over it in great detail.

A result when a job is running looks like:

{
    "name": "Most awesome PVA print ever done.gcode",
    "progress": 0,
    "state": "pre_print",
    "time_elapsed": 0,
    "time_total": 0
}

Initially, the most important entry to look at is the "state", this is different from the printer status. And can have the following values:

  • printing: Print is currently busy. Most common state.
  • pausing: Print was busy and the printer is in the process of going to the paused state. This usually does not last long.
  • paused: Print is paused and thus will not finish without used interaction.
  • resuming: Print is resuming after a pause. Could be heating up the hotend again so this can take a while.
  • pre_print: Preparing to print. This is the state before any gcode is run. Active leveling is done during this state as well as heating up the bed/hotends.
  • post_print: Print is finished, cooling down things and homing the head. This state lasts a while because of how the hotends are properly released from filament. (user can skip part of this at the machine)
  • wait_cleanup: Print is fully finished, everything is cooled down. But the print still needs to be removed from the printer. This waits for a conformation of the user at the printer itself.

The progress value is from 0.0 to 1.0 for 0% to 100%, the time values are in seconds. Note that the time_total will be updated during a print as the estimate on when the print is finished will be adjusted during printing. Printing estimates from Cura are usually within the 5% error range. And due to some extra time markers we added the estimate is generally less then 1% off after 2 layers of printing.

-

If you only care about a single value, you can request just that, just like all the other parts of the API.

http://10.180.1.209/api/v1/print_job/name

http://10.180.1.209/api/v1/print_job/state

http://10.180.1.209/api/v1/print_job/progress

http://10.180.1.209/api/v1/print_job/time_elapsed

http://10.180.1.209/api/v1/print_job/time_total

Documentation

I've uploaded our work-in-progress documentation files at: http://software.ultimaker.com/jedi/api/2016.10.20/, these can be viewed with http://editor.swagger.io/. Note that there could be errors and mistakes in this documentation.

Wrapping it up

This is day 2. I think this is a information overload for quite some people already. I also have actual work to do. Tomorrow I will go into the details of using the API to actually change things. That will be a lot more technical then today. Expect code.

Also, I don't know how many days I will fill on remote access. As there is a lot to cover. Stay tuned.

-

-

Disclaimer: Any information presented here could be wrong. I did my best to proof read everything, but it could conflict with official statements and the actual behavior of the printer.

8 replies
 4008 9
Best replies 
Sort 
DidierKlein Moderator Points: 8962
Posts: 5112
Location: Harre, Belgium Printers: Ultimaker 2, Ultimaker Original, Ultimaker 2 Extended, Ultimaker 2 Go, Ultimaker 2+, Ultimaker 3
Posted by
DidierKlein

Posted Oct 20, 2016 - 11:16 AM

I love this! It's really interesting stuff thanks again for sharing!

Nicolinux Moderator Points: 3806
Posts: 2575
Location: Wiesbaden, Germany Printers: Ultimaker 2+, Ultimaker 3
Posted by
Nicolinux

Posted Oct 20, 2016 - 11:30 AM

I love how you have to state we shouldn't infer that there will be more heads just because the API supports it. And no I don't think there will be an official UM3-LED-Lamp addon

One little addition. I am using Postman to access/test the API. It formats everything nicely and is super useful when working with APIs:

https://www.getpostman.com

neotko Moderator Points: 10103
Posts: 4473
Location: Madrid, Spain Printers: Ultimaker Original+, Ultimaker 3
Posted by
neotko

Posted Oct 20, 2016 - 11:35 AM

Quote by Nicolinux

I love how you have to state we shouldn't infer that there will be more heads just because the API supports it. And no I don't think there will be an official UM3-LED-Lamp addon

One little addition. I am using Postman to access/test the API. It formats everything nicely and is super useful when working with APIs:

https://www.getpostman.com

I tried but without succu(because lack of knowhow). Could you explain a small tutorial of how to call the um3 and send basic orders like changing led or using the gcode api?

Daid Team Ultimaker Points: 6188
Posts: 4670
Posted by
Daid

Posted Oct 21, 2016 - 1:54 PM

Quote by neotko

I tried but without succu(because lack of knowhow). Could you explain a small tutorial of how to call the um3 and send basic orders like changing led or using the gcode api?

Day 3 is up, and goes into this topic.

Postmans Digest authentication is too low level to be useful for this. But I've provided example code in python, so maybe that helps.

P
peteruithoven 3D printing enthusiast Level: 17 Points: 278
Posts: 44
Posted by
P
peteruithoven

Posted Oct 27, 2016 - 2:52 PM • Edited 2:52 PM

Why the "?csv=1"? Why not simply ".csv"?

nallath Team Ultimaker Points: 4449
Posts: 2408
Location: Geldermalsen, Netherlands Printers: Ultimaker 3
Posted by
nallath

Posted Oct 27, 2016 - 2:58 PM

Quote by peteruithoven

Why the "?csv=1"? Why not simply ".csv"?

Because the ?csv= is something standard libraries can understand and then generate (aka; Only when you call the API will it generate the CSV file). If you let it link directly to a file (by means of 10.180.1.209/api/v1/printer/diagnostics/temperature_flow/10.csv) implies that there -always- must be a an up to date file named 10.csv at that location (it also implies that there must be a 1,2,3,4, .., n.csv on the machine as well).

T
The3DPrintStudio Level 1 - Starter Points: 5
Posts: 50
Location: Charlotte, United States
Posted by
T
The3DPrintStudio

Posted Feb 23, 2017 - 3:57 PM

Is there a way to remotely access the camera?

nallath Team Ultimaker Points: 4449
Posts: 2408
Location: Geldermalsen, Netherlands Printers: Ultimaker 3
Posted by
nallath

Posted Feb 23, 2017 - 5:07 PM • Edited 5:07 PM

Quote by The3DPrintStudio

Is there a way to remotely access the camera?

Yep;

ip:8080/?action=snapshot

or

ip:8080/?action=stream

8 replies
 4008 9
Best replies 
Sort 
Support