Metadata-Version: 2.5
Name: sofabaton-x-server
Version: 0.2.5
Summary: Self-hosted hub management, web remote and local API for Sofabaton X1 / X1S / X2
Project-URL: Homepage, https://github.com/m3tac0de/home-assistant-sofabaton-x1s/tree/main/sofabaton-x-server
Project-URL: Issues, https://github.com/m3tac0de/home-assistant-sofabaton-x1s/issues
Project-URL: Changelog, https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/CHANGELOG.md
Author: m3tac0de
License: MIT
Keywords: home-automation,openapi,rest,sofabaton,universal-remote,websocket,x1,x1s,x2
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Home Automation
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115
Requires-Dist: sofabaton-x<0.3,>=0.2.4
Requires-Dist: uvicorn[standard]>=0.47
Provides-Extra: dev
Requires-Dist: httpx; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: websockets>=12; extra == 'dev'
Description-Content-Type: text/markdown

# Sofabaton X Server

**Manage your Sofabaton hubs from your browser.**

Sofabaton X Server is a self-hosted management application for **X1, X1S,
and X2** hubs. Configure devices and activities, edit commands and button
assignments, back up and restore your configuration, and control your
equipment with the built-in web remote.

Run one server for all your hubs. Open it from a computer, phone or tablet
on your network. **No Home Assistant installation is required.** Its local
HTTP and WebSocket API also lets you connect your hubs to automation
platforms and build your own integrations.

> Unofficial community project; not affiliated with or endorsed by Sofabaton.

[Get started](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/getting-started.md) ·
[Manage your hubs](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/managing-hubs.md) ·
[Run the server](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/running-server.md) ·
[Build an integration](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/first-integration.md)

## Control panel

| What you want to do | Where to start |
| --- | --- |
| Add a hub or switch between hubs | The hub picker at the top of the panel |
| Edit devices, commands and IR payloads | **Hub → Devices** |
| Change activity buttons, favorites, macros, power sequences and inputs | **Hub → Activities** |
| Create, edit or restore a backup | **Backup → Make / Edit / Restore** |
| Control equipment and customize your web remote | **Remote → Card / Layout** |
| Set up remote buttons for an integration to use | **Wifi Commands** |
| Require a sign-in for changes, and make tokens for integrations | **Server settings → Access** in the cog menu |
| Configure and test the X2 MQTT broker | **Server settings → MQTT broker** (admin sign-in required) |

Review configuration changes before **Sync to Hub** writes them. The panel
shows progress and prevents competing writes while another hub operation
or the official Sofabaton app owns control.

Follow the [hub management guide](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/managing-hubs.md)
for editing, synchronization, backups and Wifi Commands.

## Run

You need a Sofabaton X1, X1S or X2 hub and something on the same network
that stays on to run the server: a NAS or Docker host, or a computer
running Windows, macOS or Linux. One server manages all your hubs. (Home
Assistant users have the
[integration in this repository](https://github.com/m3tac0de/home-assistant-sofabaton-x1s),
which manages hubs inside Home Assistant; this server is for everyone
else and for other platforms.)

**Fully close the official Sofabaton app on all phones and tablets before
setup.** If another proxy, including the Home Assistant integration,
already manages the hub, disable that hub there first.

Pick the way that fits where it will run:

- **Docker, or a NAS such as a Synology:** run the published image
  `m3tac0de/sofabaton-x-server` (also on GHCR) with the
  [Compose file](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docker-compose.yml)
  and Linux host networking. See [Docker](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/running-server.md#docker).
- **A computer (Windows, macOS, Linux):** install with
  [pipx](https://pipx.pypa.io/stable/installation/), which keeps the
  server in its own Python environment and upgrades with one command:

  ```sh
  pipx install "sofabaton-x-server>=0.2.5,<0.3"
  sofabaton-x-server --data-dir <a folder for its data>
  ```

  Plain `pip` works too. See [Install](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/running-server.md#install).
- **From source:** install both packages from the repository root. See
  [from a source checkout](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/running-server.md#from-a-source-checkout).

Then open `http://<server>:8480/`, or `http://localhost:8480/` on the
machine running it. Add your hub through the hub picker, try **Remote**,
then create and download your first backup. The
[getting-started guide](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/getting-started.md)
walks through each step.

Keep the server's data directory across restarts; the Server page tells
you when a newer release is out and how to update your kind of
installation. Until you set up access (**Server settings → Access**),
anyone on your network can change your hubs; see
[security](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/running-server.md#security).

<!-- Keep earlier deployment links and bookmarks useful. -->
<a id="docker"></a>
<a id="behind-a-reverse-proxy-tls"></a>
<a id="settings"></a>
<a id="security"></a>

For [Docker](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/running-server.md#docker),
[networking and reverse proxies](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/running-server.md#behind-a-reverse-proxy-tls),
[settings](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/running-server.md#settings),
and [storage and upgrades](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/running-server.md#storage-and-upgrades),
see **Running the server**.

## Using the official Sofabaton app

After setup, the official app can connect through the server's local
proxy. The hub normally accepts one client connection; the server holds
that connection and presents a virtual hub to the app.

While the app is connected, the server observes the session and pauses
control and configuration writes. Close the app to return control to the
panel and your integrations. After editing in the app, refresh the affected
devices or activities in the panel.

<a id="ir-payloads-backup-restore"></a>

## Back up and restore

Use **Backup → Make** to save your entire hub or selected devices, then
download the result. Edit a backup file in the browser or restore selected
devices and activities through **Backup → Edit / Restore**.

The downloaded file is your backup; the server keeps no backup archive.
See [back up and restore](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/managing-hubs.md#back-up-and-restore)
for the steps and restore options. For command payloads, see the
[IR reference](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/api-reference.md#ir-payloads-backup-restore).

## Web remote

Use **Remote** in the panel, or open `http://<server>:8480/ui/remote/`
for a standalone remote. Select a hub, bookmark the page, or add it to
your phone's home screen. Customize its buttons and layout in
**Remote → Layout** and save the configuration for that hub.

The same card is also a web component for your own dashboard: load
`/ui/embed/sofabaton-remote.js` from the server and place
`<sofabaton-remote hub="...">` on any page whose origin you list under
Server settings → Access (or install `sofabaton-x-remote` from npm).
See the [web remote guide](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/web-remote.md)
for layout options, device mode and dashboard embedding.

<a id="wifi-commands"></a>
<a id="button-events"></a>
<a id="mqtt"></a>

## Connect an automation platform

The server provides activity control, command sending, hub state and
remote-button events for integrations. **Wifi Commands** lets you assign
selected remote buttons to events an integration can receive. An
integration must receive those events and run the actions in your platform.

The [Hubitat example](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/examples/hubitat/README.md)
demonstrates activity switches, command actions and button events.
Developers can use the same API to build integrations for other platforms.

For setup, see [Wifi Commands](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/managing-hubs.md#wifi-commands).
For delivery details, see the [button-event](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/api-reference.md#button-events)
and [MQTT reference](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/api-reference.md#mqtt).

<!-- Earlier reference anchors remain entry points to the moved material. -->
<a id="api"></a>
<a id="snapshot"></a>
<a id="jobs"></a>
<a id="writes"></a>
<a id="whole-document-writes"></a>
<a id="recovery-and-retention"></a>
<a id="discovery"></a>
<a id="events-websocket"></a>

## Build an integration

Use the server as the starting point for a platform integration. Let users
configure their hubs in the panel, then select those hubs in your client.
Your integration can focus on controls, state and automations, and link
back to management and the web remote.

- [Build an integration](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/first-integration.md): activity controls, synchronized state, command actions and remote-button triggers, with an optional runnable client.
- [Platform integration guide](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/platform-integration.md): production behavior, errors, reconnection and optional editing flows.
- [API reference](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/api-reference.md): snapshots, jobs, writes, recovery, IR payloads, backups, discovery and events.
- [OpenAPI document](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/openapi.json): the committed contract for generated clients. A running server also serves interactive docs at `/api/v1/docs`.

## Help and releases

Start with [setup troubleshooting](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/getting-started.md#if-something-does-not-work).
For a bug report, [open an issue](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/issues)
with your server version, hub model and firmware, installation method,
relevant logs and steps to reproduce the problem.

This README describes **0.2.5**, using **API 1** and
**sofabaton-x >=0.2.4,<0.3**. Read the
[changelog and upgrade notes](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/CHANGELOG.md)
when updating. This release adds per-hub server IP overrides, improves
multi-interface routing, lets you copy favorites between activities, and
updates the control panel and web remote. Existing access settings, hub
registrations, Wifi Devices and saved layouts carry forward without conversion.

## Development

See [server development](https://github.com/m3tac0de/home-assistant-sofabaton-x1s/blob/main/sofabaton-x-server/docs/development.md)
for building the UI, tests, OpenAPI generation and releases.
