Commands and response codes for Uhlmann & Zacher secured by BlueID

Commands and response codes for Uhlmann & Zacher secured by BlueID

BlueID Access standard 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

Uhlmann & Zacher specific commands

Command	Description	Since version
boot	Reboot the module and enter DFU mode. When in boot mode the module advertizes as device name the MAC address for 20 seconds and it is possible to use NRF tools to upgrade the firmware. After 20 seconds of inactivity, the module returns to application.	UUZ 1
mntc	Enter maintenance mode.	UUZ 1
avfw	Read the AVR firmware version. The response is encoded in the user data in three bytes: Start Byte Size Type Description 0 1 byte UINT8 AVR firmware minor version number 1 1 byte UINT8 AVR firmware major version number 2 1 byte UINT8 AVR firmware build version number	UUZ 6
avhw	read the AVR hardware version. The response is encoded in the user data in one byte: Start Byte Size Type Description 0 1 byte UINT8 AVR hardware version number	UUZ 6
ckfw	Check if the AVR firmware version is matching the module firmware. The response is encoded in the user data in four bytes: Start Byte Size Type Description 0 1 byte UINT8 Value Description 0x00 AVR version matches 0xFF AVR version doesn't match All the other values are invalid and reserved for future use. 1 1 byte UINT8 AVR firmware minor version number expected by the module. 2 1 byte UINT8 AVR firmware major version number expected by the module. 3 1 byte UINT8 AVR firmware build version number expected by the module.	UUZ 6
rrva	Read the RAM storage values. The response is encoded in the user data in 20 bytes: Start Byte Size Type Description 0 4 bytes UINT32 Restart counter 4 4 bytes UINT32 Timestamp for RTC 8 4 bytes UINT32 Number of times the RTC overflow triggered a timestamp update 12 1 byte Bitmask Name Bit Description SetFromExternal 0x01 Time has been set by a command ResetFromRamStore 0x02 RAM store reset the data as it has been detected corrupted TimeAcceptedAtRestart 0x04 Time accepted after restart TimeEmptyAtRestart 0x08 No data for time at restart TimeInvalidAtRestart 0x10 Time is invalid at startup TimeInitialValueAtRestart 0x20 Time at startup has intial value All other bits are unused. 13 1 byte BOOL Flag indicating if office mode is enabled 14 1 byte UINT8 Log level 15 1 byte BOOL Flag indicating if restartCount has been set 16 1 byte BOOL Flag indicating if timeStamp has been set 17 1 byte BOOL Flag indicating if timeStatus has been set 18 1 byte BOOL Flag indicating if isOfficeModeEnabled has been set 19 1 byte BOOL Flag indicating if logLevel has been set	UUZ 6
blvs	Read the bootloader version. The response is encoded in the user data in four bytes: Start Byte Size Typ Description 0 4 byte UINT32 current bootloader version number	UUZ 7

BlueID Access standard command execution responses

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

Detailed Scenarios

ID	Scenario	Outcome
1	tokn is triggered while the office mode is active	52
2	tokn is triggered yet coupling fails for mechanical reasons	52
3	enof is triggered but the lock is already in office mode	0
4	diof is triggered but the lock is not in office mode	0
5	enof, diof, tokn, boot or mtnc is triggered while the lock is opened by tokn	BUSY
6	tokn, enof or diof while the handle is not in a horizontal position	52

More about signaling and UX can be found at Signaling of Uhlmann & Zacher secured by BlueID page.