REST API Devices Objects DEVICE

April 13, 2023 at 2:39 AM

DEVICE object

The JSON DEVICE object returns all the technical data regarding a SpringCard device.

Use List connected devices to retrieve all the DEVICE objects, or Get device data if you already know the device’s DeviceId.

Object definition

Field name Type Status Description Condition
DeviceId string always The DeviceId of the device. Use this as {$id} in all /device/{$id}/* requests
Binding string always pnp, not-bound, bound
Status string always Current status returned by the system: ok, error, missing or unknown
Channel string always Communication channel: usb, serial, ble or network
FriendlyChannel string option More details regarding the communication channel (such as serial comm. name, IP address or host name, etc)
Mode string option Operating mode of the device: pcsc, smartreader, rfidscanner, … Status is OK
FriendlyMode string option User-friendly version of the Mode (PC/SC, RDR (MQTT), RDR (RFID Scanner), …) Status is OK
Profile string option Main communication protocol of the device: direct, ccid, hid, comm, … Status is OK
Name string option Name of the device, as returned by the driver or collected from the device’s meta-data Status is OK
FriendlyName string option Alternate name of the device, possibly used by the system in its own views Not empty
Not equal to Name
VendorId integer option VendorID (vvvvpart of the PnpID) in decimal (7220 for SpringCard)
ProductId integer option ProductID (pppppart of the PnpID) in decimal
PnpId string option Technical identifier of the device, in the form ssvvvvpppprrrr where
-ss is the VendorID source (02for USB Workgroup),
-vvvvis the VendorID in hex (1C34 for SpringCard),
-pppp is the ProductID in hex,
-rrrr the Release (for instance, 0210 for version “2.10”)
SerialPort string option The name of the COM port associated to this device Channel is serial
IpAddress string option IPv4 network address, if the device has one
IpAddress6 string option IPv6 network address, if the device has one
SerialNumber string option Serial number of the device Not empty
Version string option Version of the device (ex: “2.10”)
Firmware string option Identification of the firmware
Hardware string option Identification of the hardware (part number) Not empty
Characteristics string option Technical characteristics of the hardware (see Hardware Characteristics) Not empty
UniqueId string option Unique Identifier of the device (signature of the hardware)
ConfigId string option The GUID of the configuration (signature of the settings) (register 0200) Register set in NVM
Inventory string option Inventory number (register 0201) Register set in NVM
Location string option Location (register 0202) Register set in NVM
Application string option Application name or integrator specific string (register 0208) Register set in NVM
LicenseKey string option License key or license number (register 0209) Register set in NVM
LicenseCryptogram string option License cryptogram (register 020A) Register set in NVM
Pcsc object option The list of PC/SC readers associated to this device. This object has 2 entries:
Names: an array of strings with the name of every PC/SC reader
ReaderIds: an array of strings with the ReaderId of every PC/SC reader.		 Profile is pc/sc
HidInstance string option The name of the HID driver instance associated to this device Profile is hid
PhysAddress string option Physical address of the device, as an hex-string, if this information is available and makes sense.
For a BLE device, this is the BT_ADDR, for a network device, the MAC address.

Warning

The DeviceId field is only a temporary value. The very same device may have a different "DeviceId" the next time it connects to the computer. A different device may have the same DeviceId as a previously connected one.

Always use List devices to enumerate all the devices that are currently connected to the computer, and do not store the DeviceId values anywhere.

If you want to identify a particular device, use the SerialNumber or UniqueId fields.

Example

{
	"Name": "Puck One",
	"FriendlyName": "SpringCard Puck One",
	"PnpId": "021C3461220123",
	"VendorName": "SpringCard",
	"ProductName": "Puck",
	"ProductVariant": "One",
	"SerialNumber": "251C1A74",
	"Version": "1.23",
	"Firmware": "springcore/h518/puck",
	"Characteristics": "nfc,usb,led-rgb,buzzer,atecc,samav,crypto",
	"UniqueId": "DB571829-3992-7BA4-8A6B-B3E018AA5878",
	"ConfigId": "00000000-0000-0000-0000-000000000000",
	"SealSubject": "C=FR,ST=Ile-de-France,O=SpringCard,OU=SpringCore,CN=DB571829-3992-7BA4-8A6B-B3E018AA5878",
	"SealSignature": "WH0g5POUphEVpCmdb/cK8c7X+bgVQ0tQfVzlB8Q4br8Q0Fnvw6/OaZMENbAaH6UxFgSwuV1FLn1WrPLgq1p8DT0ps93d6PuGrIf3YMRzGK6HI6d9Or5GICJ5c/wNSJtEhhSCacYxrAznzhjkYoDPqSvyM1+DdZZIuK3SBDcaBJbi4exmKt1LaU8+nihZ3O6zxOuWQUjtv+6rmCnUd0XtP4reJcKS+RMoMCLypzM+3EXN2VUowwjtiEtULy6MJRe7CDNrWhEo7rzl2NPt1JzPqlELD4Y1Fi1jqUvoKd69i7RJTKqEkjZHtxJtEZGe1+gCum60aHUfAYvbHHvDrmewCw==",
	"Genuine": true,
	"DeviceId": "VwMwAs4FZZ8CVoqYNR8b21",
	"Channel": "usb",
	"Binding": "pnp",
	"Status": "ok",
	"Profile": "ccid",
	"Mode": "pcsc",
	"FriendlyMode": "PC/SC",
	"VendorId": 7220,
	"ProductId": 24866
}

Understanding the state of the device

Fields Binding and Status reflect the state of the device.

Please refer to this table for a complete understanding:

Status=ok Status=missing
Binding=pnp Device is currently connected over a PNP channel (namely usb) Not possible
Binding=not-bound Device is currently connected over a non-PNP channel (for instance, serial)
Device is not in the list of persistent bindings		 Not possible
Binding=bound Device is currently connected over a non-PNP channel (for instance, serial)
Device is in the list of persistent bindings		 Device is in the list of persistent bindings but is currenlty not connected

When status is missing, all the optional fields of the DEVICE object are absent.