Create isp_bldc_motor.txt

- add current public interface doc

isp_bldc_motor.txt

@@ -0,0 +1,342 @@
+ =================================================================================================
+   File....... isp_bldc_motor.spin2
+   Purpose.... Object providing control interface for a single BLDC motor
+   Authors.... Stephen M Moraco
+               -- Copyright (c) 2023 Iron Sheep Productions, LLC
+               -- see below for terms of use
+   E-mail..... stephen@ironsheep.biz
+   Started.... Feb 2022
+   Updated.... 16 Sep 2023
+ =================================================================================================
+
+Object "isp_bldc_motor" Interface:
+
+PUB null()
+PUB start(eMotorBasePin, eMotorVoltage, eDetectionMode) : ok
+PUB startEx(eMotorBasePin, eMotorVoltage, eDetectionMode, sync) : ok
+PUB stop()
+PUB startSenseCog() : ok
+PUB setAcceleration(rate)
+PUB setRampingValues(minRamp, maxRamp, incRamp, decrRamp)
+PUB getRampingValues() : minRamp, maxRamp, incRamp, decrRamp
+PUB setMaxSpeed(speed)
+PUB setMaxSpeedForDistance(speed)
+PUB calibrate()
+PUB holdAtStop(bEnable)
+PUB resetTracking()
+PUB moveShaftToAngle(desiredAngle)
+PUB driveForDistance(distance, distanceUnits)
+PUB driveAtPower(power)
+PUB driveAtPowerEx(power, sync)
+PUB stopAfterRotation(nRotationCount, eRotationUnits)
+PUB stopAfterDistance(nDistance, eDistanceUnits)
+PUB stopAfterTime(nTime, eTimeUnits)
+PUB stopMotor()
+PUB emergencyCutoff()
+PUB clearEmergency()
+PUB forwardIsReverse()
+PUB getDistance(eDistanceUnits) : nDistanceInUnits
+PUB getRotationCount(eRotationUnits) : rotationCount
+PUB getPower() : nPower
+PUB getCurrent() : fAmps, fWatts
+PUB getMaxSpeed() : nSpeed
+PUB getMaxSpeedForDistance() : nSpeed4dist
+PUB getStatus() : eStatus
+PUB getDriverState() : eDrvrState
+PUB getRawHallTicks() : nPos
+PUB boardIdString() : pZStr
+PUB getBoardType() : eBoardRev
+PUB isReady() : bState
+PUB isStopped() : bState
+PUB isFaulted() : bState
+PUB isStarting() : bState
+PUB isTurning() : bState
+PUB isEmergency() : bState
+PUB isFaultSignal() : bState
+PUB clearFaultSignal()
+PUB validBasePinForChoice(userBasePin) : legalBasePin
+PUB validVoltageForChoice(userVoltage) : legalVoltage
+PUB validMotorForChoice(userMotor) : legalMotor
+PUB validDetectModeForChoice(userDetMode) : legalMode
+PUB hallTicInfoForMotor() : degreesPerTic, ticsPerRotation
+PUB SyncStatus()
+
+__________
+PUB null()
+
+ This is not a top-level object
+
+____________________________________________________________
+PUB start(eMotorBasePin, eMotorVoltage, eDetectionMode) : ok
+
+ Specify motor control board connect location for this motor and start the driver
+
+____________________________________________________________________
+PUB startEx(eMotorBasePin, eMotorVoltage, eDetectionMode, sync) : ok
+
+ Specify motor control board connect location for this motor and start the driver, specify sync setting
+
+__________
+PUB stop()
+
+ Stop cogs and release pins assigned to this motor
+
+________________________
+PUB startSenseCog() : ok
+
+ Start the single motor sense task (tracks position of motor, distance traveled, etc.)
+
+_________________________
+PUB setAcceleration(rate)
+
+ Limit Acceleration to {rate} where {rate} is [??? - ???] mm/s squared (default is ??? mm/s squared)
+
+_________________________________________________________
+PUB setRampingValues(minRamp, maxRamp, incRamp, decrRamp)
+
+ Change the ramping parameters
+
+____________________________________________________________
+PUB getRampingValues() : minRamp, maxRamp, incRamp, decrRamp
+
+ Return the ramping parameters
+
+______________________
+PUB setMaxSpeed(speed)
+
+ Limit top-speed to {speed} where {speed} is [1 to 100]  (default is 75)
+
+_________________________________
+PUB setMaxSpeedForDistance(speed)
+
+ Limit top-speed of driveDistance() operations to {speed} where {speed} is [1 to 100]  (default is 75)
+
+_______________
+PUB calibrate()
+
+ NOT WORKING: (we may or may not need this?)
+  have motor drivers determine fixed-offset constants
+
+_______________________
+PUB holdAtStop(bEnable)
+
+ Informs the motor control cog to actively hold position (bEnable=true) or coast (bEnable=false) at end of motion
+
+___________________
+PUB resetTracking()
+
+ Resets the position tracking values returned by getDistance() and getRotations()
+
+_____________________________________________
+PUB driveForDistance(distance, distanceUnits)
+
+ Control the forward direction of this motor using the {distance} and {distanceUnits} inputs.
+ Turn the motor on then turn it off again after it reaches the specified {distance} in {distanceUnits} [DDU_IN, DDU_CM, DDU_FT or DDU_M].
+ AFFECTED BY:  setAcceleration(), setMaxSpeedForDistance(), holdAtStop()
+
+_______________________
+PUB driveAtPower(power)
+
+ Control the speed and direction of this motor using the {power, [(-100) to 100]} input.
+ Turns the motor on at {power}.
+ AFFECTED BY:  setAcceleration(), setMaxSpeed(), holdAtStop()
+
+_______________________________
+PUB driveAtPowerEx(power, sync)
+
+ Control the speed and direction of this motor using the {power, [(-100) to 100]} input. (allow sync setting)
+ Turns the motor on at {power}.
+ AFFECTED BY:  setAcceleration(), setMaxSpeed(), holdAtStop()
+
+_____________________________________________________
+PUB stopAfterRotation(nRotationCount, eRotationUnits)
+
+ Stops the motor after it reaches {rotationCount} of {rotationUnits} [DRU_HALL_TICKS, DRU_DEGREES, or DRU_ROTATIONS].
+ USE WITH:  driveAtPower()
+ Will ABORT if {rotationCount} < 1
+
+________________________________________________
+PUB stopAfterDistance(nDistance, eDistanceUnits)
+
+ Stops the motor after it reaches {distance} specified in {distanceUnits} [DDU_MM, DDU_CM, DDU_IN, DDU_FT, DDU_M].
+ USE WITH:  driveAtPower()
+ Will ABORT if {distance} < 1
+
+____________________________________
+PUB stopAfterTime(nTime, eTimeUnits)
+
+ Stops the motor, after {time} specified in {timeUnits} [DTU_MILLISEC or DTU_SEC] has elapsed.
+ USE WITH:  driveAtPower()
+ Will ABORT if {time} < 1
+
+_______________
+PUB stopMotor()
+
+ Stops the motor, killing any motion that was still in progress
+  AFFECTED BY:holdAtStop()
+
+_____________________
+PUB emergencyCutoff()
+
+ EMERGENCY-Stop - Immediately stop motor, killing any motion that was still in progress
+
+____________________
+PUB clearEmergency()
+
+ Clear EMERGENCY-Stop - remove the need to stop!
+
+______________________
+PUB forwardIsReverse()
+
+ Call when we have two motors and one of them needs to be reversed
+
+__________________________________________________
+PUB getDistance(eDistanceUnits) : nDistanceInUnits
+
+ Returns the distance in {distanceUnits} [DDU_MM, DDU_CM, DDU_IN, DDU_FT, DDU_M, DDU_KM, DDU_MI] travelled by this motor since last reset
+
+____________________________________________________
+PUB getRotationCount(eRotationUnits) : rotationCount
+
+ Returns accumulated {rotationCount} in {rotationUnits} [DRU_DEGREES, DRU_ROTATIONS, or DRU_HALL_TICKS], since last reset, for this motor.
+
+_______________________
+PUB getPower() : nPower
+
+ Returns the last specified power value [-100 thru +100] for motor (will be zero if the motor is stopped).
+
+________________________________
+PUB getCurrent() : fAmps, fWatts
+
+ Returns the latest current sense values
+
+__________________________
+PUB getMaxSpeed() : nSpeed
+
+ Returns the last specified {maxSpeed}
+
+__________________________________________
+PUB getMaxSpeedForDistance() : nSpeed4dist
+
+ Returns the last specified {maxSpeedForDistance}
+
+_________________________
+PUB getStatus() : eStatus
+
+ Returns status of motor drive state for this motor: enumerated constant: DS_Unknown, DS_MOVING, DS_HOLDING, or DS_OFF
+
+_________________________________
+PUB getDriverState() : eDrvrState
+
+ Return Enum [DCS_*] value representing state of driver
+
+____________________________
+PUB getRawHallTicks() : nPos
+
+ Return the raw driver-maintained tick count
+
+___________________________
+PUB boardIdString() : pZStr
+
+ Return board ID string for this board revision
+
+______________________________
+PUB getBoardType() : eBoardRev
+
+ ID Revision of attached BLDC driver board
+
+______________________
+PUB isReady() : bState
+
+ Return T/F where T means the motor cog is running
+
+________________________
+PUB isStopped() : bState
+
+ Return T/F where T means the motor is stopped
+
+________________________
+PUB isFaulted() : bState
+
+ Return T/F where T means the motor has faulted
+
+_________________________
+PUB isStarting() : bState
+
+ Return T/F where T means the motor is spinning up
+
+________________________
+PUB isTurning() : bState
+
+ Return T/F where T means the motor is rotating
+
+__________________________
+PUB isEmergency() : bState
+
+ Return T/F where T means the motor is emergency-stopped
+
+____________________________
+PUB isFaultSignal() : bState
+
+ Return T/F where T means the motor has faulted
+
+______________________
+PUB clearFaultSignal()
+
+ Reset top-level fault indicator
+
+_____________________________________________________
+PUB validBasePinForChoice(userBasePin) : legalBasePin
+
+ VALIDATE users' base-pin choice returns legalBasePin or INVALID_PIN_BASE
+
+_____________________________________________________
+PUB validVoltageForChoice(userVoltage) : legalVoltage
+
+ VALIDATE users' voltage choice returns legalVoltage or INVALID_VOLTAGE
+
+_______________________________________________
+PUB validMotorForChoice(userMotor) : legalMotor
+
+ VALIDATE users' motor choice returns legalMotor or INVALID_MOTOR
+
+_____________________________________________________
+PUB validDetectModeForChoice(userDetMode) : legalMode
+
+ VALIDATE users' detection mode choice returns legalMode or INVALID_DET_MODE
+
+__________________________________________________________
+PUB hallTicInfoForMotor() : degreesPerTic, ticsPerRotation
+
+ Return numbers for user selected motor (for use by two-wheel-steering object!)
+
+________________
+PUB SyncStatus()
+
+ Wait until both motors are in sync (when configured for synchronization)
+
+
+
+ -------------------------------------------------------------------------------------------------
+  MIT License
+
+  Copyright (c) 2023 Iron Sheep Productions, LLC
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to deal
+  in the Software without restriction, including without limitation the rights
+  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+  copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+  SOFTWARE.
+ =================================================================================================