BlueID Access commands and response codes

BlueID Access commands

BlueID Access standard commands

Every BlueID Access hardware supports the following BlueID commands:

Command	Description	Since BlueID SDK for C version
tokn	The secured object generally remains in a locked state, i.e. a user does not gain access without presenting a valid BlueID Token. An authorized user must present his valid BlueID Token for getting access to corresponding secured object (e.g. a room). The door of a hotel room is a typical use case since you want to make sure that only authorized users can access the room.	2.6
enof	An authorized user must present his valid BlueID Token for enabling the office mode on a secured object. Once the secured object is placed into office mode, any user can access the secured object without presenting any BlueID Token. The doors in an "open-door policy" office are a typical use case.	2.6
diof	An authorized user must present his valid BlueID Token for disabling the office mode on a secured object. Once the office mode is disabled, no user can access the secured object without presenting his valid BlueID Token.	2.6
toof	Toggles the office mode. If the office mode was active, it will be deactivated. If the office mode was inactive, it will be activated.	3.7
time	An authorized user must present his valid BlueID Token for setting the time on the real time clock of the secured object. The time is then set to the current time of the mobile device as a Unix timestamp. To make sure that the BlueID Token with this command is valid, please set the start date to 0. Please note that this command is for administrative purposes only.	2.6
gtim	get time: Retrieves the time of the real time clock on the secured object as a Unix timestamp.	2.6
gual	get user access log: Retrieves a list of all authorized and unauthorized user accesses on the secured object. Use the responseObject getter method in CommandExecutionResponse on the mobile device to get the user access log.	2.6
cual	clear user access log: Use this to clear the user access log when you have successfully retrieved the user access log in a previous step.	2.6
vers	get version: Retrieves the version of the BlueID SDK on the secured object as a string.	2.6
slol	set log level: This command makes the user capable to set the log level on secured objects. To set the log level, pass a number between 0 to 5 which maps the following level of logging respectively: All (0), Debug, Information, Warning, Error and Off (5).	2.8
glol	get log level: Retrieves the log level of the BlueID SDK on the secured object as string.	2.8
batt	This commands returns a qualitative indication for the state of the battery (e.g. battery full, empty or getting critical).	3.7
gsta	get status information: get the status information including current time and time status, battery status, user access log count and capacity, revocation store count and capacity, reset reason and count, hardware mode states. The response is encoded in CBOR.	3.9
gver	get version information: get the versions for boot loader, platform and lock controller and furthermore hardware revision, vendor and name. The response is encoded in CBOR.	3.9
gcfg	get configuration information: get the configuration information including lock id, API key and all available bluetooth settings. The response is encoded in CBOR.	3.9
hrev	get hardware revision: retrieve the revision of the hardware as a string with major, minor and revision numbers.	3.9
lcvs	get lock controller version: retrieve the version of the controller of the lock (when present) as a string with major, minor and revision numbers.	3.9
blvs	get the bootloader version: retrieve the bootloader version as a string with major, minor and revision numbers.	3.9
hwna	get hardware name: retrieve the hardware name as a string.	3.9
hwve	get the hardware vendor: retrieve the hardware vendor as a string.	3.9
hwmo	get the hardware mode: retrieve the status of all available hardware modes (like office mode or privacy mode) as a string.	3.9
resr	get reset reason: retrieve the reason of the last reset as a string.	3.9
resc	get reset count: retrieve the number of resets that were counted as unsigned integer.	3.9

Please note that the actual state of the secured object (e.g. is the door locked or not) after presenting a valid BlueID Token highly depends on the type of the secured object. For example, an electronic door trim which you usually find in hotels is locked again after presenting a valid BlueID Token tokn. However, an electronic cylinder might be still unlocked after presenting a valid BlueID Token tokn since the electronic cylinder might not operate the door handle.

Additional BlueID Access commands for different objects

ISEO Zero1

All the ISEO Zero1 secured by BlueID products support the following additional BlueID Access commands:

Command	Description	Since version
dcwl	Delete Card Whitelist: Command for deleting all whitelist entries for ISEO User Cards inside the lock.	2.6
gcwl	Get Card Whitelist: Sends all whitelist entries for ISEO User Cards of the lock device to the mobile device. It returns a list of 4-byte values in big-endian format starting with a header containing the number of whitelist elements, followed by the elements.	2.6
adcd	Add Card: Adds an ISEO User Card to the card whitelist. Requires an unsigned 32-bit card number as command parameter, encoded in a 4-byte representation in big-endian format, e.g. card number 7448 must be sent as 0x00, 0x00, 0x1d, 0x18. Blinks green on success, red on error. See response code for more information.	2.6
rmcd	Remove Card: Removes a formerly added ISEO User Card from the card whitelist. Requires an unsigned 32-bit card number as command parameter, encoded in a 4-byte representation in big-endian format, e.g. card number 29340 must be sent as 0x00, 0x00, 0x72, 0x9c. Blinks green on success, red on error. See response code for more information.	2.6
boot	Change to bootloader mode. The ISEO lock changes to normal mode after 5 seconds.	3
fres	Complete factory reset. This command removes all data from storage expect the software itself. The ISEO lock has to be reinitialized after that. Lock does reboot after the initialization data is removed.	3
rmma	Delete ISEO master card assignment. After that, a new master set can be assigned. This is useful when the master set is lost or should be blocked.	3
adcs	Activate this mode for adding ISEO user cards to the ISEO device. After activating the mode, as many ISEO user cards as needed can be presented to the ISEO lock. The ISEO lock changes to normal mode after 5 seconds without a card.	3
rmcs	Activate this mode for removing ISEO user cards from the ISEO device. After activating the mode, as many ISEO user cards as needed can be presented to the ISEO lock. The ISEO lock changes to normal mode after 5 seconds without a card.	3
svop	This command has the same functionality as tokn except on Aries locks, where no access is granted when privacy mode is active.	7
fota	Start the FOTA update with NFC cards	10
resc	Not supported by ISEO	10

BlueID Ready2Go 28 Modul

Please note that how to use the following BlueID commands highly depends on the hardware where the module is built-in:

Command	Description
tria	Toggle the output level of pin A
opeb	Set the pin B for 500 ms to high
ronb	Activate the pin B (high level)
rofb	Deactivate the pin B (low level)
trib	Toggle the output level of pin B
opec	Set the pin C for 500 ms to high
ronc	Activate the pin C (high level)
rofc	Deactivate the pin C (low level)
tric	Toggle the output level of pin C
oped	Set the pin D for 500 ms to high
rond	Activate the pin D (high level)
rofd	Deactivate the pin D (low level)
trid	Toggle the output level of pin D

BlueID Access response codes

BlueID Access standard response codes

The return value while executing a BlueID command is of type CommandExecutionResponse. For example:

CommandExecutionResponse response = 
    sdk.executeCommand(securedObject,channel, command);

The CommandExecutionResponse contains a ResponseCode and ResponseObject that are returned by the secured object. We refer to the apiDoc of BlueID SDK for Android and BlueID SDK for iOS for more details. We have the following standard BlueID response codes:

Code	Type	Description	Since version
0	Success	OK	2.6
49	Mobile Device Error	The Secured Object received an invalid parameter. Please make sure that the parameter is valid	2.6
50	Mobile Device Error	The Secured Object received an unknown command. Please make sure that the command is valid	2.6
51	Mobile Device Error	The Secured Object expected a parameter for the used command. Please make sure that a parameter is provided	2.6
52	Secured Object Error	Error during execution of the procedure associated to command	2.6
53	Informational	When calling gtim but the time was not set, the Secured Object must always return the default timestamp and this response code	3.7
54	Secured Object Error	For a Secured Object connected to an online directory, this response code indicates that the online directory is not available	3.7
55	Secured Object Error	For a Secured Object connected to an online directory, the directory rejected the command execution request	3.7
100	Informational	Already executing another command, dismissing command request.	2.6
128	Informational	Battery level is low, please replace the battery soon	3.7
132	Secured Object Error	Some hardware component that is required to execute the command -- e.g. a mechanical switch -- is unavailable so the Secured Object was not able to execute the command	3.7
133	Secured Object Error	Command execution was rejected because the privacy mode was activated on the Secured Object	3.7
134	Secured Object Error	The Secured Object is already in office mode	3.7
135	Hardware Failure	Command execution failed due to hardware failure	3.7

Finally, the following BlueID Access standard commands have special types of ResponseObject:

Command	RepsonseObject	Since version
gtim	LockServerTime
gual	UserAccessLog
vers	LockServerVersion
glol	LockServerLogLevel
batt	BatteryState	3.8

Note: "batt" uses "User Specified Data" before version 3.8.

Further documentation to some BlueID commands

Fetching the battery status

The value shown using batt BlueID command is a single byte value that is forwarded from the lock indicating the battery state. The following table describes the possible values:

Value	Meaning
0	OK
1	Battery is getting empty
2	Battery is empty, replace it soon
3	Battery is critically low, replace it now
100	Device has no battery but is permanently powered
101	Device has battery that is charged inductively
255	Failed to retrieve battery status

Additional BlueID Access response codes for different objects

ISEO Zero1

All the ISEO Zero1 secured by BlueID products support the following additional BlueID Access response codes:

Code	Type	Description	Since version
129	Success	Card cannot be added because it is already on whitelist.	3.0
130	Success	Card cannot be removed because it is not on whitelist.	3.0
180	Security warning	Security threat: No ISEO Master Card assigned!	v9

BlueID Ready2Go 28 Modul

In case of the commands "tria", "trib", "tric" and "trid" two additional response codes are defined:

Code	Type	Description
2	Success	Ok. The voltage level of the output pin after the command execution is low.
3	Success	Ok. The voltage level of the output pin after the command execution is high.