Get Device Status
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.
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
Property | Description |
---|---|
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
Property | Description |
---|---|
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);