Wireless Sensor Payload Protocol

Doküman Versiyonu: 1.0
Tarih: Ocak 2026

Amaç ve Kapsam

Bu doküman, PowerStat ekosisteminde LoRa tabanlı kablosuz sensör node’larının uplink yönünde göndereceği sabit boyutlu (fixed-size) uygulama katmanı paket formatını tanımlar.

Tasarım öncelikleri:

• Ultra düşük güç tüketimi (node tarafı)
• Minimum airtime (RF tarafı)
• Sahada deterministik çalışma (basit, sürprizsiz akış)
• Backend tarafında hızlı ve güvenli çözümleme

Node; yalnızca ham sensör verisini ve kendi donanım sağlığını iletir. Limit/eşik/alarm kararları ve tüm değerlendirme mantığı server/backend tarafında yürütülür.

Bu yaklaşımın amacı, node firmware’ini basit tutmak ve sahada “kural seti değişti” gibi durumlarda node güncelleme ihtiyacını minimize etmektir.

---

Paket Formatı Genel Özellikler

• Toplam Boyut: 21 byte (sabit)
• Endian: Çok byte’lı alanlar big-endian (MSB first)
• Checksum: Özel 1-byte doğrulama mekanizması
• Versiyonlama: Version_Maj.Version_Min biçiminde 2 byte

Kodlama Kuralları

• Çok byte’lı alanlar big-endian (MSB first) kodlanır.
• Sayısal alanlar unsigned kabul edilir.
• Kullanılmayan/verisi olmayan sensör alanları 0x0000 gönderilir.
• Receiver tarafında Checksum doğrulanmadan paket işlenmemelidir.

---

Byte Yerleşimi

Byte Index	Alan Adı	Boyut	Açıklama
0	Version_Maj	1 B	Major versiyon
1	Version_Min	1 B	Minor versiyon
2–9	Device_ID	8 B	64-bit benzersiz ID
10–11	Flags	2 B	16-bit node health bit alanı
12–13	Battery_mV	2 B	Batarya voltajı (mV)
14–15	Sensor1	2 B	Sensör verisi ×1000 (yoksa 0)
16–17	Sensor2	2 B	Sensör verisi ×1000 (yoksa 0)
18–19	Sensor3	2 B	Sensör verisi ×1000 (yoksa 0)
20	Checksum	1 B	Doğrulama byte’ı

Toplam: 21 byte

Device_ID alanı 64-bit benzersiz kimliktir. PowerStat mimarisinde bu alan, DS28C gibi donanım kimlik bileşenlerinden türetilen “değişmez” kimlik olarak kullanılmalıdır.

---

Flags (16-bit Health/Status Map)

Flags alanı node’un yalnızca kendi donanım/çalışma sağlığını bildirir. Eşik/limit/alarma karar veren kural mantığı backend tarafındadır.

Genel Durum Bitleri

Bit	İsim	Açıklama
0	ALARM_ACTIVE	Node'da kritik seviye fault var
1	WARNING_ACTIVE	Uyarı seviyesi durum

Batarya & Sensör Sağlığı

Bit	İsim	Açıklama
2	LOW_BATTERY	Pil düşük
3	SENSOR_GLOBAL_ERROR	Genel sensör okuma hatası
4	S1_FAULT	Sensör1 arızası
5	S2_FAULT	Sensör2 arızası
6	S3_FAULT	Sensör3 arızası

Node Durumu

Bit	İsim	Açıklama
7	NODE_BOOT	Node yeni açıldı
8	CONFIG_DIRTY	Konfigürasyon değişikliği, ACK bekleniyor
9	INTERNAL_ERROR	Firmware içi hata (watchdog vb.)

Ayrılmış Bitler

Bit	Durum
10–15	RESERVED (0 gönderilir)

RESERVED bitler her zaman 0 gönderilmelidir. Receiver tarafı bu bitleri yok saymalı, böylece ileriye dönük genişletmeler geriye uyumluluğu bozmaz.

---

Sensör Veri Formatı

Her sensör alanı 2 byte uint16 şeklindedir.

Ölçekleme:

$ext_{raw\_value} = \text{real\_value} \times 1000$

$ext_{real\_value} = \frac{\text{raw\_value}}{1000}$

Örnek:

• 12.345 → gönderilen: 12345 → 0x3039
• Sensör yok / geçersiz → 0x0000

Not: Alan tipi uint16 olduğu için negatif değerler doğrudan temsil edilemez. Negatif aralığı olan sensörlerde (ör. sıcaklık) iki yaklaşım önerilir: (1) offset ile unsigned aralığa taşıma, (2) ayrı bir Sx_FAULT/durum biti ile “geçersiz/ölçülemedi” senaryosunu işaretleyip değer alanını 0 bırakma.

Paket her zaman sabit 21 byte olduğu için kullanılmayan sensörler 0 olarak gönderilir.

---

Checksum Hesaplama

Checksum, uygulama katmanında basit bütünlük kontrolü sağlar.

Bu mekanizma kriptografik güvenlik sağlamaz; yalnızca paket bozulmalarını hızlı yakalamak için tasarlanmıştır. Daha güçlü hata yakalama istenirse gelecekte RESERVED alanlarının bir kısmı CRC8/CRC16 için kullanılabilir (paket boyutu korunacak şekilde).

Hesaplama

Veri dizisi:

$D_0, D_1, \dots, D_{19}$

1. Veri toplamı:

$S = \left(\sum_{i=0}^{19} D_i\right) \bmod 256$

2. Checksum:

$\mathrm{CHK} = (255 - S) \bmod 256$

Doğrulama

Tüm 21 byte için:

$T = \left(\sum_{i=0}^{20} B_i\right) \bmod 256$

Geçerli paket koşulu:

$T = 255$

---

Örnek Paket

Cihaz verileri:

• Version = 01.02
• Device_ID = 11 22 33 44 55 66 77 88
• Flags = 00 05
• Battery = 0F 0A (3850 mV)
• Sensor1 = 30 39 (12.345)
• Sensor2 = 02 A6 (0.678)
• Sensor3 = 00 00

İlk 20 byte:

Toplam:S = 0x96

Checksum: CHK = 0x69

Tam Paket (21 byte):

HEX string: $0x0102112233445566778800050F0A303902A6000069$

---

Backend Decoder Önerileri

• Byte offset tablosuna göre ayrıştırma yapılmalı.
• Flags bitleri maske ile değerlendirilmelidir.
• Sensör değerleri: $\text{real\_value} = \frac{\text{raw}}{1000}$
• Device_ID backend’de benzersiz kimlik olarak kullanılabilir.
• Checksum doğrulanmadan paket işlenmemelidir.

Örnek çözümleme akışı (pseudo-code):

if (sum(packet[0..20]) & 0xFF) != 0xFF: reject
maj = packet[0]
min = packet[1]
device_id = packet[2:10]
flags = (packet[10] << 8) | packet[11]
batt_mv = (packet[12] << 8) | packet[13]
s1 = ((packet[14] << 8) | packet[15]) / 1000.0
s2 = ((packet[16] << 8) | packet[17]) / 1000.0
s3 = ((packet[18] << 8) | packet[19]) / 1000.0

---

Gelecek Genişletmeler

• Reserved bitler gelecekte ek fonksiyonlar için kullanılabilir.
• Yeni sensör türleri eklenebilir (kullanılmayan alanlar yine 0 gönderilir).
• Gerektiğinde heartbeat-only veya config-only paketleri için Version alanı içinde tip genişletmesi yapılabilir.
• İhtiyaç halinde “paket tipi” (data/heartbeat/config) bilgisi, boyut büyütmeden Flags içindeki RESERVED bitlerden birine taşınabilir.

---

Sonuç

Bu protokol tarla koşullarında çalışan kablosuz sensörler için:

• Güvenilir,
• Hafif,
• Minimum airtime kullanan,
• Sabit paket boyutu sayesinde hızlı çözümlenen,
• Backend tarafında tamamen esnek

bir yapı sunmaktadır.

Tüm node firmware, gateway ve backend yazılımları bu formata uyumlu olmalıdır.