ChameleonUltra

Protocol description

Versioning

Global firmware+CLI versions are following the semantic versioning logic mostly regarding the protocol version, so third party clients (GUIs, mobile apps, SDKs) can rely on firmware version to know their level of compatibility.

Given a version number MAJOR.MINOR.PATCH, we will increment the:

MAJOR version when we are breaking the existing protocol format
MINOR version when we are extending the protocol format in a backward compatible manner (new commands,…)
PATCH version when we are releasing bugfixes not affecting the protocol description

Besides compatibility with a given firmware version, third party clients may choose to offer to the users the possibility to follow a stable release channel (installing only tagged releases) or the development channel (installing latest commits).

For the stable channel, a client compatible with versions X.y.z can accept any version > X.y’.z’ but should refuse to work with a version X’>X.

For the development channel, a client compatible with versions X.y.z can accept any latest commit unless a tag X’.0.0 with X’>X is present in the repo, indicating that the corresponding commit and all the commits above are incompatible with the client version. There is still a non negligible risk that breaking changes are pushed while forgetting about putting a new tag, or artefacts being built before the tag being pushed. Here be dragons… It’s always a good practice for the client to validate whatever data is transmitted by the firmware, and fail gracefully in case of hiccups.

Cf GET_APP_VERSION and GET_GIT_VERSION.

When GET_GIT_VERSION returns only a tag and no commit hash info (on a release tag), one can query the corresponding hash with the GitHub API, e.g.

"4747d3884d21e0df8549e3029a920ea390e0b00a"

Frame format

The communication between the firmware and the client is made of frames structured as follows:

packet
+8: "SOF"
+8: "LRC1"
+16: "CMD"
+16: "STATUS"
+16: "LEN"
+8: "LRC2"
+48: "DATA (variable length)"
+8: "LRC3"

SOF: 1 byte, “Start-Of-Frame byte” represents the start of a packet, and must be equal to 0x11.
LRC1: 1 byte, LRC over SOF byte, therefore must be equal to 0xEF.
CMD: 2 bytes, each command have been assigned a unique number (e.g. DATA_CMD_SET_SLOT_TAG_NICK = 1007).
STATUS: 2 bytes.
- From client to firmware, the status is always 0x0000.
- From firmware to client, the status is the result of the command.
LEN: 2 bytes, length of the DATA field, maximum is 512.
LRC2: 1 byte, LRC over CMD|STATUS|LEN bytes.
DATA: LEN bytes, data to be sent or received, maximum is 512 bytes. This payload depends on the exact command or response to command being used. See Packet payloads below.
LRC3: 1 byte, LRC over DATA bytes.

Notes:

The same frame format is used for commands and for responses.
All values are unsigned values, and if more than one byte, in network byte order, aka Big Endian byte order.
The total length of the packet is LEN + 10 bytes, therefore it is between 10 and 522 bytes.
The LRC (Longitudinal Redundancy Check) is the 8-bit two’s-complement value of the sum of all bytes modulo $2^8$.
LRC2 and LRC3 can be computed equally as covering either the frame from its first byte or from the byte following the previous LRC, because previous LRC nullifies previous bytes LRC computation. E.g. LRC3(DATA) == LRC3(whole frame)

Data payloads

Each command and response have their own payload formats.

Standard response status is STATUS_SUCCESS for general commands, STATUS_HF_TAG_OK for HF commands and STATUS_LF_TAG_OK for LF commands. See Guidelines for more info.

Beware, slots in protocol count from 0 to 7 (and from 1 to 8 in the CLI…).

In the following list, “CLI” refers to one typical CLI command using the described protocol command. But it’s not a 1:1 match, there can be other protocol commands used by the CLI command and there can be other CLI commands using the same protocol command…

1000: GET_APP_VERSION

CLI: cf hw version

---
title: "Command Packet"
---
packet
+8: "SOF"
+8: "LRC1"
+16: "CMD (=1000)"
+16: "STATUS"
+16: "LEN (=0)"
+8: "LRC2"
+8: "LRC3"

Command: no data

---
title: "Response Packet"
---
packet
+8: "SOF"
+8: "LRC1"
+16: "CMD (=1000)"
+16: "STATUS"
+16: "LEN (=2)"
+8: "LRC2"
+8: "major version"
+8: "minor version"
+8: "LRC3"

Response: 2 bytes: version_major|version_minor

1001: CHANGE_DEVICE_MODE

CLI: cf hw mode

---
title: "Command Packet"
---
packet
+8: "SOF"
+8: "LRC1"
+16: "CMD (=1001)"
+16: "STATUS"
+16: "LEN (=1)"
+8: "LRC2"
+8: "new device mode"
+8: "LRC3"

device mode: 0x00=emulator mode, 0x01=reader mode

---
title: "Response Packet"
---
packet
+8: "SOF"
+8: "LRC1"
+16: "CMD (=1001)"
+16: "STATUS"
+16: "LEN (=0)"
+8: "LRC2"
+8: "LRC3"

Response: no data

1002: GET_DEVICE_MODE

Command: no data
Response: data: 1 byte. 0x00=emulator mode, 0x01=reader mode
CLI: cf hw mode
1003: SET_ACTIVE_SLOT
Command: 1 byte. slot_number between 0 and 7
Response: no data
CLI: cf hw slot change
1004: SET_SLOT_TAG_TYPE
Command: 3 bytes. slot_number|tag_type[2] with slot_number between 0 and 7 and tag_type according to tag_specific_type_t enum, U16 in Network byte order.
Response: no data
CLI: cf hw slot type
1005: SET_SLOT_DATA_DEFAULT
Command: 3 bytes. slot_number|tag_type[2] with slot_number between 0 and 7 and tag_type U16 according to tag_specific_type_t enum, U16 in Network byte order.
Response: no data
CLI: cf hw slot init
1006: SET_SLOT_ENABLE
Command: 3 bytes. slot_number|sense_type|enable with slot_number between 0 and 7, sense_type according to tag_sense_type_t enum and enable = 0x01 to enable, 0x00 to disable
Response: no data
CLI: cf hw slot enable/hw slot disable
1007: SET_SLOT_TAG_NICK
Command: 2+N bytes. slot_number|sense_type|name[N] with slot_number between 0 and 7, sense_type according to tag_sense_type_t enum and name a UTF-8 encoded string of max 32 bytes, no null terminator.
Response: no data
CLI: cf hw slot nick
1008: GET_SLOT_TAG_NICK
Command: 2 bytes. slot_number|sense_type with slot_number between 0 and 7 and sense_type according to tag_sense_type_t enum.
Response: a UTF-8 encoded string of max 32 bytes, no null terminator. If no nick name has been recorded in Flash, response status is STATUS_FLASH_READ_FAIL.
CLI: cf hw slot nick
1009: SLOT_DATA_CONFIG_SAVE
Command: no data
Response: no data
CLI: cf hw slot store
1010: ENTER_BOOTLOADER
Command: no data
Response: this special command does not return and will interrupt the communication link while rebooting in bootloader mode, needed for DFU.
CLI: cf hw dfu
1011: GET_DEVICE_CHIP_ID
Command: no data
Response: 8 bytes. nRF DEVICEID[8] U64 in Network byte order.
CLI: cf hw chipid
1012: GET_DEVICE_ADDRESS
Command: no data
Response: 6 bytes. nRF DEVICEADDR[6] U48 in Network byte order. First 2 MSBits forced to 0b11 to match BLE static address.
CLI: cf hw address
1013: SAVE_SETTINGS
Command: no data
Response: no data
CLI: cf hw settings store
1014: RESET_SETTINGS
Command: no data
Response: no data
CLI: cf hw settings reset
1015: SET_ANIMATION_MODE
Command: 1 byte, according to settings_animation_mode_t enum.
Response: no data
CLI: cf hw settings animation
1016: GET_ANIMATION_MODE
Command: no data
Response: 1 byte, according to settings_animation_mode_t enum.
CLI: cf hw settings animation
1017: GET_GIT_VERSION
Command: no data
Response: n bytes, a UTF-8 encoded string, no null terminator.
CLI: cf hw version

Notes: the returned string is the output of git describe --abbrev=7 --dirty --always --tags --match "v*.*" so, depending on the status of the repo it can be

a short tag, e.g. v2.0.0 if the firmware is built from the tagged commit
a longer tag indicating how far it is from the latest tag and 7 nibbles of its commit hash, prepended with g, e.g. 5 commits away from v2.0.0: v2.0.0-5-g617d6d0
a long tag finishing with -dirty if the local repo contains changes not yet committed, e.g. v2.0.0-5-g617d6d0-dirty
1018: GET_ACTIVE_SLOT
Command: no data
Response: 1 byte
CLI: cf hw slot list
1019: GET_SLOT_INFO
Command: no data
Response: 32 bytes, 8 tuples hf_tag_type[2]|lf_tag_type[2] according to tag_specific_type_t enum, for slots from 0 to 7, U16 in Network byte order.
CLI: cf hw slot list
1020: WIPE_FDS
Command: no data
Response: no data. Status is STATUS_SUCCESS or STATUS_FLASH_WRITE_FAIL. The device will reboot shortly after this command.
CLI: cf hw factory_reset
1021: DELETE_SLOT_TAG_NICK
Command: 2 bytes. slot_number|sense_type with slot_number between 0 and 7 and sense_type according to tag_sense_type_t enum.
Response: no data
CLI: cf hw slot nick
1023: GET_ENABLED_SLOTS
Command: no data
Response: 16 bytes, 8*2 bool = 0x00 or 0x01, 2 bytes for each slot from 0 to 7, as enabled_hf|enabled_lf
CLI: cf hw slot list
1024: DELETE_SLOT_SENSE_TYPE
Command: 2 bytes. slot_number|sense_type with slot_number between 0 and 7 and sense_type according to tag_sense_type_t enum.
Response: no data
CLI: cf hw slot delete
1025: GET_BATTERY_INFO
Command: no data
Response: 3 bytes, voltage[2]|percentage. Voltage: U16 in Network byte order.
CLI: cf hw battery

Notes: wait about 5 seconds after wake-up, before querying the battery status, else the device won’t be able to give a proper measure and will return zeroes.

1026: GET_BUTTON_PRESS_CONFIG

Command: 1 byte. Char A or B (a/b tolerated too)
Response: 1 byte, button_function according to settings_button_function_t enum.
CLI: cf hw settings btnpress
1027: SET_BUTTON_PRESS_CONFIG
Command: 2 bytes. button|button_function with button char A or B (a/b tolerated too) and button_function according to settings_button_function_t enum.
Response: no data
CLI: cf hw settings btnpress
1028: GET_LONG_BUTTON_PRESS_CONFIG
Command: 1 byte. Char A or B (a/b tolerated too)
Response: 1 byte, button_function according to settings_button_function_t enum.
CLI: cf hw settings btnpress
1029: SET_LONG_BUTTON_PRESS_CONFIG
Command: 2 bytes. button|button_function with button char A or B (a/b tolerated too) and button_function according to settings_button_function_t enum.
Response: no data
CLI: cf hw settings btnpress
1030: SET_BLE_PAIRING_KEY
Command: 6 bytes. 6 ASCII-encoded digits.
Response: no data
CLI: cf hw settings blekey
1031: GET_BLE_PAIRING_KEY
Command: no data
Response: 6 bytes. 6 ASCII-encoded digits.
CLI: cf hw settings blekey
1032: DELETE_ALL_BLE_BONDS
Command: no data
Response: no data
CLI: cf hw settings bleclearbonds
1033: GET_DEVICE_MODEL
Command: no data
Response: 1 byte. hw_version aka NRF_DFU_HW_VERSION according to chameleon_device_type_t enum (0=Ultra, 1=Lite)
CLI: cf hw version
1034: GET_DEVICE_SETTINGS
Command: no data
Response: 14 bytes
- settings_current_version = 5
- animation_mode, cf GET_ANIMATION_MODE
- btn_press_A, cf GET_BUTTON_PRESS_CONFIG
- btn_press_B, cf GET_BUTTON_PRESS_CONFIG
- btn_long_press_A, cf GET_LONG_BUTTON_PRESS_CONFIG
- btn_long_press_B, cf GET_LONG_BUTTON_PRESS_CONFIG
- ble_pairing_enable, cf GET_BLE_PAIRING_ENABLE
- ble_pairing_key[6], cf GET_BLE_PAIRING_KEY
CLI: unused
1035: GET_DEVICE_CAPABILITIES
Command: no data
Response: 2*n bytes, a list of supported commands IDs.
CLI: used internally on connect
1036: GET_BLE_PAIRING_ENABLE
Command: no data
Response: 1 byte, bool = 0x00 or 0x01
CLI: cf hw settings blepair
1037: SET_BLE_PAIRING_ENABLE
Command: 1 byte, bool = 0x00 or 0x01
Response: no data
CLI: cf hw settings blepair
2000: HF14A_SCAN
Command: no data
Response: N bytes: tag1_data|tag2_data|... with each tag: uidlen|uid[uidlen]|atqa[2]|sak|atslen|ats[atslen]. UID, ATQA, SAK and ATS as bytes.
CLI: cf hf 14a scan

Notes:

remind that if no tag is present, status will be STATUS_HF_TAG_NO and Response empty.
at the moment, the firmware supports only one tag, but get your client ready for more!
atslen must not be confused with ats[0]==TL. So atslen|ats = 00 means no ATS while 0100 would be an empty ATS.
2001: MF1_DETECT_SUPPORT
Command: no data
Response: 1 byte, bool = 0x00 or 0x01
CLI: cf hf 14a info
2002: MF1_DETECT_PRNG
Command: no data
Response: 1 byte, according to mf1_nested_type_t enum
CLI: cf hf 14a info
2003: MF1_STATIC_NESTED_ACQUIRE
Command: 10 bytes: type_known|block_known|key_known[6]|type_target|block_target. Key as 6 bytes.
Response: 4+N*8 bytes: uid[4] followed by N tuples of nt[4]|nt_enc[4]. All values as U32.
CLI: cf hf mf nested on static nonce tag
2004: MF1_DARKSIDE_ACQUIRE
Command: 4 bytes: type_target|block_target|first_recover|sync_max. Type=0x60 for key A, 0x61 for key B.
Response: 1 byte if Darkside failed, according to mf1_darkside_status_t enum, else 33 bytes darkside_status|uid[4]|nt1[4]|par[8]|ks1[8]|nr[4]|ar[4]
- darkside_status
- uid[4] U32 (format expected by darkside tool)
- nt1[4] U32
- par[8] U64
- ks1[8] U64
- nr[4] U32
- ar[4] U32
CLI: cf hf mf darkside
2005: MF1_DETECT_NT_DIST
Command: 8 bytes: type_known|block_known|key_known[6]. Key as 6 bytes. Type=0x60 for key A, 0x61 for key B.
Response: 8 bytes: uid[4]|dist[4]
- uid[4] U32 (format expected by nested tool)
- dist[4] U32
CLI: cf hf mf nested
2006: MF1_NESTED_ACQUIRE
Command: 10 bytes: type_known|block_known|key_known[6]|type_target|block_target. Key as 6 bytes. Type=0x60 for key A, 0x61 for key B.
Response: N*9 bytes: N tuples of nt[4]|nt_enc[4]|par
- nt[4] U32
- nt_enc[4] U32
- par
CLI: cf hf mf nested
2007: MF1_AUTH_ONE_KEY_BLOCK
Command: 8 bytes: type|block|key[6]. Key as 6 bytes. Type=0x60 for key A, 0x61 for key B.
Response: no data
Status will be STATUS_HF_TAG_OK if auth succeeded, else STATUS_MF_ERR_AUTH
CLI: cf hf mf nested
2008: MF1_READ_ONE_BLOCK
Command: 8 bytes: type|block|key[6]. Key as 6 bytes. Type=0x60 for key A, 0x61 for key B.
Response: 16 bytes: block_data[16]
CLI: cf hf mf rdbl
2009: MF1_WRITE_ONE_BLOCK
Command: 24 bytes: type|block|key[6]|block_data[16]. Key as 6 bytes. Type=0x60 for key A, 0x61 for key B.
Response: no data
CLI: cf hf mf wrbl
2010: HF14A_RAW
Command: : 5+N bytes: options|resp_timeout_ms[2]|bitlen[2] followed by data to be transmitted, with options a 1-byte BigEndian bitfield, so starting from MSB:
- activate_rf_field:1
- wait_response:1
- append_crc:1
- auto_select:1
- keep_rf_field:1
- check_response_crc:1
- reserved:2
Response: data sent by the card
CLI: cf hf 14a raw
2011: MF1_MANIPULATE_VALUE_BLOCK
Command: 21 bytes: src_type|src_block|src_key[6]|operator|operand[4]|dst_type|dst_block|dst_key[6]. Key as 6 bytes. Type=0x60 for key A, 0x61 for key B. Operator=0xC0 for decrement, 0xC1 for increment, 0xC2 for restore. Operand as I32 in Network byte order.
Response: no data
CLI: cf hf mf value
2012: MF1_CHECK_KEYS_OF_SECTORS
Command: 10+N*6 bytes: mask[10]|keys[N][6] (1<=N<=83)
- mask: 40 sectors, 2 bits/sector, MSB: 0A|0B|1A|1B|...|39A|39B. 0b1 represent to skip checking the key.
Response: 490 bytes: found[10]|sectorKey[40][2][6].
- found: 40 sectors, 2 bits/sector, MSB: 0A|0B|1A|1B|...|39A|39B. 0b1 represent the key is found.
- sectorKey: 40 sectors, 2 keys/sector, 6 bytes/key: key0A[6]|key0B[6]|key1A[6]|key1B[6]|...|key39A[6]|key39B[6]
CLI: cf hf mf fchk
3000: EM410X_SCAN
Command: no data
Response: 5 bytes. id[5]. ID as 5 bytes.
CLI: cf lf em 410x read
3001: EM410X_WRITE_TO_T55XX
Command: 9+N*4 bytes: id[5]|new_key[4]|old_key1[4]|old_key2[4]|... (N>=1). . ID as 5 bytes. Keys as 4 bytes.
Response: no data
CLI: cf lf em 410x write
3002: HIDPROX_SCAN
Command: no data
Response: 13 bytes: format[1]|facility_code[4]|card_number[5]|issue_level[1]|oem[2].
CLI: cf lf hid prox read
3003: HIDPROX_WRITE_TO_T55XX
Command: 17+N*4 bytes: format[1]|facility_code[4]|card_number[5]|issue_level[1]|oem[2]|new_key[4]|old_key1[4]|old_key2[4]|... (N>=1). Keys as 4 bytes.
Response: no data
CLI: cf lf hid prox write
4000: MF1_WRITE_EMU_BLOCK_DATA
Command: 1+N*16 bytes: block_start|block_data1[16]|block_data2[16]|... (1<=N<=31)
Response: no data
CLI: cf hf mf eload
4001: HF14A_SET_ANTI_COLL_DATA
Command: N bytes: uidlen|uid[uidlen]|atqa[2]|sak|atslen|ats[atslen]. UID, ATQA, SAK and ATS as bytes.
Response: no data
CLI: cf hf mf econfig/hf mfu econfig
4004: MF1_SET_DETECTION_ENABLE
Command: 1 byte, bool = 0x00 or 0x01
Response: no data
CLI: cf hf mf econfig
4005: MF1_GET_DETECTION_COUNT
Command: no data
Response: 4 bytes, count[4], U32 in Network byte order.
CLI: cf hf mf elog
4006: MF1_GET_DETECTION_LOG
Command: 4 bytes, index, U32 in Network byte order.
Response: N*18 bytes. 0<=N<=28
- block
- ...|is_nested|is_key_b 1-byte bitfield, starting from LSB
- uid[4] ?
- nt[4] ?
- nr[4] ?
- ar[4] ?
CLI: cf hf mf elog
4007: MF1_GET_DETECTION_ENABLE
Command: no data
Response: 1 byte, bool = 0x00 or 0x01
CLI: cf hw slot list
4008: MF1_READ_EMU_BLOCK_DATA
Command: 2 bytes: block_start|block_count with 1<=block_count <=32
Response: block_count*16 bytes
CLI: cf hf mf eread
4009: MF1_GET_EMULATOR_CONFIG
Command: no data
Response: 5 bytes
- detection, cf MF1_GET_DETECTION_ENABLE
- gen1a_mode, cf MF1_GET_GEN1A_MODE
- gen2_mode, cf MF1_GET_GEN2_MODE
- block_anti_coll_mode, cf MF1_GET_BLOCK_ANTI_COLL_MODE
- write_mode, cf MF1_GET_WRITE_MODE
CLI: cf hf mf econfig
4010: MF1_GET_GEN1A_MODE
Command: no data
Response: 1 byte, bool = 0x00 or 0x01
CLI: unused
4011: MF1_SET_GEN1A_MODE
Command: 1 byte, bool = 0x00 or 0x01
Response: no data
CLI: cf hf mf econfig
4012: MF1_GET_GEN2_MODE
Command: no data
Response: 1 byte, bool = 0x00 or 0x01
CLI: unused
4013: MF1_SET_GEN2_MODE
Command: 1 byte, bool = 0x00 or 0x01
Response: no data
CLI: cf hf mf econfig
4014: MF1_GET_BLOCK_ANTI_COLL_MODE
Command: no data
Response: 1 byte, bool = 0x00 or 0x01
CLI: unused
4015: MF1_SET_BLOCK_ANTI_COLL_MODE
Command: 1 byte, bool = 0x00 or 0x01
Response: no data
CLI: cf hf mf econfig
4016: MF1_GET_WRITE_MODE
Command: no data
Response: 1 byte, according to nfc_tag_mf1_write_mode_t aka MifareClassicWriteMode enum
CLI: unused
4017: MF1_SET_WRITE_MODE
Command: 1 byte, according to nfc_tag_mf1_write_mode_t aka MifareClassicWriteMode enum
Response: no data
CLI: cf hf mf econfig
4018: HF14A_GET_ANTI_COLL_DATA
Command: no data
Response: no data or N bytes: uidlen|uid[uidlen]|atqa[2]|sak|atslen|ats[atslen]. UID, ATQA, SAK and ATS as bytes.
CLI: cf hw slot list/hf mf econfig/hf mfu econfig
4019: MF0_NTAG_GET_UID_MAGIC_MODE
Command: no data
Response: 1 byte where a non-zero value indicates that UID magic mode is enabled for the current slot.
CLI: cf hf mfu econfig
4020: MF0_NTAG_SET_UID_MAGIC_MODE
Command: 1 byte where a non-zero value indicates that UID magic mode should be enabled for the current slot, otherwise disabled.
Response: no data
CLI: cf hf mfu econfig --enable-uid-magic/hf mfu econfig --disable-uid-magic
4021: MF0_NTAG_READ_EMU_PAGE_DATA
Command: 2 bytes: one for first page index, one for count of pages to be read.
Response: 4 * n bytes where n is the number if pages to be read
CLI: cf hf mfu eview
4022: MF0_NTAG_WRITE_EMU_PAGE_DATA
Command: 2 + n * 4 bytes: one for first page index, one for count of pages to be read, n * 4 for n pages data.
Response: no data
CLI: unused
4023: MF0_NTAG_GET_VERSION_DATA
Command: no data
Response: 8 version data bytes.
CLI: cf hf mfu econfig
4024: MF0_NTAG_SET_VERSION_DATA
Command: 8 version data bytes.
Response: no data
CLI: cf hf mfu econfig --set-version <hex>
4025: MF0_NTAG_GET_SIGNATURE_DATA
Command: no data
Response: 32 signature data bytes.
CLI: cf hf mfu econfig
4026: MF0_NTAG_SET_SIGNATURE_DATA
Command: 32 signature data bytes.
Response: no data
CLI: cf hf mfu econfig --set-signature <hex>
4027: MF0_NTAG_GET_COUNTER_DATA
Command: 1 byte for the counter index
Response: 3 bytes for the counter value (big-endian) + 1 byte for tearing where 0xBD means tearing flag is not set.
CLI: cf hf mfu ercnt
4028: MF0_NTAG_SET_COUNTER_DATA
Command: 1 byte where the lower 7 bits are the counter index and the top bit indicates whether tearing event flag should be reset + 3 bytes of the counter value (big-endian).
Response: no data
CLI: cf hf mfu ewcnt
4029: MF0_NTAG_RESET_AUTH_CNT
Command: no data
Response: 1 byte for the old value of the unsuccessful auth counter.
CLI: cf hf mfu econfig --reset-auth-cnt
4030: MF0_NTAG_GET_PAGE_COUNT
Command: no data
Response: 1 byte is the number of pages available in the current card slot
CLI: unused
5000: EM410X_SET_EMU_ID
Command: 5 bytes. id[5]. ID as 5 bytes.
Response: no data
CLI: cf lf em 410x econfig
5001: EM410X_GET_EMU_ID
Command: no data
Response: 5 bytes. id[5]. ID as 5 bytes.
CLI: cf lf em 410x econfig
5002: HIDPROX_SET_EMU_ID
Command: 13 bytes: format[1]|facility_code[4]|card_number[5]|issue_level[1]|oem[2].
Response: no data
CLI: cf lf hid prox econfig
5003: HIDPROX_GET_EMU_ID
Command: no data
Response: 13 bytes: format[1]|facility_code[4]|card_number[5]|issue_level[1]|oem[2].
CLI: cf lf hid prox econfig -s 1 --fc 107 --cn 10044 --format H10301

New data payloads: guidelines for developers

If you need to define new payloads for new commands, try to follow these guidelines.

Guideline: Verbose and explicit

Be verbose, explicit and reuse conventions, in order to enhance code maintainability and understandability for the other contributors

Guideline: Structs

Define C struct for cmd/resp data greater than a single byte, use and abuse of struct.pack/struct.unpack in Python. So one can understand the payload format at a simple glimpse. Exceptions to C struct are when the formats are of variable length (but Python struct is still flexible enough to cope with such formats!)
Avoid hardcoding offsets, use sizeof(), offsetof(struct, field) in C and struct.calcsize() in Python
For complex bitfield structs, exceptionally you can use ctypes in Python. Beware ctypes.BigEndianStructure bitfield will be parsed in the firmware in the reverse order, from LSB to MSB.
Guideline: Status

If single byte of data to return, still use a 1-byte data, not status. Standard response status is STATUS_SUCCESS for general commands, STATUS_HF_TAG_OK for HF commands and STATUS_LF_TAG_OK for LF commands. If the response status is different than those, the response data is empty. Response status are generic and cover things like tag disappearance or tag non-conformities with the ISO standard. If a command needs more specific response status, it is added in the first byte of the data, to avoid cluttering the 1-byte general status enum with command-specific statuses. See e.g. MF1_DARKSIDE_ACQUIRE.

Guideline: unambiguous types
Use unambiguous types such as uint16_t, not int or enum. Cast explicitly int and enum to uint_t of proper size
Use Network byte order for 16b and 32b integers
- Macros U16NTOHS, U32NTOHL must be used on reception of a command payload.
- Macros U16HTONS, U32HTONL must be used on creation of a response payload.
- In Python, use the modifier ! with all struct.pack/struct.unpack
  Guideline: payload parsing in handlers
Concentrate payload parsing in the handlers, avoid further parsing in their callers. Callers should not care about the protocol. This is true for the firmware and the client.
In cmd_processor handlers: don’t reuse input length/data parameters for creating the response content
Guideline: Naming conventions
Use the exact same command and fields names in firmware and in client, use function names matching the command names for their handlers unless there is a very good reason not to do so. This helps grepping around. Names must start with a letter, not a number, because some languages require it (e.g. 14a_scan not possible in Python)
Respect commands order in m_data_cmd_map, data_cmd.h and chameleon_cmd.py definitions
Even if a command is not yet implemented in firmware or in client but a command number is allocated, add it to data_cmd.h and chameleon_cmd.py with some FIXME: to be implemented comment
Guideline: Validate status and data
Validate response status in client before parsing data.
Validate data before using it.

Room for improvement

some num_to_bytes bytes_to_num could use hton*, ntoh* instead, to make endianess explicit
some commands are using bitfields (e.g. mf1_get_detection_log (sending directly the flash stored format) and hf14a_raw) while some commands are spreading bits into 0x00/0x01 bytes (e.g. mf1_get_emulator_config)
describe flash storage formats

This site is open source. Improve this page.

ChameleonUltra

Protocol description

Versioning

Frame format

Data payloads

1000: GET_APP_VERSION

1001: CHANGE_DEVICE_MODE

1002: GET_DEVICE_MODE

1003: SET_ACTIVE_SLOT

1004: SET_SLOT_TAG_TYPE

1005: SET_SLOT_DATA_DEFAULT

1006: SET_SLOT_ENABLE

1007: SET_SLOT_TAG_NICK

1008: GET_SLOT_TAG_NICK

1009: SLOT_DATA_CONFIG_SAVE

1010: ENTER_BOOTLOADER

1011: GET_DEVICE_CHIP_ID

1012: GET_DEVICE_ADDRESS

1013: SAVE_SETTINGS

1014: RESET_SETTINGS

1015: SET_ANIMATION_MODE

1016: GET_ANIMATION_MODE

1017: GET_GIT_VERSION

1018: GET_ACTIVE_SLOT

1019: GET_SLOT_INFO

1020: WIPE_FDS

1021: DELETE_SLOT_TAG_NICK

1023: GET_ENABLED_SLOTS

1024: DELETE_SLOT_SENSE_TYPE

1025: GET_BATTERY_INFO

1026: GET_BUTTON_PRESS_CONFIG

1027: SET_BUTTON_PRESS_CONFIG

1028: GET_LONG_BUTTON_PRESS_CONFIG

1029: SET_LONG_BUTTON_PRESS_CONFIG

1030: SET_BLE_PAIRING_KEY

1031: GET_BLE_PAIRING_KEY

1032: DELETE_ALL_BLE_BONDS

1033: GET_DEVICE_MODEL

1034: GET_DEVICE_SETTINGS

1035: GET_DEVICE_CAPABILITIES

1036: GET_BLE_PAIRING_ENABLE

1037: SET_BLE_PAIRING_ENABLE

2000: HF14A_SCAN

2001: MF1_DETECT_SUPPORT

2002: MF1_DETECT_PRNG

2003: MF1_STATIC_NESTED_ACQUIRE

2004: MF1_DARKSIDE_ACQUIRE

2005: MF1_DETECT_NT_DIST

2006: MF1_NESTED_ACQUIRE

2007: MF1_AUTH_ONE_KEY_BLOCK

2008: MF1_READ_ONE_BLOCK

2009: MF1_WRITE_ONE_BLOCK

2010: HF14A_RAW

2011: MF1_MANIPULATE_VALUE_BLOCK

2012: MF1_CHECK_KEYS_OF_SECTORS

3000: EM410X_SCAN

3001: EM410X_WRITE_TO_T55XX

3002: HIDPROX_SCAN

3003: HIDPROX_WRITE_TO_T55XX

4000: MF1_WRITE_EMU_BLOCK_DATA

4001: HF14A_SET_ANTI_COLL_DATA

4004: MF1_SET_DETECTION_ENABLE

4005: MF1_GET_DETECTION_COUNT

4006: MF1_GET_DETECTION_LOG

4007: MF1_GET_DETECTION_ENABLE

4008: MF1_READ_EMU_BLOCK_DATA

4009: MF1_GET_EMULATOR_CONFIG

4010: MF1_GET_GEN1A_MODE

4011: MF1_SET_GEN1A_MODE

4012: MF1_GET_GEN2_MODE

4013: MF1_SET_GEN2_MODE

4014: MF1_GET_BLOCK_ANTI_COLL_MODE

4015: MF1_SET_BLOCK_ANTI_COLL_MODE

4016: MF1_GET_WRITE_MODE

4017: MF1_SET_WRITE_MODE

4018: HF14A_GET_ANTI_COLL_DATA

4019: MF0_NTAG_GET_UID_MAGIC_MODE

4020: MF0_NTAG_SET_UID_MAGIC_MODE

4021: MF0_NTAG_READ_EMU_PAGE_DATA

4022: MF0_NTAG_WRITE_EMU_PAGE_DATA