4Home User Manual

For 4Home 0.1.21 (beta), last updated 30 October 2026. Android 13 or later.

4Home is a companion for Home Assistant. You choose the devices it may use, then work them from 4Home, from Quick Settings tiles, from the launcher, from 4Dictate's keys and gestures, and (with 4Dictate, a paid app) by voice.

1. What 4Home is

4Home connects to your own Home Assistant. It does not replace it. Home Assistant still runs your home; 4Home gives you quick ways to use the parts you pick.

You choose. Nothing is offered to voice commands or shortcuts until you switch it on, device by device.
Many ways in. Use a device from Quick Settings tiles, the launcher's long-press menu, 4Dictate's keys and gestures, and by voice with 4Dictate.
Home Assistant's own actions. Each device offers only what Home Assistant says it can do. 4Home invents nothing and guesses nothing from a device's name.
Nothing goes to us. 4Home talks only to your Home Assistant, at the address you give it. There is no account, no analytics and no advertising.

4Home is not made by, or affiliated with, Home Assistant, the Open Home Foundation or Nabu Casa.

The main screen shows two cards: Home Assistant (your address, or "Not connected yet") and Offered to voice commands (one row for each device you offered, with its states as buttons you can tap, such as "up" and "down", and "always ask" beside the ones that ask first; tap the name or the pencil to rename it or its scenes). ⚙ at the top opens Settings, whose pages are Dashboards · All devices · Shortcuts · Home Assistant · Backup · About.

2. Getting started

Make a token in Home Assistant. In Home Assistant, open your profile (your name at the bottom of the side bar), choose the Security tab, and under Long-lived access tokens choose Create token. Give it a name such as "4Home" and copy it. Home Assistant shows it only once.
Open 4Home, then ⚙ → Home Assistant.
Address: type your Home Assistant's whole address, for example https://homeassistant.local:8123 or your Home Assistant Cloud address. https always works. Plain http is allowed only to a 192.168.x, 10.x, or 100.64.x to 100.127.x address, such as http://192.168.x.x:8123 with your Home Assistant's numbers, because the token would otherwise travel readable. If the address cannot be used, the box says why.
Access token: paste the token and press Save token. It is kept encrypted on this phone. It is never shown, logged or backed up. Remove token deletes it; pasting a new one replaces it.
Test connection asks Home Assistant whether the address and token work. It changes nothing. "Connected" means you are ready.
Go to All devices (or Dashboards) and press Read the list. 4Home reads your devices and your dashboards from Home Assistant and says how many it found, for example "212 found, 3 dashboards."
Switch on Offer to voice commands for the devices you want to use (section 3).

3. All devices

⚙ → All devices lists everything 4Home read from Home Assistant, grouped by type:

Group	What it holds
Lights and rooms	Lights, and groups of lights such as a whole room
Scenes	Home Assistant scenes
Switches and plugs	Switches and smart plugs
Heating	Thermostats
Buttons	Home Assistant buttons
Numbers	Settings Home Assistant keeps as a number, such as a timer length
Sensors	Readings, such as a temperature or a plug's power. These can be asked about, not changed.
Covers	Blinds, curtains, garage doors, a desk that moves: anything Home Assistant calls a cover
Media players	Speakers and TVs. These can be asked about, not changed.

Search by name (the 🔍 box at the top) finds a device by its name in 4Home, its name in Home Assistant, or its Home Assistant id. Show only what is offered hides the rest.
Offer to voice commands: off for everything to start with. Switch it on and 4Dictate may use that device. Switch it off and it can no longer be used, at once, even by a request already on its way.
Always ask: off for everything to start with. Switch it on and every change to that device asks first, by any way in: 4Dictate shows its Do it box every time, even with "Change without asking" on, and a tile or launcher shortcut says "This device is set to always ask" with Cancel and Do it.
Shortcut: for lights, switches, scenes, buttons, covers and heating. Switch it on to get that device's ready-made shortcuts (section 5). A device must be offered to voice commands first: until then the switch is greyed and says "Offer it to voice commands first."
Renaming: tap a device's name. The "Name for voice commands" box shows what Home Assistant calls it. Type the name you will say, such as "hall light" or "desk", and press Save. Leave it empty to use Home Assistant's name again. Renaming in 4Home changes nothing in Home Assistant.

When you say a name, small differences do not matter: case, punctuation, a leading "the" or "my", and a trailing "light" or "lamp" are ignored, so "the hall light" finds "Hall". If two devices could match, 4Home never guesses: it asks which one. If a name is only close, 4Dictate asks "Did you mean …?" and does nothing until you say yes.

4. What each device can do

Each device offers only the actions Home Assistant reports for it. A light that does not dim has no brightness; a blind that cannot stop part way has no stop. If you ask for something a device does not offer, nothing is changed and the reply lists what it does offer.

Type	Actions
Lights	on, off, toggle; and, when the light reports them, brightness, colour, white (warm to daylight) and effects. Brightness is 0 to 100%; 0% turns the light off. Brightness can go with a colour, a white or an effect in one go ("warm white 40%").
Switches and plugs	on, off, toggle
Covers	open, close, stop, and position (0 is closed, 100 is open), each when the cover reports it
Buttons	press
Scenes	start
Numbers	set a value, kept within the number's own minimum, maximum and step
Heating	temperature in °C (kept within the thermostat's own limits and step), mode (the thermostat's own modes, such as heat or off), and each of its own presets
Sensors, media players	nothing to change; 4Dictate can ask about them (section 7)

Colour

Any colour name Home Assistant knows, such as red, orange, light blue or gold. By voice you can also give red, green and blue values. A name Home Assistant does not know is refused before anything is sent.

White, warm to daylight

Four whites, each kept within the light's own range as Home Assistant reports it:

Say	Kelvin
warm white	2700 K, or the light's warmest if that is higher
neutral white	4000 K
cool white	5000 K
daylight	6500 K

A light that goes from 3000 K to 6000 K, for example, gets 3000 K for warm white and 6000 K for daylight. By voice you can also give a number of kelvin; it is kept within the light's range in the same way.

Effects

The light's own effect list, as Home Assistant reports it, by their own names.

5. Shortcuts

⚙ → Shortcuts lists every shortcut. Each one is a single Home Assistant action on one device. It runs exactly as a voice request would, with the same checks.

Automatic shortcuts

Switch on Shortcut for a device and it gets one shortcut for each action that needs no value: a light's on, off and toggle; a switch's on, off and toggle; a scene's start; a button's press; a cover's open, close and stop; each of a thermostat's presets. Each is named after the device and the action, such as "Hall on" or "Blind open". A shortcut set to ask first shows "asks first".

Renaming: tap the pencil. The "Shortcut name" box sets the name shown on tiles, the launcher and in 4Dictate. Leave it empty, or press Reset, to use the automatic name.
A shortcut works by the device's Home Assistant id, not its name, so renaming the device or the shortcut never breaks a key, a gesture or a tile.

Your own shortcuts with a value

+ Add a shortcut makes one with its value set, such as a light at 40% or in warm white, a blind at half way or the heating at 20 °C.

Choose a device. Devices with "Shortcut" switched on that have an action taking a value are listed: a light that dims, a cover that moves to a position, a thermostat.
Choose what it does: Brightness, Colour, White, warm to daylight, Effect, Position, Temperature or Mode, as Home Assistant says that device offers.
Set the value. Brightness and position have a slider. Colour takes a colour name, with buttons for common ones. White shows the four whites with the kelvin each gives on that light. Effect and Mode list the device's own. Temperature shows the thermostat's limits, and keeps the value within them. For colour, white and effect, Also set the brightness adds a brightness.
Name it, or keep the name 4Home suggests, such as "Hall warm white 40%" or "Heating 20 °C". Press Add.

Your own shortcuts have a bin as well as a pencil. Delete asks first, because a key, gesture or tile that runs it stops working. Automatic shortcuts cannot be deleted: switch off "Shortcut" on the device instead.

Where shortcuts appear

Quick Settings tiles (section 6).
The launcher: long-press the 4Home icon. Shortcuts appear in list order, as many as your launcher shows.
4Dictate's keys and gestures: in 4Dictate, ⚙ → Keys & buttons has a 4Home key, and gesture apps can run "4Home: <shortcut>".
4Dictate's Voice commands → Home: say a shortcut's name in command mode (section 7).

6. Dashboards and Quick Settings tiles

Dashboards

⚙ → Dashboards is the first page. After Read the list it shows each of your Home Assistant dashboards, with the devices its cards show, in the same order. Usually these are the few devices that matter, out of the hundreds Home Assistant has. Each device has the same switches as under All devices, and tapping its name renames it. A dashboard that shows no device is left out, and two identical dashboards are shown once. Everything else is under All devices.

Quick Settings tiles

4Home has four tiles, "4Home tile 1" to "4Home tile 4".

Pull down Quick Settings, open its edit view (the pencil), and drag the 4Home tiles you want into place.
In 4Home, ⚙ → Shortcuts, tap Tile 1 (or 2, 3, 4) and choose a shortcut, or Empty.

A tile shows its shortcut's name. An empty tile says "Choose in 4Home's settings".
Tap the tile to run the shortcut. What Home Assistant did shows briefly, for example "Hall: on.".
A tile does not show whether a device is on or off: that would mean asking Home Assistant all the time.
A device set to Always ask asks first.

7. With 4Dictate

4Dictate is our dictation app (a paid app). With it, you can use the devices you offered by voice. See the 4Dictate manual for its side.

The Home group: your shortcuts by phrase

In 4Dictate, the Voice commands tab has a Home group under Command mode, listing every 4Home shortcut. Each shortcut's name is its first phrase, and you can add phrases of your own there. In command mode, say the phrase on its own, such as "hall light on". It runs at once: no model is asked, so this step needs no internet. 4Home still needs to reach your Home Assistant. If you rename a shortcut in 4Home, the new name is its phrase from then on.

Voice commands: object and state

A voice command about your home is a device and what you want it to be: "Desk up", "John's room 50%", "John's room blue", "John's room warm", "John's room Relax". 4Home gives 4Dictate the list: each device you offered, under your name for it, and the states it takes, all taken from what Home Assistant says that device can do.

Fixed words: on and off for lights and switches; up, down, open, close and stop for a cover, as it offers them; press for a button; start for a scene; a thermostat's own modes and presets; a light's own effects. There is no "toggle": say on or off.
A value: a percent (brightness, or a cover's position), a colour, a white (warm, neutral, cool, daylight), or a number (a thermostat's temperature, a Home Assistant number), each only where the device supports it.
Scenes of a light: when Home Assistant puts a scene on the same device as a light, as a Hue room's scenes are, the scene is a state of that light. Its word is its name without the light's name in front, so "John's room Relax" is "Relax". A scene on no device, or on a device with more than one light, stays a device of its own: say its name to start it. 4Home links them by Home Assistant's device only, never by area or by name.

The main screen shows each device as one row: its name, and beneath it its states as buttons, such as "on", "off", "Relax" and "Read", followed by what takes a value ("%", "colours", "whites"). Tap a state to do it now, with the same checks and the same "always ask" as a voice command. Tap the name or the pencil to rename the device or any of its scenes. You can also rename in Settings: 4Dictate uses 4Home's names. Which scene belongs to which light is read again each time you read Home Assistant's list, and 4Home reads it by itself when it has not yet, such as after an update or a restore. Every state goes through the same checks as any other request, and Always ask still asks.

Keys and gestures

You choose which states are links: tap a device's name on the main screen and, under Links, switch on the states you want, such as "Desk up" or "John's room Relax". Every switch starts off. Apps connected through 4Link can bind the states you switched on to a key or a gesture. The key keeps working when you rename the device. Your choice of links is kept in 4Home's backup.

Anything else: through the tidy-up model

Any other request about your home, such as "landing light 50%", "the desk to 30%", "heating to 20" or "is the hall light on?", goes to 4Dictate's tidy-up model. The model sees only the devices you offered to voice commands, by your names for them, and asks 4Home through 4Link, our way for apps on your phone to work together. 4Home checks every request again against your current choices before Home Assistant is asked to do anything.

A change asks first in 4Dictate's Do it / Cancel box, unless you turned on "Change without asking" for 4Home in 4Dictate's Connected apps. A device set to Always ask asks every time.
A question ("is the plug on?", "how warm is it in the hall?", "what's the speaker playing?") gets an answer from Home Assistant as it is now.
Each reply says what was done, such as "Hall: on, warm white (2700 K), 40%." If nothing could be done, it says why and ends "Nothing was changed."

Connected apps and approvals

Our own apps can use 4Home directly. Any other app must ask you first: 4Home shows "<app> wants to use 4Home", with the app's name and certificate, and a list of what it asked for, grouped Read and Change, each saying what the app will send. Tick what it may do and press Allow ticked, or Refuse.

⚙ → About → Apps allowed to use 4Home shows each allowed app, what it may do and when it last did it, with Remove (which asks first). Below is the call log, newest first. It records which app called and the result, never what it sent.

8. Backup

⚙ → Backup saves your setup as a file you keep. Your token is never in a backup, not even encrypted.

Save a backup: choose where to save it. It holds the Home Assistant address, the devices you ticked, Always ask, your names, shortcuts and their names, tiles and dashboards.
Restore from a backup: choose the file. 4Home first shows "Replace your setup?" with when the backup was saved and a line for each thing it changes (address, devices listed, offered to voice commands, your own names, Always ask, shortcuts, tiles, dashboards, your own shortcuts), each with the number now. Nothing is replaced until you press Replace. A token already on the phone stays if the backup has the same address. If the address changes, 4Home removes the token on this phone, so it never goes to the new address unasked. If there is then no token, 4Home opens the Home Assistant page so you can paste it once.
Automatic copy: switch it on and pick a folder once. 4Home then saves 4Home-backup.json there after each change to your setup, replacing the last copy. The card shows the folder and when it last saved, or why it could not.
Apps you allowed to use 4Home are not in a backup. After a restore, you allow them again.

9. Troubleshooting

When something doesn't work

When a tap, a shortcut, a tile, a key or a voice command does nothing, 4Home says why and what to do. The same sentence appears in 4Home and in the app you used.

"4Home isn't connected yet." No address or token is saved. Open 4Home and add them.
"Home Assistant refused 4Home's token." The token was deleted in Home Assistant or mistyped. Enter it again in 4Home's settings.
"Home Assistant's certificate wasn't accepted." The address may be wrong. Check it in 4Home's settings.
"Cannot reach Home Assistant." Home Assistant is switched off, or this phone cannot reach it, for example on another network. Switch it on, or connect the phone.
"Home Assistant can't reach …" Home Assistant has the device but cannot talk to it: it may have no power, a flat battery, or be out of range. For a group of lights or a scene, it means none of its lights answered. Check the device.
"… is not in Home Assistant." The device was removed or renamed in Home Assistant. Check its configuration there, then press Read the list in 4Home.
"Home Assistant answered with an error" Something else went wrong in Home Assistant. Its own log says more.

Message or problem	Try
"Not connected yet" or "4Home isn't connected yet"	⚙ → Home Assistant: add the address and the token, then Test connection.
"Home Assistant refused 4Home's token"	The token was deleted in Home Assistant, or mistyped. Make a new long-lived access token (section 2) and paste it on its own.
"Cannot reach Home Assistant"	Home Assistant, or the computer it runs on, is off or out of reach. Check you can open it in a browser at the same address.
"Home Assistant's certificate wasn't accepted"	Check the address in ⚙ → Home Assistant.
A device "is unavailable in Home Assistant"	Home Assistant cannot reach that device: it may be unplugged, out of battery or offline. Fix it in Home Assistant; 4Home has nothing to change.
"Home Assistant can't reach …"	The device is known to Home Assistant but did not answer: check its power, battery or range.
"… is not in Home Assistant"	It was renamed or removed in Home Assistant. Check its configuration there, then read the list again.
"4Home doesn't know yet what … can do"	Read the list again: 4Home then knows what that device offers.
In 4Dictate: "… is no longer one of 4Home's shortcuts"	The shortcut was removed, or its device's "Shortcut" switched off. Switch it on again in 4Home, or choose another shortcut for that key.
"That 4Home shortcut has gone"	From the launcher: switch "Shortcut" on again for that device.
Something new in Home Assistant is missing, or a device has new abilities	Press Read the list again after changing things in Home Assistant. New devices arrive switched off; your choices for the others are kept.

To report a problem, email [email protected] with the time it happened and what the message said.

10. Privacy

4Home talks only to your own Home Assistant. Nothing goes to us: there is no account, no analytics and no advertising. Your token stays encrypted on your phone. See the 4Home privacy policy.