Unfolded Circle Integration

Home Assistant integration for the Unfolded Circle Remote Two / Remote 3 and associated docks. A rich integration providing activity control, remote settings and diagnostics, firmware management, IR transmission & learning, wake features, dock management, wireless charging control and advanced automation hooks.

---

Table of Contents

• Key Features
• Supported Devices & Concepts
• Installation
• HACS (Recommended)
• Manual Installation
• Configuration
• Manual Setup
• Entities Overview
• Dock Support
• External Entity Management
• Mapped Button Remote Commands
• IR Remote Commands
• Infrared Platform
• Activity Update Actions
• IR Learning
• Options
• Zeroconf
• Wake on LAN
• Planned / Future Ideas
• Notes & Behavior
• Services & Actions Summary
• Troubleshooting & Support
• Localization
• About This Project
• License
• Support the Project

---

Key Features

• Automatic device & dock discovery (zeroconf)
• Guided configuration flow and options flow
• Flexible entity exposure: activities, groups, media players (global / per group / per activity)
• Firmware update control with progress reporting
• External Entity Management (select which HA entities are exposed back to the remote)
• IR send (codeset/custom) with dock & port targeting
• IR learning workflow that builds ready-to-use codesets
• Mapped button command dispatch (long press, repeats, delays, activity scoping)
• Activity maintenance services (e.g., prevent sleep toggling, standby inhibitors)
• Wake on LAN for Remote Two (Remote 3 when firmware supports it)
• Resource usage sensors (opt-in polling)
• Docks as sub-entries: IR, brightness, identity, reboot, firmware
• Button backlight Light entity (brightness + color control)
• Multi-language support (EN, Partial (FR, PT))

---

Supported Devices & Concepts

Component	Description
Remote Two / Remote 3	Primary handheld device defining activities, buttons, media surface.
Dock	IR emission, LED brightness, reboot, identity flash, firmware update.
Activity / Activity Group	Logical usage contexts exposed as switches/selects with optional media players.
Firmware	Update entity supports version awareness & install execution.
IR Dataset	Learned or manufacturer-based sets of IR commands.
IR Emitter	Infrared platform entity exposing dock ports, built-in remote IR, and third-party emitters to other HA integrations.
Button Backlight	Light entity allowing dynamic brightness and color adjustment of remote button illumination.
Wireless Charging	Toggle wireless charging on and off to control battery setpoint.

---

Installation

HACS (Recommended)

1. Install HACS if not already.
2. Home Assistant → HACS → Integrations.
3. Search “Unfolded Circle” → Install.
4. Restart Home Assistant.
5. Continue with Configuration.

Manual Installation

1. Clone or download this repository.
2. Copy custom_components/unfoldedcircle into your HA custom_components/ directory.
3. Restart HA.
4. Proceed to Configuration.

Manual installs won’t auto-notify updates—watch the repo if you go this route.

---

Configuration

After restart (HACS or manual): 1. A discovery notification should appear. 2. Go to Settings → Devices & Services → Configure and click Configure on the newly discovered Unfolded Circle Device. 3. Enter PIN (from remote web configurator). - On the remote: profile icon (upper-right) → enable web configurator → PIN appears (refresh if needed). - PIN only needed initially; you can change it after pairing. 4. Assign an Area.

Manual Setup

If not discovered: 1. Settings → Devices & Services → Integrations → + Add Integration. 2. Search “Unfolded Circle”. 3. Supply PIN and Host (IP/hostname).

---

Entities Overview

Category	Examples / Notes
Sensors	Battery, Illuminance, Resource Usage (CPU/Mem/Storage)*, Config flags
Binary Sensor	Charging status
Update	Firmware reporting + install
Switch	Activities (configurable), configuration toggles
Select	Activity groups (optional)
Button	Restart remote
Remote	Mapped button & IR dispatch
Infrared	IR emitter entities for use by other integrations (e.g. LG, Samsung)
Media Player	Global and/or per group / per activity
Number	Numeric configuration, dock LEDs
Light	Button backlight (brightness + color control)
Dock Sub-Entities	Remote (IR), Buttons (Reboot, Identity), Update, Brightness controls

*Resource usage sensors disabled by default; enabling one enables selective polling.

Button Backlight Light Entity

A light entity exposes remote button backlight control: - Adjustable brightness - Adjustable color (depending on device capabilities) - Suitable for themes/ambience automations (e.g., dim during night mode)

Example automation:

automation:
  - alias: Dim remote backlight at night
    trigger:
      - platform: time
        at: "23:00:00"
    action:
      - service: light.turn_on
        target:
          entity_id: light.remote_two_button_backlight
        data:
          brightness_pct: 10
          rgb_color: [255, 80, 10]

---

Wireless Charging Switch

A switch entity enables and disables the wireless charger on your Remote 3.

Example Automation:

alias: Preserve Battery
description: "Toggle wireless charging functionality based on battery percentage"
triggers:
  - trigger: numeric_state
    entity_id:
      - sensor.remote_3_battery
    above: 80
    id: "OFF"
  - trigger: numeric_state
    entity_id:
      - sensor.remote_3_battery
    below: 60
    id: "ON"
conditions: []
actions:
  - if:
      - condition: trigger
        id:
          - "OFF"
    then:
      - action: switch.turn_off
        metadata: {}
        data: {}
        target:
          entity_id: switch.remote_3_wireless_charging
  - if:
      - condition: trigger
        id:
          - "OFF"
    then:
      - action: switch.turn_on
        metadata: {}
        data: {}
        target:
          entity_id: switch.remote_3_wireless_charging
mode: single

Dock Support

• Docks are Sub-entries
• One-time migration cleans legacy definitions & repairs.
• Removed reliance on dock passwords 🎉

Each dock exposes: - Remote (IR) - Buttons: Reboot, Identity flash - Numbers: LED Brightness - Update: Firmware visibility

---

External Entity Management

Select which HA entities are shared to the remote (Options flow).

Requirements: - Remote firmware ≥ 2.0.0 (≥ 2.6.9 recommended; Remote 3 currently beta but stable)

Demo video: Watch the demo

---

Mapped Button Remote Commands

Preferred service: unfoldedcircle.send_button_command Options: num_repeats, delay_secs, hold, activity

Supported buttons:

- BACK
- HOME
- VOICE
- VOLUME_UP
- VOLUME_DOWN
- GREEN
- DPAD_UP
- YELLOW
- DPAD_LEFT
- DPAD_MIDDLE
- DPAD_RIGHT
- RED
- DPAD_DOWN
- BLUE
- CHANNEL_UP
- CHANNEL_DOWN
- MUTE
- PREV
- PLAY
- PAUSE
- NEXT
- POWER

---

IR Remote Commands

The remote entity supports sending predefined or (HEX/PRONTO) IR commands using the unfoldedcircle.send_ir_command action.

device: will match the case-sensitive name of your remote defined in the web configurator on the remote page. This will be your custom name or the manufacturer name selected.

codeset (Optional) If you supplied a manufacturer name, you also need to supply the codeset name you are using.

command will match the case-senstitive name of the pre-defined (custom or codeset) or (Hex or Pronto) command defined for the remote.

num_repeats (Optional) The number of times to repeat sending the command.

dock_name (Optional) The name of the dock you would like to send the command from. If not supplied, all docks will emit the IR signal.

port (Optional) The location on the dock you want the IR signal to be emitted from. If not supplied, all ports are used.

Yaml of the above image:

action: unfoldedcircle.send_ir_command
data:
  device: Samsung
  codeset: Generic TV 1
  command: POWER_TOGGLE
  dock: Remote Dock
  port: Ext 1
target:
  entity_id: remote.remote_two_remote

TIP: Core remote.send_command only supports custom codes (platform limitation).

---

Infrared Platform

This integration exposes all active IR emitters as infrared platform entities, allowing other Home Assistant integrations (e.g. LG TV, Samsung, climate devices) to send device-specific IR commands through your Unfolded Circle hardware without needing to know which physical emitter to use.

How It Works

HA's infrared platform is an abstraction layer: - Emitter integrations (like this one) register hardware emitters as infrared.* entities. - Consumer integrations (like LG, Samsung) use the infrared helper to discover available emitters and send commands through them.

Emitter Types

Three types of IR emitters are registered:

1. Dock Ports

One infrared entity is created for each active port on each configured dock. This lets you target a specific physical output (e.g. Ext 1, Dock top, Default).

Entity Name	Description
infrared.<dock_name>_dock_bottom	Bottom IR port
infrared.<dock_name>_dock_top	Top IR port
infrared.<dock_name>_ext_1	External port 1
infrared.<dock_name>_default_all_outputs	All outputs simultaneously

Entities are registered under the dock's sub-device in the device registry.

2. Remote Built-in IR

If the remote's internal IR emitter is enabled (Settings → Development → Preview Features on the remote), a single infrared entity is created and attached to the main remote device.

Entity Name	Description
infrared.<remote_name>_internal_ir_emitter	Remote's built-in IR blaster

3. External / Third-party Emitters

Third-party IR blasters added to the remote via a driver integration (e.g. Broadlink RM Pro) are also registered. One entity is created per port. These are attached to the main remote device.

Entity Name	Description
infrared.<remote_name>_<emitter_name>_<port_name>	Named port on external emitter

Example: Using with a Consumer Integration

Once an emitter entity exists, any integration using the infrared helper can send commands to it:

# Example: sending an NEC IR command to a dock port via automation
action: infrared.send_command
target:
  entity_id: infrared.remote_two_dock_dock_bottom
data:
  command:
    type: nec
    address: 0x04
    command: 0x08
    modulation: 38000

Note: The infrared platform is a HA 2026.4+ feature. Ensure your Home Assistant installation is up to date.

---

Activity Update Actions

Service: unfoldedcircle.update_activity

service: unfoldedcircle.update_activity
target:
  entity_id: switch.remote_two_control_projector
data:
  prevent_sleep: true

Currently supports prevent_sleep (more may follow).

---

IR Learning

Service: unfoldedcircle.learn_ir_command

service: unfoldedcircle.learn_ir_command
target:
  entity_id: remote.remote_dock_remote
data:
  remote:
    name: Sony TV
    icon: uc:tv
    description: My Sony TV Remote
  dock: R3 Dock
  ir_dataset:
    name: Sony A95L
    command:
      - direction_up
      - direction_right
      - direction_down
      - direction_left
      - menu
      - back
      - home

Follow HA notifications for capture steps. Resulting dataset appears in remote web configurator.

Screenshots:

---

Options

Access