Telemetry (Dữ liệu cảm biến)

Telemetry là dữ liệu time-series được thiết bị gửi lên theo thời gian: nhiệt độ, độ ẩm, điện áp, GPS... VieLang IoT lưu trữ toàn bộ lịch sử và cho phép truy vấn, tổng hợp theo nhiều cách.

Định dạng dữ liệu

Không có timestamp (server tự gán)

{"temperature": 25.5, "humidity": 68, "voltage": 3.7}

Có timestamp (milliseconds)

{
  "ts": 1735000000000,
  "values": {
    "temperature": 25.5,
    "humidity": 68
  }
}

Mảng nhiều điểm cùng lúc

[
  {"ts": 1735000000000, "values": {"temperature": 25.5}},
  {"ts": 1735000005000, "values": {"temperature": 25.8}},
  {"ts": 1735000010000, "values": {"temperature": 26.1}}
]

Lưu trữ

VieLang IoT hỗ trợ nhiều backend lưu trữ:

Backend	Khuyến nghị dùng khi
PostgreSQL	< 5,000 điểm/giây, đơn giản
Cassandra	> 5,000 điểm/giây, phân tán
TimescaleDB	Cần SQL + time-series tốc độ cao

Cấu hình trong vielang.toml:

[timeseries]
backend = "postgres"  # "postgres" | "cassandra" | "timescale"

Data Retention (Giữ dữ liệu)

Cấu hình TTL (time-to-live) ở nhiều cấp độ (ưu tiên từ cao xuống thấp):

Rule node — TTL ghi trong message metadata
Tenant attribute — TTL attribute của tenant
Tenant profile — Cấu hình trong tenant profile
System config — Cấu hình global trong vielang.toml

[timeseries]
default_ttl_days = 365  # 1 năm

REST API

Lấy keys hiện có

GET /api/plugins/telemetry/DEVICE/{deviceId}/keys/timeseries
Authorization: Bearer {JWT}

# Response:
["temperature", "humidity", "voltage", "battery"]

Lấy giá trị mới nhất

GET /api/plugins/telemetry/DEVICE/{deviceId}/values/timeseries
  ?keys=temperature,humidity
Authorization: Bearer {JWT}

# Response:
{
  "temperature": [{"ts": 1735000000000, "value": "25.5"}],
  "humidity":    [{"ts": 1735000000000, "value": "68"}]
}

Lấy lịch sử (time range)

GET /api/plugins/telemetry/DEVICE/{deviceId}/values/timeseries
  ?keys=temperature
  &startTs=1700000000000
  &endTs=1735000000000
  &interval=3600000
  &agg=AVG
  &limit=720
Authorization: Bearer {JWT}

Các tham số:

Tham số	Mô tả	Ví dụ
`keys`	Danh sách keys, cách nhau bởi `,`	`temperature,humidity`
`startTs`	Thời gian bắt đầu (ms)	`1700000000000`
`endTs`	Thời gian kết thúc (ms)	`1735000000000`
`interval`	Bucket size (ms)	`3600000` (1 giờ)
`agg`	Hàm tổng hợp	`AVG`, `MIN`, `MAX`, `SUM`, `COUNT`, `NONE`
`limit`	Số điểm tối đa	`1000`
`orderBy`	Thứ tự	`ASC`, `DESC`

Hàm tổng hợp (Aggregation)

Hàm	Mô tả
`NONE`	Raw data, không tổng hợp
`AVG`	Trung bình cộng
`MIN`	Giá trị nhỏ nhất
`MAX`	Giá trị lớn nhất
`SUM`	Tổng
`COUNT`	Đếm số điểm

WebSocket — Dữ liệu real-time

Kết nối WebSocket để nhận cập nhật ngay khi thiết bị gửi dữ liệu:

const ws = new WebSocket("ws://localhost:8080/api/ws/plugins/telemetry")

// Authenticate sau khi kết nối
ws.onopen = () => {
  ws.send(JSON.stringify({
    authCmd: { cmdId: 0, token: "YOUR_JWT_TOKEN" }
  }))
}

// Subscribe telemetry real-time
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data)

  // Sau khi auth thành công, gửi subscription
  if (msg.authCmd) {
    ws.send(JSON.stringify({
      tsSubCmds: [{
        entityType: "DEVICE",
        entityId:   "DEVICE_UUID",
        scope:      "LATEST_TELEMETRY",
        cmdId:      1
      }]
    }))
  } else {
    // Nhận data update
    console.log("Telemetry update:", msg.data)
  }
}

Xóa telemetry

# Xóa keys cụ thể (giữ lại dữ liệu cũ)
DELETE /api/plugins/telemetry/DEVICE/{deviceId}/timeseries/delete
  ?keys=temperature,humidity
  &startTs=1700000000000
  &endTs=1710000000000
Authorization: Bearer {JWT}

# Xóa toàn bộ lịch sử của key
DELETE /api/plugins/telemetry/DEVICE/{deviceId}/timeseries/delete
  ?keys=temperature
  &deleteAllDataForKeys=true
Authorization: Bearer {JWT}