梯控开放能力说明

更新时间:2024-06-13 10:36:53下载pdf

本文介绍梯控开放能力接入的相关说明。

说明

梯控功能点说明

功能点相关接口,请参考 修改设备功能点

功能点 Code 说明
face_lift 支持刷脸乘梯。
qrcode_lift 支持扫二维码乘梯。
out_lift 支持外呼。
unify_lift 支持外呼联动内呼,有电梯状态上报。上报的状态包含电梯井、轿厢当前楼层和上下行方向等数据。
out_auth 支持外呼联动内呼,无电梯状态上报。
public_lift 支持公共楼层。

API 说明

梯控用户管理

API 名称 接口地址
删除人员 DELETE:/v1.0/elevator-control/{device_id}/persons/{person_id}
更新人员 PUT:/v1.0/elevator-control/{device_id}/persons/{person_id}
新增人员 POST:/v1.0/elevator-control/{device_id}/persons/{person_id}

梯控人脸管理

API 名称 接口地址
删除人脸 DELETE:/v1.0/elevator-control/{device_id}/persons/{person_id}/faces/{face_id}
新增人脸 POST:/v1.0/elevator-control/{device_id}/persons/{person_id}/faces/{face_id}
更新人脸 PUT:/v1.0/elevator-control/{device_id}/persons/{person_id}/faces/{face_id}

梯控卡管理

API 名称 接口地址
解冻梯控卡 PUT:/v1.0/elevator-control/{device_id}/persons/{person_id}/card/{card_no}/unfreeze
冻结梯控卡 PUT:/v1.0/elevator-control/{device_id}/persons/{person_id}/card/{card_no}/freeze
新增梯控卡 POST:/v1.0/elevator-control/{device_id}/persons/{person_id}/card/{card_no}
删除梯控卡 DELETE:/v1.0/elevator-control/{device_id}/persons/{person_id}/card/{card_no}

呼梯指令

API 名称 接口地址
呼梯指令发送 POST:/v1.0/elevator-control/{device_id}/persons/{person_id}/actions/call

梯控二维码管理

API 名称 接口地址
删除二维码 DELETE:/v1.0/elevator-control/{device_id}/persons/{person_id}/qrcodes/{qr_code}
更新二维码 PUT:/v1.0/elevator-control/{device_id}/persons/{person_id}/qrcodes/{qr_code}
新增二维码 POST:/v1.0/elevator-control/{device_id}/persons/{person_id}/qrcodes/{qr_code}

梯控事件格式

云开发项目 开启消息订阅 后,可以收到梯控设备端上报的事件消息。消息队列接入流程的详细介绍,请参考 消息队列

通行记录上报

功能描述

用户触发梯控通行,梯控会上报用户的通行事件给开发者。事件 Code:pass_event

value 参数说明

参数名 类型 说明 必填
uid String 通行人员 ID。如果是陌生人,默认传 -1
way Integer 通行方式。
  • 1:卡
  • 2:密码
  • 3:二维码
  • 4:人脸
  • 5:指纹
  • 9:远程
  • 10:其它
t Long 通行时间,13 位时间戳。
success Integer 是否成功。
  • 1:成功
  • 0:失败
message String 通行事件描述。如果通行失败,则返回失败原因。
picUrl String 通行照片的 URL。人员通行时,设备抓拍的人员照片。通行照片的 URL 是临时 URL,开发者需要根据 URL 下载照片并存储。
temp String 体温。
startFloor Integer 开始楼层。
endFloor Integer 结束楼层。
lifeNum Integer 电梯井号。
extend String 扩展字段。

数据示例

{
    "dataId": "AAXRV4BrtW9BRB9A2JYW****",
    "devId": "6ca****",
    "productKey": "e6rz6vba81wm****",
    "status": [
        {
            "12": "{\"message\":\"ok\",\"success\":1,\"t\":1637548630452,\"uid\":\"zs123\",\"way\":4}",
            "code": "pass_event",
            "t": 1637548630455,
            "value": "{\"message\":\"ok\",\"success\":1,\"t\":1637548630452,\"uid\":\"zs123\",\"way\":1}"
        }
    ]
}

状态监测事件上报

功能描述

上报轿厢当前楼层、上下行方向等数据。事件 Code:function_data

value 参数说明

参数名 类型 说明 必填
shaftList List 轿厢列表

ElevatorShaftDTO 参数说明

参数名 类型 说明 必填
lifeNum Integer 电梯井号。
status Integer 电梯状态。
  • 0:停止
  • 1:上行中
  • 2:下行中
  • 3:故障
direction Integer 电梯运行方向。
  • 0:上行
  • 1:下行
curFloor Integer 当前楼层,为物理楼层。

数据示例

{
    "dataId": "AAXRV4BrtW9BRB9A2JYW****",
    "devId": "6ca****",
    "productKey": "e6rz6vba81wm****",
    "status": [
        {
            "6": "{\"shaftList\":[{\"lifeNum\":1,\"curFloor\":1,\"direction\":0,\"status\":1},{\"lifeNum\":2,\"curFloor\":1,\"direction\":0,\"status\":1}]}",
            "code": "function_data",
            "t": 1637548630455,
            "value": "{\"shaftList\":[{\"lifeNum\":1,\"curFloor\":1,\"direction\":0,\"status\":1},{\"lifeNum\":2,\"curFloor\":1,\"direction\":0,\"status\":1}]}"
        }
    ]
}

其它

梯控二维码

目前二维码分为静态二维码和动态二维码。

  • 静态二维码:二维码固定不变,二维码与人员绑定,由开发者下发给设备。
  • 动态二维码:二维码定期刷新,设备端根据用户信息中的秘钥与时间因子动态生成。

梯控二维码流程

  1. 下发二维码
    • 静态二维码:开发者调用接口下发静态二维码给设备。
    • 动态二维码:开发者调用接口下发人员信息给设备,设备端根据人员信息的动态秘钥生成动态二维码。
  2. 设备端保存静态二维码,或根据人员的动态秘钥生成动态二维码。
  3. 开发者 App 端生成相应二维码。
  4. 梯控设备扫描二维码,匹配成功后,识别成功并上报通行事件。

梯控二维码格式

二维码内容格式:

{
  "qrcode": "7kCzIejJVhfwYOGGJLr1iUUPRXP69AiNMGcMhowRSVA="  //value:Base64编码后字符串
}

梯控二维码生成(App 端)

静态二维码

静态二维码生成步骤如下:

  1. 拼接二维码字符串 “uid|二维码内容”。
  2. 对 “uid|二维码内容” 进行 Base64 编码。
  3. 生成 JSON 格式的二维码内容。

示例:

    用户 ID: ay16110581781387****
    用户二维码内容: 46bff10b9bf843fab194cf246bfedda8
    对"ay16110581781387****|46bff10b9bf843fab194cf246bfedda8"进行base64编码,
    生成的字符串:      
      YXkxNjExMDU4MTc4MTM4N240Mjd8NDZiZmYxMGI5YmY4NDNmYWIxOTRjZjI0NmJmZWRkYTg=
    二维码的内容:
    {
      "qrcode": "YXkxNjExMDU4MTc4MTM4N240Mjd8NDZiZmYxMGI5YmY4NDNmYWIxOTRjZjI0NmJmZWRkYTg="
    }
动态二维码

动态二维码生成步骤如下:

  1. 通过 generateTOTP 方法生成二维码信息。
  2. 对 “uid|二维码信息” 进行 base64 编码。
  3. 生成 JSON 格式的二维码内容。

generateTOTP 方法参考代码:

/**
   * 生成动态码
   *
   * @param uid           涂鸦用户 ID
   * @param secretKey     秘钥,32 位字符串,建议由 UUID 生成
   * @param refreshTime   二维码刷新时间
   * @return
   */
  public static TOTPTokenCodeDTO generateTOTP(String uid, String secretKey, Long refreshTime) {
      if (StringUtils.isBlank(uid) || StringUtils.isBlank(secretKey) || refreshTime == null) {
          log.error("请求参数有误, uid:{}, secretKey:{}, refreshTime:{}", uid, secretKey, refreshTime);
          throw new RuntimeException("请求参数有误");
      }

      // 获取当前时间的时间戳
      long now = new Date().getTime();
      // 将动态因子转为16进制
      String time = Long.toHexString(timeFactor(now, refreshTime)).toUpperCase();
      String totp = doGenerateTOTP(uid + secretKey, time);
      //本周期动态码已生成时长
      long usedTime = validTime(now, refreshTime);
      return new TOTPTokenCodeDTO(totp, usedTime);
  }

  /**
   * @param key  用户 ID+种子密钥
   * @param time 时间因子
   * @return
   */
  private static String doGenerateTOTP(String key, String time) {
      // 1、如果 time 小于 16 个字符,则用零补齐,例如:30B649C -> 00000000030B649C
      StringBuilder timeBuilder = new StringBuilder(time);
      while (timeBuilder.length() < 16) {
          timeBuilder.insert(0, "0");
      }
      time = timeBuilder.toString();

      // 2、16 进制转 2 进制
      byte[] msg = hexStr2Bytes(time);
      // 3、将 key 转为字节
      byte[] k = key.getBytes();
      // 4、哈希加密
      byte[] hash = hmac_sha("HmacSHA256", k, msg);
      // 5、返回指定位数的动态口令
      String encodeHexStr = Hex.encodeHexString(hash);
      StringBuilder result = new StringBuilder(encodeHexStr);
      //6. 如果返回值小于指定的位数,则用 0 补齐
      while (result.length() < 8) {
          result.insert(0, "0");
      }
      return result.substring(0, 8);
  }

  /**
   * 获取动态因子
   *
   * @param targetTime 指定时间
   * @param refreshTime       时间步长,单位:毫秒。用作动态口令变化的时间周期
   * @return long
   */
  private static long timeFactor(Long targetTime, long refreshTime) {
      return targetTime / refreshTime;
  }

  /**
   * 获取本周期动态码已生成时长
   *
   * @param targetTime
   * @param refreshTime
   * @return
   */
  private static long validTime(long targetTime, long refreshTime) {
      return targetTime % refreshTime;
  }

  /**
   * 哈希加密
   *
   * @param crypto   加密算法
   * @param keyBytes 密钥数组
   * @param text     加密内容
   * @return byte[]
   */
  private static byte[] hmac_sha(String crypto, byte[] keyBytes, byte[] text) {
      try {
          Mac hmac;
          hmac = Mac.getInstance(crypto);
          SecretKeySpec macKey = new SecretKeySpec(keyBytes, "AES");
          hmac.init(macKey);
          return hmac.doFinal(text);
      } catch (GeneralSecurityException gse) {
          throw new RuntimeException(gse);
      }
  }

  private static byte[] hexStr2Bytes(String hex) {
      byte[] sourceArray = new BigInteger("10" + hex, 16).toByteArray();
      byte[] targetArray = new byte[sourceArray.length - 1];
      // 将原数组 copy 到目标数组
      // src:表示源数组,srcPos:源数组要复制的起始位置,dest:表示目标数组,destPos:目标数组要复制的起始位置,length:表示要复制的长度
      System.arraycopy(sourceArray, 1, targetArray, 0, targetArray.length);
      return targetArray;
  }

示例:

    用户 ID:ay16110581781387****
    密钥:46bff10b9bf843fab194cf246bfedda8
    二维码刷新时间:5 * 60 * 1000
    generateTOTP方法生成二维码信息:e4af23e6
    对"ay16110581781387****|e4af23e6"进行base64编码,
    生成的字符串:
    7kCzIejJVhfwYOGGJLr1iUUPRXP69AiNMGcMhowRSVA=
    二维码的内容:
    {
    "qrcode": "7kCzIejJVhfwYOGGJLr1iUUPRXP69AiNMGcMhowRSVA="
    }

梯控事件 1.0 格式

设备事件消息兼容 1.0 版本格式。如需开通 1.0 版本格式,请联系涂鸦工作人员。接入流程参考 行业三方设备事件 1.0 版本格式

通行记录上报

功能描述

用户触发梯控通行,梯控会上报用户的通行事件给开发者。

参数说明

参数名 类型 说明 必填
bizCode String 事件业务 code,默认 edge_device
eventType String 事件类型,默认 edge_report_data
mode String 事件模式,默认 elevator-pass
deviceId String 涂鸦设备 ID。
uid String 通行人员 ID。如果是陌生人,默认传 -1
way Integer 通行方式。
  • 1:卡
  • 2:密码
  • 3:二维码
  • 4:人脸
  • 5:指纹
  • 9:远程
  • 10:其它
t Long 通行时间,13 位时间戳。
success Integer 是否成功。
  • 1:成功
  • 0:失败
message String 通行事件描述。如果通行失败,则返回失败原因。
passUrl String 通行照片 URL。人员通行时,设备抓拍的人员照片。通行照片的 URL 是临时 URL,开发者需要根据 URL 下载照片并存储。
temp String 体温。
startFloor Integer 开始楼层。
endFloor Integer 结束楼层。
lifeNum Integer 电梯井号。
extend String 扩展字段。

数据示例

{
	"data": "{\"mode\":\"elevator-pass\",\"data\":\"{\\\"deviceId\\\":\\\"002dj00118fe34d9****\\\",\\\"t\\\":1612514362591,\\\"message\\\":\\\"success\\\",\\\"passUrl\\\":\\\"http://www.xxx.com/image.jpg\\\",\\\"uid\\\":\\\"ay16110581781387n***\\\",\\\"way\\\":4}\",\\\"success\\\":1}\"}",
	"bizCode": "edge_device",
	"eventType": "edge_report_data"
}