obsidian_note/各种项目/光交锁/智能锁-Android API文档.md

版本记录	时间	修改者	日志
1.0.0	2025.01.07	陈强	初版
1.1.0	2025.02.08	陈强	移除部分描述

1. **前言**

针对现在公司现有的光交锁产品进行功能合并和兼容处理，包含NFC、蓝牙读写器、蓝牙锁、USB锁等四种方式。

2. **流程图**

3. **配置**

3.1. **密钥、appID申请**

使用本SDK之前，请开发联系商务，并提供app的包名以便获取appID和密钥，后续激活SDK使用

3.2. **权限配置**

<!-- 低版本蓝牙权限兼容 -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<!-- 蓝牙操作权限 -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<!-- Android11及以上需补充以下权限 -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
<!--NFC权限-->
<uses-permission android:name="android.permission.NFC" />
<uses-feature
android:name="android.hardware.nfc"
android:required="true" />
<!--USB权限-->
<uses-feature android:name="android.hardware.usb.host" />
<uses-permission android:name="android.permission.USB_PERMISSION" />

3.3. 开锁密码

开锁时，需要对应的密码，集成SDK时建议做好密码管理。开锁时传入对应的密码。

4. **参数说明**

4.1. **接口数据（采用Map集合）**

键（key）	值（value)	类型	备注
lockStatus	1或0	String	1：开启 0：关闭
nfcElectricity		String	NF电量
solarEnergyElectricity		String	太阳能电量
batteryElectricity		String	电池电量
lockBeamStatus	1或0	String	锁梁状态（运营商锁） 1：已脱落 0：锁梁正常
lockTypeC	1或0	String	TypeC状态（运营商锁） 1：已连接 0：未连接
lockBle	1或0	String	蓝牙状态（运营商锁） 1：已连接 0：未连接
birth		String	出厂日期（运营商锁）
version		String	固件版本号
hardwareVersion		String	硬件版本号
sn		String	智能锁序号
unlockTimes		String	开锁次数
status		String	网络状态（NB锁）
pw		String	网络信号强度（NB锁）
read		String	读取MCU状态
open		String	读取传感器状态（门状态）
localStatus		String	读取传感器状态（锁舌状态）

4.2. **设备枚举类型**

**MkdLockTypeEnum（设备类型）**

类型	说明
MKD_LOCK_TYPE_NFC	通过手机的NFC功能实现开锁，适用于支持NFC功能的设备
MKD_LOCK_TYPE_READER	利用蓝牙读写器进行开锁，适合需要通过蓝牙连接的场景
MKD_LOCK_TYPE_BLE	通过手机蓝牙与锁具连接进行开锁
MKD_LOCK_TYPE_USB	通过手机外接USB设备实现开锁，适用于需要物理连接的情况

5. **接入流程**

5.1. **管理类-****MkdLockManagerNewer**

5.2. **激活SDK**

/**
     * 初始化鉴权
     *
     * @param appID     AppID
     * @param appSecret 密钥
     * @return boolean true：激活成功  false：激活失败
     */
public boolean initWithAppID(String appID, String appSecret,Application application)

5.3. **设备类型设置**

/**
     * 根据不同的锁类型切换当前的锁类型
     * 此方法主要用于在应用中切换锁的类型，以便适应不同的安全或使用需求
     *
     * @param mkdLockTypeEnum 新的锁类型，通过MkdLockTypeEnum枚举指定
     */
public void changeCurrentLockType(MkdLockTypeEnum mkdLockTypeEnum)

5.4. **蓝牙**

5.4.1. **设备搜索**

/**
     * 开始搜索设备
     *
     * @param timeOut      超时设置
     * @param scanListener 设备搜索回调
     */
void startScan(int timeOut, MkdScanListener scanListener);

public interface MkdScanListener {
    //开始扫描
    void onScanStart();

    //停止扫描
    void onScanStop();

    //获取扫描结果
    void onScanResult(Device device, boolean isConnectedBySys);

    //扫描错误
    void onScanError(String errorMsg);
}

5.4.2. **停止搜索**

public void stopScan()

5.4.3. **设置搜索过滤条件**

public void setDeviceScanPrefix(String... prefix)

5.4.4. **设备连接**

/**
     * 连接设备
     * @param device 设备对象
     * @param listener 连接监听器
     */
public void connectDevice(Device device, MkdBleConnectListener listener)

/**
     * 连接设备
     * @param device 设备标识字符串
     * @param listener 连接监听器
     */
public void connectDevice(String device, MkdBleConnectListener listener)

public interface MkdBleConnectListener {
    void connectSuccess (Device device);
    void connectFailed(String msg);
    void connectClose();
}

5.4.5. **设备断开**

public void disConnectDevice()

5.4.6. **释放资源**

public void releaseAllConnection()

5.4.7. **其他**

//是否真正扫描设备中
public boolean isScanning()
//移除扫描监听
public void removeScanListener()
//是否连接设备
public boolean isBleDeviceConnect()

5.5. **NFC**

5.5.1. **NFC Tag监听**

//注意：此处未使用onNewIntent方式来获取NFC Tag的方式，是由于在部分手机设备上
//存在Intent携带的Tag为null，导致无法使用NFC
NfcAdapter mNfcAdapter = NfcAdapter.getDefaultAdapter(activity);
mNfcAdapter.enableReaderMode(activity, new NfcAdapter.ReaderCallback() {
    @Override
    public void onTagDiscovered(Tag tag) {
        Log.e("onTagDiscovered", "tag = " + tag);
        //接收获取的NFC 信息便于后续连接处理
    }
}, NfcAdapter.FLAG_READER_NFC_A | NfcAdapter.FLAG_READER_NFC_B | NfcAdapter.FLAG_READER_NFC_F | NfcAdapter.FLAG_READER_NFC_V | NfcAdapter.FLAG_READER_SKIP_NDEF_CHECK, null);

5.5.2. **创建NFC意图**

public void createPendingIntent(Activity activity)

5.5.3. **开启NFC前台分发**

public void enableForegroundDispatch(Activity activity)

5.5.4. **关闭NFC前台分发**

public void disableForegroundDispatch(Activity activity)

5.5.5. **连接NFC**

public void connectTag(Tag mTag, MkdNfcConnectStatusListener listener)

public interface MkdNfcConnectStatusListener {

    /**
     * 连接状态
     * @param status true已连接 false未连接
     */
    void connectStatus(boolean status);
}

5.6. **API方法**

5.6.1. **添加蓝牙读写器寻卡监听**

public void addReceiveRWSearchCardListener(MkdLockManagerListener listener)

5.6.1.1. **返回****数据**

参数key	类型	值	说明
hasCard	String	“1”or"0"	"1":有卡 “0”:无卡
uid	String		锁mac地址
protocol	String		寻卡的类型： “default”：全部 “ISO14443A”：14443A NFC协议 “ISO14443B”：14443B NFC协议 “ISO15693”：15693 NFC协议

5.6.2. **查询蓝牙读写器状态**

public void queryBleReaderWriterStatus(MkdLockManagerListener listener)

5.6.2.1. **返回****数据**

参数key	类型	值	说明
rwPowerMV	String		读写器电量
rwPowerPercent	String		读写器电量百分比
rwHW	String		读写硬件版本
rwSW	String		读写器软件版本

5.6.3. **读取锁的基本信息**

public void readLockBasicInfoSuccess(MkdLockManagerListener listener)

5.6.3.1. **返回****数据**

参数key	类型	值	说明
sn	String		锁序号
mac	String		锁mac地址

5.6.4. **读取锁的状态和电量**

public void readStatusAndElectricity( MkdLockManagerListener listener)

5.6.4.1. **返回****数据**

参数key	类型	值	说明
lockStatus	String	1或0	1：开启 0：关闭
nfcElectricity	String		NF电量
solarEnergyElectricity	String		太阳能电量
batteryElectricity	String		电池电量
lockBeamStatus	String	1或0	锁梁状态（LK02-BT运营商锁） 1：已连接 0：未连接
lockTypeC	String	1或0	TypeC状态（LK02-BT运营商锁） 1：已连接 0：未连接
lockBle	String	1或0	蓝牙状态（LK02-BT运营商锁） 1：已连接 0：未连接
birth	String		出厂日期（LK02-BT运营商锁）

5.6.5. **读取开锁次数**

public void readUnlockTimes(MkdLockManagerListener listener)

5.6.5.1. **返回****数据**

参数key	类型	值	说明
unlockTimes	String		累计的开锁次数

5.6.6. **读取锁的固件版本**

public void readFWVersion(MkdLockManagerListener listener)

5.6.6.1. **返回****数据**

参数key	类型	值	说明
version	String		固件版本号
hardwareVersion	String		硬件版本号

5.6.7. **密钥开锁**

//encryptedPassword：获取的开锁密钥
//listener：开锁结果回调，包含充电进度、开锁失败、开锁成功
public void unlockWithSecretKey(String encryptedPassword, MkdLockManagerProgressListener listener)

5.6.8. **资源释放**

public void release()