Chapter 1:  Introduction

AstroPrint provides a web interface for performing all of the functions needed to work with a 3D printer remotely, including internet-based slicing of STL files. AstroPrint is a very good looking piece of software straight out of the box, it is certainly much more attractive than most 3D printing host software. But if you want to customize the look and feel of AstroPrint, whether for personal preference, branding, or just to learn more about the inner workings of the software, this guide is for you. Here you will learn how to customize all of the graphics, icons, colors, animations, and whatever other visual elements you want changed.

This guide will cover four ways to customize AstroPrint:

• Customize the icons found on the AstroBox dashboard
• Customize the manual control interface
• Customize colors, fonts, sizes, spacing, layout, and everything else controlled by the CSS
• Customize the small icons found in the toolbars and in random places throughout the software by customizing the webfonts used by AstroPrint

Getting Started

First, know that customizing AstroPrint is not for the faint of heart. We will be using a wide range of different technologies and software to modify various parts of AstroPrint. To begin the process of customizing AstroPrint, we will need to install a number of tools, which are listed below. As you install each tool, I would encourage you to do at least some preliminary reading about what each software package does and how each is used. It will also be extremely useful if you have a general idea of how to work with a Raspberry Pi. This guide attempts to be as clear and understandable as possible, but it will still be very useful if you have some base level of knowledge about the software.

Prerequisites

This guide starts the process of customizing AstroPrint from scratch. The only thing you will need to begin is a working AstroBox and a computer. You can either purchase an AstroBox from AstroPrint, or build your own AstroBox using a Raspberry Pi or PCduino.

Required Software

We will need a number of tools to customize AstroPrint.

 Install PuTTY (Windows Only)

If you are using Windows (as  I am), you will need to download an SSH client. The one recommended by the Raspberry Pi Foundation is PuTTY. PuTTY will allow us to issue commands to the AstroBox without having to connect a monitor, keyboard, and mouse to it. Remember that the default login for the Raspberry Pi is username=pi, password=raspberry.

Install Ruby

AstroPrint uses a tool called sass to make writing and managing the CSS easier. sass is a CSS extension language that offers a number of features that make CSS more powerful and easier to work with, including variables, nested selectors, and partials. sass is a Ruby Gem, so therefore the first step to getting sass is installing Ruby.

Install sass

After you install Ruby, installing Sass is easy. Ruby uses Gems to manage its various packages of code like Sass. Therefore, installing Sass is as easy as running a single command in Ruby:

gem install sass

Install FileZilla

There are a number of FTP clients out there, but the one I like best is FileZilla. FileZilla is fast and quite easy to use, it works great for working with the AstroBox. FileZilla is available for Windows or Mac, simply download the program from the FileZilla website and install it.

Chapter 2:  Setting up FileZilla

All of the AstroPrint modifications we will be making throughout this guide will involve transferring various source files (images, sprite sheets, CSS, fonts, etc.) from the AstroBox to a computer, editing those files, and then transferring the new versions back onto the AstroBox (overriding the original files). So the first thing we will do is set up a convenient way to transfer files back and forth between the AstroBox and your computer. We will use a technology called FTP to share files between a computer and the AstroBox. If you have any experience in web development you have doubtless used FTP before. FTP is a technology for transferring files between two computers over a network, which is exactly what we will need to do for every AstroPrint file we want to edit. You don’t technically need any software to transfer files over FTP besides the terminal or command line. However, using FTP is much easier with a graphical interface. FileZilla is a very popular FTP client that provides an intuitive drag-and-drop interface for transferring files between two computers.

Set AstroBox Root User Password

There is an important step to accessing the AstroPrint files with FileZilla that many tutorials forget to mention. I will summarize the issue and solution, and then take a moment to discuss the issue in more detail. Since accessing the AstroPrint file system with FileZilla is the most fundamental part of customizing AstroPrint, I think it is important to fully understand how it works.

Connect to the AstroBox over SSH

We will set the root user password by issuing commands to the AstroBox over SSH. SSH is technology used to connect to computers remotely; it will allow us to remotely control the AstroBox. Instead of using SSH, we could connect a mouse, keyboard, and monitor to the AstroBox and use the Linux terminal directly, but since we have to do all of our other AstroBox customization work from a remote computer, it is much easier to use SSH.

SSH on Windows using PuTTY

On Windows, you’ll need an SSH client to connect to the AstroBox. The most commonly used SSH client is PuTTY. For complete instructions, follow the tutorial on the Raspberry Pi Foundation website.

Set the Root User Password

When you first make the SSH connection between your computer and your AstroBox, the AstroBox will prompt you for a username and password. We will use the Raspberry Pi’s default login credentials:

Username:  pi
Password:  raspberry

After you log in, you will be able to enter commands. Setting the root user password requires only one command:

sudo passwd root

After entering that command, you will be prompted to enter a password, and then enter it again for verification.

Use the command, “sudo passwd root” to set the root user password.

Configure the FileZilla Connection

Now that we have a password for the Linux root user, we can go forward with setting up FileZilla. First, open up FileZilla and open the Site Manager by clicking on the icon on the far-left side of the toolbar.

Open the site manager.

The Site Manager will allow us to input settings for connecting to the AstroBox and then save those settings. This way we only need to input the connection information once, not every time we want to connect to the AstroBox. Start by clicking on the New Site button and giving your new connection a descriptive name. Then we will input the information necessary for FileZilla to make the connection to the AstroBox:

Host:  <your AstroBox’s IP address>
Protocol:  SFTP – SSH File Transfer Prorocol
Logon Type:  Normal User:  root
Password:  <the password you set for the root user>

Just input the information as above, with your AstroBox’s IP address, and and password you just set for the root user. The information should look something like the image below.

FileZilla to AstroBox connection information in Site Manager.

Press the Connect button and the Site Manager dialog box will close. Keep an eye on the box on the top of the FileZilla window and it will inform you of when the connection is made and if any issues occur while trying to make the connection. The first time you connect to the AstroBox, you will get a message about an “unknown host key.” Since you’re confident of the server’s identity (because you set it up) you can simply click OK. The AstroBox does not have a huge amount of computing horsepower (that is part of what makes it affordable) so it may take FileZilla a moment to connect. When the connection has been established, you will see the AstroBox’s file system appear on the right side of the FileZilla window, with your computer’s file system on the left side. We will learn much more about using FileZilla because we will be using it extensively throughout the rest of this guide.

The box at the top of the window will tell you when the connection has been established and you will be able to see the AstroBox’s file system on the right side of the window.

Chapter 3:  Modifying Dashboard Icons

With FileZilla all set up, we can finally begin making customizations to the AstroPrint software. We will begin with the easiest customization to make, changing the icons in the AstroBox Dashboard. The graphics used throughout AstroPrint come from three places:

• The icons on the AstroBox Dashboard are simply individual images in the AstroPrint source files.
• The icons used in the 3D printer manual control interface are part of a sprite sheet.
• The other icons, like the three in the upper-right corner of the AstroPrint interface and the four tabs on the bottom of the interface, are webfonts.

The icons used on the AstroBox Dashboard are definitely the easiest element in AstroPrint to modify, so we will start our AstroPrint modifications with the Dashboard interface.

We will begin by customizing the seven icons on the AstroBox Dashboard.

Locate the Dashboard Icons

The icons used in the AstroBox Dashboard live in a specific directory within the AstroPrint source files. When you first connect to the AstroBox with FileZilla, on the right side of the screen, where the AstroBox files are displayed, you should see four items:  a .. folder, a .gem folder, a .bashrc file, and a .profile file. In FileZilla, the .. folder has a special purpose; double-clicking on this folder will take you up one level in the directory structure. Start by double-clicking the .. folder. After double-clicking the .. folder, you should see a bunch of folders; this is the / directory, which is the top-level directory in Linux. Every single file on the AstroBox is contained within the / directory. You will find all of the Dashboard icons, as well as some other images we will modify later, in the following directory:

/AstroBox/src/astroprint/static/img

The Dashboard images are found under /AstroBox/src/astroprint/static/img.

There are seven icons used on the AstroBox Dashboard:

• control-icon.png
• file-manager-icon.png
• gcode-terminal-icon.png
• settings-icon.png
• supplies-icon.png
• support-icon.png
• upload-icon.png

Customize your AstroBox Dashboard Icons

You can replace the seven default Dashboard icons with any other images you want, as long as your replacement image are at least 140 x 140 pixels (and they should be exactly that size because using larger images will only increase loading time, and using smaller icons will mess up the layout of the page).

Modifying the Images

If you want, you can transfer the images from the AstroBox to your computer, modify them, then transfer the files back to the AstroBox, replacing the originals. First, on the left side of the FileZilla window, which shows the directory structure for your computer, create a new directory to store the images while you work on them by right clicking anywhere in the window and choosing Create directory. Then, transfer whichever file(s) you want to modify by simply dragging the files from the right side of the window to the left. This will copy the files from the AstroBox to your computer. You can modify the images using whatever image editing software you’d like (if you need a good, free image editing tool, check out Pixlr). Just make sure not to rename the files. Once you’ve made your modifications, transfer the custom images back to the AstroBox by dragging from the left side of the FileZilla window to the right side. It may take a moment for FileZilla to make the connection and transfer the file. FileZilla will give you a warning that the “target file already exists” on the AstroBox. Under the Action section, choose Overwrite and click OK. Finally, hop back over to your browser, either on your computer or on your phone, and refresh the page to see your brand new Dashboard images.

Using New Images

Instead of modifying the AstroBox Dashboard icons, you can just obtain brand new icons and transfer them to the AstroBox. An excellent place for getting custom icons is on Iconfinder. For only $9, you can get all the images you will need to customize AstroPrint. When you’ve found a image you want to use, first download the image as a PNG file. Then, using the image editing software of your choice, resize the image to 140 x 140 pixels. Rename the image file to match the AstroPrint image you wish to replace. When you’ve selected all your custom images, transfer the  images to the AstroBox by dragging from the left side of the FileZilla window to the right side. It may take a moment for FileZilla to make the connection and transfer the file. FileZilla will give you a warning that the “target file already exists” on the AstroBox. Under the Action section, choose Overwrite and click OK. Finally, hop back over to your browser, either on your computer or on your phone, and refresh the page to see your brand new Dashboard images.

Chapter 4:  Modifying Manual Control Icons

Customizing the icons on the manual control interface is a bit more complicated and a bit more difficult than customizing the Dashboard icons. Instead of storing all of the different buttons on the manual control interface as separate images, all the buttons are tiled onto a single image called a sprite sheet.

What is a Sprite Sheet?

A sprite sheet, also called an image sprite or a CSS sprite, is a collection of small images tiled together into a larger image. To display a specific icon, the application just displays a small section of the sprite sheet. For example, to display the little house icon in the center of the horizontal movement controls, AstroPrint starts at the upper-left corner of the icon at (0, -149), and displays a section of the sprite sheet measuring, 68 x 53 px. Using sprite sheets is a more complex than simply using a regular image to be sure. The benefit of using sprite sheets instead of individual images has to do with performance. It is faster for the application to load a single large image into memory and just display parts of it than it is to load a bunch of different images.

Editing the Sprite Sheet

The best way to modify the graphics in the manual control interface is to edit the sprite sheet directly. The sprite sheet is located under

/AstroBox/src/astroprint/static/img

and the file is called img_sprite_control.png. Transfer the file from the AstroBox to your computer using FileZilla by simply dragging the file from the right side of the window to the left side. Finally, open the file in the image editing software of your choice (a good free option is Pixlr). When you are replacing the icons in the sprite sheet with your custom ones, be very careful to use images that are the same size or smaller than the original icons. The new images must also be placed in the same positions. If your icons are larger than the originals, or are not in the same positions, your icons will be cut off (unless you feel like editing the CSS which this guide will show you how to do later, but it does involve some extra work). A good way to make certain the icons in your new sprite sheet are positioned and sized correctly is to use an image editor with layering functionality. You can draw or copy/paste your new icons into a new layer, maintaining the original icons on the background layer. Then, when you are done inserting your new icons, delete the layer with the original images.

It is important for all the icons in the sprite sheet to be in the same locations and be the same size.

After your new sprite sheet is complete, transfer it back to the AstroBox, overwriting the original file, and refresh your browser to see your changes.

Chapter 5:  Modify Other Icons

So far we’ve customized the AstroBox Dashboard icons by replacing the individual icon images, and we’ve customized the manual control icons by modifying the sprite sheet. The remaining images, like those in the upper-right corner of the screen, the four on the bottom of the screen, and other random icons, like the power icon that displays during power down, are created with a more clever technology than image files. These icons are webfonts.

What are webfonts?

Webfonts, also called icon fonts, are just fonts, but instead of letters and numbers, webfonts contain symbols and glyphs. They are like the Wingdings fonts on Windows computers. Webfonts have a number of benefits over using a bunch of images:

• It is faster to load a webfont than it is to load a bunch of images.
• Fonts are vector files, which means they look perfectly crisp on screens of any resolution, unlike images which may become blurry on certain displays.
• The webfont icons can be controlled with CSS, which means their color and size can be easily manipulated.

The downside to using webfonts is that the icons can only use a single color. Fortunately, the AstroPrint icons for which webfonts are used only require one color. So how are webfont characters displayed? Well, if you are not familiar with CSS, it might seem a bit confusing. If you are not interested in how the webfont symbols are displayed, you can just jump to the next section. We will discuss how to make sure the symbols display correctly in the next section. Each “character” in the webfont has a specific code. The characters are displayed by referencing their specific codes in the CSS. For example, the folder icon on the bottom of the page is generated by .icon-folder:before { content: '\e822'; } So E822 is the code for the folder icon. Each icon in the webfont has its own unique code.

Modifying the Webfont Icons

There are several tools available for creating and editing webfonts, but the one used by AstroPrint is Fontello. Fontello is a very well designed tool that is intuitive to use. The first thing we need to do is import the webfont used by AstroPrint. Like with the sprite sheet customization, we are going to swap out the icons in the webfont rather than building a new webfont from scratch. This is because, as described above, each icon in the webfont is associated with a code used to display it. We want to make sure that when we replace an icon, the new icon uses the same code as the old one. That way we don’t need to bother editing the CSS. So, to import the default AstroBox webfont into Fontello, first we need to transfer it from the AstroBox to the computer via FileZilla. The file we want is:

/AstroBox/src/astroprint/static/font/config.json

Just drag the config.json from the AstroBox to your computer in FileZilla like we have with many other files so far. Then, drag the config.json file onto the Fontello page. When you do this, Fontello will automatically select all of the icons the AstroPrint uses by default, there are 41 icons in total.

Dragging the config.json file onto the Fontello page will select all the default icons AstroPrint uses.

Changing the icons in the webfont is a four-step process which we will follow for one icon at a time. It is really important that you swap icons one at a time because this will maintain the same codes for the icons.

1. Switch to the Customize Codes tab in Fontello and jot down the code for the icon you want to change.
2. Go back to the Select Icons and deselect the icon you are changing.
3. Select the new icon you want to use in the place of the one you just deselected.
4. Go back to the Customize Codes tab and verify that the code for the new icon matches the code for the old one you jotted down in step 1.

Just repeat that procedure for all the icons you want to change.

Download and Update the Webfonts

Once you are done replacing whatever icons you want to replace using Fontello, you are ready to download the webfont and upload all the necessary files to the AstroBox. Downloading the webfont is easy, just click the red button in the upper-right corner of the Fontello screen. The Fontello ZIP file contains a number of files, but we will only require four of them:

• config.json (you will recognize this file as the one we imported into Fontello earlier)
• font/fontello.eot
• font/fontello.svg
• font/fontello.ttf
• font/fontello.woff

Even though the config.json file is in a different directory than the font files in the ZIP file you downloaded, all the files go into the same directory on the AstroBox. Using FileZilla, move all four files listed above onto the AstroBox:

/AstroBox/src/astroprint/static/font

As we did before, overwrite the existing files when FileZilla warns you about them.

The config.json file and the four font files all go into the same directory on the AstroBox.

Give your browser a refresh to see your changes.

Chapter 6:  Adjusting the CSS

So far we’ve been doing a great deal of work customizing all of the graphics used throughout the AstroPrint software. Now we are going to switch gears a little bit and work on adjusting all of the other visual elements of the software by adjusting the CSS. The CSS controls all of the colors, sizes, animations, transparencies, borders, fonts, and all other visual elements in the AstroPrint software that aren’t images. If you don’t have any experience working with CSS, you should probably check out some of the numerous tutorials available online because working with the AstroPrint CSS is a much more organic process than customizing the images. Adjusting the CSS is more art than science so this guide will not detail every customization you could make, because there are literally thousands.

Download the AstroPrint Source Files

The process for adjusting the CSS will be a bit different than the process for the images we have been working with thus far. The AstroPrint developers have chosen to use SASS, instead of just regular CSS. Let’s start by understanding what SASS is, because it can be a little confusing.

What is SASS?

SASS stands for “Syntactically Awesome Style Sheets,” which honestly does not explain much about how SASS works, but it is a catchy name. SASS is a tool for making it easier to write and manage CSS. Plain CSS does not work like a programming language, because it isn’t a programming language, it is a markup language. But SASS makes CSS work more like a programming language. SASS is a CSS extension language that adds a number of features to make working the CSS easier. First, SASS adds the ability to use variables in CSS. This, in my opinion, is the most powerful feature offered by SASS. This means certain CSS rules that you use site-wide, or just very often, can be defined as variables. Then, if you want to change these values, you only need to do so once. For example, in AstroPrint, the color scheme is defined using variables in SASS, in the _global.sass file.

$primary-color: #008CBA !default; // bondi-blue
$secondary-color: #e7e7e7 !default; // white-lilac
$alert-color: #f04124 !default; // cinnabar
$success-color: #43AC6A !default; // sea-green
$warning-color: #f08a24 !default; // carrot
$info-color: #a0d3e8 !default; // cornflower

So then, to adjust the color scheme of the AstroPrint software, only these values need to be changed, not all of the dozens of different rules throughout the CSS that reference these colors. The second very useful feature of SASS is selector nesting. The best way to explain this feature is by example. In the code sections below, standard CSS is shown on the left and SASS is shown on the right.

nav {
  ul {
    margin: 0;
    padding: 0;
    list-style: none;
  }

  li { display: inline-block; }

  a {
    display: block;
    padding: 6px 12px;
    text-decoration: none;
  }
}

You can see that nesting selectors makes the SASS easier to read, and faster to write. The third major SASS feature is partials; AstroPrint makes heavy use of partials. Partials are snippets of SCSS that are included in other CSS files. Partials allow developers to write more modular CSS that is easier to maintain. SASS partials are given file names starting with underscores, like _animations.scss. You will notice a ton of these SASS partials used in the AstroPrint source code. Partials are added to other SCSS files with the @import directive. Note that SASS treats the import directive differently than the default import directive used by standard CSS. This ties in to the last major feature of SASS, CSS preprocessing. You might be wondering how all of the above-mentioned features actually work with CSS. Well, you will not use the actual SCSS files on the AstroBox, because the software will not know how to read these files. As you makes changes to your SCSS files, SASS generates standard CSS files. It is the standard CSS files that we will eventually put on the AstroBox.

Obtain the AstroPrint Source Files

As I just mentioned, you will not find any SCSS files on the AstroBox, just standard CSS. So, we can’t do what we did with the image files and get the source files off the AstroBox, instead we need to get the actual AstroPrint source files from the AstroPrint/AstroBox GitHub page. Just download the ZIP file, and copy the \src\astroprint\static\ somewhere to work on.

Setting up SASS

You should have Ruby and the SASS Gem already installed from way up at the top of this guide. Before we start making edits to the SASS files, we are going to make SASS “watch” our SCSS directory. SASS will detect when you save changes to any of the SASS files and it will automatically rebuild the CSS file.

1. On Windows, from the start menu select Start Command Prompt with Ruby. On a Linux or Mac machine, open the terminal.
2. You want to navigate to the /static/ directory you just copied from the AstroPrint source files by using the cd <file path> command.
3. Make SASS watch the SCSS files by entering sass --watch css/scss:css/gen. Here, the first directory listed css/scss is the directory containing the SCSS files we want SASS to watch and the second directory listed css/gen is the location where we want SASS to save the generated CSS file.

Then you just need to make any edits you want to the SCSS files and you will see the command prompt/terminal window let you know that SASS is building the CSS files for each change you make.

Transfer the Generated CSS Files to the AstroBox

Once you’ve made any changes you want to the SCSS/CSS files, you can put the new CSS files onto the AstroBox. There are five different CSS files:

• app.css
• locked.css
• login.css
• setup.css
• updating.css

Depending upon which SCSS file you edit, some or all of these CSS files might be changed. Just to be safe and make sure none of your customizations get left out, just transfer all of the CSS files each time you want your changes incorporated into the AstroBox code. On the AstroBox, the CSS files live in the /AstroBox/src/astroprint/static/css/gen/ directory.