DYP-A17 Ultrasonic Level Sensor Integration Guide

Model catalog

Search for these models in ThinkLink by name or ID.

Model type	Name	id_name	Platform model ID
RPC	[A17 GET] 22112	dyp_a17_get_22112	115860154150187009
RPC	[A17 SET] 22112	dyp_a17_set_22112	115860154150187008
RPC	[A17 SET ALARM] 22112	dyp_a17_set_alarm_22112	115861829380370432
RPC	[A17 ACT] 22112	dyp_a17_set_filter_22112	115860154150187010
Template	DYP-A17		115862917407993856
Thing Model	[A17]	dyp_a17_22112	115859351784026112
Thing Model	[DYP-22112-A17资产] 区域聚合	dyp_a17_asset_22112	119677174411063307
Parameter Thing Model	[A17-PARA]	dyp_a17_para_22112	115859352627081216
Trigger	[A17] Level Alarm Trigger	dyp_a17_trigger_22112	115861828692504576

1. Sensor Overview

Item	Value
Device	A17 Ultrasonic Level (Distance) Sensor
Model	DYP-A17-V1.0 (RS485 model DYP-A17NY4W-V1.0)
Manufacturer	Shenzhen Dianyingpu Technology Co., Ltd. (DYP / Best Sensor)
Protocol	Modbus-RTU (RS-485)
Connectivity	EdgeBus DTU (KC21 battery), LoRaWAN Class A
Business Code	22112
Template	DYP-A17

The A17 uses reflective ultrasonic ranging to measure the non-contact distance from the probe to the liquid surface (range 25cm~1000cm). It connects to ThinkLink via a KC21 battery DTU over Modbus-RTU, for sewage/drainage well level monitoring with high-level/overflow, low-level, and sensor-fault alarms.

⚠️ Level semantics: the A17 measures the probe-to-liquid distance, so a higher liquid level means a SMALLER distance. Therefore the high-level alarm uses a small distance threshold and the low-level alarm uses a large one.

2. Product Features

Smart signal processing, small blind zone, range 25cm~1000cm, min error < 1cm.
Non-contact measurement — the probe never touches the sewage, avoiding corrosion, tangling and scaling.
Anti-water-accumulation housing mitigates probe condensation (critical in humid wells).
On-board temperature compensation (-15℃~60℃) auto-corrects temperature drift.
Low power: static current < 10µA, measuring < 15mA; long battery life with the battery DTU + COV reporting.
Adjustable step-filter level, probe excitation strength and blind-zone value for complex well conditions.
ESD protection per IEC61000-4-2.

3. Application Scenarios

Sewage / drainage well level monitoring (this integration)
Municipal drainage network / rain-well flood early warning
Sump / pump-station level monitoring

4. Gateway (DTU) Information

4.1 Hardware

Item	Value
DTU model	KC21 (battery version)
Interface	RS-485
Power	Battery (confirmed), LoRaWAN Class A
Device template	MT-EB-BATTERY
Heartbeat	Factory/binding ships a short heartbeat (900s, for commissioning); after configuration the SET RPC sets it to 8h (28800s) to save power
Sensor voltage	DC 3.3~5.0V (static < 10µA, measuring < 15mA)

⚠️ Power compatibility (verify on site before deployment): the A17 sensor operates at DC 3.3~5.0V. The voltage the KC21 battery DTU outputs to power the sensor must match this (some KC21 battery versions offer 3.3V/5V output). Similar battery ultrasonic level sensors have been integrated successfully, but verify the actual KC21 supply output before deployment to avoid a power mismatch that prevents the sensor from working.

4.2 Wiring

Pin	Label	Function	To KC21 (battery)
①	VCC	3.3~5V power	KC21 VCC output (verify voltage)
②	GND	Ground	KC21 GND
③	RX	RS485-B (inverting)	KC21 RS485-B
④	TX	RS485-A (non-inverting)	KC21 RS485-A

Note: on the A17, ③RX = 485-B and ④TX = 485-A; do not swap the A/B pairing.

5. Data Acquisition

Via Modbus-RTU (FC03 read holding registers, CRC-16, default address 0x01, 9600/8/N/1, big-endian) the following points are read:

0x0100 processed distance (filtered stable value) → primary level telemetry, alarm basis
0x0101 real-time distance (single-shot, 130ms response) → COV trigger source
0x0102 ambient temperature

5.1 Register Map

Register	Item	Data Type	R/W	Notes
0x0100	Processed distance	uint16BE (mm)	R	Filtered stable value, response 0.9~2.5s (acquired, alarm basis — filtered/stable)
0x0101	Real-time distance	uint16BE (mm)	R	Single-shot, response 130ms (acquired, COV trigger source — fastest, for overflow early-warning; noisier so NOT used for alarms)
0x0102	Ambient temperature	int16BE (0.1℃)	R	Module temperature, 0.5℃ resolution (acquired)
0x0200	Slave address	uint16BE	R/W	0x01~0xFE, default 0x01
0x0201	Baud rate	uint16BE	R/W	Default 0x03=9600
0x0210	Blind-zone value	uint16BE (cm)	R/W	25~100, default 25; affects blind-zone stability
0x0211	Step-filter level	uint16BE	R/W	0~5, default 4; higher = stronger filtering
0x0212	Probe excitation	uint16BE	R/W	5~15, default 10
0x0213	Small-angle mode	uint16BE	R/W	0 normal / 1 small-angle, default 0

5.2 Communication Examples

Read distance:   M 01 03 01 00 00 01 85 F6 -> S 01 03 02 02 F2 38 A1 (0x02F2=754mm)
Read temp:       M 01 03 01 02 00 01 24 36 -> S 01 03 02 01 2C B8 09 (0x012C=30.0℃)
Write step filt: M 01 06 02 11 00 03 98 76 -> S 01 06 02 11 00 03 98 76 (step filter = 3)

6. EdgeBus Model

6.1 EB Configuration

Param	Value
name	dyp-a17
port	22
version	0x87
dataType	0x12
upPeriodIndex	70 (upload period app_70)
periodIndex	74 (collect period app_74)
indexAPP	150 (Modbus address app_150)
COV	enabled on distance_realtime (real-time distance 0x0101, covAppIndex 110 / cov_distance)
Serial	9600 / 8 / NONE / 1
Battery	true (Class A)
BzType / BzVersion	22112 / 2

6.2 EB Code

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";

// DYP-A17 超声波液位（测距）传感器 · Modbus-RTU FC03
//   0x0100 处理值距离 (uint16BE, mm)  ← 告警判据（滤波稳定），每帧上报
//   0x0101 实时值距离 (uint16BE, mm)  ← COV 上报触发源（130ms 响应，溢出早预警），阈值 app_110(cov_distance)
//   0x0102 环境温度   (int16BE, 0.1℃)
// 采集周期 app_74 / 上传周期 app_70 / Modbus 地址 app_150
// 2026-06-07 amend：加回 0x0101 实时值并把 COV 由 0x0100 移到 0x0101；BzVersion 1→2。
const eventInfo: UserConfUPItem[] = [
  {
    name: "dyp-a17", port: 22, version: "0x87", dataType: "0x12", upPeriodIndex: 70,
    quInfo: [
      {
        protocol: "modbus", addr: "0x01", code: "0x03", periodIndex: 74,
        indexAPP: 150, indexCMD: 0, copySize: 1,
        listVal: [
          { start: "0x0100", end: "0x0100" },
          { start: "0x0101", end: "0x0101", covType: "Uint16BE", covAppIndex: 110 },
          { start: "0x0102", end: "0x0102" }
        ]
      }
    ]
  }
];

let otaConfig = getOtaConfig({
  BaudRate: 9600,
  StopBits: 1,
  DataBits: 8,
  Checkbit: CheckbitEnum.NONE,
  Battery: true, // 电池供电，Class A
  ConfirmDuty: 60,
  BzType: 22112,
  BzVersion: 2
});

const MODBUS_TT = (ebModel: EBModel) => {
  for (let i = 0; i < eventInfo.length; i++) {
    let event = new EventInfoItem(eventInfo[i]);
    event.upEventSetup();
    event.eventInstall();
  }
  return JSON.stringify(ebModel, null, 2);
};
buildOtaFile(import.meta.url, otaConfig, MODBUS_TT);

6.3 Notes

One query event: FC03 reads registers 0x0100 (processed distance), 0x0101 (real-time distance) and 0x0102 (temperature) — three data points.
COV reporting: COV is enabled on distance_realtime (real-time distance 0x0101), threshold from app_110 (cov_distance); the real-time value responds fastest (130ms) for earlier overflow warning, and a level change >= threshold uploads immediately while saving battery. The real-time value is noisier, so in fluctuating wells the threshold may need raising; alarms still use the stable processed distance (0x0100).
Separate collect/upload periods: collect app_74, upload app_70 (COV window cap).
Uplink frame layout: standard 6-byte DTU header + distance (index 6-7, uint16BE) + distance_realtime (index 8-9, uint16BE) + temperature (index 10-11, int16BE), dataLen = 12.
Dynamic Modbus address: app_150 (indexAPP).

7. Thing Models

7.1 Basic Info

Type	Display name	id Name
Telemetry	[A17]	dyp_a17_22112
Parameter	[A17-PARA]	dyp_a17_para_22112

7.2 Uplink Frame Structure

frameInfo: port 22, dataLen 12, rssi true, battery 4, tagList [{index:0,tag:0x87},{index:1,tag:0x12}]

index	field	type	unit	coefficient
6	distance	uint16BE	mm	1
8	distance_realtime	uint16BE	mm	1
10	temperature	int16BE	℃	0.1

7.3 Scripts

Telemetry dyp_a17_22112.js and parameter dyp_a17_para_22112.js are under thinklink/thingModel/.

8. Third-Party Data Subscription

8.1 MQTT Topic

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

8.2 Sample Payload

json

{
    "eui": "0102030405060708",
    "active_time": "2026-06-06T08:35:48.000Z",
    "thingModelId": "115859351784026112",
    "thingModelIdName": "dyp_a17_22112",
    "telemetry_data": {
        "snr": 12.5,
        "rssi": -68,
        "battery": 3.55,
        "distance": 754,
        "distance_realtime": 752,
        "temperature": 23.5
    }
}

9. RPC

9.1 RPC Names

Type	Display name	id Name
Set parameters	[A17 SET] 22112	dyp_a17_set_22112
Get parameters	[A17 GET] 22112	dyp_a17_get_22112
Device-register tune (variant)	[A17 ACT] 22112	dyp_a17_set_filter_22112
Alarm threshold config	[A17 SET ALARM] 22112	dyp_a17_set_alarm_22112

9.2 Parameter Definitions

Param	Slot/Register	Name	Unit	Type	Default	Description
period_up	app_70	Upload period	s	uint32LE	3600	How often data is pushed to the cloud (COV window cap)
period_read	app_74	Collect period	s	uint32LE	300	How often the DTU polls the sensor
cov_distance	app_110	COV distance threshold	mm	int16BE	50	Real-time distance (0x0101) change >= this uploads immediately; the real-time value is noisier, raise it in fluctuating wells
period_heart	app_40	Heartbeat period	s	uint32LE	28800	Battery power-saving default 8h (short factory heartbeat is for commissioning only)
addr_modbus	app_150	Modbus address	—	uint8	1	DTU query target address
step_filter	0x0211	Step-filter level	—	uint16	4	Transparent FC06 write to device register
blind_zone	0x0210	Blind-zone value	cm	uint16	25	Transparent FC06 write to device register

9.3 RPC Notes

dyp_a17_set_22112: writes upload/collect period, COV threshold, Modbus address and heartbeat in one shot (PTL-D01 port 214). Battery devices keep heartbeat >= 1h (default 8h) to save power.
dyp_a17_get_22112: reads current DTU app parameters.
dyp_a17_set_filter_22112 (variant): dropdown chooses step-filter level or blind-zone value; transparent FC06 write to the device register, echo-validated then written back to shared_attrs. One item per call, current value prefilled.
dyp_a17_set_alarm_22112: configures per-well alarm thresholds (writes server_attrs.alarm_config, read by the alarm trigger).

Full RPC scripts are under thinklink/rpc/.

10. Alarms

The trigger dyp_a17_trigger_22112 ([A17] Level Alarm Trigger) evaluates after each telemetry frame; thresholds come from server_attrs.alarm_config (set per well via dyp_a17_set_alarm_22112; safe defaults apply if unset).

Alarm	Condition (distance semantics)	Default threshold	Level
High level / overflow	distance <= high_level_dist (liquid near probe)	300mm	high
Low level	distance >= low_level_dist (well near empty)	8000mm	mid
Sensor reading fault	distance abnormal (< 250mm blind zone / >= 10000mm over range / = 0)	—	mid

Distance thresholds use a 50mm hysteresis dead-band to prevent chatter near thresholds.
Run dyp_a17_set_alarm_22112 first to set thresholds, and set the notify group on the device.
Offline / no-data is handled by the platform offline alarm (the trigger only evaluates on uplink and cannot detect "no uplink").

11. Template Selection

In the ThinkLink platform, find the template by:

Template name: DYP-A17
Business code: 22112 (ultrasonic level sensor)

12. Additional Notes

Factory defaults: slave address 0x01, baud 9600, blind zone 25cm, step filter level 4, probe excitation 10.
Change slave address: FC06 write 0x0200; change baud: FC06 write 0x0201 (effective after reboot).
In humid wells with large temperature swings the probe can develop condensation, affecting the ultrasonic signal; the A17 anti-water housing mitigates this — if needed, raise the step-filter level via dyp_a17_set_filter_22112.

LoRaWAN Gateway

Application Notes

LoRaWAN EB Collector

LoRaWAN Sensor

Network Server

Device

meter

BMS

Industry

DYP-A17 Ultrasonic Level Sensor Integration Guide

Model catalog

1. Sensor Overview

2. Product Features

3. Application Scenarios

4. Gateway (DTU) Information

4.1 Hardware

4.2 Wiring

5. Data Acquisition

5.1 Register Map

5.2 Communication Examples

6. EdgeBus Model

6.1 EB Configuration

6.2 EB Code

6.3 Notes

7. Thing Models

7.1 Basic Info

7.2 Uplink Frame Structure

7.3 Scripts

8. Third-Party Data Subscription

8.1 MQTT Topic

8.2 Sample Payload

9. RPC

9.1 RPC Names

9.2 Parameter Definitions

9.3 RPC Notes

10. Alarms

11. Template Selection

12. Additional Notes

LoRaWAN Gateway

Application Notes

LoRaWAN EB Collector

LoRaWAN Sensor

meter

BMS

Industry

DYP-A17 Ultrasonic Level Sensor Integration Guide ​

Model catalog ​

1. Sensor Overview ​

2. Product Features ​

3. Application Scenarios ​

4. Gateway (DTU) Information ​

4.1 Hardware ​

4.2 Wiring ​

5. Data Acquisition ​

5.1 Register Map ​

5.2 Communication Examples ​

6. EdgeBus Model ​

6.1 EB Configuration ​

6.2 EB Code ​

6.3 Notes ​

7. Thing Models ​

7.1 Basic Info ​

7.2 Uplink Frame Structure ​

7.3 Scripts ​

8. Third-Party Data Subscription ​

8.1 MQTT Topic ​

8.2 Sample Payload ​

9. RPC ​

9.1 RPC Names ​

9.2 Parameter Definitions ​

9.3 RPC Notes ​

10. Alarms ​

11. Template Selection ​

12. Additional Notes ​

DYP-A17 Ultrasonic Level Sensor Integration Guide

Model catalog

1. Sensor Overview

2. Product Features

3. Application Scenarios

4. Gateway (DTU) Information

4.1 Hardware

4.2 Wiring

5. Data Acquisition

5.1 Register Map

5.2 Communication Examples

6. EdgeBus Model

6.1 EB Configuration

6.2 EB Code

6.3 Notes

7. Thing Models

7.1 Basic Info

7.2 Uplink Frame Structure

7.3 Scripts

8. Third-Party Data Subscription

8.1 MQTT Topic

8.2 Sample Payload

9. RPC

9.1 RPC Names

9.2 Parameter Definitions

9.3 RPC Notes

10. Alarms

11. Template Selection

12. Additional Notes