diff --git a/MSG-Style-Guide.md b/MSG-Style-Guide.md new file mode 100644 index 0000000..2098bb7 --- /dev/null +++ b/MSG-Style-Guide.md @@ -0,0 +1,122 @@ +## MSG Style Guide + +### ---- For Discussion and Comment Only --- + +Grbl has a standard for [non queried feedback](https://github.com/gnea/grbl/wiki/Grbl-v1.1-Interface#message-summary). It uses the use a [MSG: xxxx] format. Senders can do what they want with these messages, but must be able to deal with or ignore any that are in this format. + +### Grbl ESP32 + +Grbl_ESP32 uses a lot of MSGs to show the setup and at key events. It may not be of use to senders but, it is crucial for effective support. + +### Style Guide + +While anything in the [MSG:xxxxx] format should be fine, to make messages as clear and consistent as possible use this style guide. + +### Problem + +Here are the current messages in a typical startup. Note the mix of styles. + +``` +[MSG:Grbl_ESP32 Ver 1.3a Date 20201207] +[MSG:Compiled with ESP32 SDK:v3.2.3-14-gd3e562907] +[MSG:Using machine:6 Pack Controller StepStick XYZ] +[MSG:Axis count 3] +[MSG:I2S Steps, Stream] +[MSG:Init Motors] +[MSG:Using StepStick Mode] +[MSG:X Axis Standard Stepper Step:I2SO(2) Dir:I2SO(1) Disable:I2SO(0) Limits(0.000,300.000)] +[MSG:Y Axis Standard Stepper Step:I2SO(5) Dir:I2SO(4) Disable:I2SO(7) Limits(-300.000,0.000)] +[MSG:Z Axis Standard Stepper Step:I2SO(10) Dir:I2SO(9) Disable:I2SO(8) Limits(-300.000,0.000)] +[MSG:Macro Pin 0 GPIO(2)] +[MSG:Macro Pin 1 GPIO(25)] +[MSG:Macro Pin 2 GPIO(39)] +[MSG:Macro Pin 3 GPIO(36)] +[MSG:User Digital Output:0 on Pin:I2SO(24)] +[MSG:User Digital Output:1 on Pin:I2SO(25)] +[MSG:User Digital Output:2 on Pin:I2SO(26)] +[MSG:User Digital Output:3 on Pin:I2SO(27)] +[MSG:Laser spindle on Pin:GPIO(15), Enbl:GPIO(12), Freq:5000Hz, Res:13bits Laser mode:On] + +[MSG:Client Started] +[MSG:Connecting Barts-WLAN] +[MSG:Connecting.] +[MSG:Connecting..] +[MSG:Connecting...] +[MSG:Connecting....] +[MSG:Connecting.] +[MSG:Connecting..] +[MSG:Connecting...] +[MSG:Connecting....] +[MSG:Connected with 192.168.1.28] +[MSG:Start mDNS with hostname:http://grblesp.local/] +[MSG:SSDP Started] +[MSG:HTTP Started] +[MSG:TELNET Started 23] +[MSG:X Axis limit switch on pin GPIO(33)] +[MSG:Y Axis limit switch on pin GPIO(32)] +[MSG:Z Axis limit switch on pin GPIO(35)] +``` + +**Capitalization inconsistency** + +``` +[MSG:Init Motors] +[MSG:Axis count 3] +``` + +**Parameter listing method inconsistency** + +``` +[MSG:X Axis Standard Stepper Step:I2SO(2) Dir:I2SO(1) Disable:I2SO(0) Limits(0.000,300.000)] +[MSG:Macro Pin 0 GPIO(2)] +[MSG:X Axis limit switch on pin GPIO(33)] +``` + +**Punctuation Inconsistency** + +``` +[MSG:X Axis Standard Stepper Step:I2SO(2) Dir:I2SO(1) Disable:I2SO(0) Limits(0.000,300.000)] +[MSG:Laser spindle on Pin:GPIO(15), Enbl:GPIO(12), Freq:5000Hz, Res:13bits Laser mode:On] +``` + +### Initial Thoughts. + +I think the stepper MSG is one of the clearest. + +``` +[MSG:X Axis Standard Stepper Step:I2SO(2) Dir:I2SO(1) Disable:I2SO(0) Limits(0.000,300.000)] +``` + +That could change + +``` +[MSG:X Axis limit switch on pin GPIO(33)] +to +[MSG:X Limit Switch:GPIO(33)] + +[MSG:Macro Pin 0 GPIO(2)] +to +[MSG:0 Macro Pin:GPIO(2)] + +[MSG:User Digital Output:0 on Pin:I2SO(24)] +to +[MSG:0 User Digital Output:I2SO(24)] + +[MSG:Axis count 3] +to +[MSG:Axis Count:3] +``` + +That makes the capitalization format a leading uppercase character on each word. + +I/O description + +- Start with any axis (X, X2, Y, etc) or other index +- Category +- Pin Name follow by colon: +- Pin number in GPIO(xx) or I2S0(xx) format + +Ranges shall be in the (xxx, xxx) format + + +