Get Device Status (On Demand)

This method pulls the results of the previous collect card data, PIN entry, or device status request. This method can also retrieve the battery level and charging status of the card reader.

error_outline
note

This method requires a valid connected and/or battery-powered card reader.

When using a ROAM card reader, Commerces SDK does not return the status during an on-demand card read.

Code Samples

CWS

Request

method
string | required
startDeviceStatusOnCardReader
 
requestId
string | required
Transaction Request ID
 
parameters
JSONObject | required
All relevant parameters for retrieving the card reader's connection status and/or battery information.
 

Response

requestId
string
Transaction Request ID
As specified in the request.
statusDetails
string
Request Status
 
data
JSONObject
Object holding various responses.
 
connectionStatus
string
Connection Status
 
batteryChargingState
string
Battery Charging State
 
batteryChargeLevelState
string
Battery Charge Level State
 
batteryChargeLevel
string
Battery Charge Level
 
model
string
Device Model
 

Example

To perform a device status check in CWS, you send in a request for startDeviceStatusOnCardReader. After that command has been accepted, you check the status of the command with the getCommandStatusOnCardReader command. If the command is complete, you will receive the appropriate response. There are 3 different types of responses that can be returned. One for a card reader containing battery information, one for a card reader without battery information, and one if a card reader is disconnected.

Request
startDeviceStatusOnCardReader:

{
    "requestId":"1",
    "method":"startDeviceStatusOnCardReader",
    "parameters":{
    }
}

getCommandStatusOnCardReader:

{
    "requestId":"2",
    "method":"getCommandStatusOnCardReader",
    "parameters":{
        "id":"1"
    }
}
Response

Card Reader with Battery Information

{
    "data": {
        "cardReaderCommand": {
            "completed": true,
            "deviceStatusData": {
                "batteryChargeLevel": 100,
                "batteryChargeLevelState": "FULL",
                "batteryChargingState": "CHARGING",
                "connectionStatus": "CONNECTED",
                "model": "iCM122"
            },
            "eventQueue": [
                {
                    "statusDetails": "DEVICE_STATUS_COMPLETE",
                    "timeStamp": "1475075758193"
                }
            ],
            "id": "1"
        }
    },
    "requestId": "2",
    "statusDetails": "REQUEST_ACCEPTED"
}

Card Reader without Battery Information

{
    "data": {
        "cardReaderCommand": {
            "completed": true,
            "deviceStatusData": {
                "connectionStatus": "CONNECTED",
                "model": "iSC250"
            },
            "eventQueue": [
                {
                    "statusDetails": "DEVICE_STATUS_COMPLETE",
                    "timeStamp": "1474312814238"
                }
            ],
            "id": "1"
        }
    },
    "requestId": "2",
    "statusDetails": "REQUEST_ACCEPTED"
}

Disconnected Card Reader

{
    "data": {
        "cardReaderCommand": {
            "completed": true,
            "deviceStatusData": {
                "connectionStatus": "DISCONNECTED"
            },
            "eventQueue": [
                {
                    "statusDetails": "DEVICE_STATUS_COMPLETE",
                    "timeStamp": "1475075501387"
                }
            ],
            "id": "1"
        }
    },
    "requestId": "2",
    "statusDetails": "REQUEST_ACCEPTED"
}

Java

You need to set up a listener to implement ECLDeviceStatusListener and call refreshStatus function of card reader interface. The card reader's status will be available in listener's call back methods.

ECLDeviceStatusListener statusListener = new ECLDeviceStatusListener()
{
    @Override
    public void deviceConnectionStateChanged(ECLDeviceInterface device, ECLDeviceConnectionState deviceConnectionState)
    {
        displayMessage("Card reader " + ((ECLCardReaderInterface)device).getName() + " status - "
            + deviceConnectionState);
    }

    @Override
    public void devicePowerStateChanged(ECLDeviceInterface device, ECLDevicePowerState devicePowerState)
    {
        displayMessage("Card reader " + ((ECLCardReaderInterface)device).getName() + " battery charge level - "
            + devicePowerState.getBatteryChargeLevel().getChargeLevel());
        displayMessage("Card reader " + ((ECLCardReaderInterface)device).getName() + " battery charge level state - "
            + devicePowerState.getBatteryChargeLevel().getChargeLevelState());
        displayMessage("Card reader " + ((ECLCardReaderInterface)device).getName() + " battery charging state - "
            + devicePowerState.getBatteryChargingState());
    }

    @Override
    public void refreshStatusDidFail(ECLDeviceInterface cardReader, List<ECCError> errors)
    {
        for (ECCError error : errors)
        {
            displayMessage("refreshStatusDidFail " + error);
        }
    }

    @Override
    public void refreshStatusDidComplete()
    {
        displayMessage("refreshStatusDidComplete");
    }
};

cardReaderInterface.addStatusListener(statusListener);
cardReaderInterface.refreshStatus();

Objective-C

You need to set up a delegate to implement ECLDeviceStatusDelegate and pass it to refreshStatus function of card reader protocol. The card reader's status will be available in delegate's call back methods.

[cardReader addStatusDelegate:self];
[cardReader refreshStatus];

+ (void)deviceConnectionStateChanged:(id<ECLDeviceProtocol>)device deviceConnectionState:(ECLDeviceConnectionState)deviceConnectionState {
    [NSString stringWithFormat:@"Card reader %@ is %@\n", [(id<ECLCardReaderProtocol>)device name ], [self connectionStatusToString:deviceConnectionState]];
}

+ (void)devicePowerStateChanged:(id<ECLDeviceProtocol>)device devicePowerState:(ECLDevicePowerState *)devicePowerState {
    [NSString stringWithFormat:@"Card reader %@  battery charge level: %@\n", [(id<ECLCardReaderProtocol>)device name], [[devicePowerState batteryChargeLevel] chargeLevel]];
    [NSString stringWithFormat:@"Card reader %@  battery charge state: %@\n", [(id<ECLCardReaderProtocol>)device name], [self batteryLevelToString:[[devicePowerState batteryChargeLevel] chargeLevelState]]];
    [NSString stringWithFormat:@"Card reader %@  battery charging state: %@\n", [(id<ECLCardReaderProtocol>)device name], [self batteryChargingStateToString:[devicePowerState batteryChargingState]]];
}

+ (void)refreshStatusDidFail:(id<ECLDeviceProtocol>)device errors:(NSArray *)arrayOfNSErrors {
    [NSString stringWithFormat:@"Refresh Status failed: %@\n",[arrayOfNSErrors[0] debugDescription]];
}

+ (NSString *)connectionStatusToString:(ECLDeviceConnectionState) connectionStatus {
    switch(connectionStatus) {
        case ECLDeviceConnectionState_Connected:
            return @"Connected";
        case ECLDeviceConnectionState_Disconnected:
            return @"Disconnected";
        case ECLDeviceConnectionState_ConnectedNotReady:
            return @"Connected Not Ready";
        case ECLDeviceConnectionState_Unknown:
            return @"Unknown";
        case ECLDeviceConnectionState_UnSet:
            return @"UnSet";
    }
}

+ (NSString *)batteryChargingStateToString:(ECLDeviceBatteryChargingState) chargingState {
    switch(chargingState) {
        case ECLDeviceBatteryChargingState_Charging:
            return @"Charging";
        case ECLDeviceBatteryChargingState_ChargingUsb:
            return @"Charging Usb";
        case ECLDeviceBatteryChargingState_ChargingAc:
            return @"Charging AC";
        case ECLDeviceBatteryChargingState_Discharging:
            return @"Discharging";
        case ECLDeviceBatteryChargingState_Unknown:
            return @"Unknown";
        case ECLDeviceBatteryChargingState_UnSet:
            return @"UnSet";
    }
}

+ (NSString *)batteryLevelToString:(ECLDeviceBatteryChargeLevelState) batteryLevel {
    switch(batteryLevel) {
        case ECLDeviceBatteryChargeLevelState_Full:
            return @"Full";
        case ECLDeviceBatteryChargeLevelState_Good:
            return @"Good";
        case ECLDeviceBatteryChargeLevelState_Low:
            return @"Low";
        case ECLDeviceBatteryChargeLevelState_Critical:
            return @"Critical";
        case ECLDeviceBatteryChargeLevelState_Unknown:
            return @"Unknown";
        case ECLDeviceBatteryChargeLevelState_UnSet:
            return @"UnSet";
    }
}

C#

The device status data is returned in a DeviceStatusData object.

public class DeviceStatusData
{
  public String connectionStatus { get; set; }
  public String batteryChargingState { get; set; }
  public String batteryChargeLevelState { get; set; }
  public long batteryChargeLevel { get; set; }
  public String model { get; set; }
}

/* Delegate to handle results */
public void MyDeviceStatusComplete(DeviceStatusResults dsr)
{
    DeviceStatusData dsd = dsr.DeviceStatusData;
    if (null != dsd)
    {
            /* handle device status */
    }
}
...

/* Kick off refresh device status */

m_CWS.StartDeviceStatus(MyNotifyCWSEvent, MyDeviceStatusComplete);