openydt-device

openydt-device — デバイス制御ドメイン (device)

重要：開始前に必ず Read ツールを使って ../openydt-shared/SKILL.md を読み込んでください（認証／profile／署名／ステータスコード／レート制限／安全ルール）。共有基盤を読まずにコマンドを実行しないでください。

このスキルを使用するタイミング

ユーザーの意図が「駐車場の現場デバイスに指示を出す、またはデバイスの状態を読み取る」場合にこのスキルを使用します。例：ゲートのリモート開閉、ゲートを常時開放モードに切り替える、ディスプレイにテキストを送信する、デバイスに音声を再生させる／呼びかけをさせる、車両を撮影する、クラウドスキャン端末を制御する（スキャン開始／停止／音声／設定更新）、デバイスのオンライン状態を確認する。

意図の振り分け:

• 「ゲートを開ける／閉める／バーを上げる／下ろす／ドアをリモートで開ける」→ 従来型／クラウド施設では op-gate を使用します。純粋なクラウド施設でチャネル ID による開閉を行う場合は cloud-open-gate を使用します。
• 「常時開放／通常状態に戻す／ゲートモードを変更する」→ change-channel-mode。
• 「ディスプレイ／LED 表示／音声再生／呼びかけ」→ op-show-voice。デフォルトの画面表示画像のスライドショーを設定する場合は set-default-screen。
• 「撮影／写真撮影」→ channel-snap。
• 「スキャン端末／QR コード決済デバイス」→ スキャンは cloud-scan-qr-code、停止は cloud-stop-scan-code、音声は cloud-scan-voice、設定更新は cloud-scan-update-config。
• 「デバイスの状態／オンラインかどうか」→ get-cloud-equip-status。

現場デバイスに関係しない照会（駐車中の車両、注文、月極券、クーポン）には、対応する業務ドメインのスキル（openydt parking／openydt trade／openydt ticket／openydt coupon など）を使用してください。

使用可能なコマンド

中国語名	コマンド	読み取り／書き込み	主なパラメーター
一体型ゲートのモードを変更	openydt device change-channel-mode	書き込み	parkCode, channelCode, mode(0常時開放/1通常)
手動撮影	openydt device channel-snap	書き込み	parkCode, channelCode, operator(任意)
クラウド施設のチャネルゲート開閉	openydt device cloud-open-gate	書き込み	parkCode, channelId, opType(0開/1閉)
スキャン端末にスキャンを指示	openydt device cloud-scan-qr-code	書き込み	parkCode, scanMachineId, deviceType, timeLength, voiceType
スキャン端末の設定を更新	openydt device cloud-scan-update-config	書き込み	scanMachineId, channelId
スキャン端末で音声を再生	openydt device cloud-scan-voice	書き込み	parkCode, scanMachineId, voiceType, voiceNum, voiceInterval
スキャン端末のスキャンを停止	openydt device cloud-stop-scan-code	書き込み	parkCode, scanMachineId, deviceType(任意)
クラウドデバイスの状態を取得	openydt device get-cloud-equip-status	読み取り	equipType(0一体型/2カード端末/3スキャン端末), clientId
ゲートを開閉	openydt device op-gate	書き込み	parkCode, channelCode, opType(0開/1閉), operator, operateTime, carNo(任意)
ディスプレイ／音声再生	openydt device op-show-voice	書き込み	parkCode, channelCode, show/voice(少なくとも一方), qrCode(任意), operator, operateTime
デフォルトの画面表示内容を設定	openydt device set-default-screen	書き込み	parkCode, deviceType, channelCode, templateData.imageArray

get-cloud-equip-status（読み取り）を除き、上記はすべて書き込み操作です。実行時には --yes を付けて確認する必要があります。

⚠️ channel-snap を使用するには、チャネルに撮影デバイスが必要です。resultCode=908 找不到设备 が返された場合、そのチャネルには撮影デバイスがありません。別のチャネルを試してください。

表に記載されていないデバイスドメインの呼び出し可能な API（setLeavePrompt／removeLeavePrompt／setShowMsg／setVipShowMsg／addMidAccount／scanMachineFlow）は、openydt api <cmd> --body '{...}' で呼び出してください（書き込みには --yes を付け、事前に --dry-run を実行してください）。詳細は [[openydt-api-explorer]] を参照してください。

业务流程

设备控制属于直接作用于现场硬件的高危操作。标准顺序:先定位设备 → 干预前可先查状态 → 用 --dry-run 预览 → 确认无误再加 --yes 真正下发。务必把前序命令响应里的字段透传到后续命令入参,不要手填臆测值。

1. 定位通道 / 设备:在停车场域(openydt parking / openydt park)拿到 parkCode、通道 channelCode 或 channelId、设备 scanMachineId / clientId。这些是后续所有设备命令的入参来源。

2. (可选)先查设备在线状态:对云端设备先跑 get-cloud-equip-status(equipType + clientId),响应里设备在线/状态字段确认设备可用,再决定是否下发指令。clientId 即扫码机的 scanMachineId。

3. 预览写指令(高危,务必先 dry-run):对 op-gate、cloud-open-gate、op-show-voice、change-channel-mode、set-default-screen、channel-snap 及扫码机系列命令,先用 --dry-run 查看将要发送的请求体与目标,核对 parkCode / channelCode / channelId / opType 等无误。

4. 确认下发:复核 dry-run 输出后,把同一组参数加 --yes 正式执行。

   • 开关闸:传统场/云场用 op-gate(channelCode + opType);纯云场按通道 ID 用 cloud-open-gate(用第 1 步拿到的 channelId 而非 channelCode)。
   • 闸机常开:change-channel-mode(mode=0 常开 / mode=1 正常)。
   • 屏显/喊话:op-show-voice(show 与 voice 至少给一个);扫码机喊话用 cloud-scan-voice(scanMachineId 取自第 1/2 步)。
   • 扫码流程:cloud-scan-qr-code 开始扫码 →(需要时)cloud-scan-voice 提示 → cloud-stop-scan-code 停止,三者复用同一 scanMachineId。

5. 核对结果:看返回状态码(参见基座规范)。开关闸等动作可再次 get-cloud-equip-status 或在停车场域复查在场记录确认生效。

📖 结果解读:开关闸/抓拍 status=1 表示指令已下发,不等于物理动作完成——以 get-cloud-equip-status 在线状态或停车场域复查为准。三层判读见 [[openydt-shared]] 的 references/result-reading-sop.md。 🔑 重复下发风险:开关闸/抓拍/扫码无幂等键,网关 404 触发的自动重试可能重复开闸/抓拍。高危写先 dry-run、单次执行,不确定是否生效用 get-cloud-equip-status 复查而非盲目重发。详见 [[openydt-shared]] 的 references/write-idempotency.md。

错误自愈速查（设备）

现象	含义	恢复动作
resultCode=908 找不到设备	该通道无对应设备(抓拍/扫码机)	换有设备的通道;扫码机核对 scanMachineId
status=7 参数不完整	channelId 与 channelCode 用错(云场用 channelId)	纯云场用 channelId、传统/云用 channelCode;按 schema 核对
下发后设备无反应	设备离线	get-cloud-equip-status 查在线再下发

通用码/退出码/重试见 [[openydt-shared]];结果解读(三层判读/金额/空结果)见其 references/result-reading-sop.md;写幂等规则见其 references/write-idempotency.md。

示例

示例 parkCode/时间为文档化测试值(仅 test);照抄历史 sampleBody 会撞无效车场/过期时间。--client-id 的 3571F003 取自设备查询,实际换真实设备 ID。

# 1) 开闸(写,高危):先预览
openydt device op-gate \
  --park-code 1ZS7H5PQH9 --channel-code 001 --op-type 0 \
  --operator operator --operate-time "2026-06-01 14:04:04" --dry-run
# 预览无误后真正执行
openydt device op-gate \
  --park-code 1ZS7H5PQH9 --channel-code 001 --op-type 0 \
  --operator operator --operate-time "2026-06-01 14:04:04" --yes

# 2) 显示屏 + 语音播报(写,需 --yes;show/voice 至少一个)
openydt device op-show-voice \
  --park-code 1ZS7H5PQH9 --channel-code 001 \
  --show "欢迎光临" --voice "请缴费" \
  --operator operator --operate-time "2026-06-01 14:04:04" --yes

# 3) 查询云端扫码机状态(读,无需 --yes)
openydt device get-cloud-equip-status --equip-type 3 --client-id 3571F003