CoreDash HydroLink · API

REST API · CoreDash HydroLink

API สำหรับเชื่อมต่อข้อมูล SCADA เข้ากับระบบอื่นขององค์กร (ERP, BI, BMS) ใช้มาตรฐาน REST และข้อมูล JSON ไม่ผูกขาดกับผู้พัฒนา

Base URLhttps://scada.hydrolink.example (กำหนดจริงเมื่อส่งมอบ)
เวอร์ชันv1 — เส้นทางขึ้นต้นด้วย /api/v1
รูปแบบJSON (UTF-8) · เวลาเป็น ISO 8601 พร้อมเขตเวลา (+07:00)
SpecOpenAPI 3.0 (openapi.yaml) — นำเข้า Postman / Swagger UI ได้ทันที

การยืนยันตัวตน

ทุกคำขอต้องแนบ API Key ที่ผู้ดูแลระบบสร้างจากเมนู REST API ในระบบ เลือกแบบใดแบบหนึ่ง

X-API-Key: cdhl_live_xxxxxxxxxxxxxxxxxxxxxxxx
# หรือ
Authorization: Bearer cdhl_live_xxxxxxxxxxxxxxxxxxxxxxxx

คีย์แต่ละตัวกำหนดสิทธิ์ (scope) ได้ และยกเลิกสิทธิ์ได้ทันทีโดยไม่กระทบคีย์อื่น

Scopeอนุญาต
read:latest/latest, /points, /meta/last-update
read:history/history
read:status/devices/status
read:alarms/alarms
control/control, /sim/scenario (ผู้ปฏิบัติงานขึ้นไป)

จำกัดจำนวนการเรียก

กำหนดได้ต่อคีย์ (30 / 60 / 120 / 600 ครั้งต่อนาที) ทุกคำตอบมี header

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1794667380      # epoch seconds เมื่อโควตารีเซ็ต
Retry-After: 23                    # เฉพาะเมื่อได้ 429

รูปแบบข้อมูล

ค่าตัวเลขเป็นหน่วยตามจุดตรวจวัด quality บอกคุณภาพข้อมูล: good ปกติ, bad_comm ขาดการสื่อสารกับอุปกรณ์, uncertain ค่าไม่แน่นอน

ตัวกลาง (Edge Gateway) — ข้อมูลกลายเป็น JSON ได้อย่างไร

อุปกรณ์ในตู้ควบคุมใช้โปรโตคอลอุตสาหกรรมคนละแบบ ระบบภายนอกต้องการ JSON ผ่าน HTTPS จึงมี CoreDash Edge Gateway เป็นตัวกลางในตู้ควบคุม

Inverter ACS580 ×2 ─┐
Power Meter M1M 20 ─┼─► PLC FX5U ──Modbus TCP──► Edge Gateway ──HTTPS + JSON──► Web App · มือถือ · ERP · BI
Flowmeter (RS-485) ─┘    (D-register)            อ่านทุก 1 วินาที
                                                 Alarm → LINE / Telegram / Email
                                                 ประวัติ + Audit log · AES-256-GCM
ขั้นทำอะไร
1. อ่านGateway อ่าน D-register ของ PLC ทุก 1 วินาทีตาม Register Map (เช่น D100–D101 = system.pressure แบบ float32)
2. แปลงคูณ scale ใส่หน่วย ตรวจคุณภาพข้อมูล แล้วเก็บเป็นจุดตรวจวัดชื่อเดียวกับ API
3. ให้บริการตอบคำขอ REST เป็น JSON ตรวจ API Key, scope, rate limit และเข้ารหัสเพิ่มได้
4. สั่งงานรับ POST /control ตรวจสิทธิ์และ Interlock แล้วเขียนกลับไปที่ PLC พร้อมบันทึก Audit log

ทำไมไม่ต่อ PLC ตรงกับ Cloud: PLC ส่ง HTTPS/JSON ไม่ได้ และการเปิด Modbus ออกอินเทอร์เน็ตเสี่ยงถูกสั่งงานจากภายนอก Gateway จึงเป็นจุดเดียวที่คุยกับ PLC และตรวจสิทธิ์ทุกคำสั่ง ถ้าอินเทอร์เน็ตหลุด Gateway ยังเก็บข้อมูลต่อ แล้วส่งย้อนหลังเมื่อกลับมา

เข้ารหัสข้อมูล (AES-256-GCM)

ทุกการเชื่อมต่อใช้ HTTPS อยู่แล้ว ถ้าระบบปลายทางต้องการเข้ารหัสตัวข้อมูลเพิ่ม ส่ง header นี้ (หรือผู้ดูแลกำหนดให้ API Key นั้นเข้ารหัสทุกครั้ง)

X-CD-Encrypt: aes-256-gcm

คำตอบจะเป็นซอง JSON แทนข้อมูลปกติ ถอดรหัสแล้วได้ JSON เดิมทุกประการ

{ "enc": "aes-256-gcm", "kid": "v1", "iv": "base64 12 byte", "tag": "base64 16 byte", "data": "base64" }
กุญแจ32 byte (CD_AES_KEY) สร้างด้วย node tools/keygen.js บน Gateway
IVสุ่มใหม่ 12 byte ทุกคำตอบ
ตรวจการแก้ไขtag 16 byte ในตัว (GCM) — ข้อมูลถูกแก้แม้ 1 bit ถอดรหัสจะล้มเหลว

วิธีใช้

  1. ผู้ดูแลระบบสร้างกุญแจด้วย node tools/keygen.js บน Gateway
  2. ส่งกุญแจให้ระบบปลายทางทางช่องทางปลอดภัย (ไม่ส่งทางอีเมล/แชท) และเปลี่ยนกุญแจทุก 90 วัน
  3. ระบบปลายทางเรียก API พร้อม X-CD-Encrypt: aes-256-gcm แล้วถอดรหัสตามตัวอย่าง
# Python (pip install requests cryptography)
import base64, json, requests
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
env = requests.get(URL + "/api/v1/latest", headers={"X-API-Key": KEY, "X-CD-Encrypt": "aes-256-gcm"}).json()
b = base64.b64decode
payload = json.loads(AESGCM(AES_KEY).decrypt(b(env["iv"]), b(env["data"]) + b(env["tag"]), None))
// Node.js
const b = (s) => Buffer.from(s, 'base64');
const d = crypto.createDecipheriv('aes-256-gcm', AES_KEY, b(env.iv)); d.setAuthTag(b(env.tag));
const payload = JSON.parse(Buffer.concat([d.update(b(env.data)), d.final()]));

ค่าล่าสุด

GET/api/v1/latestread:latest
พารามิเตอร์ชนิดคำอธิบาย
pointsstringรหัสจุดตรวจวัด คั่นด้วย , (ดู รายการจุดตรวจวัด)

ตัวอย่าง

curl -s "https://scada.hydrolink.example/api/v1/latest?points=system.pressure,FT-01.flow,P-01.current" \
  -H "X-API-Key: $CDPS_KEY"
{
  "data": [
    { "point": "system.pressure", "value": 4.01,  "unit": "bar",  "quality": "good", "ts": "2026-11-14T21:42:24+07:00" },
    { "point": "FT-01.flow",      "value": 104.49,"unit": "m3/h", "quality": "good", "ts": "2026-11-14T21:42:24+07:00" },
    { "point": "P-01.current",    "value": 35.7,  "unit": "A",    "quality": "good", "ts": "2026-11-14T21:42:24+07:00" }
  ],
  "meta": { "site": "DEMO-01", "generated_at": "2026-11-14T21:42:24+07:00" }
}

ข้อมูลย้อนหลัง

GET/api/v1/historyread:history
พารามิเตอร์ชนิดคำอธิบาย
point *stringจุดตรวจวัด เช่น FT-01.flow
start *ISO 8601เวลาเริ่มต้น
end *ISO 8601เวลาสิ้นสุด (ต้องมากกว่า start)
intervalenumช่วงเวลารวมข้อมูล 1m 5m 15m 1h 1d (ค่าเริ่มต้น 5m)
aggenumวิธีรวม avg min max (ค่าเริ่มต้น avg)
ได้สูงสุด 10,000 จุดข้อมูลต่อคำขอ หากเกินจะได้ 400 RANGE_TOO_LARGE ให้เพิ่ม interval หรือแบ่งช่วงเวลา
curl -s "https://scada.hydrolink.example/api/v1/history?point=FT-01.flow&start=2026-11-13T00:00:00%2B07:00&end=2026-11-14T00:00:00%2B07:00&interval=1h&agg=avg" \
  -H "X-API-Key: $CDPS_KEY"
{
  "point": "FT-01.flow", "unit": "m3/h",
  "start": "2026-11-13T00:00:00+07:00", "end": "2026-11-14T00:00:00+07:00",
  "interval": "1h", "agg": "avg", "count": 24, "truncated": false,
  "data": [
    { "ts": "2026-11-13T00:00:00+07:00", "value": 96.412 },
    { "ts": "2026-11-13T01:00:00+07:00", "value": 88.905 },
    ...
  ],
  "meta": { "site": "DEMO-01", "generated_at": "2026-11-14T21:45:02+07:00" }
}

สถานะอุปกรณ์

GET/api/v1/devices/statusread:status
{
  "devices": [
    { "id": "PLC", "name": "PLC Mitsubishi FX5U-32MR/DS", "address": "192.168.10.10", "protocol": "SLMP (MC) / Modbus TCP", "online": true, "last_update": "2026-11-14T21:42:24+07:00" },
    { "id": "INV-01", "name": "ABB ACS580-01-073A-4 + FMBT-21", "address": "192.168.10.21", "protocol": "Modbus TCP :502", "online": true, "last_update": "..." }
  ],
  "pumps": [
    { "id": "P-01", "status": "RUN",  "ready": true, "role": "LEAD", "frequency_hz": 44.62, "active_fault": null },
    { "id": "P-02", "status": "STOP", "ready": true, "role": "LAG",  "frequency_hz": 0,     "active_fault": null }
  ],
  "control": { "mode": "AUTO", "setpoint_bar": 4.0, "alternation_hours": 6, "next_alternation": "2026-11-15T01:20:00+07:00" }
}

รายการ Alarm

GET/api/v1/alarmsread:alarms
พารามิเตอร์คำอธิบาย
stateactive (ค่าเริ่มต้น) หรือ all
from, toISO 8601 ช่วงเวลาที่เกิด Alarm
{
  "state": "active", "count": 1,
  "data": [
    { "id": "ALM-1001", "code": "P1_FAULT", "severity": "critical", "tag": "INV-01",
      "message": "P-01 Inverter Fault 2310 Overcurrent — กระแสเกิน",
      "raised_at": "2026-11-14T21:42:19+07:00", "cleared_at": null, "ack_by": null, "ack_at": null }
  ]
}

เวลาอัปเดตล่าสุด

GET/api/v1/meta/last-updateread:latest
{ "last_update": "2026-11-14T21:42:24+07:00", "age_seconds": 1, "source": "PLC FX5U-32MR/DS" }

รายการจุดตรวจวัด

GET/api/v1/pointsread:latest

ภาพรวมทั้งหมดเป็นไฟล์ JSON

GET/api/v1/exportread:latest

ได้ค่าล่าสุดทุกจุด ค่าตั้ง และ Alarm ที่ค้างอยู่ในไฟล์เดียว (รูปแบบเดียวกับปุ่ม “ส่งออกภาพรวม” ใน Web App)

{ "format": "coredash.snapshot/v1", "site": "DEMO-01", "generated_at": "2026-11-15T09:30:00Z",
  "values":   { "system.pressure": 4.01, "FT-01.flow": 106.2, "P-01.run": 1, "P-01.freq": 45.0, "…": "…" },
  "settings": { "CTRL.sp": 4.0, "CTRL.int_start": 30, "CTRL.int_stop": 60, "CTRL.alt_hours": 6, "…": "…" },
  "alarms_active": [] }

สั่งงาน

POST/api/v1/controlcontrol
commandargsผล
start / stop{"pump": 1}สั่งเดิน/หยุดปั๊ม (โหมด MANUAL)
reset{"pump": 2}Reset Fault (DI02)
alternate—สลับปั๊มหลักทันที
mode{"mode": "AUTO"}AUTO / MANUAL
config{"sp": 4.2, "intervalStart": 30, "intervalStop": 60, "altHours": 6, "kp": 0.8, "ti": 3, "deadband": 0.15, "lowAlarm": 3.5, "highAlarm": 5.5}ตั้งค่าควบคุม (ตรวจช่วงค่า เช่น sp 2–6 bar)
curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
     -d '{"command":"config","args":{"sp":4.2}}' https://scada.hydrolink.example/api/v1/control
# 202 { "accepted": true, "command": "config", "writes": [ { "point": "CTRL.sp", "value": 4.2 } ] }
# 409 INTERLOCK — เช่น กด E-Stop อยู่แล้วสั่งเดินปั๊ม

ทดสอบด้วยไฟล์ JSON

เตรียมไฟล์ค่าตามเวลา แล้วอัปโหลดใน Web App (แถบ 📄 ไฟล์ทดสอบ) หรือส่งให้ Gateway ขณะรันโหมดจำลอง ทุกหน้าจอ ค่าตั้ง และ Alarm ทำงานตามไฟล์ — ใช้ทดสอบระบบและสาธิตก่อนติดตั้งจริง

{ "format": "coredash.scenario/v1",
  "description": "P-01 Fault → ปั๊มสำรองรับงาน",
  "loop": true, "interpolate": true,
  "settings": { "CTRL.sp": 4.0 },
  "frames": [
    { "t": 0,  "values": { "system.pressure": 4.0, "P-01.run": 1, "P-01.freq": 45 } },
    { "t": 41, "values": { "system.pressure": 3.6, "P-01.run": 0, "P-01.fault": 2310 }, "note": "P-01 Fault" },
    { "t": 46, "values": { "P-02.run": 1, "P-02.freq": 30, "CTRL.lead": 2 }, "note": "Failover" } ] }
ฟิลด์ความหมาย
tวินาทีนับจากเริ่ม เรียงจากน้อยไปมาก
valuesชื่อจุดตรวจวัดเหมือน API · จุดที่ไม่ระบุจะคงค่าเดิม
interpolateค่าตัวเลขเปลี่ยนแบบต่อเนื่องระหว่าง frame (สถานะ 0/1 และ Fault code เปลี่ยนทันที)
noteข้อความแสดงบนแถบด้านบนขณะเล่นถึงช่วงนั้น
POST/api/v1/sim/scenariocontrol · วิศวกรขึ้นไป · SIMULATE=1

ตัวอย่างพร้อมใช้: scenario-peak.json · scenario-p01-fault.json · scenario-power-estop.json

รหัสข้อผิดพลาด

{ "error": { "status": 429, "code": "RATE_LIMITED", "message": "เกินจำนวนการเรียกที่กำหนด 60 ครั้ง/นาที" } }
HTTPcodeสาเหตุแนวทางแก้
400INVALID_PARAMETERพารามิเตอร์ผิดรูปแบบตรวจ start/end/interval/agg
400RANGE_TOO_LARGEเกิน 10,000 จุดข้อมูลเพิ่ม interval หรือแบ่งช่วง
401UNAUTHORIZEDไม่ได้ส่ง API Keyแนบ X-API-Key
401INVALID_API_KEYคีย์ผิดหรือถูกยกเลิกขอคีย์ใหม่จากผู้ดูแลระบบ
403FORBIDDENคีย์ไม่มี scope ที่ต้องใช้ขอเพิ่ม scope
409INTERLOCKคำสั่งขัดกับ Interlock (เช่น E-Stop)แก้สาเหตุที่หน้างานก่อน
501ENCRYPTION_NOT_CONFIGUREDขอเข้ารหัสแต่ยังไม่ได้ตั้งกุญแจผู้ดูแลรัน tools/keygen.js
400ENCRYPTION_NOT_ALLOWEDขอวิธีเข้ารหัสอื่นที่ไม่ใช่ AES-256-GCMใช้ X-CD-Encrypt: aes-256-gcm
404POINT_NOT_FOUNDไม่พบจุดตรวจวัดดู GET /points
429RATE_LIMITEDเกินโควตาต่อนาทีรอตาม Retry-After
503DEVICE_OFFLINEอุปกรณ์ต้นทางขาดการสื่อสารลองใหม่ / ตรวจสถานะ
500INTERNAL_ERRORข้อผิดพลาดภายในแจ้งผู้ดูแลพร้อม X-Request-Id

รายการจุดตรวจวัด

ครอบคลุมค่าที่ PLC อ่านจากปั๊ม Inverter มิเตอร์ และ Flowmeter ทั้งหมด

pointชื่อหน่วย

ตัวอย่างโค้ด

Python

import requests
r = requests.get("https://scada.hydrolink.example/api/v1/latest",
                 params={"points": "system.pressure,FT-01.flow"},
                 headers={"X-API-Key": CDPS_KEY}, timeout=10)
r.raise_for_status()
for p in r.json()["data"]:
    print(p["point"], p["value"], p["unit"])

JavaScript

const res = await fetch("https://scada.hydrolink.example/api/v1/devices/status", {
  headers: { Authorization: `Bearer ${CDPS_KEY}` }
});
const { pumps } = await res.json();
console.table(pumps);

Power BI / Excel (Power Query)

let
  Src = Json.Document(Web.Contents("https://scada.hydrolink.example/api/v1/history",
        [Query=[point="FT-01.flow", start="2026-11-01T00:00:00+07:00", end="2026-12-01T00:00:00+07:00", interval="1d"],
         Headers=[#"X-API-Key"=CDPS_KEY]])),
  T = Table.FromRecords(Src[data])
in T

CoreDash Technology · โทร 081-923-2380