Thuộc tính (Attributes)

Thuộc tính (Attributes) là các cặp key-value gắn với thực thể (thiết bị, tài sản, tenant...). Khác với telemetry (dữ liệu time-series), attributes thường lưu trữ thông tin tĩnh hoặc ít thay đổi.

Ba loại Scope

1. Server-side Attributes

Được quản lý bởi server, thiết bị không thể đọc trực tiếp. Dùng cho:

Vị trí địa lý: latitude, longitude
Ngưỡng cảnh báo: maxTemperatureThreshold, minBatteryLevel
Phân loại thiết bị: building, floor, room

Đặt qua API:

POST /api/plugins/telemetry/DEVICE/{deviceId}/attributes/SERVER_SCOPE
Authorization: Bearer {JWT}

{
  "latitude": 10.7769,
  "longitude": 106.7009,
  "maxTemperatureThreshold": 35,
  "building": "HCM Factory"
}

Đọc qua API:

GET /api/plugins/telemetry/DEVICE/{deviceId}/values/attributes/SERVER_SCOPE
Authorization: Bearer {JWT}

# Response:
[
  { "lastUpdateTs": 1617633139380, "key": "latitude",   "value": 10.7769 },
  { "lastUpdateTs": 1617633139380, "key": "longitude",  "value": 106.7009 }
]

2. Shared Attributes

Được server quản lý nhưng thiết bị có thể đọc. Dùng để đồng bộ cấu hình từ server xuống thiết bị:

Phiên bản firmware cần cập nhật: targetFirmwareVersion
Cấu hình vận hành: maxTemperature, samplingInterval
Chế độ hoạt động: mode, enabled

Đặt qua API (server → thiết bị):

POST /api/plugins/telemetry/DEVICE/{deviceId}/attributes/SHARED_SCOPE
Authorization: Bearer {JWT}

{
  "targetFirmwareVersion": "v2.1.0",
  "samplingInterval": 5000
}

Thiết bị đọc qua MQTT:

# Thiết bị gửi yêu cầu:
Topic: v1/devices/me/attributes/request/1
Payload: {"sharedKeys": "targetFirmwareVersion,samplingInterval"}

# Server trả lời:
Topic: v1/devices/me/attributes/response/1
Payload: {"shared": {"targetFirmwareVersion": "v2.1.0", "samplingInterval": 5000}}

Thiết bị subscribe nhận cập nhật realtime:

# Subscribe topic:
v1/devices/me/attributes

# Khi server thay đổi, thiết bị nhận:
{"targetFirmwareVersion": "v2.2.0"}

3. Client-side Attributes

Do thiết bị tự báo cáo lên server. Server chỉ đọc, không ghi. Dùng để báo cáo trạng thái:

Phiên bản firmware hiện tại: currentFirmwareVersion
Cấu hình đang chạy: currentSamplingInterval
Trạng thái phần cứng: batteryLevel, signalStrength

Thiết bị gửi qua MQTT:

Topic: v1/devices/me/attributes
Payload: {
  "currentFirmwareVersion": "v2.1.0",
  "batteryLevel": 87,
  "signalStrength": -65
}

Thiết bị gửi qua HTTP:

POST http://localhost:8080/api/v1/{ACCESS_TOKEN}/attributes
Content-Type: application/json

{
  "currentFirmwareVersion": "v2.1.0",
  "batteryLevel": 87
}

Đọc qua API:

GET /api/plugins/telemetry/DEVICE/{deviceId}/values/attributes/CLIENT_SCOPE
Authorization: Bearer {JWT}

Kiểu dữ liệu

Attributes hỗ trợ các kiểu:

Kiểu	Ví dụ
String	`"v2.1.0"`, `"online"`
Boolean	`true`, `false`
Integer	`42`, `-5`
Double	`25.5`, `10.7769`
JSON	`{"min": 0, "max": 100}`

Đặt tên (Best Practices)

Dùng camelCase: maxTemperature, batteryLevel, firmwareVersion
Tên ngắn gọn, rõ ràng
Nhất quán trong toàn hệ thống

Đọc tất cả attributes

# Lấy tất cả scopes cùng lúc
GET /api/plugins/telemetry/DEVICE/{deviceId}/values/attributes
Authorization: Bearer {JWT}

# Lấy keys cụ thể
GET /api/plugins/telemetry/DEVICE/{deviceId}/values/attributes?keys=batteryLevel,firmwareVersion
Authorization: Bearer {JWT}

Xóa attributes

DELETE /api/plugins/telemetry/DEVICE/{deviceId}/SERVER_SCOPE?keys=obsoleteKey
Authorization: Bearer {JWT}