مرجع عمومی API
مرجع کلاس‌ها، توابع کمکی و Typeهای عمومی FlovaSDK.
این صفحه سطح عمومی برنامه را که در راهنماها استفاده شده فهرست می‌کند. برای امضای دقیق و Overloadهای مخصوص هر Target، Headerهای ارائه‌شده در نسخهٔ FlovaSDK را ببینید. به Classها و Typeهای داخلی که در این صفحه نیامده‌اند وابسته نشوید.
Facadeهای برد
| Type | کاربرد |
|---|---|
FlovaEsp32 | برنامهٔ سفارشی ESP32 با Flova Link یا MQTT اختیاری. |
FlovaEsp8266 | برنامهٔ سفارشی ESP8266 با همان مدل Typeدار Datastream. |
FlovaUniversalEsp32 | ترکیب کامل ESP32 با Provisioning و رفتار Device تحت مدیریت Flova. |
FlovaUniversalEsp8266 | ترکیب کامل ESP8266. |
FlovaLinux | Process دستگاه در Linux یا Raspberry Pi. |
flova::Device | هستهٔ قابل انتقال برای برد یا Gateway سفارشی. |
متدهای چرخهٔ اجرا
| متد | کاربرد |
|---|---|
begin() | Facade انتخاب‌شده را آماده می‌کند و Session را بازیابی یا آغاز می‌کند. |
run() | یک گام محدود از Connection، Configuration و پردازش فرمان را انجام می‌دهد. |
connected() | وضعیت فعلی Connection مربوط به Transport را گزارش می‌کند. |
datastream<T>(key) | یک مرجع Typeدار برای Datastream می‌دهد. |
value() | مقدار موجود در Cache محلی را می‌خواند. |
write(value) | یک فرمان محلی از طرف برنامه را اعمال می‌کند. |
report(value) | مشاهدهٔ حسگر یا وضعیت واقعی Hardware را Report می‌کند. |
onWrite(handler) | Handler مرز Hardware برای فرمان راه دور را ثبت می‌کند. |
توابع کمکی Arduino
FLOVA_DATASTREAM(device, bool, "relay")
FLOVA_SETTING(device, double, "threshold", 35.0)
FLOVA_ON_WRITE(relay, setRelay)
FLOVA_WRITE(relay, true)
FLOVA_READ(relay)
FLOVA_REPORT(temperature, 23.4f)
FLOVA_HAS_VALUE(relay)توابع کمکی را پس از تعریف Device و پیش از begin() استفاده کنید.
کلید فنی را در یک محل ثابت نگه دارید تا بین Firmware و Template تغییر نکند.
اگر برنامه به Type یا رفتار مخصوص Target نیاز ندارد، از
<FlovaSDK.h> شروع کنید.
نتیجه و وضعیت نوشتن
flova::WriteResult وضعیت‌های Accepted،
Rejected، NoChange و Failed را گزارش
می‌کند. وقتی برنامه باید بداند مقدار واقعاً پذیرفته شده است یا نه، نتیجه را
بررسی کنید. فرمان ردشدهٔ Hardware نباید وضعیت برنامه یا SDK را به‌طور بی‌صدا
تغییر دهد.
Typeهای عمومی مقدار شامل Boolean، int64_t، float،
double و متن محدود هستند. Enumهای عمومی Lifecycle و Diagnostic
در Headerهای SDK تعریف شده‌اند. به Protocolهای تولیدشده یا Classهای خصوصی
Adapter وابسته نشوید.
متدهای وضعیت
برنامه‌های سفارشی Arduino می‌توانند بدون ورود به پیاده‌سازی Transport، مرزهای چرخهٔ اجرا را بررسی کنند:
| متد | کاربرد |
|---|---|
networkConnected() | Network برنامه در دسترس است. |
tlsReady() | پیش‌نیازهای TLS یا Transport امن آماده هستند. |
runtimeReady() | Runtime احراز هویت‌شدهٔ Flova آماده است. |
ready() | Facade برای کار عادی Device آماده است. |
status(output) | یک نمای لحظه‌ای محدود برای Diagnostic می‌نویسد. |
setStatusListener(...) | تغییرهای Lifecycle را مشاهده می‌کند. |
startProvisioning() | Session Flova را پاک و منتظر Handoff تازه می‌ماند. |
factoryReset() | وضعیت خصوصی Flova را از مسیر Facade بازنشانی می‌کند. |
وضعیت برای نشانگر محصول یا صفحهٔ Maintenance مفید است، اما جای Accepted Command یا Telemetry تازه را نمی‌گیرد.
متدهای Firmware و توان
Facadeهای Target ممکن است این عملیات Lifecycle را ارائه کنند:
| متد | کاربرد |
|---|---|
setFirmwareTarget(target) | شناسهٔ Target گزارش‌شدهٔ Image را تعیین می‌کند. |
enableOta(enabled) | مسیر OTA مربوط به Target را فعال یا غیرفعال می‌کند. |
setOtaProfile(...) | روش OTA و Boot Layout را مشخص می‌کند. |
setRestartHandler(...) | اجرای Restart را به برنامه می‌سپارد. |
restartRequired() | بررسی می‌کند Runtime به Restart نیاز دارد یا نه. |
prepareForPowerDown() | پیش از Sleep یا قطع برق کار SDK را آرام می‌کند. |
فقط از متدهای Target انتخاب‌شده استفاده کنید. Service Supervisor در Linux، Boot Layout در ESP32 و Staged Update در ESP8266 مرزهای مالکیت یکسانی ندارند.
مدیریت نتیجه‌ها
const flova::WriteResult result = FLOVA_REPORT(sensor, value);
if (!result.accepted()) {
logReportFailure(result.status, result.reason);
}نتیجهٔ Accepted یعنی SDK عملیات را در مرز خودش پذیرفته است. در MQTT همچنان
run() را اجرا کنید و Latest Value یا History را در Console
بررسی کنید. در نوشتن Hardware، Accepted باید به معنی پذیرفته شدن وضعیت واقعی
توسط Handler محصول باشد.
انتخاب Header
| Include | کاربرد |
|---|---|
<FlovaSDK.h> | برنامه‌های سادهٔ Arduino و نقطهٔ ورود عمومی. |
<FlovaEsp32.h> | دسترسی مستقیم به Facade مربوط به ESP32. |
<FlovaEsp8266.h> | دسترسی مستقیم به Facade مربوط به ESP8266. |
<FlovaUniversalEsp32.h> | ترکیب مستقیم Universal برای ESP32. |
<FlovaUniversalEsp8266.h> | ترکیب مستقیم Universal برای ESP8266. |
<FlovaLinux.h> | برنامه‌های Device در Linux. |
<FlovaDevice.h> | اتصال‌های قابل انتقال به هسته. |
تا وقتی به Constructor یا متد مخصوص Target نیاز ندارید، Header عمومی
<FlovaSDK.h> را ترجیح دهید.