دور و ایتا

دور

در Nest API، مفهوم «خانه» یا «دور» تأثیر قدرتمندی بر رفتارهای صرفه‌جویی در انرژی و ویژگی‌های راحتی Nest دارد.

خانه و دور چگونه کار می کند

Nest از سیگنال‌های مختلفی برای تشخیص حضور انسان در خانه استفاده می‌کند. اگر Nest برای مدت طولانی عدم حضور را تشخیص دهد، خانه را به‌طور خودکار روی «خارج» تنظیم می‌کند. وقتی حضور انسان را تشخیص داد، ساختار را به حالت Home برمی‌گرداند.

واکنش به تغییرات در وضعیت خانه/خارج از خانه طیف وسیعی از فرصت‌ها را برای محصولات شما باز می‌کند. به عنوان مثال، محصولات شما می توانند:

  • برای صرفه جویی در مصرف انرژی، وقتی خانه به خانه رفت، چراغ ها را خاموش کنید
  • در صورت باز بودن درب گاراژ زمانی که خانه خارج است، اعلان ارسال کنید
  • وقتی خانه به صفحه اصلی تغییر می کند، موسیقی پخش کنید

نحوه کار ETA

در برخی موارد، کاربران یک برنامه شخص ثالث دارند که از GPS برای ارائه داده های تخمینی زمان رسیدن (ETA) به Nest API استفاده می کند. در موارد دیگر، کاربر ممکن است از یک برنامه برای وارد کردن دستی ETA خود استفاده کند. یا شاید ETA بر اساس برنامه منظم کاربر محاسبه می شود.

برنامه‌های ETA که با Nest Thermostat یکپارچه شده‌اند باعث می‌شوند که ترموستات قبل از ورود کاربر شروع به گرم کردن یا خنک کردن خانه کند.

وقتی ادغام ETA/ترموستات در حساب کاربر وجود دارد، داده های ETA برای سایر توسعه دهندگان Works with Nest در دسترس است تا در ادغام های Works with Nest خود از آن استفاده کنند.

پس از ورود ETA به سرویس Nest، ادغام Works with Nest دیگری می تواند از آن به عنوان سیگنالی برای آماده کردن خانه برای ورود کاربر استفاده کند.

  1. ETA توسط یک توسعه دهنده Nest با استفاده از تماس PUT eta و API فقط نوشتنی نوشته شده است.
  2. Nest Thermostat از این داده ها استفاده می کند.
  3. اگر توسعه‌دهندگان دیگر نیز بخواهند از آن استفاده کنند، می‌توانند از تماس API فقط GET eta_begin استفاده کنند .
داده های ETA

نکته مهمی که باید در نظر داشت این است که داده های ETA باید توسط شخص ثالث وارد شود. Nest در حال حاضر داده های ETA را ارائه نمی دهد. اگر داده‌های ETA نوشته نشده باشند، Nest API مقدار پیش‌فرض «1970-01-01T00:00:00.000Z» را برمی‌گرداند.

برای مثال فرض کنید که شما یک فروشنده روشنایی هستید. می توانید داده های ETA ارائه شده توسط ادغام ETA/ترموستات را دریافت کرده و از آن به عنوان سیگنال برای روشن کردن چراغ ها استفاده کنید.

به این ترتیب، نه تنها دما راحت است، بلکه هنگام ورود کاربر به خانه، چراغ ها نیز روشن می شوند.

واکنش به تغییرات در وضعیت ETA طیف گسترده ای از فرصت ها را برای محصولات شما باز می کند. به عنوان مثال، محصولات شما می توانند:

  • وقتی کاربر به خانه نزدیک می شود، تلویزیون را روشن کنید
  • زمانی که کاربر تقریباً در خانه است، درب گاراژ را باز کنید
  • وقتی کاربر به خانه برمی گردد، از قبل موسیقی پخش شده باشد

مجوزهای دور

سطوح مجوز دسترسی زیر برای مقادیر داده مربوط به Away موجود است:



دسترسی داشته باشید

دور بخوانید
دور خواندن/نوشتن

ETA خوانده شود

خواندن/نوشتن ETA

هشدار دود + CO خوانده شد
ترموستات خوانده شد
خواندن/نوشتن ترموستات
away آره آره آره
eta_begin (فقط خواندنی) آره آره
شی eta (فقط نوشتن) آره

برای اطلاعات بیشتر، به نمای کلی مجوزها مراجعه کنید.

ویژگی های دور

خانه و دور

مقدار داده away می‌تواند به شما بگوید که آیا Nest فکر می‌کند ساختار اشغال شده است یا خیر. مقادیر ممکن عبارتند از:

مقدار شرح
home یک نفر در ساختار وجود دارد. این حالت را می توان تنظیم کرد:
• توسط Nest اگر از داده‌های حسگر حرکت اطمینان بالایی دارد
• توسط کاربر از طریق برنامه Nest ، ترموستات Nest یا محصول شما
• الگوریتمی از طریق ETA
away هیچ کس در ساختار وجود ندارد. کاربر صراحتاً از طریق برنامه Nest ، Nest Thermostat یا محصول شما، ساختار را روی دور تنظیم کرده است.
unknown اگر هیچ دستگاهی با ساختار مرتبط نباشد، وضعیت دور unknown .

Nest API امکان تنظیم مستقیم خانه و خارج از خانه و همچنین گوش دادن به تغییرات این حالت ها را فراهم می کند. با این حال، هنگام تنظیم خانه و خارج از خانه، باید همانطور که برنامه Nest این کار را انجام می دهد انجام شود: در نتیجه درخواست صریح کاربر. تلاش برای تنظیم الگوریتمی این حالت خطر ایجاد یک تجربه کاربر گیج کننده را دارد و توسط خط مشی های طراحی Nest ممنوع است.

توجه داشته باشید که کاربران همیشه این امکان را دارند که حالت خانه/خارج از خانه را به صورت دستی تنظیم کنند.

درباره نحوه تنظیم وضعیت خانه و خارج از خانه توسط کاربران بیشتر بیاموزید.

ETA

دور

ETA یک شی با فیلدهایی است که می توان روی یک ساختار تنظیم کرد. از آن برای اطلاع دادن به Nest استفاده می شود که انتظار می رود کاربر در یک زمان خاص به خانه بازگردد. هنگام تنظیم ETA، یک محصول یک trip_id منحصربه‌فرد ایجاد می‌کند و یک پنجره ورود مورد انتظار را ارائه می‌کند که با مقادیر زیر مشخص می‌شود:

  • estimated_arrival_window_begin
  • estimated_arrival_window_end

از آنجایی که شرایط اطراف سفرها می‌تواند به دلیل ترافیک، برنامه‌های کاربر تغییر یافته و سایر رویدادها تغییر کند، محصولات باید به‌طور دوره‌ای ETA را با پیشرفت سفر به‌روزرسانی کنند و جریانی از زمان‌های تخمینی رسیدن به Nest را ارائه کنند (5 دقیقه فاصله زمانی ایده‌آل است).

هرچه اطلاعات بیشتری دریافت کنیم، می توانیم به قابلیت اطمینان ورودی های ETA اطمینان بیشتری داشته باشیم، که باعث می شود هنگام اقدام برای آماده سازی خانه، اطمینان بیشتری داشته باشیم.

ETA مستقل از کشور اصلی است. اگر زمان رسیدن یک ETA با یک ETA دیگر در تضاد باشد، زودترین زمان ورود اولویت دارد.

یک تماس نوشتن ETA برقرار کنید

منطق ETA به وجود ترموستات در ساختار بستگی دارد. اگر هیچ ترموستاتی در ساختار وجود نداشته باشد، تماس‌های برقرار شده با شی ETA با پیام خطای «دستگاه‌های جفت‌شده وجود ندارد» با شکست مواجه می‌شوند. این خطا حتی اگر انواع دیگری از دستگاه‌ها در ساختار وجود داشته باشند (به عنوان مثال، Nest Cam یا Nest Protect) رخ می‌دهد.

مقادیر داده ها

یک تماس ETA به مقادیر داده زیر نیاز دارد:

نام تایپ کنید شرح
trip_id رشته شناسه منحصر به فرد سفر ETA
estimated_arrival_window_begin رشته مهر زمان
باید بزرگتر از NOW در قالب ISO 8601 باشد
estimated_arrival_window_end رشته مهر زمان
در قالب ISO 8601 باید بیشتر از estimated_arrival_window_begin زده_arrival_window_begin باشد

به دلیل احتمال قطع اتصال در ارتباطات GPS، ما یک جریان نمونه را پیشنهاد می کنیم، در حالت ایده آل هر 5 دقیقه یک بار.

هر تماس ETA باید شامل یک رشته trip_id منحصر به فرد باشد که در تماس اولیه تعریف می کنید. سایر پارامترها می توانند با تماس های متوالی به همان trip_id کنند.

یک تماس ETA در صورت موفقیت یک کد وضعیت HTTP 200 OK را برمی گرداند.

مثال ها

حلقه
curl --location-trusted -X PUT -d \
  '{"trip_id":"sample-trip-id","estimated_arrival_window_begin":"2014-10-31T22:42:00.000Z","estimated_arrival_window_end":"2014-10-31T23:59:59.000Z"}' \
  "http://developer-api.nest.com/structures/5af48890-b516-11e3-9eff-123139166438/eta.json?auth=c.VG6bfzyOxAltaih6P4v..."

لغو ETA

برای لغو یک eta، estimated_arrival_window_begin = 0 را ارسال کنید. بررسی کنید که در این تماس یک عدد صحیح (0) ارسال می کنید، نه رشته ("0")، در غیر این صورت تماس ناموفق خواهد بود.

پیغام خطا

برای اطلاعات در مورد اینکه خطاهای فراخوانی API به چه معنا هستند و نحوه رسیدگی به آنها، به پیام های خطا مراجعه کنید.