fix(dispenser): simplify card preparation and recovery
This commit is contained in:
@@ -41,10 +41,14 @@ type sequenceTiming struct {
|
||||
}
|
||||
|
||||
const (
|
||||
sequencePollInterval = time.Second
|
||||
sequenceRetryAfter = 6 * time.Second
|
||||
sequenceResetWait = 2 * time.Second
|
||||
sequenceTimeout = 16 * time.Second
|
||||
sequencePollInterval = time.Second
|
||||
sequenceShakeAfter = 3 * time.Second
|
||||
sequenceResetWait = 2 * time.Second
|
||||
sequenceTimeout = 32 * time.Second
|
||||
sequenceUncertainWait = 4 * time.Second
|
||||
sequenceMaxShakes = 3
|
||||
deliveryClearanceTimeout = 16 * time.Second
|
||||
deliveryMinimumWait = 2 * time.Second
|
||||
)
|
||||
|
||||
type Client struct {
|
||||
@@ -217,19 +221,22 @@ func (c *Client) handle(req cmdReq) {
|
||||
}
|
||||
}
|
||||
err := cardToEncoderPosition(req.ctx, c.port)
|
||||
log.Infof("FC7 dispatch finished; dispatched=%t error=%v", err == nil, err)
|
||||
c.invalidateStatusCache()
|
||||
req.respCh <- cmdResp{err: err}
|
||||
|
||||
case cmdReset:
|
||||
err := resetDispenser(req.ctx, c.port)
|
||||
log.Infof("RS dispatch finished; dispatched=%t error=%v", err == nil, err)
|
||||
c.invalidateStatusCache()
|
||||
req.respCh <- cmdResp{err: err}
|
||||
|
||||
case cmdOutOfMouth:
|
||||
attempted, err := cardOutOfMouth(req.ctx, c.port)
|
||||
log.Infof("FC0 dispatch finished; ENQ_attempted=%t error=%v", attempted, err)
|
||||
if attempted {
|
||||
c.deliveryPending = true
|
||||
c.deliveryStarted = time.Now()
|
||||
c.deliveryStarted = c.now()
|
||||
log.Info("delivery ENQ attempted; awaiting mechanical clearance")
|
||||
}
|
||||
// A movement command makes any previously cached position unreliable.
|
||||
@@ -243,19 +250,24 @@ func (c *Client) handle(req cmdReq) {
|
||||
|
||||
// deliveryClearance deliberately does not apply encoder-success precedence.
|
||||
func deliveryClearance(status []byte) (bool, error) {
|
||||
if err := validateDispenserStatusData(status); err != nil {
|
||||
class, err := classifyPreparationStatus(status)
|
||||
if err != nil {
|
||||
return false, err
|
||||
}
|
||||
if isCardWellEmpty(status) {
|
||||
if class == positionWellEmpty {
|
||||
return false, ErrCardWellEmpty
|
||||
}
|
||||
if isPreparationMoving(status) {
|
||||
if isPreparationMoving(status) || status[1] == 0x34 {
|
||||
return false, nil
|
||||
}
|
||||
if err := dispenserStatusError(status); err != nil {
|
||||
return false, err
|
||||
return status[3] == 0x30 || status[3] == 0x34, nil
|
||||
}
|
||||
|
||||
func (c *Client) now() time.Time {
|
||||
if c.sequenceTiming.now != nil {
|
||||
return c.sequenceTiming.now()
|
||||
}
|
||||
return status[0] == 0x30 && status[1] == 0x30 && status[3] == 0x30, nil
|
||||
return time.Now()
|
||||
}
|
||||
|
||||
// readWorkerStatus is called only by the serial worker and always reads fresh AP.
|
||||
@@ -264,13 +276,18 @@ func (c *Client) readWorkerStatus(ctx context.Context) ([]byte, error) {
|
||||
if err != nil {
|
||||
return st, err
|
||||
}
|
||||
if err := ctx.Err(); err != nil {
|
||||
return st, err
|
||||
}
|
||||
if c.deliveryPending {
|
||||
class, _ := classifyPreparationStatus(st)
|
||||
log.Infof("delivery clearance AP; class=%s elapsed=%s raw status: % X", class, c.now().Sub(c.deliveryStarted), st)
|
||||
clear, clearanceErr := deliveryClearance(st)
|
||||
if clearanceErr != nil {
|
||||
log.Warnf("delivery clearance failed: %v; %s raw status: % X", clearanceErr, statusDescription(st), st)
|
||||
} else if clear {
|
||||
} else if clear && c.now().Sub(c.deliveryStarted) >= deliveryMinimumWait {
|
||||
c.deliveryPending = false
|
||||
log.Infof("previous delivery cleared after %s; FC7 permitted", time.Since(c.deliveryStarted))
|
||||
log.Infof("previous delivery cleared after %s; FC7 permitted", c.now().Sub(c.deliveryStarted))
|
||||
}
|
||||
}
|
||||
if len(st) == 4 {
|
||||
@@ -408,186 +425,12 @@ func (c *Client) readSequenceStatus(ctx context.Context, operation string) ([]by
|
||||
return status, stockStatus, nil
|
||||
}
|
||||
|
||||
func preparationStatus(operation string, status []byte, allowCombinedFailure bool) (bool, error) {
|
||||
// A confirmed read sensor takes precedence over every other diagnostic.
|
||||
if isAtEncoderPosition(status) {
|
||||
if hasPreparationDiagnostics(status) {
|
||||
log.Warnf(
|
||||
"[%s] card confirmed at encoder with dispenser diagnostics: %s raw status: % X",
|
||||
operation,
|
||||
statusDescription(status),
|
||||
status,
|
||||
)
|
||||
}
|
||||
return true, nil
|
||||
}
|
||||
if err := validateDispenserStatusData(status); err != nil {
|
||||
return false, fmt.Errorf("[%s] %w", operation, err)
|
||||
}
|
||||
if isCardWellEmpty(status) {
|
||||
return false, fmt.Errorf("[%s] %w", operation, ErrCardWellEmpty)
|
||||
}
|
||||
if isPreparationMoving(status) {
|
||||
return false, nil
|
||||
}
|
||||
|
||||
// Some dispenser firmware briefly reports 0x32 ("Preparing card fails")
|
||||
// while the card is still travelling to the encoder. Treat that one
|
||||
// diagnostic as transient during an active preparation sequence and let
|
||||
// pollForEncoderPosition decide encoder success or timeout. Do not mask
|
||||
// independent hard errors reported in the other status bytes.
|
||||
// Combined command rejection is also recoverable before the one retry.
|
||||
if status[0] == 0x32 || (status[0] == 0x36 && allowCombinedFailure) {
|
||||
statusWithoutPrepareFailure := append([]byte(nil), status...)
|
||||
statusWithoutPrepareFailure[0] = 0x30
|
||||
if err := dispenserStatusError(statusWithoutPrepareFailure); err != nil {
|
||||
return false, fmt.Errorf("[%s] %w", operation, err)
|
||||
}
|
||||
|
||||
log.Warnf(
|
||||
"[%s] transient preparation failure (%s); waiting for encoder position, raw status: % X",
|
||||
operation,
|
||||
statusDescription(status),
|
||||
status,
|
||||
)
|
||||
return false, nil
|
||||
}
|
||||
|
||||
if err := dispenserStatusError(status); err != nil {
|
||||
return false, fmt.Errorf("[%s] %w", operation, err)
|
||||
}
|
||||
return false, nil
|
||||
}
|
||||
|
||||
func (c *Client) pollForEncoderPosition(ctx context.Context, operation string) (stockStatus string, resultErr error) {
|
||||
started := c.sequenceTiming.now()
|
||||
recoveryAt := started.Add(sequenceRetryAfter)
|
||||
deadline := started.Add(sequenceTimeout)
|
||||
ctx, cancel := context.WithTimeout(ctx, sequenceTimeout)
|
||||
defer cancel()
|
||||
retried := false
|
||||
resetAttempted := false
|
||||
retryAfterReset := false
|
||||
consecutiveFailures := 0
|
||||
stage := "initial polling"
|
||||
var lastStatus []byte
|
||||
defer func() {
|
||||
if resultErr != nil {
|
||||
log.Warnf("[%s] card preparation failed; stage=%s reset_attempted=%t raw status: % X: %v", operation, stage, resetAttempted, lastStatus, resultErr)
|
||||
}
|
||||
}()
|
||||
|
||||
checkDeadline := func() error {
|
||||
if err := ctx.Err(); err != nil {
|
||||
return fmt.Errorf("[%s] %s: %w", operation, stage, err)
|
||||
}
|
||||
if !c.sequenceTiming.now().Before(deadline) {
|
||||
return fmt.Errorf("[%s] %s: timed out after %s", operation, stage, sequenceTimeout)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
for {
|
||||
if err := checkDeadline(); err != nil {
|
||||
return stockStatus, err
|
||||
}
|
||||
status, currentStockStatus, err := c.readSequenceStatus(ctx, operation)
|
||||
stockStatus = currentStockStatus
|
||||
lastStatus = status
|
||||
if err != nil {
|
||||
return stockStatus, err
|
||||
}
|
||||
if err := checkDeadline(); err != nil {
|
||||
return stockStatus, err
|
||||
}
|
||||
ready, err := preparationStatus(operation, status, !retried || retryAfterReset)
|
||||
if err != nil {
|
||||
return stockStatus, err
|
||||
}
|
||||
if ready {
|
||||
if resetAttempted {
|
||||
log.Infof("[%s] card preparation recovered after reset", operation)
|
||||
}
|
||||
return stockStatus, nil
|
||||
}
|
||||
|
||||
moving := isPreparationMoving(status)
|
||||
prepareFailed := status[0] == 0x32 || status[0] == 0x36
|
||||
if prepareFailed && !moving {
|
||||
consecutiveFailures++
|
||||
} else {
|
||||
consecutiveFailures = 0
|
||||
}
|
||||
if !moving && retryAfterReset {
|
||||
stage = "post-reset FC7"
|
||||
if err := checkDeadline(); err != nil {
|
||||
return stockStatus, err
|
||||
}
|
||||
log.Infof("[%s] reset settle wait completed; retrying card preparation", operation)
|
||||
if err := c.ToEncoder(ctx); err != nil {
|
||||
return stockStatus, fmt.Errorf("[%s] post-reset retry command: %w", operation, err)
|
||||
}
|
||||
retryAfterReset = false
|
||||
stage = "polling after reset and retry"
|
||||
} else if !moving && !retried && !c.sequenceTiming.now().Before(recoveryAt) {
|
||||
if prepareFailed && consecutiveFailures >= 2 {
|
||||
stage = "RS recovery"
|
||||
if err := checkDeadline(); err != nil {
|
||||
return stockStatus, err
|
||||
}
|
||||
retried = true
|
||||
resetAttempted = true
|
||||
log.Warnf("[%s] persistent prepare failure; resetting dispenser, raw status: % X", operation, status)
|
||||
if err := c.Reset(ctx); err != nil {
|
||||
return stockStatus, fmt.Errorf("[%s] reset command: %w", operation, err)
|
||||
}
|
||||
stage = "reset settle"
|
||||
if err := checkDeadline(); err != nil {
|
||||
return stockStatus, err
|
||||
}
|
||||
log.Infof("[%s] reset dispatched; waiting for mechanical settling", operation)
|
||||
wait := sequenceResetWait
|
||||
if remaining := deadline.Sub(c.sequenceTiming.now()); remaining < wait {
|
||||
wait = remaining
|
||||
}
|
||||
if err := c.sequenceTiming.wait(ctx, wait); err != nil {
|
||||
return stockStatus, fmt.Errorf("[%s] reset settle: %w", operation, err)
|
||||
}
|
||||
retryAfterReset = true
|
||||
stage = "post-reset status"
|
||||
continue // Always read fresh physical status before the retry.
|
||||
}
|
||||
if !prepareFailed {
|
||||
stage = "FC7 retry"
|
||||
if err := checkDeadline(); err != nil {
|
||||
return stockStatus, err
|
||||
}
|
||||
retried = true
|
||||
if err := c.ToEncoder(ctx); err != nil {
|
||||
return stockStatus, fmt.Errorf("[%s] retry command: %w", operation, err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if err := checkDeadline(); err != nil {
|
||||
return stockStatus, err
|
||||
}
|
||||
wait := sequencePollInterval
|
||||
if remaining := deadline.Sub(c.sequenceTiming.now()); remaining < wait {
|
||||
wait = remaining
|
||||
}
|
||||
if err := c.sequenceTiming.wait(ctx, wait); err != nil {
|
||||
return stockStatus, fmt.Errorf("[%s] %s: %w", operation, stage, err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// waitForDeliveryClearance reuses the first clear AP as the initial preparation sample.
|
||||
// Its bounded window is separate from recovery, which starts after initial FC7.
|
||||
// Its bounded window is separate from subsequent preparation and recovery.
|
||||
func (c *Client) waitForDeliveryClearance(ctx context.Context, operation string) (status []byte, stock string, resultErr error) {
|
||||
ctx, cancel := context.WithTimeout(ctx, sequenceTimeout)
|
||||
ctx, cancel := context.WithTimeout(ctx, deliveryClearanceTimeout)
|
||||
defer cancel()
|
||||
deadline := c.sequenceTiming.now().Add(sequenceTimeout)
|
||||
deadline := c.sequenceTiming.now().Add(deliveryClearanceTimeout)
|
||||
var lastStatus []byte
|
||||
defer func() {
|
||||
if resultErr != nil {
|
||||
@@ -634,26 +477,143 @@ func (c *Client) waitForDeliveryClearance(ctx context.Context, operation string)
|
||||
}
|
||||
}
|
||||
|
||||
func (c *Client) prepareCardAtEncoder(ctx context.Context, operation string) (string, error) {
|
||||
status, stockStatus, err := c.waitForDeliveryClearance(ctx, operation)
|
||||
func (c *Client) prepareCardAtEncoder(parent context.Context, operation string) (stock string, resultErr error) {
|
||||
status, stock, err := c.waitForDeliveryClearance(parent, operation)
|
||||
if err != nil {
|
||||
return stockStatus, err
|
||||
return stock, err
|
||||
}
|
||||
ready, err := preparationStatus(operation, status, true)
|
||||
if err != nil {
|
||||
return stockStatus, err
|
||||
started := c.now()
|
||||
deadline := started.Add(sequenceTimeout)
|
||||
ctx, cancel := context.WithTimeoutCause(parent, sequenceTimeout, ErrPreparationExhausted)
|
||||
defer cancel()
|
||||
shakes := 0
|
||||
stage := "initial status"
|
||||
var lastFC7, uncertainSince time.Time
|
||||
var previous preparationClass
|
||||
defer func() {
|
||||
log.Infof("[%s] preparation finished; stage=%s shakes=%d elapsed=%s raw status: % X error=%v", operation, stage, shakes, c.now().Sub(started), status, resultErr)
|
||||
}()
|
||||
checkDeadline := func() error {
|
||||
if err := parent.Err(); err != nil {
|
||||
return err
|
||||
}
|
||||
if !c.now().Before(deadline) || errors.Is(context.Cause(ctx), ErrPreparationExhausted) {
|
||||
return ErrPreparationExhausted
|
||||
}
|
||||
return ctx.Err()
|
||||
}
|
||||
if ready {
|
||||
return stockStatus, nil
|
||||
wait := func(duration time.Duration) error {
|
||||
if err := checkDeadline(); err != nil {
|
||||
return err
|
||||
}
|
||||
if remaining := deadline.Sub(c.now()); remaining < duration {
|
||||
duration = remaining
|
||||
}
|
||||
if err := c.sequenceTiming.wait(ctx, duration); err != nil {
|
||||
if deadlineErr := checkDeadline(); deadlineErr != nil {
|
||||
return deadlineErr
|
||||
}
|
||||
return err
|
||||
}
|
||||
return checkDeadline()
|
||||
}
|
||||
|
||||
if err := c.ToEncoder(ctx); err != nil {
|
||||
return stockStatus, fmt.Errorf("[%s] to encoder: %w", operation, err)
|
||||
sendFC7 := func() error {
|
||||
stage = "FC7 dispatch"
|
||||
if err := checkDeadline(); err != nil {
|
||||
return err
|
||||
}
|
||||
err := c.ToEncoder(ctx)
|
||||
if deadlineErr := checkDeadline(); deadlineErr != nil {
|
||||
return deadlineErr
|
||||
}
|
||||
if err != nil {
|
||||
return fmt.Errorf("[%s] FC7 dispatch: %w", operation, err)
|
||||
}
|
||||
lastFC7 = c.now()
|
||||
log.Infof("[%s] FC7 dispatched; shake=%d elapsed=%s", operation, shakes, lastFC7.Sub(started))
|
||||
return nil
|
||||
}
|
||||
for {
|
||||
if err := checkDeadline(); err != nil {
|
||||
return stock, err
|
||||
}
|
||||
class, err := classifyPreparationStatus(status)
|
||||
if err != nil {
|
||||
return stock, err
|
||||
}
|
||||
log.Infof("[%s] fresh AP; class=%s previous=%s elapsed=%s shake=%d raw status: % X", operation, class, previous, c.now().Sub(started), shakes, status)
|
||||
previous = class
|
||||
switch class {
|
||||
case encoderConfirmed:
|
||||
stage = "encoder sensor handoff"
|
||||
return stock, checkDeadline()
|
||||
case positionWellEmpty:
|
||||
stage = "empty"
|
||||
return stock, ErrCardWellEmpty
|
||||
}
|
||||
if lastFC7.IsZero() {
|
||||
if err := sendFC7(); err != nil {
|
||||
return stock, err
|
||||
}
|
||||
} else if class == positionNoCard && c.now().Sub(lastFC7) >= sequenceShakeAfter {
|
||||
uncertainSince = time.Time{}
|
||||
if shakes == sequenceMaxShakes {
|
||||
stage = "three shakes exhausted"
|
||||
return stock, ErrPreparationExhausted
|
||||
}
|
||||
shakes++
|
||||
stage = "RS dispatch"
|
||||
if err := checkDeadline(); err != nil {
|
||||
return stock, err
|
||||
}
|
||||
err := c.Reset(ctx)
|
||||
if deadlineErr := checkDeadline(); deadlineErr != nil {
|
||||
return stock, deadlineErr
|
||||
}
|
||||
if err != nil {
|
||||
return stock, fmt.Errorf("[%s] RS dispatch: %w", operation, err)
|
||||
}
|
||||
stage = "reset settling"
|
||||
log.Infof("[%s] RS dispatched; shake=%d settling=%s", operation, shakes, sequenceResetWait)
|
||||
if err := wait(sequenceResetWait); err != nil {
|
||||
return stock, err
|
||||
}
|
||||
log.Infof("[%s] reset settle wait completed; shake=%d", operation, shakes)
|
||||
if err := sendFC7(); err != nil {
|
||||
return stock, err
|
||||
}
|
||||
} else {
|
||||
if class == positionUncertain {
|
||||
if uncertainSince.IsZero() {
|
||||
uncertainSince = c.now()
|
||||
}
|
||||
if c.now().Sub(uncertainSince) >= sequenceUncertainWait {
|
||||
stage = "uncertain position handoff"
|
||||
return stock, checkDeadline()
|
||||
}
|
||||
} else {
|
||||
uncertainSince = time.Time{}
|
||||
}
|
||||
stage = "polling"
|
||||
if err := wait(sequencePollInterval); err != nil {
|
||||
return stock, err
|
||||
}
|
||||
}
|
||||
stage = "fresh AP"
|
||||
if err := checkDeadline(); err != nil {
|
||||
return stock, err
|
||||
}
|
||||
status, stock, err = c.readSequenceStatus(ctx, operation)
|
||||
if deadlineErr := checkDeadline(); deadlineErr != nil {
|
||||
return stock, deadlineErr
|
||||
}
|
||||
if err != nil {
|
||||
return stock, err
|
||||
}
|
||||
}
|
||||
return c.pollForEncoderPosition(ctx, operation)
|
||||
}
|
||||
|
||||
// PrepareCurrentCard authoritatively places the card to be encoded at the encoder.
|
||||
// PrepareCurrentCard grants one encoder opportunity after bounded physical preparation.
|
||||
func (c *Client) PrepareCurrentCard(ctx context.Context) (string, error) {
|
||||
return c.prepareCardAtEncoder(ctx, "PrepareCurrentCard")
|
||||
}
|
||||
@@ -668,15 +628,42 @@ func (c *Client) DeliverCurrentCard(ctx context.Context) (string, error) {
|
||||
return "", nil
|
||||
}
|
||||
|
||||
// BeginPrepareNextCard starts moving the next card to the encoder without waiting for readiness.
|
||||
// BeginPrepareNextCard waits for delivery clearance and dispatches FC7 once,
|
||||
// without waiting for encoder readiness.
|
||||
func (c *Client) BeginPrepareNextCard(ctx context.Context) error {
|
||||
if err := c.ToEncoder(ctx); err != nil {
|
||||
return fmt.Errorf("[BeginPrepareNextCard] to encoder: %w", err)
|
||||
ctx, cancel := context.WithTimeout(ctx, deliveryClearanceTimeout)
|
||||
defer cancel()
|
||||
deadline := c.now().Add(deliveryClearanceTimeout)
|
||||
for {
|
||||
if err := ctx.Err(); err != nil {
|
||||
return err
|
||||
}
|
||||
if !c.now().Before(deadline) {
|
||||
return context.DeadlineExceeded
|
||||
}
|
||||
// The worker checks fresh AP while delivery is pending and dispatches
|
||||
// FC7 only once clear, within the same ownership boundary.
|
||||
err := c.ToEncoder(ctx)
|
||||
if !errors.Is(err, errDeliveryPending) {
|
||||
if err != nil {
|
||||
return fmt.Errorf("[BeginPrepareNextCard] to encoder: %w", err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
wait := sequencePollInterval
|
||||
if remaining := deadline.Sub(c.now()); remaining < wait {
|
||||
wait = remaining
|
||||
}
|
||||
if wait <= 0 {
|
||||
return context.DeadlineExceeded
|
||||
}
|
||||
if err := c.sequenceTiming.wait(ctx, wait); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// PrepareNextCard places a new card at the encoder for a later issuance attempt.
|
||||
// PrepareNextCard runs the same bounded physical preparation for a later issuance attempt.
|
||||
func (c *Client) PrepareNextCard(ctx context.Context) (string, error) {
|
||||
return c.prepareCardAtEncoder(ctx, "PrepareNextCard")
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user