toro/services.cabcard.toro/ToroClient/ensureDeviceReady

ensureDeviceReady

fun ensureDeviceReady(onStateChanged: (DeviceSetupState) -> Unit, onManualEccSigningRequired: (csr: ByteArray) -> Unit = {}, onSuccess: () -> Unit, onError: (ToroException) -> Unit)

Ensures the selected device is in a Toro-compatible state: resets OS and MPI to the required versions if needed, then checks for and applies any pending TMS updates (ECC certificate signing, key injection, configuration).

Safe to re-run — call it when first pairing a reader and again on every app launch. Steps that are already satisfied (e.g. device already on the required OS/MPI) are skipped, so on a healthy device the only unavoidable work is a StatusReport to confirm there are no pending TMS updates. The onStateChanged callback is invoked throughout so the integrating application can surface appropriate messaging to the end user.

TEST devices and ECC signing: the TMS has no CSR signing service for TEST devices. When a TEST device needs its ECC terminal certificate signed, setup generates the CSR on the device and then halts at DeviceSetupState.MANUAL_ECC_SIGNING_REQUIRED, delivering the CSR bytes via onManualEccSigningRequired. Have the CSR signed out-of-band, install the result via installEccTerminalCert, then call this again to complete provisioning. The CSR is persisted on the device and reused, so re-running returns the same CSR until the certificate is installed. This is a development-only concern: PROD devices are provisioned end-to-end by the TMS and never reach this state. Kotlin callers can omit onManualEccSigningRequired (it defaults to a no-op); the Java DeviceSetupListener overload requires it but it can be left empty.

Parameters

onStateChanged

Invoked on the main thread when the setup phase changes.

onManualEccSigningRequired

Invoked on the main thread (TEST devices only) with the raw CSR bytes when manual ECC signing is required. Setup halts after this; no onSuccess/onError. Defaults to a no-op, so PROD-only integrations can omit it.

onSuccess

Invoked on the main thread when setup completes successfully.

onError

Invoked on the main thread if setup fails.

fun ensureDeviceReady(forceSoftwareReset: Boolean, onStateChanged: (DeviceSetupState) -> Unit, onManualEccSigningRequired: (csr: ByteArray) -> Unit = {}, onSuccess: () -> Unit, onError: (ToroException) -> Unit)
fun ensureDeviceReady(listener: DeviceSetupListener, forceSoftwareReset: Boolean)

When forceSoftwareReset is true, attempts to reinstall both MPI and OS even if their versions already match, then handles pending TMS updates as usual.

Checks after each reboot verify the reported versions. If a version already matched, these checks cannot distinguish a successful reinstall from a reboot without applying the package; onSuccess does not confirm that the package was reapplied.

@JvmName(name = "ensureDeviceReady")
fun ensureDeviceReady(listener: DeviceSetupListener)

Java-friendly version of ensureDeviceReady driven by a DeviceSetupListener instead of Kotlin function-type callbacks. See ensureDeviceReady for full behaviour.

Parameters

listener

The listener notified of setup progress, completion, errors and (TEST devices only) manual ECC signing. All callbacks are invoked on the main thread.