Skip to main content

Unfolded Circle Remote smart home integration, free and open source

Unfolded Circle Remote integration for Gladys Assistant

Unfolded Circle Remote Two and Remote 3: battery, activities and their buttons, on your network.

View on GitHubAll integrations

This integration brings an Unfolded Circle Remote Two or Remote 3 into Gladys, through the local API of the remote (the REST Core API documented by Unfolded Circle): no cloud, everything stays on your network.

Warning: never tested with a real device. This integration has never been tested with a real device: it was written from the pyUnfoldedCircleRemote library and tested with simulated answers only. Your feedback is welcome on the Gladys forum.

Unofficial, not affiliated with Unfolded Circle.

What the remote shows​

FeatureTypeValues
Batteryread onlycharge level, %
Chargingread only1 on its dock or cable, 0 otherwise
Reachableread only1 the remote answered the last reading, 0 otherwise
Power modetextNormal, Idle, Low power, Asleep
Current activitytextnames of the activities running, "—" when none
activity: runningread only1 the activity runs, 0 stopped (one per activity)
Start activitybuttonstarts the activity (activity.on)
Stop activitybuttonstops the activity (activity.off)

Start and stop are buttons, not a switch: an "everything off" of a voice assistant or a scene cannot trigger them. The state of each activity can trigger a scene.

The activities are the ones you created on the remote (50 at most). An activity added on the remote shows up in the Discovery tab at the next reading; a deleted activity keeps its features in Gladys (its history is not lost), but its buttons answer that it no longer exists.

Configuration​

  1. Address of the remote: its IP address or host name on your network (settings of the remote, Wi-Fi). Better give it a fixed address in your router. A port may follow (192.168.1.20:8080).
  2. API key: see below.
  3. Reading interval: 30 seconds to 5 minutes (1 minute by default).
  4. Save. The remote shows up in the Discovery tab: add it.

The key is kept by Gladys in its database, never shown again, and sent only to your remote, in the Authorization header of each request. The local API of the remote is plain HTTP: the key travels in clear on your local network, as for the web configurator of the remote.

Create an API key​

The key is created with the PIN of the web configurator of the remote (shown on the remote in the profile settings, web configurator section). From a computer on the same network:

curl -u web-configurator:<PIN> -X POST http://<address>/api/auth/api_keys \
  -H 'Content-Type: application/json' \
  -d '{"name": "Gladys", "scopes": ["admin"]}'

The answer holds api_key: copy its value into the API key field. It is shown only once. The integration never asks for the PIN. To revoke the key later: GET /api/auth/api_keys (with the PIN) then DELETE /api/auth/api_keys/<key_id>.

Sleep​

To save its battery, the remote goes to sleep and turns its Wi-Fi off: it no longer answers. "Reachable" goes to 0, the other values keep their last reading, and the integration tries again at each interval (never faster). The values come back as soon as it wakes up (a press, a pick-up, the dock). A button pressed while it sleeps answers that the remote is unreachable: nothing is sent. The integration does not wake the remote up (no Wake-on-LAN in this version).

While it sleeps, each reading costs one request (the activity list): the battery and the power mode are only asked once it answered.

Question to testers: tell us on the forum whether readings every 30 seconds keep the remote from sleeping or drain its battery faster. When in doubt, keep 1 minute or more.

Commands​

  • "Start" is sent in the order of the presses, one command at a time.
  • "Stop" goes at once, without waiting for the queued starts, and cancels the starts of the same activity still waiting. It is always tried once, even during a pause or while the key is held as refused, and even for an activity the integration has not read yet.
  • Each command must go through within 3.5 seconds (Gladys waits 5 seconds). When the remote does not answer in time, Gladys shows "sent, without confirmation" and the state is read again two seconds later.
  • After commands, the readings are grouped: one every 10 seconds at most.
  • A command the remote refuses (401 or 403) does not stop the integration: a reading checks the key at once, and only a refused reading holds it as refused.

Status and errors​

  • Key refused (revoked, or another remote at this address): the integration stops and only tries again by itself after 1 hour, then 6 hours, then every 24 hours. This stop is kept across restarts. Paste a new key (tried at once, even while a reading was under way) or click Reconnect (one try).
  • Too many requests (429) or remote busy (5xx): a pause of 1 minute to 6 hours (5 minutes by default for a 5xx, 15 minutes for a 429), kept across restarts. During the pause nothing is read and "Start" is refused; "Stop" still goes (one try). A 5xx of the activity list starts the pause; a 5xx of the battery, the power mode or the identity of a remote already known (at a restart, a new key or "Reconnect" too) only leaves those values out: the saved identity is kept and asked again 6 hours later, the activities are still followed. Only the very first identity reading, without which there is no device, pauses on a 5xx. A 429 always starts the pause.
  • Certificate refused: an https:// address with a self-signed certificate is refused; the status says so and nothing is sent. Type the address without https:// (the local API is plain HTTP).
  • No answer: see "Sleep".

Privacy​

The integration only talks to your remote, on your network. It reads /api/pub/version (without the key), /api/system, /api/system/power, /api/system/power/battery and /api/activities, and sends the activity commands to /api/entities/<activity>/command. Nothing goes to the Internet.

Credits​

JavaScript port of pyUnfoldedCircleRemote (MIT), the library of the Home Assistant integration by Jack Powell.

Configuration settings​

These are the settings Unfolded Circle Remote asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Your Unfolded Circle remotesectionNoBrings an Unfolded Circle Remote Two or Remote 3 into Gladys, through the local API of the remote (no cloud): battery level, charging, power mode, the activities running, and for each activity a button to start it and a button to stop it. The remote needs an API key (see the guide). A remote asleep does not answer: its values come back when it wakes up. Never tested with a real remote. Unofficial, not affiliated with Unfolded Circle.
Address of the remotestringYesIts IP address or host name on your network, as shown in the settings of the remote (Wi-Fi). A port may follow (192.168.1.20:8080).
API keysecretYesCreated on the remote (see the guide). Kept by Gladys in its database, never shown again, sent only to your remote.
Reading intervalselectNoHow often the remote is read. Shorter shows a started activity sooner.
Language of the namesselectNoUsed for the names of the features added from now on, and the activity names when the remote has them in several languages.

How to install Unfolded Circle Remote in Gladys​

  1. In Gladys, open Integrations: Unfolded Circle Remote appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/lm1lc3n7/gladys-unfolded-circle:0.1.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/LM1LC3N7/gladys-unfolded-circle.

Unfolded Circle Remote requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Unfolded Circle Remote is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by LM1LC3N7, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on