This project allows you to integrate your Counter-Strike 2 game with Home Assistant by exposing it as an MQTT device. Its purpose is to enable you to automate your smart home based on in-game events and information, enhancing your overall gaming experience.
cs2mqtt is cross-platform and can run locally on your gaming machine, or any server device. All communication happens entirely within your local network, no data is sent to the cloud.
If the MQTT integration is installed, cs2mqtt will automatically create MQTT devices using the MQTT Discovery protocol, with all values configured as sensors.
cs2mqtt is designed to run as a container. You can use any OCI-compliant runtime to host the application.
If you're using Home Assistant Operating System, you can simply install the application as an add-on, as described below.
Add this repository as an add-on using the button above, or manually:
go to the Add-on store → top-right hamburger menu → Repositories → Add
https://github.com/lupusbytes/cs2mqtt.
Configure the add-on and Counter-Strike by following the readme on the info page inside the add-on.
In this example, it is expected that an MQTT broker, such as Mosquitto, is already set up and configured with the MQTT integration in Home Assistant.
services:
cs2mqtt:
image: ghcr.io/lupusbytes/cs2mqtt:latest
container_name: cs2mqtt
ports:
- "5000:8080"
environment:
MQTT__Host: 127.0.0.1 # MQTT broker address
MQTT__Port: 1883 # MQTT broker port
MQTT__UseTLS: false # Set to true if your broker uses TLS (optional, default: false)
MQTT__Username: c2m # MQTT client username (optional)
MQTT__Password: password # MQTT client password (optional)
MQTT__ClientId: cs2mqtt # MQTT client ID (optional)
MQTT__ProtocolVersion: 5.0.0 # Allowed values are 3.1.0, 3.1.1, or 5.0.0 (optional, default: 5.0.0)
restart: unless-stopped
⚠️ Make sure you replace the host, username, and password with values matching your setup. If the broker is configured to allow anonymous access, the username and password can be omitted.
To make Counter-Strike 2 send game state data to cs2mqtt, you need to create a config file within the game's directory.
If Steam and Counter-Strike 2 are installed with default options, the path where you need to create your config is:
C:\Program Files (x86)\Steam\steamapps\common\Counter-Strike Global Offensive\game\csgo\cfg
Once you have located the correct path, create a new file there called gamestate_integration_cs2mqtt.cfg with the following content:
"cs2mqtt"
{
"uri" "http://<YOUR-CS2MQTT-SERVER-IP>:5000"
"timeout" "5.0"
"buffer" "0.1"
"throttle" "0.1"
"heartbeat" "5.0"
"data"
{
"provider" "1"
"map" "1"
"round" "1"
"player_id" "1"
"player_state" "1"
}
}
💡 Tip
In Windows File Explorer, it can be tricky to create a new file with a specific file extension (like
.cfg).
A simple workaround is to copy one of the many pre-existing.cfgfiles in the folder, rename it, and then replace its contents using Notepad.
⚠️ Make sure you replace theuriwith the IP address or hostname of the host that is running cs2mqtt.
The next time you launch Counter-Strike 2, cs2mqtt will use the MQTT discovery protocol to make Home Assistant create an MQTT device named CS2 STEAM_{X}:{Y}:{Z}, matching your SteamID. On the very first game launch, the device will not have many sensors, but after joining or creating a game server, all sensors will automatically be discovered.
cs2mqtt receives its data from the built-in Counter-Strike Game State Integration engine. This integration is created by Valve and is safe to use and will not be flagged by anti-cheat systems such as VAC or FACEIT.
flowchart LR;
CS2(Counter-Strike 2
game instance)
C2M(((**cs2mqtt**)))
HA(Home Assistant
MQTT integration)
CS2 -- Game state data in JSON format over HTTP(s) --> C2M
C2M -- MQTT messages --> MQTT(MQTT broker)
MQTT --> HA
Internally, cs2mqtt keeps track of the current state of every connected Counter-Strike game instance. Inside the Counter-Strike game, every game state change will trigger the game to send a full payload containing both the changed and unchanged state data. cs2mqtt compares the received data to its in-memory cache, updates the cache accordingly, and asynchronously submits the changed data as MQTT messages to the MQTT broker.
flowchart LR;
Endpoint(((**cs2mqtt**
HTTP
ingestion endpoint)))
Endpoint -- Game state data --> GameStateService
GameStateService -- Push new data to observer --> AvailabilityMqttPublisher
GameStateService -- Push new data to observer --> GameStateMqttPublisher
GameStateService -- Push new data to observer --> HomeAssistantDevicePublisher
AvailabilityMqttPublisher -- Maintain availability (online/offline) for every sensor ---> MqttClient
GameStateMqttPublisher -- Send game state data on distinct sensor topics ---> MqttClient
HomeAssistantDevicePublisher -- Use Home Assistant MQTT device discovery protocol to automatically create Home Assistant devices and sensors for each data provider. ---> MqttClient
On startup, when cs2mqtt connects to the MQTT broker, it publishes an online message to cs2mqtt/status.
It also sets a Last Will and Testament (LWT) for the MQTT broker to publish an offline message to this topic if it loses connection or terminates unexpectedly.
On graceful shutdown, cs2mqtt will publish an offline message to this topic before disconnecting.
When a Counter-Strike 2 game instance submits data for the first time, cs2mqtt will automatically create an MQTT device for it, as described above, and publish online messages to cs2mqtt/{steamId64}/+/status topics.
If a player disconnects from a game server, the topics related to player_state, map, and round will immediately be set to offline.
When a player closes their Counter-Strike 2 game, there is no data transmitted, and there's nothing to indicate they've quit. As a result, cs2mqtt listens for heartbeats and eventually sets the entire device to an offline availability state once the timeout is reached.
It is possible to require authentication between Counter-Strike 2 and cs2mqtt.
To do this, pick a password and add it as an environment variable in the cs2mqtt docker-compose.yml like:
GameState__Token: passwordThen also add the same password to gamestate_integration_cs2mqtt.cfg in the root object:
"auth"
{
"token" "password"
}
It is possible to remove any of the following entries from the data object in gamestate_integration_cs2mqtt.cfg:
maproundplayer_idplayer_state
This will stop Counter-Strike 2 from sending data about the removed topics.
Since version 1.9.0, cs2mqtt ignores data from spectated players by default.
This behaviour can be changed by setting the environment variables
GameState__IgnoreSpectatedPlayers: falseAs mentioned in Device Availability, CS2 can and will not notify cs2mqtt when the game is closed. To work around this limitation, cs2mqtt listens for heartsbeats and sets the device as offline if no data has been received within the expected interval. The timeout and cleanup interval can be defined by following environment variables:
GameState__TimeoutInSeconds: 10.5
GameState__TimeoutCleanupIntervalInSeconds: 5The TimeoutInSeconds should be a little longer than the heartbeat defined in the gamestate_integration_cs2mqtt.cfg, to get the best results.
The TimeoutCleanupIntervalInSeconds defines how often the background job that checks for timed out devices is executed.