传感器#

除了提供位置服务外，Companion 应用还向 Home Assistant 添加了多个额外的传感器。如果您不想要 device_tracker 实体但仍想让传感器更新，只需在实体注册表中禁用该实体即可停止位置更新并保持传感器更新。

Companion 应用提供的传感器取决于您使用的应用，请参阅下面的列表。

#多服务器支持

如果多个服务器连接到 Companion 应用，您可以配置是否针对每个服务器发送传感器数据。目前传感器设置对于所有连接的服务器都是通用的。

在 设置 > Companion App 中，打开服务器设置并在隐私下更改传感器发送设置。可用选项：

• 全部 发送所有已启用的传感器。
• 无 不发送任何传感器。

在 设置 > Companion App 中，前往管理传感器并选择您要管理的传感器。点击屏幕顶部的展开/折叠图标可更改特定服务器的设置。

#iOS 和 macOS 传感器

#传感器何时更新

在 iOS 上，传感器在有限的情况下更新：当您的位置发生变化时、应用在前台运行时定期更新、下拉刷新网页视图时、在后台以 iOS 确定的速率更新时，以及执行"更新传感器"或通过"发送位置"快捷方式或推送通知时。当 2022.6 或更高版本中启用并可用 本地推送 时，也将执行定期更新。

在 macOS 上，传感器在上述相同情况下以及某些传感器发生变化时立即更新。

# 从 2025.5 起

并非所有 传感器都默认启用。如果您在 Home Assistant 中看不到您的传感器，请前往 Companion App 设置 > 传感器，并手动启用它。

#传感器列表

专属传感器

专属传感器

可以通过模板访问 蜂窝网络技术 等属性：

{{ states.sensor.connection_type.attributes['Cellular Technology'] }}

#Android 传感器

下面的每个 传感器都可以通过导航到 设置 > Companion App > 管理传感器来启用。默认情况下，大多数传感器都是禁用的，除了 battery_level、battery_state、charger_type 以及在引导过程中获得权限的传感器。启用后，传感器将开始向您的 Home Assistant 服务器发送数据，如果您稍后选择禁用它，传感器将停止更新。启用传感器时，如果需要，应用将请求权限。如果您没有在下面看到列出的传感器，则您的设备不支持它。下面的某些传感器为其各自的需求提供自定义设置，请阅读每个传感器的说明以了解其提供的功能。这些设置可以在启用传感器的同一位置找到。

#传感器如何更新

所有传感器在 15 分钟的定期间隔期间更新，如果满足某些其他条件，它们也会更新。阅读下面每个传感器的说明以了解预期更新的频率。在 15 分钟更新间隔期间，会临时创建一个低优先级前台通知，以防止 Android 系统停止工作器。除非用户安装了拦截通知并决定发出声音的第三方应用，否则此通知不会发出声音。如果您使用的是 Android 8.0+，您可以自由地最小化和/或关闭 SensorWorker 的通知渠道。

您可以通过导航到 设置 > Companion App > 传感器更新频率来更改传感器更新的频率。您可以选择正常、充电时快速或始终快速。正常是上一段中提到的默认设置。设置为始终快速时，更新将每分钟进行一次。设置为充电时快速时，只有在设备充电时才会每分钟更新一次，否则将使用默认间隔。更改此选项后，您需要重启应用。

#传感器列表

#活动传感器

sensor.active 提供设备当前是否正在被使用，基于几个不同的输入，这些输入作为属性提供以供参考。

此传感器有一个设置来决定被视为"空闲"的持续时间。

#活动传感器

sensor.activity 提供 iOS 计算的当前运动活动以及计算的置信度。iOS 已知并由 sensor.activity 提供的活动有：

• Stationary（静止）
• Walking（步行）
• Running（跑步）
• Automotive（乘车）
• Cycling（骑行）

如果 iOS 无法从运动数据计算活动，将给出 Unknown（未知）。

可能返回多个活动，例如 Cycling 和 Stationary（如果您正在骑行但在红灯处停车），传感器的状态只是 iOS 返回的第一个（不一定是最可能的）。完整的计算活动列表由 types 属性给出。有关不同场景如何产生多个活动的描述，请参阅 nshipster 上 @Mattt 的这篇文章。

confidence 属性对应 iOS 对当前活动报告准确程度的判断。可能的值有：

• Low（低）
• Medium（中）
• High（高）

此传感器仅在 Google Play 商店中找到的 Android 应用完整版本上可用，最小版本不可用。对于 Android，用户将有一组不同的状态：

• in_vehicle（在车辆中）
• on_bicycle（在自行车上）
• on_foot（步行）
• running（跑步）
• still（静止）
• tilting（倾斜）
• walking（步行）
• unknown（未知）

状态的属性将反映来自 Activity Recognition API 的 confidence 评级。此传感器需要 Activity Recognition 权限。

#Android Auto

#Android OS 传感器

#应用数据传感器

#应用重要性传感器

可能的状态有：

• cached（缓存）
• cant_save_state（无法保存状态）
• foreground（前台）
• foreground_service（前台服务）
• gone（已消失）
• not_running（未运行）
• perceptible（可感知）
• service（服务）
• top_sleeping（顶部睡眠）
• visible（可见）

#应用内存传感器

#应用使用传感器

app_standby_bucket 传感器的可能状态（请参阅上面链接的 API 以获取其定义）：

• active（活动）
• frequent（频繁）
• rare（稀有）
• restricted（受限）
• working_set（工作集）
• never（从不）

#音频传感器

这些传感器使用 AudioManager API 来检索它们的状态。查看下表以了解有关每个传感器的更多信息，包括它们更新的频率。

#音量级别

给定音量流（volume_level_*）的当前设备音量级别。这些传感器将在正常间隔期间更新，或在检测到变化时立即更新。

可能的音量流有：

• accessibility（无障碍）
• alarm（闹钟）
• call（通话）
• dtmf
• music（音乐）
• notification（通知）
• ring（铃声）
• system（系统）

BETA 属性指示最小和最大值。

#电池传感器

电池状态传感器（sensor.battery_state）提供有关设备电池当前状态的信息。当设备充电 100% 时，三个可能的值是 Charging（充电中）、Not Charging（未充电）或 Full（已充满）。电池电量传感器（sensor.battery_level）报告设备从 0–100% 的当前电池电量。电量级别反映在传感器图标中。此外还有一个"低电量模式"属性，根据您的 iOS 设备是否处于低电量模式，报告 true 或 false。

下面列出的电池传感器描述了电池在几个不同数据点的状态。传感器的图标反映充电状态和正在使用的充电类型。当设备连接或断开充电器时，battery_state、charger_type 和 is_charging 传感器将更新。当任何其他传感器更新时，以及当设备报告低电量或从低电量警报恢复时，battery_health、battery_level、battery_power 和 battery_temperature 传感器都会更新。所有这些传感器都使用 BatteryManager。

#蓝牙传感器

蓝牙连接状态将是已连接蓝牙设备的总数。一旦设备的蓝牙状态发生变化，传感器就会更新。此传感器使用 Android 的 Bluetooth 包。

还会有一个 bluetooth_state 的二进制传感器，表示设备上的蓝牙是否已开启。每当蓝牙状态发生变化时，此传感器都会更新。

设置可用于更改 UUID、Major 和 Minor 掩码。这些可用于更改整体标识符，以及允许分组，例如家庭手机设备可以有特定的 Major 值，可以在 roomassistant 等应用中列入白名单。这些设置经过验证：UUID 应为标准格式，Major 和 Minor 需要在 0 和 65535 之间。

还有设置可以更改：

• 发射功率（超低、低、中和高之间）
• 广播模式（低功耗（1Hz）、平衡（3Hz）和低延迟（10Hz）之间）
• 1 米处的测量功率（必须为负数）
• 是否仅在家用 WiFi 网络 SSID 上启用发射

发射设置开关将启动或停止 BLE 发射。此设置以及上述大多数设置可以通过通知命令更改。

信标监视器显示扫描 BLE iBeacon。传感器的状态显示应用是否正在监视。范围内所有信标及其距离都列在属性中。当有新的距离测量可用时，此传感器将更新。

设置可用于更改扫描周期和间隔，这对于节省电池寿命很有用。设置过滤迭代和过滤 RSSI 乘数可以调整以获得更稳定的测量结果。所有这些设置都会影响传感器的响应性。还有一个 UUID 过滤器，用于将报告的信标限制为匹配（或不匹配）UUID 列表的信标。

监视设置开关将启动或停止扫描 - 此设置也可以通过通知命令调整。

当应用主动扫描信标时，将显示通知以使后台扫描更可靠。如果您使用的是 Android 8.0+，您可以自由地最小化和/或关闭 Beacon Monitor Scanning 的通知渠道。

#汽车传感器

下面列出的传感器描述了汽车在几个不同数据点的状态。目前这仅适用于 Android Auto。根据您的手机和/或汽车软件，这些传感器可能无法提供数据。如果您看到 unknown 状态，请检查 status 属性以了解没有数据的原因。

#蜂窝运营商传感器

蜂窝运营商传感器显示有关用户蜂窝服务提供商的信息，例如其唯一标识符以及是否允许在其网络上进行 VoIP 呼叫。sensor.sim_1 对应于安装的物理 SIM 卡，sensor.sim_2 对应于 eSIM（仅在启用 eSIM 时显示）。

Android 用户将在网络发生变化时看到这些传感器更新，这使用 SubscriptionManager。这些传感器需要 Read Phone State 权限。

属性	描述
Carrier Name	用户蜂窝服务提供商的名称。
Current Radio Technology	仅 。
ISO Country Code	用户蜂窝服务提供商的 ISO 国家代码。
Mobile Country Code	用户蜂窝服务提供商的移动国家代码（MCC）。
Mobile Network Code	用户蜂窝服务提供商的移动网络代码（MNC）。
Carrier ID
Allows VoIP	指示运营商是否允许在其网络上进行 VoIP 呼叫。
Is Opportunistic	临时订阅连接到功能和/或覆盖范围受限的网络。
Data Roaming	设备是否启用了数据漫游。

#连接类型传感器

以下连接类型是 Companion 应用已知的：

• Wi-Fi
• Cellular（蜂窝网络）
• No Connection（无连接）

可以在传感器的 Cellular Technology 属性中找到数据连接的更具体描述（仅在蜂窝网络上时出现）。此属性的可能值有：

• 4G
• 3G
• 2G
• Cellular（蜂窝网络）
• No Connection（无连接）

如果无法识别连接类型，将返回 Unknown 或 Unknown Technology。

对于 Android，有多种不同类型的连接传感器可用，当检测到网络状态变化时它们将更新：

bssid 传感器提供设置让您重命名当前的 MAC 地址，以避免在自动化和前端中使用模板和秘密。如果您有多个接入点并想要一种简单的方法来区分它们，这通常很有用。这些设置默认关闭。这些传感器需要 Background Location 或 Fine Location 权限，具体取决于您运行的 Android 版本。

#当前时区传感器

#当前版本传感器

#显示传感器

#屏幕亮度传感器

此传感器将报告屏幕亮度值作为其状态。如果屏幕当前正在使用自动亮度模式，也存在一个属性。此传感器使用 Settings.System API。

#屏幕关闭超时传感器

此传感器将报告屏幕关闭超时值作为其状态，单位为毫秒。此传感器使用 Settings.System API。

#屏幕方向传感器

此传感器报告屏幕的方向，当屏幕开启且方向变化时，此传感器将立即更新。此传感器使用 Orientation API。

#屏幕旋转传感器

此传感器报告相对于设备"自然"方向的旋转度数。此传感器仅针对以下旋转角度更新：0、90、180 和 270。此传感器使用 Rotation API。

#免打扰传感器

仅限 6+
此传感器将表示设备上免打扰（DND）的状态。DND 的功能取决于 Android 版本。可能的状态值有 off、priority_only、total_silence、alarms_only、unavailable 或 unknown。并非所有状态都会在所有 Android 版本上显示，例如 Pixel 4 XL 只会显示 off 或 priority_only。如果您从未使用过 DND，您可能会看到 unavailable，直到您更改设备上的设置。一旦 DND 状态发生变化，此传感器就会更新。此传感器使用 NotificationManager API。

#动态颜色传感器

仅在支持 Material 3 动态颜色的设备上可用。

此传感器的状态将是当前设备主题中使用的强调色的十六进制颜色值。动态颜色可以来自壁纸或由用户选择。还有一个 rgb_color 属性，如果您想在自动化中为 light.turn_on 服务调用使用此颜色。此传感器使用 Dynamic Colors API。

#打盹传感器

状态将反映设备是否处于打盹模式。状态将在状态变化时立即更新，数据由 PowerManager 提供。有一个属性 ignoring_battery_optimizations，如果 Companion 应用正在忽略电池优化，将显示 true 或 false。如果您好奇状态实际上如何变化，可以按照这些概述的步骤进行测试。

#最前端应用传感器

当最前端的应用发生变化时，此传感器会立即更新。

#地理编码位置传感器

地理编码位置传感器提供用户当前位置坐标的用户友好描述，通常包含地点名称、地址和其他相关信息。此传感器报告许多详细属性，允许您创建有用的模板传感器。

地理编码由 iOS 的 MapKit 和 Core Location 服务直接处理。在 Android 中，地理编码由内部 Geocoder 处理。

属性	描述
Location	地标的纬度和经度坐标。
Name	地标的名称。仅 和
Country	与地标关联的国家名称。
ISOCountryCode	缩写的国家名称。
TimeZone	与地标关联的时区。仅
AdministrativeArea	与地标关联的州或省。
SubAdministrativeArea	地标的额外行政区域信息。
PostalCode	与地标关联的邮政编码。
Locality	与地标关联的城市。
SubLocality	地标的额外城市级信息。
Thoroughfare	与地标关联的街道地址。
SubThoroughfare	地标的额外街道级信息。
AreasOfInterest	与地标相关的感兴趣区域。仅
Ocean	与地标关联的海洋名称。仅
InlandWater	与地标关联的内陆水域名称。仅
phone	地标的电话号码（如果有）。
premises	地标的前提（如果有）。
url	地标的 URL（如果有）。

Android 用户将有一个传感器设置用于最小所需精度，默认为 200 米。如果用户发现报告不准确或报告不足，可以根据自己的需求调整此设置。此传感器需要 Background Location 或 Fine Location 权限，具体取决于您运行的 Android 版本。所有属性都将小写，所有空格都替换为下划线。传感器只会在准确和最新时发送更新。在 full 版本中，如果启用了位置追踪，传感器也会随位置变化更新。有一个设置可以让传感器与位置更新保持同步。默认情况下，此设置是关闭的。

和 用户将有一个传感器设置，用于是否使用活动区域的名称（如果存在）而不是地理编码状态，默认不使用。

#Health Connect 传感器

9+ 带 Play Store 版本 • （Android 14+ 所有版本 BETA）

这些传感器将反映存储在您设备 Health Connect 中由其他应用提供的健康和健身数据。除非另有说明，否则仅使用最近 30 天的数据。

#高精度模式

此传感器的状态将反映设备当前是否启用了高精度模式。一旦高精度模式状态发生变化，此传感器就会更新，直到首次启用高精度模式，传感器才会出现。

#高精度更新间隔

此传感器的状态将反映高精度模式的设备更新间隔（秒）。一旦值发生变化（手动或通过通知命令），此传感器就会更新。

#交互传感器

此传感器的状态将反映设备是否处于交互状态。这通常是屏幕开启和关闭时，但可能因设备而异。一旦检测到状态变化，此传感器就会更新，数据由 PowerManager 提供。

使用 History Stats 集成，可以监控每日屏幕时间 type: time 以及当天屏幕开启的次数 type: count。

#Keyguard 传感器

这些传感器将反映来自 Keyguard Manager 的各种状态。您将能够确定设备是否主动锁定、是否设置了密码，甚至设备是否需要密码才能解锁。这些传感器将在定期传感器间隔期间更新。

#上次重启传感器

此传感器的状态将是设备上次重启的日期和时间，采用 UTC 格式。传感器将在正常传感器更新间隔期间更新。如果无法确定时间戳，状态将为 unavailable。此传感器使用 SystemClock 和当前 System 时间来计算时间戳。此传感器提供一个死区设置，默认为 1 分钟，以解决某些运营商上看到的时间计算问题。

#上次更新触发器传感器

对于 Android，此传感器的状态将反映最近发送更新的意图。此外，传感器提供设置允许用户从广播意图的其他 Android 应用接收应用事件。用户可以根据需要注册任意数量的意图，一旦收到意图，就会向 Home Assistant 发送事件。保存意图后，请务必重启应用以注册意图。

如果您注意到您在设置中注册的意图不再被应用触发，那么您需要添加意图期望的类别。您可以通过编辑意图的设置并在意图后添加 , 后跟类别来添加类别。如果需要多个类别，则需要添加每个类别后跟 ,，直到没有更多类别要添加。例如，如果您的意图需要 2 个类别，格式将是：intent,category1,category2。保存意图和类别后，确保重启应用。

此传感器准确显示导致从设备到 Home Assistant 的位置和传感器数据最后更新的原因。

#上次使用的应用传感器

6+

传感器的状态将始终是上次使用的应用的包名称，以确保它始终是唯一值。应用的标签将是传感器的一个属性（如果已知）。此传感器在正常传感器更新间隔期间更新，并使用 UsageStatsManager API。

#光线传感器

此传感器将反映设备检测到的当前照度级别。传感器在正常传感器更新间隔期间或与其他传感器更新一起更新，并使用 环境传感器。

#移动数据传感器

关于移动数据状态的几个不同传感器。这些传感器使用 Settings.Global 和 TelephonyManager 来获取移动数据状态。

#下一个闹钟传感器

此传感器的状态将是下一个闹钟的日期和时间，采用 UTC 格式。一旦计划了下一个闹钟，传感器就会更新。当没有下一个闹钟时，状态将为 unavailable。此传感器使用 AlarmManager 来获取下一个计划的闹钟，该闹钟可以由任何应用在任何时间设置。此传感器有设置，允许您通过选择要从中获取闹钟事件的包来创建允许列表，请记住 API 只能获取下一个计划的闹钟。此设置默认关闭。

#NFC 状态传感器

此传感器的状态将反映设备是否当前启用了 NFC 传感器。一旦检测到状态变化，此传感器就会更新。数据由 NfcAdapter 提供。

#通知传感器

注意：带有允许列表的传感器在允许的应用之一收到新通知之前，不会在 Home Assistant 中显示为新实体。

#最后一个通知

此传感器将反映设备上发布的最后一个通知。此传感器需要一个特殊权限，应用会将用户带到该权限以授予通知访问权限。此传感器的状态默认为通知的文本，如果不可用则为发布包名称。此传感器提供一个允许列表设置，让用户选择他们希望从哪些包获取通知数据，Home Assistant 发送的通知始终被忽略。您需要创建一个允许列表或启用"禁用允许列表要求"的设置。请记住，没有允许列表，此传感器有可能消耗大量电池。我们强烈建议创建允许列表而不是禁用此要求。这对于集成任何发送通知但不提供直接集成的应用（例如：外卖应用或 2FA 短信代码）非常有用。用户可以期待看到几个属性，尽管并非所有属性都包含数据。此传感器使用 NotificationListenerService API。有关每个属性的更多详细信息可以在 Notification Extras 中找到。

#最后删除的通知

此传感器与最后一个通知类似，不同之处在于当通知已从设备中删除（由用户或应用程序）时，它将更新。您可以为此传感器期待类似的属性，其中一些概述如下。此传感器需要与上面提到的相同的权限。此传感器也有一个允许列表，其功能类似于最后一个通知。

#活动通知计数

此传感器将反映设备上的活动通知总数。此计数将包括持久和/或静默的通知。有时它甚至可能包括传感器工作器通知。每当任何其他传感器有更新时，此传感器都会更新。此传感器需要与最后一个通知中提到的相同的权限。此传感器没有允许列表。

下面您可以找到某些通知可以提供的详细信息。除非您禁用相应的传感器设置，否则这些将作为属性提供。

#媒体会话传感器

此传感器需要通知权限才能启用并发送数据。状态将是主媒体会话的播放状态。如果没有活动的媒体会话，则状态将为 unavailable。属性将包括活动会话的总数以及按包名称分隔的所有活动会话的媒体数据。此传感器将在正常传感器更新间隔期间更新。为了充分利用此传感器，我们建议使用最后一个通知来挂钩您的媒体应用以发送更快的更新。此传感器使用 MediaController 和 MediaSessionManager API 来获取数据。

#计步器传感器

计步器传感器从设备内置的运动处理器提供步数数据。它们记录您的日常步行活动，并在午夜重置。这些传感器需要启用运动权限。

Android 用户将只有一个 sensor.steps 实体，它将表示自上次设备重启以来的总步数。获取每日步数的推荐方法是使用 cycle: daily 的 Utility Meter 集成。此传感器将在正常传感器更新间隔期间更新，并使用 运动传感器。此传感器需要 Activity Recognition 权限。

#电话传感器

#数据网络类型传感器

SIM 插槽为数据传输提供的无线电技术（网络类型）。数据由 TelephonyManager 提供。

#电话状态传感器

只有当用户在设备的应用信息屏幕中明确授予应用 Phone 权限时，此传感器才会显示。此传感器跟踪的唯一数据是以下状态：idle、ringing、offhook。每当检测到电话状态变化时，此传感器都会更新，并使用 TelephonyManager。此传感器需要 Read Phone State 权限。

#信号强度传感器

一个传感器，表示 SIM 插槽提供的蜂窝信号强度（dBm）。属性将存在信号质量以及任意强度单位。由于省电，此数据可能并不总是最新的。数据由 TelephonyManager 提供。

#省电传感器

此传感器将显示设备上省电模式的状态。根据设备的不同，这通常是一个用户可配置的选项，用于指示设备何时应进入特殊省电模式。一旦检测到状态变化，状态就会更新，传感器使用 PowerManager。

#压力传感器

此传感器将显示设备的当前压力读数。此传感器将在正常传感器更新间隔期间更新，并使用 环境传感器。

#接近传感器

此传感器将显示设备的当前接近读数。此传感器将在正常传感器更新间隔期间更新。并非所有设备都报告实际读数，因此这些设备将根据传感器的最大范围是否为 5 来显示 near 或 far。此传感器使用 位置传感器。

#公共 IP 传感器

此传感器使用 ipify API 来确定设备的公共 IP 地址。此传感器将在正常传感器更新间隔期间更新。

#存储传感器

此传感器显示设备存储的信息。报告的文件大小采用十进制。

对于 Android，由于两个操作系统的差异，行为略有不同。状态将与 iOS 相同，我们显示可用空间的百分比，属性不会相同。这些传感器将在正常传感器更新间隔期间更新，计算借助于 StatFs 完成。

sensor.internal_storage

sensor.external_storage

#流量统计传感器

这些传感器将显示设备传输和接收的总数据。有总传感器和移动传感器可供使用，统计数据在设备重启时重置。这些传感器使用 Traffic Stats API。

#工作配置文件传感器

如果设备的工作配置文件已启用，此传感器将为 on，否则为 off。此传感器使用 Device Policy Manager API。