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

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)

int16_t	write1stOrderFiltering (Period sampleRate, uint16_t filterConstant)

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

sw	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 )

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.

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

Definition at line 328 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.

Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ GripServo()

Member Function Documentation

◆ begin()

◆ calibrateGripper()

◆ calibrateServoRange()

◆ grip()

◆ objectPresent()

◆ release()

Member Data Documentation

◆ calibratedMaxCurrent

◆ calibratedMaxPosition

◆ calibratedMinCurrent

◆ calibratedMinPosition

◆ sensor