云快充 1.6主要解決充電樁與運(yùn)營平臺之間的通信，二維碼顯示并沒有統(tǒng)一命令。實(shí)際項(xiàng)目中，不同設(shè)備廠商會在基礎(chǔ)協(xié)議上增加私有擴(kuò)展：有的只下發(fā) URL前綴，由充電樁拼接樁號和槍號；有的按槍下發(fā)完整 URL；還有的使用固定長度字段保存二維碼內(nèi)容。

本文根據(jù)三組項(xiàng)目材料，對這些擴(kuò)展進(jìn)行統(tǒng)一設(shè)計。由于材料沒有標(biāo)注公司歸屬，文中以“擴(kuò)展A、B、C”代稱。生產(chǎn)實(shí)施仍應(yīng)以設(shè)備廠商確認(rèn)的協(xié)議版本和真機(jī)聯(lián)調(diào)結(jié)果為準(zhǔn)。

一、三種擴(kuò)展有什么區(qū)別

對比項(xiàng)

擴(kuò)展A：前綴拼接

擴(kuò)展 B：完整URL

擴(kuò)展C：固定內(nèi)容

下發(fā)/應(yīng)答命令

0xF0 / 0xF1

0x9C / 0x9B

0x5A / 0x59

下發(fā)范圍

整樁

單槍

單槍

樁編號

BCD 7 字節(jié)

下發(fā)數(shù)據(jù)域不攜帶

BCD 7 字節(jié)

槍號

由格式?jīng)Q定是否拼接

BIN 1 字節(jié)

BCD 1 字節(jié)

二維碼內(nèi)容

ASCII 變長前綴

ASCII 變長 URL

ASCII 固定 150 字節(jié)

長度字段

BIN 1 字節(jié)

BIN 2 字節(jié)

無

Zui大長度

200 字節(jié)

200 字節(jié)

固定 150 字節(jié)

成功碼

0x00

0x01

0x01

Zui容易出錯的地方有三個：

0xF1 的 0x00表示成功，而 0x9B、0x59 的 0x01 才表示成功；

擴(kuò)展 B 的槍號是 BIN，擴(kuò)展 C 的槍號是BCD；

長度是編碼后的字節(jié)數(shù)，不是 Java 字符串長度。

二、三種協(xié)議的數(shù)據(jù)域擴(kuò)展 A：0xF0/0xF1

0xF0 下發(fā)數(shù)據(jù)域：

字段

類型

長度

說明

樁編號

BCD

7 字節(jié)

14 位編號，不足補(bǔ)零

二維碼格式

BIN

1 字節(jié)

0x00 或 0x01

前綴長度

BIN

1 字節(jié)

不超過 200

二維碼前綴

ASCII

變長

URL 前綴

兩種格式的拼接規(guī)則為：

代碼語言：JavaScript

自動換行

AI代碼解釋

格式 0：前綴 + 14 位樁編號
格式 1：前綴 + 14 位樁編號 + 2 位槍編號

例如：

代碼語言：JavaScript

自動換行

AI代碼解釋

前綴：https:///?No=樁號：34220001000233格式0：https:///?No=34220001000233格式1：https:///?No=3422000100023301

0xF1 應(yīng)答由 7 字節(jié) BCD 樁編號和 1字節(jié)結(jié)果組成：0x00 成功，0x01 失敗。

擴(kuò)展 B：0x9C/0x9B

0x9C 按槍下發(fā)完整 URL：

字段

類型

長度

說明

槍號

BIN

1 字節(jié)

充電槍號

URL 長度

BIN

2 字節(jié)

ASCII 字節(jié)數(shù)

URL

ASCII

變長

Zui大 200 字節(jié)

該命令不攜帶樁編號，目標(biāo)設(shè)備由當(dāng)前TCP 會話確定。URL長度字段的端序在材料中沒有明確說明，必須通過廠商黃金報文或真機(jī)測試確認(rèn)，不能根據(jù) Java 默認(rèn)端序猜測。

0x9B 應(yīng)答由 7 字節(jié) BCD 樁編號、1 字節(jié)BIN 槍號和 1 字節(jié)結(jié)果組成：0x00 失敗，0x01 成功。

擴(kuò)展 C：0x5A/0x59

0x5A 下發(fā)固定長度二維碼內(nèi)容：

字段

類型

長度

說明

樁編號

BCD

7 字節(jié)

14 位編號，不足補(bǔ)零

槍號

BCD

1 字節(jié)

0x01 表示 1 號槍

二維碼內(nèi)容

ASCII

固定 150 字節(jié)

不足補(bǔ) 0x00

二維碼內(nèi)容可以采用：

代碼語言：JavaScript

自動換行

AI代碼解釋

https:///qr?c=<設(shè)備編號><槍號>

0x59 應(yīng)答由樁編號、BCD槍號和設(shè)置結(jié)果組成：0x00 失敗，0x01 成功。固定內(nèi)容域必須補(bǔ)足 150 字節(jié)，不能省略尾部的0x00。

三、兼容層設(shè)計

三種擴(kuò)展應(yīng)復(fù)用現(xiàn)有云快充 1.6基礎(chǔ)幀，只負(fù)責(zé)命令數(shù)據(jù)域：

代碼語言：JavaScript

自動換行

AI代碼解釋

業(yè)務(wù)配置
 -> 二維碼擴(kuò)展適配器
 -> 數(shù)據(jù)域 byte[]
 -> 云快充基礎(chǔ)幀編碼器
 -> TCP 會話

通過設(shè)備型號和固件版本選擇適配器，不要只根據(jù)品牌名稱判斷。同一廠商的不同固件也可能使用不同命令。

展開

代碼語言：JavaScript

自動換行

AI代碼解釋

public enum {
   PREFIX_F0_F1,
   URL_9C_9B,
   FIXED_5A_59}
public interface {
    protocol();
    encode( setting, ility);
   QrAck decodeAck(byte frameType, ByteBufferpayload);
}
public record (byte frameType, byte[] payload) {}
publicrAck(
    protocol,
   String deviceNo,
   Integer connectorNo,
   boolean success,
   int rawResult
) {}

能力配置至少包含協(xié)議類型、Zui大長度、長度字段端序、斷電是否保存以及登錄后是否需要重發(fā)。找不到明確配置時，不要輪流嘗試三個命令，以免舊固件錯誤處理未知幀。

四、Java 編碼實(shí)現(xiàn)

先把 14 位樁號轉(zhuǎn)換為 7 字節(jié)BCD：

展開

代碼語言：JavaScript

自動換行

AI代碼解釋

static byte[] encodeDeviceNo(String value) {
   if (value == null || !value.matches("\\d{1,14}")){
       throw newIllegalArgumentException("invalid deviceNo");
   }
   String digits = "0".repeat(14 - value.length()) +value;
   byte[] result = new byte[7];
   for (int i = 0; i < result.length; i++) {
       int high = digits.charAt(i * 2) -'0';
       int low = digits.charAt(i * 2 + 1) -'0';
       result[i] = (byte) ((high << 4) |low);
   }
   return result;
}static byte encodeBcd(int value) {
   if (value < 0 || value > 99) {
       throw new IllegalArgumentException("BCDvalue out of range");
   }
   return (byte) (((value / 10) << 4) | value %10);
}

三種數(shù)據(jù)域的核心編碼如下：

展開

代碼語言：JavaScript

自動換行

AI代碼解釋

https:// 0xF0：樁號 + 格式 + 一字節(jié)長度 + 前綴static byte[] encodeF0(StringdeviceNo, int format, byte[] prefix) {
   if (prefix.length > 200) throw newIllegalArgumentException("prefix too long");
   ByteBuffer out = ByteBuffer.allocate(9 +prefix.length);
   return out.put(encodeDeviceNo(deviceNo))
       .put((byte) format)
       .put((byte) prefix.length)
       .put(prefix)
       .array();
}https:// 0x9C：BIN 槍號 + 兩字節(jié)長度 + 完整 URLstatic byte[] encode9c(intconnector, byte[] url, ByteOrder byteOrder) {
   if (url.length > 200) throw newIllegalArgumentException("url too long");
   ByteBuffer out = ByteBuffer.allocate(3 +url.length).order(byteOrder);
   return out.put((byte) connector)
       .putShort((short) url.length)
       .put(url)
       .array();
}https:// 0x5A：樁號 + BCD 槍號 + 固定 150 字節(jié)內(nèi)容static byte[] encode5a(StringdeviceNo, int connector, byte[] content) {
   if (content.length > 150) throw newIllegalArgumentException("content too long");
   ByteBuffer out = ByteBuffer.allocate(158);
  out.put(encodeDeviceNo(deviceNo)).put(encodeBcd(connector)).put(content);
   while (out.hasRemaining()) out.put((byte) 0x00);
   return out.array();
}

調(diào)用前還要嚴(yán)格校驗(yàn)ASCII。不要直接用字符數(shù)作為長度，也不要讓不可編碼字符被靜默替換為問號。若 URL 中包含中文，應(yīng)先完成百分號編碼，再檢查Zui終ASCII 字節(jié)數(shù)。

應(yīng)答解析也必須歸屬具體適配器：

代碼語言：JavaScript

自動換行

AI代碼解釋

boolean success = switch (protocol) {
   case PREFIX_F0_F1 -> rawResult == 0x00;
   case URL_9C_9B, FIXED_5A_59 -> rawResult ==0x01;
};

五、下發(fā)與重試

二維碼設(shè)置應(yīng)作為異步任務(wù)處理：

代碼語言：JavaScript

自動換行

AI代碼解釋

PENDING -> SENT -> ACK_SUCCESS
               ->ACK_FAILED
               ->TIMEOUT

擴(kuò)展 A的應(yīng)答不帶槍號，可按設(shè)備會話和協(xié)議序列號關(guān)聯(lián)；擴(kuò)展 B、C 還應(yīng)校驗(yàn)槍號。收到重復(fù)應(yīng)答時保持冪等。

設(shè)備斷電后是否保存二維碼，各材料沒有統(tǒng)一結(jié)論。平臺可以維護(hù)“期望配置版本”和“設(shè)備Zui后確認(rèn)版本”，在設(shè)備登錄后按能力配置決定是否重發(fā)。擴(kuò)展A 下發(fā)一次，擴(kuò)展 B、C 按槍下發(fā)。

超時不代表設(shè)備一定沒有寫入，因此重試必須可冪等。同一槍存在多條待處理任務(wù)時，只發(fā)送Zui新配置；格式錯誤、長度超限和能力不匹配不應(yīng)重試。

六、二維碼內(nèi)容設(shè)計

二維碼盡量使用 HTTPS短鏈接：

代碼語言：JavaScript

自動換行

AI代碼解釋

https:///c/4Yp7kN2m

不要在 URL中放入手機(jī)號、用戶令牌、價格或內(nèi)部數(shù)據(jù)庫主鍵。掃碼后由服務(wù)端把公開 ID映射到設(shè)備和槍口。

協(xié)議允許 150 或 200字節(jié)，不代表應(yīng)該用滿。URL越長，二維碼越密，在小尺寸或低分辨率屏幕上的識別率越差。優(yōu)先使用短域名、短路徑和服務(wù)端映射。

協(xié)議日志記錄設(shè)備號、槍號、命令碼、序列號、內(nèi)容哈希、長度和結(jié)果碼即可，默認(rèn)不要打印完整URL。

七、測試重點(diǎn)

上線前至少覆蓋以下用例：

用例

預(yù)期結(jié)果

14 位樁號

編碼為 7 字節(jié) BCD

擴(kuò)展 B 的 12 號槍

BIN 0x0C

擴(kuò)展 C 的 12 號槍

BCD 0x12

URL 為 200 字節(jié)

允許

URL 為 201 字節(jié)

拒絕

擴(kuò)展 C 內(nèi)容不足 150 字節(jié)

補(bǔ) 0x00

0xF1 返回 00

成功

0x9B、0x59返回 01

成功

應(yīng)答長度不正確

拒絕解析

每種擴(kuò)展還需要一組廠商確認(rèn)的完整十六進(jìn)制報文，逐字節(jié)驗(yàn)證編碼結(jié)果。真機(jī)測試不能只看應(yīng)答成功，還要確認(rèn)二維碼是否顯示在正確槍口、掃碼內(nèi)容是否完全一致，以及斷電重啟后是否需要重新下發(fā)。

總結(jié)

云快充二維碼擴(kuò)展的難點(diǎn)不在生成二維碼，而在兼容協(xié)議差異：0xF0/0xF1下發(fā)前綴，0x9C/0x9B按槍下發(fā)變長 URL，0x5A/0x59下發(fā)固定 150字節(jié)內(nèi)容。三者的槍號編碼、長度字段和成功碼并不統(tǒng)一。

實(shí)現(xiàn)時應(yīng)保留統(tǒng)一的云快充基礎(chǔ)幀，為每種擴(kuò)展建立獨(dú)立適配器，并根據(jù)設(shè)備型號和固件能力選擇協(xié)議。端序、BCD補(bǔ)零方向和斷電保存策略等材料未明確的內(nèi)容，必須通過廠商確認(rèn)和真機(jī)測試后再上線。

本文中的域名、樁號和二維碼內(nèi)容均為演示數(shù)據(jù)，命令定義來自項(xiàng)目提供的三份擴(kuò)展材料，不代表公開行業(yè)標(biāo)準(zhǔn)。