User guide
Everything you need to set up PocketOS, connect your home and get the most from it.
Setting up
PocketOS arrives with its software installed. Setup takes a few minutes and needs only your phone.
The complete walkthrough is in Getting started.
The settings page
Each PocketOS hosts its own settings page on your home network.
Opening it
- Tap the Settings tile on PocketOS and scan the code.
- Or, on any phone or computer on your Wi-Fi, type the address shown on PocketOS under This PocketOS.
- On iPhone or iPad, choose Share → Add to Home Screen for quick access.
What you can change
The settings page works like PocketOS itself: tap a tile to open it, then tap ‹ or swipe right to go back.
Controls
Use the touchscreen for everyday control, and the two buttons on the side for the screen, power and voice.
Touchscreen
| To | Do this |
|---|---|
| Open the menu | Swipe up or left on the home screen |
| Go back | Swipe right |
| Open a room or device | Tap it |
| Change brightness, temperature, volume or position | Slide your finger around the ring |
| Turn on or off, play or pause, lock or unlock | Tap the button in the middle |
Side buttons
Power button
- Press
- Turn the screen off or on.
- Hold for 1 second
- Switch PocketOS on, when it’s off.
- Hold for 6 seconds
- Switch PocketOS off. After a moment the screen says “Keep holding to switch off”.
Boot button
- Press
- Show the code that opens the settings page on your phone. If the screen is off, it wakes up.
- Press twice
- Go back to the home screen.
- Hold
- Talk to your home. Let go when you’ve finished speaking.
Lights
Open a light and turn the dial to set its brightness. If the light supports them, the buttons beside the power button switch the dial to warmth (from warm white to cool white) or colour. Tap the same button again to go back to brightness.
When you change something, PocketOS shows “Sending…” until your home confirms it. If there’s no answer within six seconds, it shows “No response”.
Managing devices
Choose what PocketOS shows, what it calls things and what comes first. Nothing changes in Home Assistant.
On PocketOS
Press and hold a device in any list, or open it and tap ··· at the top of its screen. You can then:
- Add to favourites or Remove from favourites
- Move up or Move down to change its place in Favourites
- Hide from PocketOS to take it out of menus and lists. To bring it back, go to More → Hidden devices.
On the settings page
- Open Devices and tap ✎ next to a device to rename it, favourite it or hide it.
- Your favourites are listed at the top. Use the arrows to put them in order.
- To go back to Home Assistant’s name, open the device and choose Use that name.
Names can be up to 32 characters. To remove a device completely, delete it in Home Assistant; PocketOS removes it too.
Voice
Hold the Boot button, say what you’d like, for example “turn on the kitchen lights”, then let go. PocketOS shows what it heard, then shows and says the reply.
To keep replies on screen only, or to change how loud they are, open the settings page and go to Smart home → Voice. Holding the Boot button again stops a reply that’s still playing.
Voice uses the assistant set up in Home Assistant under Settings → Voice assistants, which needs speech-to-text configured. Spoken replies also need text-to-speech set up in the same assistant. Without it, replies are shown on screen only.
Battery and power
- Battery status appears on PocketOS under This PocketOS, and on the settings page with a 48-hour chart.
- Time remaining is estimated after a few hours off the charger, based on your actual use.
- Screen timeout is 30 seconds by default. Choose Never only when PocketOS stays on the charger.
- Away mode: when you leave home, PocketOS sleeps and checks every five minutes for your return.
- Low battery: when the battery is empty, PocketOS shuts down safely and restarts once charging.
Updates
PocketOS checks for a new version once a day. Choose how updates install under More → Updates.
| Setting | Behaviour |
|---|---|
| Notify | Shows an alert on PocketOS and the settings page. Install with a tap. Default. |
| Install overnight | Installs between 2 and 5 am while charging and not in use. |
| Off | Never checks for updates. |
Updates need 30% battery or a charger. Each update is verified before it runs. If a new version fails to start, PocketOS returns to the previous one automatically. See What’s new.
More than one PocketOS
Each PocketOS has its own name, address, settings and paired phones. The settings page always shows which one you’re changing. Add each one to your Home Screen separately.
Troubleshooting
The settings page won’t open
Make sure your phone is on the same Wi-Fi as PocketOS. Some Android phones can’t open addresses ending in .local. Use the number address shown on PocketOS under This PocketOS instead, for example 192.168.1.40.
I’m asked for a pairing code again
This happens after Forget all phones or a reset. Press the Boot button to show the code on PocketOS.
Home Assistant won’t connect
Check that Home Assistant is running and that the address on the Smart home page is the one you use to open it, for example http://homeassistant.local:8123. If PocketOS says its sign-in was refused, create a new access token in Home Assistant and paste it in again.
A device shows “No response”
Home Assistant didn’t confirm the change. Check that the device is powered and available in Home Assistant.
I’ve changed my router or Wi-Fi password
If only the password changed, PocketOS notices and its screen says Wi-Fi changed? Press Boot. Press the Boot button, then press it again to confirm. For a new router, open More → This PocketOS → Change Wi-Fi network on PocketOS and press the Boot button to confirm. Either way, PocketOS restarts into setup and keeps all your other settings. Then follow Connect to Wi-Fi.
PocketOS won’t start
Connect it to a USB-C charger for a few minutes, then hold the Power button for a second. If it still doesn’t start, its software can be reinstalled from Software recovery. This erases its settings.
Resetting PocketOS
On PocketOS, open More → This PocketOS → Reset PocketOS and press the Boot button to confirm. Or, on the settings page, choose More → Reset everything, then press the Boot button on PocketOS within 15 seconds to confirm. Nothing is erased unless you press it.
Privacy
PocketOS has no account, cloud service, advertising or analytics. Your Wi-Fi password, Home Assistant token, devices and settings are stored only on the device.
- Home Assistant: PocketOS connects only to your own Home Assistant. Voice requests go there too.
- Updates: once a day PocketOS downloads a small file from the PocketOS update server to check for a new version. Nothing about you or your home is sent. You can turn this off.
- This website uses no cookies or analytics. Like any host, Vercel can see visitors’ IP addresses.
- On your Wi-Fi, the settings page isn’t encrypted between your phone and PocketOS, like most home devices. Your Wi-Fi password keeps outsiders out.
Lost or sold your PocketOS? See how to cut off its access. Full details: Privacy and Security.