Swarm Orb Electronic Speed Control API v11.0 17-April-2007 Petey the Programmer ----------------- The API into the speed controller is an ASCII based serial protocol. The commands to the ESC (electronic speed control) all start with a dollar sign '$' and end with an asterisk '*'. Only chars between these two delimiters will be processed - anything else is ignored. (which means you can add CR-LF after the * so they are read-able on a terminal for debugging, and the ESC will ignore them.) Most commands consist of a single ascii chr, followed by a numeric value. An example is Set_Drive_Torque, the Cmd is the letter 't'. The numeric values range from -100 to +100, as a percent of total available torque. (We can change the precision if we want, to -1000 to +1000 to represent 100.0 percent) A single space can be added between the Cmd and numeric values for read-ability if desired. (the space is ignored) To set the torque to 50% The chars sent to the ESC will be: $t50* or $t 50* The ESC has an internal buffer of 32 bytes, and processes chars very quickly, but if more than 32 chars are sent at once (I don't know why you would) it may over run the buffer. (I've never over run it) All chars are processed within 0.1ms of being received. (160,000 chars per second) Commands execute as soon as the * char is received. ----------------- ALL_STOP Panic stop. Immediately turns off the drive motor. Cmd: 'STOP' or just 'S' Example: $STOP* or $S* Set_Direction_Forward Setup the controller for Forward direction When using PID torque control, the host controller should bring the orb to a stop (or close to it) before reversing directions. Cmd: 'Fwd' or 'F' Example: $Fwd* Set_Direction_Reverse Setup the controller for Reverse direction Cmd: 'Rev' or 'R' Example: $Rev* Set_Drive_Torque Set the amount of torque sent to drive motor. Turns ON PID control. Cmd = 't' Values are -100 to +100 as percentage of available torque. Negative values are for braking. Zero sets controller to coast. Example: $t50* will set the torque to 50% Direction must be set using the Fwd / Rev commands. If we don't want braking or coasting, this can be changed to +100 to -100 for direct Fwd / Reverse control. Positive = Fwd, Neg = Rev. 0 = Stop. Set_Drive_PWM Set the Duty Cycle of the H-Bridge directly. Turns OFF PID control. Cmd = 'p' Values are -100 to +100 as percent duty cycle. Zero = stop. Positive values are forward direction, negative values are reverse. Example: $p33* sets the PWM to 33% forward. $p-50* sets 50% reverse. Set_Steering_Position Set the steering servo's position. Cmd = 's' Values are -512 to 512 Zero is center. Negative values steer towards the left, positive to the right. Example: $s0* centers the steering. We can change this to -100 to +100 if someone wants, and it will then be relative control of the servo position as percentage of AVAILABLE throw. Then the host won't have to figure out where the servo limits are... (s-100 will steer full left - even if we only have 40 degrees of swing) ------- Setting the Motor Control PID Gain Factors (for testing & tuning) This requires some understanding of the actual code... Motor_Drive = (P_Factor * Kp) + (D_Factor * Kd) + (I_Factor * Ki) Actual values depend on which PID function is being used. The values are NOT saved to EPROM, and if changed, must be reset after each re-boot. Once we like the values, I will burn them into the startup code. The default startup values for the ESC are: Use the iTerm PID (P1) Kp = 8 Ki = 10 Kd = 4 Kp, Kd, and Ki CAN be adjusted while the orb is in motion. Select_Drive_PID There are two PID functions available. One is a standard PID, the other uses the iTerm in a novel way to deal with the relatively long time lag found in this system. Cmd: 'P' Values are 0 or 1. 0 selects the Std PID, 1 selects the iTerm PID Example: $P1* selects the iTerm PID. DO NOT CHANGE THE PID WHILE THE ORB IS MOVING !!! Set_Drive_Kp Sets the proportional drive gain. Values are -9999 to 9999. Reasonable values are 0 to 50 Cmd: 'Kp' Example: $Kp12* sets the Kp gain factor to 12 Set_Drive_Kd Sets the derivative drive gain. Values are -9999 to 9999. Reasonable values are 0 to 50 (depends on PID and motor used) Cmd: 'Kd' Example: $Kd 5* sets the Kp gain factor to 5. Set_Drive_Ki Sets the iterative drive gain. Values are -9999 to 9999. Reasonable values are 0 to 50 (depends on PID and motor used) Cmd: 'Ki' Example: $Ki 5* sets the Kp gain factor to 5. --------- Setting the Steering Servo PID factors. The Steering Servo works a little different than the Motor Drive. It attempts to form a trapezoidal power function, accelerating to a max speed, maintain that speed until close to the set point, then de-accelerate to avoid overshoot. There is also a dead-band, and min drive value to limit chatter around the set point. Default values for Steering Servo at Startup: Kp = 10 dead_band = 5 minDrive = 10 maxDrive = 255 maxAccel = 30 Set_Steering_Kp Sets proportional gain factor. Cmd: 'v' Values: 0 to 9999 Example: $v8* sets steering Kp to 8 Set_Steering_Dead_Band Sets size of dead-band area around the set point. if ( abs(crntPos - targetPos) < dead_band) then don't move servo. Cmd: 'd' Values: 0 to 255 Example: $d5* sets dead band value to 5 Set_Steering_Max_Acceleration Sets max acceleration value for servo. (saves the gears) This can be decreased if the servo is accelerating too fast. Cmd: 'a' Values: 0 to 255 Example: $a30* sets max acceleration to 30. Set_Steering_Min_Drive Sets min value sent to PWM motor control when moving servo. There is a minimum value of PWM that will actually cause the servo to move. Anything less just makes it hum. Cmd: 'b' Values: 0 to 255 Example: $b5* sets min drive value to 5 Set_Steering_Max_Drive Sets max value sent to PWM motor control when moving servo. This is the fastest you want the servo to move. Cmd: 'c' Values: 0 to 255 zero makes no sense. 255 is the fastest speed available. Example: $c255* sets max drive value to 255 (Full speed) --------------- Dump_Data Request the ESC to return debug data about motor, steering & PIDs Cmd: '?' Response is dependant on what I'm debugging. Example response: Steer: -00185 -00168 Gain: +00010 +00010 +00255 +00030 +00005 Motor: +00010 +00010 +00255 PID: +00030 +00005 +00030 +00005 --------------- That's it. The commands can easily be changed, or augmented, or the value ranges modified. End of Doc.