###### tags : `xirka` `documentation` # Dokumentasi Smart Stove [toc] # A. Spesifikasi Pembacaan Data Sensor ## 1. Skema ```sequence Note left of Kompor: Pengukuran sensor Note left of Kompor: Membuat token JWT Kompor->Aplikasi: Membaca token Note left of Aplikasi: Decode token body Note left of Aplikasi: Menampilkan data Aplikasi->Server: Mengirim token Note left of Server: Verifikasi token Note left of Server: Decode token Server->Database: Menyimpan data ``` #### 1. Pengukuran sensor a. Kompor melakukan pengukuran sensor meliputi penggunaan energi, power dan waktu pengukuran. b. Token dibuat dari data dengan mekanisme JWT dengan kunci yang unik. c. Kompor menyediakan API untuk pembacaan token JWT baik dengan menggunakan QR Code atau bluetooth #### 2. Aplikasi a. Aplikasi membaca data melalui pemindaian qrcode atau bluetooth b. Token yang dibaca pada poin (a) diparsing kemudian ditampilkan pada aplikasi. c. Aplikasi mengirimkan token ke server secara otomatis. #### 3. Server a. Server memvalidasi token JWT dengan kunci. b. Data yang valid disimpan ke dalam database ## 2. Format Data ### 2.1 Format Data Mentah Data disimpan dalam format teks yang memuat informasi versi, id kompor, timetag, tegangan, arus, daya, power factor, stand energi nyata dan energi bulan berjalan | Field | Deskripsi | Satuan | Ketentuan | QR Code | Bluetooth | | -------- | -------- | -------- | -------- | -------- | -------- | | vs | Versi API | - | V01 | &#9745; | &#9745; | | id | ID Kompor | - | 11 Digit | &#9745; | &#9745; | | t | Epoch Time/ Unix time | Detik | - | &#9745; | &#9745; | | V | Tegangan rms rata-rata 5 menit | volt | xxx | - | &#9745; | | I | Arus rms rata-rata 5 menit | ampere | xx.xxx | - | &#9745; | | P | Daya rata-rata 5 menit | watt | xxxx | - | &#9745; | | PF | Power Factor rata-rata 5 menit | - | x.xx | - | &#9745; | | E | Energi Akumulatif | kWh | xxxxx.xxx | &#9745; | &#9745; | | EM | Energi Bulan berjalan | kWh | xxxx.xxx | &#9745; | &#9745; | - Body token Qr Code : ``` // format {vs};{id}:{t}:{E};{EM};APIKEY01; // contoh V01;00000000001;1646646860;00010.000;0002.000;APIKEY01; ``` - Body token Bluetooth : ``` // format {vs};{id}:{t}:{V}:{I}:{P}:{PF}:{E};{EM};APIKEY01; // contoh V01;00000000001;1646646860;220;32.000;1000;5.12;00010.000;0002.000;APIKEY01; ``` ### 2.2 Data Token JWT Data mentah dikonversi dengan mekanisme JWT. Mekanisme ini merupakan standar terbuka (RFC 7519) yang mendefinisikan cara untuk mentransmisikan informasi antar pihak secara aman sebagai objek JSON. Meski data bisa dibaca oleh pihak lain, data yang didalam token tidak bisa dimanipulasi karena memuat `signature` yang memuat validitas data. JWT terdiri atas tiga bagian yang dipisahkan oleh tanda titik, antara lain : - `Header` memuat informasi `type` dan algoritma yang digunakan. - `Payload` memuat informasi data yang diterbitkan - `Signature` adalah hash gabungan dari header, payload dan sebuah `secret key`. > untuk keperluan keamanan sebaiknya `secret key` memuat random string dengan minimum 32 karakter. > Informasi payload tidak boleh memuat data yang sifatnya rahasia. > Enkripsi : SHA256 #### Contoh Berikut adalah contoh token JWT dengan algoritma HMAC SHA256 dan secret : `spat9uv8choh4pl2lhewA3otrabldrUqasep` ``` // data V01;00000000001;1646646860;00010.000;0002.000;APIKEY01; // token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.VjAxOzAwMDAwMDAwMDAxOzE2NDY2NDY4NjA7MDAwMTAuMDAwOzAwMDIuMDAwO0FQSUtFWTAxOw.5JHaQso8bUvKDcIJkz1k__FBV9j0xLo0L8e54NfmGmw ``` ``` // data "V01;00000000001;1646646860;220;32.000;1000;5.12;00010.000;0002.000;APIKEY01;" // token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.VjAxOzAwMDAwMDAwMDAxOzE2NDY2NDY4NjA7MjIwOzMyLjAwMDsxMDAwOzUuMTI7MDAwMTAuMDAwOzAwMDIuMDAwO0FQSUtFWTAxOw.XFep22dBJsVsFv3mRbGtGI93DlOipdkqeviR57kLcBg ``` ## 3. Pembacaan Data Token yang dibuat dengan mekanisme JWT bisa diakses oleh aplikasi baik dengan menggunakan QR Code atau komunikasi melalui bluetooth. ### 3.1 QR Code Berikut adalah resume spesifikasi dari QR Code kompor. | Item | Deskripsi | | -------- | -------- | | Informasi | Token JWT (Hanya body + signature) yang memuat pengukuran sensor| | Warna | Background putih dan warna blok hitam | | Ukuran LCD | +- 1.8 inch | | Contoh | ![](https://i.imgur.com/6WBUPVT.png) | > catatan : dari contoh token jwt di atas: nilai yang ditampilkan pada qrcode adalah : `VjAxOzAwMDAwMDAwMDAxOzE2NDY2NDY4NjA7MDAwMTAuMDAwOzAwMDIuMDAwO0FQSUtFWTAxOw.5JHaQso8bUvKDcIJkz1k__FBV9j0xLo0L8e54NfmGmw` > ### 3.2 Bluetooth Berikut adalah resume spesifikasi dari Bluetooth kompor. | Item | Deskripsi | | -------- | -------- | | Versi | Versi 5| | Kompatibilitas | Android 4 dan Iphone 4s | | Informasi | Token JWT (Hanya body + signature) yang memuat pengukuran sensor | | Akses | Klien hanya diperbolehkan untuk membaca pengukuran sensor | ## 4. Pengiriman data ke server Data token yang telah dibaca oleh aplikasi, dikirim ke REST API server melalui jaringan internet. | Item | Nilai / Deskripsi | | -------- | -------- | | URL | `<baseUrl>/api/v1/stove-payload` | | Metode | POST | | Autentikasi | Bearer Token| | Body | `{ payload: <token>, username: <username>, method: <metode_pembacaan> }`| Contoh Pengiriman data: ```curl // request curl --location --request POST 'http://192.168.2.7:8081/api/v1/stove-payload' \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwicm9sZSI6InN1cGVydXNlciIsImlhdCI6MTY0Njk2ODk1MCwiZXhwIjoxNjQ2OTc5NzUwfQ.UVV8yQKTOQtdhmgPUR9jhyprPi-gnxuz-WCzUybHASQ' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'username=klien-1' \ --data-urlencode 'payload=VjAxOzAwMDAwMDAwMDAxOzE2NDY2NDY4NjA7MDAwMTAuMDAwOzAwMDIuMDAwO0FQSUtFWTAxOw.5JHaQso8bUvKDcIJkz1k__FBV9j0xLo0L8e54NfmGmw' \ --data-urlencode 'method=qrcode' ``` > Jika klien tidak memiliki jaringan internet, pada aplikasi bisa ada opsi simpan gambar. Dan mengirim otomatis jika ada koneksi internet. # B. Spesifikasi Update Kompor ID / Secret Key ```sequence Note left of Aplikasi: generate data Aplikasi->Server: Verifikasi data Server->Aplikasi: ack Aplikasi->Kompor: Mengubah nilai data Note left of Kompor: Verifikasi data Note left of Kompor: Ubah nilai data Kompor->Aplikasi: ack Aplikasi->Server: Ubah ID data ``` Catatan : - supaya tidak terjadi konflik, disarankan skema ini bisa digunakan jika terhubung ke server. - data yang dimaksud adalah nilai kompor ID atau secret key ```json // data untuk mengubah nilai kompor ID { "id": <kompor_id>, "cmd": "id", "data": { "id": <kompor_id_baru> } } // data untuk mengubah nilai secret ID { "id": <kompor_id>, "cmd": "secret", "data": { "prevSecret": <secret_key_lama>, "newSecret": <secret_key_baru> } } ``` # C. Lain-lain <!-- - Dokumentasi API smart stove bisa diakses di [sini](https://hackmd.io/@mraditya/BJ1ecbX-c) --> - [sumber spesifikasi kompor PLN](https://drive.google.com/file/d/1Iwd2UGj-RhOXvWvrfbbMhpkG_c6q4MLM/view?usp=sharing)