Skip to main content

Crafty Controller smart home integration, free and open source

Crafty Controller integration for Gladys Assistant

Your Minecraft servers in Crafty: running, players, CPU, start, stop, backup from scenes.

View on GitHubAll integrations

Follow and drive your Minecraft servers managed by Crafty Controller from Gladys: whether each one runs, how many players are on it and who, its CPU and memory, its version. Gladys can react when a player joins or leaves, when a server empties or fills up, stops unexpectedly or restarts — and start, stop, restart or back up a server from a scene or from the dashboard.

The integration talks to the REST API of Crafty 4 on your network, with an API token. Nothing to install on the servers. It is not affiliated with Crafty Controller nor with Mojang.

Without Crafty, the Game Servers (GameDig) integration (gladys-gamedig) reads a Minecraft server (and 300 other games) like the server list of the game, and Minecraft Server reads it through RCON.

Tested against a real Crafty Controller 4.11 (a Paper 1.21.4 server, real players connected, a crash and a clean stop), but not yet inside a real Gladys: feedback welcome. If something does not work as described, please say so on the Gladys forum or in the issues.

What you need​

  • Gladys Assistant 5.1.0 or later.
  • Crafty Controller 4 (checked on 4.11), reachable from Gladys: by default https://<address of Crafty>:8443.
  • An API token of Crafty:
    1. in Crafty, open Panel Config → Users, edit your user (or a user made for Gladys), then the API Keys tab;
    2. create a key: a name (gladys), and Full Access (or, for a key limited to some rights: Commands to start, stop, restart and back up, Logs to tell a crash from a clean stop);
    3. click Get A Token and copy the long text it shows.

The token acts with the rights of its user: a user who only sees some servers gives a token that only sees them.

Set up​

  1. Install the integration: Integrations → Install from GitHub, address https://github.com/guim31/gladys-crafty.
  2. In its configuration:
    • Crafty address: the address you open Crafty with, e.g. https://192.168.1.10:8443. A bare IP address gets https:// and the port 8443.
    • API token: the token copied above.
    • Accept self-signed certificates: ticked by default, Crafty serving its HTTPS with its own certificate. Untick it only if yours is a trusted one.
    • Allow stop and restart: off by default. Stopping or restarting a server throws its players out: tick it to allow them from the scenes and the widget.
    • Refresh interval: 30 seconds by default (Crafty measures its servers every 30 seconds itself).
    • Language of the names: of the features (set when a device is added) and of the texts the integration writes.
  3. Click Test the connection: it lists the servers Crafty gives.
  4. In Discovery, add the servers you want as devices.

The device of each server​

One device per server of Crafty, named like it, kept when it is renamed:

FeatureValue
Running1 while the server runs in Crafty, 0 when it is stopped
Players onlineplayers connected (0 when the server is stopped)
Player slotsmaximum number of players, once the server has given it
Playerswho is playing, e.g. Alice, Bob; "Nobody"; "Server stopped"
CPUCPU use of the server process, in %
Memorymemory used by the server process, in MB
Versione.g. Paper 1.21.4, once the server has given it

The players features only exist for the servers whose players Crafty counts (Minecraft Java and Bedrock). Minecraft gives 12 names at most: beyond, the text adds "and N more".

Dashboard​

The Crafty servers widget shows a tile per server (players online / slots, or its state: stopped, crashed, starting), a list with the state, the version and who is playing, and buttons, each one confirmed first:

  • Start for a stopped server;
  • Restart and Stop, only if allowed in the configuration;
  • Backup when the widget shows one server;
  • Refresh.

Every server by default (three at most), or the one chosen in the widget settings: one server also shows its CPU and memory.

Scenes​

Triggers​

  • A player joined the Minecraft server — with the name when Minecraft gives every name. Filters: server, player name.
  • A player left the Minecraft server — with the minutes played. Not fired when the server stops.
  • The Minecraft server is empty — the last player left, the server still running.
  • The Minecraft server is full — every slot is taken.
  • A server stopped unexpectedly — a stop asked neither from Gladys nor from Crafty: no clean shutdown in the log of the server (the key needs the Logs right), or Crafty's crash detection.
  • A server restarted — running again after a restart (from Gladys or Crafty) or after an unexpected stop (variable "After an unexpected stop").

A stop or a start seen in Crafty is also the Running feature of the device: a scene can use it directly ("Running" becomes 0).

Actions​

  • Start a Minecraft server — nothing is sent when it already runs.
  • Stop a Minecraft server and Restart a Minecraft server — only when allowed in the configuration, else the scene stops with an error.
  • Back up a Minecraft server — runs the default backup of the server in Crafty, with its settings (one set to stop the server stops it).
  • Read a Minecraft server — reads it now; its state (running, players, CPU, memory, version) goes to the next steps: a message, or "Continue only if" on running.

The four commands give "Command sent" (false when nothing had to be done).

Scene ideas​

  • At 23:00 on school days, if the kids' server is still running: send a message, then Stop a Minecraft server.
  • The Minecraft server is empty → Back up a Minecraft server.
  • A server stopped unexpectedly → a notification, then Start a Minecraft server.
  • A player joined the Minecraft server (player "Alice") → "Alice is on {{server}}".

Troubleshooting​

  • "Crafty unreachable": check the address and the port (8443 by default), and that Gladys reaches the machine of Crafty.
  • "Certificate refused": tick "Accept self-signed certificates".
  • "This address is not the Crafty API": usually http:// on the HTTPS port: use https://.
  • "API token refused by Crafty": the key was deleted, or the token copied partly: create a new token with Get A Token.
  • "Permission missing for this token in Crafty": give the key (or its user) the right on the server: Commands for the actions.
  • "Crafty answers, but this token sees no server": the user of the key has no server, or the key has no right on them.
  • No crash detected: without the Logs right, the integration cannot tell a crash from a clean stop; turn on crash detection in Crafty, or give the key the Logs right.
  • Logs of the integration with more details: LOG_LEVEL=debug.

Limits​

  • Tested against a real Crafty Controller 4.11, not yet inside a real Gladys.
  • Crafty measures its servers every 30 seconds: a change shows within 30 to 60 seconds, a player who stays less can be missed.
  • Minecraft gives 12 player names at most: beyond, the join and leave events have no name.
  • A restart faster than two readings is only seen through its new start time.
  • Other servers of Crafty (Steam, Hytale) get the running state, CPU, memory and the commands, without players.
  • One Crafty per integration, at its own address: a Crafty behind a reverse proxy under a sub-path (/crafty) is not supported.

Configuration settings​

These are the settings Crafty Controller asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Your Crafty ControllersectionNoIn Crafty, open Panel Config, Users, edit your user, API Keys: create a key with Full Access, then Get A Token. Paste it below with the address of Crafty and click Test the connection.
Crafty addressstringNoThe address you open Crafty with. A bare IP address gets https:// and port 8443.
API tokensecretNoOf an API key of Crafty. It acts with the rights of its user and of the key.
Accept self-signed certificatesbooleanNoCrafty serves HTTPS with its own certificate by default: leave it ticked unless yours is a trusted one.
CommandssectionNoStart and backup are always allowed. Stop and restart throw the players out: they stay off until you allow them.
Allow stop and restartbooleanNoFrom the scenes and the widget (always with a confirmation in the widget).
OptionssectionNo
Refresh intervalselectNoHow often Crafty is read. Crafty itself measures its servers every 30 seconds.
Language of the namesselectNoOf the device features (set when a device is added) and of the texts the integration writes.

How to install Crafty Controller in Gladys​

  1. In Gladys, open Integrations: Crafty Controller appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-crafty:1.0.0), 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/guim31/gladys-crafty.

Crafty Controller 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​

Crafty Controller 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 guim31, 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