{"action":"created","issue":{"url":"https://api.github.com/repos/evil-mad/EggBot/issues/54","repository_url":"https://api.github.com/repos/evil-mad/EggBot","labels_url":"https://api.github.com/repos/evil-mad/EggBot/issues/54/labels{/name}","comments_url":"https://api.github.com/repos/evil-mad/EggBot/issues/54/comments","events_url":"https://api.github.com/repos/evil-mad/EggBot/issues/54/events","html_url":"https://github.com/evil-mad/EggBot/issues/54","id":170321907,"number":54,"title":"Clarify EBB command description syntax","user":{"login":"oskay","id":1009180,"avatar_url":"https://avatars.githubusercontent.com/u/1009180?v=3","gravatar_id":"","url":"https://api.github.com/users/oskay","html_url":"https://github.com/oskay","followers_url":"https://api.github.com/users/oskay/followers","following_url":"https://api.github.com/users/oskay/following{/other_user}","gists_url":"https://api.github.com/users/oskay/gists{/gist_id}","starred_url":"https://api.github.com/users/oskay/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/oskay/subscriptions","organizations_url":"https://api.github.com/users/oskay/orgs","repos_url":"https://api.github.com/users/oskay/repos","events_url":"https://api.github.com/users/oskay/events{/privacy}","received_events_url":"https://api.github.com/users/oskay/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/evil-mad/EggBot/labels/EBB","name":"EBB","color":"bfd4f2"},{"url":"https://api.github.com/repos/evil-mad/EggBot/labels/enhancement","name":"enhancement","color":"84b6eb"}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":2,"created_at":"2016-08-10T03:49:00Z","updated_at":"2016-08-10T04:06:18Z","closed_at":null,"body":"Following up on #51, I would like to request an update to the descriptions of individual commands on [the EBB commands page](http://www.schmalzhaus.com/EBB/EBBCommands.html). \r\n\r\nFor reasons of clarity and usability, it would be nice to standardize the command (and query) description with slightly more rigid syntax.  While there isn't any one given standard for this kind of thing – Many different \"standards\" are used – there are certain norms and conventions that are common and that can be very clear when an explicit legend is given.\r\n\r\nI would like to recommend that the following syntax legend (details of which are certainly up for debate!) prepend the command set, and that the commands be updated to follow this syntax.\r\n\r\n\r\n------\r\n\r\nEBB Syntax Conventions\r\n* Command format descriptions and examples are set in `code font`.\r\n* Query response format descriptions and examples are also set in `code font`.\r\n* _Italics_ are used to represent variables and adjustable parameters.\r\n* Square brackets (`[ ]`) are used to enclose optional items.\r\n* Angle brackets (`< >`) are used to represent individual control characters, such as `<CR>` for carriage return.\r\n* All unitalicized text and punctuation within a command description must be used literally.\r\n\r\nAdditionally, please note that:\r\n* All commands are composed of ASCII characters\r\n* All commands are case insensitive.\r\n* Whitespace within a command will be ignored.\r\n* All commands must have a total length of 64 characters or fewer, including the terminating `<CR>` .\r\n\r\n------\r\n\r\nTo give an example, here is what the current description of the \"SE\" command looks like:\r\n\r\n* **Format**: \"SE,&lt;state&gt;,&lt;power>&lt;CR&gt;\" (pre v2.4.1)\r\n* **Format**: \"SE,&lt;state&gt;,&lt;power&gt;,&lt;use_motion_queue&gt;&lt;CR&gt;\" (v2.4.1 and on)\r\n* **Example**: \"SE,1,1023\"\r\n* &lt;state&gt; is 0 for disable, and 1 for enable. You must include this parameter.\r\n* &lt;power&gt; is a value from 0 to 1023 and represents the relative power (% duty cycle of the PWM signal), where 0 is off and 1023 is full on. This parameter is optional.\r\n* &lt;use_motion_queue&gt; is optional, and can be a 0 or a 1. If 1, then this SE command will be put on the motion queue just like SM and SP commands, thus it will be executed when the previous motion commands have finished. Note that if you need to use this parameter, the &lt;power&gt; parameter is not optional. (You must have 3 parameters if you use this parameter.)\r\n* This command is used to enable and disable the engraver PWM output on RB3 (called B3 on the board), and also set its output power. Use SE,0 to disable this feature.\r\n* If &lt;power&gt; is not included, 50% PWM will be used.\r\n* Returns: \"OK&lt;CR&gt;\"\r\n* Version Notes: Firmware versions prior to v2.2.2 do not have working PWM from this command. Instead, they always defaulted to 50% PWM. Version 2.2.2 fixes this problem.\r\n\r\n\r\nNow, here is what that same description would look like with the new syntax (and a few edits):\r\n\r\n* **Format**: <code>SE, <i>state</i> [, <i>power</i>]&lt;CR&gt;</code>  (Firmware < v2.4.1)\r\n* **Format**: <code>SE, <i>state</i> [, <i>power</i> [,  <i>queue</i>   ] ]&lt;CR&gt;</code>  (Firmware &ge; v2.4.1)\r\n* **Example**: <code>SE,1,1023&lt;CR&gt;</code>\r\n* <i>state</i> is a required parameter, with allowed values 0 for disable, and 1 for enable. \r\n* <i>power</i> is an optional parameter, with allowed values 0 through 1023. It represents the relative power (% duty cycle of the PWM signal), where 0 is off and 1023 is full on. If <i>power</i> is not specified, the default value of 50% PWM will be used.\r\n* <i>queue</i> is an optional parameter, with allowed values 0 or 1. If the value is 1, then this SE command will be put on the motion queue just like SM and SP commands, thus it will be executed when the previous motion commands have finished. If the value is 0, it will be executed immediately instead. Note that the power parameter must be specified if you choose to include this parameter.\r\n* **Returns**: <code>OK&lt;CR&gt;</code>\r\n* Version Notes: Firmware versions prior to v2.2.2 do not have a working PWM argument from this command, and always use 50% PWM. Firmware v2.4.1 adds the <i>queue</i> parameter.\r\n\r\n----\r\n\r\n\r\nA couple of notes on the example above:\r\n* I've added the `<CR>` in the example.\r\n* This set of changes makes it explicitly clear which items are parameters (for example, &lt;state&gt; is, but &lt;CR&gt; is not)\r\n* This set of changes makes it explicitly clear which items are optional and which are not-- for example, the comma before <i>power</i> is required, if power is used, and that <i>queue</i> may be used only if <i>power</i> is. With the previous syntax, it is ambiguous as to whether the additional commas are optional or required.\r\n\r\nA couple of additional thoughts in general:\r\n* It might be nice to have some convention or explicit means of marking the the expected parameter values a little more clearly. One might consider the following means of doing that:\r\n * Adding to the command: <code>SE, <b>BOOLEAN</b> <i>state</i> [, <b>INTEGER</b> <i>power</i> [,  <b>BOOLEAN</b> <i>queue</i>   ] ]&lt;CR&gt;</code>  \r\n * Adding to the parameter as: \"<i>state</i>: Boolean, required. Values: 0 for disable, and 1 for enable.\" \r\n * Adding to the parameter, as \"Boolean <i>state</i>: required parameter. Values: 0 for disable, and 1 for enable.\"\r\n * Using a convention where all boolean parameters are capitalized (\"<i>STATE</i>\").\r\n* This is a mouthful; I'm open to discussing the types of formatting used, as well as helping out with the editing.\r\n"},"comment":{"url":"https://api.github.com/repos/evil-mad/EggBot/issues/comments/238760721","html_url":"https://github.com/evil-mad/EggBot/issues/54#issuecomment-238760721","issue_url":"https://api.github.com/repos/evil-mad/EggBot/issues/54","id":238760721,"user":{"login":"EmbeddedMan","id":450056,"avatar_url":"https://avatars.githubusercontent.com/u/450056?v=3","gravatar_id":"","url":"https://api.github.com/users/EmbeddedMan","html_url":"https://github.com/EmbeddedMan","followers_url":"https://api.github.com/users/EmbeddedMan/followers","following_url":"https://api.github.com/users/EmbeddedMan/following{/other_user}","gists_url":"https://api.github.com/users/EmbeddedMan/gists{/gist_id}","starred_url":"https://api.github.com/users/EmbeddedMan/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/EmbeddedMan/subscriptions","organizations_url":"https://api.github.com/users/EmbeddedMan/orgs","repos_url":"https://api.github.com/users/EmbeddedMan/repos","events_url":"https://api.github.com/users/EmbeddedMan/events{/privacy}","received_events_url":"https://api.github.com/users/EmbeddedMan/received_events","type":"User","site_admin":false},"created_at":"2016-08-10T04:06:17Z","updated_at":"2016-08-10T04:06:17Z","body":"Would it work better to transition the EBB Commands page into the EBB Wiki?\nWould that help in any way? (Anybody could edit it then, for example.)\n\nOn Tue, Aug 9, 2016 at 10:52 PM, Brian Schmalz <brian@schmalzhaus.com>\nwrote:\n\n> Yeah! I love it. This is a fantastic idea, and something that's been\n> sorely needed from the beginning.\n>\n> If you're willing to edit the commands file to match this new format, that\n> would be great.\n>\n> Otherwise I can do it as I have some time (which might not be soon).\n>\n> If you do the editing, the only thing I ask is that you send me any\n> changes to the commands HTML file that require changes to the firmware, or\n> at least file them as issues.\n>\n> On Tue, Aug 9, 2016 at 10:49 PM, Windell Oskay <notifications@github.com>\n> wrote:\n>\n>> Following up on #51 <https://github.com/evil-mad/EggBot/issues/51>, I\n>> would like to request an update to the descriptions of individual commands\n>> on the EBB commands page\n>> <http://www.schmalzhaus.com/EBB/EBBCommands.html>.\n>>\n>> For reasons of clarity and usability, it would be nice to standardize the\n>> command (and query) description with slightly more rigid syntax. While\n>> there isn't any one given standard for this kind of thing – Many different\n>> \"standards\" are used – there are certain norms and conventions that are\n>> common and that can be very clear when an explicit legend is given.\n>>\n>> I would like to recommend that the following syntax legend (details of\n>> which are certainly up for debate!) prepend the command set, and that the\n>> commands be updated to follow this syntax.\n>> ------------------------------\n>>\n>> EBB Syntax Conventions\n>>\n>>    - Command format descriptions and examples are set in code font.\n>>    - Query response format descriptions and examples are also set in code\n>>    font.\n>>    - *Italics* are used to represent variables and adjustable parameters.\n>>    - Square brackets ([ ]) are used to enclose optional items.\n>>    - Angle brackets (< >) are used to represent individual control\n>>    characters, such as <CR> for carriage return.\n>>    - All unitalicized text and punctuation within a command description\n>>    must be used literally.\n>>\n>> Additionally, please note that:\n>>\n>>    - All commands are composed of ASCII characters\n>>    - All commands are case insensitive.\n>>    - Whitespace within a command will be ignored.\n>>    - All commands must have a total length of 64 characters or fewer,\n>>    including the terminating <CR> .\n>>\n>> ------------------------------\n>>\n>> To give an example, here is what the current description of the \"SE\"\n>> command looks like:\n>>\n>>    - *Format*: \"SE,<state>,<power><CR>\" (pre v2.4.1)\n>>    - *Format*: \"SE,<state>,<power>,<use_motion_queue><CR>\" (v2.4.1 and\n>>    on)\n>>    - *Example*: \"SE,1,1023\"\n>>    - <state> is 0 for disable, and 1 for enable. You must include this\n>>    parameter.\n>>    - <power> is a value from 0 to 1023 and represents the relative power\n>>    (% duty cycle of the PWM signal), where 0 is off and 1023 is full on. This\n>>    parameter is optional.\n>>    - <use_motion_queue> is optional, and can be a 0 or a 1. If 1, then\n>>    this SE command will be put on the motion queue just like SM and SP\n>>    commands, thus it will be executed when the previous motion commands have\n>>    finished. Note that if you need to use this parameter, the <power>\n>>    parameter is not optional. (You must have 3 parameters if you use this\n>>    parameter.)\n>>    - This command is used to enable and disable the engraver PWM output\n>>    on RB3 (called B3 on the board), and also set its output power. Use SE,0 to\n>>    disable this feature.\n>>    - If <power> is not included, 50% PWM will be used.\n>>    - Returns: \"OK<CR>\"\n>>    - Version Notes: Firmware versions prior to v2.2.2 do not have\n>>    working PWM from this command. Instead, they always defaulted to 50% PWM.\n>>    Version 2.2.2 fixes this problem.\n>>\n>> Now, here is what that same description would look like with the new\n>> syntax (and a few edits):\n>>\n>>    - *Format*: SE, *state* [, *power*]<CR> (Firmware < v2.4.1)\n>>    - *Format*: SE, *state* [, *power* [, *queue* ] ]<CR> (Firmware\n>>    versions ≥ v2.4.1)\n>>    - *Example*: SE,1,1023<CR>\n>>    - *state* is a required parameter, with allowed values 0 for disable,\n>>    and 1 for enable.\n>>    - *power* is an optional parameter, with allowed values 0 through\n>>    1023. It represents the relative power (% duty cycle of the PWM signal),\n>>    where 0 is off and 1023 is full on. If *power* is not specified, the\n>>    default value of 50% PWM will be used.\n>>    - *queue* is an optional parameter, with allowed values 0 or 1. If\n>>    the value is 1, then this SE command will be put on the motion queue just\n>>    like SM and SP commands, thus it will be executed when the previous motion\n>>    commands have finished. If the value is 0, it will be executed immediately\n>>    instead. Note that the power parameter must be specified if you choose to\n>>    include this parameter.\n>>    - *Returns*: OK<CR>\n>>    - Version Notes: Firmware versions prior to v2.2.2 do not have a\n>>    working PWM argument from this command, and always use 50% PWM. Firmware\n>>    v2.4.1 adds the *queue* parameter.\n>>\n>> ------------------------------\n>>\n>> A couple of notes on the example above:\n>>\n>>    - I've added the <CR> in the example.\n>>    - This set of changes makes it explicitly clear which items are\n>>    parameters (for example, <state> is, but <CR> is not)\n>>    - This set of changes makes it explicitly clear which items are\n>>    optional and which are not-- for example, the comma before *power* is\n>>    required, if power is used, and that *queue* may be used only if\n>>    *power* is. With the previous syntax, it is ambiguous as to whether\n>>    the additional commas are optional or required.\n>>\n>> A couple of additional thoughts in general:\n>>\n>>    - It might be nice to have some convention or explicit means of\n>>    marking the the expected parameter values a little more clearly. One might\n>>    consider the following means of doing that:\n>>       - Adding to the command: SE, *BOOLEAN* *state* [, *INTEGER* *power*\n>>       [, *BOOLEAN* *queue* ] ]<CR>\n>>       - Adding to the parameter as: \"*state*: Boolean, required. Values:\n>>       0 for disable, and 1 for enable.\"\n>>       - Adding to the parameter, as \"Boolean *state*: required\n>>       parameter. Values: 0 for disable, and 1 for enable.\"\n>>       - Using a convention where all boolean parameters are capitalized\n>>       (\"*STATE*\").\n>>    - This is a mouthful; I'm open to discussing the types of formatting\n>>    used, as well as helping out with the editing.\n>>\n>> —\n>> You are receiving this because you are subscribed to this thread.\n>> Reply to this email directly, view it on GitHub\n>> <https://github.com/evil-mad/EggBot/issues/54>, or mute the thread\n>> <https://github.com/notifications/unsubscribe-auth/AAbeCPUxJIs9UTrASZfknrcZSy7hTYHIks5qeUosgaJpZM4JgvX_>\n>> .\n>>\n>\n>\n"}}
{"actor":{"display_login":"EmbeddedMan"}}