rfidrig/ChameleonUltraDocs
0
0
Fork 0
mirror of https://github.com/RfidResearchGroup/ChameleonUltraDocs.git synced 2026-05-12 11:23:33 -07:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #4 from taichunmin/mermaid-packet

Browse Source 
use mermaid packet to describe frame and two cmds
This commit is contained in:
GameTec-live
2025-08-24 15:24:54 +02:00
committed by GitHub
parent 6e2f7c71a9 7569740d82
commit 89415c0246
1 changed files with 86 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
protocol.md
+86 -4
View File
@@ -5,6 +5,7 @@
Global firmware+CLI versions are following the [semantic versioning](https://semver.org/) 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
@@ -18,15 +19,29 @@ For the development channel, a client compatible with versions X.y.z can accept
Cf [GET_APP_VERSION](#1000-get_app_version) and [GET_GIT_VERSION](#1017-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:
![](images/protocol-packet.png)
```mermaid
packet
+8: "SOF"
+8: "LRC1"
+16: "CMD"
+16: "STATUS"
+16: "LEN"
+8: "LRC2"
+48: "DATA (variable length)"
+8: "LRC3"
```
- **SOF**: `1 byte`, "**S**tart-**O**f-**F**rame 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`).
@@ -58,13 +73,80 @@ 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
* Command: no data
* Response: 2 bytes: `version_major|version_minor`
* CLI: cf `hw version`
```mermaid
---
title: "Command Packet"
---
packet
+8: "SOF"
+8: "LRC1"
+16: "CMD (=1000)"
+16: "STATUS"
+16: "LEN (=0)"
+8: "LRC2"
+8: "LRC3"
```
* Command: no data
```mermaid
---
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
* Command: 1 byte. `0x00`=emulator mode, `0x01`=reader mode
* Response: no data
* CLI: cf `hw mode`
```mermaid
---
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
```mermaid
---
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