Introduction

This guide will go through installing berconpy and using it to connect to a server, send commands, and receive messages.

Requirements

The minimum Python version required is 3.10. No other external dependencies are required.

Installation

This library can be installed from PyPI using one of the following commands:

# Linux/macOS
python3 -m pip install berconpy

# Windows
py -m pip install berconpy

To install the development version of the library, you can download it from GitHub directly:

# Windows
py -m pip install git+https://github.com/thegamecracks/berconpy

Note

The above command requires Git to be installed.

Basic Usage

The primary class berconpy offers is the RCONClient, which provides an interface over the underlying protocol and allows you to register event listeners and send commands to the BattlEye RCON server.

Sending commands

Let’s start with an example of how to send a command:

import asyncio
import berconpy as rcon

IP_ADDR = "XXX.XXX.XXX.XXX"
PORT = 9999
PASSWORD = "ASCII_PASSWORD"

client = rcon.RCONClient()

async def main():
    async with client.connect(IP_ADDR, PORT, PASSWORD):
        response = await client.send_command("players")
        print(response)

asyncio.run(main())

Note

The RCON IP address, port, and password can be found in your server’s BEServer.cfg / BEServer_x64.cfg.

  1. client = rcon.RCONClient() creates the client instance. No arguments are necessary, but you can set up event listeners on the client before beginning any connection which will be demonstrated afterwards.

  2. async with client.connect(IP_ADDR, PORT, PASSWORD) attempts to connect and log into the RCON server. The context manager also keeps the connection alive until you exit it, or an error occurs.

  3. response = await client.send_command("players") requests the players currently connected to the server and returns a string.

send_command() provides a simple method for sending commands and awaiting their responses. Commands can be found in the BattlEye documentation under the “Server-side BE commands” section.

Event listeners

There are four basic events you can listen to handle messages sent by the server in real-time:

import asyncio
import berconpy as rcon

IP_ADDR = "XXX.XXX.XXX.XXX"
PORT = 9999
PASSWORD = "ASCII_PASSWORD"

client = rcon.RCONClient()

@client.dispatch.on_raw_event
async def on_raw_event(packet: rcon.protocol.ServerPacket):
    print(f"Raw event: {packet}")

@client.dispatch.on_login
async def on_login():
    print("We have logged in!")

@client.dispatch.on_command
async def on_command(response: str):
    print(f"Received command response: {response}")

@client.dispatch.on_message
async def on_message(message: str):
    print(f"Received message: {message}")

async def main():
    async with client.connect(IP_ADDR, PORT, PASSWORD):
        # Keep client alive indefinitely:
        await asyncio.get_running_loop().create_future()

asyncio.run(main())

Each decorator adds their function as a listener for that specific event when it is received from the server. The on_* methods are provided by the EventDispatcher class, which has function signatures that allow your type checker to ensure that your listener is correctly typed.

Usage with Arma 3 and DayZ

For Arma 3 and DayZ specifically, there is also an ArmaClient class which has its own message parser and ArmaDispatcher class, allowing it to dispatch more granular events like on_player_connect() and on_player_message(). It also manages a cache of Player and Ban objects, providing helper methods like Player.ban_guid() and Player.send() which calls send_command() with the appropriate arguments.

Due to the parser relying on a specific message format followed by these two games, it is strongly advised not to use ArmaClient with any other game like Arma Reforger, and instead use the generic RCONClient class.

Configuring Logging

berconpy allows logging information about the protocol and the client during runtime with the built-in logging module. By default, no logging configuration is used. You can set up logging either by calling logging.basicConfig() (which configures the root logger) or by adding your own handlers to the berconpy logger.

The following table describes what messages are shown in each level of logging:

Level

Messages

CRITICAL

Unused

ERROR

Potentially fatal connection errors (e.g. incorrect password)

WARNING

Unexpected messages and incomplete cache (see ArmaClient)

INFO

Connection and disconnect events

DEBUG

Events and packets transmitted/received

Example configurations

Log all messages to stderr:

import logging

logging.basicConfig(level=logging.DEBUG)

Log berconpy warnings to berconpy.log:

import logging

log = logging.getLogger("berconpy")
log.setLevel(logging.WARNING)
handler = logging.FileHandler("berconpy.log", "w")
handler.setFormatter(logging.Formatter("%(asctime)s:%(levelname)s:%(name)s: %(message)s"))
log.addHandler(handler)

Next Steps

This has covered the fundamentals of using berconpy. You can learn more about the available methods by checking the RCON Client API Reference, or if you’re interested in the technical details you can check the source code.