This software is intended to be used with a KKMoon laser engraver (3000mW). It comes with ABSOLUTELY NO WARRANTY. It may or may not work with an other kind of laser engraver.
The program is written in python (V3) and uses the python packages 'pyserial' and 'Pillow' (former PIL). So you have get them installed first.
This software comes in two parts:
engraver.py is a command line tool without any GUI. But it has (nearly) every
feature the Windows software that came with the engraver has.
gui.py is a graphical user interface implemented as a web frontend. It runs
in a browser tab/window.
You can get a short help by just typing: python3 engraver.py -h or ./engraver.py -h
if you have made it executable.
usage: engraver.py [-h] [-d device] [-s speed] [-v] [--fan] [--no-fan]
[-m x:y] [-f x:y] [-F imagefile] [-c x|y] [-H] [-C]
[-D depth] [-P power] [--checkerboard tile_size number]
[-i imagefile] [--contrast number] [--brightness number]
[-t text] [--font font]
[-T cw|ccw|turn|tb|lr [cw|ccw|turn|tb|lr ...]] [-S w:h]
[--invert] [--limit steps] [--dry-run [imagefile]]
Engraver program for using a KKMoon laser engraver V0.9.7 (c) 2019 by Bernd
Breitenbach This program comes with ABSOLUTELY NO WARRANTY. This is free
software, and you are welcome to redistribute it under certain conditions; See
COPYING for details.
optional arguments:
-h, --help show this help message and exit
-d device, --device device
the serial device (default: /dev/ttyUSB0)
-s speed, --speed speed
the speed of the serial device (default: 115200)
-v, --verbosity increase verbosity level (default: 0)
--fan switch fan on (default: None)
--no-fan switch fan off (default: None)
-m x:y move the laser x/y steps (default: None)
-f x:y draw a moving frame (default: None)
-F imagefile, --image-frame imagefile
draw a moving frame as large as the given image
(default: None)
-c x|y, --center-only x|y
draw a center line only (x or y) with the other
dimension taken from an image. Has an effect only when
used with the -F option (default: None)
-H, --home move the laser to pos 0/0 (default: False)
-C, --center-reference
use the current laser postion as reference point for
the center of the image or text to engrave; usually it
will be the top-left of the image (default: False)
-D depth, --depth depth
set the burn depth of the laser (0-100) (default: 10)
-P power, --power power
set the laser power (0-100) (default: 100)
--checkerboard tile_size number
engrave a quadratic checkerboard pattern of given tile
size and number (default: None)
-i imagefile, --image imagefile
the image file to engrave (default: None)
--contrast number adjust the contrast of the image (-10..10) (default:
None)
--brightness number adjust the brightness of the image (-10..10) (default:
None)
-t text, --text text the text to engrave; you also have to specify a font
with the --font option (default: None)
--font font the truetype/opentype font used to engrave text
(default: None)
-T cw|ccw|turn|tb|lr [cw|ccw|turn|tb|lr ...], --transform cw|ccw|turn|tb|lr [cw|ccw|turn|tb|lr ...]
transform the image after any other operation just
before engraving. The following transformations are
possible: cw - rotate 90 degrees clockwise; ccw -
rotate 90 degrees counterclockwise; turn - rotate 180
degrees ; tb - flip top-bottom ; lr - flip left-right
(default: None)
-S w:h, --maxsize w:h
scale the image down to match maximal width and
height; the aspect ratio is kept (default: None)
--invert invert the image/text before engraving (default:
False)
--limit steps set maximum no. of steps in x/y direction (default:
1575)
--dry-run [imagefile]
do not engrave anything; you can specify an optional
file for saving engraving data (default: None)
All distances and sizes can be specified in steps or millimeter by just adding
mm to a given number. The KKMoon engraver has a resolution of 500 steps/inch
(19.685.. steps/mm)
Before sending any commands to the KKMoon engraver you have to power it up and connect it to the computer. Depending on your OS you may have to install a driver for the serial device.
Under Linux you can check whether the device is recognized by looking at the output of dmesg.
You should see something like this:
[1172392.928109] usb 3-5: new full-speed USB device number 16 using xhci_hcd
[1172393.057149] usb 3-5: New USB device found, idVendor=1a86, idProduct=7523
[1172393.057152] usb 3-5: New USB device strings: Mfr=0, Product=2, SerialNumber=0
[1172393.057154] usb 3-5: Product: USB2.0-Serial
[1172393.057681] ch341 3-5:1.0: ch341-uart converter detected
[1172393.061184] usb 3-5: ch341-uart converter now attached to ttyUSB0
The last line shows the here the name of our device: ttyUSB0.
This device has to be specified with the -d option. The KKMoon normally
works with 115200 baud so you don't have the specify the speed.
To check whether the engraver gets detected just enter (if using a Windows OS you may have to replace /dev/ttyUSB0
with your port name e.g. COM3):
./engraver.py -d /dev/ttyUSB0 -v
The -v increases the verbosity and you should see something like this:
[DEBUG]: opening device /dev/ttyUSB0
[DEBUG]: connecting...
[DEBUG]: sending:[10, 0, 4, 0, 255, 0, 4, 0]
[DEBUG]: got acknowledge
[DEBUG]: ...connected
This indicates that the engraver is regcognized and you can try some other commands. If you get an error message like this:
[DEBUG]: opening device /dev/ttyUSB0
[FATAL]: [Errno 2] could not open port /dev/ttyUSB0: [Errno 2] No such file or directory: '/dev/ttyUSB0'
then the serial device ist not present (perhaps a connection problem). If you got something like this (after a timeout):
[DEBUG]: opening device /dev/ttyUSB0
[DEBUG]: connecting...
[DEBUG]: sending:[10, 0, 4, 0, 255, 0, 4, 0]
[FATAL]: didn't got acknowledge; got:b''
then the serial device is present, but the KKMoon engraver could not be detected. Perhaps due to another model or other firmware.
If the above things worked fine. We can now try some commands.
The case fan of the KKMoon can be switched on/off with the --fan/--no-fan option.
If not given the state of the fan will remain unchanged.
The cooling fan on the laser head is always on and can not be switched off with this option.
By entering ./engraver.py -v -m 10:10 -d /dev/ttyUSB0 the laser will move by a small amount.
You see this output:
[DEBUG]: opening device /dev/ttyUSB0
[DEBUG]: connecting...
[DEBUG]: sending:[10, 0, 4, 0, 255, 0, 4, 0]
[DEBUG]: got acknowledge
[DEBUG]: ...connected
[DEBUG]: start moving delta_x=10px (0.5mm) delta_y=10px (0.5mm)
[DEBUG]: sending:[1, 0, 7, 0, 10, 0, 10]
[DEBUG]: got acknowledge
[DEBUG]: move finished
laser moved x:10px (0.5mm) delta_y=10px (0.5mm)
It shows that the laser got moved roughly 0.5 millimeters in x and y direction.
You can revert this movement by entering: ./engraver.py -v -m -10:-10 -d /dev/ttyUSB0
(Due to a bug in an old version of the python argsparse package it can happen, that
the negative values aren't regcognized correctly. You can get around this bug by
modifying the command slightly: ./engraver.py -v -m ' -10:-10' -d /dev/ttyUSB0)
You also can specify the distance in millimeters instead of pixels/steps by adding
mm to the value.
The command ./engraver.py -v -m 7.5mm:3.5mm -d /dev/ttyUSB0 will move the laser
7.5 millimeters in x and 3.5mm in y direction.
You can also leave out the value for x- or y-direction:
./engraver.py -v -m :7mm -d /dev/ttyUSB0 will only move the laser 7mm in y-direction
and ./engraver.py -v -m ' -4mm' -d /dev/ttyUSB0 will only move the laser -4mm in x-direction
With the two parameters depth (-D) and power (-P) you can adjust the final look of the engraving. When increasing the depth parameter the laser moves more slowly and stays longer at the same point. This results in removing more material and a deeper engraving. Lowering the power results in a weaker laser beam. I assume the laser is controlled through PWM and so the on-time during a cycle is probably decreased.
You can move the laser to the home position (0,0) with the -H option. But be careful
the KKMoon has no endswitches and the firmware will drive both stepper motors the full distance
(89mm) towards the origin. So they eventually will hit the case.
As the original software does you can also show a moving frame to align the workpiece
before doing the engraving.
Enter ./engraver.py -v -f 25mm:10mm -d /dev/ttyUSB0 and you see the laser repetitive
drawing a frame until you hit the return key.
You can also use your image file you want to engrave to show a frame. Just enter
./engraver.py -F <yourimage> -d /dev/ttyUSB0 and you will an output like this
showing frame x:283px (14.4mm) y:309px (15.7mm)
press return to finish
After pressing the return key. The laser will complete the current frame until it reaches the origin of the frame. As an image format you can use all formats the Pillow (PIL) package support (e.g. jpg/png/gif).
It is also possible to restrict the frame to the x- or y-axis by using the -c option:
./engraver.py -c x -F <yourimage> -d /dev/ttyUSB0
will show a line in x direction in the middle of the y size of the image.
The program contains a function to engrave a checkerboard pattern as a test. For example
if you enter: ./engraver.py --checkerboard 4mm 4 -d /dev/ttyUSB0 it will engrave a checkboard
pattern 4 by 4 with a tile size of 4mm. It will take a while and you see some output:
waiting for engraver
sending data (312 rows) ...
100% done
engraving...
completed!
It will engrave the pattern with the default values for engravement depth (10) and laser power (100). Both values can be changed between 0 and 100.
Instead of the test pattern you can specify your image file:
./engraver.py -i <yourimage> -D 15 -d /dev/ttyUSB0
or with a given maximum size by keeping the aspect ratio:
./engraver.py -i <yourimage> -S 5mm:5mm -D 15 -d /dev/ttyUSB0
You see an output like this:
image resized to width:89px (4.5mm) height:98px (5.0mm)
preparing image data width:89px (4.5mm) height:98px (5.0mm)
waiting for engraver
sending data (98 rows) ...
100% done
engraving...
completed!
Note: you only can shrink your image you cannot enlarge it with this option.
With the -t and the --font options you can engrave a text with a given font. Here the -S option
is very useful for setting the maximum height or width of the engraving.
With the --font you have to specify a TrueType or OpenType font file.
The command ./engraver.py -t "Hello!" --font fonts/arial.ttf -S 25mm:10mm -d /dev/ttyUSB0
engraves the word 'Hello' using the font arial.ttf in the subdirectory fonts and
with the maximal dimensions of 25mm in x direction and 10mm in y direction.
I do not provide any fonts with this program. You can find a lot by searching the internet for 'open source fonts' or using one of those already installed on your OS.
With the -T option you can rotate and/or mirror your image or text before engraving after any other operation.
You can specify multiple transformation after the option e.g:
./engraver.py -t "Hello!" --font fonts/arial.ttf -T cw tb -S 25mm:10mm -D 15 -d /dev/ttyUSB0
first rotates the text clockwise and afterwards mirrors it about the y axis (flips top-bottom).
Note: the scaling with -S happens before tranforming. So in the above example 25mm is the maximal length of
the text image and 10mm its maximal height.
You can specify contrast and brightness adjustments for an image between -10 and 10. Positive values increase contrast/brightness. Negative values decreases them.
Note: these values only makes sense if the original image is of a multicolor or grayscale type. If you use a black/white image they are useless.
Finally the image always gets converted to a black/white image by dithering, because the engraver can not handle grayscale values.
With the --dry-run option you can test options without sending any commands to the device. It does not even has
to be connected to the computer.
If a file name is specified with this option and an image or text should be engraved the final image will be saved to that file.
If something go wrong during engraving, hit the interrupt key (Ctrl-c) and the engraving
will pause. You can abort the process now by hitting the return key or continue it by
entering n followed by a return.
The graphical user interface can be started by entering ./gui.py. You can get a help by adding -h:
usage: gui.py [-h] [-d device] [-s speed] [-v] [--limit steps] [-b browser]
[-B bind] [-P port]
Engraver program for using a KKMoon laser engraver V0.9.7 (c) 2019 by Bernd
Breitenbach This program comes with ABSOLUTELY NO WARRANTY. This is free
software, and you are welcome to redistribute it under certain conditions; See
COPYING for details.
optional arguments:
-h, --help show this help message and exit
-d device, --device device
the serial device (default: /dev/ttyUSB0)
-s speed, --speed speed
the speed of the serial device (default: 115200)
-v, --verbosity increase verbosity level (default: 0)
--limit steps set maximum no. of steps in x/y direction (default:
1575)
-b browser, --browser browser
use browser to open gui, set to - to not open the gui
(default: )
-B bind, --bind bind use the given address to bind to; use 0.0.0.0 for all
interfaces (default: 127.0.0.1)
-P port, --port port use the given port (default: 8008)
The GUI has fewer options. You can specify most parameters in the GUI itself.
The first options are identical to the corresponding ones of engraver.py. The last three
are for specifying the browser, the address and the port for the web server.
If the -b option is ommited the gui is opened in the users default browser.
You can specify other browsers by their name. The gui was tested with firefox and chromium-browser.
By using - behind the browser option the gui is not opened automatically.
By default the web server for the gui is only bound to 127.0.0.1 (localhost) so it can only
used from the same computer. If you bind it to 0.0.0.0 any computer in the same network can
control the gui of the engraver. The default port is 8008. You can change it with the -P option.
After starting gui.py your default browser should show a new window/tab with the GUI.
Here you can see the screen opened with the chromium browser.
In the top section you can see many buttons to control the engraver:
A. You can connect/disconnect to the engraver. If not connected most of the buttons are disabled.
B. Here you can switch on/off the engraverfan
C. Move the laser to the home position
D. Move the laser in the given direction
E. The length the laser is moved by the direction buttons [D] (0.1-10mm)
F. Show a preview line of the horizontal engraving dimension
G. Show a preview line of the vertical engraving dimension
H. Show a preview frame of the engraving dimensions
I. Specify the laser power (1-100)
J. Specify the engraving depth (1-100)
K. Start the engraving. If pressed, most buttons are disabled until the engraving process is finished or canceled.
A. Switch between image and text mode
B. Toggle the reference point for engraving between top-left (default) and center. If center is selected the image will be engraved symmetrically around the center point.
C. Rotate the image counter-clockwise respectivly clockwise
D. Flip the image horizontally respectivly vertically
E. Here you can specify the maximum width respectivly height of the image. The aspect ratio of the image is always kept. So mostly only one of the values restrict the size of the image. Note: you cannot enlarge an image beyond its give size by entering large values. Normally you enter the size in pixel value but you can type 'mm' after the number and the it is taken as a mm-value and converted to the correct pixel value.
F. Enter a contrast value (-10..10) 0 means no change.
G. Enter a brightness value (-10..10) 0 means no change.
Note: only color or grayscale images are affected by contrast/brightness settings
H. Upload an image to engrave
A. Enter your text to engrave
B. Select a font from the ones residing in the fonts directory.
You can copy any truetype font into this directory.
Currently this software is tested and works with a KKMoon 3000 (3 Watts power). It may or may not work with other models from KKMoon.