Rituals Perfume Genie smart home integration, free and open source
Rituals Perfume Genie 2.0 diffusers: on/off, intensity, perfume level, Wi-Fi, battery.
Published by LM1LC3N7
- Devices
- Version 0.1.1
- Requires Gladys >=5.1.0
- ★ 0
Brings the Rituals Perfume Genie 2.0 diffusers of your Rituals account into Gladys, through the Rituals cloud (the one the Rituals app uses). Unofficial integration, not affiliated with Rituals.
This integration has never been tested with a real diffuser: it was written from the
ritualsgenielibrary (the one Home Assistant uses) and tested against a simulated Rituals cloud. Feedback is welcome on the forum.
What you get
One Gladys device per diffuser of the account, named as in the Rituals app:
| Feature | Type | Notes |
|---|---|---|
| Diffusing | switch, on/off | Command: turn on, turn off. |
| Perfume intensity (1-3) | fan speed, 1 to 3 | Command: 1 low, 2 medium, 3 high. |
| Perfume level | level, % | An estimate from the use of the cartridge, as in the app. |
| Perfume | text | The name of the perfume, or "No cartridge". |
| Wi-Fi signal | signal, 0 to 5 | From the RSSI the diffuser reports. |
| Battery, Charging | battery %, charging | Portable Genie only; the level is rough (the app's icons). |
A diffuser that Rituals reports offline gets an "unreachable" badge and no new value until it is back.
Configuration
- In the Configuration tab, enter the e-mail and the password of your Rituals account. The password is kept by Gladys in its database, never shown again, and sent only to Rituals. A password without an e-mail is not used.
- The refresh interval (5 minutes by default, 2 minutes to 1 hour) sets how often the list of diffusers is read: one request each time, whatever the number of diffusers. The sensors (level, perfume, Wi-Fi, battery) take one request each, so they are read for one diffuser per read, at most every 30 minutes: Rituals has blocked clients that asked too often.
- Save, then add the diffusers from the Discovery tab.
- Test the connection shows the diffusers found. It reads the account only when the interval has passed since the last read; otherwise it shows the last read and when the next one comes.
How it talks to Rituals
- The integration logs in with the e-mail and the password and keeps the token Rituals gives (valid about an hour) in memory only. It renews it a minute before it expires, comparing with the date Rituals sends; without that date, the token is used until Rituals refuses it. Logins for reads and for turn on or intensity commands are at least 2 minutes apart (a turn off logs in at once). A 401 on a turn on or intensity command of one diffuser, with a token the account list accepts, refuses that command and keeps the token (a token revoked meanwhile is renewed at the next read). A turn off refused that way logs in again once for that token and is sent again. A 400 or 422 of the login without a message about the credentials is a wrong answer, retried later, not a refused password.
- It presents itself with its own name (
gladys-rituals), not as the Rituals app, and sends no key of the app. - Refused password: when Rituals refuses the e-mail or the password, nothing is tried again until you change them or the Test the connection button succeeds (one login per click, 30 seconds apart after a refusal). The refusal is remembered across restarts by a marker that cannot give the password back.
- Too many login attempts: Rituals then locks the logins for a while (it says how long); no login is tried before the end, even after a restart.
- 429 (too many requests) or 5xx on a read: reads and commands pause as long as Rituals asks (Retry-After), otherwise 1 minute, doubled each time, 6 hours at most; the pause survives a restart. A turn off is not paused. A 5xx on a command concerns that diffuser only (no pause).
- Network errors, unreadable answers: the reads wait longer each time (never less than the interval). A 401 on a token Rituals just gave is not a refused password: the reads are spaced out, doubled each time, up to one hour.
- After a restart, the next read never comes sooner than the interval after the last one, even if the clock of the machine moved.
Commands
-
Turn on and intensity wait their turn per diffuser (two at most waiting) and are refused, with nothing sent, while Rituals asks to wait (429), for a diffuser offline or unknown, or with a refused password. Once sent, the integration reads the diffuser back: the state in Gladys changes only when Rituals shows the value asked. Otherwise ("not applied yet", or no answer), Gladys keeps the previous state and the list is read again 5 and 20 seconds later.
-
Turn off is handled as a protective command. It does not wait for a read in progress (a read silent for a second is cut, without counting as a failure), for the 429 pause, for the spacing of the logins nor for other commands; it logs in at once when no token is held; it cancels the turn on and intensity commands still waiting for that diffuser; if a command was already on its way, the turn off is sent again after it. It is kept in
/dataand tried again every minute for 30 minutes, until a read made after it shows the diffuser off, unless a newer command for that diffuser left meanwhile. Only the sends that reached Rituals count, three at most: a try that never left (network down, logins locked, 429, a 401 before the token was renewed) does not count, and the turn off leaves as soon as it can; after a 429, not before the Retry-After of Rituals (within the 30 minutes). A second turn off of a diffuser whose turn off is on its way joins it when no other command of that diffuser left meanwhile (otherwise it is sent itself), and is confirmed only by a read made after it. A turn off sent without an answer is read back 5 and 20 seconds later (that diffuser alone, even during a pause); a diffuser turned on again from the Rituals app before that confirmation may be turned off again by a resend. After a restart, a kept turn off is sent as soon as the configuration is read, before the first read; one clicked while Gladys has not given the configuration yet is kept and sent then.A turn off is refused only when: no account is configured once the configuration is read (or the e-mail is missing or invalid); Rituals refused the e-mail or the password (until they change or the test button succeeds); Rituals locked the logins and no token is held (it is then kept and sent again); the diffuser was never seen on the account (neither in a read nor in
/data); Rituals answers that the diffuser is not linked to the account; Rituals answers the turn off with another error 4xx (it is then kept and sent again).
The diffuser's own schedules (set in the Rituals app) keep working and may turn it on or off by themselves.
Privacy and data
/data/rituals-state.json keeps: the time of the last read and of the last
login, a pause or a lockout asked by Rituals, the marker of a refused login (8
bits of a salted hash), a salted hash of the account, the diffusers seen
(hublot, API hash) and the turns off still to confirm. Never the
password, the e-mail nor the token. If the file cannot be read, it is not
written over.
Troubleshooting
- "Rituals refused the e-mail or the password": check them in the Rituals app, fix them in Gladys (the integration tries again at once) or click Test the connection.
- "paused": Rituals asked to wait; the integration resumes by itself.
- A diffuser is missing: it must be on the account and have a valid
identifier; the logs (
docker logs) say when one is left out.
Configuration settings
These are the settings Rituals Perfume Genie asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Your Rituals account | section | No | Brings the Rituals Perfume Genie 2.0 diffusers of your Rituals account into Gladys through the Rituals cloud (the one of the Rituals app): turn on and off, perfume intensity (1 to 3), perfume level, perfume name, Wi-Fi signal, and the battery of the portable model. Enter the e-mail and the password of your Rituals account, then add the diffusers from the Discovery tab. The list is read every 5 minutes by default, the sensors every 30 minutes (Rituals blocks clients that ask too often). Unofficial, not affiliated with Rituals. |
| Rituals e-mail | string | Yes | |
| Rituals password | secret | Yes | Kept by Gladys in its database, never shown again, sent only to Rituals. |
| Refresh interval (s) | number | No | How often the list of diffusers is read, in seconds (120 to 3600). One request each time, plus one per sensor of one diffuser every 30 minutes. |
| Language of the feature names | select | No |
How to install Rituals Perfume Genie in Gladys
- In Gladys, open Integrations: Rituals Perfume Genie appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/lm1lc3n7/gladys-rituals:0.1.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/LM1LC3N7/gladys-rituals.
Rituals Perfume Genie 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
Rituals Perfume Genie 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.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation