---
# System prepended metadata

title: Dokumentasi Smart Stove
tags: [documentation, xirka]

---

###### 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) 
