Abstract data type modelling a spudpole from the manufacturer Ankreo.
The Spudpole class implements an abstract data type which models the key characteristics of a winch-operated spudpole. The ADT uses a state machine to represent spudpole hardware and supports the following states.
- UNKNOWN. The state of the hardware is unknown. This is generally a temporary and transient condition which will be updated as soon as the machine begins to operate.
- DOCKED The spudpole is fully retracted and docked. This state is forced when a call is made to the setDocked() method. Typically this call will be triggered when the host hardware interface detects through a sensor that the pole has been shipped and secured.
- DEPLOYING The spudpole is being deployed. This state is forced when a call is made to the deploy() method. Typically, this call will be triggered when a command for deployment of the pole is received over some external control mechanism.
- RETRIEVING The spudpole is being retrieved. This state is forced when a call is made to the retrieve() method (the transition to RETRIEVING cannot be made from the DOCKED state). Typically, this call will be triggered when a command for retrieval of the pole is received over some external control mechanism.
- STOPPED The spudpole is stopped. This state is forced when a call is made to the Stop() method and the transition will only occur from the DEPLOYING state. Typically, this call will be triggered when either (i) a command to stop pole deployment or retrieval is received over some external control mechanism, or (ii) the host hardware interface detects that the spudpole is fully deployed or that the pole has embedded in terra-firma.
This basic state model is supplemented by a counter which records the extent of winch line deployment in terms of rotations of the winch spool.
Spudpole functionality can be extended by configuring mechanisms to support external control, winch line length calculations and the recording of winch motor runtime.
A Spudpole instance is created in the usual C++ way by simply declaring a variable of the Spudpole type and supplying some arguments which characterise the new object.
#define manufacturerName "Ankreo"
#define modelCode "Type 32"
#define serialCode" "0001"
Spudpole mySpudpole(manufacturerName, modelCode, serialCode);
The following configuration methods set-up and enable optional features.
setControlCallback() forces Spudpole to call an external function each time the state model enters DEPLOYING, RETRIEVING or STOPPED states. The supplied callback function will be called with an argument expressing the required operating state.
void callback(SpudpoleControl action) {
switch (action) {
case STOP: break; // Switch motor off
case DEPLOY: break; // Deploy line
case RETRIEVE: break; // Retrieve line
};
Spudpole mySpudpole(callback);
configureLineMeasurement() enables support for calculating the lenth of line deployed by the winch. Note that this is a calculated measure, not an actual measurement.
// Diameter of the winch spool/drum.
double spoolDiameter = 0.06;
// Diameter of the winch line.
double rodeDiameter = 0.01;
// Nominal number of turns of the winch line across the spool/drum.
unsigned int spoolWidth = 12;
// Number of turns on the winch spool when pole is fully docked.
unsigned int lineTurnsWhenDocked = 60;
mySpudpole.configureLineMeasurement(spoolDiameter, rodeDiameter, spoolWidth, lineTurnsWhenDocked);
The configureRunTimeAccounting() method enables support for recording the total run time of the winch motor.
unsigned long motorRunTime = 0L;
unsigned long timer(SpudpoleTimer action, unsigned long motorRunTime) {
static unsigned long retval = motorRunTime;
static unsigned long timestamp;
switch (mode) {
case START: timestamp = millis(); break;
case STOP: retval += (millis() - timestamp); break;
default: break;
}
return(retval);
}
mySpudpole.configureMotorRuntime(motorRunTime, timer);
The configured instance identifiers can be recovered using three eponymous_get..._ methods.
char* n = mySpudpole.getManufacturerName();
char* m = mySpudpole.getModelCode();
char* s = mySpudpole.getSerialCode();
Machine state is directly modified by the setDocked(), deploy(), retrieve(), stop() (and its alias setStop()) methods each of which immediately asserts the implied state and, with the exception of setDocked(), will call any defined control callback function. A side-effect of setDocked() is to zero the winch rotation counter.
mySpudpole.setDocked()
mySpudpole.deploy();
mySpudpole.retrieve();
mySpudpole.stop();
There are a number of methods which allow interrogation of the current state.
SpudpoleState s = mySpudpole.getState(); // returns an enum value
bool b = mySpudpole.isWorking(); // true if DEPLOYING or RETRIEVING
bool b = mySpudpole.isDocked(); // true if DOCKED
bool b = mySpudpole.isDeployed(); // true if STOPPED
The winch rotation counter can be accessed using a number of functions. The counter is a rotation counter and should be updated once per winch revolution by a strategy that is left to the host application. Note that the counter is reset to zero by a call to setDocked().
The getCounter() method returns the current counter value. The counter can be updated using one of counterIncr(), counterDecr() or counterBump(). Calls to counterIncr() or counterDecr() will only be honoured if the machine state is DEPLOYING or RETRIEVING respectively. A call to counterBump() will increment or decrement the counter value dependent upon the machine state.
unsigned long now = mySpudpole.getCounter();
mySpudpole.counterIncr();
mySpudpole.counterDecr();
mySpudpole.counterBump();
If line measurement has been configureded then the currently deployed length of the winch line in metres can be computed from the current counter value.
double getDeployedLineLength();
If motor runtime accounting has been configured then the currently computed total motor run time in milliseconds can be easily recovered.
unsigned long getMotorRuntime();