22117-MAGNETOSTRICTIVE 磁致伸缩位移液位传感器

模型清单

可使用下列名称或 ID 在 ThinkLink 中搜索对应模型。

模型类型	名称	id_name	平台模型 ID
RPC	[MAGNETOSTRICTIVE GET] 22117	magnetostrictive_get_22117	134816011390971904
RPC	[MAGNETOSTRICTIVE SET] 22117	magnetostrictive_set_22117	134816010694717440
Template	MAGNETOSTRICTIVE	magnetostrictive_22117	134816008626925568
Thing Model	[MAGNETOSTRICTIVE]	magnetostrictive_22117	134816009310597120
Parameter Thing Model	[MAGNETOSTRICTIVE-PARA]	magnetostrictive_para_22117	134816010011045888

1. 传感器简介

SX 磁致伸缩绝对位移/液位传感器通过 RS-485/Modbus RTU 接入 KC21，业务代码为 22117，ThinkLink 模板为 magnetostrictive_22117。

2. 产品特点

重复精度 ±0.001mm
绝对位置输出，断电重启无需重新寻零
支持 RS-485 Modbus RTU 或 4-20mA 版本

3. 适用范围

水库、油罐和工艺容器液位监测
液压缸、闸门和机械执行机构位移监测
桥梁、基坑和结构变形监测

4. 采集器信息

DTU：KC21
接口：RS-485
默认模式：Battery / Class A
串口：9600、8N1
传感器上电延时：1000ms

部署前供电确认： 本对接在现场信息缺失时默认按 KC21 电池供电（Class A）处理，尚未由客户确认。若实际为常供电，需改为 Class C、改用 MT-EB-POWER 模板并重新核对心跳周期，否则可能出现下行不及时、功耗异常或控制指令不可达。

电源正负极必须按设备资料与实物铭牌连接；RS-485 A/B 分别连接 KC21 485A/485B。部署前断电完成接线，并确认传感器实际供电范围。

5. 数据采集

采用 FC03，1 个查询事件：读取地址 0-1 的低字和高字，组合为毫米位移。采集与上报共用 app_70=900s，COV 关闭。

地址	字段	数据项	类型	系数	单位
0-1	displacement	位移/液位 / Displacement or level	uint32WordsLowHigh	0.001	mm

6. EdgeBus 模型

port: 22
version/dataType: 0x88/0x01
BzType/BzVersion: 22117/1
upPeriodIndex: 70
addr_modbus: app_150
上行帧长度：6 字节公共头 + 所有查询结果字节
查询逻辑：1 个查询事件：读取地址 0-1 的低字和高字，组合为毫米位移

6.2 EdgeBus 代码

typescript

import { Buffer } from "buffer";
import { buildOtaFile } from "@EBSDK/run";
import { EBModel } from "@EBSDK/EBCompiler/EBModel/EBModel";
import { EventInfoItem } from "@EBSDK/EBCompiler/plugins/EBHelper";
import type { UserConfUPItem } from "@EBSDK/EBCompiler/plugins/EBHelper";
import { CheckbitEnum, getOtaConfig } from "@EBSDK/otaConfig";

// SX magnetostrictive displacement/level sensor, RS485/Modbus-RTU FC03.
// Registers 0x0000 and 0x0001 are low word then high word. The ThinkLink
// parser combines them using standard 32-bit binary carry and scales to mm.
const eventInfo: UserConfUPItem[] = [
  {
    name: "sx-magnetostrictive",
    port: 22,
    version: "0x88",
    dataType: "0x01",
    upPeriodIndex: 70,
    quInfo: [
      {
        protocol: "modbus",
        addr: "0x01",
        code: "0x03",
        periodIndex: 70,
        indexAPP: 150,
        indexCMD: 0,
        copySize: 1,
        isLast: true,
        listVal: [{ start: "0x0000", end: "0x0001" }],
      },
    ],
  },
];

const otaConfig = getOtaConfig({
  BaudRate: 9600,
  StopBits: 1,
  DataBits: 8,
  Checkbit: CheckbitEnum.NONE,
  Battery: true,
  ConfirmDuty: 60,
  BzType: 22117,
  BzVersion: 2,
});

const MODBUS_TT = (ebModel: EBModel) => {
  for (const info of eventInfo) {
    const event = new EventInfoItem(info);
    event.upEventSetup();
    event.eventInstall();
  }
  return JSON.stringify(ebModel, null, 2);
};

buildOtaFile(import.meta.url, otaConfig, MODBUS_TT);

7. 物模型

遥测物模型：magnetostrictive_22117
参数物模型：magnetostrictive_para_22117
上行：port 22，标签 0x88/0x01

7.1 遥测解析器

import {Buffer} from "buffer";
import {PayloadParser, RPCHelper} from "#tklHelper";

function payload_parser(device, msg, thingModelId, noticeAttrs, org_params) {
    const port = msg?.userdata?.port ?? null;
    if (port !== 22) return null;

    const frameInfo = {
        port: 22,
        dataLen: 10,
        rssi: true,
        battery: 4,
        status: 3,
        tagList: [{index: 0, tag: 0x88}, {index: 1, tag: 0x01}],
    };
    const parser = new PayloadParser({device, msg, frameInfo, appInfo: []});
    let telemetry = parser.telemetry();
    if (telemetry == null) return null;

    if ((telemetry.status & 0x02) === 0x02) {
        const status = telemetry.status;
        telemetry = {...(device.telemetry_data?.[thingModelId] ?? {})};
        telemetry.status = status;
    } else {
        const payload = Buffer.from(msg.userdata.payload, "base64");
        const raw = payload.readUInt16BE(8) * 65536 + payload.readUInt16BE(6);
        telemetry.displacement = Number((raw * 0.001).toFixed(3));
    }
    telemetry._modelName = "magnetostrictive_22117";
    telemetry.adr = msg?.userdata?.adr ?? null;

    const result = {
        telemetry_data: telemetry,
        server_attrs: null,
        shared_attrs: null,
    };
    if (typeof RPCHelper.buildRpcHookAction === "function") {
        const action = RPCHelper.buildRpcHookAction({
            device,
            msg,
            thingModelId,
            idName: "magnetostrictive_22117",
            name: "[MAGNETOSTRICTIVE]",
            parsed: result,
        });
        if (action) result.actions = [action];
    }
    return result;
}

const deviceObj = {telemetry_data: {}};
const msgObj = {
    userdata: {
        port: 22,
        payload: Buffer.from("880100006401b7cd0001", "hex").toString("base64"),
    },
};
const noticeAttrsObj = {telemetry_data: true};
console.log(payload_parser(deviceObj, msgObj, "1", noticeAttrsObj, {}));

7.2 参数解析器

import {PayloadParser, RPCHelper, Utils} from "#tklHelper";

function payload_parser(device, msg, thingModelId, noticeAttrs, org_params) {
    const port = msg?.userdata?.port ?? null;
    const rpcName = "magnetostrictive_set_22117";
    const paraDef = {
        app_20: {name: "TimeOffset", field_name: "TimeOffset", unit: "", index: 20, type: "uint32le"},
        app_38: {name: "pwron_delay", field_name: "pwron_delay", unit: "ms", index: 38, type: "uint16le"},
        app_40: {name: "period_heart", field_name: "period_heart", unit: "s", index: 40, type: "uint32LE"},
        app_70: {name: "period_up", field_name: "period_up", unit: "s", index: 70, type: "uint32LE"},
        app_150: {name: "addr_modbus", field_name: "addr_modbus", unit: "", index: 150, type: "uint8"},
    };
    if (port !== 214) {
        const checkData = Utils.paraCheck(rpcName, device.server_attrs, device.shared_attrs);
        return {server_attrs: checkData.sdata, actions: checkData.actions};
    }
    const pdata = (new PayloadParser({device, msg, paraInfo: paraDef})).paras();
    if (pdata == null) return null;
    const checkData = Utils.paraCheck(rpcName, device.server_attrs, pdata);
    const result = {
        telemetry_data: pdata,
        server_attrs: checkData.sdata,
        shared_attrs: {
            TimeOffset: pdata.TimeOffset,
            pwron_delay: pdata.pwron_delay,
            period_heart: pdata.period_heart,
            period_up: pdata.period_up,
            addr_modbus: pdata.addr_modbus,
        },
        actions: checkData.actions,
    };
    if (typeof RPCHelper.buildRpcHookAction === "function") {
        const action = RPCHelper.buildRpcHookAction({
            device,
            msg,
            thingModelId,
            idName: "magnetostrictive_para_22117",
            name: "[MAGNETOSTRICTIVE-PARA]",
            parsed: {
                telemetry_data: result.telemetry_data,
                server_attrs: result.server_attrs,
                shared_attrs: result.shared_attrs,
            },
        });
        if (action) {
            result.actions = result.actions || [];
            result.actions.push(action);
        }
    }
    return result;
}

const deviceObj = {telemetry_data: {}, server_attrs: {}, shared_attrs: {}};
const msgObj = {userdata: {port: 11, payload: ""}};
const noticeAttrsObj = {telemetry_data: true};
console.log(payload_parser(deviceObj, msgObj, "1", noticeAttrsObj, {}));

8. 第三方 MQTT 订阅

Topic: /v32/{Organization Account}/tkl/up/telemetry/{eui}

json

{
  "eui": "6353012af10a9331",
  "active_time": "2026-07-29T08:35:48.000Z",
  "thingModelId": "22117",
  "thingModelIdName": "magnetostrictive_22117",
  "telemetry_data": {
    "snr": 13.5,
    "rssi": -51,
    "battery": 3.37,
    "displacement": 112.589
  }
}

9. RPC

参数设置：magnetostrictive_set_22117
参数读取：magnetostrictive_get_22117

APP 槽位	字段	含义	单位	类型	默认值

| app_20 | TimeOffset | 时间偏移 | | uint32le | 0 | | app_38 | pwron_delay | 上电延时 | ms | uint16le | 1000 | | app_40 | period_heart | 心跳周期 | s | uint32LE | 86400 | | app_70 | period_up | 采集与上报周期（≥60） | s | uint32LE | 900 | | app_150 | addr_modbus | Modbus 地址（1-247） | | uint8 | 1 |

9.1 参数设置 RPC

import {RPCHelper, Utils} from '#tklHelper';
import {Buffer} from 'buffer';

function rpc_script({device, params, alarms, logger, org_params}) {
    const classMode = device?.shared_attrs?.class_mode || "ClassA";
    const rpcName = "magnetostrictive_set_22117";
    params = params && typeof params === "object" ? {...params} : {};

    if (params.period_up != null && params.period_up < 60) {
        logger.info("period_up must be at least 60 seconds");
        return null;
    }
    if (params.addr_modbus != null && (params.addr_modbus < 1 || params.addr_modbus > 247)) {
        logger.info("addr_modbus must be between 1 and 247");
        return null;
    }
    if (params.period_heart == null || params.period_heart < 3600) {
        params.period_heart = 86400;
    }
    if (params.pwron_delay == null || params.pwron_delay < 1000) {
        params.pwron_delay = 1000;
    }

    const paraDef = {
        app_20:  {name: "TimeOffset", field_name: "TimeOffset", unit: "", index: 20, type: "uint32le"},
        app_38:  {name: "pwron_delay", field_name: "pwron_delay", unit: "ms", index: 38, type: "uint16le"},
        app_40:  {name: "period_heart", field_name: "period_heart", unit: "s", index: 40, type: "uint32LE"},
        app_70:  {name: "period_up", field_name: "period_up", unit: "s", index: 70, type: "uint32LE"},
        app_150: {name: "addr_modbus", field_name: "addr_modbus", unit: "", index: 150, type: "uint8"}
    };
    const frames = RPCHelper.buildFrame({paraDef, params});
    const redoBuffer = RPCHelper.redo();
    const dnBuffer = Buffer.alloc(frames.writeBuffer.length + frames.readBuffer.length);
    frames.writeBuffer.copy(dnBuffer, 0);
    frames.readBuffer.copy(dnBuffer, frames.writeBuffer.length);
    logger.info("set magnetostrictive KC21 app parameters");
    const msgQue = Utils.makeParaSetMSG({
        device,
        classMode,
        rpcName,
        params,
        paraDownBuffer: dnBuffer,
        extraAppBuffer: redoBuffer
    });
    return msgQue.length == 0 ? null : msgQue;
}

rpc_script({
    device: {server_attrs: {}, shared_attrs: {}},
    params: {period_up: 900, addr_modbus: 1, period_heart: 86400, pwron_delay: 1000},
    alarms: [],
    logger: console,
    org_params: {}
});

9.2 参数读取 RPC

import {RPCHelper, Utils} from '#tklHelper';

function rpc_script({device, params, alarms, logger, org_params}) {
    const classMode = device?.shared_attrs?.class_mode || "ClassA";
    const sleepMs = classMode === "ClassA" ? 500 : 5000;
    const paraDef = {
        app_20:  {name: "TimeOffset", field_name: "TimeOffset", unit: "", index: 20, type: "uint32le"},
        app_38:  {name: "pwron_delay", field_name: "pwron_delay", unit: "ms", index: 38, type: "uint16le"},
        app_40:  {name: "period_heart", field_name: "period_heart", unit: "s", index: 40, type: "uint32LE"},
        app_70:  {name: "period_up", field_name: "period_up", unit: "s", index: 70, type: "uint32LE"},
        app_150: {name: "addr_modbus", field_name: "addr_modbus", unit: "", index: 150, type: "uint8"}
    };
    const frames = RPCHelper.buildFrame({paraDef, params: params || {}});
    const msg = RPCHelper.makeMSG({
        msgType: Utils.msgType.paras,
        device,
        dnBuffer: frames.readBuffer,
        sleepTime: sleepMs
    });
    return [msg];
}

rpc_script({
    device: {server_attrs: {}, shared_attrs: {}},
    params: {},
    alarms: [],
    logger: console,
    org_params: {}
});

以上 RPC 只配置 KC21 应用参数，不写传感器寄存器。

10. 模板选择

在 ThinkLink 中搜索模板 MAGNETOSTRICTIVE，或按业务代码 22117 查找。

11. 补充说明

本实现按标准二进制规则 high*65536+low 合成。手册示例使用 65535，结果相差 0.001mm，必须用实物已知位移复核。
资料标注 12V/24V、≤50mA；现场必须确认具体电源版本以及是否允许 KC21 的传感器供电电压。
置零、满量程和模拟量校准需要密码且会改变设备状态，本次不开放。

LoRaWAN 网关

应用笔记

LoRaWAN EB 采集器

LoRaWAN 传感器

平台

网络服务器

设备

农业传感器

BMS

定制设备

工业设备

门思传感器

仪表

22117-MAGNETOSTRICTIVE 磁致伸缩位移液位传感器

模型清单

1. 传感器简介

2. 产品特点

3. 适用范围

4. 采集器信息

5. 数据采集

6. EdgeBus 模型

6.2 EdgeBus 代码

7. 物模型

7.1 遥测解析器

7.2 参数解析器

8. 第三方 MQTT 订阅

9. RPC

9.1 参数设置 RPC

9.2 参数读取 RPC

10. 模板选择

11. 补充说明

LoRaWAN 网关

应用笔记

LoRaWAN EB 采集器

LoRaWAN 传感器

农业传感器

BMS

定制设备

工业设备

门思传感器

仪表

22117-MAGNETOSTRICTIVE 磁致伸缩位移液位传感器 ​

模型清单 ​

1. 传感器简介 ​

2. 产品特点 ​

3. 适用范围 ​

4. 采集器信息 ​

5. 数据采集 ​

6. EdgeBus 模型 ​

6.2 EdgeBus 代码 ​

7. 物模型 ​

7.1 遥测解析器 ​

7.2 参数解析器 ​

8. 第三方 MQTT 订阅 ​

9. RPC ​

9.1 参数设置 RPC ​

9.2 参数读取 RPC ​

10. 模板选择 ​

11. 补充说明 ​

22117-MAGNETOSTRICTIVE 磁致伸缩位移液位传感器

模型清单

1. 传感器简介

2. 产品特点

3. 适用范围

4. 采集器信息

5. 数据采集

6. EdgeBus 模型

6.2 EdgeBus 代码

7. 物模型

7.1 遥测解析器

7.2 参数解析器

8. 第三方 MQTT 订阅

9. RPC

9.1 参数设置 RPC

9.2 参数读取 RPC

10. 模板选择

11. 补充说明