Tutorial + New Features: Make your own buttons for the Ember web interface


#1

Want to add your own buttons to the Ember web interface? This tutorial will show you how, and it will also give you two handy new buttons.

In the Ember embedded web interface (at http://192.168.7.2 when connected by USB, or the printer’s IP if connecting over a network), there are four buttons. Each button takes you to a page that allows you to do something. For example, the Load Print File button takes you to a page where you can load a print file into the printer. This guide will show you how to add your own buttons! This requires some coding in Ruby and HTML, but it’s doable if you have a basic understanding of programming. You can also ask for help on this forum, or buy your Ruby developer friend a beer and ask them to help you.

This tutorial is extra-special because it’s an unofficial way of releasing two new features: the Edit Config button (written by Cappie) and the Test Projector button (written by me). Instead of using Terminal and PuTTY to change printer settings and do projector tests, these buttons will allow you to do it via the Ember internal web interface, which is much more convenient. Officially, the Ember team has stopped firmware development. However, we want to empower Ember users to make your own firmware modifications. It’s my hope that this tutorial will be a good place to start, and that eventually other users will contribute their own firmware modifications as well.


How to add the Edit Config and Test Projector buttons

I realize that many users may just want to add the Config and Projector buttons now, and learn how to make your own later, so here’s how to add them:

  1. Load a development image onto a MicroSD card and boot your Ember from it. Make sure to run the all the commands listed on that page (aside from just smith or smith-service). If you get disconnected after the reboot command, that’s normal – simply reconnect and continue with the next steps.

  2. Connect your computer to your Ember via USB.

  3. Download and open FileZilla

  4. Go to File > Site Manager in FileZilla, and create a new site with the following settings:

    Host: 192.168.7.2
    Protocol: SFTP - SSH File Transfer Protocol
    Logon Type: Normal
    User: root
    Password: leave blank

  5. Switch to the Advanced tab in FileZilla and paste the following under default remote directory:

    /usr/local/lib/gems/2.1.0/gems/smith-3.2.20160930.1/lib/smith/server

  6. Plug in your Ember via USB and click Connect in FileZilla. Click Yes/OK if you get any warnings.

  7. Download and unzip the set of files for the new buttons: server.zip (265.6 KB)

    You can also find the code on my fork of the Ember firmware.

  8. In FileZilla, drag the server folder into /usr/local/lib/gems/2.1.0/gems/smith-3.2.20160930.1/lib/smith and replace the existing server folder.

  9. SSH into your Ember and type systemctl restart smith-server.service

  10. Navigate to http://192.168.7.2 in your web browser and enjoy the new features!


How to make your own buttons

How the Ember web interface works

  • Inside Ember’s little brain, there are Ruby files that comprise the Ember web interface, which is called smith-server. Unlike smith, which controls the printing aspect of Ember, the web interface files don’t get compiled into an executable. Instead, they are read as a script, which means they can be easily modified.
  • These same files are contained in the source code for the Ember firmware, in the ruby directory.
  • The routes folder contains .rb files, which contain Ruby code.
  • The views folder contains .erb files (Embedded Ruby), which contain HTML with Ruby embedded into it.
  • init.rb contains a list of the functions used in the Ember web interface. Each require_relative line references a .rb file. Not all of them are tied directly to buttons, but most of them are – for example, print_file_uploads).
  • index.erb is the template that creates the Ember web interface homepage and the buttons on it. When you click a button, it activates the .rb file referenced by the <form action= tag.
  • The activated .rb file displays an .erb file, receives inputs from it, and performs whatever actions you want.
  • For example: clicking the Load Print File button in the Ember web interface activates print_file_uploads.rb, which displays new_print_file_upload.erb, which contains a form for uploading a print file. When you select a print file and click the Upload button, print_file_uploads.rb takes the data from the page and uploads it to the printer.

Hopefully this makes some amount of sense. I’m not a particularly good coder, and I had never used Ruby or Javascript until writing this tutorial, but I was able to cobble together the code to turn the projector on and off after a couple days of looking at it. Hopefully you will too! If not, ask on this forum.

How to set up Ruby for development (Mac/Linux only)

The Ember Ruby environment can only be set up on Mac and Linux, because some of the Ruby components used by Ember were only designed to run on Unix-like operating systems. If you have Windows, you can still modify the Ruby files using the “quick-n-dirty” method below, you just can’t do unit testing or use certain other fancy Ruby dev things.

  1. Download the source code from our github repository.

  2. Install all the necessary dependencies:

  • Open a Terminal window.
  • Install Bundler by typing sudo gem install bundler
  • cd to the ruby directory in the Ember firmware that you downloaded
  • Type bundle install to install all the gems required by smith-server (the Ember web interface)
  • If you get errors about eventmachine, enter sudo gem install eventmachine -v '1.0.8' -- --with-cppflags=-I/usr/local/opt/openssl/include, then enter bundle install again once it finishes.
  1. Once you’re done writing your code, you can simulate it by using the dummy server. To launch the dummy server, open Terminal, navigate to the ruby/lib/smith/server directory, and type bundle exec rackup -p 9292. Then navigate to http://localhost:9292/ to try it out! It can’t perform actual printer functions, but it’s enough to do basic debugging and get everything working. You can also run unit tests by typing bundle exec rspec from the ruby directory in a new Terminal window (the dummy server needs to be running).

Quick-n-dirty Ruby file editing procedure

If you just want to change a few simple things in the Ember web interface and don’t want to deal with setting up the Ruby environment on your computer (or you can’t because you have Windows), this procedure will allow you to edit the Ruby files directly on your Ember. This is essentially the same as the earlier procedure for installing the new buttons, but it shows you how to edit files instead of just copying them.

  1. Load a development image onto a MicroSD card and boot your Ember from it. Make sure to run the all the commands listed on that page.

  2. Connect your computer to your Ember via USB.

  3. Download FileZilla

  4. Create a new connection in FileZilla with the following settings:

    Host: 192.168.7.2
    Protocol: SFTP - SSH File Transfer Protocol
    Logon Type: Normal
    User: root
    Password: leave blank

  5. Switch to the Advanced tab in FileZilla and paste the following under default remote directory:

    /usr/local/lib/gems/2.1.0/gems/smith-3.2.20160930.1/lib/smith/server

  6. Plug in your Ember via USB and click Connect in FileZilla. Click Yes/OK if you get any warnings.

  7. Find the files in the routes and views folders (mentioned above) and edit them by selecting a file, right-clicking, and choosing View/Edit from the context menu. This will open the file for editing in your default text editor (I recommend Atom or Sublime Text, both of which handle Ruby files well).

  8. Edit your files, save them, then switch back to FileZilla. You’ll get a popup saying that a file was changed, and asking if you want to upload it back to your Ember and delete the temporary local file (click Yes).

  9. In Terminal/PuTTY, SSH into your Ember and type systemctl restart smith-server.service to restart the web server. You’ll need to do this every time you make a change.

  10. Browse to http://192.168.7.2 in a web browser to see your changes.

  11. You’ll notice that if you have any errors, all you get is “Internal Server Error”. To see debugging information, type tail -f /var/log/syslog in Terminal/PuTTY, then repeat the action that caused the error.

How to make your own buttons

Now that you’ve either set up Ruby on your computer or you know how to copy Ruby files to your Ember, here’s how to make your own buttons. You still need at least somewhat of a grasp of programming, but this should help you get started.

  1. Download or clone the Ember source code.

  2. Choose a name for your button, and decide what you’re going to name its files.

  3. Edit ruby/lib/smith/server/routes/init.rb and add a new line for the filename of your button (i.e. require_relative 'mybutton')

  4. Edit ruby/lib/smith/server/views/index.erb and paste the following code:

      <form action=‘/mybutton’>
        <button type='submit' class='btn btn-default btn-lg btn-fixed'>
          <span class='glyphicon glyphicon-pencil glyphicon-big' aria-hidden='true'></span><br>BUTTON LABEL
          </button> 
      </form>
    </div>
    

    (Change mybutton to the name of your button, and glyphicon-pencil to another icon if desired.)

  5. Make a new .rb file for your button’s code under ruby/lib/smith/server/routes (e.g. mybutton.rb), and put your code into it. Generally it’s easiest to copy and paste an existing .rb file and modify it. Here’s an example of my Test Projector page:

#  File: projector.rb
#  Sinatra routes for wireless network configuration
#
#  This file is part of the Ember Ruby Gem.
#
#  Copyright 2015 Autodesk, Inc. <http://ember.autodesk.com/>
#
#  Authors:
#  Owen Smithyman
#
#  This program is free software: you can redistribute it and/or modify
#  it under the terms of the GNU General Public License as published by
#  the Free Software Foundation, either version 3 of the License, or
#  (at your option) any later version.
#
#  THIS PROGRAM IS DISTRIBUTED IN THE HOPE THAT IT WILL BE USEFUL,
#  BUT WITHOUT ANY WARRANTY; WITHOUT EVEN THE IMPLIED WARRANTY OF
#  MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  SEE THE
#  GNU GENERAL PUBLIC LICENSE FOR MORE DETAILS.
#
#  You should have received a copy of the GNU General Public License
#  along with this program.  If not, see <http://www.gnu.org/licenses/>.

require 'bigdecimal'

module Smith
  module Server
    class Application < Sinatra::Base

      get '/projector' do
        @all_settings = Printer.settings.to_json
        erb :projector
      end

# [this section was originally used to turn the projector on and off
# before there was a box to change the value]
#
#      get '/projector/on' do
#        File.write(Settings.command_pipe, "showwhite" + "\n")
#        erb :projector
#      end

      get '/projector/testpattern' do
        File.write(Settings.command_pipe, "test" + "\n")
        redirect :projector
      end

      get '/projector/off' do
        File.write(Settings.command_pipe, "showblack" + "\n")
        redirect :projector
      end

      get '/projector/change_value' do
        @setting_to_change = params['setting']
        @change_value = params['value']
        current_settings = Printer.settings
        @new_settings = current_settings
        @new_settings[@setting_to_change] = to_numeric(@change_value)
        @new_settings = {"Settings" =>@new_settings}
        File.write(Settings.smith_settings_file, JSON.pretty_generate(@new_settings))
        #Printer.write_settings_file(@new_settings)
        File.write(Settings.command_pipe, "showblack" + "\n")
        Printer.send_command(CMD_REFRESH_SETTINGS)
        File.write(Settings.command_pipe, "showwhite" + "\n")
        #erb :change_value
        redirect :projector
      end

      def to_numeric(anything)
        num = BigDecimal.new(anything.to_s)
        if num.frac == 0
          num.to_i
        else
          num.to_f
        end
      end
    end
  end
end
To issue a command that you would normally have to do from Terminal/PuTTY, use the following line:

`File.write(Settings.command_pipe, "your command here" + "\n")`

You can see it used in the code above to turn the projector on and off and to create a test pattern.
  1. Create a new .erb file for your page under ruby/lib/smith/server/views, (e.g. mybutton.erb). Generally it’s easiest to copy and paste an existing .erb file and modify it. For example, here’s my projector.erb:
<div class="content" id="settings">
      <script>
       var all_settings = '<%= @all_settings%>';
       var obj = JSON.parse(all_settings);
       var sweetElement = document.createElement('form');
       var key = "ProjectorLEDCurrent";
       sweetElement.setAttribute('action',"/projector/change_value");
       sweetElement.setAttribute('class',"max-width center-block border");
       sweetElement.innerHTML = "<button type=\"submit\" class=\"btn btn-primary\">Projector ON</button><label>&nbsp;with ProjectorLEDCurrent:&nbsp;</label> <input type=hidden name=setting value=" + key + "> <input type=number step=0.01 name=value value=" + obj[key] + "></form>";
       document.getElementById("settings").appendChild(sweetElement);
      </script>
      <form class="max-width center-block border" action="/projector/off" method="get" enctype="multipart/form-data">
        <button type="submit" class="btn btn-primary">Projector OFF</button>
        <label>Turn the projector off</label>
      </form>
      <form class="max-width center-block border" action="/projector/testpattern" method="get" enctype="multipart/form-data">
        <button type="submit" class="btn btn-primary">Test Pattern</button>
        <label>Project a test pattern</label>
      </form>
</div>
  1. Once you’re ready to test it on your printer, load a development image onto a MicroSD card and boot your printer from it (if you haven’t already). Once it’s running, use FileZilla to transfer your new Ruby files to the appropriate directories via USB or network.

  2. Once you get it working on your Ember, you’re done! Simply keep the MicroSD card inserted in your Ember, and your changes will stay. If you remove the card, your changes will leave with it. This allows you to switch back to the original Ember settings, which is very handy if you mess something up and don’t have time to fix it). It also allows you to move your settings to a new Ember by simply inserting the card into it.

Enjoy, and please let me know if anything is missing or doesn’t make sense. If you end up writing something useful, please post it!


Access to Firmware through PrintSettings file
#2

Owen,

thank you for an awesome guide to start.

Would you be so kind to tell me where I should change a string to reverse signal from a door sensor?
I took apart Ember to achieve projector’s fixing screw to enable focus adjusting for our in-house VAT and during disassembling wires went out from the plug. Now I need to wait from 3 to 5 weeks to get right contacts for the wires. Meanwhile, I want to continue with printing tryings. It should be super-easy, but I think I will spend a few days for findings :blush:

Anyway I will go forward with firmware-worming :slight_smile:


#3

I’m not sure where in the firmware the door sensor code is, but you can just short the contacts on the main board where they come out the back of the connector. If you can be trusted to not leave the door open in bright sunlight, you can solder the contacts and never have to deal with door issues again :astonished:

Also, this guide is only for the Ember web interface (smith-server), not the print engine (smith), which handles the door sensor. Smith-server runs on Ruby, whereas smith is compiled from C++ source files. I’ll eventually make a guide for tinkering with smith, but for now, your best bet is to look through the list of source files in the C++ folder in the source code.


#4

I experienced some issues booting my Ember from the development image in my MicroSD. Once I am connected to SSH via PuTTY, I am able to run the “resize-rootfs” command. However, when I run the reboot command, I get an error saying: “Server unexpectedly closed network connection”, so I cannot boot.

Also, sometimes it takes me several tries to get the root@ember prompt - even though I always do exactly the same steps. I am not very experienced connecting to SSH. Are these issues common? How can I fix them?


#5

I think the “closed network connection” is due to the machine rebooting, so you can continue with the next steps after you reconnect. And with PuTTY it’s normal for it to sometimes take a few tries to connect. So you’re doing everything right!