ONX2424G013 ONX2424G013 用户指南 User Manual
Home Assistant 快速接入 Home Assistant setup

ONX2424G013
旋钮屏用户指南 Smart Knob Display

完成 Wi-Fi 配网并连接 Home Assistant，用旋钮控制开关、插座、灯光、窗帘和自动化。

Connect the display to Wi-Fi and Home Assistant, then control switches, sockets, lights, covers, and automations from the knob.

开始配置 Start setup 故障排查 Troubleshooting
ONX2424G013

先认识一下这块旋钮屏 Meet the smart knob display

ONX2424G013 是一款基于 ESP32-S3 的 1.28 英寸旋钮屏。出厂演示固件通过 ESPHome 接入 Home Assistant，并读取已授权的实体进行显示和控制。

ONX2424G013 is a 1.28-inch smart knob display powered by ESP32-S3. Its factory demo firmware connects to Home Assistant through ESPHome and displays or controls authorized entities.

Wi-Fi 仅支持 2.4 GHz 2.4 GHz only
PlatformHome Assistant + ESPHome
Controls 旋转、短按、长按 Rotate, press, press and hold
Entities 开关、插座、灯光、窗帘、自动化等 Switches, sockets, lights, covers, automations, and more

开始前准备 Before you begin

  • 可用的 2.4 GHz Wi-Fi 名称和密码。
  • 已安装并可访问的 Home Assistant。
  • 旋钮屏和 Home Assistant 位于同一局域网。
  • 可创建长期访问令牌的 Home Assistant 账号。
  • 一部可连接 Wi-Fi 的手机或电脑。
  • A working 2.4 GHz Wi-Fi network and its password.
  • An installed and accessible Home Assistant instance.
  • The display and Home Assistant on the same local network.
  • A Home Assistant account that can create a long-lived access token.
  • A phone or computer with Wi-Fi.
设备配网 Connect Wi-Fi
约 2 分钟 About 2 minutes
添加到 HA Add to HA
约 3 分钟 About 3 minutes
配置实体 Choose entities
约 5 分钟 About 5 minutes

1. 配置设备 Wi-Fi 1. Connect the display to Wi-Fi

ONX2424G013 Connect to Device AP screen
设备实机界面On-device screen

看到此页面即可开始配网Start setup when this screen appears

绿色区域显示设备热点名称。手机连接该热点后，打开屏幕提示的地址。The green field shows the device hotspot name. Join it from your phone, then open the address shown on the display.

1

首次上电后，等待屏幕显示设备热点名称，格式为 After first power-on, wait for the device hotspot name to appear. Its format is ONX2424G013-{MAC}.

2

打开手机 Wi-Fi 设置，连接该热点。热点默认没有密码。手机提示“无互联网连接”时仍保持连接。 Open Wi-Fi settings and join the hotspot. It has no password by default. Stay connected if your phone reports “No internet”.

3

配置页通常会自动弹出；如果没有，在浏览器打开 The setup page normally opens automatically. Otherwise, visit http://192.168.4.1.

4

选择 2.4 GHz Wi-Fi，输入密码并保存。设备成功联网后会退出 AP 页面。 Select your 2.4 GHz Wi-Fi, enter its password, and save. The AP screen closes after a successful connection.

① Wi-Fi连接设备热点Join device hotspotONX2424G013-XXXX
→
② 192.168.4.1选择 2.4 GHz 网络Choose 2.4 GHz Wi-FiWi-Fi password
→
③ Connected✓ 配网成功Connected
设备热点连接和 Wi-Fi 配置流程。 Device hotspot and Wi-Fi setup flow.
成功标志 Success 屏幕不再显示 AP 配网页，进入设备主界面或“添加到 Home Assistant”页面。 The AP setup screen disappears and the main screen or “Add Device to Home Assistant” screen appears.
配置页打不开？ Can’t open the setup page? 确认手机仍连接设备热点；临时关闭移动数据、VPN 和“自动切换到可用网络”，然后重新打开地址。 Confirm that you are still connected to the device hotspot. Temporarily disable mobile data, VPN, and automatic network switching, then try the address again.

2. 添加到 Home Assistant 2. Add the display to Home Assistant

ONX2424G013 Add Device to Home Assistant screen
设备实机界面On-device screen

Wi-Fi 连接成功后的提示页Screen shown after Wi-Fi connects

看到此页面表示设备已联网。按照屏幕提示进入 Home Assistant 的“设备与服务”页面添加 ESPHome 设备。This screen confirms that the display is online. Open Devices & services in Home Assistant and add the ESPHome device.

优先使用自动发现 Use automatic discovery

设置 → 设备与服务 Settings → Devices & services

Home Assistant 通常会发现同一局域网中的 ONX2424G013。在发现卡片中选择“添加”，按提示确认设备名称和区域。

Home Assistant normally discovers the ONX2424G013 on the same network. Select “Add” on the discovered card, then confirm its name and area.

在“已发现”卡片中确认设备名称，然后点击“添加”。点击图片可放大。 Confirm the device name on the Discovered card, then select Add. Click the image to enlarge.

没有自动发现时 If discovery does not appear

设置 → 设备与服务 → 添加集成 → 搜索“ESPHome” Settings → Devices & services → Add integration → Search “ESPHome”

在 Host 字段输入旋钮屏 IP。短按旋钮进入 Settings → Wireless network，可查看 IP 地址。

Enter the display IP address in the Host field. Press the knob to open Settings → Wireless network and view the IP address.

1ONX2424G013 Settings entry screen进入 SettingsOpen Settings旋转至最右侧设置入口Rotate to the rightmost page
2ONX2424G013 Settings options screenWireless network旋转选择，短按进入Rotate to select, press to open
3ONX2424G013 Wi-Fi information screen找到设备 IPFind the device IP记录 IP，用于填写 ESPHome HostUse this IP as the ESPHome Host
自动发现失败时，在设备端查看 IP 地址。Find the device IP on the display when automatic discovery fails.
将设备端显示的 IP 填入 Host，端口保持默认的 6053，然后点击“提交”。点击图片可放大。Enter the IP displayed on the device in Host, keep the default port 6053, then select Submit. Click the image to enlarge.
成功标志 Success “设备与服务”中出现该旋钮屏对应的 ESPHome 设备。 The display appears as an ESPHome device under Devices & services.

3. 允许设备执行 HA 动作 3. Allow the display to perform HA actions

设置 → 设备与服务 → ESPHome → 旋钮屏条目 Settings → Devices & services → ESPHome → Display entry

点击旋钮屏设备条目右侧的设置按钮，勾选“允许设备执行 Home Assistant 动作”，然后点击“提交”。不同 HA 版本的文字可能略有差异。

Select the settings button for the display, enable “Allow the device to perform Home Assistant actions”, then select Submit. Wording can vary between HA versions.

依次执行图中的 1–3：打开设置、勾选权限、点击“提交”。点击图片可放大。Follow steps 1–3: open settings, enable the permission, and select Submit. Click the image to enlarge.

4. 创建并配置长期访问令牌 4. Create and configure a long-lived access token

安全警告 Security warning Token 是长期访问凭证。不要把它发给他人，也不要在截图中展示。设备丢失、转让或 Token 泄露时，请立即在 HA 中撤销。 A token is a long-term credential. Never share it or expose it in screenshots. Revoke it immediately if the display is lost, transferred, or the token is exposed.
1

打开 HA 左下角账号头像/名称 → Security → Long-lived access tokens → Create token。 Open your HA profile → Security → Long-lived access tokens → Create token.

2

为 Token 使用容易识别的名称，例如“ONX2424G013 客厅”。创建后立即复制；该值只显示一次。 Use a recognizable name such as “ONX2424G013 Living Room”. Copy the token immediately; it is shown only once.

ProfileSecurity
→
Long-lived access tokensCreate token
→
ONX2424G013eyJhbGciOi…仅显示一次，请立即复制Shown once. Copy now.
长期访问令牌创建入口。 Creating a long-lived access token.
3

回到旋钮屏的 ESPHome 配置页，将 Token 粘贴到对应配置项，并按 Enter 保存。 Return to the display’s ESPHome configuration, paste the token into the matching field, and press Enter to save.

在 Configuration 区域找到“7. HA token”，粘贴 Token 后按 Enter 保存。点击图片可放大。Under Configuration, locate “7. HA token”, paste the token, and press Enter to save. Click the image to enlarge.
4

查看 HA Token Status。刷新页面后，Token 不应继续以明文显示。 Check HA Token Status. After refreshing the page, the token should no longer be shown in plain text.

在 Diagnostic 区域查看 HA Token Status；显示“Configured”表示 Token 已配置。点击图片可放大。Check HA Token Status under Diagnostic. “Configured” confirms that a token has been saved. Click the image to enlarge.
成功标志 Success HA Token Status 显示有效或已连接状态。 HA Token Status reports a valid or connected state.

5. 刷新、选择并保存实体 5. Refresh, select, and save entities

1

点击 Refresh Entity List 对应的 Press 按钮，等待设备从 HA 拉取实体。 Select Press for Refresh Entity List and wait while the display downloads entities from HA.

2

设备可能断开并重新连接，这是正常现象。重新上线后检查实体列表。 The display may disconnect and reconnect. This is normal. Check the entity list after it comes back online.

3

在 Weather 和 Device1–Device10 下拉列表中选择需要展示和控制的实体。 Choose the entities to display and control from the Weather and Device1–Device10 lists.

4

完成选择后，点击 Save Entity Config 对应的 Press 按钮保存配置，并等待设备重连完成。 After making your selections, select Press for Save Entity Config and wait for the display to reconnect.

5

重连完成后，在 Device1 Config–Device10 Config 中为每个已选实体设置匹配的显示和控制类型。Device 编号应与前面选择实体时的编号一一对应。 After reconnection, set the matching display and control type for each selected entity under Device1 Config–Device10 Config. Each Device number must match the entity selected in the corresponding slot.

点击 Refresh Entity List 右侧的 Press，拉取 Home Assistant 实体。点击图片可放大。Select Press beside Refresh Entity List to download Home Assistant entities. Click the image to enlarge.
依次选择 Weather、Device1–Device10，最后点击 Save Entity Config 右侧的 Press 保存。点击图片可放大。Choose Weather and Device1–Device10, then select Press beside Save Entity Config. Click the image to enlarge.
保存并重连后，为 Device1 Config–Device10 Config 选择与对应实体匹配的显示和控制类型。点击图片可放大。After saving and reconnecting, choose the matching display and control type under Device1 Config–Device10 Config. Click the image to enlarge.
成功标志 Success 旋钮屏实体列表显示已选实体及其当前状态；控制操作会同步到 HA，选择自动化后可触发执行。 The selected entities and their states appear on the display. Control actions are reflected in HA, and selected automations can be triggered.

使用旋钮控制实体 Control entities with the knob

通用操作 General controls

  • 列表页旋转：选择实体 Rotate on list: select entity
  • 列表页短按：进入详情 Press on list: open details
  • 详情页短按：执行主要动作 Press in details: primary action
  • 详情页长按：返回列表 Hold in details: return to list

开关 / 插座 Switch / socket

短按切换开启和关闭，列表页同步显示当前状态。 Press to toggle on or off. The list reflects the current state.

灯光 Lights

短按开关；旋转调节；长按并旋转可切换亮度、色温或彩光模式。具体功能取决于灯具能力和配置。 Press to toggle; rotate to adjust; hold and rotate to switch between brightness, color temperature, or color modes. Available controls depend on the light and configuration.

窗帘 Covers

短按移动至预设位置，移动时短按停止；旋转可控制全开/全关；长按并旋转可选择百分比位置。 Press to move to the preset position; press while moving to stop. Rotate for fully open/closed; hold and rotate to select a percentage.

自动化 Automations

在实体列表中选择自动化，短按进入详情页，再短按旋钮即可触发执行该自动化。自动化的具体动作和条件由 Home Assistant 中的配置决定。 Select an automation from the entity list, press to open its details, then press again to trigger it. Its actions and conditions are defined in Home Assistant.

开关Switch

短按旋钮在关闭和开启间切换Press to toggle between off and on

OFF
ON

插座Plug

短按旋钮在关闭和开启间切换Press to toggle between off and on

OFF
ON

开关灯On/off light

短按旋钮切换灯光开关Press the knob to toggle the light

OFF
ON

调光灯Dimming light

短按开关灯光，旋转调节亮度Press to toggle; rotate to adjust brightness

OFF
ON · 50%

设备设置、待机与休眠 Device settings, standby, and sleep

在实体列表继续顺时针旋转可进入最右侧的 Settings 页面。长按旋钮退出 Settings。

From the entity list, continue rotating clockwise to the rightmost Settings page. Press and hold the knob to exit Settings.

Wireless network 查看 Wi-Fi 和 IP 地址 View Wi-Fi and IP address
Display 调节屏幕亮度 Adjust brightness
KNOB 调节旋钮灵敏度 Adjust knob sensitivity
Wake 旋转或按下旋钮唤醒 Rotate or press to wake

Wi-Fi 与 IP 信息Wi-Fi and IP information

进入 Wireless network，查看当前 Wi-Fi 名称和设备 IPOpen Wireless network to view the connected Wi-Fi and device IP

Wireless network

屏幕亮度Screen brightness

进入 Display → Brightness，旋转旋钮调节亮度Open Display → Brightness, then rotate the knob to adjust

亮度设置Brightness

旋钮灵敏度Knob sensitivity

进入 KNOB，旋转选择 Low、Medium 或 HighOpen KNOB, then rotate to select Low, Medium, or High

灵敏度设置Sensitivity

HA 端待机 / 休眠设置 Standby / sleep settings in HA

在旋钮屏 ESPHome 配置页设置无操作后的待机和休眠时间。启用休眠模式后，还可限制其生效时间段。休眠状态下屏幕熄灭，旋转或按下旋钮即可唤醒。

Configure standby and sleep delays on the display’s ESPHome page. When sleep is enabled, you can also limit it to a time range. The screen turns off in sleep and wakes when the knob is rotated or pressed.

设置待机超时、启用休眠模式、休眠生效时段和休眠超时。时间值以页面实际配置为准。点击图片可放大。Configure standby timeout, sleep mode, the active sleep period, and sleep timeout. Use values appropriate for your setup. Click the image to enlarge.

HA 端 GPIO 与屏幕背光控制GPIO and screen-light controls in HA

旋钮屏 ESPHome 设备页的 Controls 区域可控制 HMI IO10、IO11、IO17、IO18，并可通过 Screen Light 开关打开或关闭屏幕背光。

Under Controls on the display’s ESPHome page, you can control HMI IO10, IO11, IO17, and IO18, and use Screen Light to turn the display backlight on or off.

HMI IO 控制项和 Screen Light 背光开关。点击图片可放大。HMI IO controls and the Screen Light backlight switch. Click the image to enlarge.

重新配置 Wi-Fi Reset and reconnect Wi-Fi

需要更换路由器或 Wi-Fi 时，长按旋钮超过 10 秒。设备会清除已保存的 Wi-Fi 信息并重新进入 AP 配网状态，然后从本指南第 1 步重新配置。

To change the router or Wi-Fi network, press and hold the knob for more than 10 seconds. The display clears saved Wi-Fi details and returns to AP setup. Repeat step 1 of this guide.

执行前确认 Before resetting 该操作会清除设备上的 Wi-Fi 凭据。请提前确认新网络为 2.4 GHz，并准备好密码。 This clears the saved Wi-Fi credentials. Make sure the new network is 2.4 GHz and that you have its password.

故障排查 Troubleshooting

找不到设备热点 The device hotspot is missing

等待设备完成启动；靠近设备刷新 Wi-Fi 列表。如果设备曾配网，长按旋钮超过 10 秒清除旧网络后重试。

Wait for startup to finish and refresh the Wi-Fi list near the display. If it was previously configured, hold the knob for more than 10 seconds to clear the old network.

连接热点后打不开 192.168.4.1 192.168.4.1 does not open

保持连接设备热点，关闭移动数据、VPN 和自动网络切换，再手动输入完整地址 http://192.168.4.1。

Stay connected to the device hotspot. Disable mobile data, VPN, and automatic network switching, then enter http://192.168.4.1 manually.

HA 没有自动发现设备 HA does not discover the display

确认设备和 HA 在同一局域网；从屏端 Settings → Wireless network 查看 IP，然后手动添加 ESPHome 集成。

Confirm that HA and the display are on the same network. Find the IP under Settings → Wireless network, then add the ESPHome integration manually.

Token 状态无效 Token status is invalid

重新复制有效 Token，粘贴后按 Enter；确认没有多余空格。仍失败时撤销旧 Token 并新建一个。

Paste a valid token and press Enter. Remove leading or trailing spaces. If it still fails, revoke the old token and create a new one.

刷新后实体列表为空 Entity list is empty after refresh

先确认 Token 有效且已允许 ESPHome 执行 HA 动作，再次执行 Refresh Entity List，等待设备重连后保存。

Confirm that the token is valid and ESPHome actions are allowed. Run Refresh Entity List again, wait for reconnection, then save.

修改配置后设备暂时离线 The display goes offline after a change

刷新或保存实体时设备可能主动重连。等待约 1 分钟后刷新 HA 页面；持续离线时检查 Wi-Fi 信号和设备 IP。

The display may reconnect after refreshing or saving entities. Wait about one minute and refresh HA. If it remains offline, check Wi-Fi signal and the device IP.

安全、资源与技术支持 Security, resources, and support

  • 不要公开 Wi-Fi 密码、Token、家庭地址和其他敏感信息。
  • 设备丢失或转让前，撤销 Token 并清除设备 Wi-Fi。
  • Home Assistant 更新后界面文字可能变化，请按功能名称寻找对应入口。
  • Do not expose Wi-Fi passwords, tokens, home addresses, or other sensitive data.
  • Before transferring or disposing of the display, revoke its token and clear Wi-Fi.
  • HA labels can change after updates; look for the equivalent function if wording differs.
关于出厂演示例程 About the factory demo 设备预装例程仅用于功能演示，帮助用户在收到设备后初步体验 ONX2424G013 与 Home Assistant 联动控制的用途。该例程是示例项目，不属于我公司承诺长期维护的正式软件产品，不保证持续适配 Home Assistant、ESPHome 或其他第三方平台的后续版本，也不建议未经评估直接用于生产环境或关键控制场景。例程代码已在 GitHub 开源，用户可根据自身需求参考、修改和二次开发。 The preinstalled firmware is provided solely as a functional demonstration, allowing users to experience how ONX2424G013 can interact with Home Assistant after receiving the device. It is a sample project rather than an officially supported, long-term software product. Continued compatibility with future versions of Home Assistant, ESPHome, or other third-party platforms is not guaranteed, and it should not be used in production or critical-control scenarios without independent evaluation. The example source code is available on GitHub for reference, modification, and further development.

官方资源 Official resources

ONX2424G013 设备 Wiki ONX2424G013 device wiki
查看设备说明、规格及相关资料 → Device information, specifications, and resources → ONX2424G013 设备资料 GitHub ONX2424G013 resources on GitHub
OpenNextion/OpenNextion-SKU-ONX2424G013 → 出厂演示例程 GitHub Factory demo on GitHub
OpenNextion/OpenNextion-Example-ESPHome_KNOB_Control →
文档适用范围 Document scope 本指南适用于 ONX2424G013 出厂演示固件 V1.0。更多产品资料、代码和后续说明请以上述官方资源为准。 This guide applies to ONX2424G013 factory demo firmware V1.0. Refer to the official resources above for product information, source code, and subsequent updates.
Model: ONX2424G013 Firmware: V1.0 文档版本：1.0 Manual version: 1.0 Updated: 2026-08-04