Device Setup & Readiness

a miura reader must be in a known good state before it can transact on the os and mpi versions the sdk supports, with security keys loaded, its ecc terminal certificate signed and installed, and its configuration current all of this is coordinated by a single entry point ensuredeviceready() ensuring the device is ready to transact ensuredeviceready() brings the selected device into a toro compatible state in one call it will, as needed reset the reader to the sdk's required mpi version reset the reader to the sdk's required os version reconnect to the reader after any reboot triggered by the above check the tms for pending updates sign and install the ecc terminal certificate inject security keys (sred / pin) apply pending configuration updates toro ensuredeviceready( onstatechanged = { state > log d(tag, "device setup $state") // drive end user messaging from `state` }, onsuccess = { log d(tag, "device is ready") }, onerror = { error > log e(tag, "device setup failed", error) } // onmanualeccsigningrequired is optional in kotlin (defaults to a no op) and is // test device only, so it is omitted here see "manual ecc signing" below )toro ensuredeviceready(new devicesetuplistener() { @override public void onstatechanged(@nonnull devicesetupstate state) { // drive end user messaging from `state` } @override public void onsuccess() { // device is ready } @override public void onerror(@nonnull toroexception error) { // device setup failed } @override public void onmanualeccsigningrequired(@nonnull byte\[] csr) { // test devices only — leave empty in production see "manual ecc signing" below } }); safe to re run ensuredeviceready() is safe to call repeatedly steps that are already satisfied are skipped, so it only does the work the device actually needs if the device is already on the correct os and mpi, has its keys and certificate, and has no pending tms updates, no changes are made to the device (the tms status check still runs each time to determine that) because of this, you should call it both when first pairing a new reader, and on every app launch (and/or whenever a device is selected) on a healthy device the only unavoidable work is a single statusreport to the tms to confirm there are no pending updates which os / mpi versions? ensuredeviceready() targets the specific os and mpi versions that the current toro sdk release is built and tested against the values the sdk requires are exposed as constants on miuradeviceinfo ( miuradeviceinfo required os version and miuradeviceinfo required mpi version ), which indicate which mpi and os that sdk release is designed for the osversionok / mpiversionok fields of baselinestatus are derived from them tracking progress devicesetupstate the onstatechanged callback fires on the main thread each time setup moves to a new phase, with a devicesetupstate value use it to show appropriate messaging to the operator and cardholder automatic reconnection after reboot resetting the os/mpi or applying certain updates causes the reader to reboot the reader gives no direct "reboot finished" signal, so the sdk reconnects automatically by polling for the connection to come back, then continues, with no integrator intervention required while this is happening, onstatechanged reports reconnecting manual ecc signing (test devices only) most integrations can ignore this section for prod devices, ensuredeviceready() provisions the ecc terminal certificate end to end via the tms, so there is nothing to do — and prod devices never reach the manual signing state manual ecc signing only ever applies to test devices used during development, where there is no tms csr signing service and the certificate must instead be signed out of band by the device manufacturer because it is a development only, low frequency step, you are not expected to build manual signing support into your app the onmanualeccsigningrequired callback is only ever invoked for test devices, which your production app will never see, so prod integrations can ignore it entirely kotlin — the callback is optional; it defaults to a no op, so you can simply omit it java — devicesetuplistener onmanualeccsigningrequired must be implemented, but the body can be left empty instead, use our sample app to provision test devices it ships as a ready made apk with a complete manual signing ui, so you can get a test device's certificate signed and installed without writing any of this yourself what happens under the hood for completeness, when a test device needs its ecc certificate signed, setup generates the csr on the device halts at devicesetupstate manual ecc signing required and delivers the raw csr bytes via the onmanualeccsigningrequired callback (when this happens, onsuccess / onerror are not called for that run ) to complete provisioning get the csr signed, producing a signed terminal ecc cert json install it with installeccterminalcert() ; the device restarts automatically on success call ensuredeviceready() again to finish setup the sample app implements exactly this flow if you do need to drive it yourself, the callback receives the csr bytes error handling if a setup step fails, onerror is invoked on the main thread with a toroexception setup does not partially "succeed"; re running ensuredeviceready() after resolving the cause will resume from wherever the device currently is, skipping any steps already completed