Guide: How To Use zee, Ember's Built-in Motor Control Interface


Ember has two motors. One controls the Z-axis linear drive, and the other controls the build plate rotation. From firmware version 2.0+, Ember comes with an internal low-level motor controller interface called zee that allows the user to control one or both motors. This is helpful for users who want to modify their machine to operate in new ways.

Starting zee:

  1. Connect to your printer via SSH
  2. Once connected, type zee

General Low-Level Commands:
NOTE: Zee’s commands are case-sensitive, and the “-” following the commands are not part of the code.

T - Reset motor controller (wait at least 0.1 s after a reset before sending any other commands)

C - Clear all pending commands

P - Pause the command in progress

U - When paused, resume all pending commands

W - Wait for an interrupt after all pending commands have completed. Note: any action commands (and subsequent settings commands) will only be queued and not executed until an interrupt request is sent. More commands should then not be sent until that interrupt is received, i.e. all queued movements have completed. If it’s necessary to send a command (e.g. P, pause) while a movement is in progress, there’s the possibility of an I2C write error, in which case the command would need to be resent.

E - Enable both motors

D - Disable both motors

High-level commands that use the current settings defined in /var/smith/config/settings:

I - Initialize the controller with all necessary parameters and enable both axes

H - Go home (both Z & rotation axes, followed by RHomingAngleMilliDegrees rotation) & await interrupt

G - Go to print start/calibration position & await interrupt

F - First layer separation & await interrupt

B - Burn-in layer separation & await interrupt

M - Model layer separation & await interrupt

f - First layer approach & await interrupt

b - burn-in layer approach & await interrupt

m - model layer approach & await interrupt

S - reload/refresh settings from settings file In the following commands, all values are integers, optionally signed.

Axis Parameter Commands:

z<parameter><value> - Set Z-axis parameter to given value

r<parameter><value> - Set rotation axis parameter to given value possible parameters:

n<value> - Step angle in millidegrees per step

u<value> - Number of units of travel (microns or millidegrees) for each motor revolution

t<value> - Microstepping mode, 1 = full step, 2 = half step, ..., 6 = 1/32 step

s<value> - Target speed for following moves (microns/s or RPM)

j<value> - Maximum jerk for following moves, defines the acceleration profile, units are deci-degrees/minute^3 (x1E6) for rotation and m/minute^3 for Z-axis

Axis Action commands:

Z<action> - Perform Z-axis action with given value

R<action> - Perform rotation axis action with given value posible actions:

V<value> - Move given number of units (positive values are upward or clockwise)

L<value> - Move to limit switch (or given number of units if limit switch isn't tripped first)


If you wanted to initialize and home the system using the current settings, you could just issue these two high-level commands:

But you could also do the same thing by issuing the following low-level commands (don’t enter the // comments):

T                 // reset  
                  // wait 0.1 s to avoid erasing the following commands as part of the reset
zn1800            // set Z step angle to 1.8 degrees
zu2000            // set Z units to 2 mm/rotation 
zt4               // set Z microsteps to 1/8 
rn1800            // set rotation step angle to 1.8 degrees 
ru180000          // set rotation units to 180 degrees/rotation (2:1 gear ratio) 
rt4               // set rotation microsteps to 1/8 
E                 // enable motors 
                  // the above commands do the same thing as 'I' (with the default settings), and the ones below do the same thing as 'H' 
rj3000000         // set max jerk for rotation 
rs20              // set target rotation speed to 20 RPM 
RL360000          // rotate to limit switch, but no more than 360 degrees 
RV-60000          // rotate 60 degrees CCW 
zj1000000         // set max jerk for Z movement 
zs4000            // set target Z speed to 4mm/s 
ZL330000          // move up to limit switch, but no more than 330mm 
W                 // request and await an interrupt when all the above commands are completed

Alternatively you can issue zee commands directly from the shell:

    zee I H                         // initialize and home the motors

    zee I rj300000 rs12 RV60000 W   // rotate the build tray 60 degrees clockwise at 12 RPM

    zee I zj100000 zs2000 ZV200 W   // move the build head up 200 microns at 2mm/sec