fix(dispenser): recover stuck card preparation with reset

This commit is contained in:
2026-09-24 15:07:40 +01:00
parent aeb86f55b9
commit 4dfe139c3b
5 changed files with 396 additions and 35 deletions
+114 -31
View File
@@ -17,6 +17,7 @@ const (
cmdStatus cmdType = iota
cmdToEncoder
cmdOutOfMouth
cmdReset
)
type cmdReq struct {
@@ -38,7 +39,8 @@ type sequenceTiming struct {
const (
sequencePollInterval = time.Second
sequenceRetryAfter = 6 * time.Second
sequenceTimeout = 12 * time.Second
sequenceResetWait = 2 * time.Second
sequenceTimeout = 16 * time.Second
)
type Client struct {
@@ -205,6 +207,11 @@ func (c *Client) handle(req cmdReq) {
c.invalidateStatusCache()
req.respCh <- cmdResp{err: err}
case cmdReset:
err := resetDispenser(c.port)
c.invalidateStatusCache()
req.respCh <- cmdResp{err: err}
case cmdOutOfMouth:
err := cardOutOfMouth(c.port)
// A movement command makes any previously cached position unreliable.
@@ -262,6 +269,12 @@ func (c *Client) ToEncoder(ctx context.Context) error {
return err
}
// Reset dispatches RS through the port owner; acceptance does not imply mechanical completion.
func (c *Client) Reset(ctx context.Context) error {
_, err := c.do(ctx, cmdReset)
return err
}
func (c *Client) OutOfMouth(ctx context.Context) error {
_, err := c.do(ctx, cmdOutOfMouth)
return err
@@ -326,7 +339,7 @@ func (c *Client) readSequenceStatus(ctx context.Context, operation string) ([]by
return status, stockStatus, nil
}
func preparationStatus(operation string, status []byte) (bool, error) {
func preparationStatus(operation string, status []byte, allowCombinedFailure bool) (bool, error) {
if len(status) != 4 {
return false, fmt.Errorf("[%s] %w", operation, validateDispenserStatusData(status))
}
@@ -356,7 +369,8 @@ func preparationStatus(operation string, status []byte) (bool, error) {
// diagnostic as transient during an active preparation sequence and let
// pollForEncoderPosition decide success (0x33) or timeout. Do not mask
// independent hard errors reported in the other status bytes.
if status[0] == 0x32 {
// 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 {
@@ -364,8 +378,9 @@ func preparationStatus(operation string, status []byte) (bool, error) {
}
log.Warnf(
"[%s] transient Preparing card fails; waiting for encoder position, raw status: % X",
"[%s] transient preparation failure (%s); waiting for encoder position, raw status: % X",
operation,
statusDescription(status),
status,
)
return false, nil
@@ -377,57 +392,125 @@ func preparationStatus(operation string, status []byte) (bool, error) {
return false, nil
}
func (c *Client) pollForEncoderPosition(
ctx context.Context,
operation string,
retryCommand func(context.Context) error,
) (string, error) {
func (c *Client) pollForEncoderPosition(ctx context.Context, operation string) (stockStatus string, resultErr error) {
started := c.sequenceTiming.now()
halfway := started.Add(sequenceRetryAfter)
recoveryAt := started.Add(sequenceRetryAfter)
deadline := started.Add(sequenceTimeout)
ctx, cancel := context.WithTimeout(ctx, sequenceTimeout)
defer cancel()
retried := false
stockStatus := ""
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 := ctx.Err(); err != nil {
return stockStatus, fmt.Errorf("[%s] %w", operation, err)
if err := checkDeadline(); err != nil {
return stockStatus, err
}
now := c.sequenceTiming.now()
if !now.Before(deadline) {
return stockStatus, fmt.Errorf("[%s] timed out after %s", operation, sequenceTimeout)
}
status, currentStockStatus, err := c.readSequenceStatus(ctx, operation)
stockStatus = currentStockStatus
lastStatus = status
if err != nil {
return stockStatus, err
}
ready, err := preparationStatus(operation, status)
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
}
now = c.sequenceTiming.now()
if !now.Before(deadline) {
return stockStatus, fmt.Errorf("[%s] timed out after %s", operation, sequenceTimeout)
moving := isPreparationMoving(status)
prepareFailed := status[0] == 0x32 || status[0] == 0x36
if prepareFailed && !moving {
consecutiveFailures++
} else {
consecutiveFailures = 0
}
if retryCommand != nil && !retried && !now.Before(halfway) {
if err := retryCommand(ctx); err != nil {
return stockStatus, fmt.Errorf("[%s] retry command: %w", operation, err)
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)
}
}
retried = true
}
if err := checkDeadline(); err != nil {
return stockStatus, err
}
wait := sequencePollInterval
if remaining := deadline.Sub(now); remaining < wait {
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] %w", operation, err)
return stockStatus, fmt.Errorf("[%s] %s: %w", operation, stage, err)
}
}
}
@@ -437,7 +520,7 @@ func (c *Client) prepareCardAtEncoder(ctx context.Context, operation string) (st
if err != nil {
return stockStatus, err
}
ready, err := preparationStatus(operation, status)
ready, err := preparationStatus(operation, status, true)
if err != nil {
return stockStatus, err
}
@@ -448,7 +531,7 @@ func (c *Client) prepareCardAtEncoder(ctx context.Context, operation string) (st
if err := c.ToEncoder(ctx); err != nil {
return stockStatus, fmt.Errorf("[%s] to encoder: %w", operation, err)
}
return c.pollForEncoderPosition(ctx, operation, c.ToEncoder)
return c.pollForEncoderPosition(ctx, operation)
}
// PrepareCurrentCard authoritatively places the card to be encoded at the encoder.