Eggbot
+Software for the Original EggBot Kit
+View the Project on GitHub evil-mad/EggBot
+-
+
- View On GitHub +
+EBB (EiBotBoard) Command Set
+ + +Introduction
+ The EBB firmware is based on the UBW + firmware. The same basic command processing framework is used, so + the same type of commands are used, and the same type of errors are + returned. See the UBW command + documentation for an introduction to these topics.+
+ This command reference applies to EiBotBoard Firmware v1.8.0 and + above. (Any differences between firmware versions are noted below + and in release notes.)
+
Other Resources
+ +Differences + between 'standard' EggBot firmware version (2.0.1) and latest + version (2.3.0)
+ There have been many changes in the code between the version that is + currently (April 27th, 2014) shipping with EggBot (v2.0.1) and the + latest version (v2.3.0). However, care has been taken to make the + actual performance of the commands used by the EggBot Inkscape + extension (and Water Color Bot) exactly the same as version 2.0.1 + for compatibility's sake. At least until somebody discovers an + incompatibility, and then we will fix it! (please send us e-mail or + file an issue on GitHub : https://github.com/evil-mad/EggBot/issues+
+ All of the changes made between versions 2.0.1 and 2.3.0 (or above) + should not affect EggBot or WaterColorBot operation in any way. The + changes are there to support other uses of the EBB (lots of other + folks use it as well for many different things). So if you are just + using EggBot or WaterColorBot, there isn't a good reason to update + your firmware to the latest.
+
+
EBB Command Reference
+
+ The "XM"
+ Command (stepper motor move for mixed-axis geometries) - Added
+ in version 2.3.0
+
+ -
+
- Format: + "XM,<move_duration>,<axisA>,<axisB><CR>" +
- <move_duration> is a value from 1 to 16777215 and is + in milliseconds. It represents the total length of time you + want this move to take. +
- <axisA> and <axisB> are step values from
+ -1677215 to 1677215 (see below)
+
+ - If both <axisA> and <axisB> are zero, then a + delay of <move_duration> ms is executed. +
- The sign of <axisA> and <axisB> represent the
+ direction you want the motors to move.
+
+ - This command takes the <axisA> and <axisB> values, + and creates a call to the SM command with the SM command's + <Axis1> value as <AxisA> + <AxisB>, and + <Axis2> as <AxisA> - <AxisB>. +
- This command is designed to allow cleaner operation of
+ machines like the H-Bot
+ and CoreXY
+ systems.
+
+ - The minimum speed at which the EBB can generate steps for each
+ motor is 1.31 steps/second. The maximum speed is
+ 25Ksteps/second. If the XM command finds that this speed range
+ will be violated on either axis, it will output an error message
+ declaring such and it will not complete the move. Note that the
+ range is checked on Axis1 and Axis2, NOT on AxisA and AxisB.
+ (I.e. post-math ops)
+
+ - Note that internally the EBB generates an ISR at the 25KHz
+ rate. Each time the ISR fires, the EBB determines if a step
+ needs to be taken for a given axis or not. The practical result
+ of this is that all steps will be 'quantized' to the 25KHz
+ (40uS) time intervals, and thus as the step rate gets close to
+ 25Khz the 'correct' time between steps will not be generated,
+ but instead each step will land on a 40uS tick in time. In
+ almost all cases normally used by the EBB, this doesn't make any
+ difference because the overall proper length for the entire move
+ will be correct.
+
+ - A value of 0 for <move_duration> is invalid and will be + rejected. +
-
+
-
+
- Example: + "XM,1000,550,-1234" +
- Return Packet: "OK" +
The "QC"
+ Command (Query Current) - Added in v2.0, broken up to v2.2.2.
+ Works properly in v2.2.3 and above.
+
+ -
+
- Format: "QC<CR>" +
- Example: "QC" +
- Returns: + "<REF_RA0_VOLTAGE>,<V+_NET_VOLTAGE><CR>" +
- <REF_RA0_VOLTAGE> is the voltage on the REF_RA0 net, as + expressed as a 10 bit number where 0 = 0.0V and 1023 = 3.3V +
- <V+_NET_VOLTAGE> is the voltage on the V+ net scaled by + the resistor divider R13 and R18 +
- This command reads two analog voltages and returns their raw
+ 10 bit values. You can use this to figure out what the user has
+ set the current adjustment pot to, and to read the voltage
+ coming into the board.
+
+ - Returns: + "0421,0021<CR>OK<CR>" +
+
+ For a v1.5 EBB, the following values were + measured for the second returned parameter of the QC command:
+
Input (V+) QC second parameter+ So one + can use these two returned values to check for proper stepper motor + driver current and proper power supply input voltage. You could also + disable the motors, read the power input voltage, then enable the + motors and check it again, giving an approximate reading of the + level of voltage droop on the power supply when the motors are + loading it down. Note that V+ is not measured directly, but rather + after a diode and through a resistor divider. The diode will drop + some voltage (dependent upon current) and there will be some + tolerance in the voltage divider. Thus you can't rely upon the raw + ADC value alone to give a precise measurement.
0.0 449
5.0 513
9.0 574
12.0 604
24.0 775
+
+ Version History: This command was introduced in + v2.0.0, but it had a bug where the upper byte of the result was no + being displayed. Version 2.0.2 fixed this bug and the command now + works properly. But then other problems were discovered. The whole + analog sampling code was re-written for version 2.2.3 and this + command now works.
+
+ The "ES" Command + (E Stop) - Added in v2.2.7, updated in 2.2.9
+ +
-
+
- Format: "ES<CR>" +
- Example: "ES" +
- Use this command to abort any in-progress motor move (SM)
+ command. This command will also delete any motor move command
+ (SM) from the FIFO. It will immediately stop the motors, but
+ leave them energized.
+
+ - This command will return a "1" if it had to stop an
+ in-progress move command, or if it had to delete a move command
+ from the FIFO. This would indicate that some steps might be
+ lost, since the host application thinks the moves have already
+ completed, when in fact they were aborted partway through. This
+ command will return a "0" if no motor move commands were deleted
+ or aborted.
+
+ - Returns: +
- "1<CR>" or
+ "0<CR", then
+
+ - "OK<CR>" +
- Version Notes: In 2.2.9 and above, there are extra + values in the reply to this command: +
- Returns:
+<command_interrupted>,<fifo_steps1>,<fifo_steps2>,<steps_remaining1>,<steps_remaining2><CR>OK<CR>
+ <command_interrupted> = 0 if no FIFO or in-progress move + commands were interrupted,
+ + + + + 1 if a motor move command was in progress or in the FIFO
+ <fifo_steps1> and <fifo_steps1> = 24 bit unsigned + integers with the number of steps
+ + + + + in any SM command sitting in the fifo for axis1 and axis2.
+ <steps_remaining1> and <steps_remaining2> = 24 bit + unsigned integers with the number of
+ + + + + steps left in the currently executing SM command (if any) for
+ + + + + axis1 and axis2.
+ It will return 0,0,0,0,0 if no SM command was executing at the + time, and no SM command was in the FIFO.
+
+
+
-
+
-
+
-
+
The "SE"
+ Command (Set Engraver) - Added in v2.1.0, updated in v2.4.1
+
+ -
+
- Format: + "SE,<state>,<power><CR>" (pre v2.4.1)
- Format: "SE,<state>,<power>,<use_motion_queue><CR>" (v2.4.1 and on)
- Example: "SE,1,1023" +
- <state> is 0 for disable, and 1 for enable. You must + include this parameter. +
- <power> 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.
- <use_motion_queue> 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 <power> parameter is not optional. (You must have 3 parameters if you use this parameter.)
- 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. +
- If <power> is not included, 50% PWM will be used.
+
+ - Returns: + "OK<CR>" +
- 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.
+
+
The "NI"
+ Command (Node count Increment) - Added in v1.9.5
+
+ -
+
- Format: "NI<CR>" +
- Example: "NI" +
- This command increments the 32 bit Node Counter by 1.
+
+ - Returns: + "OK<CR>" +
The "ND"
+ Command (Node count Decrement) - Added in v1.9.5
+
+ -
+
- Format: "ND<CR>" +
- Example: "ND" +
- This command decrements the 32 bit Node Counter by 1.
+
+ - Returns: + "OK<CR>" +
The "BL"
+ Command (BootLoad) - Added in v1.9.5
+
+ -
+
- Format: "BL<CR>" +
- Example: "BL" +
- This command turns off interrupts and jumps into the
+ bootloader. The EBB will enter bootloader mode without having to
+ push any buttons. Note that this command will ONLY work if you
+ have a EBB bootloader version later than 7/3/2010 (the version
+ released on 7/3/2010 has a distinct LED blink mode - the USB LED
+ stays on 3 times longer than the USR LED). With a previous
+ version of the bootloader code, this command may cause the EBB
+ to be come unresponsive.
+
+ - Returns: + "OK<CR>" +
The "SN"
+ Command (Set Node count) - Brought back in v1.9.5
+
+ -
+
- Format: + "SN,<value><CR>" +
- Example: + "SN,123456789" +
- This command sets the Node Counter to <value>.
+ <value> is a 32 bit unsigned int.
+
+ - Returns: + "OK<CR>" +
The "CN"
+ Command (Clear Node count) - Added in v1.9.3, removed in 1.9.5
+ and above
+
+ -
+
- Format: "CN<CR>" +
- Example: "CN" +
- This command clears the value of the Node Counter (see QN
+ command).
+
+ - Returns: + "OK<CR>" +
The "SL"
+ Command (Set Layer) - Added in v1.9.2
+
+ -
+
- Format: + "SL,<NewLayerValue><CR>" +
- Example: "SL,4" +
- This command set the value of the Layer variable (see QL
+ command).
+
+ - Returns:"OK<CR>" +
The "QL"
+ Command (Query Layer) - Added in v1.9.2
+
+ -
+
- Format: "QL<CR>" +
- Example: "QL" +
- This command asks the EBB to report back the current value of
+ the Layer variable. This variable is set with the SL command, as
+ is a single unsigned byte.
+
+ - Returns: + "<CurrentLayerValue><CR>" then "OK<CR>" +
- Example: "4" then "OK"
+
+
+ +
-
+
- Format: "QN<CR>" +
- Example: "QN" +
- This command asks the EBB what the current value of the Node
+ Counter is. The Node Counter is an unsigned long int (8 bytes)
+ value that gets incremented each time an SM command is finished
+ executing.
+
+ - Returns: "<NodeCount><CR>OK<CR>" +
- Example: "1234567890"
+ then "OK"
+
+
The "QB"
+ Command (Query Button) - Added in v1.9.2
+
+ -
+
- Format: "QB<CR>" +
- Example: "QB" +
- This command simply asks the EBB if the PRG button has been
+ pressed since the last QB command or not.
+
+ - Returns: "1" if the + PRG button has been pressed since the last QB command, "0" if it + has not, then "OK" +
The "QP"
+ Command (Query Pen) - Added in v1.9
+
+ -
+
- Format: "QP<CR>" +
- Example: "QP" +
- This command simply asks the EBB what state the pen is in. It
+ will return 1 if the pen is up and 0 if the pen is down. If a
+ pen up/down command is pending in the FIFO, it will only report
+ the new state of the pen after the pen move has been started.
+
+ - Return Packet: "1" if + the pen is UP, "0" if the pen is DOWN, then "OK" +
The "TP"
+ Command (Toggle Pen) - Added in v1.9
+
+ -
+
- Format: + "TP,<duration><CR>" +
- <duration> (optional parameter - if no value then 0 is + used internally) is a value from 1 to 65,535 and is in + milliseconds. It represents the total length of time between + when the pen move is started, and when the next command will + be executed. Note that this does not have anything to do with + how fast the pen moves (which is set with the SC command). The + <duration> parameter is to force the EBB not to execute + the next command (normally an SM) for some length of time, + which gives the system time to allow the pen move to complete + and then some extra time before moving the motors (if you set + up the pen speed and this duration parameter properly). +
- Version Notes: In versions prior to 2.2.1, the
+ <duration> parameter had a bug and was in units of 40uS
+ rather than 1ms. Versions from 2.2.1 and on have this bug fixed.
+
+ -
+
This command toggles the state of the pen (up->down and + down->up). EBB firmware boots up with pen in 'up' + (<servo_min>) state.
+
+
+ - Example: "TP" +
- Return Packet: "OK" +
-
+
-
+
The "SM"
+ Command (stepper motor move)
+
+ -
+
- Format: + "SM,<move_duration>,<axis1>,<axis2><CR>" +
- <move_duration> is a value from 1 to 65,535 (for + version 2.2.5 and above, this value can be up to 1677215) and + is in milliseconds. It represents the total length of time you + want this move to take. +
- <axis1> and <axis2> are values from -32,767 to + +32,767 (for version 2.2.5 and above, these values can be from + -1677215 to 1677215) and represent the number of steps for + each motor to take in <move_duration> milliseconds. +
- If both <axis1> and <axis2> are zero, then a + delay of <move_duration> ms is executed. <axis2> + is an optional value, and if it is not included in the + command, zero steps are assumed for axis 2. +
- The sign of <axis1> and <axis2> represent the
+ direction you want each motor to turn.
+
+
-
+
-
+
- Use this command to make the motors draw a straight line at + constant velocity. +
- The minimum speed at which the EBB can generate steps for each + motor is 1.31 steps/second. The maximum speed is + 25Ksteps/second. If the XM command finds that this speed range + will be violated on either axis, it will output an error message + declaring such and it will not complete the move. Note that the + range is checked on Axis1 and Axis2, NOT on AxisA and AxisB. + (I.e. post-math ops) +
- Note that internally the EBB generates an ISR at the 25KHz + rate. Each time the ISR fires, the EBB determines if a step + needs to be taken for a given axis or not. The practical result + of this is that all steps will be 'quantized' to the 25KHz + (40uS) time intervals, and thus as the step rate gets close to + 25Khz the 'correct' time between steps will not be generated, + but instead each step will land on a 40uS tick in time. In + almost all cases normally used by the EBB, this doesn't make any + difference because the overall proper length for the entire move + will be correct. +
- A value of 0 for <move_duration> is invalid and will be + rejected. +
-
+
- Example: + "SM,1000,250,-766" +
- Return Packet: "OK" +
- Version notes:
+
+ - In versions prior to 2.2.1, the <move_duration>
+ parameter had a bug where values over 2621 would produce
+ incorrect delays (when <axis1> and <axis2> are 0).
+ This has been fixed for 2.2.1 and above, and now values up to
+ 65,535 will work properly.
+ As of version 2.2.5, the <move_duration>, <axis1>, + and <axis2> parameters for this command are full 24 bit + numbers. <move_duration> is an unsigned 24-bit value, + while <axis1> and <axis2> are signed. This allows + for some _very_ long stepper moves.
+ - As of version 2.2.8, the error messages for this command
+ have been corrected. If an input parameter is too large
+ (>1677215) or a step rate is too fast (>25K steps/s) or
+ too slow (<1.31 steps/s) a proper error will be printed
+ back to the host.
+
+
-
+
The "SP"
+ Command (set pen state)
+
+ -
+
- Format: + "SP,<value>,<duration>,<portBpin><CR>" +
- <value> is 0 or 1
+
+ - <duration> (optional parameter - if no value then 0 is + used internally) is a value from 1 to 65,535 and is in + milliseconds. It represents the total length of time between + when the pen move is started, and when the next command will + be executed. Note that this does not have anything to do with + how fast the pen moves (which is set with the SC command). The + <duration> parameter is to force the EBB not to execute + the next command (normally an SM) for some length of time, + which gives the system time to allow the pen move to complete + and then some extra time before moving the motors (if you set + up the pen speed and this duration parameter properly). +
- <portBpin> (optional - if not present, then 1 is used) + Which port B pin you want this output to come out of (values + from 0 through 7 are valid) (Note: this parameter is new for + EBF 2.1.1 and above) +
- When a <value> of 1 is used, the servo will be moved to + the <servo_min> value (as set by the "SC,4" command + below). +
- When a <value> of 0 is used, the servo will be moved to + the <servo_max> value (as set by the "SC,5" command + below). +
- Note that the EggBot Inkscape extension uses the
+ <servo_min> ("SC,4") value as the 'Pen up position', and
+ the <servo_max> ("SC,5") value as the 'Pen down position'.
+
+ - This command will make the pen go up or down. On EBB versions + 1.1, 1.2 and 1.3 this will make the solenoid output turn on and + off. On all EBB versions it will also make the RC servo output + on RB1 move to the up or down position. Also, by default, it + will turn on RB4 or turn off RB4 as a simple digital output, so + that you could use this to trigger a laser for example. +
- The default position for the RC servo output (RB1) on boot is
+ the 'Pen up position' (<servo_min>), and at boot
+ <servo_min> is set to 12000 which results in a pulse width
+ of 1.0mS on boot. <servo_max> is set to 16000 on boot, so
+ the down position will be 1.3mS unless changed with the "SC,5"
+ command.
+
+ - Version Notes:In versions prior to 2.2.4, the
+ <duration> parameter had two bugs. One was that the units
+ for <duration> were 40uS (instead of the correct 1ms). The
+ second was that the change of state of the servo would happen
+ AFTER the delay had elapsed. Both of these bugs have been
+ corrected in v2.2.4 and above. The servo move and the
+ <duration> delay are both started simultaneously now.
+
+
-
+
-
+
- Example: "SP,1" +
- Return Packet: "OK" +
The "EM" Command (enable
+ motors) for EBB v1.1
+
+ -
+
- Format: + "EM,<EnableAxis1>,<EnableAxis2><CR>" +
- Everything after <EnableAxis1> is optional
+
+ - For each axis: +
- 0 will disable that axis (the driver will stop sending + current to the motor, so the motor will freewheel) +
- 1 will enable that axis in 1/8th step mode (default) +
- 2 will enable that axis in 1/4 step mode +
- 3 will enable that axis in 1/2 step mode +
- 4 will enable that axis in full step mode
+
+ - Example: "EM,1,0" +
- Return Packet: "OK" +
-
+
-
+
The "EM"
+ Command (enable motors) for EBB v1.2 and above
+
+ -
+
- Format: + "EM,<Enable1>,<Enable2><CR>" +
- To enable a motor driver, set its <Enable> parameter
+ to 1.
+
+ - To disable a motor driver, set its <Enable> parameter + to 0. +
- For example, "EM,1,0" will enable motor 1 and disable motor + 2. +
- To set the microstep mode of BOTH motor drivers (the same + signals go to both drivers, so you can't set them separately) + use a value of 1,2,3,4 or 5 for <Enable1>. +
- When setting microstep values with <Enable1>:
+
+ - 1 will enable both axis in 1/16th step mode (default on + boot) +
- 2 will enable both axis in 1/8th step mode
+
+ - 3 will enable both axis in 1/4 step mode +
- 4 will enable both axis in 1/2 step mode +
- 5 will enable both axis in full step mode +
- Note that any time an SM command is executed, both motors
+ become 'enabled' before the move starts. Thus it is almost
+ never necessary to issue a "EM,1,1" command to enable both
+ motors.
+
+ - Example: "EM,2" - this + command will set both motors in 1/8th step mode +
- Example: "EM,0,0" - + this command will disable both motors (they will then freewheel) +
- Example: "EM,1,1" -
+ this command will enable both motors and set them to 1/16th
+ microstep mode.
+
+ - Return Packet: "OK" +
-
+
-
+
The "SC"
+ Command (stepper mode configure)
+
+ -
+
- Format: + "SC,<value1>,<value2><CR>" +
- <value1> is a number from 0 to 255 - it's meaning is
+ defined below
+
+ - <value2> is a number from 0 to 65535 - it's meaning
+ depends upon <value1>
+
+ -
+
This command allows you to set different parameters that + effect the operation of the EBB.
+
+ - SC,1,0 - uses just the solenoid output (RB4) for pen up/down + (no RC servo outputs) +
- SC,1,1 - uses just the RC pen lift servo on RB1 for pen
+ up/down (no solenoid output on RB4)
+
+ - SC,1,2 - uses solenoid (RB4) and RC servo (RB1) output for + pen up/down, hardware RC output (default) +
- SC,2,0 - Set PIC to control built-in stepper driver chips + (default) +
- SC,2,1 - Set PIC to control external step/direction drivers
+ based on these pins.
+
+ - ENABLE1 = RD1 +
- ENABLE2 = RA1 +
- STEP1 = RC6 +
- DIR1 = RC2 +
- STEP2 = RA5 +
- DIR2 = RA2
+
+ - Note that SC,2,1 will also disconnect the PIC from the
+ built-in motor drivers, so you can drive the
+ step/direction/enable lines of the built-in drivers from the
+ pins of J5 and J4 (they all come out there - see schematic)
+ This command allows you to use the PIC as a step and
+ direction generator for external step/dir drives.
+
+ - SC,2,2 - PIC is disconnected from built-in motor drivers and
+ external pins - all step/dir/enable pins on the PIC are set to
+ inputs. This allows you to completely control the built-in
+ stepper motor driver chips externally with your own
+ step/dir/enable signals. Use the pins listed in the schematic
+ from J5 and J4. (new in 2.2.2)
+
+ - SC,4,<servo_min> - sets the minimum value for the
+ servo (1 to 65535, in units of 83nS ). This is the 'Pen up
+ position', and defaults to 12000 (1.0mS) on boot.
+
+ - SC,5,<servo_max> - sets the maximum value for the
+ servo (1 to 65535, in units of 83nS). This is the 'Pen down
+ position', and it defaults to 16000 (1.3mS) on boot.
+
+ - SC,8,<maximum_S2_channels> - sets the number of
+ channels, each of <S2_channel_duration_ms> before
+ cycling back to channel 1 for S2 command. Values from 1 to 24
+ are valid. Defaults to 8 on bootup. (new for EBB 2.1.1)
+
+ - SC,9,<S2_channel_duration_ms> - sets the number of
+ milliseconds before firing the next enabled channel for the S2
+ command. Defaults to 3ms. (new for EBB 2.1.1)
+
+ - SC,10,<servo_rate> - sets both going up and going down
+ rates of change for the servo. (Same as <rate> parameter
+ in S2 command below)
+
+ - SC,11,<servo_rate_up> - sets the rate of change of the + servo when going up (new in v1.9.2) (Same as <rate> + parameter in S2 command below) +
- SC,12,<servo_rate_down> - sets the rate of change of + the servo when going down (new in v1.9.2) (Same as + <rate> parameter in S2 command below) +
- SC,13,<use_alt_pause> - turns on (1) or off (0) + alternate pause button function on RB0. On by default. For + v1.1 boards, it uses RB2 instead. (new in v2.0) +
- Example: "SC,4,8000" +
- Return Packet: "OK" +
-
+
-
+
-
+
-
+
+
The "S2" Command (general RC
+ servo output) - for versions prior to 2.2.0
+
+ -
+
- Format: +"S2,<channel>,<position>,<output_pin>,<rate><CR>" +
- <channel> is a number from 0 to 8 (with 0 as a special
+ value which shuts off all S2 outputs)
+
+ - <position> is a number from 0 to 32,000, and
+ represents the 'on' time in 1/12,000,000ths of a second (0 =
+ channel off, 1=83us, 32,000 = 3ms)
+
+ - <output_pin> is a number from 0 to 24, and is the RPx
+ pin number you want this channel to come out on- see schematic
+ for RPx numbers
+
+ - <rate> is the rate at which to change from the current
+ value to the new value. Use 0 to have changes instant. See
+ below for the units of this value. Values from 0 to 65535 are
+ valid. Optional parameter.
+
+ - This command is a generic RC servo output command. It allows + you to control the RC servo output system on the EBB. Many I/O + pins have RPx numbers (see the schematic) - and you can output + RC servo pulses on up to 8 of these RPx pins. Any of them that + you want - it doesn't matter to the software. There are seven RC + servo 'channels', which have no physical meaning other than we + can (by default) only output up to 8 separate signals at once. + But you can assign any RPx pin to any channel - that's up to you + to manage. The RC servo system will cycle through each of the 8 + channels. Each gets 3m of 'time'. (Thus giving a 24ms repeat + rate for the whole RC system.) If the current channel is + enabled, then at the beginning of its 3ms time slot, it's RPx + pin is set high. Then, <position> time later, the RPx pin + is set low. This time is controlled purely by hardware (the + ECCP2 in the CPU) so there is no jitter for the pulse durations. + <position> is in units of 1/12,000 of a second, so 32,000 + for <position> would be exactly 3ms. +
- The number of available channels is normally (by default) 8.
+ This can be changed with the SC,8 command (see above). The S2 RC
+ servo output command cycles from channel 1 through channel
+ <maximum_S2_channels> (normally 8), outputting any enabled
+ channel's pulse from 0ms to 3ms. For a given channel, the
+ repetition rate is determined by <maximum_S2_channels> *
+ <S2_channel_duration_ms> which is normally 8 * 3 or 24ms.
+ Thus, each channel's output pulse will be repeated every 24ms.
+ Note that channel 0 is not a real channel - the <channel>
+ = 0 value is used to disable all S2 functionality. If you change
+ the <maximum_S2_channels> you will change the repetition
+ rate of the pulses.
+
+ - The <rate> parameter is used to indicate how quickly to + move from the current pulse width (servo position) to the new + pulse width. If <rate> is zero, then the move is made on + the next PWM cycle (i.e. the next time the pin is pulsed). If + <rate> is not zero, then <rate> is added to (or + subtracted from) the current pulse width each time the pulse is + generated until the new target is reached. This means that the + units of <rate> are 1/12,000ths of a second per + <maximum_S2_channels> * <S2_channel_duration_ms> or + 1/12,000ths of a second per 24ms. +
- The normal pen up/down servo control (SP and TP commands) use + S2 channel 1. So if you want to use SP and TP, then leave + channel 1 alone and start with channel 2. If you don't care to + use SP and TP anymore, then you can use channels 1 through + <maximum_S2_channels>. +
- The S2 command will always make <output_pin> an output
+ before it starts outputting pulses to that pin.
+
+ - For example, to use RP6 as a RC servo output, and to set it's
+ on-time to 2ms, and using channel 3 of the RC system, you would
+ send the command (note <rate> is optional)
+
+ - S2,3,24000,6<CR> +
- S2,0 - will turn off all RC servo support (freeing up CPU + time, if that's important to you) +
- S2,3,0 - will turn off the output on whatever pin channel 3
+ was assigned to.
+
+ - Return Packet: "OK" +
-
+
-
+
+
The "S2"
+ Command (general RC servo output) - for versions 2.2.0 and above
+
+ -
+
- Format: +"S2,<position>,<output_pin>,<rate>,<delay><CR>" +
- <position> is a number from 0 to 32,000, and
+ represents the 'on' time in 1/12,000,000ths of a second (0 =
+ off, 1=83us, 32,000 = 3ms)
+
+ - <output_pin> is a number from 0 to 24, and is the RPx
+ pin number you want this channel to come out on- see schematic
+ for RPx numbers
+
+ - <rate> is the rate at which to change from the current + value to the new value. Use 0 to have changes instant. See + below for the units of this value. Values from 0 to 65535 are + valid. Optional parameter. +
- <delay> is the number of milliseconds to delay the
+ start of the next command (optional, defaults to 0 = instant)
+
+ - This command is a generic RC servo output command. It allows + you to control the RC servo output system on the EBB. Many I/O + pins have RPx numbers (see the schematic) - and you can output + RC servo pulses on up to 8 of these RPx pins. Any of them that + you want - it doesn't matter to the software. There are seven RC + servo 'channels', which have no physical meaning other than we + can (by default) only output up to 8 separate signals at once. + But you can assign any RPx pin to any channel - that's up to you + to manage. The RC servo system will cycle through each of the 8 + channels. Each gets 3m of 'time'. (Thus giving a 24ms repeat + rate for the whole RC system.) If the current channel is + enabled, then at the beginning of its 3ms time slot, it's RPx + pin is set high. Then, <position> time later, the RPx pin + is set low. This time is controlled purely by hardware (the + ECCP2 in the CPU) so there is no jitter for the pulse durations. + <position> is in units of 1/12,000 of a second, so 32,000 + for <duration> would be exactly 3ms. +
- The <rate> parameter is used to indicate how quickly to + move from the current pulse width (servo position) to the new + pulse width. If <rate> is zero, then the move is made on + the next PWM cycle (i.e. the next time the pin is pulsed). If + <rate> is not zero, then <rate> is added to (or + subtracted from) the current pulse width each time the pulse is + generated until the new target is reached. This means that the + units of <rate> are 1/12,000ths of a second per + <maximum_S2_channels> * <S2_channel_duration_ms> or + 1/12,000ths of a second per 24ms. +
- The S2 command will always make <output_pin> an output
+ before it starts outputting pulses to that pin.
+
+ - For example, to use RP6 (which is pin RB3) as a RC servo
+ output, and to set it's on-time to 2ms,you would send the
+ command (note <rate> and <delay> are optional)
+
+ - S2,24000,6<CR> +
- S2,0 - will turn off all RC servo support (freeing up CPU + time, if that's important to you) +
- S2,0,5 - will turn off the output on RP5 (which is pin RB2) so
+ it stops sending any pulses.
+
+ - Return Packet: "OK" +
- More examples: +
- Say you want to control a servo on RB2. (RB2 = RP5 as per + schematic). You could send +
- "S2,10000,5" to send a 1ms pulse out pin RB2. (This made my + servo go full clockwise) +
- "S2,27500,5" to send a 2.3ms pulse out pin RB2. (This made + my servo go full counter-clockwise) +
- You have to experiment to see what <position> + value makes your servo go all the way CW and all the way CCW. + Each servo model is slightly different. Also it is common that + servos will refuse to move at all if the pulse is outside + their normal 'accepted' range (whatever that is for that model + servo). So if you send a very short pulse (like 0.1mS) the + servo may just completely ignore it rather than going all the + way in one direction. +
- RPn vs pin number table:
++ +
++ +RPn +
+RP0 +
+RP1 +
+RP2 +
+RP3 +
+RP4 +
+RP5 +
+RP6 +
+RP7 +
++ + +Pin +
+REF_RA0 +
+RA1 +
+RA5 +
+RB0 +
+RB1 +
+RB2 +
+RB3 +
+RB4 +
++ +
++ +RPn +
+RP8 +
+RP9 +
+RP10 +
+RP11 +
+RP13 +
+RP17 +
+RP18 +
++ + +Pin +
+RB5 +
+RB6 +
+RB7 +
+RC0 +
+RC2 +
+RC6 +
+RC7 +
+
+
+
-
+
-
+
-
+
+
-
+
- Format: "A<CR>" +
- When any analog channels are enabled (see "AC" command below), + the "A" command will cause the EBB to return a list of all + enabled channels and their associated 10 bit values. Note that + this is a different format from the "A" command that is in pre + v2.2.3 versions. Before version 2.2.3, the "A" command format is + the same as the normal UBW "A" command. (See UBW documentation + for details.) Once the analog commands were re-written in + v2.2.3, the AC command was added and the A command modified to + return a list that includes the channel number as well as the + ADC value for each channel. +
- Format of return packet: + "A,<channel>:<value>,<channel>:<value>. + . . <CR>" +
- The <value> returned for each enabled channel will range
+ from 0 (for 0.0V on the input) to 1023 (for 3.3V on the input).
+
+ - The list of channels and their data will always be in sorted + order from least (channel) to greatest. Only enabled channels + will be present in the list. +
- The channel number and ADC value are both padded to 2 and 4
+ characters respectively in the A response.
+
+ - Return Packet: + "A,00:0713,02:0241,05:0089:09:1004<CR>" if channels 0, 2, + 5 and 9 are enabled. +
- NOTE: Analog inputs can ONLY take up to 3.3V inputs. They are + not able to take voltages more than 3.3V. Be careful not to put + 5V on them or you may damage the pin. +
- Also, if you connect an ADC pin to GND (0.0V) it will likely
+ not read exactly 0. It will be a bit higher than that. (I got
+ 0023 in my testing) This is because of the way that the analog
+ input reference voltages are supplied to the PIC.
+
+
+ The "AC" Command (Analog Configure) - for + versions 2.2.3 and above
+
-
+
- Format: + "AC,<channel>,<enable><CR>" +
- <channel> is a number from 0 15, and represents the
+ PIC's analog channel number (ANx on the schematic and
+ datasheet) you wish to enable/disable.
+
+ - <enable> is either 1 to enable, or 0 to disable
+ <channel>.
+
+ - Use this command to turn on or turn off individual analog + channels. Once a channel is turned on, it will begin converting + analog values to digital values and the results of the + conversions will be displayed in the returned value of the "A" + command. See "A" command above. You can turn on and off any of + the 16 analog channels individually on this microcontroller. + Once a channel is turned off, it will no longer show up in the + "A" packet returned value list. +
- You can find the pins that are analog inputs by looking at the
+ EBB schematic, and looking at the pins on the PIC
+ microcontroller. They will show ANx as one of their functions.
+ For example, pin 11 of the PIC, which is labeled RB2 and comes
+ out as the RB2 pin on the servo header, has the text
+ "RB2/AN8/CTEDG1/PMA3/VMO/REFO/RP5" next to it on the CPU symbol.
+ This means that this pin is connected to Analog Channel 8 inside
+ the PIC. Check out chapter 21 of the PIC18F46J50
+
+
+
+
+
+
+
+
+
+
+ datasheet to read more about the ADC converter.
+
+ - Return Packet: "OK" +
-
+
+ The "QM" Command (Query Motor) - for versions 2.2.6 + and above
+
-
+
- Format: "QM<CR>" +
- Return Packet: +"QM,<CommandExecutingStatus>,<Motor1Status>,<Motor2Status>" +
- <CommandExecutingStatus> will be 0 if there are no
+ currently executing 'motion commands', and will be non-zero if
+ there are any currently executing 'motion commands'.
+
+ - <Motor1Status> will be 0 if motor 1 is idle, and will + be 1 if motor 1 is currently running +
- <Motor2Status> will be 0 if motor 2 is idle, and will + be 1 if motor 2 is currently running +
- This command takes no parameters. +
- Use this command to see what the EBB is currently doing. It + will return the current state of the 'motion system' and each + motor's current state. +
- The definition of a 'motion command' is any command that has a
+ time associated with it. For example, all SM commands. Also, any
+ command (like S2, SP, or TP) that uses a <delay> or
+ <duration> parameter. All of these commands cause the
+ motion processor to 'do something' for some length of time,
+ which then prevents later motion commands from running until
+ they have finished.
+
+ - It is very important to realize that with the existing EBB
+ firmware (all versions), there are a limited number of
+ 'motion commands' that can be executing or queued up at a time.
+ In fact, there can only be three. One (the first one) will be
+ actually executing. Another one (the second) will be stored in
+ the 1-deep FIFO that sits between the USB command processor and
+ the motion engine that executes motion commands. Then the last
+ one (the third) will be stuck in the USB command buffer, waiting
+ for the 1-deep FIFO to be emptied before it can be processed.
+ Once there are these three motion commands, the whole USB
+ command processor will block (i.e. lock up) until the FIFO is
+ cleared, and the third motion command can be processed and put
+ into the FIFO. This means that NO USB commands can be processed
+ by the EBB once the third motion command gets 'stuck' in the USB
+ command processor. Using the QM command can help prevent this
+ situation by allowing the PC to know when there are no more
+ motion commands to be executed, and so can send the next one on.
+
+
-
+
+
Questions? E-mail me at
+ brian@schmalzhaus.com
+
+ +
+
+ EggBotBoard by Brian + Schmalz is licensed under a Creative + Commons Attribution 3.0 United States License.
+ Based on a work at www.schmalzhaus.com/EBB.
+ Permissions beyond the scope of this license may be available at www.schmalzhaus.com/EBB.
+
+ + + + +
Extended EggBot documentation available at: http://wiki.evilmadscientist.com/eggbot
+