简介北京凯恩帝KND系列CNC系统REST API参考文档面向数控系统集成商、第三方开发者及设备维护人员用于对CNC设备进行远程状态读取、坐标管理、PLC数据采集与程序执行监控可无缝融入工厂自动化与生产数据采集场景。资源为单个PDF文档压缩包仅485KB内容按接口模块化编排涵盖系统信息、系统配置、轴配置、软限位、参考点、主轴进给控制及错误处理等细节并给出v1.3与v1.2版本基地址及JSON请求示例便于快速上手。已有198人学习下载适合具备基础HTTP与JSON知识、希望调用KND开放接口的开发者阅读建议结合实际机床操作手册优先从系统状态与配置接口入手再逐步深入到坐标与PLC相关功能。1. 别再把数控机床当黑匣子凯恩帝 CNC REST API 能直接读出系统状态做过车间数据采集的人都有体会最难的往往不是 MES 逻辑怎么写而是设备数据根本拿不到。老一点的车床只有串口新一点的又是各家私有协议想读个坐标都要跟现场 PLC 工程师磨半天。而凯恩帝KND部分 CNC 系统上直接内置了一个 REST API 服务器跑在标准 80 端口上用 HTTP 就能读到系统状态、坐标、倍率、宏变量甚至 PLC 寄存器。这对系统集成商、第三方开发者和维护人员来说相当于厂家给了一扇正门不用再靠旁路硬件去猜数据。本文要拆的这份《KND REST API 参考文档》覆盖 v1.3 与 v1.2 两个版本接口范围从基础配置、运行状态、坐标管理一路延伸到 PLC 虚拟机和加工程序访问适合把这套接口当作车间数据底座的人仔细读一遍。2. 接口地基版本、基地址、Content-Type 和错误对象先把这四个约定吃透2.1 版本选择v1.3 优先v1.2 仅作兼容文档里写得很明确当前最新版本是 v1.3建议直接用 v1.3请求基地址是/api/v1.3同时兼容 v1.2基地址为/api/v1.2。除了程序列表这个接口在 v1.2 里只返回程序号、v1.3 里才会附带程序名之外绝大多数接口在两个版本下行为一致。我通常的做法是统一按 v1.3 开发代码里把 base 路径做成可配置项这样现场如果遇到只能用 v1.2 的老系统改一个变量就能切过去不用动业务逻辑。这里有一个容易被忽略的细节基地址是从/api/v1.3开始的后面的接口路径才是/status、/coors这种相对路径。假设 CNC 的 IP 是 192.168.1.101那么完整的状态接口地址就是http://192.168.1.101/api/v1.3/status。第一次调试时很多人习惯性写成http://192.168.1.101/status结果 404这不是接口不存在而是把版本前缀漏掉了。2.2 请求约束只收 application/json编码必须是 UTF-8所有接口只接收Content-Type: application/json的 HTTP 数据除了部分文件相关接口外大部分接口返回的也是 JSON。数据编码统一 UTF-8。这意味着你用 curl、Postman 或者 Python requests 都能直接调但要注意两点第一不要用application/x-www-form-urlencoded去 POST第二如果是从 Windows 的 cmd 里手敲 curl中文注释或者特殊字符很容易被系统默认编码搞乱建议脚本文件统一存成 UTF-8 无 BOM。另一个隐含约束是除特殊说明外HTTP 方法默认是 GET。但也有一批接口支持 PUT设置和 DELETE清零比如坐标清零、宏变量写入、刀补设置、工件坐标系写入、加工计数清零。设计程序轮询时一定要区分“读接口”和“写接口”不要把写操作放进高频读循环里后面会具体讲哪些接口有写入副作用。2.3 错误对象HTTP 200 也可能带着 error别只盯状态码错误处理这块值得单独拎出来说。文档给出的错误返回格式如下{ error: -1, error-message: 未知错误 }error是错误码error-message是错误描述。关键点在于返回错误时 HTTP 状态码一般是 400、500但也可能是 200。也就是说不能只看 HTTP 状态码判断请求是否成功必须解析响应体里有没有error字段。我在做数据采集框架时统一封装了一个响应校验函数先检查状态码再检查 JSON 里是否含error键两者都通过才算成功。还需要注意当操作成功且没有数据需要返回时服务端只返回 2xx 状态码不返回任何数据体。所以 DELETE 清零坐标、PUT 设置目标件数这类操作成功后的响应体可能是空的解析的时候要容忍空响应。3. 系统状态与配置从机器配置到实时状态这一组接口就是“体检报告”3.1 /config/basic先看机床基础配置再谈采集采集程序真正跑起来之前我建议先调一次/config/basic把机床的基础参数捞一遍。这个接口返回插补周期、PLC 周期、直线轴个数、旋转轴个数、主轴个数、通道个数、本地数字输入输出点数、模拟轴输出接口个数、手轮接口个数以及远程 IO 模块的分布情况。curl -s http://192.168.1.101/api/v1.3/config/basic | python3 -m json.tool返回里的interpolation-period单位是微秒典型值是 2000也就是 2ms 的插补周期plc-period单位也是微秒常见 16000。这两个值决定了你能以多快的频率去读动态数据——插补周期 2ms 意味着坐标值本身是 2ms 量级在刷新但 REST API 走 HTTP 协议实际轮询做到 100ms 级别已经算高频了再快意义不大反而可能占用系统资源。io-modules是一个数组每个元素含di-count和do-count对应远程 IO 模块的点数。如果你的设备上有扩展 IO 模块这个字段能帮你确定 PLC 地址映射范围后续读 X/Y 区时心里有数。3.2 /status运行状态、工作模式与未就绪原因掩码/status是监控页面最核心的接口返回运行状态、当前工作模式、是否准备就绪、未就绪原因、报警类型列表以及机床锁、辅助锁、空运行、单段、跳段、选择停这些开关状态。curl -s http://192.168.1.101/api/v1.3/status | python3 -m json.toolrun-status有三个取值0 停止、1 暂停进给保持、2 运行。opr-mode是工作模式枚举值很细0 录入、1 自动、3 编辑、4 单步、5 手动、6 手动编辑示教、7 手轮编辑示教、8 手轮、9 机械回零、10 程序回零。做设备状态大屏时我一般把这两个字段组合成业务状态自动模式下 run-status 为 2 就是“自动运行中”手动模式下 run-status 为 0 就是“手动待机”回零模式单独显示“正在回零”。ready是布尔值表示机床是否准备就绪。如果为 falsenot-ready-reason是掩码值0x1 急停信号有效、0x2 伺服准备未绪、0x4 IO 准备未绪远程 IO 设备等。注意这是按位或的组合判断时要用位运算不能直接做等值比较。reason status_json.get(not-ready-reason, 0) if reason 0x1: print(急停信号有效) if reason 0x2: print(伺服准备未绪) if reason 0x4: print(IO准备未绪)alarms字段是当前报警类型的列表比如[ps, prm-switch]。注意它只给类型名称具体报警文本要去/alarms/接口查。还有machine-lock、dry-run、single-block这些辅助开关状态做远程监控时也建议一并展示因为机床锁和空运行状态下坐标在动但实际并没有切削直接统计运行时长会误导生产报表。3.3 /alarms报警类型与单类型查询/alarms/返回系统中所有当前报警属性名是报警类型属性值是文本描述。文档里列出的类型相当全prm-switch参数开关报警、reboot开关机报警、plcPLC 报警或提示、psPS 报警操作错、over-travel超程、over-heat过热、mem存储器、servo伺服驱动、servo-bus伺服总线、over-workarea超出工作区、io-bus、io-module、manufacture机床厂报警、forbid-move不允许移动的轴发生移动。curl -s http://192.168.1.101/api/v1.3/alarms/ps每种报警类型也可以单独访问比如/alarms/ps。如果当前没有该类型报警返回空对象{}。这里有个实用技巧我只关注ps、servo、over-travel、plc这四类就能覆盖车间九成以上的停机原因轮询时可以只轮这四个子接口减少数据量。3.4 /config/axes 与 /config/spindles轴和主轴的“身份证”轴配置接口/config/axes/axisNameOrNo既可以按轴号也可以按轴名访问比如/config/axes/X和/config/axes/1都行。返回字段里有typelinear/rotary、soft-limit软限位数组、ref-pos参考点数组、screw-pitch螺距、gear-ratio齿轮比、closed-loop-type半闭环/全闭环、backlash间隙补偿值以及伺服、电机、编码器的配置参数。文档里特别提醒轴配置信息客户端应至少读两次以确保数据完整有效。原因是伺服、电机、编码器这些字段在总线驱动器未连接时可能为 null而且配置数据存在更新窗口单次读取可能拿到半新半旧的数据。我做设备台账初始化时会让程序连续拉两次/config/axes对比一致后再入库不一致就重试。主轴配置/config/spindles/spindleNameOrNo的返回结构里axis字段如果为 null 表示模拟主轴否则返回对应数字轴的完整配置。批量接口/config/axes/和/config/spindles/返回所有轴和主轴的配置数组适合做一次性全量采集。3.5 PLC 虚拟机/plc/vm远程读 PLC 寄存器的关键路径如果要采集 PLC 侧的传感器信号、气缸到位、夹具状态这类数据就要用到/plc/vm/这一组接口。先调/plc/vm/获取运行环境信息返回 PLC 版本号和各区域大小{ version: 4.1, region-size: { X: 1000, Y: 1000, F: 20000, G: 20000, R: 20000, S: 20, K: 256, D: 20000, TL: 2000, T: 1000, C: 1000 } }X/Y/F/G/R/S/K/D/TL 区的读取方式是/plc/vm/regionoffset?typetypecountcount。offset可以是字节偏移也可以是字节内位偏移如10.0指定位时只支持访问 1 位且不能指定其他查询参数。type默认为u8可选s8/u16/s16/u32/s32count不指定时默认 1最大 128。注意TL区只支持u8类型且type与offset必须有对齐关系——u32类型要求 offset 按 4 字节对齐u16要求 2 字节对齐否则请求直接报错。curl -s http://192.168.1.101/api/v1.3/plc/vm/X0?typeu16count3这条命令读的是 X0、X1 组成一个 u16X2、X3 组成一个 u16X4、X5 组成一个 u16返回[1, 2, 4]这样的列表。如果count不写返回单个对象{val: 100}如果写了 count即使值为 1也返回列表这是为了避免代码里对“返回的是对象还是数组”做特殊判断。T/C 区定时器/计数器的读取格式稍有不同/plc/vm/T0返回的是{conf: 1000, cur: 100}conf是设置值cur是当前值。带count参数时返回对象列表最大支持 128 个。4. 坐标管理与数据操作读坐标、清坐标、写工件坐标系、宏变量和刀补4.1 /coors四类坐标读取与清零的两个红灯坐标是这个 API 里最常用的数据。/coors/一次性返回四组坐标absolute绝对坐标、machine机床坐标、relative相对坐标、dist-to-go余移动量。import requests resp requests.get(http://192.168.1.101/api/v1.3/coors/, timeout3) coors resp.json() print(绝对坐标:, coors[absolute]) print(机床坐标:, coors[machine]) print(相对坐标:, coors[relative]) print(余移动量:, coors[dist-to-go])四组坐标也可以单独访问/coors/absolute、/coors/machine、/coors/relative、/coors/dist-to-go返回格式是{X: 10.0, Z: 10.0, Y: 20.0}轴名列表与系统配置里的axes对应。清零操作有两个红灯DELETE /coors/machine清零机床坐标DELETE /coors/relative清零相对坐标加工时清零会返回错误。清零机床坐标有风险文档原话是“应仅用于测试、教学、无机床零点或不使用机床零点的机床”。我自己的习惯是生产系统里绝对不开放这个接口给操作工只保留相对坐标清零而且清零前必须确认 run-status 为 0。4.2 /workcoors工件坐标系的读与写/workcoors/返回所有工件坐标系 G54-G59 的当前值。单个坐标系可以 GET也可以用 PUT 修改curl -s -X PUT http://192.168.1.101/api/v1.3/workcoors/g55 \ -H Content-Type: application/json \ -d {X: 10.0, Z: 2.0, Y: 0}PUT 支持只设置部分轴比如只写 X 轴。这个接口做远程对刀、批量工件坐标系下发时很有用但要注意坐标系修改是在系统运行参数上直接动刀写入前一定要确认机床处于非运行状态并且最好用/workcoors/cur先看当前用的是哪个坐标系别把正在用的坐标系改了。4.3 /vars宏变量的读写与并发风险单个宏变量接口是/vars/varNoGET 读取PUT 写入curl -s -X PUT http://192.168.1.101/api/v1.3/vars/100 \ -H Content-Type: application/json \ -d {val: 10.0}varNo既可以是宏变量号也可以是宏名称如/vars/TEST。批量接口/vars/?namevarNo1,varNo2,...,varNo3-varNo4,...,varNox最多一次性读取 64 个宏变量的值name为必选参数逗号分隔可以使用区间。区间是左闭右开比如300-302等价于300,301不包含 302。这里有两个明确警告第一宏变量接口支持访问系统宏变量包括刀补、模态和坐标值等运行时修改可能对加工产生重大影响第二如果加工程序和 REST API 同时修改同一个宏变量结果未知。我在做刀具寿命管理时刀具计数宏变量的写入会严格限定在循环启动前和循环结束后这两个窗口避免和加工程序撞车。4.4 /ofs刀补读写的“部分成功”大坑刀补接口/ofs/count获取系统支持的刀补个数/ofs/geoms/ofsNo和/ofs/wears/ofsNo分别读写形状值和磨损值。形状值包含每轴一项、R半径形状值、T刀尖方向仅车床0~9磨损值包含每轴一项和R半径磨损值。批量接口支持?startstartcountcountstart 默认 1count 默认 32最大 32。PUT 批量设置时传对象数组payload [ {no: 1, val: {X: 1.0, Y: 0.5, R: 0.1, T: 0}}, {no: 2, val: {X: 1.0, Y: 0.5, R: 0.1, T: 0}}, ] resp requests.put( http://192.168.1.101/api/v1.3/ofs/geoms/, jsonpayload, timeout3 )文档里有一句非常关键的警告设置即使返回失败也可以部分成功客户端应处理这种情况读回确认全部成功。也就是说批量写刀补之后不能只看响应码必须再批量 GET 一次逐一比对写入值。这是这个接口最典型的边界后面避坑章还会展开。5. 常见问题排查六个容易翻车的边界场景5.1 现象HTTP 200 但业务失败第一次对接时明明返回了 200程序却一直拿不到数据。后来把响应体打出来才发现是{error: -1, error-message: 未知错误}。原因这套 API 的错误处理里HTTP 状态码不保证与业务成功一致200 也可能带 error 对象。调用方只校验 HTTP 状态码就会漏掉业务错误。解决统一封装响应解析函数先判断 HTTP 状态码再解析 JSON最后检查是否有error键。我把这个确认逻辑固化成了采集框架的公共方法后续所有接口都走同一套校验。5.2 现象读 PLC 的 u32 数据一直报错原因/plc/vm/接口要求type与offset有对齐关系u32的 offset 必须是 4 字节对齐u16必须是 2 字节对齐。直接把 offset 写成 1 再去读 u32服务端认为是非法请求。解决先算好 offset 是否满足对齐条件。我一般会写一个对齐检查offset 对类型字节数取模为 0 才发请求读连续数据时count个 u32 占count * 4字节下一个读取起点要加count * 4而不是加 1。5.3 现象清零机床坐标时报错加工时清零相对坐标也失败原因接口设计上做了保护加工状态run-status 为 2下不允许清零坐标。清零操作会直接破坏加工基准系统拒绝执行。解决清零前先 GET/status确认run-status为 0 再发 DELETE。同时在业务逻辑里区分场景相对坐标清零可以开放给操作工在待机时使用机床坐标清零仅保留给调试模式或教学场景生产环境不开放这个按钮。5.4 现象宏变量写入后加工程序行为异常且偶发写不进去原因加工程序和 REST API 同时修改同一个宏变量时结果未知文档明确警告过。宏变量里有很多是系统宏变量包含刀补、模态、坐标值运行时改这些变量等于在加工中途篡改系统数据。解决把宏变量的读写窗口严格限定在机床停止状态并且通过/gmodals/确认当前不在自动运行中的 G 代码模态下。若必须读写刀具寿命类变量我会把变量号集中在用户宏变量区如 #500 以后躲开系统占用区间。5.5 现象批量写刀补返回失败但读回发现部分刀补已经生效原因刀补写入不是原子操作。文档明确说“设置即使返回失败也可以部分成功”服务端在执行批量写入时可能写入前几项后遇到错误中断但前面已写入的数据不会回滚。解决批量设置之后强制读回。我一般修改完刀补会立即调用/ofs/geoms/?startstartcountcount读回逐项核对写入值发现不一致就重新写入该序号。刀补数据直接影响加工精度这个读回校验绝对不能省。5.6 现象程序列表读出来只有程序号找不到程序名原因v1.2 和 v1.3 的程序列表返回结构不同。v1.2 中/progs/仅返回程序号没有程序号的程序不会出现在列表中v1.3 才返回程序名、程序号、大小、etag 和最后修改时间。解决程序管理功能一律按 v1.3 开发。如果遇到现场系统只支持 v1.2程序列表里拿不到名称只能靠程序号匹配业务数据。另注意程序访问要求 CNC 处于编辑模式或自动模式修改/删除程序时程序开关还必须处于打开状态否则返回错误。6. 用一小段脚本把接口串起来状态巡检与坐标采集的落地起点接口看完了最终还是要落到能跑的代码上。这里给一个最小的巡检脚本骨架它把状态、坐标、报警、加工时间四类数据串起来每秒轮询一次写入本地 JSON 文件。这个脚本可以直接跑在车间工控机上也可以改造成数据推送服务的一部分。import requests import json import time BASE http://192.168.1.101/api/v1.3 def get(path): resp requests.get(BASE path, timeout3) data resp.json() if resp.text else {} if error in data: raise RuntimeError(data[error-message]) return data def poll_once(): status get(/status) coors get(/coors/absolute) alarms get(/alarms/) cycle get(/cycletime) return { run-status: status[run-status], opr-mode: status[opr-mode], ready: status[ready], position: coors, alarms: alarms, cycle: cycle, } while True: try: snapshot poll_once() with open(cnc_snapshot.json, w, encodingutf-8) as f: json.dump(snapshot, f, ensure_asciiFalse, indent2) print(snapshot ok:, snapshot[position]) except Exception as e: print(poll error:, e) time.sleep(1)这个脚本里get()函数做了两层校验空响应体和 error 字段。轮询循环里把异常兜住防止网络抖动导致采集线程退出。实际项目里我还会在此基础上增加写入保护只有run-status 0时才允许执行 PUT/DELETE 类操作坐标采集永远只读绝对坐标机床坐标只在初始化时读一次用于对零校验。至于倍率、目标件数、工件计数这类数据建议放到低频采集5 秒以上间隔没必要每秒刷。第一次把脚本接到真机上时我因为没处理“HTTP 200 但带 error”的情况整整查了一个下午最后打印响应体才恍然大悟。从那以后我每次对接新接口都强制先把原始响应打印出来看一遍再写业务解析。这套 API 的文档已经算写得清楚但边界条件仍然不少希望这份拆解能帮你少踩几个坑让数控机床的数据底座少一点玄学多一点可控。本文还有配套的精品资源点击获取