راهنمای دستگاه زنگ درب برای اندروید

نوع دستگاه Doorbell با استفاده از دو ویژگی پیاده‌سازی می‌شود: PushAvStreamTransport که انتقال جریان صوتی و تصویری را با استفاده از پروتکل‌های مبتنی بر فشار مدیریت می‌کند، و WebRtcLiveView که امکان کنترل پخش زنده و talkback را فراهم می‌کند.

قبل از استفاده از هرگونه ویژگی یا تلاش برای به‌روزرسانی ویژگی‌ها، همیشه پشتیبانی از ویژگی‌ها و دستورات را برای دستگاه بررسی کنید. به بخش کنترل دستگاه‌ها مراجعه کنید.Android برای اطلاعات بیشتر.

دریافت اطلاعات اولیه در مورد یک دستگاه

ویژگی BasicInformation شامل اطلاعاتی مانند نام فروشنده، شناسه فروشنده، شناسه محصول، نام محصول (شامل اطلاعات مدل)، نسخه نرم‌افزار و شماره سریال دستگاه است:

// Get device basic information. All general information traits are on the RootNodeDevice type.
    device.type(RootNodeDevice).first().standardTraits.basicInformation?.let { basicInformation ->
        println("vendorName ${basicInformation.vendorName}")
        println("vendorId ${basicInformation.vendorId}")
        println("productId ${basicInformation.productId}")
        println("productName ${basicInformation.productName}")
        println("softwareVersion ${basicInformation.softwareVersion}")
        println("serialNumber ${basicInformation.serialNumber}")
    }

بررسی اتصال دستگاه

اتصال برای یک دستگاه در واقع در سطح نوع دستگاه بررسی می‌شود زیرا برخی از دستگاه‌ها از چندین نوع دستگاه پشتیبانی می‌کنند. حالت برگردانده شده ترکیبی از حالت‌های اتصال برای همه ویژگی‌های آن دستگاه است.

val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState

در صورت عدم اتصال به اینترنت، ممکن است در مورد انواع دستگاه‌های مختلف، حالت PARTIALLY_ONLINE مشاهده شود. ویژگی‌های استاندارد Matter ممکن است به دلیل مسیریابی محلی هنوز آنلاین باشند، اما ویژگی‌های مبتنی بر ابر آفلاین خواهند بود.

شروع پخش زنده

برای شروع پخش زنده، رشته‌ی پروتکل شرح جلسه (SDP) را به متد startLiveView() از ویژگی WebRtcLiveView ارسال کنید، که یک WebRtcLiveViewTrait.StartLiveViewCommand.Response حاوی سه مقدار را برمی‌گرداند:

• SDP برای جلسه.
• مدت زمان جلسه بر حسب ثانیه.
• شناسه جلسه، که ممکن است برای تمدید یا خاتمه جلسه استفاده شود.

suspend fun getWebRtcLiveViewTrait(cameraDevice: HomeDevice) {
 return cameraDevice.type(GoogleDoorbellDevice).trait(WebRtcLiveView).first {
    it?.metadata?.sourceConnectivity?.connectivityState == ConnectivityState.ONLINE
  }

}

// Start the live view
suspend fun startCameraStream(trait: WebRtcLiveView, offerSdp: String) {
  val response = trait.startLiveView(offerSdp)
  // Response contains three fields (see below)
  return response
}
  ...

// This is used to manage the WebRTC connection
val peerConnection: RTCPeerConnection = ...

   ...

val startResponse = startCameraStream(sdp)
val answerSdp = startResponse?.answerSdp
val sessionDuration = startResponse?.liveSessionDurationSeconds
val mediaSessionId = startResponse?.mediaSessionId

peerConnection.setRemoteDescription(SessionDescription.Type.ANSWER,
                                    answerSdp)

پخش زنده را تمدید کنید

پخش زنده دارای مدت زمان از پیش تعیین شده‌ای است که پس از آن منقضی می‌شود. برای افزایش مدت زمان یک پخش زنده فعال، با استفاده از متد WebRtcLiveView.extendLiveView() درخواست تمدید ارسال کنید:

// Assuming camera stream has just been started
suspend fun scheduleExtension(trait: WebRtcLiveView, mediaSessionId: String, liveSessionDurationSeconds: UShort ) {
  delay(liveSessionDurationSeconds - BUFFER_SECONDS * 1000)
  val response = trait.extendLiveView(mediaSessionId)
  // returns how long the session will be live for
  return response.liveSessionDurationSeconds
}

شروع و توقف تاک‌بک

برای شروع talkback، متد startTalkback() از ویژگی WebRtcLiveView را فراخوانی کنید. برای توقف آن، stopTalkback() استفاده کنید.

// Make sure camera stream is on
suspend fun setTalkback(isOn: Boolean, trait: WebRtcLiveView, mediaSessionId: String) {
  if(isOn) {
    trait.startTalkback(mediaSessionId)
  } else {
    trait.stopTalkback(mediaSessionId)
  }
}

فعال و غیرفعال کردن قابلیت ضبط

برای فعال کردن قابلیت ضبط دوربین، TransportStatusEnum.Active را به متد setTransportStatus() از ویژگی PushAvStreamTransport ارسال کنید. برای غیرفعال کردن قابلیت ضبط، TransportStatusEnum.Inactive را ارسال کنید. در مثال زیر، این فراخوانی‌ها را در یک فراخوانی واحد قرار می‌دهیم که از یک Boolean برای فعال یا غیرفعال کردن قابلیت ضبط استفاده می‌کند:

// Start or stop recording for all connections.
suspend fun setCameraRecording(trait: PushAvStreamTransport, isOn: Boolean) {
  if(isOn) {
    trait.setTransportStatus(TransportStatusEnum.Active)
  } else {
    trait.setTransportStatus(TransportStatusEnum.Inactive)
  }
}

فعال یا غیرفعال کردن قابلیت ضبط دوربین، همانند روشن یا خاموش کردن فیلم‌برداری دوربین است. وقتی فیلم‌برداری دوربین فعال است، در حال ضبط است (برای رویدادها و کلیپ‌های مرتبط).

وقتی قابلیت ضبط غیرفعال است (فیلمبرداری دوربین خاموش است):

• دوربین همچنان می‌تواند بر اساس connectivityState نوع دستگاه، آنلاین نشان داده شود.
• دسترسی به پخش زنده امکان‌پذیر نیست و دوربین نیز هیچ رویداد ابری را تشخیص نمی‌دهد.

بررسی کنید که آیا قابلیت ضبط فعال است یا خیر

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

// Get the on/off state
suspend fun onOffState(pushAvStreamTransport: PushAvStreamTransport) {
  return pushAvStreamTransport
    .currentConnections?.any { it.transportStatus == TransportStatusEnum.Active } ?: false
}

// Check if the camera's recording capability is enabled
fun PushAvStreamTransport.recordModeActive(): Boolean {
  return currentConnections?.any { it.transportStatus == TransportStatusEnum.Active } ?: false
}

راه دیگر برای بررسی، استفاده از تابع findTransport() به همراه یک گزاره است:

// Fetch the current connections
suspend fun queryRecordModeState(trait: PushAvStreamTransport) {
  return trait.findTransport().let {
      it.transportConfigurations.any { it.transportStatus == TransportStatusEnum.Active
    }
}

تنظیمات باتری

تنظیمات مختلف باتری را می‌توان از طریق APIهای Home کنترل کرد.

تنظیم اولویت استفاده از باتری

تنظیم تعادل انرژی به شما امکان می‌دهد تا بین عمر باتری و عملکرد دستگاه تعادل برقرار کنید. می‌توانید پروفایل‌های باتری مختلفی مانند «توسعه‌یافته»، «متعادل» و «عملکرد» ایجاد کنید و بین آنها جابجا شوید.

این ویژگی با به‌روزرسانی ویژگی currentEnergyBalance از ویژگی EnergyPreference پیاده‌سازی می‌شود. این ویژگی یک اندیس عدد صحیح می‌پذیرد که مربوط به یک پروفایل خاص تعریف شده در لیست energyBalances دستگاه است (برای مثال، 0 برای EXTENDED ، 1 برای BALANCED و 2 برای PERFORMANCE ).

مقدار null برای currentEnergyBalance نشان می‌دهد که دستگاه از یک پروفایل سفارشی استفاده می‌کند. این حالت فقط خواندنی است.

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

// Example energyBalances list
energy_balances: [
  {
    step: 0,
    label: "EXTENDED"
  },
  {
    step: 50,
    label: "BALANCED"
  },
  {
    step: 100,
    label: "PERFORMANCE"
  }
]

// The index parameter must be within the UByte range (0-255).
suspend fun setEnergyBalance(trait: EnergyPreference, index: Int) {
  trait.update { setCurrentEnergyBalance(index.toUByte()) }
}

// Setting the battery usage to more recording ie performance
setEnergyBalance(energyPreference, 2)

فعال کردن ذخیره خودکار باتری

برای پیکربندی این ویژگی، ویژگی currentLowPowerModeSensitivity از ویژگی EnergyPreference را به‌روزرسانی کنید. این ویژگی از یک شاخص برای انتخاب سطح حساسیت استفاده می‌کند، که در آن 0 معمولاً نشان دهنده Disabled و 1 نشان دهنده Enabled یا Automatic ) است.

suspend fun setAutomaticBatterySaver(enable: Boolean, trait: EnergyPreference) {
  // 0 is Disabled, 1 is Enabled
  val value = if (enable) 1.toUByte() else 0.toUByte()
  trait.update { setCurrentLowPowerModeSensitivity(value) }
}

دریافت وضعیت شارژ باتری

برای دریافت وضعیت شارژ فعلی دستگاه (در حال شارژ، کاملاً شارژ شده یا در حال شارژ نیست)، از ویژگی batChargeState از ویژگی PowerSource استفاده کنید.

// Get the battery charging state
val batteryChargeState = powerSource.batChargeState

when (batteryChargeState) {
    PowerSourceTrait.BatChargeStateEnum.IsCharging -> "Charging"
    PowerSourceTrait.BatChargeStateEnum.IsAtFullCharge -> "Full"
    PowerSourceTrait.BatChargeStateEnum.IsNotCharging -> "Not Charging"
    else -> "Unknown"
}

دریافت میزان باتری

برای دریافت سطح فعلی باتری، از ویژگی batChargeLevel از ویژگی PowerSource استفاده کنید. این سطح یا OK ، Warning (کم) یا Critical است.

// Get the battery charge level
val batteryLevel = powerSourceTrait.batChargeLevel

when (batteryLevel) {
    PowerSourceTrait.BatChargeLevelEnum.OK -> "OK"
    PowerSourceTrait.BatChargeLevelEnum.Warning -> "Warning"
    PowerSourceTrait.BatChargeLevelEnum.Critical -> "Critical"
    else -> "Unknown"
}

منبع تغذیه را دریافت کنید

برای تعیین منبع تغذیه‌ای که دستگاه از آن استفاده می‌کند، از ویژگی‌های BatPresent و wiredPresent از ویژگی PowerSource استفاده کنید.

  val trait: PowerSource
  val isWired = trait.wiredPresent
  val hasBattery = trait.batPresent

تنظیمات صوتی

تنظیمات مختلف صوتی را می‌توان از طریق APIهای Home کنترل کرد.

میکروفون را روشن یا خاموش کنید

برای روشن یا خاموش کردن میکروفون دستگاه، ویژگی microphoneMuted از ویژگی CameraAvStreamManagement را با استفاده از تابع داخلی setMicrophoneMuted کاتلین به‌روزرسانی کنید:

// Turn the device's microphone on or off
suspend fun turnOffMicrophone(disableMicrophone: Boolean, trait: CameraAvStreamManagement) {
  trait.update { setMicrophoneMuted(disableMicrophone) }
}

ضبط صدا را روشن یا خاموش کنید

برای فعال یا غیرفعال کردن ضبط صدا برای دستگاه، ویژگی recordingMicrophoneMuted از ویژگی CameraAvStreamManagement را با استفاده از تابع داخلی setRecordingMicrophoneMuted کاتلین به‌روزرسانی کنید:

// Turn audio recording on or off for the device
suspend fun turnOffAudioRecording(disableAudioRecording: Boolean, trait: CameraAvStreamManagement) {
  trait.update { setRecordingMicrophoneMuted(disableAudioRecording) }
}

تنظیم صدای بلندگو

برای تنظیم میزان صدای بلندگو برای دستگاه، ویژگی speakerVolumeLevel از ویژگی CameraAvStreamManagement را با استفاده از تابع داخلی setSpeakerVolumeLevel کاتلین به‌روزرسانی کنید:

// Adjust the camera speaker volume
suspend fun adjustSpeakerVolume(volume: Int, trait: CameraAvStreamManagement) {
  trait.update { setSpeakerVolumeLevel(volume.toUbyte()) }
}

تنظیمات دیگر

تنظیمات مختلف دیگری را می‌توان از طریق APIهای Home کنترل کرد.

فعال یا غیرفعال کردن دید در شب

برای فعال یا غیرفعال کردن دید در شب برای دوربین، از TriStateAutoEnum برای به‌روزرسانی ویژگی nightVision از ویژگی CameraAvStreamManagement با استفاده از تابع داخلی setNightVision کاتلین استفاده کنید:

// Turn night vision on
cameraAvStreamManagement.update {
  setNightVision(CameraAvStreamManagementTrait.TriStateAutoEnum.On)
}

// Turn night vision off
CameraAvStreamManagement.update {
  setNightVision(CameraAvStreamManagementTrait.TriStateAutoEnum.Off)
}

تغییر روشنایی LED وضعیت

برای تغییر روشنایی LED وضعیت، ThreeLevelAutoEnum برای به‌روزرسانی ویژگی statusLightBrightness از ویژگی CameraAvStreamManagement با استفاده از تابع داخلی setStatusLightBrightness کاتلین استفاده کنید:

// Set the LED brightness to high
cameraAvStreamManagement.update {
  setStatusLightBrightness(CameraAvStreamManagementTrait.ThreeLevelAutoEnum.High)
}

// Set the LED brightness to low
cameraAvStreamManagement.update {
  setStatusLightBrightness(CameraAvStreamManagementTrait.ThreeLevelAutoEnum.Low)
}

تغییر زاویه دید دوربین

نمای دوربین همان ویژگی بزرگنمایی و برش است که در مقاله پشتیبانی از ویدیوی دوربین Nest با بزرگنمایی و بهبود، توضیح داده شده است.

نمای دید (viewport) در یک ViewportStruct تعریف شده است که شامل چهار مقدار است که به عنوان مختصات نمای دید استفاده می‌شوند. این مختصات به صورت زیر تعریف می‌شوند:

(x1,y1) -- (x2,y1)
   |          |
(x1,y2) -- (x2,y2)

تعیین مقادیر ViewportStruct به رابط کاربری برنامه و پیاده‌سازی دوربین بستگی دارد. در سطح بسیار ابتدایی، برای تنظیم نمای ویدیوی دوربین، ویژگی viewport از ویژگی CameraAvStreamManagement را با ViewportStruct به‌روزرسانی کنید، و از تابع داخلی setViewport کاتلین استفاده کنید:

cameraAvStreamManagement
  .update { setViewport(
    CameraAvStreamManagementTrait.ViewportStruct(
      x1 = horizontalRange.rangeStart.roundToInt().toUShort(),
      x2 = horizontalRange.rangeEnd.roundToInt().toUShort(),
      y1 = verticalRange.rangeStart.roundToInt().toUShort(),
      y2 = verticalRange.rangeEnd.roundToInt().toUShort(),
    )
) }

حساسیت بیدار شدن دستگاه را تنظیم کنید

حساسیت بیدار شدن دستگاه برای صرفه‌جویی در مصرف باتری استفاده می‌شود، به این صورت که محدوده‌ای که دستگاه می‌تواند فعالیت را حس کند کاهش می‌یابد و زمان بیدار شدن پس از تشخیص آن فعالیت افزایش می‌یابد.

در APIهای Home، این مورد را می‌توان با استفاده از ویژگی motionSensitivity از triggerOptions در transportOptions دستگاه تنظیم کرد. این گزینه‌ها در ویژگی PushAvStreamTransport برای هر دستگاه تعریف شده‌اند.

حساسیت بیدارباش فقط می‌تواند روی مقادیر زیر تنظیم شود:

• ۱ = کم
• ۵ = متوسط
• ۱۰ = زیاد

فرآیند به‌روزرسانی به این صورت است که پیکربندی انتقال برای جریان‌های ضبط فعال با استفاده از دستور findTransport پیدا می‌شود، سپس پیکربندی با مقدار حساسیت جدید با استفاده از دستور modifyPushTransport اصلاح می‌شود:

// Create a struct with the new wake-up sensitivity
val toUpdate =  TransportOptionsStruct(
  triggerOptions =
    TransportTriggerOptionsStruct(
      motionSensitivity =
        OptionalValue.present(wakeUpSensitivity.toUByte())
    )
  )

// Get the configurations for active connections
val connections  = pushAvStreamTransport.findTransport().transportConfigurations
  // Update all recording streams with the new transport options.
  for (connection in connections) {
    if (connection.transportOptions.getOrNull()?.streamUsage == StreamUsageEnum.Recording) {
      trait.modifyPushTransport(
        connectionId = connection.connectionId,
        transportOptions = toUpdate,
      )
    }
  }

حداکثر طول رویداد را تنظیم کنید

حداکثر طول رویداد، مدت زمانی است که دوربین کلیپی از یک رویداد ضبط می‌کند. از طریق APIهای Home، این مدت زمان را می‌توان برای هر دستگاه، با همان طول زمانی که از طریق GHA و در فواصل ثانیه‌ای تنظیم می‌شود، تنظیم کرد:

• ۱۰ ثانیه
• ۱۵ ثانیه
• ۳۰ ثانیه
• ۶۰ ثانیه (۱ دقیقه)
• ۱۲۰ ثانیه (۲ دقیقه)
• ۱۸۰ ثانیه (۳ دقیقه)

در APIهای Home، این مورد را می‌توان با استفاده از ویژگی motionTimeControl از triggerOptions در transportOptions دستگاه تنظیم کرد. این گزینه‌ها در ویژگی PushAvStreamTransport برای هر دستگاه تعریف شده‌اند.

فرآیند به‌روزرسانی به این صورت است که پیکربندی انتقال برای جریان‌های ضبط فعال با استفاده از دستور findTransport پیدا می‌شود، سپس پیکربندی با مقدار طول رویداد جدید با استفاده از دستور modifyPushTransport اصلاح می‌شود:

// Create a struct with the new max event length
// where maxDuration is the length in seconds
val toUpdate =  TransportOptionsStruct(
  triggerOptions =
    TransportTriggerOptionsStruct(
      motionTimeControl =
        OptionalValue.present(
          TransportMotionTriggerTimeControlStruct(maxDuration = it.toUInt())
        )
    )
  )

// Get the configurations for active connections
val connections  = pushAvStreamTransport.findTransport().transportConfigurations
  // Update all recording streams with the new transport options.
  for (connection in connections) {
    if (connection.transportOptions.getOrNull()?.streamUsage == StreamUsageEnum.Recording) {
      trait.modifyPushTransport(
        connectionId = connection.connectionId,
        transportOptions = toUpdate,
      )
    }
  }

تنظیمات زنگ

تنظیمات مختلف زنگ در را می‌توان از طریق APIهای خانه کنترل کرد.

صدای زنگ را تغییر دهید

برای تغییر صدای زنگ در، ابتدا لیست صداهای زنگی که روی دستگاه نصب شده‌اند را با استفاده از ویژگی installedChimeSounds از ویژگی Chime دریافت کنید:

// Get a list of chimes and identify the currently selected one
private val doorbellChimeTraitFlow: Flow =
    device.traitFromType(Chime, GoogleDoorbellDevice)
val chimeSounds = doorbellChimeTraitFlow.first().installedChimeSounds ?: emptyList()

سپس، با استفاده از تابع داخلی setSelectedChime در کاتلین، ویژگی selectedChime از Chime trait را به‌روزرسانی کنید:

// Set the chime using the chimeId from the installed list
chimeSounds.firstOrNull { it.name == name }?.let { setSelectedChime(it.chimeId) }

از زنگ خارجی استفاده کنید

زنگ در را می‌توان طوری تنظیم کرد که از یک زنگ خارجی، مانند زنگ مکانیکی نصب شده در داخل خانه، استفاده کند. این تنظیم باید هنگام نصب زنگ در انجام شود تا از آسیب احتمالی به زنگ خارجی جلوگیری شود.

برای نشان دادن نوع زنگ خارجی نصب شده، ExternalChimeType برای به‌روزرسانی ویژگی externalChime از Chime trait با استفاده از تابع داخلی setExternalChime کاتلین استفاده کنید:

// Indicate the external chime is mechanical
chime.update {
  setExternalChime(ChimeTrait.ExternalChimeType.Mechanical)
}

مدت زمان زنگ خارجی را تغییر دهید

مدت زمان زنگ زدن یک زنگ خارجی (بر حسب ثانیه) را می‌توان از طریق APIهای Home پیکربندی کرد. اگر زنگ خارجی از مدت زمان زنگ پشتیبانی می‌کند، کاربر می‌تواند آن را پیکربندی کند.

مقدار تعیین‌شده در اینجا به مشخصات خود زنگ خارجی و مدت زمان پیشنهادی زنگ آن بستگی دارد.

برای تغییر مدت زمان زنگ خارجی، ویژگی externalChimeDurationSeconds از Chime trait را با استفاده از تابع داخلی setExternalChimeDurationSeconds در کاتلین به‌روزرسانی کنید:

// Change the external chime duration
chime.update {
  setExternalChimeDurationSeconds(newDuration.toUShort())
}

فعال کردن تم زنگوله

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

برای دیدن اینکه کدام تم‌های chime برای یک کاربر در دسترس هستند، یک فیلتر timebox ایجاد کنید و از آن برای فیلتر کردن نتایج دستور getAvailableThemes() از ویژگی ChimeThemes استفاده کنید. این دستور لیستی از تم‌های موجود، از جمله نام تم‌ها را برمی‌گرداند.

مثال زیر نحوه فیلتر کردن لیست را نشان می‌دهد. یک قالب در صورتی فعال در نظر گرفته می‌شود که زمان فعلی در محدوده زمان شروع و پایان آن (به ترتیب مقادیر startTimeSeconds و endTimeSeconds ) باشد. اگر زمان شروع تنظیم نشده باشد، از ابتدای زمان فعال در نظر گرفته می‌شود. اگر زمان پایان تنظیم نشده باشد، به طور نامحدود فعال خواهد بود. اگر هر دو وجود نداشته باشند، قالب همیشه فعال است.

// Get themes from the ChimeThemes trait
fun List<ChimeThemesTrait.ThemeStruct>.filterTimeboxedThemes():
    List<ChimeThemesTrait.ThemeStruct> {
  val now = timeSource.instant().epochSecond.toULong()
  return filter { chimeStruct: ChimeThemesTrait.ThemeStruct ->
    val startTime: ULong = chimeStruct.startTimeSeconds.getOrNull() ?: 0UL
    val endTime: ULong = chimeStruct.endTimeSeconds.getOrNull() ?: MAX_VALUE
    startTime <= now && now <= endTime
  }
}

val availableThemes =
  doorbellChimeThemesTraitFlow
    .first()
    .getAvailableThemes()
    .themes
    .filterTimeboxedThemes()

وقتی نام تم مورد نظر خود، مانند Christmas ، را پیدا کردید، می‌توانید آن را با استفاده از تابع setSelectedTimeboxedThemeName() در ویژگی ChimeThemes انتخاب کنید:

// Select a theme using the ChimeThemes trait
val themeToSelect = "Christmas"
if (themeToSelect in availableThemeNames) {
  doorbellChimeThemesTraitFlow.first().setSelectedTimeboxedThemeName(themeToSelect)
}