Datastreamها

Datastream یک مقدار Typeدار است که میان Firmware، Console، Studio و Dashboard منتشرشدهٔ Device مشترک می‌شود. Technical Key آن قرارداد میان این بخش‌هاست و باید دقیقاً با Key موجود در Template منتشرشده یکسان باشد.

تعریف Datastreamکپی پیوند این بخش

توابع کمکی Arduino برنامه را کوتاه نگه می‌دارند:

auto temperature = FLOVA_DATASTREAM(device, float, "temperature");
auto relay = FLOVA_DATASTREAM(device, bool, "relay");

API قابل انتقال همین Typeها را ارائه می‌کند:

auto relay = device.datastream<bool>("relay");

Datastreamها را پیش از begin() تعریف کنید. SDK هنگام Connection Device، Keyهای تعریف‌شده را با Template منتشرشده Bind می‌کند. تعریف شدن یک Datastream در Firmware بدون وجود همان Key در Template، آن را در Console قابل مشاهده نمی‌کند.

چهار مسیر کار با وضعیتکپی پیوند این بخش

FLOVA_ON_WRITE(relay, setRelay);       // فرمان راه دور
FLOVA_WRITE(relay, true);              // فرمان محلی برنامه
FLOVA_REPORT(temperature, 23.4f);      // مشاهدهٔ حسگر یا Hardware
bool enabled = FLOVA_READ(relay);      // مقدار Cache محلی

FLOVA_READ و value() Cache محلی را می‌خوانند و درخواست Network نمی‌فرستند. FLOVA_REPORT یک مشاهده را ثبت می‌کند و Handler نوشتن را اجرا نمی‌کند.

پیش از خواندن مقداری که ممکن است هنوز Restore یا دریافت نشده باشد، FLOVA_HAS_VALUE را بررسی کنید:

if (FLOVA_HAS_VALUE(relay) && FLOVA_READ(relay)) {
  digitalWrite(2, HIGH);
}

اعمال امن فرمان راه دورکپی پیوند این بخش

فرمان‌ها از مسیر run() به Handler می‌رسند:

flova::WriteResult setRelay(bool enabled) {
  digitalWrite(2, enabled ? HIGH : LOW);
  return flova::accept();
}

void setup() {
  FLOVA_ON_WRITE(relay, setRelay);
}

void loop() {
  device.run();
}

اگر Hardware فرمان را نمی‌پذیرد، به‌جای تغییر وضعیت محلی یک Rejection برگردانید. Handler باید کوتاه باشد. کار طولانی را در State برنامه قرار دهید تا حلقهٔ اصلی آن را انجام دهد و پردازش Connection متوقف نشود.

Typeهای مقدارکپی پیوند این بخش

سطح Typeدار عمومی از Boolean، عدد صحیح، عدد اعشاری، Double و متن محدود پشتیبانی می‌کند. Type زبان C++ باید با Type تعریف‌شده در Template یکی باشد. طول متن به ظرفیت Build وابسته است؛ اگر متن از کاربر می‌گیرید، نتیجه و محدودیت آن را پیش از اعمال به Hardware بررسی کنید.

Offline و Connection دوبارهکپی پیوند این بخش

Cache محلی اجازه می‌دهد Hardware هنگام قطع Network از آخرین مقدار Accepted استفاده کند. سیاست Offline به نوع Stream و Configuration Firmware بستگی دارد. پس از Connection دوباره، SDK بر اساس همان سیاست وضعیت را Sync می‌کند.

اگر Report رد شد، Network، Connection، Technical Key، Type مقدار و Version Template را بررسی کنید. Online بودن Device به‌تنهایی Accepted بودن Report را ثابت نمی‌کند.

طراحی قرارداد Templateکپی پیوند این بخش

Datastream را ابتدا در Console تعریف کنید و بعد Declaration متناظر Firmware را بنویسید. انتخاب‌های Template رفتار برنامه را مشخص می‌کنند:

Technical Key به حروف بزرگ و کوچک حساس است. temperature، Temperature و TEMPERATURE سه Key متفاوت‌اند. تغییر Key باید هم‌زمان در Template، Firmware، Dashboard، Automation و Clientهای بیرونی انجام شود.

State، Sample، Command و Eventکپی پیوند این بخش

برای مقدار فعلی Device یا Actuator از State استفاده کنید؛ برای اندازه‌گیری در یک لحظه از Sample؛ برای دستوری که Device باید اعمال کند از Command؛ و برای وقوعی مانند فشردن Button یا Alarm از Event. یک Relay که باید پس از Restart بازیابی شود معمولاً State است، در حالی که دمای حس‌شده Sample و یک Trigger یک‌بارمصرف Command یا Event است.

این انتخاب روی Restore، History، Dashboard و رفتار Offline اثر می‌گذارد. پیش از ساخت Template مشخص کنید که مقدار باید «آخرین وضعیت» باشد یا «یک اندازه‌گیری مستقل».

خواندن نمای کامل Datastreamکپی پیوند این بخش

Handle قابل انتقال می‌تواند اطلاعاتی بیشتر از Value بدهد:

auto snapshot = relay.snapshot();
if (snapshot.hasValue && snapshot.quality == flova::Quality::Good) {
  applyRelay(snapshot.value);
}

Snapshot می‌تواند زمان آخرین تغییر، Origin، Quality، Dirty بودن و Revision را شامل شود. وقتی برنامه باید مقدار Restoreشده را از Sensor تازه یا Command راه دور جدا کند، از Snapshot استفاده کنید.

Report کردن وضعیت واقعی Hardwareکپی پیوند این بخش

برای یک خروجی فیزیکی، ابتدا Command را اعمال کنید و سپس چیزی را Report کنید که Hardware واقعاً پذیرفته است:

flova::WriteResult setRelay(bool requested) {
  const bool applied = writeRelayHardware(requested);
  if (!applied) return flova::reject("hardware_rejected");
  return flova::accept();
}

void loop() {
  device.run();
  const bool measured = readRelayHardware();
  FLOVA_REPORT(relay, measured, flova::Origin::PhysicalInput);
}

به این ترتیب Value در Cloud با خروجی واقعی Relay، Driver یا Power Controller هماهنگ می‌ماند، حتی اگر Hardware به دلیل خطای برق یا محدودیت مکانیکی فرمان را نپذیرد.

ظرفیت و Historyکپی پیوند این بخش

Buildهای Embedded برای Datastream، Text، نتیجهٔ Command و History ظرفیت محدود دارند. ظرفیت را برای Board و محصول برنامه‌ریزی کنید و Container بدون حدی اضافه نکنید. Queue Overflow، History حذف‌شده یا خطای Storage نشانهٔ آن است که باید Resource Plan یا نرخ Report را بررسی کنید.

Sensor را در هر دور Loop Report نکنید. با نرخ مناسب Sample بگیرید، تغییرهای معنادار را Report کنید و زمان کافی برای Network و Hardware باقی بگذارید.

بررسی یک Value گمشدهکپی پیوند این بخش

مسیر را به همین ترتیب بررسی کنید: Device Online باشد و Template انتخاب‌شده منتشر شده باشد؛ Key Firmware با Key Template بایت‌به‌بایت یکی باشد؛ C++ Type با Value Type هماهنگ باشد؛ نتیجهٔ Report Accepted باشد؛ Latest Value در Console دیده شود؛ و در بازهٔ زمانی انتخاب‌شده یک ردیف در History وجود داشته باشد.

Online بودن، Queue Acceptance، Latest Value و History بخش‌های متفاوت مسیر را ثابت می‌کنند. Device می‌تواند Online باشد اما Datastream تعریف‌نشده یا Report ردشده داشته باشد.