TMS Updates

6 min

The Terminal Management System (TMS) is the source of truth for a reader's encryption keys and configuration. There are two points at which the SDK applies pending TMS updates:

During device setup, as part of ensureDeviceReady()ensui. This is the primary mechanism and handles everything: key injection, ECC certificate signing and configuration updates.

On transaction start: an opt-in, lighter-weight check that applies pending configuration updates immediately before a transaction.

Updates during device setup

The recommended approach is to call ensureDeviceReady()ensui when pairing a reader and again on every app launch. It checks the TMS for pending updates and applies any that are found (keys, ECC certificate and configuration alike), skipping anything already up to date. On a healthy device with nothing pending, the only cost is a single StatusReport to the TMS.

See Device Setup & ReadinessDe for the full flow, progress states and ECC handling.

Updates on transaction start (opt-in)

For integrators who want configuration to stay current without relying solely on app-launch setup, the SDK can check for and apply pending updates at the start of each transaction. This is off by default.

Enable it via ToroConfig:

var config = toro.getConfig()
config.checkForUpdatesOnTransactionStart = true
try toro.setConfig(config)

You can equally set it when first constructing the ToroConfig you pass to the SDK:

let config = ToroConfig(
    // ...other config...
    checkForUpdatesOnTransactionStart: true
)

When enabled, startTransaction() checks the TMS for pending updates before proceeding and applies any applicable update. When disabled (the default), startTransaction() behaves exactly as before and runs no update checks.

The transaction-start path handles CONFIGURATION_UPDATE (application parameters) only. Key injection and ECC signing are not applied here; those are prerequisites that must be resolved during initial device setup via Device Setup & ReadinessensureDeviceReady().

Transaction states for this flow

When checkForUpdatesOnTransactionStart is enabled, two additional TransactionState values may be emitted to your TransactionStateListener immediately after .connectingToDevice (i.e. once the device is connected and its info has been read) and before the usual .awaitingGratuity / .awaitingCard states:

State	What's happening
.checkingForUpdates	Checking the gateway for pending device updates before the transaction starts.
.applyingUpdates	Installing a pending configuration update on the device before the transaction starts. Only emitted when an applicable update was found.

If no update is pending, only .checkingForUpdates is emitted (briefly) and the transaction proceeds normally; the only cost is the status check itself.

Reconnection after an update

Applying a configuration update can reboot the reader. As with device setup, the SDK reconnects automatically via connection polling and then continues the transaction without integrator intervention.

Choosing an approach

	App-launch setup	Transaction-start check
Entry point	ensureDeviceReady()	startTransaction() (with config flag)
Opt-in?	No, call it yourself	Yes, via checkForUpdatesOnTransactionStart
Handles keys / ECC	Yes	No (configuration only)
Handles configuration	Yes	Yes
Added latency	On app launch / pairing	Before every transaction

The two are complementary. At minimum, call ensureDeviceReady() regularly. Enable the transaction-start check additionally if you need configuration to converge as quickly as possible between setup runs.