IoTuring 2024.6.1

Simple and powerful cross-platform script to control your pc and share statistics using communication protocols like MQTT and home control hubs like HomeAssistant.

IoTuring

If you really like this project and you would like to support it:

The project

Simple and powerful cross-platform script to control your pc and share statistics using communication protocols like MQTT and home control hubs like HomeAssistant.

Like his predecessor - PyMonitorMQTT - IoTuring allows you to choose which data are sent and which command are expected to be given.

Why should you use this ? You don't have to write your configurations manually, entities are updated asynchronously and multiple warehouses can be used with one single run (and this is not deprecated obviously!).

But the most important thing: works on all OSs and all architectures ! Windows, Linux, macOS, openBSD; x86, amd64, ARM and so on...

CHANGELOG: available in Releases page

HomeAssistant preview

When the HomeAssistant warehouse is active, your computer will automatically show up in HomeAssistant as a single device, so all your entities will be grouped together. The device will also have some properties like connectivity and battery status.

All sensors and switches will be ready to be added to your dashboard in your favourite cards !

For detailed instructions about how to add your computer to HomeAssistant, look at the HomeAssistant setup section below.

Install

With pipx (recommended)

1. Install pipx, follow documentation according to your OS
2. Install IoTuring with pipx:

pipx install IoTuring

3. Done! You can configure IoTuring now.

Detailed instructions

Debian/Ubuntu with pipx

sudo apt update
sudo apt install pipx
pipx ensurepath
pipx install IoTuring

ArchLinux with pipx

pacman -Syu python-pipx
pipx ensurepath
pipx install IoTuring

Windows with pipx

1. Download latest python https://www.python.org/downloads/
2. Install with default options
3. In a CommandPrompt or in Powershell window:

py -m pip install --user pipx
py -m pipx ensurepath
py -m pipx install IoTuring

4. Close and reopen the window, and you can run IoTuring without any prefixes.

Manual install from git to a virtual environment

Requirements:

• Python 3.8+
• Pip
• Git

git clone https://github.com/richibrics/IoTuring
cd IoTuring
mkdir .venv
python -m venv .venv
. ./.venv/bin/activate
pip install --upgrade pip
pip install .

With system pip (not recommended)

Requirements:

• Python 3.8+
• Pip

pip install IoTuring

Configure

The first time you run IoTuring you need to specify which entities and warehouses you want to enable. To run in configuration mode, you only need to specify the -c argument along the script execution command:

IoTuring -c

A simple menu will show and you will be able to configure your entities and warehouses ! Once you have selected your preferred settings, you're ready to run IoTuring.

You will be able to enter the configuration menu whenever you want (with the same command as above) to edit your choises.

Run

You can simply run IoTuring using this command:

IoTuring

Other arguments

To see all command options run IoTuring --help:

> IoTuring --help
usage: IoTuring [-h] [-v] [-c] [-o]

Simple and powerful cross-platform script to control your pc and share statistics using communication protocols like MQTT and home control hubs like HomeAssistant.

options:
  -h, --help          show this help message and exit
  -v, --version       show program's version number and exit
  -c, --configurator  enter configuration mode
  -o, --open-config   open config file

Start without argument for normal use

Docker

Run the configurator:

docker run -it -v ./.config/IoTuring/:/config richibrics/ioturing:latest IoTuring -c

Enable the Console Warehouse to see logs!

Run detached after configuration:

docker run -d -v ./.config/IoTuring/:/config richibrics/ioturing:latest

For a docker compose example see docker-compose.yaml. Create configuration manually or with the command above!

HomeAssistant setup

Steps to connect IoTuring to your HomeAssistant install:

1. Install an MQTT broker. You can find the full list of brokers here: https://mqtt.org/software/
   • If you have a HAOS or supervised installation you can use the Mosquitto broker addon
   • For Docker users the official eclipse-mosquitto container is recommended
2. Enable the MQTT integration in HA, and connect to your broker
3. Install and configure IoTuring, in the configurator menu add the HomeAssistant Warehouse, connect to the same broker
4. When you start IoTuring, your computer will show up as a new MQTT device in HA automagically

Features

Available entities

Name	Description	Supported platforms
ActiveWindow	shares the name of the window you're working on
AppInfo	shares app informations like the running version
Battery	shares the battery level and charging status
BootTime	shares the machine boot time
Cpu	shares useful information about cpu usage (times, frequencies, percentages)
DesktopEnvironment	shares the running desktop environment (useful only for Linux)
Disk	shares disk usage data
DisplayMode	command for changing multimonitor display mode
Fanspeed	shares maximum fanspeed of each controller
Hostname	shares the machine hostname
Lock	command for locking the machine
Monitor	command for switching monitors on/off
Notify	displays a notification
OperatingSystem	shares the operating system of your machine
Power*	commands for poweroff, reboot and sleep
Ram	shares useful information about ram usage
Temperature	shares temperature sensor data
Terminal	runs custom commands in the shell
Time	shares the machine local time
Uptime	shares the time since the machine is on
Username	shares the name of the user who is working on the machine
Volume	control audio volume

* To use the features from Power entity on macOS and on some Linux distros you need to give permissions to your user to shutdown and reboot without sudo password. You can easily do that by using the following terminal command:

sudo sh -c "echo '$USER ALL=(ALL) NOPASSWD: /sbin/poweroff, /sbin/reboot, /sbin/shutdown' >> /etc/sudoers"

Available warehouses

• HomeAssistant: shares sensors and switches to HomeAssistant. The machine is shown as a Device and all the entites are grouped together. recommended
• MQTT: sends data to MQTT broker and subscribes to commands topics.
• Console: prints data to the console

Environment variables

• IOTURING_CONFIG_DIR: Change the path to the directory of the config file
• IOTURING_LOG_LEVEL: Set the log level

To run IoTuring with debug log on Linux or on Mac run:

env IOTURING_LOG_LEVEL=LOG_DEBUG IoTuring

On Windows:

set "IOTURING_LOG_LEVEL=LOG_DEBUG" && IoTuring

Development

See DEVELOPMENT.md

Contributors

• @richibrics: Riccardo Briccola - Author
• @infeeeee - Main contributor
• @tsunglung

Acknowledgement

Icons in this readme are from Material Design Icons, License: Pictogrammers Free License

Notification icon is from Home Assistant: License: CC BY-SA 4.0