Serial Wombat Arduino Library

Loading...
Searching...
No Matches
Public Member Functions | Public Attributes | List of all members
GripServo Class Reference

A class representing a servo output and an Allegro ACS712 5A current sensor connected to a SW8B Analog input on a PCB0031 Grip board. More...

`#include <PCB0031_Grip.h>`

Inheritance diagram for GripServo:
[legend]
Collaboration diagram for GripServo:
[legend]

## Public Member Functions
| GripServo (SerialWombatChip &serialWombatChip)
| Constructor for the GripServo Class.
int16_t | begin (byte pin, bool reverse=false)
| Initialize a GripServo on the specified pin, and its associated sensor on pin + 4.
void | calibrateServoRange (uint16_t expectedCurrentRise=400, uint16_t calibrationStartPosition=0x8000)
| Sweep a servo across its range measuring current to determine endstops.
void | grip (uint16_t gripStrength=0, uint16_t slowIncrement=100, uint16_t fastSlowThreshold=350, uint16_t fastIncrement=3500)
| Close a servo based gripper with a specified force.
void | release ()
| Disable the grip control algorithm and move the servo to the smallest non-stall position.
bool | objectPresent (uint16_t divisor=50)
| Reports if an object is in the gripper based on stop position of servo.
void | calibrateGripper (bool reverse=false, uint16_t rangeConstant=49152)
| A single calibration call that will fully calibrate a gripper.
Public Member Functions inherited from SerialWombatServo_18AB
| SerialWombatServo_18AB (SerialWombatChip &serialWombat)
uint8_t | pin ()
| Facilitates inheritance.
uint8_t | swPinModeNumber ()
| Facilitates inheritance.
Public Member Functions inherited from SerialWombatServo
| SerialWombatServo (SerialWombatChip &sw)
| Constructor for the SerialWombatServo Class.
void | attach (uint8_t pin, bool reverse)
| Initialize a servo on the specified pin.
void | attach (uint8_t pin, uint16_t min=544, uint16_t max=2400, bool reverse=false)
| Initialize a servo on the specified pin.
void | write (uint8_t angle)
| Writes a value to the servo.
void | write16bit (uint16_t position)
| Writes a 16 bit value to the servo.
uint8_t | read (void)
| returns the last position of the servo scaled to a number from 0 to 180.
Public Member Functions inherited from SerialWombatPin
| SerialWombatPin (SerialWombatChip &serialWombatChip)
| Instantiates a Serial Wombat Pin.
| SerialWombatPin (SerialWombatChip &serialWombatChip, uint8_t pin)
| Instantiates a Serial Wombat Pin.
uint16_t | readPublicData ()
| Read the 16 Bit public data associated with this pin.
void | pinMode (uint8_t mode, bool pullDown=false, bool openDrain=false)
| Set pin to INPUT or OUTPUT, with options for pull Ups and open Drain settings.
void | digitalWrite (uint8_t val)
| Set output pin High or Low.
int | digitalRead ()
| Reads the state of the Pin.
uint16_t | writePublicData (uint16_t value)
| Write a 16 bit value to this pin.
uint8_t | pin ()
| Returns the current SW pin number. Used primarily for virtual calls by derived classes.
uint8_t | swPinModeNumber ()
| Returns the Mode number. Used primarily by derived classes to populate packet data.
int16_t | initPacketNoResponse (uint8_t packetNumber, uint8_t param0=0x55, uint8_t param1=0x55, uint8_t param2=0x55, uint8_t param3=0x55, uint8_t param4=0x55)
int16_t | initPacketNoResponse (uint8_t packetNumber, uint16_t param0=0x55, uint8_t param1=0x55, uint8_t param2=0x55, uint8_t param3=0x55)
int16_t | initPacketNoResponse (uint8_t packetNumber, uint16_t param0, uint16_t param1, uint8_t param2=0x55)
int16_t | disable ()
| Disables the pin mode (if applicable)
int16_t | enablePullup (bool enabled)
| Enables the weak pull up on a pin. Implemented on SW18AB and SW8B only.
int16_t | enablePulldown (bool enabled)
| Enables the weak pull down on a pin. Implemented on SW18AB and SW8B only.
int16_t | enableOpenDrain (bool enabled)
| Enables open drain mode on a pin. Implemented on SW18AB and SW8B only.
int16_t | forceDMA (bool enabled)
| Forces use of DMA instead of hardware timing resources on SW18AB.
void | setPinNumberForTesting (uint8_t pin)
| A function designed for testing only. May have unpredictable results if used in real time. Not intended for general use.
Public Member Functions inherited from SerialWombatAbstractScaledOutput
| SerialWombatAbstractScaledOutput (SerialWombatChip &sw)
| Constructor for the SerialWombatAbstractScaledOutput Class.
int16_t | writeTimeout (uint16_t timeout_mS, uint16_t timeoutOutputValue)
| Enable a timeout value which will cause the output to go to a default value if not updated.
int16_t | writeScalingEnabled (bool enabled, uint8_t sourcePin)
| Enable scaling and set which pin or public data is used as the input source.
int16_t | writeInputScaling (uint16_t inputMin, uint16_t inputMax)
| Scale incoming values to a range of 0 to 65535.
int16_t | writeOutputScaling (uint16_t outputMin, uint16_t outputMax)
| Reduces the output range from 0 to 65535 to user specified range.
int16_t | writeScalingInvertedInput (bool inverted)
| if enabled subtract the input value from 65535 before doing any other processing.
int16_t | writeScalingTargetValue (uint16_t target)
| The target input value for PID control.
int16_t | writeRateControl (Period samplePeriod, uint16_t maximumChangecounts, uint16_t maximumDecrementCounts=0)
| Controls how fast an ouput can change in counts.
int16_t | write1stOrderFiltering (Period samplePeriod, uint16_t filterConstant)
| Controls how fast an ouput can change based on filtering.
int16_t | writeHysteresis (uint16_t lowLimit, uint16_t lowOutputValue, uint16_t highLimit, uint16_t highOutputValue, uint16_t initialOutputValue)
| Controls the output based on hystersis control.
int16_t | writeRamp (uint16_t slowIncrement, uint16_t incrementThreshold, uint16_t fastIncrement, Period samplePeriod, RampMode rampMode)
| Configure the scaled output block into Ramp control mode.
int16_t | writePID (uint16_t kp, uint16_t ki, uint16_t kd, uint16_t target, Period samplePeriod, uint8_t targetPin=255, bool biDirectional=false)
| Configure the scaled output block into PID control mode.
uint16_t | readLastOutputValue ()
| Request Last Output Value.
int16_t | writeScalingTargetValueResetIntegrator (uint16_t target)
int32_t | PIDGetLastError ()
int32_t | PIDGetLastIntegrator ()
int32_t | PIDGetLastIntegratorEffort ()
int32_t | PIDGetLastProportionalEffort ()
int32_t | PIDGetLastDerivativeEffort ()
int32_t | PIDGetLastEffort ()
uint16_t | ReadLastTarget ()
int16_t | Enable2DLookupOutputScaling (uint16_t IndexInUserMemory)
| Set Up 2D Lookup Output Scaling.

## Public Attributes
GripACS712 | sensor
uint16_t | calibratedMinPosition = 0
| The position at which the least current was pulled during calibration.
uint16_t | calibratedMaxPosition = 65535
| The highest position at which relatively low current was pulled during calibration.
uint16_t | calibratedMinCurrent = 0
| The lowest observed current during calibration.
uint16_t | calibratedMaxCurrent = 65535
| The highest observed current during calibration.

## Additional Inherited Members
Public Types inherited from SerialWombatAbstractScaledOutput
enum | Period { PERIOD_1mS = 0 , PERIOD_2mS = 1 , PERIOD_4mS = 2 , PERIOD_8mS = 3 , PERIOD_16mS = 4 , PERIOD_32mS = 5 , PERIOD_64mS = 6 , PERIOD_128mS = 7 , PERIOD_256mS = 8 , PERIOD_512mS = 9 , PERIOD_1024mS = 10 }
enum | RampMode { RAMP_MODE_BOTH = 0 , RAMP_MODE_INCREMENT = 1 , RAMP_MODE_DECREMENT = 2 }
Protected Member Functions inherited from SerialWombatServo
void | initializeServo ()
Protected Attributes inherited from SerialWombatServo
uint16_t | _position = 0
uint16_t | _min = 544
uint16_t | _max = 2400
bool | _reverse = false
Protected Attributes inherited from SerialWombatPin
uint8_t | _pin = 255
SerialWombatChip & | _sw
uint8_t | _pinMode = 0

## Detailed Description

A class representing a servo output and an Allegro ACS712 5A current sensor connected to a SW8B Analog input on a PCB0031 Grip board.

The GripServo class is a child class of SerialWombatServo_18AB. It has all of the same methods. It adds a GripACS712 named sensor which corresponds to the sensor attached to that servo, allowing a single class to represent both the servo and its associated sensor.

This class includes methods for automatically determinging the range of motion of a servo based mechanism based on current draw, and methods for automatically gripping and releasing an object with force feedback when a servo based gripping mechanism is used.

A Tutorial video is also avaialble:

https://youtu.be/TODO

Definition at line 139 of file PCB0031_Grip.h.

## Constructor & Destructor Documentation

## ◆ GripServo()

GripServo::GripServo | ( | SerialWombatChip & | serialWombatChip | ) |
| inline

Constructor for the GripServo Class.

Parameters

  serialWombatChip | A reference to a previously declared SerialWombatChip to which the Servo is connected.

Definition at line 147 of file PCB0031_Grip.h.

## Member Function Documentation

## ◆ begin()

int16_t GripServo::begin | ( | byte | pin,
|  | bool | reverse = false )
| inline

Initialize a GripServo on the specified pin, and its associated sensor on pin + 4.

This function must be called after the SerialWombatChip instance specified in the constructor has been initialized with a begin call.

Parameters

  pin | The Serial Wombat pin to set. Valid values are 4-7 as those pins are ACS712 pins on the grip board
  reverse | Whether the attached servo should be reversed

Returns
  Returns a negative number indicating an error code, or a non negative number indicating success

Definition at line 163 of file PCB0031_Grip.h.

## ◆ calibrateGripper()

void GripServo::calibrateGripper | ( | bool | reverse = false,
|  | uint16_t | rangeConstant = 49152 )
| inline

A single calibration call that will fully calibrate a gripper.

This function must be called after the begin call for the GripServo is called.

This function will iterate over the entire range of motion of the servo mapping current readings, and determinging end stops and gripper current ranges.

Warning
  This function will attempt to move the servo through its full range of motion. Do not use this servo if your physical assembly can be damaged by attempts to move the servo through its full 180 degrees of motion

Parameters

  reverse | Reverse the direction of the servo.
  rangeConstant | A constant to scale the range of motion of the servo. The default value works well for an SG90 servo.

This is a blocking function that takes a few seconds to complete.

Definition at line 329 of file PCB0031_Grip.h.

## ◆ calibrateServoRange()

void GripServo::calibrateServoRange | ( | uint16_t | expectedCurrentRise = 400,
|  | uint16_t | calibrationStartPosition = 0x8000 )
| inline

Sweep a servo across its range measuring current to determine endstops.

This function must be called after the begin call for the GripServo is called.

Parameters

  expectedCurrentRise | A threshold to help indicate the difference in current in counts of a servo that has reached its position vs one that is stalled. Default value works good for an SG90
  calibrationStartPosition | A position in 16 bit counts where the servo should be able to move freely. it will then move in both directions from this point looking for an endstop.

Definition at line 195 of file PCB0031_Grip.h.

## ◆ grip()

void GripServo::grip | ( | uint16_t | gripStrength = 0,
|  | uint16_t | slowIncrement = 100,
|  | uint16_t | fastSlowThreshold = 350,
|  | uint16_t | fastIncrement = 3500 )
| inline

Close a servo based gripper with a specified force.

This function must be called after the begin call for the GripServo is called and after calibration

Default values work well for an SG90 servo with a rack and pinion grabber. Other gripper servo models and configurations may need differng calibration constants to achieve a predicable and quick grip.

Parameters

  gripStrength | The proportion of current difference between minimum and maximum observed current that the control algorithm should attempt to achieve. A fraction of 65535. A default value of 0 corresponds to 75%
  slowIncrement | The amount of change in servo counts when the servo is near the target current. Based on the ScaledOutput ramp control algoritm. Used to grip firmly with minimal vibration
  fastSlowThreshold | If the measured current is within this number of counts of the target, slowIncrement is used. Otherwise fast increment.
  fastIncrement | The amount of change in servo counts when the servo is far from the target current. Used to close quickly.

Definition at line 241 of file PCB0031_Grip.h.

## ◆ objectPresent()

bool GripServo::objectPresent | ( | uint16_t | divisor = 50 | ) |
| inline

Reports if an object is in the gripper based on stop position of servo.

This function uses circumstantial evidence to determine if an object is in the gripper. If the control algorithm stops the gripper closing before the close position then it is likely an object is in the gripper. The amount of difference between the closed calibration and current position which represents a positive object detection is configurable.

This function must be called after the begin call for the GripServo is called and after calibration, and after grip.

Parameters

  divisor | A divisor of the difference between open and closed calibration points. If the stop position is more than this amount from closed, and object is considered detected. Increasing this value makes it more likely that small objects will be detected, but also more likely that false positive detections will occur.

Sufficent time must be given after grip is called to allow the gripper to reach steady state. True will be returned if the gripper is still converging on its endpoint.

Returns
  Returns true if an object is detected.

Definition at line 308 of file PCB0031_Grip.h.

## ◆ release()

void GripServo::release | ( |  | ) |
| inline

Disable the grip control algorithm and move the servo to the smallest non-stall position.

This function must be called after the begin call for the GripServo is called and after calibration

Definition at line 274 of file PCB0031_Grip.h.

## Member Data Documentation

## ◆ calibratedMaxCurrent

uint16_t GripServo::calibratedMaxCurrent = 65535

The highest observed current during calibration.

Definition at line 184 of file PCB0031_Grip.h.

## ◆ calibratedMaxPosition

uint16_t GripServo::calibratedMaxPosition = 65535

The highest position at which relatively low current was pulled during calibration.

Definition at line 176 of file PCB0031_Grip.h.

## ◆ calibratedMinCurrent

uint16_t GripServo::calibratedMinCurrent = 0

The lowest observed current during calibration.

Definition at line 180 of file PCB0031_Grip.h.

## ◆ calibratedMinPosition

uint16_t GripServo::calibratedMinPosition = 0

The position at which the least current was pulled during calibration.

Definition at line 172 of file PCB0031_Grip.h.

## ◆ sensor

GripACS712 GripServo::sensor

Definition at line 150 of file PCB0031_Grip.h.