Speed Controller API

Jump to: navigation, search

Original taken from http://www.photopete.com/swarm/ESC_API.txt on 4-18-07

Swarm Orb Electronic Speed Control API
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.


	Panic stop.  Immediately turns off the drive motor.
	Cmd: 'STOP'  or just 'S'
	Example:  $STOP*  or $S*

	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*
	Setup the controller for Reverse direction
	Cmd: 'Rev' or 'R'
	Example:  $Rev*

	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 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 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.

	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.
	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
	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.
	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

	Sets proportional gain factor.
	Cmd: 'v'
	Values: 0 to 9999
	Example: $v8*  sets steering Kp to 8

	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

	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.

	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

	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)


	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.