GNSS API Tester Arduino IDE

Test API — รายการ endpoint เรียกเร็ว ๆ

กดปุ่มเดียวต่อ endpoint เพื่อตรวจว่า reachable — เกณฑ์ PASS = status < 500 (เขียว <300 · เหลือง 4xx · แดง 5xx/network error). หมายเหตุ: satellite-track ที่ไม่ส่ง constellation จะคืน 422 ตาม design. ระบบรันอัตโนมัติครั้งแรกเมื่อเปิด tab นี้ (ครั้งเดียวต่อการโหลดเพจ ป้องกัน rate limit).

Request history

Arduino IDE Code — Firmware ESP32-S3 จริง (GNSS01 · v1.0.3)

โค้ด firmware ที่รันอยู่บนบอร์ดล่าสุด — แสดงทุกไฟล์ในโฟลเดอร์โปรเจกต์ พร้อม Copy / Download ใส่ Arduino IDE

วิธีใช้ใน Arduino IDE (ละเอียด)

1) ติดตั้งบอร์ด ESP32 (ครั้งเดียว)

• File → Preferences → ช่อง "Additional boards manager URLs" ใส่:
  https://dl.espressif.com/dl/package_esp32_index.json
• Tools → Board → Boards Manager… → ค้นหา esp32 → ติดตั้ง esp32 by Espressif Systems

2) ติดตั้งไลบรารี (Sketch → Include Library → Manage Libraries…)

• ArduinoJson (Benoit Blanchon) — สร้าง/แยก JSON ใน payload
• OneWire (Paul Stoffregen) — โพรโทคอล 1-Wire
• DallasTemperature (Miles Burton) — เซนเซอร์ DS18B20

3) เลือกบอร์ดและตั้งค่า (สำคัญมาก)

4) ต่อสายจริง (อิงจาก config.h)

DS18B20: VDD=3V3, GND, DATA พร้อม 4.7kΩ ระหว่าง DATA กับ 3V3 (ต่อได้ 1 ตัว/ขา ตามโค้ด)
โมดูล GNSS ใช้ไฟ 3.3V และใช้ระดับสัญญาณ TTL 3.3V — ห้ามต่อ 5V หรือ RS-232 โดยตรง

5) ตั้งค่า config.h แล้วอัปโหลด

• เปิด config.h เติมค่าจริง: WIFI_SSID, WIFI_PASSWORD, API_KEY (key ของ device นี้)
• กด Upload (→) แล้วเปิด Serial Monitor baud 115200
• เห็น log: LOCAL=… collecting=1 fix=1 … sats=20 … WiFi=1 แปลว่ารันปกติ (อัปโหลดทุก 5 นาที = INTERVAL_SECONDS 300)

Request Format (JSON Schema v1.0)

ตัวอย่าง payload

Response Format

Success envelope

HTTP 200/201
{
  "success": true,
  "status": 200,
  "message": "ok",
  "data": { ... }
}

Error envelope

HTTP 4xx/5xx
{
  "success": false,
  "status": 422,
  "error": {
    "code": "INVALID_TIMESTAMP",
    "message": "คำอธิบาย",
    "field": "position.latitude"      // optional
  }
}

Status code ที่ใช้

รายละเอียดเพิ่มเติม

• ทุก response เป็น JSON: Content-Type: application/json; charset=utf-8 (ยกเว้น export-csv/excel ที่ดาวน์โหลดไฟล์)
• POST 201 คืน data = {"measurement_id": <id>, "duplicate": false} · POST 200 (duplicate) คืน {"measurement_id": …, "duplicate": true}
• message มีในทั้ง success และ error envelope
• data เป็น object {} ว่าง สำหรับ success ที่ไม่มีข้อมูลเพิ่มเติม
• error field มีเฉพาะ validation fail บางรายการ (เช่น position.latitude) — ไม่ใช่ทุก error
• ทุก response มี header rate limit: X-RateLimit-Limit / Remaining / Reset · 429 เพิ่ม Retry-After
• 404 Not found = เส้นทาง API ไม่มี (web server) ส่วน endpoint ที่ device ไม่มีข้อมูลจะตอบ 200 NO_DATA ไม่ใช่ 404
• GET ที่ query ได้แต่ไม่มีข้อมูลตามช่วงจะยังตอบ 200 โดย data.device.status="NO_DATA" และ data.measurement=null (ไม่ใช่ error)

Authentication

• GET endpoints ไม่ต้องใช้ key (เปิดอ่านได้) — อาจเจอ rate limit GET 120/นาที/IP
• GET มีตัวเลือก device (default GNSS01) ให้ระบุ device ที่ต้องการอ่าน
• POST ต้องส่ง header X-API-Key: <device API key> (ไม่รองรับ Authorization: Bearer)
• Header อื่นที่ต้องใช้: Content-Type: application/json (ผิด → 415 INVALID_REQUEST)
• Key ถูก hash ด้วย SHA-256 เก็บในตาราง devices.api_key_hash (ไม่เก็บ plaintext)
• key ผูกเฉพาะ device — device_id ใน payload ต้องตรงกับ device ของ key (ไม่ตรง → 422 INVALID_DEVICE_ID)
• key ถูกต้องแต่ device ถูกปิด (enabled=0) → 403 DEVICE_DISABLED
• key ไม่มีในระบบ → 401 INVALID_API_KEY · ขาด header → 401 MISSING_API_KEY
• ทุกคำขอ POST ผ่าน auth ก่อนแล้วจึงนับ rate limit ต่อ device

วิธีได้ key

ลงทะเบียน device ในระบบ / request จากผู้ดูแลระบบ แล้วใส่ในช่อง API Key ด้านบนก่อน POST.

ลำดับการประมวลผล POST (gnss.php)

1. Method ตรวจ (ต้อง POST)
2. Auth ผ่าน X-API-Key (401/403 ก่อนอย่างอื่น)
3. อ่าน payload JSON (grade: 400 INVALID_JSON / 413 too large / 415 wrong Content-Type)
4. ตรวจ device_id ไม่ตรงกับ key → 422
5. Rate limit POST 60/นาที/device (429 + Retry-After)
6. Validate schema v1.0 (422 ต่อ field)
7. Idempotency: uuid ซ้ำ timestamp ตรง → 200 duplicate · uuid ซ้ำ payload ต่าง → 409 · device+timestamp ซ้ำ → 409
8. Transaction: insert measurement + satellites + last_seen → 201

Application error codes

Rate limit (window 60 วินาที, นับด้วยตาราง api_request_logs)

• POST: 60 requests / นาที / device (นับหลัง auth ผ่าน แล้วค่อยตรวจ)
• GET: 120 requests / นาที / IP (ตรวจก่อนเข้า endpoint ทุกตัว)
• ทุก response (สำเร็จหรือ error) มี X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (epoch seconds)
• เกิน limit → 429 RATE_LIMIT_EXCEEDED พร้อม header Retry-After = วินาทีที่เหลือจนกว่าจะรีเซ็ต
• นับรวมทุก endpoint/method เดียวกัน — เช่น เปิด tab Quick Test อัตโนมัติ 15 GETs กินโควตา GET ด้วย
• firmware ต้องอ่าน Retry-After แล้ว schedule ใหม่ (backoff) ไม่รีส่งต่อเนื่อง

Automated test suite

อ่านข้อมูลแบบ read-only 15 cases + ถ้าใส่ API Key จะเพิ่ม 3 POST cases (รวม 18). หมายเหตุ: สำเร็จ = status < 500 (เช่น satellite-track ที่คืน 422 โดย design ยังถือว่า PASS).

API request logs

API usage charts (aggregate จาก api-logs)

API documentation

รวม endpoint ทั้งหมดของระบบ พร้อมพารามิเตอร์ GET (device เป็นค่าพื้นฐานที่ append ให้อัตโนมัติ)

ตัวอย่าง curl

# GET
curl "https://project12569.theeeiot.com/EE67172310228/api/v1/latest.php?device=GNSS01"

# POST
curl -X POST "https://project12569.theeeiot.com/EE67172310228/api/v1/gnss.php" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_DEVICE_KEY>" \
  -d @payload.json