# grblhub
Grblhud is an interactive grbl1.1 control center. It is easy to install and needs python version 3.7 or above.
**Grblhud** can run as a commandline program to stream gcode files directly to a grbl1.1 compatible machine. Just type 'grblhud gcodefile'.
Streaming is done via a buffer counting protocol as described by the grbl standard and is error free and fast.
**Grblhud** can run in interactive mode. Just type 'grblhud<enter>'.
This mode features full control of the grbl v1.1 device and supports <i>realtime</i> direct commands and buffered streaming of commands and programs.
Grbl state is realtime in line viewable, showing head location (XYZ) and the machine state *Idle, Run, Hold, Jog, Alarm, Door, Check, Home, Sleep* in color. State also includes current buffered (pending) gcode blocks (and no scrolling *ok's*).
Grbl v1.1 error and Alarm code definitions are shown when they occur.
Spindle and Feed settings can be updated realtime while gcode is running; gcode programs can be loaded and run with specific *Spindle* and *Feed* settings.
It is possible to easily draw a bounding box of a gcode program and set a new origin (workspace coordinates).
CNC machines can do a Z probe to easily put the bit right on top of the object (to be CNC'd).
Gcode loops are simulated (using a very simple WHILE DO syntax that must be annotated within the gcode) and can be run separately and (be) iterated at will.
Soft and hard-resets can be issued and *Ctrl-D* makes a full stop (to machine state *Door*).
This makes it easy to laser draw and cut without the need to (re)connect the device, so drawings and cuts have full (relative) machine precision.
**Grblhub** is tested on several platforms - arm64/intel - and operating systems - Linux/macosx and two grbl v1.1 devices (a lasercutter and a CNC router)
Information on grbl commands: https://github.com/gnea/grbl/blob/master/doc/markdown/commands.md
Note that *image2gcode* and *svg2gcode* can be used to convert images and vector graphics to gcode at the highest quality. *gcode2image* can be used to validate these conversions and verify the layout before using *grblhud* to send the code to your lasercutter or cnc machine. https://github.com/johannesnoordanus?tab=repositories
Also: *grblhud* now has a *showgcode* command, that runs *gcode2image* to show the currently loaded gcode (this includes the origin, size and orientation of the image). Note that *gcode2image* must be *pip* installed first (a lot of python library code is needed for this to run, which might be too much for small computers having a low network bandwidth)
Please consider supporting me, so I can make this application better and add new functionality to it: <http://paypal.me/johannesnoordanus/5,00>
### First run:
As shown below. If you do not specify a serial device, *grblhud* will open a default one and on error show a list of possible candidates you can choose one from, or type a device name you know.
It then starts a status report and run loop.
If you add file names to the command, *grblhud* will stream the files directly to the device in non interactive mode. It does show a realime status report as mentioned below.
Without file names grblhud enters interactive mode.
You can enter grbl(hud) commands from that point.
The prompt shows realtime status information of the machine you are connected to (see the explanation of the *grblhud>* prompt below).
It is possible to 'stream' a gcode file 'directly' to the machine (via command *stream <file>*) or via a buffer (via commands *load <file>* and *run*).
The buffered approach makes additional features available, like running LOOPs and bounding boxes and updating F and S values for a specific gcode run.
To exit, type *exit*.
Look at the short command summary below, so you are able the control the laser machine directly.
Note that *load* and *run* commands can take a while on large gcode files, do not panic, realtime load/run information is shown and load/run can be aborted via *anykey* or ```<Ctrl><C>```.</br>
When you do panic, because your laser machine is hitting walls etc, type ```<Ctrl><D>```, (or ```<Ctrl><C>``` first when commands *run* or *load* are executing)!
```
$ grblhud --serial /dev/ttyUSB0
Opened serial port /dev/ttyUSB0 at 115200 bauds (bits/s)
Initializing grbl...
okok
Status report every 0.1 seconds (WPos coordinates)
Start command queue
**************************************************
Enter grblhud interactive mode:
type 'help <enter>' for a command overview
type 'exit <enter>' to leave
command history: type arrow up/down
command completion: type <tab>
interrupt buffer load/run: type <Ctrl><C>
machine full stop: type <Ctrl><D>
machine halt: type '~ <enter>'
machine laser (Spindle) off: type 'M5<enter>'
Explanation of the realtime 'grbl>' prompt:
101|[Hold XYZ:00.050,51.049,00.000 FS:0,850 ] grbl> ~
99|[Run XYZ:59.268,19.031,00.000 FS:1050,0] grbl> hardreset
0|[Idle XYZ:141.840,45.351,00.000 FS:0,850] grbl> $$
^ ^ ^ ^ ^
| | | | |
| 'grbl state' 'XYZ coordinates' 'Feed/Speed rates' '(grbl) commands you type'
|
'nbr of lines in buffer' (not the machine buffer!)
**************************************************
0|[Idle XYZ:-6.513,09.283,-0.500 FS:0,0] grbl>
```
### Grblhud help:
See notes below.
```
$ grblhud --help
usage: grblhud [-h] [--serial <default:/dev/ttyUSB0>] [-V] [gcode ...]
Interactive grbl1.1 control center.
Type 'grblhud file' to stream file(s) to your machine
Type 'grblhud<enter>' to start the interactive 'hud'.
positional arguments:
gcode gcode file(s) to stream to your machine
options:
-h, --help show this help message and exit
--serial <default:/dev/ttyUSB0>
serial device of your machine (115200 baud)
-V, --version show version number and exit
```
You can also store the device setting in ~/.config/grblhud.toml, eg:
```
serial = "/dev/ttyUSB0
```
It can be used with any parameter which takes a value, and alows to persist your laser settings.
### Example runs:
**commandline**
```
$ grblhud ring10.gc ring70.gc
Opened serial port /dev/ttyUSB0 at 115200 bauds (bits/s)
Initializing grbl...
Grbl 1.1h ['$' for help]
Status report every 0.1 seconds (WPos coordinates)
Start command queue
0|[Idle XYZ:-0.700,-0.400,-1.000 FS:0,0] # stream ring10.gc
Stream send: 118 lines, - wait for device to complete!
0|[Run XYZ:139.363,45.000,-1.000 FS:1000,0] # [MSG:Pgm End]
0|[Idle XYZ:140.313,45.013,-1.000 FS:0,0] # stream ring70.gc
Stream send: 224 lines, - wait for device to complete!
0|[Run XYZ:50.688,22.500,-1.000 FS:501,0] # [MSG:Pgm End]
0|[Idle XYZ:50.000,22.500,-1.000 FS:0,0] #
Wait for program exit ....
Status report exit
End command queue
Exit program
```
**interactive**
```
grblhud --serialdevice /dev/cu.wchusbserial620
0|[Idle XYZ:-6.513,09.283,-0.500 FS:0,0] grbl> help
grblhud commands:
<Ctrl><D> / FSTOP (FULL MACHINE STOP (grbl1.1 state: 'Door'), issue softreset to continue)
- help (this help)
- exit (exit grblhud)
- OS <Unix command> (run a Unix command)
- stream <filename> (stream file 'directly' to the machine (Note that WHILE loops, F and S settings are not possible)
- load <filename> (load file to buffer)
- run [LOOP] [F<eed>] [S<pindlepeed/power>] (run file or LOOP from buffer, and possibly set F and/or S for this run)
- listgcode [<pcstart> [<pcend>]] (gcode listing, possibly set start [end] lines (for large files)
- showgcode (show image of the current gcode file (must be in the working directory))
- setLOOP <loopname> <count> <pcstart> <pcend> (set a WHILE LOOP)
- S+10, S+1, S-10, S-1 (Speed up/down 10% 1%)
- F+10, F+1, F-10, F-1 (Feed up/down 10% 1%)
- softstop (purge command buffer, but let machine buffer run till empty)
- softreset (issue soft reset command)
- hardreset (hard reset: close/open serial port)
- sleep ($SLP command)
- Zprobe (lower head until 'probe' contact is made)
- origin [X<coord>][Y<coord>][Z<coord>] (make current XYZ: [X<coord>][Y<coord>][Z<coord>] (shift work coordinates))
- Bbox [(X<min>,Y<min>:X<max>,Y<max>)] [S<peed>] [F<eed>]
(draw a bounding box of the current gcode file (no argument) or a self defind box)
- Stoggle (Spindle on/off, in 'Hold' state only)
grbl commands:
- $ (grbl help)
$$ (view Grbl settings)
$# (view # parameters)
$G (view parser state)
$I (view build info)
$N (view startup blocks)
$x=value (save Grbl setting)
$Nx=line (save startup block)
$C (check gcode mode)
$X (kill alarm lock)
$H (run homing cycle)
~ (cycle start)
! (feed hold)
? (current status)
ctrl-x/command + x/softreset (reset Grbl)
0|[Idle XYZ:-6.513,09.283,-0.500 FS:0,0] grbl>
```
### WHILE DO syntax:
Grblhud unrolls loops when files are loaded (via command *load <filename>*) and subsequently run (via command *run*)
Loops can be defined within a gcode file, as comments *;* using the syntax show below, or be defined by command *setLOOP*.
```
# Gcode:
# #100 = 1
# WHILE [#100 LE 5] DO1
# (Some G-Code Blocks Go Here to Be Repeated Each Loop)
# #100 = #100 + 1 (Increase #100 by 1 each iteration of the loop)
# END1
# Simulate gcode WHILE DO instructions (above) like this:
# ; WHILE <count> <loopname>' example: '; WHILE 23 aloop123'
# (Some G-Code Blocks Go Here to Be Repeated Each Loop)
# ; DO <loopname>' example: '; DO aloop123'
#
# Note that this is an annotation (quoted out so the grbl controller does not see it)
# Note also that loopnames are all lowercase! And have a number (if any) at the end:
# in regex '[a-z]+[0-9]*'
```
### Installation note:
```
- pip install grblhud
To install additional tools:
- pip install gcode2image
- pip install image2gcode
- pip install svg2gcode
```
Raw data
{
"_id": null,
"home_page": null,
"name": "grblhud",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "grbl, grblv1.1, hud, laser cutter, laser engraving",
"author": null,
"author_email": "Johannes Noordanus <mailjohannes.mailnoordanus@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f0/ab/275a895f354baa00f4deaf60dc87ca3de08f6972b525f1dbb0622b6e55bd/grblhud-1.7.9.tar.gz",
"platform": null,
"description": "# grblhub\nGrblhud is an interactive grbl1.1 control center. It is easy to install and needs python version 3.7 or above. \n\n**Grblhud** can run as a commandline program to stream gcode files directly to a grbl1.1 compatible machine. Just type 'grblhud gcodefile'.\n\nStreaming is done via a buffer counting protocol as described by the grbl standard and is error free and fast.\n\n**Grblhud** can run in interactive mode. Just type 'grblhud<enter>'.\n\nThis mode features full control of the grbl v1.1 device and supports <i>realtime</i> direct commands and buffered streaming of commands and programs.\n\nGrbl state is realtime in line viewable, showing head location (XYZ) and the machine state *Idle, Run, Hold, Jog, Alarm, Door, Check, Home, Sleep* in color. State also includes current buffered (pending) gcode blocks (and no scrolling *ok's*).\n\nGrbl v1.1 error and Alarm code definitions are shown when they occur.\n\nSpindle and Feed settings can be updated realtime while gcode is running; gcode programs can be loaded and run with specific *Spindle* and *Feed* settings.\n\nIt is possible to easily draw a bounding box of a gcode program and set a new origin (workspace coordinates).\n\nCNC machines can do a Z probe to easily put the bit right on top of the object (to be CNC'd).\n\nGcode loops are simulated (using a very simple WHILE DO syntax that must be annotated within the gcode) and can be run separately and (be) iterated at will.\n\nSoft and hard-resets can be issued and *Ctrl-D* makes a full stop (to machine state *Door*).\n\nThis makes it easy to laser draw and cut without the need to (re)connect the device, so drawings and cuts have full (relative) machine precision.\n\n**Grblhub** is tested on several platforms - arm64/intel - and operating systems - Linux/macosx and two grbl v1.1 devices (a lasercutter and a CNC router)\n\nInformation on grbl commands: https://github.com/gnea/grbl/blob/master/doc/markdown/commands.md\n\nNote that *image2gcode* and *svg2gcode* can be used to convert images and vector graphics to gcode at the highest quality. *gcode2image* can be used to validate these conversions and verify the layout before using *grblhud* to send the code to your lasercutter or cnc machine. https://github.com/johannesnoordanus?tab=repositories\n\nAlso: *grblhud* now has a *showgcode* command, that runs *gcode2image* to show the currently loaded gcode (this includes the origin, size and orientation of the image). Note that *gcode2image* must be *pip* installed first (a lot of python library code is needed for this to run, which might be too much for small computers having a low network bandwidth)\n\nPlease consider supporting me, so I can make this application better and add new functionality to it: <http://paypal.me/johannesnoordanus/5,00>\n### First run:\nAs shown below. If you do not specify a serial device, *grblhud* will open a default one and on error show a list of possible candidates you can choose one from, or type a device name you know.\nIt then starts a status report and run loop.\n\nIf you add file names to the command, *grblhud* will stream the files directly to the device in non interactive mode. It does show a realime status report as mentioned below.\n\nWithout file names grblhud enters interactive mode. \nYou can enter grbl(hud) commands from that point.\n\nThe prompt shows realtime status information of the machine you are connected to (see the explanation of the *grblhud>* prompt below).\n\nIt is possible to 'stream' a gcode file 'directly' to the machine (via command *stream <file>*) or via a buffer (via commands *load <file>* and *run*).\nThe buffered approach makes additional features available, like running LOOPs and bounding boxes and updating F and S values for a specific gcode run.\n\nTo exit, type *exit*.\n\nLook at the short command summary below, so you are able the control the laser machine directly.\nNote that *load* and *run* commands can take a while on large gcode files, do not panic, realtime load/run information is shown and load/run can be aborted via *anykey* or ```<Ctrl><C>```.</br>\nWhen you do panic, because your laser machine is hitting walls etc, type ```<Ctrl><D>```, (or ```<Ctrl><C>``` first when commands *run* or *load* are executing)!\n\n```\n$ grblhud --serial /dev/ttyUSB0\nOpened serial port /dev/ttyUSB0 at 115200 bauds (bits/s)\nInitializing grbl...\nokok\nStatus report every 0.1 seconds (WPos coordinates)\nStart command queue\n\n**************************************************\nEnter grblhud interactive mode:\n type 'help <enter>' for a command overview\n type 'exit <enter>' to leave\n command history: type arrow up/down\n command completion: type <tab>\n interrupt buffer load/run: type <Ctrl><C>\n machine full stop: type <Ctrl><D>\n machine halt: type '~ <enter>'\n machine laser (Spindle) off: type 'M5<enter>'\n\nExplanation of the realtime 'grbl>' prompt:\n 101|[Hold XYZ:00.050,51.049,00.000 FS:0,850 ] grbl> ~\n 99|[Run XYZ:59.268,19.031,00.000 FS:1050,0] grbl> hardreset\n 0|[Idle XYZ:141.840,45.351,00.000 FS:0,850] grbl> $$\n ^ ^ ^ ^ ^\n | | | | |\n | 'grbl state' 'XYZ coordinates' 'Feed/Speed rates' '(grbl) commands you type'\n | \n'nbr of lines in buffer' (not the machine buffer!)\n\n**************************************************\n\n0|[Idle XYZ:-6.513,09.283,-0.500 FS:0,0] grbl> \n```\n### Grblhud help:\nSee notes below.\n```\n$ grblhud --help\nusage: grblhud [-h] [--serial <default:/dev/ttyUSB0>] [-V] [gcode ...]\n\nInteractive grbl1.1 control center.\n Type 'grblhud file' to stream file(s) to your machine\n Type 'grblhud<enter>' to start the interactive 'hud'.\n\npositional arguments:\n gcode gcode file(s) to stream to your machine\n\noptions:\n -h, --help show this help message and exit\n --serial <default:/dev/ttyUSB0>\n serial device of your machine (115200 baud)\n -V, --version show version number and exit\n```\nYou can also store the device setting in ~/.config/grblhud.toml, eg:\n```\nserial = \"/dev/ttyUSB0\n```\nIt can be used with any parameter which takes a value, and alows to persist your laser settings.\n\n### Example runs:\n**commandline**\n```\n$ grblhud ring10.gc ring70.gc\nOpened serial port /dev/ttyUSB0 at 115200 bauds (bits/s)\nInitializing grbl...\nGrbl 1.1h ['$' for help]\nStatus report every 0.1 seconds (WPos coordinates)\nStart command queue\n0|[Idle XYZ:-0.700,-0.400,-1.000 FS:0,0] # stream ring10.gc\nStream send: 118 lines, - wait for device to complete!\n0|[Run XYZ:139.363,45.000,-1.000 FS:1000,0] # [MSG:Pgm End]\n0|[Idle XYZ:140.313,45.013,-1.000 FS:0,0] # stream ring70.gc\nStream send: 224 lines, - wait for device to complete!\n0|[Run XYZ:50.688,22.500,-1.000 FS:501,0] # [MSG:Pgm End]\n0|[Idle XYZ:50.000,22.500,-1.000 FS:0,0] # \nWait for program exit ....\nStatus report exit\nEnd command queue\nExit program\n```\n**interactive**\n```\ngrblhud --serialdevice /dev/cu.wchusbserial620\n0|[Idle XYZ:-6.513,09.283,-0.500 FS:0,0] grbl> help\ngrblhud commands:\n <Ctrl><D> / FSTOP (FULL MACHINE STOP (grbl1.1 state: 'Door'), issue softreset to continue)\n\n - help (this help)\n - exit (exit grblhud)\n - OS <Unix command> (run a Unix command)\n - stream <filename> (stream file 'directly' to the machine (Note that WHILE loops, F and S settings are not possible)\n - load <filename> (load file to buffer)\n - run [LOOP] [F<eed>] [S<pindlepeed/power>] (run file or LOOP from buffer, and possibly set F and/or S for this run)\n - listgcode [<pcstart> [<pcend>]] (gcode listing, possibly set start [end] lines (for large files)\n - showgcode (show image of the current gcode file (must be in the working directory))\n - setLOOP <loopname> <count> <pcstart> <pcend> (set a WHILE LOOP)\n - S+10, S+1, S-10, S-1 (Speed up/down 10% 1%)\n - F+10, F+1, F-10, F-1 (Feed up/down 10% 1%)\n - softstop (purge command buffer, but let machine buffer run till empty)\n - softreset (issue soft reset command)\n - hardreset (hard reset: close/open serial port)\n - sleep ($SLP command)\n - Zprobe (lower head until 'probe' contact is made)\n - origin [X<coord>][Y<coord>][Z<coord>] (make current XYZ: [X<coord>][Y<coord>][Z<coord>] (shift work coordinates))\n - Bbox [(X<min>,Y<min>:X<max>,Y<max>)] [S<peed>] [F<eed>]\n (draw a bounding box of the current gcode file (no argument) or a self defind box)\n - Stoggle (Spindle on/off, in 'Hold' state only)\n\ngrbl commands:\n - $ (grbl help)\n $$ (view Grbl settings)\n $# (view # parameters)\n $G (view parser state)\n $I (view build info)\n $N (view startup blocks)\n $x=value (save Grbl setting)\n $Nx=line (save startup block)\n $C (check gcode mode)\n $X (kill alarm lock)\n $H (run homing cycle)\n ~ (cycle start)\n ! (feed hold)\n ? (current status)\n ctrl-x/command + x/softreset (reset Grbl)\n\n0|[Idle XYZ:-6.513,09.283,-0.500 FS:0,0] grbl> \n\n```\n### WHILE DO syntax:\nGrblhud unrolls loops when files are loaded (via command *load <filename>*) and subsequently run (via command *run*)\nLoops can be defined within a gcode file, as comments *;* using the syntax show below, or be defined by command *setLOOP*.\n```\n # Gcode:\n # #100 = 1\n # WHILE [#100 LE 5] DO1\n # (Some G-Code Blocks Go Here to Be Repeated Each Loop)\n # #100 = #100 + 1 (Increase #100 by 1 each iteration of the loop)\n # END1\n \n # Simulate gcode WHILE DO instructions (above) like this:\n # ; WHILE <count> <loopname>' example: '; WHILE 23 aloop123'\n # (Some G-Code Blocks Go Here to Be Repeated Each Loop)\n # ; DO <loopname>' example: '; DO aloop123'\n #\n # Note that this is an annotation (quoted out so the grbl controller does not see it)\n # Note also that loopnames are all lowercase! And have a number (if any) at the end:\n # in regex '[a-z]+[0-9]*'\n```\n### Installation note:\n``` \n\t- pip install grblhud \n\n\tTo install additional tools:\n\t- pip install gcode2image\n\t- pip install image2gcode\n\t- pip install svg2gcode\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "grblhub: a command line tool to handle grbl code.",
"version": "1.7.9",
"project_urls": {
"Home": "https://github.com/johannesnoordanus/grblhud"
},
"split_keywords": [
"grbl",
" grblv1.1",
" hud",
" laser cutter",
" laser engraving"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "24349f2cfc4ea0fe5f456745491f77af8eb00ff0f80643c2771245d14860a572",
"md5": "20b2455ca746dfdfb1e0c6d159c31d0d",
"sha256": "6beef6b27646dc1a96b4c939682aa010cd6083c7d711aca002706a6150426521"
},
"downloads": -1,
"filename": "grblhud-1.7.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "20b2455ca746dfdfb1e0c6d159c31d0d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 36106,
"upload_time": "2024-07-01T13:41:04",
"upload_time_iso_8601": "2024-07-01T13:41:04.407621Z",
"url": "https://files.pythonhosted.org/packages/24/34/9f2cfc4ea0fe5f456745491f77af8eb00ff0f80643c2771245d14860a572/grblhud-1.7.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f0ab275a895f354baa00f4deaf60dc87ca3de08f6972b525f1dbb0622b6e55bd",
"md5": "e7f1b8f38af91ad20e9c9f9380535135",
"sha256": "7c203e1562cc5f6b40293df630d3caf8aca4fcd29f530f672353ccc06923b316"
},
"downloads": -1,
"filename": "grblhud-1.7.9.tar.gz",
"has_sig": false,
"md5_digest": "e7f1b8f38af91ad20e9c9f9380535135",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 32283,
"upload_time": "2024-07-01T13:41:07",
"upload_time_iso_8601": "2024-07-01T13:41:07.104914Z",
"url": "https://files.pythonhosted.org/packages/f0/ab/275a895f354baa00f4deaf60dc87ca3de08f6972b525f1dbb0622b6e55bd/grblhud-1.7.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-01 13:41:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "johannesnoordanus",
"github_project": "grblhud",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "grblhud"
}
JSON
